@ixfx/components 0.5.20 → 0.6.0

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/rating.md

@@ -0,0 +1,102 @@
+# `ixfx-rating`
+
+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 the current value clears it to `0` (unrated).
+
+```html
+<ixfx-rating value="3"></ixfx-rating>
+<ixfx-rating allow-half value="2.5"></ixfx-rating>
+<ixfx-rating max="10" value="7"></ixfx-rating>
+<ixfx-rating variant="heart" value="4"></ixfx-rating>
+<ixfx-rating variant="square" value="3"></ixfx-rating>
+<ixfx-rating disabled value="3"></ixfx-rating>
+<ixfx-rating readonly value="3"></ixfx-rating>
+```
+
+### Properties / attributes
+
+| Attribute / Property | Type | Default | Description |
+|---|---|---|---|
+| `value` | `number` | `0` | Current rating. `0` means unrated. Clamped `0..max` |
+| `max` | `number` | `5` | Number of glyphs rendered |
+| `allow-half` / `allowHalf` | `boolean` | `false` | When set, pointer position within a glyph selects `n` or `n+0.5`; keyboard step becomes `0.5` |
+| `variant` | `"star"` \| `"heart"` \| `"square"` | `"star"` | Glyph shape |
+| `disabled` | `boolean` | `false` | Disables interaction; muted via prominence filter and `pointer-events: none` |
+| `readonly` | `boolean` | `false` | Prevents interaction but retains full visual prominence |
+
+### Events
+
+Both events bubble and are `composed`.
+
+| Event | Detail | Description |
+|---|---|---|
+| `input` | `{ value: number, oldValue: number }` | Fired on commit |
+| `change` | `{ value: number, oldValue: number }` | Fired on commit (same timing as `input` for this component) |
+
+Clicking the glyph that already equals `value` clears to `0`. Both events carry the previous value as `oldValue`.
+
+```ts
+import type { RatingChangeEvent } from './rating.js';
+el.addEventListener('change', (e: RatingChangeEvent) => {
+  console.log(e.detail.value, e.detail.oldValue);
+});
+el.addEventListener('input', (e: RatingChangeEvent) => {
+  console.log(e.detail.value, e.detail.oldValue);
+});
+```
+
+### Interaction
+
+**Pointer:** hovering previews the value that would be set (filled glyphs use the hover colour, host gains prominence saturation). Click commits; clicking the active value clears to `0`. With `allow-half`, the left/right half of a glyph resolves to `n+0.5` / `n+1`.
+
+**Keyboard** (when focused, not `disabled`/`readonly`):
+
+| Key | Action |
+|---|---|
+| `ArrowRight` / `ArrowUp` | Increase by `1` (or `0.5` with `allow-half`) |
+| `ArrowLeft` / `ArrowDown` | Decrease by `1` (or `0.5`) |
+| `Home` | Clear to `0` |
+| `End` | Set to `max` |
+| `0`–`9` | Set to that number (clamped to `max`) |
+
+Accessibility: `role="slider"` with `aria-valuenow` / `aria-valuemin="0"` / `aria-valuemax` / `aria-disabled` / `aria-readonly`; `tabindex` is `0` when interactive, `-1` when `disabled` or `readonly`.
+
+### CSS custom properties
+
+| Property | Default | Description |
+|---|---|---|
+| `--ixfx-rating-size` | `1.5rem` | Glyph width/height |
+| `--ixfx-rating-gap` | `0.2rem` | Gap between glyphs |
+| `--ixfx-rating-color` | `var(--surface-4)` | Idle glyph colour |
+| `--ixfx-rating-color-active` | `var(--accent)` | Filled glyph colour |
+| `--ixfx-rating-color-hover` | `var(--accent)` | Hover-preview glyph colour |
+| `--ixfx-rating-<n>-color` | — | Per-rank idle override (e.g. `--ixfx-rating-3-color`) |
+| `--ixfx-rating-<n>-color-active` | — | Per-rank filled override |
+| `--ixfx-rating-<n>-color-hover` | — | Per-rank hover override |
+
+Per-rank variables are set **outside** the shadow DOM (e.g. on the `ixfx-rating` element or a parent) and bridged via inline `var()` fallbacks on each glyph, so they pierce the shadow boundary without extra plumbing.
+
+```html
+<style>
+  ixfx-rating.saturated {
+    --ixfx-rating-1-color-active: oklch(70% 0.05 280);
+    --ixfx-rating-5-color-active: oklch(60% 0.25 30);
+  }
+</style>
+<ixfx-rating class="saturated" value="4"></ixfx-rating>
+```
+
+### Prominence
+
+Includes `prominenceStyles` from `src/styles/prominence.ts`: idle state is desaturated/dimmed, `:hover` / `:focus-within` raises opacity and saturation, `:active` removes the filter, `disabled` applies a heavy mute. `readonly` explicitly resets the filter so it remains visually full. Override via `--prominence-*` variables if needed.
+
+### TypeScript types
+
+```ts
+import type { RatingElement, RatingVariant, RatingChangeDetail, RatingChangeEvent } from 'ixfxfun-components';
+```
+
+### Implementation notes
+
+* Half-fill is a stacked pair ofidentical SVGs — a background glyph plus an absolutely-positioned foreground glyph clipped with `clip-path: inset(0 50% 0 0)`.
+* Glyph paths are inline `d` strings (`star` is a 5-point star, `heart` a cardioid-like path, `square` a rect) sharing a single `24×24` viewBox.
+* Preview is local `@state _preview: number | null`, derived into render via `_effective() = _preview ?? value`; `pointerleave` on the host clears it.