electronics-inventory/ui-structure.md

# 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.