@ixfx/components 0.4.3 → 0.5.0

package/docs-user/tabs.md

@@ -2,8 +2,6 @@
 
 A complete tabbed interface system using several coordinated components:
 
-- **`ixfx-tab-layout`** — Layout wrapper (minimal)
-- **`ixfx-tab-layout-item`** — Individual tab item within layout
 - **`ixfx-tab-list`** — Tab header bar with tab buttons
 - **`ixfx-tab-list-item`** — Individual tab button
 - **`ixfx-tab-panel`** — Content panel for a single tab
@@ -12,17 +10,15 @@ A complete tabbed interface system using several coordinated components:
 ## Basic usage
 
 ```html
-<ixfx-tab-layout>
-  <ixfx-tab-list>
-    <ixfx-tab-list-item id="tab-home" for="panel-home">Home</ixfx-tab-list-item>
-    <ixfx-tab-list-item id="tab-profile" for="panel-profile">Profile</ixfx-tab-list-item>
-  </ixfx-tab-list>
-  
-  <ixfx-tab-panels>
-    <ixfx-tab-panel id="panel-home">Home content</ixfx-tab-panel>
-    <ixfx-tab-panel id="panel-profile">Profile content</ixfx-tab-panel>
-  </ixfx-tab-panels>
-</ixfx-tab-layout>
+<ixfx-tab-list>
+  <ixfx-tab-list-item id="tab-home" for="panel-home">Home</ixfx-tab-list-item>
+  <ixfx-tab-list-item id="tab-profile" for="panel-profile">Profile</ixfx-tab-list-item>
+</ixfx-tab-list>
+
+<ixfx-tab-panels>
+  <ixfx-tab-panel id="panel-home">Home content</ixfx-tab-panel>
+  <ixfx-tab-panel id="panel-profile">Profile content</ixfx-tab-panel>
+</ixfx-tab-panels>
 ```
 
 Wire them together:
@@ -47,13 +43,15 @@ Manages tab selection and keyboard navigation.
 |---------------------|-----------------------------------|----------------|----------------------------------|
 | `orientation`       | `'horizontal' \| 'vertical-stack' \| 'vertical-side'` | `'horizontal'` | Layout direction |
 | `flip`              | `boolean`                          | `false`        | Flip indicator to opposite side   |
-| `scrollable`        | `boolean`                          | `false`        | Enable scroll overflow           |
+| `scrollable`        | `boolean`                          | `false`        | Enable scroll overflow. When set, vertical mousewheel on horizontal lists scrolls horizontally (and vice-versa for vertical lists). |
+| `drag-mode`         | `'off' \| 'reorder'`                | `'off'`        | Pointer-driven reordering within the list (sets `grab` cursor on items) |
 
 ### Events
 
 | Event    | Detail                                               | Description               |
 |----------|------------------------------------------------------|---------------------------|
 | `change` | `{ previous, selected, for }`                       | Tab selection changed     |
+| `reorder` | `{ id, fromIndex, toIndex }`                       | Tab reordered (only fired when `drag-mode="reorder"`). Fires after the DOM has been updated. Press <kbd>Esc</kbd> or receive a `pointercancel` while dragging to abort — no `reorder` event fires in that case. |
 
 ### Methods
 

package/docs-user/user-catalog.md

@@ -30,12 +30,33 @@ A circular input control for selecting values in a rotational manner. Ideal for
 ### ixfx-ac-text
 An autocomplete text input that suggests options as the user type. Perfect for search boxes, tag entry, or any field where you want to assist users with predefined options.
 
+### ixfx-ac-token
+A token/tag input with per-token autocomplete, where committed tokens appear as inline chips and a suggestion popup follows the typing cursor. Ideal for email recipient fields, tag pickers, or any multi-value entry with per-value suggestions.
+
 ### ixfx-narrowed-text
 A specialized text input that constrains input length and provides visual feedback about remaining capacity. Use for fields with strict character limits like tweet composition or SMS messages.
 
 ### ixfx-editable-label
 A label that becomes an inline editor when clicked or focused. Useful for in-place editing of list items, card titles, or any display text that users might need to modify.
 
+### ixfx-editable-number
+A numeric label that combines inline text editing with pointer-drag-to-adjust (Ableton-style), optional min/max clamping, step snapping, and a fill-bar visualisation. Use for mixing-console-style numeric controls where both typing and dragging are appropriate.
+
+### ixfx-range-input
+A label-free, fully styled range slider wrapping the native `<input type="range">`. Supports horizontal and vertical orientations, custom thumb shapes, gradient fills, and an optional value tooltip. Use as a drop-in replacement for native range inputs when you need consistent theming.
+
+### ixfx-slider-input
+A linear SVG-based slider with horizontal/vertical orientations, single/dual/triple value modes, and triangle/needle/dot markers. Use for audio-mixer style multi-handle sliders, threshold selectors, or any interface requiring precise linear control.
+
+### ixfx-radial-input
+A rotary dial input rendered as a flattened arc SVG, inspired by music production interfaces. Responds to drag and keyboard input. Use as a building block for custom rotary controls or combine with `ixfx-editable-label` via `ixfx-labelled-radial-input`.
+
+### ixfx-swipe
+A touch-friendly swipe/nudge component that produces a value in [-1, 1] based on tap-and-drag distance, emitted only on pointer release. Use as a compact gesture control for audio scrubbing, video seeking, or any value where a spring-back gesture is appropriate.
+
+### ixfx-vertical-list
+A scrollable vertical list of items with selection, keyboard navigation, and incremental search. Supports plain `<li>` items in HTML or rich custom elements added programmatically. Use wherever you need a list with first-class keyboard and selection support.
+
 ### ixfx-color-picker
 A comprehensive color selection tool with multiple modes (hue/saturation/lightness, red/green/blue, etc.) and support for saving custom colors. Use whenever users need to select or adjust colors.
 
@@ -53,9 +74,21 @@ A tabbed interface for organizing content into separate views. Use when you have
 ### ixfx-tab-panel
 Individual panels that work with the ixfx-tabs component to create tabbed interfaces.
 
+### ixfx-tab-panels
+A container that manages a collection of `ixfx-tab-panel` children and exposes a `selectPanel()` method to switch between them. Pair with `ixfx-tab-list` for a complete tabbed interface.
+
+### ixfx-tab-list
+The header bar of a tabbed interface, holding `ixfx-tab-list-item` buttons and emitting a `change` event when the active tab changes. Pair with `ixfx-tab-panels` for a complete tabbed interface.
+
+### ixfx-tab-list-item
+Individual tab buttons used inside `ixfx-tab-list`. Use the `for` attribute to associate each button with the id of its corresponding `ixfx-tab-panel`.
+
 ### ixfx-data-display
 A flexible component for presenting various types of data with consistent formatting. Use for showing metrics, status information, or any structured data that benefits from standardized presentation.
 
+### ixfx-transitory-label
+An inline text label that animates between values instead of changing instantly, with fade, slide-up, and other transition effects. Use for status readouts, mode indicators, or any text that benefits from smooth value transitions rather than abrupt updates.
+
 ## Navigation Components
 
 ### ixfx-menu
@@ -76,6 +109,15 @@ A hierarchical tree view component for displaying nested data structures. Perfec
 ### ixfx-crumb-navigation
 Similar to breadcrumb navigation but with a more compact representation focused on the immediate path context.
 
+### ixfx-crumb-path
+A path-style breadcrumb (e.g. `/users/jane/projects`) with editable path segments and autocomplete dropdowns. Supports lazy-loaded sibling paths. Use for file paths, URL navigation, or any address-bar-style interface where segments can be edited inline.
+
+### ixfx-miller
+A Miller column component that 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. Use for navigating deeply nested data with persistent visibility of the path.
+
+### ixfx-grouped-item-lister
+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 sub-component (grouped mode). Use for categorised lists, filtered views, or any list that needs both grouping and rich item rendering.
+
 ## Layout Components
 
 ### ixfx-split-layout
@@ -110,6 +152,15 @@ A component for representing and manipulating numerical ranges with visual handl
 ### ixfx-range-multi
 An extension of the range component that allows multiple non-overlapping ranges to be selected simultaneously. Ideal for selecting multiple time segments or value ranges.
 
+### ixfx-plot-multi-axis
+A multi-series plot that renders several named 1D data streams simultaneously with per-series colours. Use for comparing multiple sensor readings, multi-track audio visualisation, or any scenario where several signals need to share the same axes.
+
+### ixfx-plot-histogram
+A histogram plot that bins buffered values into buckets over the observed (or fixed) data range, with no time or sequence axis. Use for value distributions, density estimation, or any scenario where the shape of a dataset matters more than its order.
+
+### ixfx-hex-editor
+A hex editor for inspecting and editing binary data, with configurable columns, ASCII/Hex/Offset columns, byte-level selection, drag-to-edit values, undo/redo, and colour-scheme options. Use for binary file inspection, debuggers, or any tool that needs to view or modify raw bytes.
+
 ## Utility Components
 
 ### ixfx-icon
@@ -124,6 +175,9 @@ A simple indicator light component that can show on/off states or various colors
 ### ixfx-horizontal-selector
 A compact horizontal control for selecting from a set of options. Use when you need a more space-efficient alternative to radio groups or dropdowns.
 
+### ixfx-incr-search
+Incremental (type-ahead) search utilities for filtering data collections or DOM-backed lists in real time. Provides controllers for plain lists, tree components, and Miller columns, with built-in highlighting and keyboard navigation. Use to add fast type-ahead filtering to any list, tree, or column-based interface.
+
 ## Component Selection Guidelines
 
 When choosing components for your application, consider these patterns:
@@ -131,22 +185,30 @@ When choosing components for your application, consider these patterns:
 ### For Forms and Settings
 - Use `ixfx-checkbox` for binary options
 - Use `ixfx-radio-group` for mutually exclusive choices
-- Use `ixfx-labelled-range-input` for numerical parameters
+- Use `ixfx-labelled-range-input` for numerical parameters with labels
 - Use `ixfx-toggle-switch` for settings with clear on/off states
+- Use `ixfx-range-input` or `ixfx-slider-input` for plain slider-style numeric entry
+- Use `ixfx-editable-number` for values that benefit from both typing and dragging
 - Use `ixfx-panel` or `ixfx-panel-group` to organize related settings
 
 ### For Data Display
 - Use `ixfx-data-display` for consistent metric presentation
 - Use `ixfx-panel` as containers for grouped information
 - Use `ixfx-tabs` to separate different views of related data
-- Use visualization components (`ixfx-xy-pad`, `ixfx-single-axis`, etc.) for graphical data representation
+- Use visualization components (`ixfx-xy-pad`, `ixfx-single-axis`, `ixfx-plot-multi-axis`, `ixfx-plot-histogram`, etc.) for graphical data representation
+- Use `ixfx-transitory-label` for readouts that animate between values
 
 ### For Navigation and Selection
 - Use `ixfx-menu` for contextual actions
 - Use `ixfx-menu-bar` for primary application navigation
 - Use `ixfx-tree` for hierarchical data exploration
 - Use `ixfx-breadcrumb-navigation` to show location in hierarchies
-- Use `ixfx-ac-text` for assisted text entry with predefined options
+- Use `ixfx-crumb-path` for path-style navigation with editable segments
+- Use `ixfx-miller` for deeply nested data with persistent column visibility
+- Use `ixfx-vertical-list` for selectable, keyboard-navigable lists
+- Use `ixfx-grouped-item-lister` for typed, optionally grouped item lists
+- Use `ixfx-ac-text` for assisted single-value entry with predefined options
+- Use `ixfx-ac-token` for multi-value tag/recipient entry with per-token suggestions
 
 ### For Layout and Structure
 - Use `ixfx-split-layout` for adjustable panes
@@ -156,9 +218,12 @@ When choosing components for your application, consider these patterns:
 
 ### For Interactive Controls
 - Use `ixfx-xy-pad` for 2D parameter control
-- Use `ixfx-labelled-radial-input` for circular parameters
+- Use `ixfx-labelled-radial-input` for labelled rotary parameters
+- Use `ixfx-radial-input` for bare rotary dial controls
 - Use `ixfx-range` or `ixfx-range-multi` for value ranges
+- Use `ixfx-swipe` for spring-back gesture controls
 - Use `ixfx-color-picker` for comprehensive color selection
+- Use `ixfx-hex-editor` for inspecting or editing raw binary data
 
 This catalog represents the core components available in the ixfx library. Each component is designed to work together through a shared theming system and consistent interaction patterns, allowing you to build cohesive interfaces with minimal effort.
 

package/docs-user/vertical-list.md

@@ -9,12 +9,13 @@ A scrollable vertical list of items with selection, keyboard navigation, and inc
 1. [Quick start](#quick-start)
 2. [Item types](#item-types)
 3. [Properties](#properties)
-4. [Selection](#selection)
-5. [Events](#events)
-6. [Keyboard navigation](#keyboard-navigation)
-7. [Incremental search](#incremental-search)
-8. [CSS variables](#css-variables)
-9. [CSS parts](#css-parts)
+4. [Custom checkbox](#custom-checkbox)
+5. [Selection](#selection)
+6. [Events](#events)
+7. [Keyboard navigation](#keyboard-navigation)
+8. [Incremental search](#incremental-search)
+9. [CSS variables](#css-variables)
+10. [CSS parts](#css-parts)
 
 ---
 
@@ -115,6 +116,7 @@ To reflect selection state inside the custom element's shadow DOM, target the `:
 | `selectionMode` / `selection-mode` | `'none' \| 'single' \| 'multiple'` | `'single'` | Which items can be selected simultaneously |
 | `interactionMode` / `interaction-mode` | `ListInteractionMode` | `'standard'` | How gestures map to selection changes (see table below) |
 | `filterPredicate` | `((el: Element) => boolean) \| undefined` | `undefined` | External filter; only items returning `true` are shown |
+| `checkboxRenderer` | `((checked: boolean) => unknown) \| undefined` | `undefined` | Custom content for the checkbox in `checked` mode. See [Custom checkbox](#custom-checkbox) |
 
 Switching `interactionMode` always clears the current selection.
 
@@ -125,11 +127,63 @@ Switching `interactionMode` always clears the current selection.
 | `'implicit'` | Click always replaces selection. No modifier support. |
 | `'standard'` | Plain click replaces selection; Ctrl/Cmd+click toggles; Shift+click range-selects (multiple mode only); Cmd+A selects all |
 | `'vscode'` | Like `standard` for clicks; Shift+Arrow extends the range from the keyboard anchor |
-| `'checked'` | Checkboxes on every `<li>` row; checkbox click (or Space) toggles; body clicks do nothing. Custom elements show a left-border indicator instead of a checkbox |
+| `'checked'` | Checkbox column on the left of every row; only that column is clickable and it spans the full row height so a tall card can still be toggled with a single click on the left; Space toggles the focused row. See [Custom checkbox](#custom-checkbox) for styling |
 | `'manual'` | No automatic selection; drive state entirely via `select()` / `deselect()` / `clearSelection()` |
 
 ---
 
+## Custom checkbox
+
+In `checked` mode every row gets a checkbox column on the left. The column is always a **full-height click target** (the wrapper uses `align-self: stretch`), so a single click anywhere on the left side of a tall card toggles it — you never have to precisely hit a small checkbox. Clicks on the row body (the text or custom card content) do **not** toggle, and the cursor is `default` there so the affordance is clear.
+
+By default the column contains a native `<input type="checkbox">`. The visible square is small, but the entire column (~20–24px wide, full row height) is clickable.
+
+### Subtle style — `checkboxRenderer`
+
+Set `checkboxRenderer` to a function that returns a Lit template. The function receives the row's current `checked` state. This is what enables the *subtle* style: render an empty template when unchecked and a translucent mark when checked.
+
+```typescript
+import { html } from 'lit';
+import type { VerticalListElement } from '@ixfx/components';
+
+const list = document.querySelector<VerticalListElement>('#my-list')!;
+list.interactionMode = 'checked';
+
+// Nothing when unchecked; a translucent tick when checked
+list.checkboxRenderer = (checked) => checked
+  ? html`<svg viewBox="0 0 16 16" width="14" height="14"
+        fill="none" stroke="currentColor" stroke-width="2"
+        stroke-linecap="round" stroke-linejoin="round"
+        style="opacity:0.5">
+      <polyline points="3,8 7,12 13,4" />
+    </svg>`
+  : html``;
+```
+
+Because the wrapper still spans the full row height and owns the click handler, the empty unchecked area is just as clickable as the visible tick — even though there is no border, background, or other visual indicator of where the column is.
+
+### How it works under the hood
+
+In `checked` mode each row has a `<span class="ixfx-list-checkbox" role="checkbox" part="checkbox">` prepended as the first child:
+
+- When `checkboxRenderer` is set, your template is rendered into the span (via lit's `render()`) and re-rendered on every state change.
+- When `checkboxRenderer` is **not** set, the span contains a real `<input type="checkbox">` with `pointer-events: none` — the span owns the click so there is exactly one toggle per click.
+- `aria-checked` and `data-checked` on the span reflect the current state.
+- `align-self: stretch` makes the span fill the row's cross-axis, giving you the full-height click target.
+
+The element is also exposed as the `checkbox` CSS part, so you can tune the wrapper from outside:
+
+```css
+ixfx-vertical-list::part(checkbox) {
+  width: 32px;          /* a wider column */
+  color: var(--accent); /* recolour your rendered content */
+}
+```
+
+You can change `checkboxRenderer` at any time (e.g., swap the subtle SVG for an animated check); the wrapper element swaps in place and the renderer is re-applied.
+
+---
+
 ## Selection
 
 ### Programmatic API
@@ -328,6 +382,19 @@ list.filterPredicate = undefined;
 | `--item-bg-selected-tickled` | `rgba(21,101,192,1)` | Selected + cursor row background |
 | `--accent` | — | Accent colour (focus ring, search highlight, checkbox) |
 | `--transition` | `0.1s ease-out` | Transition timing for hover/selection changes |
+| `--list-scrollbar-width` | `auto` | Maps to the `scrollbar-width` CSS property on the scroll container (`auto`, `thin`, `none`) |
+| `--list-scrollbar-gutter` | `auto` | Maps to the `scrollbar-gutter` CSS property on the scroll container (`auto`, `stable`, `stable both-edges`) |
+| `--list-scrollbar-color` | `auto` | Maps to the `scrollbar-color` CSS property on the scroll container (`auto` or a two-colour `thumb track` pair) |
+
+The three `--list-scrollbar-*` variables are consumed by the shadow-DOM `<ul>` scroll container, so they can be set on any ancestor:
+
+```css
+ixfx-vertical-list {
+  --list-scrollbar-width: thin;
+  --list-scrollbar-gutter: stable;
+  --list-scrollbar-color: var(--accent) var(--surface-2);
+}
+```
 
 ---
 
@@ -337,6 +404,7 @@ list.filterPredicate = undefined;
 |---|---|
 | `list` | The `<ul>` scroll container |
 | `search-overlay` | The floating search input overlay |
+| `checkbox` | The per-row checkbox column wrapper in `checked` mode (always present; hosts the native `<input>` or the user-rendered content) |
 
 Use `::part()` to style these from outside the component's shadow DOM:
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ixfx/components",
   "type": "module",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "",
   "author": "",
   "license": "ISC",
@@ -33,8 +33,10 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "start": "vite serve",
+    "dev": "vite serve",
     "lint": "eslint",
     "lint:fix": "eslint --fix",
+    "build:md": "node ./scripts/collate-docs.ts",
     "build": "tsdown",
     "rebuild": "rm -rf dist bundle && pnpm run build",
     "publish-prepare": "pnpm run rebuild && pnpm run typecheck && pnpm run lint",
@@ -43,29 +45,30 @@
   },
   "dependencies": {
     "@clinth/ui-commands": "1.1.0",
+    "@clinth/vcanvas": "0.0.3",
+    "@ixfx/arrays": "0.56.14",
+    "@ixfx/collections": "0.56.14",
+    "@ixfx/core": "0.56.14",
+    "@ixfx/dom": "0.56.14",
+    "@ixfx/flow": "0.56.14",
+    "@ixfx/geometry": "0.56.14",
+    "@ixfx/modulation": "0.56.14",
+    "@ixfx/numbers": "0.56.14",
+    "@ixfx/visual": "0.56.14",
     "fzf": "0.5.2",
     "lit": "3.3.3"
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^9.0.0",
-    "@clinth/vcanvas": "0.0.3",
-    "@ixfx/arrays": "0.56.13",
-    "@ixfx/collections": "0.56.13",
-    "@ixfx/core": "0.56.13",
-    "@ixfx/dom": "0.56.13",
-    "@ixfx/flow": "0.56.13",
-    "@ixfx/geometry": "0.56.13",
-    "@ixfx/modulation": "0.56.13",
-    "@ixfx/numbers": "0.56.13",
-    "@ixfx/visual": "0.56.13",
-    "@tsdown/css": "0.22.1",
-    "eslint": "10.4.1",
+    "@antfu/eslint-config": "^9.3.0",
+    "@tsdown/css": "0.22.14",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "eslint": "10.8.1",
     "eslint-plugin-format": "2.0.1",
-    "globals": "17.6.0",
-    "knip": "6.14.2",
-    "tsdown": "0.22.1",
-    "typescript": "6.0.3",
-    "typescript-eslint": "8.60.0",
-    "vite": "8.0.14"
+    "globals": "17.9.0",
+    "knip": "6.32.0",
+    "tsdown": "0.22.14",
+    "typescript": "npm:@typescript/typescript6@6.0.2",
+    "typescript-eslint": "8.66.0",
+    "vite": "8.2.1"
   }
 }