@ixfx/components 0.16.2 → 0.16.4

package/docs-user/multicol-list.md

@@ -62,6 +62,12 @@ one column (the first category) once `categories` is assigned.
 
 ---
 
+## Selection intents and partial rows
+
+Gestures in a column (click, Space, Enter, Shift+Arrow, Cmd/Ctrl+A, marquee, the column's incremental search, the "All" row) fire a cancelable `list-select-intent` on the multicol host with `columnId` set; `keys` are that column's item keys. Going back to "All" is a `clear` intent. `preventDefault()` leaves the column alone.
+
+`partialKeys` marks items as partially selected in every column that has an item with that key; `setColumnPartialKeys(columnId, keys)` adds keys for one column only. Selected wins. See [Selection intents, partial rows, unloaded keys](./user-selection-intents.md).
+
 ## Data flow
 
 1. A selection change in column *i* re-queries **every other** column; column *i*'s list

package/docs-user/panel.md

@@ -2,7 +2,7 @@
 
 An collapsible panel component with support for titles, icons, toolbars, and multiple visual variants.
 
-The header chrome is an `ixfx-titlebar` (see [`ixfx-titlebar`](../titlebar/README.md)); the panel adds the collapsible content area beneath it.
+The header chrome is an `ixfx-titlebar` (see [`ixfx-titlebar`](./titlebar.md)); the panel adds the collapsible content area beneath it.
 
 ```html
 <ixfx-panel title="Settings">
@@ -341,5 +341,5 @@ import type { TitlebarOrientation, TitlebarVariant, TitlebarToggleInteraction, T
 
 ## See also
 
-- [`ixfx-titlebar`](../titlebar/README.md) — Standalone titlebar chrome composed by this panel
-- [`ixfx-icon`](../icons/README.md) — Icon component used by panel
+- [`ixfx-titlebar`](./titlebar.md) — Standalone titlebar chrome composed by this panel
+- [`ixfx-icon`](./icons.md) — Icon component used by panel

package/docs-user/select-horiz.md

@@ -98,7 +98,7 @@ Click an item (or Tab to the element) to focus it first — a focus ring appears
 | `--select-horiz-spacer-width` | `10%` | Width of the leading/trailing spacer that lets the first/last item scroll to center |
 | `--scroll-fade-width` | `30px` | Width of the edge fade and the inner horizontal padding (shared with `scrollFadeStyles`) |
 
-Items are styled with the standard `--item-*` theming tokens (see [`docs/user-theming.md`](../../docs/user-theming.md)):
+Items are styled with the standard `--item-*` theming tokens (see [`docs/user-theming.md`](./user-theming.md)):
 
 | Property | State |
 |---|---|

package/docs-user/split-layout.md

@@ -132,7 +132,7 @@ Nested `<ixfx-split-layout>` elements create sub-groups:
 | `--split-collapsed-size` | `0px` | Size of collapsed panels |
 | `--split-snap` | `24px` | Snap/hysteresis distance |
 The gutter grip is the shared `dimpled` handle — theme it with the
-`--ixfx-handle-*` variables (see [docs/infra-handle.md](../../docs/infra-handle.md)).
+`--ixfx-handle-*` variables (see [docs/infra-handle.md](./infra-handle.md)).
 
 ---
 
@@ -202,7 +202,7 @@ layouts, resizing several splits with one gesture.
 `getViewState()` / `setViewState()` snapshot and restore the size and
 collapse of each direct child that has an `id`, as plain JSON (`kind:
 'split-layout'`). The component never persists anything itself — see
-[docs/infra-view-state.md](../../docs/infra-view-state.md) and
+[docs/infra-view-state.md](./infra-view-state.md) and
 `bindViewState()`.
 
 ```ts

package/docs-user/sunburst-tree.md

@@ -2,7 +2,7 @@
 
 `<ixfx-sunbursttree-list>` — a zoomable sunburst over weighted tree data. The zoom node is the centre disc; each ring outward is one generation, and each arc's angle is its share of its parent's value. Every change — data arriving, a different weighting, a zoom — animates from what's on screen to the new layout.
 
-It implements the shared `TreeComponent` interface (see [`src/tree/README.md`](../tree/README.md)), so `TreeDataModel`, `IncrSearchTreeController`, and `TreeComponent`-typed code work unmodified. Geometrically it is a polar [icicle](../icicle-tree/), and shares its API shape.
+It implements the shared `TreeComponent` interface (see [`src/tree/README.md`](./tree.md)), so `TreeDataModel`, `IncrSearchTreeController`, and `TreeComponent`-typed code work unmodified. Geometrically it is a polar [icicle](./icicle-tree.md), and shares its API shape.
 
 ---
 
@@ -123,7 +123,7 @@ All of it is computed in CSS from per-arc custom properties, so the palette is t
 | `animationDuration` (`animation-duration`) | `number` | `600` | Transition length in ms; `0` snaps. Respects `prefers-reduced-motion` |
 | `filterPredicate` | `TreeFilterPredicate \| undefined` | `undefined` | Non-matching arcs (with no matching descendant) are dimmed |
 | `disableKeyboardNavigation` (`disable-keyboard-navigation`) | `boolean` | `false` | Turn off keyboard handling |
-| `searchModes` (`search-modes`) | `string \| undefined` | `undefined` | Subset of `navigate select filter` — see [`docs/infra-incremental.md`](../../docs/infra-incremental.md) |
+| `searchModes` (`search-modes`) | `string \| undefined` | `undefined` | Subset of `navigate select filter` — see [`docs/infra-incremental.md`](./infra-incremental.md) |
 | `exclusivity` | `TreeExclusivity` | `'none'` | Accepted for interface compatibility, ignored |
 | `selectedNode` / `selectedNodes` | | | Same contract as `ixfx-tree-list` |
 | `focusedNode` | `TreeNode \| undefined` (read-only) | `undefined` | Current zoom node; `undefined` when showing the full tree |
@@ -174,7 +174,7 @@ All events **bubble** and are **composed**. `depth` counts from the root's child
 
 ## 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 `sunbursttree-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 `sunbursttree-list`.
 
 | Field | Type | Meaning |
 |---|---|---|

package/docs-user/titlebar.md

@@ -97,5 +97,5 @@ import type { TitlebarOrientation, TitlebarVariant, TitlebarToggleInteraction, T
 
 ## See also
 
-- [`ixfx-panel`](../panel/README.md) — Collapsible panel that composes this titlebar
-- [`ixfx-icon`](../icons/README.md) — Icon component used by the titlebar
+- [`ixfx-panel`](./panel.md) — Collapsible panel that composes this titlebar
+- [`ixfx-icon`](./icons.md) — Icon component used by the titlebar

package/docs-user/tree.md

@@ -424,6 +424,12 @@ el.addEventListener('select', ({ detail }) => {
 
 ---
 
+### Selection intents and partial rows (`ixfx-tree-list`)
+
+A cancelable `list-select-intent` fires before a click, Space, Enter, Shift+Arrow, Ctrl/Cmd+A, a checkbox or `selectAll()` changes the selection (in every interaction mode, including `manual`); `preventDefault()` means "I'll apply it". Expansion and the cursor still behave normally. Checking a branch in `checked` mode is one `toggle` intent with `descendants: true` and `checked` (the state it is being set to): `keys` lists the loaded selectable nodes under it, but the caller can express it as a rule ("this folder and everything under it"). `list-select` `{ selectedKeys, previousKeys, previous }` fires next to `select`.
+
+`partialKeys` marks nodes as partially selected: in `checked` mode the checkbox is indeterminate if either the loaded descendants or `partialKeys` say so (selected wins over partial); otherwise `data-partial` and an accessible description. Incremental search in `select` mode fires a `match` intent first (see below). See [Selection intents, partial rows, unloaded keys](./user-selection-intents.md).
+
 ## Expansion
 
 ### Programmatic expansion
@@ -460,7 +466,7 @@ Notes:
 ## View state (`ixfx-tree-list`)
 
 Snapshot and restore selection, expansion, keyboard cursor and scroll
-separately from the data — see [`docs/infra-view-state.md`](../../docs/infra-view-state.md)
+separately from the data — see [`docs/infra-view-state.md`](./infra-view-state.md)
 for the shared contract. `kind: 'tree-list'`; fields `selected`, `expanded`,
 `focus`, `scroll`, all keyed by `item.key`.
 
@@ -695,7 +701,7 @@ el.registry.invoke('list.search.navigate'); // or .select / .filter
 ```
 
 Limit the offered modes with the `search-modes` attribute
-(`search-modes="navigate filter"`). Full model: [`docs/infra-incremental.md`](../../docs/infra-incremental.md).
+(`search-modes="navigate filter"`). Full model: [`docs/infra-incremental.md`](./infra-incremental.md).
 
 ### Deprecated: `IncrSearchTreeController`
 

package/docs-user/treemap.md

@@ -1,12 +1,12 @@
 # Treemap
 
-`<ixfx-treemap-list>` — a nested-area (treemap) view over tree data. The zoom root fills the viewport; each node's rectangle is subdivided among its children by `valueAccessor` share. Clicking a branch zooms into it, and ancestors collapse into a breadcrumb strip. It implements the shared `TreeComponent` interface (see [`src/tree/README.md`](../tree/README.md)). See the class docs in `treemap-list.ts` for properties and events.
+`<ixfx-treemap-list>` — a nested-area (treemap) view over tree data. The zoom root fills the viewport; each node's rectangle is subdivided among its children by `valueAccessor` share. Clicking a branch zooms into it, and ancestors collapse into a breadcrumb strip. It implements the shared `TreeComponent` interface (see [`src/tree/README.md`](./tree.md)). See the class docs in `treemap-list.ts` for properties and events.
 
 ---
 
 ## 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 `treemap-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 `treemap-list`.
 
 ```typescript
 type TreemapListViewState = ViewStateBase & {

package/docs-user/twosplit-layout.md

@@ -39,7 +39,7 @@ A Lit web component that lays out two elements within a container with a split b
 
 When `--handle-size` exceeds `5px` the split bar shows the shared `dimpled` grip —
 theme it with the `--ixfx-handle-*` variables (see
-[docs/infra-handle.md](../../docs/infra-handle.md)).
+[docs/infra-handle.md](./infra-handle.md)).
 
 ### Events
 
@@ -53,7 +53,7 @@ theme it with the `--ixfx-handle-*` variables (see
 `getViewState()` / `setViewState()` snapshot and restore both sides as plain
 JSON (`kind: 'twosplit-layout'`), keyed by slot name. The component never
 persists anything itself — see
-[docs/infra-view-state.md](../../docs/infra-view-state.md) and `bindViewState()`.
+[docs/infra-view-state.md](./infra-view-state.md) and `bindViewState()`.
 
 ```ts
 split.getViewState();
@@ -211,7 +211,7 @@ ixfx-twosplit-layout {
 When `--handle-size` is greater than `5px`, a grip appears in the centre of the
 split bar — the shared `dimpled` handle (a debossed square grid), oriented along
 the split. Theme it with the `--ixfx-handle-*` variables; see
-[docs/infra-handle.md](../../docs/infra-handle.md).
+[docs/infra-handle.md](./infra-handle.md).
 
 ```css
 ixfx-twosplit-layout {

package/docs-user/user-selection-intents.md

@@ -0,0 +1,86 @@
+# Selection intents, partial rows, unloaded keys
+
+Shared by every list-like component: `ixfx-vertical-list`, `ixfx-flat-list`, `ixfx-detail-list`, `ixfx-grid-list`, `ixfx-data-grid`, `ixfx-miller-list`, `ixfx-tree-list` and `ixfx-multicol-list`. For a caller that owns the selection itself (e.g. a selection that is an expression or a set of rules, not a key set), so a list shows what it is given and reports what the user did.
+
+---
+
+## `list-select-intent` (cancelable)
+
+Fired **before** a component changes its selection, in every interaction mode (including `manual`, where nothing is selected by default). `preventDefault()` means "I apply this myself": the component changes nothing. Without it, behaviour is unchanged.
+
+```ts
+type ListSelectIntentDetail = {
+  readonly kind:
+    | `replace`   // plain click / Enter: select only `keys`
+    | `toggle`    // Cmd/Ctrl-click, Space, sticky tap, checkbox: flip `keys`
+    | `extend`    // Shift-click / Shift+Arrow: range from `anchorKey` to `targetKey`
+    | `all`       // Cmd/Ctrl+A or selectAll(): "everything in this view", not a key list
+    | `marquee`   // drag-select: `keys` covered; `mode` says how they combine with the selection
+    | `match`     // incremental search in `select` mode / "Select matches"
+    | `clear`;    // Escape / click on empty space / back to "All" in a multicol column
+  readonly keys: readonly string[];  // keys directly affected (empty for `all` / `clear`)
+  readonly anchorKey?: string;       // `extend`
+  readonly targetKey?: string;       // `extend`
+  readonly mode?: `replace` | `add` | `toggle`;  // `marquee`
+  readonly additive?: boolean;       // `marquee`: `mode` is not `replace`
+  readonly query?: string;           // `match`: the search text
+  readonly groupKey?: string | null; // `all`: the group the select-all is confined to
+  readonly descendants?: boolean;    // `toggle` on a tree branch checkbox: node + loaded descendants
+  readonly checked?: boolean;        // ...and the state it is being set to
+  readonly columnId?: string;        // multicol-list: the column
+  readonly source: `pointer` | `keyboard` | `touch` | `api`;
+};
+```
+
+```ts
+list.addEventListener('list-select-intent', (e) => {
+  e.preventDefault();
+  const { kind, keys, anchorKey, targetKey } = e.detail;
+  // ...compute the new selection from your own model, then:
+  list.selectKeys(newKeys);
+});
+```
+
+- **`extend` gives endpoints.** `keys` also holds the range as loaded here, but rows in between may not be loaded (virtualised / progressive listings): compute the range from your own order using `anchorKey` / `targetKey`.
+- **`all` is a meaning, not a list.** Turn it into your own scope rule instead of enumerating keys. In grouped lists with `cross-group-selection` off, select-all is confined to one group (the anchor's group, else the cursor's): `groupKey` names it, so a caller that takes over does the same. It is absent when select-all is not confined.
+- **`marquee` `mode`.** `replace`: the selection becomes the covered `keys` (plain drag). `add`: covered keys are added (Shift-drag). `toggle`: each covered key flips, so a Cmd/Ctrl-drag can deselect. `additive` is just `mode !== 'replace'`; use `mode`.
+- **`match` is a search.** Incremental search in `select` mode (typing, and `selectMatches()` / the "Select matches" button) reports `{ kind: 'match', query, keys }` — `keys` are the current matches, a convenience; `query` is what to keep as a live rule. Cancelling it leaves the selection untouched while the popover keeps showing the matches. Source is `keyboard` while typing, `pointer` for the button, `api` for `selectMatches()`.
+- **Tree branch checkboxes.** In `ixfx-tree-list` `checked` mode, checking a branch is one `toggle` with `descendants: true` and `checked` (the state the branch is being set to); `keys` lists the loaded selectable nodes under it, but express it as a rule.
+- **Cursor and anchor keep moving when cancelled.** They are view state, not selection; the next `extend` still has its `anchorKey`.
+- **Who fires it.** Gestures (click, Space, Enter, double-click, checkbox, Shift+Arrow, Cmd/Ctrl+A, marquee, Escape, click on empty space) and `selectAll()`. The imperative `select()` / `selectKeys()` / `clearSelection()` family never fires it, so applying your decision through them cannot re-enter your handler.
+- **`manual` mode.** The intent is reported and nothing else happens, so the caller never re-implements modifier handling. (`ixfx-data-grid` keeps Space toggling in `manual`, as before.)
+- **Not covered.** Right-click auto-select and the drag-origin auto-select of native drag-out still apply directly. `ixfx-miller-list` reports click / checkbox / Shift+Arrow; it has no select-all, and Escape navigates rather than clears.
+
+## `list-select` (consistent)
+
+Every list-like component fires `list-select` with the same key-based detail:
+
+```ts
+{ selectedKeys: ReadonlySet<string>, previousKeys: ReadonlySet<string> /* , plus component-specific extras */ }
+```
+
+Vertical-list, detail-list and grid-list keep their element-based `selected` / `previous`; data-grid keeps `datagrid-select` (and adds `list-select` with `previous` as keys); miller keeps `select` (and adds `list-select`). One adapter can read any of them through `selectedKeys` / `previousKeys`. Miller now also fires for Cmd-click and Shift-click selection changes.
+
+## `partialKeys`
+
+A row whose resource is only partly selected (a time range of an audio file, a region of an image):
+
+```ts
+list.partialKeys = ['k1', 'k2'];   // ReadonlySet<string> getter; replace-on-set
+```
+
+- Independent of `selectedKeys`; a key in both counts as selected.
+- Light-DOM lists (vertical, detail): `data-partial` on the row; grid-list cell and data-grid row: `data-partial` plus `.partial` (`part="item partial"` on grid-list); miller: `.partial`.
+- Accessibility: in `checked` mode the checkbox is indeterminate with `aria-checked="mixed"`; otherwise the row gets `aria-description="Partially selected"` (an author-set `aria-description` is never overwritten).
+- Style hooks: `--item-bg-partial`, `--item-border-partial` (`--grid-list-partial-outline` on grid-list).
+- `ixfx-flat-list` forwards `partialKeys` to its inner list. In `checked` mode (tree-list and miller-list alike) indeterminate comes from loaded descendants or `partialKeys`, whichever says so.
+
+## Selected keys that aren't loaded yet
+
+`selectKeys()` on vertical-list, flat-list (`flat.list`), detail-list and grid-list keeps keys with no row yet as *pending* and selects them when the row appears (`selectedKeys` lists only present rows). `addSelectedKeys()` does the same; `removeSelectedKeys()` also drops pending keys. Any explicit gesture-driven selection change supersedes pending keys, in single-select only the last unresolved key is kept, and pending keys are capped (2000, oldest dropped). `ixfx-data-grid` already behaved this way. A key that is selected and then leaves the data is reselected if it returns (view-state pending).
+
+## Per-component notes
+
+- **`ixfx-tree-list`** — also fires `list-select` next to `select`. `partialKeys` combines with the checkbox state derived from loaded descendants: indeterminate if either says so; selected wins.
+- **`ixfx-multicol-list`** — the intent is re-fired on the host with `columnId`; the "All" row is a `clear`. `partialKeys` applies to every column with a matching item key; `setColumnPartialKeys(columnId, keys)` targets one column.
+- **`ixfx-miller-list`** — same contract as the tree: a branch checkbox is one `toggle` with `descendants: true` and `checked`, `keys` = the node and its loaded descendants; `partialKeys` combines with the derived checkbox state (indeterminate if either says so; selected wins).

package/docs-user/user-theming.md

@@ -482,7 +482,7 @@ If you're upgrading from previous versions:
 
 For implementation details, see:
 - [`docs/infra-theming.md`](infra-theming.md) - Internal theming specification
-- [`docs-user/icons.md`](/docs-user/icons.md) - Full icon registry reference
+- [`docs-user/icons.md`](./icons.md) - Full icon registry reference
 - [`demo/loader.html?demo=icons`](/demo/loader.html?demo=icons) - Interactive icons demo
 - [`src/style.css`] - Base theme definitions
 - [`demo/shared/`] - Example theme implementations

package/docs-user/vertical-list.md

@@ -537,7 +537,7 @@ type ListItemClickDetail = { readonly item: Element };
 ### Caller-owned selection: `list-select-intent` and `partialKeys`
 
 `list-select-intent` is fired before any gesture changes the selection (in every `interactionMode`, including `manual`); `preventDefault()` means "I'll apply it". `partialKeys` marks rows as partially selected (`data-partial`, indeterminate checkbox in `checked` mode). Both are shared across the list-like components.
-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.
 
 ### Usage example
 
@@ -620,7 +620,7 @@ The element must be focused (click it or tab to it) before keyboard navigation w
 
 ## Incremental search
 
-A built-in type-ahead popover with three modes — **navigate** (cursor jumps to the best match, ↑/↓ cycle), **select** (matches become the selection), **filter** (non-matches hidden). See [`docs/infra-incremental.md`](../../docs/infra-incremental.md) for the full model, conversions between modes, and the `search-modes` attribute.
+A built-in type-ahead popover with three modes — **navigate** (cursor jumps to the best match, ↑/↓ cycle), **select** (matches become the selection), **filter** (non-matches hidden). See [`docs/infra-incremental.md`](./infra-incremental.md) for the full model, conversions between modes, and the `search-modes` attribute.
 
 There is **no default shortcut**. Open it by invoking one of the commands on `list.registry`:
 
@@ -701,7 +701,7 @@ The event is cancelable: call `preventDefault()` to suppress the browser's nativ
 
 Rename is **opt-in**: set `editValidator = (value, key) => boolean` first. Without it `beginEdit` returns `false` and rows stay plain text. The validator runs on commit; returning `false` rejects the text and the edit ends as a cancel.
 
-`list.beginEdit(key)` swaps an [`ixfx-editable-label`](../editable-label/README.md) into the row, selects its text and focuses it. It returns `false` if there is no `editValidator`, or the row is unknown or not rendered.
+`list.beginEdit(key)` swaps an [`ixfx-editable-label`](./editable-label.md) into the row, selects its text and focuses it. It returns `false` if there is no `editValidator`, or the row is unknown or not rendered.
 
 The editor replaces the row's `[data-edit-label]` element, or the whole row if there is none. Mark the text element in rows that carry icons or badges, and set `data-edit-value` there if the editable text differs from its content.
 

package/llms.txt

@@ -73,6 +73,12 @@ import '@ixfx/components/data-grid';
 - [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
+- [infra-handle.md](docs-user/infra-handle.md)
+- [infra-incremental.md](docs-user/infra-incremental.md)
+- [infra-theming.md](docs-user/infra-theming.md)
 - [infra-tickled.md](docs-user/infra-tickled.md)
+- [infra-view-state.md](docs-user/infra-view-state.md)
+- [list-state.md](docs-user/list-state.md)
 - [user-catalog.md](docs-user/user-catalog.md)
+- [user-selection-intents.md](docs-user/user-selection-intents.md)
 - [user-theming.md](docs-user/user-theming.md)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ixfx/components",
   "type": "module",
-  "version": "0.16.2",
+  "version": "0.16.4",
   "packageManager": "pnpm@10.0.0",
   "description": "Web components for ixfx — Lit-based UI toolkit",
   "author": "Clint Heyer",