@ixfx/components 0.16.2 → 0.16.4

package/docs-user/grid-list.md

@@ -194,7 +194,7 @@ grid.addEventListener('list-select', ({ detail }) => {
 ```
 
 Caller-owned selection: a cancelable `list-select-intent` fires before every gesture, and `partialKeys` marks partially selected cells (`data-partial`, `part="item partial"`).
-See [Selection intents, partial rows, unloaded keys](../../docs/infra-selection-intents.md): `list-select-intent`, `partialKeys`, and keys that arrive later.
+See [Selection intents, partial rows, unloaded keys](./user-selection-intents.md): `list-select-intent`, `partialKeys`, and keys that arrive later.
 
 Restore across a reload:
 
@@ -329,7 +329,7 @@ items directly, independent of search; the data-mode equivalent is
 `itemFilterPredicate` (`(item, index) => boolean`). Filtering removes items from
 layout and navigation without materialising anything in data mode. Limit modes
 with `search-modes="navigate filter"`. Full model:
-[`docs/infra-incremental.md`](../../docs/infra-incremental.md).
+[`docs/infra-incremental.md`](./infra-incremental.md).
 
 ---
 
@@ -428,7 +428,7 @@ operations.
 
 ## Grouping
 
-Group items under collapsible headers, following `ixfx-data-grid` (see its [Grouping](../data-grid/README.md#grouping) section).
+Group items under collapsible headers, following `ixfx-data-grid` (see its [Grouping](./data-grid.md#grouping) section).
 
 ```ts
 grid.groupBy = 'kind';                       // data mode: item property · element mode: data-kind attribute
@@ -463,7 +463,7 @@ Differences from data-grid: group state is reset on every `groupBy` change, the
 
 Snapshot and restore how the grid is showing its data, separately from the
 data. The contract is shared with the other list components; see
-[`docs/infra-view-state.md`](../../docs/infra-view-state.md).
+[`docs/infra-view-state.md`](./infra-view-state.md).
 
 ```ts
 import { bindViewState } from '@ixfx/components';

package/docs-user/hyperbolic-tree.md

@@ -2,7 +2,7 @@
 
 `<ixfx-hyperbolictree-list>` — a hyperbolic (Poincaré disk) browser over tree data. The focused node sits at the disk's center; its neighbourhood fans outward, shrinking toward the edge with tree-graph distance. Clicking a node re-centers the disk on it with an animated Möbius transform — the underlying layout never changes, only the projection.
 
-It implements the shared `TreeComponent` interface (see [`src/tree/README.md`](../tree/README.md)), so `TreeDataModel`, `IncrSearchTreeController`, and any `TreeComponent`-typed code work unmodified.
+It implements the shared `TreeComponent` interface (see [`src/tree/README.md`](./tree.md)), so `TreeDataModel`, `IncrSearchTreeController`, and any `TreeComponent`-typed code work unmodified.
 
 ---
 
@@ -36,7 +36,7 @@ It implements the shared `TreeComponent` interface (see [`src/tree/README.md`](.
 
 ## Data model
 
-Same `TreeNode` / `TreeItem` shapes as the rest of the tree family (see [`src/tree/README.md`](../tree/README.md#data-model)), including `root`, `model` (`TreeDataModel`), and `loadChildren` for lazy loading.
+Same `TreeNode` / `TreeItem` shapes as the rest of the tree family (see [`src/tree/README.md`](./tree.md#data-model)), including `root`, `model` (`TreeDataModel`), and `loadChildren` for lazy loading.
 
 Keys only need to be unique **among siblings**: internally each node is identified by its key *path* from the root (`HyperbolicLayoutNode.id`), so data like a file system — where `readme.md` recurs in many folders — lays out and focuses correctly. Key-based lookups that can't know the path (`focusedKey` when given a bare key, `revealKey`, `::part(node-<key>)`) match the first node, depth-first, carrying that key.
 
@@ -58,7 +58,7 @@ el.root = {
 | `model` | `TreeDataModel \| undefined` | `undefined` | Shared data model; takes precedence over `loadChildren` |
 | `loadChildren` | `LoadChildrenCallback \| undefined` | `undefined` | Callback for lazy child loading |
 | `restoreLoads` | `boolean` | `true` | Whether restoring a saved `center` may load its unloaded ancestors. See [View state](#view-state) |
-| `interactionMode` (`interaction-mode`) | `'implicit' \| 'standard' \| 'manual'` | `'standard'` | Gesture mapping — see [`src/tree/README.md`](../tree/README.md#interactionmode-ixfx-tree-list--ixfx-miller-list) (`'checked'` is unsupported here) |
+| `interactionMode` (`interaction-mode`) | `'implicit' \| 'standard' \| 'manual'` | `'standard'` | Gesture mapping — see [`src/tree/README.md`](./tree.md#interactionmode-ixfx-tree-list--ixfx-miller-list) (`'checked'` is unsupported here) |
 | `selectionFilter` (`selection-filter`) | `'none' \| 'leaf' \| 'branch' \| 'all'` | `'all'` | Which node kinds can be selected |
 | `exclusivity` | `TreeExclusivity` | `'none'` | Accepted for interface compatibility, ignored |
 | `filterPredicate` | `TreeFilterPredicate \| undefined` | `undefined` | Non-matching nodes (and branches with no matching descendant) are dimmed, not hidden |
@@ -80,7 +80,7 @@ el.root = {
 | `focusAnimationDuration` (`focus-animation-duration`) | `number` | `400` | Duration (ms) of the animated re-center on focus change; `0` snaps instantly. Respects `prefers-reduced-motion` |
 | `edgeRenderer` | `HyperbolicEdgeRenderer \| undefined` | `undefined` | Custom renderer for edges, in place of the default geodesic-arc path |
 | `disableKeyboardNavigation` (`disable-keyboard-navigation`) | `boolean` | `false` | Disables the keyboard handlers below |
-| `searchModes` (`search-modes`) | `string \| undefined` | `undefined` | Space-separated subset of `navigate select filter` — see [`src/tree/README.md`](../tree/README.md#incremental-search) |
+| `searchModes` (`search-modes`) | `string \| undefined` | `undefined` | Space-separated subset of `navigate select filter` — see [`src/tree/README.md`](./tree.md#incremental-search) |
 | `selectedNode` | `TreeNode \| undefined` | `undefined` | Primary (most recent) selected node |
 | `selectedNodes` | `ReadonlySet<TreeNode>` | `{}` | Full selection set (read-only) |
 | `focusedNode` | `TreeNode \| undefined` (read-only) | true root | The node currently centered on the disk. Pure view-state — `root` is never mutated by focus changes |
@@ -256,7 +256,7 @@ const nodes = el.getNodes(); // ReadonlyArray<{ node: TreeNode; depth: number }>
 
 ## View state
 
-Implements the shared view-state API (`getViewState()` / `setViewState()` / `clearPendingViewState()` / `view-state-change`) — see [`docs/infra-view-state.md`](../../docs/infra-view-state.md). `kind` is `hyperbolictree-list`.
+Implements the shared view-state API (`getViewState()` / `setViewState()` / `clearPendingViewState()` / `view-state-change`) — see [`docs/infra-view-state.md`](./infra-view-state.md). `kind` is `hyperbolictree-list`.
 
 ```typescript
 type HyperbolicTreeListViewState = ViewStateBase & {
@@ -386,4 +386,4 @@ type HyperbolicLayoutEdge = {
 };
 ```
 
-See [`src/tree/README.md`](../tree/README.md) for `TreeNode`, `TreeItem` (including `weight`), `TreeDataModel`, `TreeComponent`, and incremental search — all shared with the rest of the tree family.
+See [`src/tree/README.md`](./tree.md) for `TreeNode`, `TreeItem` (including `weight`), `TreeDataModel`, `TreeComponent`, and incremental search — all shared with the rest of the tree family.

package/docs-user/icicle-tree.md

@@ -2,13 +2,13 @@
 
 `<ixfx-icicletree-list>` — an icicle (partition) view over tree data. Each depth is a band; each node a rectangle sized by its `valueAccessor` share of its parent. Clicking a branch zooms so it becomes the visual root, with its ancestors in a breadcrumb strip.
 
-It implements the shared `TreeComponent` interface (see [`src/tree/README.md`](../tree/README.md)). The [sunburst](../sunburst-tree/) is its polar counterpart.
+It implements the shared `TreeComponent` interface (see [`src/tree/README.md`](./tree.md)). The [sunburst](./sunburst-tree.md) is its polar counterpart.
 
 ---
 
 ## View state
 
-Implements the shared view-state API (`getViewState()` / `setViewState()` / `clearPendingViewState()` / `view-state-change`) — see [`docs/infra-view-state.md`](../../docs/infra-view-state.md). `kind` is `icicletree-list`.
+Implements the shared view-state API (`getViewState()` / `setViewState()` / `clearPendingViewState()` / `view-state-change`) — see [`docs/infra-view-state.md`](./infra-view-state.md). `kind` is `icicletree-list`.
 
 | Field | Type | Meaning |
 |---|---|---|

package/docs-user/incr-search.md

@@ -6,7 +6,7 @@ Utilities for incremental (type-ahead) search over data collections or DOM-backe
   popover in `ixfx-grid-list` / `ixfx-vertical-list` / `ixfx-detail-list` /
   `ixfx-data-grid` / `ixfx-tree-list` / `ixfx-miller-list`. Three modes
   (navigate / select / filter), driven by `list.search.*` commands. See
-  [`docs/infra-incremental.md`](../../docs/infra-incremental.md) — start there
+  [`docs/infra-incremental.md`](./infra-incremental.md) — start there
   for anything component-facing.
 - **`createIncrSearch`** — the low-level fuzzy engine (fzf) both the controller
   and the helpers below are built on.

package/docs-user/index.json

@@ -1,7 +1,7 @@
 {
   "name": "@ixfx/components",
-  "version": "0.16.2",
-  "generated": "2026-11-02T19:16:08.207Z",
+  "version": "0.16.4",
+  "generated": "2026-11-02T21:02:52.405Z",
   "components": [
     {
       "name": "ac-text",
@@ -305,14 +305,38 @@
     }
   ],
   "overviews": [
+    {
+      "name": "infra-handle.md",
+      "path": "docs-user/infra-handle.md"
+    },
+    {
+      "name": "infra-incremental.md",
+      "path": "docs-user/infra-incremental.md"
+    },
+    {
+      "name": "infra-theming.md",
+      "path": "docs-user/infra-theming.md"
+    },
     {
       "name": "infra-tickled.md",
       "path": "docs-user/infra-tickled.md"
     },
+    {
+      "name": "infra-view-state.md",
+      "path": "docs-user/infra-view-state.md"
+    },
+    {
+      "name": "list-state.md",
+      "path": "docs-user/list-state.md"
+    },
     {
       "name": "user-catalog.md",
       "path": "docs-user/user-catalog.md"
     },
+    {
+      "name": "user-selection-intents.md",
+      "path": "docs-user/user-selection-intents.md"
+    },
     {
       "name": "user-theming.md",
       "path": "docs-user/user-theming.md"

package/docs-user/infra-handle.md

@@ -0,0 +1,122 @@
+# Drag / resize handles
+
+A **handle** is the grab affordance for moving or resizing an object — a
+splitter grip, a resize edge, a reorder handle. `handleStyles`
+(`src/styles/handle.js`) is the one shared look, so every draggable component
+reads the same and themes through the same variables.
+
+Before this module the library had six unrelated handle idioms (two of them
+near-duplicate 3-dot implementations, two hard-coded Unicode glyphs). Don't add a
+seventh.
+
+---
+
+## Usage
+
+```ts
+import { themeFallbacks } from '../styles/fallbacks.js';
+import { handleStyles } from '../styles/handle.js';
+
+class MyComponent extends LitElement {
+  static styles = [themeFallbacks, handleStyles, css`
+    .hit-zone { /* your resize / drag target */ }
+  `];
+
+  render() {
+    return html`
+      <div class="hit-zone" @pointerdown=${this.#onDown}>
+        <span class="ixfx-handle" data-handle="flat" data-shape="horizontal" part="handle"></span>
+      </div>`;
+  }
+}
+```
+
+Bind pointer handlers to the **hit-zone**, not the handle — the handle is
+`pointer-events: none`.
+
+---
+
+## Two independent axes
+
+| Attribute | Values | Meaning |
+|---|---|---|
+| `data-handle` | `flat` (default) · `dotted` · `dimpled` · `grated` | **texture** — how the mark looks |
+| `data-shape`  | `horizontal` (default) · `vertical` · `spot` | **topology** — a wide bar, a tall bar, or a small centred point handle |
+
+Any texture combines with any shape.
+
+- **flat** — a solid rounded capsule (a bar) or dot (`spot`), filled with
+  `--ixfx-handle-color`. The `ixfx-bottom-drawer` resize handle.
+- **dotted** — marks in the [Lucide *grip*](https://lucide.dev/icons/grip)
+  arrangement: **three in a row** (`horizontal`), **three in a column**
+  (`vertical`), or a **3×3 block** (`spot`). Drawn as one `::before` mark plus
+  `box-shadow` copies, so each mark's corner rounding is `--ixfx-handle-radius`
+  (→ the theme `--radius-l`): **round** normally, **square** under a flat theme
+  (`--radius-l: 0`, e.g. `theme-cyberpunk`). Tinted by `--ixfx-handle-color`. The
+  `ixfx-data-grid` column reorder handle, `ixfx-timeline-track-tab` reorder
+  handle, `ixfx-dock-host` junction handles.
+- **dimpled** — that same layout, but each **bar** mark is pressed in: a lighter
+  copy peeking out above-left and a darker copy below-right (`spot` stays plain —
+  the 3D is imperceptible at that size). Splitter grips (`ixfx-split-layout`,
+  `ixfx-twosplit-layout`).
+- **grated** — fine 45° knurling: parallel ridges, each a **lit edge, the base
+  colour, then a shaded edge**. `spot` is the same hatch cropped square.
+
+`dotted`, `dimpled` and `grated` are texture only — no plate, box or border; the
+gaps are transparent, so the surface behind shows through. The base is
+`--ixfx-handle-color` (`currentColor`); `--ixfx-handle-highlight` /
+`--ixfx-handle-shadow` default to that colour lightened / darkened, so `dimpled`
+stays as prominent as `dotted` and re-tones with the theme.
+
+---
+
+## Active state
+
+The handle goes to `--ixfx-handle-opacity-active` (and, for `flat` / `dotted`,
+`--ixfx-handle-color-active`) when:
+
+- its **immediate parent** (the hit-zone) is `:hover` or `:focus-visible`, or
+- the hit-zone or the handle carries `[data-active]`.
+
+While a drag is live the pointer may leave the hit-zone, so set `[data-active]`
+on the hit-zone yourself for the duration and the handle stays lit.
+
+To suppress the reveal entirely, set `--ixfx-handle-opacity-active` equal to
+`--ixfx-handle-opacity`.
+
+---
+
+## CSS variables
+
+Defaults resolve through `themeFallbacks`. Override on the handle element or any
+ancestor (`:host`, the hit-zone, …).
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `--ixfx-handle-color` | `var(--surface-muted-text)` | `flat` / `dotted` fill |
+| `--ixfx-handle-color-active` | `var(--accent)` | `flat` / `dotted` hover / focus / `[data-active]` |
+| `--ixfx-handle-thickness` | `6px` | cross-axis size of a bar |
+| `--ixfx-handle-length` | `44px` | long-axis size of a bar (`100%` fills) |
+| `--ixfx-handle-spot-size` | `14px` | width = height of a `spot` |
+| `--ixfx-handle-radius` | `var(--radius-l)` | `flat` capsule + `dotted` / `dimpled` mark rounding (0 ⇒ squares) |
+| `--ixfx-handle-opacity` | `0.55` | rest opacity |
+| `--ixfx-handle-opacity-active` | `1` | active opacity |
+| `--ixfx-handle-dot-size` | `4px` | mark size (dotted / dimpled) |
+| `--ixfx-handle-dot-gap` | `length / 6` (bar) · `spot / 3` | mark centre-to-centre step |
+| `--ixfx-handle-tile` | `5px` | knurl period (grated) |
+| `--ixfx-handle-highlight` | `color-mix(currentColor 35%, #fff)` | lit deboss edge (dimpled / grated) |
+| `--ixfx-handle-shadow` | `color-mix(currentColor 60%, #000)` | shaded deboss edge (dimpled / grated) |
+
+---
+
+## Notes & limits
+
+- **Host-as-handle** (`:host(.ixfx-handle)`) is not supported yet — always wrap
+  the class on a child element inside the hit-zone.
+- The handle exposes `part="handle"` (rename per component where a more specific
+  part name already exists, e.g. `part="grip"` / `part="reorder-handle"`).
+- No motion beyond the colour / opacity transition; nothing to gate for reduced
+  motion (the module still drops the transition under
+  `prefers-reduced-motion: reduce`).
+
+See it live: `demo/handle.html` (4 textures × 3 shapes + variable knobs).

package/docs-user/infra-incremental.md

@@ -0,0 +1,154 @@
+# Incremental search
+
+Type-ahead search shared by the list and tree components. One popover, one
+`ReactiveController`, three behaviours ("modes"), triggered by
+`@clinth/ui-commands` commands. Built on the fuzzy engine in
+`src/incr-search/incr-search.ts` (fzf).
+
+Supported today: `ixfx-grid-list`, `ixfx-vertical-list`, `ixfx-detail-list`,
+`ixfx-data-grid`, `ixfx-tree-list`, `ixfx-miller-list`.
+
+---
+
+## The three modes
+
+| Mode | As you type… | Enter | On close |
+|---|---|---|---|
+| **navigate** | the cursor moves to the best match; ↑/↓ cycle between matches | activates the current match, closes | cursor stays |
+| **select** | the selection becomes the set of matching items, live | closes | selection stays |
+| **filter** | items that don't match are hidden | closes (keeps the filter with `stickyFilter`) | filter is removed |
+
+All modes highlight the matched characters (CSS Custom Highlights) where the
+component supports it.
+
+### Conversions
+
+The popover is interactive. While it's open you can, without retyping:
+
+- **switch mode** — buttons for each other enabled mode, or **Tab** /
+  **Shift+Tab** in the input to cycle forward / back (`cycleMode(±1)`). The old
+  mode's effect is undone first (e.g. leaving *filter* un-hides), then the new
+  mode is applied to the current query. Example: start in *filter*, hit
+  **navigate** to stop hiding and just move the cursor.
+- **re-open** — running a search command while the popover is open keeps the
+  query: it switches to that command's mode and refocuses the input with the
+  text selected. `focus()` refocuses without changing mode.
+- **Select matches** — a one-shot button (shown in *navigate* / *filter* when
+  *select* is enabled) that turns the current match set into the selection while
+  staying in the current mode.
+
+### Sticky filter
+
+By default a filter lasts only while the popover is open. Set
+`list.search.stickyFilter = true` (or the `stickyFilter` controller option) so
+that Enter in *filter* mode closes the popover but keeps the filter. A
+"Filtered: …" chip (part `search-kept`) stays in the popover's place, and the
+filter re-applies as items change. Clear it with the chip's ×, Escape on the
+list, or `search.clearFilter()`. Clicking the chip, or running any search
+command, reopens the popover with the kept query. `search.keptFilter` is the
+kept query (or `undefined`).
+
+### Which modes are offered
+
+The effective set is **component capability ∩ the `search-modes` attribute**:
+
+- **capability** — most components offer all three. A component with no
+  selection concept would omit `select`, etc.
+- **`search-modes`** attribute — a space-separated subset of
+  `navigate select filter`. Unset ⇒ the component default. Empty (`search-modes=""`)
+  ⇒ search disabled: no commands registered, no popover.
+
+```html
+<ixfx-grid-list search-modes="navigate filter"></ixfx-grid-list>
+```
+
+---
+
+## Commands
+
+Each component owns a `@clinth/ui-commands` `CommandRegistry` (exposed as
+`el.registry`) and registers one command per enabled mode:
+
+| id | opens |
+|---|---|
+| `list.search.navigate` | popover in navigate mode |
+| `list.search.select` | popover in select mode |
+| `list.search.filter` | popover in filter mode |
+
+There is **no default keybinding** — a consumer binds a key or button:
+
+```ts
+el.registry.invoke('list.search.filter');
+// or via @clinth/ui-commands' InputManager / a data-command button
+```
+
+`ixfx-grouped-item-lister.dispatch('list.search.filter')` fans the command out to
+every sub-list.
+
+---
+
+## Adding search to a new component
+
+1. **Adapter.** Implement `ListSearchAdapter<TItem>` (`src/incr-search/list-search-controller.ts`):
+   `getItems` / `getLabel` / `getKey`, then `focusItem` (navigate),
+   `selectItems` (select), `applyFilter` (filter; `undefined` clears).
+   Optional: `activateItem`, the `highlight*` hooks, `container` (an element
+   whose child-list mutations should re-`refresh()` the item set).
+   - Element-based lists: `createElementListSearchAdapter(this, { itemSelector })`.
+   - Tree-based: `createTreeListSearchAdapter(this, { labelSelector })`.
+
+2. **Controller.** One field:
+
+   ```ts
+   readonly search = new ListSearchController<TItem>(this, {
+     adapter: /* from step 1 */,
+   });
+   ```
+
+3. **Styles + field.** Add `listSearchStyles` to `static styles` and
+   `${this.search.renderField()}` to `render()`, inside a `position: relative`
+   ancestor that is **not** the scroll container (so the popover doesn't scroll
+   away — put `overflow:auto` on an inner element, `position:relative` on `:host`).
+
+4. **Modes + commands.** Keep a `search-modes` reflected property; on connect and
+   whenever it changes:
+
+   ```ts
+   this.search.setModes(/* capability ∩ search-modes */);
+   this.#unregister?.();
+   this.#unregister = registerListSearchCommands(this.registry, this.search);
+   ```
+
+   Own the registry (`createCommandRegistry()`), expose it as `registry`,
+   unregister on disconnect. Route any `dispatch(commandId, args)` to
+   `registry.invoke(commandId, args)`.
+
+5. **Keyboard.** `if (this.search.isOpen) return;` at the top of the host's
+   keydown handler so list navigation doesn't fight the field.
+
+---
+
+## Notes
+
+- **Virtualised lists** (`ixfx-grid-list`, `ixfx-data-grid`) — filter genuinely
+  drops items from layout/virtualisation. Character highlights are best-effort:
+  applied to whatever is in the rendered window (data-grid does no highlighting —
+  a match position indexes into the whole-row text, which spans cells).
+- **Trees** snapshot the whole node set when the popover opens (`getNodes()`
+  returns every node regardless of expansion or an active filter), so refining a
+  query can always re-surface a node. `navigate` expands the match's ancestors;
+  `filter` prunes via `filterPredicate` but does **not** auto-expand collapsed
+  ancestors of a deep match.
+- **Highlights** painted inside a host's shadow root are styled by
+  `listSearchStyles` (keys `incr-search-highlight`, `grid-list-search`,
+  `data-grid-search`; tokens `--search-highlight-bg` / `--search-highlight-color`).
+  A host using another key must add its own rule. Text in the light DOM (the
+  element lists paint onto the item elements) needs a page-level
+  `::highlight(<key>)` rule:
+  `::highlight(vertical-list-search) { background: var(--accent); color: var(--accent-text); }`.
+- Everything is inert when the effective mode set is empty.
+
+## Deprecated
+
+`createElementIncrSearch` and `IncrSearchTreeController` (the external-`<input>`
+filter-only controllers) still work but are superseded by the built-in popover.