@ixfx/components 0.5.19 → 0.6.0

package/docs-user/colour-picker.md

@@ -188,11 +188,11 @@ Picker sizes (width × height):
 | `large`   | 200 × 180 px |
 | `huge`    | 290 × 240 px |
 
-### Getters
+### Getters/setters
 
-| Getter  | Returns  | Description |
-|---------|----------|-------------|
-| `value` | `string` | Committed colour as a CSS `oklch()` string |
+| Property | Type                    | Description |
+|----------|-------------------------|-------------|
+| `value`  | `string` (get) / `Colour.Colourish` (set) | Committed colour. Reading returns a CSS `oklch()` string; assigning accepts any ixfx-compatible colour format (equivalent to calling `setColour()`) — including via a Lit property binding, e.g. `.value=${someColour}`. |
 
 ### Methods
 
@@ -200,6 +200,10 @@ Picker sizes (width × height):
 
 Set the committed colour from any ixfx-compatible format. The swatch updates immediately. The inner picker reflects the new colour the next time the popover opens.
 
+### Limitations
+
+The popover is positioned relative to the swatch using CSS anchor positioning (`anchor-name`/`position-anchor`). Chrome does not resolve anchor positioning for elements inside an SVG `<foreignObject>` — if you embed this component there, the popover will render unanchored at the top-left of the viewport instead of next to the swatch. Workaround: keep the swatch as a plain SVG element and render this component (or just the picker) in a fixed-positioned HTML overlay positioned via `getBoundingClientRect()` on your own swatch element.
+
 ```js
 popup.setColour('#3498db');
 popup.setColour({ l: 0.5, c: 0.25, h: 30 });

package/docs-user/data-grid.md

@@ -0,0 +1,248 @@
+# `ixfx-data-grid`
+
+A virtualised data grid with sortable/resizable/reorderable columns, single/multi selection, grouping, and inline cell editing. Handles 200+ rows with windowed rendering and keyboard navigation.
+
+---
+
+## Quick start
+
+```html
+<ixfx-data-grid id="grid" style="height:400px"></ixfx-data-grid>
+
+<script type="module">
+  import '@ixfx/components/data-grid';
+
+  const grid = document.querySelector('#grid');
+  grid.columns = [
+    { key: 'name', label: 'Name', width: 160 },
+    { key: 'age', label: 'Age', width: 70, align: 'right' },
+    { key: 'score', label: 'Score', width: 90, align: 'right' },
+  ];
+  grid.rows = [
+    { key: 'r0', name: 'Ada', age: 30, score: 9.123 },
+    { key: 'r1', name: 'Bob', age: 25, score: 4 },
+  ];
+</script>
+```
+
+Import via bundle: `import '@ixfx/components';` or per-component `import '@ixfx/components/data-grid';`.
+
+---
+
+## Columns
+
+```ts
+type DataGridColumn = {
+  key: string;
+  label: string;
+  width?: number; minWidth?: number; maxWidth?: number;
+  visible?: boolean;
+  sortable?: boolean; sortFn?: (a,b)=>number;
+  resizable?: boolean; reorderable?: boolean;
+  align?: 'left'|'center'|'right'; // default left, applied as justify-content + tabular-nums for numbers
+  renderer?: (row, col, rowIndex) => unknown; // Lit template or string
+  selectable?: boolean;
+  groupable?: boolean;
+  editable?: boolean;
+  editor?: 'text'|'number'|'boolean'|'select' | DataGridEditorFactory;
+  editorOptions?: readonly (string|{value,label})[];
+  formatter?: (value, row, col) => unknown;
+};
+```
+
+* `width` defaults to `150`. Drag the handle between headers to resize; double-click handle to auto-size to content. Drag the `⠿` handle to reorder.
+* `align` controls cell content justification. Numeric columns should use `right` (or `center` for Age) – cells use `font-variant-numeric: tabular-nums` so decimal points align when paired with a fixed formatter.
+* `renderer` overrides default `String(value)` display. Use `html` from `lit`.
+
+---
+
+## Rows & keys
+
+```ts
+grid.rows = [{ key: 'r0', ... }, ...];
+grid.getRowKey = (row, i) => row.key ?? row.id ?? String(i);
+```
+
+Reassign `rows` to update. Sorting is derived from `sortState`.
+
+---
+
+## Selection & interaction
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `selectionMode` / `selection-mode` | `'none'|'single'|'multiple'` | `'single'` | How many rows can be selected |
+| `interactionMode` / `interaction-mode` | `'standard'|'implicit'|'checked'|'sticky'|'vscode'|'manual'` | `'standard'` | Gesture mapping (same as `ixfx-vertical-list`) |
+
+See `ixfx-vertical-list` README for mode table. Data-grid adds checkbox column in `checked` mode.
+
+Programmatic: selection is `Set<string>` of row keys (`_selectedKeys` private, read via events).
+
+---
+
+## Sorting
+
+Click header to cycle `asc → desc → none`. Or set:
+
+```ts
+grid.sortState = { key: 'age', direction: 'asc' };
+```
+
+Events: `datagrid-sort` `{ sort, previous }`. Custom `sortFn` per column.
+
+---
+
+## Grouping
+
+```ts
+grid.allowGrouping = true;
+grid.groupBy = 'department'; // or (row)=>String(row.dept)
+grid.groupLabel = (key, rows) => `${key} (${rows.length})`;
+grid.groupableColumns = ['department','age']; // optional allowlist
+```
+
+Collapsible group headers (no background, just divider). Header bar `ixfx-menu-trigger` (gear) shows `Columns` check-items and `Group by` radio group – uses CSS anchor positioning with `position-try-fallbacks` so it never goes off-screen (flips `block`/`inline`, max-height `min(60vh,400px)` scrolls).
+
+Cross-group selection:
+
+```html
+<ixfx-data-grid cross-group-selection></ixfx-data-grid>
+```
+
+* `cross-group-selection` (boolean, default `false` – matches `ixfx-grouped-item-lister`). When `false`, selecting in one group clears other groups; `Shift+click` range and `Ctrl+A` are clamped to the anchor's group. When `true`, selection spans groups. Logic lifted to `src/util/grouped-selection.ts`.
+
+Events: `datagrid-group-change` `{ groupBy }`.
+
+---
+
+## Editing
+
+### Editability modes
+
+| `editability` | Behaviour |
+|---|---|
+| `disabled` | No editing |
+| `manual` | Only via `startEdit` / `startRowEdit` |
+| `user` (default) | Slow double-click (two clicks 150–700ms apart on same cell) opens editor; `Enter` on a tickled row opens `lastClickedCell` if editable else first editable |
+| `immediate` | Editable cells render as editors by default |
+
+```html
+<ixfx-data-grid editability="user"></ixfx-data-grid>
+```
+
+```ts
+grid.editable = (row, col) => col.key==='name' || col.key==='department';
+// or per-column editable:true
+```
+
+### Editors
+
+* `editor:'text'` (default) → `<input type="text">`
+* `editor:'select'` + `editorOptions: ['A','B']` → `<select>`
+* `editor:'boolean'` → checkbox
+* `editor: (ctx)=>html`...` ` custom factory with `{ row, column, rowIndex, colIndex, value, commit, cancel }`
+
+Editors are seeded with the cell's current value (`curVal`). For `select`, the matching `editorOptions` entry is preselected.
+
+### Programmatic
+
+```ts
+grid.startEdit('r4','name'); // single cell
+grid.startRowEdit('r4'); // all editable cells in row
+grid.stopEdit();
+```
+
+### Keyboard while editing
+
+* `Tab` / `Shift+Tab` – commit and move to next/prev editable cell in same row, focus follows.
+* `Up` / `Down` – commit and move to same column in adjacent row if editable, also moves tickled cursor.
+* `Enter` – commit.
+* `Escape` – cancel (revert) when grid has focus.
+* Focus leaving the component reverts editors (unless `immediate`), committing only via explicit `Tab`/`Enter`/`Down`.
+
+Implementation: `updated` focuses the editor (`data-col` attribute), `_suppressBlurCommit` prevents double-commit on Tab navigation, `_onFocusOut` reverts.
+
+---
+
+## Formatting & alignment
+
+Global or per-column formatters transform display value (not stored value):
+
+```ts
+type GlobalFormatter = (value, columnName, row) => unknown;
+grid.globalFormatter = (v, col) => col==='score' ? Number(v).toFixed(2) : v;
+grid.setColumnFormatter('score', 'fixed', { digits: 3 }); // built-ins
+grid.setColumnFormatter('score', v => String(v)); // custom
+grid.setColumnFormatter('score', null); // clear
+```
+
+Built-ins:
+
+| Name | Options | Example |
+|---|---|---|
+| `fixed` | `{digits:2}` | `9.1 → 9.10` |
+| `percentage` | `{digits:0}` | `0.75 → 75%` |
+| `integer` | – | `9.6 → 10` |
+
+Column `formatter?: (value,row,col)=>unknown` also supported. Formatted value is shown when no `renderer`; if `renderer` exists it receives raw row.
+
+Demo: `Score` is random float `0–100` with 0–3 decimals, `align:'right'`, `font-variant-numeric: tabular-nums`, `fixed` 3 digits for decimal alignment. `Age` is `align:'center'` to demo middle alignment.
+
+---
+
+## Column visibility & menu
+
+Gear menu (`ixfx-menu-trigger` placement `bottom-end`, `inset-area: block-end span-inline-end`) lists `Columns` (check-items) and `Group by` (radio). Toggle visibility via `col.visible=false` or menu. Event: `datagrid-column-visibility` `{key, visible}`.
+
+Other events: `datagrid-column-reorder` `{from,to,columns}`, `datagrid-column-resize` `{key,width}`, `datagrid-cell-click` `{rowKey,colKey,rowIndex,colIndex}`, `datagrid-cell-edit` `{rowKey,colKey,oldValue,newValue}`.
+
+---
+
+## Keyboard navigation
+
+Grid is focusable (`tabindex=0`). When not editing:
+
+| Key | Action |
+|---|---|
+| `ArrowDown/Up` | Move tickled cursor, scroll into view; with `Shift` + `vscode`/`standard` extends range |
+| `Home/End` | First/last |
+| `Enter` | If `editability=user` and row has editable cell, open editor (prefers `lastClickedCell`); else select row |
+| `Space` | Toggle selection |
+| `Escape` | Clear selection (or cancel edit) |
+| `Ctrl/Cmd+A` | Select all (clamped to anchor group if `!crossGroupSelection`) |
+
+---
+
+## CSS variables & parts
+
+| Variable | Default | Description |
+|---|---|---|
+| `--data-grid-row-height` | `28px` | Row height |
+| `--data-grid-header-height` | `32px` | Header height |
+| `--data-grid-bg` | `var(--surface-3)` | Grid background |
+| `--data-grid-header-bg` | `var(--surface-2)` | Header background |
+| `--data-grid-border` | `var(--border)` | Outer/between border |
+| `--data-grid-header-text` | `var(--surface-3-text)` | Header text |
+
+Inherits global theme (`--surface-*`, `--accent`, `--item-*`, `--space-*`, `--radius-*`, `--shadow-m`). Cells use `font-variant-numeric: tabular-nums`. Group rows are transparent with divider.
+
+No `::part` exports yet (header/row/cell are shadow-internal).
+
+---
+
+## Methods
+
+| Method | Signature | Description |
+|---|---|---|
+| `setColumnFormatter` | `(key, preset\|fn\|null, opts?)` | Set built-in or custom formatter |
+| `startEdit` | `(rowKey, colKey)` | Open single-cell editor |
+| `startRowEdit` | `(rowKey)` | Open row editors |
+| `stopEdit` | `()` | Cancel editors |
+| `getVisibleRange` | `()=>{startRow,endRow,startCol,endCol}` | Virtual window |
+
+---
+
+## Demo
+
+`demo/data-grid.html` + `demo/data-grid.ts`: 200 rows, `Department` random, `Score` float, `Name`/`Department` editable (`user` mode, slow double-click; `Tab`/`Up`/`Down` navigation; `Enter` from tickled row). Controls: Selection/Interaction/Group by/Editability + `Edit first row` (manual).
+

package/docs-user/index.json

@@ -0,0 +1,217 @@
+{
+  "name": "@ixfx/components",
+  "version": "0.6.0",
+  "generated": "2026-08-29T11:13:25.291Z",
+  "components": [
+    {
+      "name": "ac-text",
+      "summary": "VS Code command-palette style autocomplete text input. Shows a popup with matching results as the user types.",
+      "path": "docs-user/ac-text.md"
+    },
+    {
+      "name": "ac-token",
+      "summary": "Token/tag input with per-token autocomplete. Looks like a text box — committed tokens appear as inline chips, and a suggestion popup follows the typing cursor. Typical use cases are email To: fields a",
+      "path": "docs-user/ac-token.md"
+    },
+    {
+      "name": "button",
+      "summary": "Three related button components:",
+      "path": "docs-user/button.md"
+    },
+    {
+      "name": "checkbox",
+      "summary": "A custom checkbox with a diagonal line indicator and indeterminate state support. Uses shadow DOM with CSS variables for full appearance customization.",
+      "path": "docs-user/checkbox.md"
+    },
+    {
+      "name": "colour-picker",
+      "summary": "Two components for picking OKLCH colours. Use `ixfx-colour-picker` when you need a full inline picker; use `ixfx-colour-picker-popup` when you need a compact swatch that opens a picker in a popover.",
+      "path": "docs-user/colour-picker.md"
+    },
+    {
+      "name": "crumbs",
+      "summary": "Breadcrumb navigation with lazy-loading child support. Uses the same `TreeNode` / `TreeItem` data model as `ixfx-tree-list`, allowing easy swapping between the two components.",
+      "path": "docs-user/crumbs.md"
+    },
+    {
+      "name": "data-display",
+      "summary": "A debug data display component that renders key-value pairs from a plain object. Supports 7 inline render modes (`led`, `plot`, `plot-xy`, `plot-heat`, `plot-histogram`, `time-elapsed`, `hide`) via `c",
+      "path": "docs-user/data-display.md"
+    },
+    {
+      "name": "data-grid",
+      "summary": "A virtualised data grid with sortable/resizable/reorderable columns, single/multi selection, grouping, and inline cell editing. Handles 200+ rows with windowed rendering and keyboard navigation.",
+      "path": "docs-user/data-grid.md"
+    },
+    {
+      "name": "editable-label",
+      "summary": "Inline editable text components. `ixfx-editable-number` extends `ixfx-editable-label` with drag-to-adjust and fill-bar visualization.",
+      "path": "docs-user/editable-label.md"
+    },
+    {
+      "name": "form",
+      "summary": "Primitives for typical form layout with responsive label positioning and data binding.",
+      "path": "docs-user/form.md"
+    },
+    {
+      "name": "grouped-item-lister",
+      "summary": "A meta-component that renders a typed item list using any sub-component you supply. Items can be displayed in a single sub-component (_ungrouped_ mode) or split into labelled groups, each with its own",
+      "path": "docs-user/grouped-item-lister.md"
+    },
+    {
+      "name": "icons",
+      "summary": "A centralized SVG icon system for `@ixfx/components`. Icons are stored by name, can be overridden globally, and all components that use a given icon re-render automatically when it changes.",
+      "path": "docs-user/icons.md"
+    },
+    {
+      "name": "incr-search",
+      "summary": "Utilities for incremental (type-ahead) search over data collections or DOM-backed lists.",
+      "path": "docs-user/incr-search.md"
+    },
+    {
+      "name": "labelled-radial-input",
+      "summary": "A composite radial input that pairs an editable label (`ixfx-editable-number`) with a rotary dial (`ixfx-radial-input`). The two controls are always in sync — turning the dial updates the number, and ",
+      "path": "docs-user/labelled-radial-input.md"
+    },
+    {
+      "name": "labelled-range-input",
+      "summary": "A composite range input that pairs an editable label (`ixfx-editable-number`) with a slider (`ixfx-range-input`). The two controls are always in sync — dragging the slider updates the number, and edit",
+      "path": "docs-user/labelled-range-input.md"
+    },
+    {
+      "name": "led",
+      "summary": "An LED indicator component with color mixing and optional blinking animation.",
+      "path": "docs-user/led.md"
+    },
+    {
+      "name": "menu",
+      "summary": "A custom menu system built on native HTML popovers with keyboard navigation, tickled focus management, and command routing.",
+      "path": "docs-user/menu.md"
+    },
+    {
+      "name": "miller",
+      "summary": "A Miller column component displays hierarchical data as multiple vertical columns, like macOS Finder or email clients. Each column shows the children of the selected item in the previous column.",
+      "path": "docs-user/miller.md"
+    },
+    {
+      "name": "narrowed-text",
+      "summary": "A filtered text selection component with inline search. Shows slotted items filtered by a query string as the user types.",
+      "path": "docs-user/narrowed-text.md"
+    },
+    {
+      "name": "notifier",
+      "summary": "A \"lookless\" app-wide notification system. `NotificationManager` is a singleton that owns notification state, queueing, and timing — it doesn't know how to draw anything. A `NotificationRenderer` (the",
+      "path": "docs-user/notifier.md"
+    },
+    {
+      "name": "panel",
+      "summary": "An collapsible panel component with support for titles, icons, toolbars, and multiple visual variants.",
+      "path": "docs-user/panel.md"
+    },
+    {
+      "name": "plots",
+      "summary": "SVG-based plotting components for visualising data streams.",
+      "path": "docs-user/plots.md"
+    },
+    {
+      "name": "polar-pad",
+      "summary": "A circular pad for setting polar coordinates (angle + radius). The user clicks or drags within a circle to position a marker. The marker's position encodes an angle (degrees, 0 = right, clockwise) and",
+      "path": "docs-user/polar-pad.md"
+    },
+    {
+      "name": "radial-input",
+      "summary": "A rotary dial input component inspired by music production interfaces (Ableton Live, synthesiser knobs). Renders as a flattened arc SVG and responds to drag and keyboard input.",
+      "path": "docs-user/radial-input.md"
+    },
+    {
+      "name": "range",
+      "summary": "Range: Coloured bar that suggests values",
+      "path": "docs-user/range.md"
+    },
+    {
+      "name": "range-input",
+      "summary": "A label-free, fully styled range slider wrapping `<input type=\"range\">`. Supports horizontal and vertical orientations, CSS variable theming, gradient fills, custom thumb shapes, and an optional value",
+      "path": "docs-user/range-input.md"
+    },
+    {
+      "name": "rating",
+      "summary": "A rating input that renders a row of glyphs (star / heart / square). Supports half-step increments, keyboard control, per-rank theming via CSS variables, and prominence-based hover feedback. Clicking ",
+      "path": "docs-user/rating.md"
+    },
+    {
+      "name": "select-horiz",
+      "summary": "A horizontally scrolling, snap-to-center single-item picker. Children are ordinary elements you provide — the component doesn't render its own item markup, it just lays them out with scroll-snap, keep",
+      "path": "docs-user/select-horiz.md"
+    },
+    {
+      "name": "slider-input",
+      "summary": "A linear SVG-based slider. Supports horizontal and vertical orientations, three value modes (single/dual/triple), three single-mode styles (range/bipolar/unipolar), triangle/needle/dot markers, and `v",
+      "path": "docs-user/slider-input.md"
+    },
+    {
+      "name": "snackbar",
+      "summary": "A small floating toolbar anchored in visual proximity to another element on the page (the \"target\"), built on the native Popover and CSS Anchor Positioning APIs.",
+      "path": "docs-user/snackbar.md"
+    },
+    {
+      "name": "snap-container",
+      "summary": "A container that positions its child element at configurable snap positions along an axis. The child can be dragged, clicked to snap, or controlled via keyboard.",
+      "path": "docs-user/snap-container.md"
+    },
+    {
+      "name": "split-layout",
+      "summary": "A Lit web component that lays out two elements within a container with a split bar to adjust their proportions.",
+      "path": "docs-user/split-layout.md"
+    },
+    {
+      "name": "swipe",
+      "summary": "A touch-friendly swipe/nudge component. User taps and drags to generate a value in range [-1, 1]. Value is emitted only on pointer release.",
+      "path": "docs-user/swipe.md"
+    },
+    {
+      "name": "tabs",
+      "summary": "A complete tabbed interface system using several coordinated components:",
+      "path": "docs-user/tabs.md"
+    },
+    {
+      "name": "timeline",
+      "summary": "A canvas-based timeline component with tracks, events, zoom/pan, and vertical track resizing. Suitable for visualizing time-series data, event logs, or scheduling.",
+      "path": "docs-user/timeline.md"
+    },
+    {
+      "name": "transitory-label",
+      "summary": "An inline text label that animates between values instead of changing instantly. Displays as `inline-block` and inherits text styling from its parent.",
+      "path": "docs-user/transitory-label.md"
+    },
+    {
+      "name": "tree",
+      "summary": "Three components share a common `TreeComponent` interface: **`ixfx-tree-list`**, **`ixfx-miller-list`**, and **`ixfx-crumb-navigation`**. This document describes the shared API, plus component-specifi",
+      "path": "docs-user/tree.md"
+    },
+    {
+      "name": "util",
+      "summary": "A tooltip component that renders a value with optional icon and formatted number display. Uses native render root (no shadow DOM).",
+      "path": "docs-user/util.md"
+    },
+    {
+      "name": "vertical-list",
+      "summary": "A scrollable vertical list of items with selection, keyboard navigation, and incremental search. Items can be plain `<li>` elements declared in HTML or rich custom elements added programmatically.",
+      "path": "docs-user/vertical-list.md"
+    },
+    {
+      "name": "xy-pad",
+      "summary": "A 2D touch-friendly XY pad for controlling two parameters simultaneously. Each axis supports independent linear/logarithmic scaling.",
+      "path": "docs-user/xy-pad.md"
+    }
+  ],
+  "overviews": [
+    {
+      "name": "user-catalog.md",
+      "path": "docs-user/user-catalog.md"
+    },
+    {
+      "name": "user-theming.md",
+      "path": "docs-user/user-theming.md"
+    }
+  ]
+}

package/docs-user/llms.txt

@@ -0,0 +1,57 @@
+# @ixfx/components
+> Web components for ixfx — Lit-based UI toolkit
+
+## Quick start
+```bash
+pnpm add @ixfx/components
+```
+```ts
+import '@ixfx/components/button';
+import '@ixfx/components/data-grid';
+```
+
+## Components
+- [ac-text](docs-user/ac-text.md): VS Code command-palette style autocomplete text input. Shows a popup with matching results as the user types.
+- [ac-token](docs-user/ac-token.md): Token/tag input with per-token autocomplete. Looks like a text box — committed tokens appear as inline chips, and a suggestion popup follows the typing cursor. Typical use cases are email To: fields a
+- [button](docs-user/button.md): Three related button components:
+- [checkbox](docs-user/checkbox.md): A custom checkbox with a diagonal line indicator and indeterminate state support. Uses shadow DOM with CSS variables for full appearance customization.
+- [colour-picker](docs-user/colour-picker.md): Two components for picking OKLCH colours. Use `ixfx-colour-picker` when you need a full inline picker; use `ixfx-colour-picker-popup` when you need a compact swatch that opens a picker in a popover.
+- [crumbs](docs-user/crumbs.md): Breadcrumb navigation with lazy-loading child support. Uses the same `TreeNode` / `TreeItem` data model as `ixfx-tree-list`, allowing easy swapping between the two components.
+- [data-display](docs-user/data-display.md): A debug data display component that renders key-value pairs from a plain object. Supports 7 inline render modes (`led`, `plot`, `plot-xy`, `plot-heat`, `plot-histogram`, `time-elapsed`, `hide`) via `c
+- [data-grid](docs-user/data-grid.md): A virtualised data grid with sortable/resizable/reorderable columns, single/multi selection, grouping, and inline cell editing. Handles 200+ rows with windowed rendering and keyboard navigation.
+- [editable-label](docs-user/editable-label.md): Inline editable text components. `ixfx-editable-number` extends `ixfx-editable-label` with drag-to-adjust and fill-bar visualization.
+- [form](docs-user/form.md): Primitives for typical form layout with responsive label positioning and data binding.
+- [grouped-item-lister](docs-user/grouped-item-lister.md): A meta-component that renders a typed item list using any sub-component you supply. Items can be displayed in a single sub-component (_ungrouped_ mode) or split into labelled groups, each with its own
+- [icons](docs-user/icons.md): A centralized SVG icon system for `@ixfx/components`. Icons are stored by name, can be overridden globally, and all components that use a given icon re-render automatically when it changes.
+- [incr-search](docs-user/incr-search.md): Utilities for incremental (type-ahead) search over data collections or DOM-backed lists.
+- [labelled-radial-input](docs-user/labelled-radial-input.md): A composite radial input that pairs an editable label (`ixfx-editable-number`) with a rotary dial (`ixfx-radial-input`). The two controls are always in sync — turning the dial updates the number, and 
+- [labelled-range-input](docs-user/labelled-range-input.md): A composite range input that pairs an editable label (`ixfx-editable-number`) with a slider (`ixfx-range-input`). The two controls are always in sync — dragging the slider updates the number, and edit
+- [led](docs-user/led.md): An LED indicator component with color mixing and optional blinking animation.
+- [menu](docs-user/menu.md): A custom menu system built on native HTML popovers with keyboard navigation, tickled focus management, and command routing.
+- [miller](docs-user/miller.md): A Miller column component displays hierarchical data as multiple vertical columns, like macOS Finder or email clients. Each column shows the children of the selected item in the previous column.
+- [narrowed-text](docs-user/narrowed-text.md): A filtered text selection component with inline search. Shows slotted items filtered by a query string as the user types.
+- [notifier](docs-user/notifier.md): A "lookless" app-wide notification system. `NotificationManager` is a singleton that owns notification state, queueing, and timing — it doesn't know how to draw anything. A `NotificationRenderer` (the
+- [panel](docs-user/panel.md): An collapsible panel component with support for titles, icons, toolbars, and multiple visual variants.
+- [plots](docs-user/plots.md): SVG-based plotting components for visualising data streams.
+- [polar-pad](docs-user/polar-pad.md): A circular pad for setting polar coordinates (angle + radius). The user clicks or drags within a circle to position a marker. The marker's position encodes an angle (degrees, 0 = right, clockwise) and
+- [radial-input](docs-user/radial-input.md): A rotary dial input component inspired by music production interfaces (Ableton Live, synthesiser knobs). Renders as a flattened arc SVG and responds to drag and keyboard input.
+- [range](docs-user/range.md): Range: Coloured bar that suggests values
+- [range-input](docs-user/range-input.md): A label-free, fully styled range slider wrapping `<input type="range">`. Supports horizontal and vertical orientations, CSS variable theming, gradient fills, custom thumb shapes, and an optional value
+- [rating](docs-user/rating.md): A rating input that renders a row of glyphs (star / heart / square). Supports half-step increments, keyboard control, per-rank theming via CSS variables, and prominence-based hover feedback. Clicking 
+- [select-horiz](docs-user/select-horiz.md): A horizontally scrolling, snap-to-center single-item picker. Children are ordinary elements you provide — the component doesn't render its own item markup, it just lays them out with scroll-snap, keep
+- [slider-input](docs-user/slider-input.md): A linear SVG-based slider. Supports horizontal and vertical orientations, three value modes (single/dual/triple), three single-mode styles (range/bipolar/unipolar), triangle/needle/dot markers, and `v
+- [snackbar](docs-user/snackbar.md): A small floating toolbar anchored in visual proximity to another element on the page (the "target"), built on the native Popover and CSS Anchor Positioning APIs.
+- [snap-container](docs-user/snap-container.md): A container that positions its child element at configurable snap positions along an axis. The child can be dragged, clicked to snap, or controlled via keyboard.
+- [split-layout](docs-user/split-layout.md): A Lit web component that lays out two elements within a container with a split bar to adjust their proportions.
+- [swipe](docs-user/swipe.md): A touch-friendly swipe/nudge component. User taps and drags to generate a value in range [-1, 1]. Value is emitted only on pointer release.
+- [tabs](docs-user/tabs.md): A complete tabbed interface system using several coordinated components:
+- [timeline](docs-user/timeline.md): A canvas-based timeline component with tracks, events, zoom/pan, and vertical track resizing. Suitable for visualizing time-series data, event logs, or scheduling.
+- [transitory-label](docs-user/transitory-label.md): An inline text label that animates between values instead of changing instantly. Displays as `inline-block` and inherits text styling from its parent.
+- [tree](docs-user/tree.md): Three components share a common `TreeComponent` interface: **`ixfx-tree-list`**, **`ixfx-miller-list`**, and **`ixfx-crumb-navigation`**. This document describes the shared API, plus component-specifi
+- [util](docs-user/util.md): A tooltip component that renders a value with optional icon and formatted number display. Uses native render root (no shadow DOM).
+- [vertical-list](docs-user/vertical-list.md): A scrollable vertical list of items with selection, keyboard navigation, and incremental search. Items can be plain `<li>` elements declared in HTML or rich custom elements added programmatically.
+- [xy-pad](docs-user/xy-pad.md): A 2D touch-friendly XY pad for controlling two parameters simultaneously. Each axis supports independent linear/logarithmic scaling.
+
+## Overviews
+- [user-catalog.md](docs-user/user-catalog.md)
+- [user-theming.md](docs-user/user-theming.md)

package/docs-user/menu.md

@@ -206,7 +206,7 @@ container.registry = registry;
 ```html
 <!-- label and icon resolved from registry -->
 <ixfx-menu-item command="bold"></ixfx-menu-item>
-<ixfx-menu-item command="italic"></ixfx-item>
+<ixfx-menu-item command="italic"></ixfx-menu-item>
 ```
 
 ### Keyboard Shortcuts
@@ -226,10 +226,12 @@ trigger.keyboardManager = keyboardManager;
 
 ### CSS Custom Properties
 
+`ixfx-menu-item` and `ixfx-menu-check-item` use the generic "Item States" variable family documented in `user-theming.md` (`--item-bg`, `--item-bg-tickled`, `--item-border`, `--item-border-tickled`, `--item-text-tickled`, etc.) — the same family used by other list/item components such as `ixfx-vertical-list` and `ixfx-select-horiz`.
+
+The trigger button and menu bar additionally expose a couple of underscore-prefixed variables — the underscore marks these as narrowly-scoped internal tuning knobs (unlike the generic `--item-*` family above, they have no effect outside the trigger/bar):
+
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `--_item-hover-bg` | `var(--surface-6)` | Background on mouse hover |
-| `--_item-focused-bg` | `var(--surface-6)` | Background when keyboard-focused (tickled) |
 | `--_trigger-hover-bg` | `var(--surface-4)` | Trigger button hover background |
 | `--_trigger-hover-opacity` | `1` | Trigger button hover opacity |
 
@@ -245,10 +247,9 @@ The popup surface uses these from `popupSurfaceStyles`:
 ### Custom Item Background Colors
 
 ```css
-/* Apply to ixfx-menu-container */
+/* Apply to ixfx-menu-container, or globally on :root */
 ixfx-menu-container {
-  --_item-hover-bg: #ffdddd;
-  --_item-focused-bg: #ffcccc;
+  --item-bg-tickled: #ffcccc;
 }
 ```
 
@@ -280,10 +281,12 @@ ixfx-menu-item[command="delete"] .item {
 
 | Event | Detail | Description |
 |-------|--------|-------------|
-| `command` | `{ command, args, checked? }` | Fired by `ixfx-menu-item`, `ixfx-menu-check-item` |
+| `command` | `{ command, args }` | Fired by `ixfx-menu-item` |
+| `command` | `{ command, args, checked }` | Fired by `ixfx-menu-check-item` |
 | `radio-select` | `{ value }` | Fired by `ixfx-menu-radio-item` |
 | `radio-change` | `{ name, value }` | Fired by `ixfx-menu-radio-group` when selection changes |
-| `menu-command` | `{ command, value?, checked? }` | Bubbles up from `ixfx-menu-trigger` |
+| `menu-command` | `{ command, args, checked }` | Bubbles up from `ixfx-menu-trigger`, re-dispatching a `command`/`checked` event's detail verbatim — `args` is always present, `checked` only from a check-item |
+| `menu-command` | `{ command, value }` | Bubbles up from `ixfx-menu-trigger`, built from a `radio-change` event — `value` only appears on this radio-group path, never alongside `args`/`checked` |
 
 ## `ixfx-menu-command-controller`