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.