Add ui-structure.md — full UI inventory and widget taxonomy

Covers all 7 nav sections with layout descriptions, all 11 dialog types, recurring widget patterns (split pane, tabbed view, table, gallery, card, field editor, modal dialog, non-modal overlay, full-page sub-view, canvas, lightbox) with every instance listed, complete template inventory (41 entries), and a primitive taxonomy for a future higher-level UI representation. Linked from CLAUDE.md. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-03 14:18:09 +00:00
parent 5fe7273e35
commit 270806539c
2 changed files with 370 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -378,6 +378,14 @@ git config user.email 'mikaels.claude.agent@efforting.tech'

 ---

+## UI structure
+
+See [`ui-structure.md`](ui-structure.md) for the full inventory of sections,
+widget patterns, dialogs, templates, and a taxonomy of primitives relevant to
+designing a higher-level UI representation.
+
+---
+
 ## Known limitations / planned rewrite notes

 See [`future-plans.md`](future-plans.md) for full detail. Key points relevant
--- a/ui-structure.md
+++ b/ui-structure.md
@@ -0,0 +1,362 @@
+# UI Structure
+
+Current UI inventory — sections, widgets, templates, and recurring patterns.
+Intended as a reference for the rewrite and for defining a higher-level UI
+representation.
+
+---
+
+## Navigation
+
+Top bar with 7 section buttons + a maintenance dropdown (⚙):
+
+| Button | Section | Default? |
+|--------|---------|----------|
+| Components | Split-pane list/detail | ✓ |
+| Inventory | Table |  |
+| Fields | Table |  |
+| Grids | Tabbed (Grids / Source images) + sub-views |  |
+| Templates | Card list |  |
+| Bins | Tabbed (Bins / Source images / Types) |  |
+| Images | Admin list |  |
+
+Maintenance dropdown (not a section):
+- Generate missing PDF thumbnails
+- Remove orphaned source image entries
+
+---
+
+## Sections
+
+### Components
+**Layout:** Resizable split-pane (width persisted in localStorage)
+
+**Left — master list:**
+- Search input (filters by name + field values)
+- Quick-add input (creates component inline)
+- List of `t-component-row` items (name + colored field-value badge tags)
+
+**Right — detail panel:**
+- Placeholder when nothing selected
+- When selected: name, description, Edit / Duplicate / Delete actions
+  - Fields block — name/value rows
+  - Images block — thumbnail gallery + upload button
+  - Files block — linked PDFs + file picker button
+  - Inventory block — location entries (each with edit/delete) + add button
+
+**Dialogs opened from here:** component edit, field create, inventory entry, file
+picker, confirm delete
+
+---
+
+### Inventory
+**Layout:** Toolbar + table
+
+- Filter: text search + location-type dropdown (All / Physical / BOM / Digital / Grid)
+- Table columns: Component | Type | Location/Ref | Qty | Notes | Actions (edit, delete)
+- Component name cells are links → `/components/:id`
+- Grid location cells link to the grid viewer at that cell
+- "+ Add entry" button in toolbar
+
+**Dialogs opened from here:** inventory entry edit/create, confirm delete
+
+---
+
+### Fields
+**Layout:** Toolbar + table
+
+- Table columns: Name | Unit | Description | Actions (edit, delete)
+- "+ Add field" button in toolbar
+
+**Dialogs opened from here:** field edit/create, confirm delete
+
+---
+
+### Templates
+**Layout:** Toolbar + card list
+
+- Cards show: name, formatter JS code (read-only `<pre>`), edit/delete actions
+- "+ Add template" button
+- Live preview panel in the edit dialog
+
+**Dialogs opened from here:** template edit/create, confirm delete
+
+---
+
+### Grids
+**Layout:** Tabbed, plus three full-page sub-views (not dialogs)
+
+**Tab: Grids**
+- Grid cards (image grid preview, name, delete)
+- Draft cards (unprocessed setups, badge "Draft")
+- "+ New grid" button → wizard dialog
+
+**Tab: Source images**
+- Source image gallery (`t-source-card`)
+- "+ Upload" button
+
+**Sub-view: Panel manager** (replaces main content)
+- Editable grid of panel slots — each slot is a photo region
+- Header with grid name, Cancel / Process buttons
+
+**Sub-view: Grid setup** (replaces main content)
+- Canvas corner editor (`Grid_Setup` class) with pan/zoom
+- Right panel: cell size info, action buttons, progress
+
+**Sub-view: Grid viewer** (replaces main content)
+- Full grid of cell thumbnails
+- Click cell → cell inventory overlay (non-modal panel)
+- Header with Edit panels / Delete actions
+
+**Dialogs opened from here:** new grid wizard, source picker, confirm delete
+
+---
+
+### Bins
+**Layout:** Tabbed
+
+**Tab: Bins**
+- Gallery of `t-bin-card` items (processed image or "Not processed" indicator)
+- Click Edit (✎) → bin editor dialog
+
+**Tab: Source images**
+- Filtered source gallery (uses includes 'bin')
+- Each card has a "+ Bin" button to create a bin from that source
+
+**Tab: Types**
+- List of `t-bin-type-row` items (name, dimensions, description)
+- Edit / delete per row
+- "+ Add type" button
+
+**Dialogs opened from here:** bin editor, bin type edit/create, bin content
+add/edit, field create, confirm delete
+
+---
+
+### Images
+**Layout:** Admin list
+
+- One row per source image: thumbnail, filename, dimensions, uses checkboxes
+  (grid / bin, toggleable), delete button
+- Purpose: correct mislabeled source images
+
+---
+
+## Widget Patterns
+
+These are the recurring structural widgets across the app. Listing all instances
+makes the taxonomy visible and suggests what a higher-level UI DSL would need to
+express.
+
+---
+
+### Split pane (master/detail)
+A resizable two-column layout. Left = filterable list. Right = detail view of
+selected item, or a placeholder.
+
+| Instance | Left | Right |
+|----------|------|-------|
+| Components | Component list + search | Detail panel (fields, images, files, inventory) |
+
+Currently only one instance. The pattern is general enough to reuse for grids,
+bins, etc.
+
+---
+
+### Tabbed section
+A tab bar that switches between content panels within the same section. Tab state
+can be reflected in the URL (`/bins/sources`, `/grids/sources`).
+
+| Instance | Tabs |
+|----------|------|
+| Grids section | Grids \| Source images |
+| Bins section | Bins \| Source images \| Types |
+| Bin editor dialog | Fields \| Contents |
+
+---
+
+### Table view
+Toolbar (search/filter + action button) + `<table>` with rows and per-row
+edit/delete icon buttons.
+
+| Instance | Row content |
+|----------|-------------|
+| Inventory | Component, type badge, location ref, qty, notes |
+| Fields | Name, unit, description |
+
+---
+
+### Card gallery
+A wrapping grid of cards. Each card has a visual element (image or preview),
+a title, and action buttons.
+
+| Instance | Card type | Visual |
+|----------|-----------|--------|
+| Grid list | `t-grid-card` | Multi-thumbnail preview |
+| Bin gallery | `t-bin-card` | Processed image or placeholder |
+| Source image gallery | `t-source-card` | Photo thumbnail |
+| Template list | `t-template-card` | Formatter code `<pre>` |
+
+---
+
+### List row with actions
+A horizontal row with info spans on the left and icon buttons on the right. Used
+in data-table rows and standalone list elements.
+
+| Instance | Info shown |
+|----------|------------|
+| Inventory table rows | Component, type, location, qty, notes |
+| Field table rows | Name, unit, description |
+| Bin type rows | Name, dimensions, description |
+| Bin content rows | Name/component, qty, notes |
+| Image admin rows | Thumbnail, filename, dimensions, uses checkboxes |
+
+---
+
+### Field editor (dynamic rows)
+A list of label + text input + remove button rows, plus an "add field" dropdown
+and "New…" button. Shared across component edit, bin edit, and bin type edit via
+`build_field_editor()`.
+
+| Instance | Host |
+|----------|------|
+| Component edit dialog | `#c-field-rows` |
+| Bin editor — Fields tab | `#bin-field-rows` |
+| Bin type dialog | `#bt-field-rows` |
+
+---
+
+### Modal dialog
+`<dialog>` element shown with `.showModal()`. All injected at init from
+`<template>` elements. Closed via Cancel button, form submit, or backdrop click.
+Save callback stored as a module-level variable, called by the registered submit
+handler.
+
+| Dialog | Purpose | Key inputs |
+|--------|---------|------------|
+| `dialog-component` | Create/edit component | Name, description, field editor |
+| `dialog-inventory` | Create/edit inventory entry | Component, type, location, qty, notes, grid picker |
+| `dialog-field` | Create/edit field definition | Name, unit, description |
+| `dialog-template` | Create/edit name formatter | Name, JS code, test data, live preview |
+| `dialog-new-grid` | Grid creation wizard | Name, rows, cols, photo coverage |
+| `dialog-source-picker` | Pick a source image | Upload or select from gallery |
+| `dialog-confirm` | Generic confirm/delete | Dynamic message text |
+| `dialog-file-picker` | Link a PDF to a component | PDF list, upload section |
+| `dialog-bin-editor` | Edit bin (image, corners, fields, contents) | Name, type, image/canvas, tabs |
+| `dialog-bin-type` | Create/edit bin type | Name, dimensions, description, field editor |
+| `dialog-bin-content` | Add/edit bin content item | Type (component/free text), qty, notes |
+
+---
+
+### Non-modal overlay / panel
+Injected into the DOM and shown/hidden with `hidden`. Not a `<dialog>` — does not
+block the rest of the UI.
+
+| Instance | Trigger | Content |
+|----------|---------|---------|
+| Cell inventory overlay | Click grid cell in viewer | Inventory entries for that cell, + add button |
+
+---
+
+### Full-page sub-view (section replacement)
+Replaces the entire `<main>` content. Not a dialog or overlay — the user is
+"inside" a different mode of the same section. Back navigation returns to the
+section list view.
+
+| Instance | Entered from | Content |
+|----------|-------------|---------|
+| Grid setup | New grid wizard → source picker | Canvas corner editor + controls |
+| Panel manager | Grid card or setup → next | Editable panel slot grid |
+| Grid viewer | Grid card click | Cell thumbnail grid, cell inventory overlay |
+
+---
+
+### Canvas editor
+`Grid_Setup` class renders into a `<canvas>`. Handles pan (middle mouse), zoom
+(wheel), and corner/edge handle dragging for perspective correction. Used in two
+places with identical behaviour.
+
+| Instance | Embedded in |
+|----------|-------------|
+| Grid setup sub-view | `t-grid-setup` canvas |
+| Bin corner editor | `dialog-bin-editor` (revealed on "Adjust corners") |
+
+---
+
+### Image lightbox
+Full-screen image overlay triggered by clicking thumbnails. Single global
+instance, not per-section. Clicking anywhere closes it.
+
+---
+
+## Complete Template Inventory
+
+| Template ID | Type | Renders |
+|-------------|------|---------|
+| `t-section-components` | Section | Split-pane container |
+| `t-section-inventory` | Section | Table container |
+| `t-section-fields` | Section | Table container |
+| `t-section-templates` | Section | Card list container |
+| `t-section-grids` | Section | Tabbed container |
+| `t-section-bins` | Section | Tabbed container |
+| `t-section-images` | Section | Admin list container |
+| `t-component-row` | List item | Name + field-value badge tags |
+| `t-field-tag` | Badge | Single field name + value |
+| `t-detail-placeholder` | Placeholder | "Select a component" message |
+| `t-detail-content` | Detail panel | Full component detail |
+| `t-detail-field-row` | Row | Field name + rendered value |
+| `t-detail-inv-entry` | Row | Inventory entry with images sub-gallery |
+| `t-image-thumb` | Thumbnail | Image link + delete button |
+| `t-inventory-row` | Table row | Inventory entry (all columns) |
+| `t-field-row` | Table row | Field definition (all columns) |
+| `t-empty-row` | Table empty | colspan message cell |
+| `t-empty-block` | Block empty | Div with message |
+| `t-template-card` | Card | Template name + code + actions |
+| `t-source-card` | Card | Source image + meta + uses badges |
+| `t-draft-card` | Card | Draft grid + badge + actions |
+| `t-grid-card` | Card | Grid preview thumbs + meta + actions |
+| `t-panel-manager` | Sub-view | Panel slot editor grid |
+| `t-panel-slot` | Grid cell | Slot thumbnail + label |
+| `t-grid-setup` | Sub-view | Canvas + controls |
+| `t-grid-viewer` | Sub-view | Cell thumbnail grid |
+| `t-grid-cell` | Grid cell | Cell image + location label |
+| `t-bin-card` | Card | Bin image or placeholder + actions |
+| `t-bin-type-row` | Row | Bin type info + actions |
+| `t-bin-content-row` | Row | Content item info + actions |
+| `t-img-admin-row` | Row | Source image admin row |
+| `t-dialog-component` | Dialog | Component create/edit |
+| `t-dialog-inventory` | Dialog | Inventory entry create/edit |
+| `t-dialog-field` | Dialog | Field definition create/edit |
+| `t-dialog-template` | Dialog | Template create/edit + preview |
+| `t-dialog-new-grid` | Dialog | Grid creation wizard |
+| `t-dialog-source-picker` | Dialog | Source image selector |
+| `t-dialog-confirm` | Dialog | Generic confirm |
+| `t-dialog-file-picker` | Dialog | PDF picker + upload |
+| `t-dialog-bin-editor` | Dialog | Bin edit (image, corners, fields, contents) |
+| `t-dialog-bin-type` | Dialog | Bin type create/edit |
+| `t-dialog-bin-content` | Dialog | Bin content item create/edit |
+| `t-cell-inventory` | Overlay | Grid cell inventory entries |
+
+---
+
+## Notes for a Higher-Level UI Representation
+
+The widgets above map fairly cleanly onto a small set of primitives that a UI DSL
+would need:
+
+- **Section** — a top-level navigable view, registered in the nav bar
+- **Tabs** — switch between named content panels, state optionally in URL
+- **SplitPane** — resizable master/detail, left = list, right = detail
+- **Table** — toolbar + rows, each row has a schema and action set
+- **Gallery** — wrapping grid of cards, each card has a schema
+- **Row** — horizontal item with info fields and icon actions
+- **FieldEditor** — dynamic key/value input list (add/remove/edit)
+- **Dialog** — modal form with a save callback, injected from a template
+- **Overlay** — non-modal panel, shown/hidden in place
+- **SubView** — full-page mode that replaces main content
+- **Canvas** — bespoke interactive widget (not expressible declaratively)
+- **Lightbox** — global full-screen image viewer
+
+Most sections are composed of 2–3 of these primitives. The Components section
+(SplitPane → Table + Gallery + FieldEditor) is the most complex. The canvas-based
+views are the only things that require imperative escape hatches.