@ixfx/components 0.16.1 → 0.16.3

package/dist/vertical-list.js

@@ -1,2 +1,2 @@
-import { t as VerticalListElement } from "./vertical-list-DyKPKGxK.js";
+import { t as VerticalListElement } from "./vertical-list-o5hfqH87.js";
 export { VerticalListElement };

package/docs-user/README.md

@@ -69,4 +69,5 @@ This directory contains documentation for each component and some architectural
 
 - [infra-tickled.md](infra-tickled.md)
 - [user-catalog.md](user-catalog.md)
+- [user-selection-intents.md](user-selection-intents.md)
 - [user-theming.md](user-theming.md)

package/docs-user/data-grid.md

@@ -222,9 +222,16 @@ grid.tickleRow('r7');              // move the row cursor + scroll it into view
 grid.tickledKey;                   // row key under the cursor, or undefined
 ```
 
-The setter fires `datagrid-select` `{ selectedKeys, previous }` only when the
-selection actually changes. Selected rows that leave `rows` are deselected
-silently, and reselected if they return. See [View state](#view-state).
+The setter fires `datagrid-select` `{ selectedKeys, previous }` (and `list-select`
+`{ selectedKeys, previousKeys, previous }`, the name the other list components use)
+only when the selection actually changes. A cancelable `list-select-intent` fires
+before every selection gesture, and `partialKeys` marks partially selected rows
+(`data-partial`, indeterminate checkbox in `checked` mode).
+See [Selection intents, partial rows, unloaded keys](./user-selection-intents.md): `list-select-intent`, `partialKeys`, and keys that arrive later.
+
+Selected rows that leave `rows` are deselected silently, and reselected if they
+return. See [View state](#view-state). In `checked` mode the row checkbox toggles
+the row.
 
 ---
 

package/docs-user/detail-list.md

@@ -310,7 +310,7 @@ the Element API is unchanged, the key API is additive. Object items built from
 `items` / a provider get their key stamped automatically from `keyProperty`.
 
 ```typescript
-list.selectKeys(['row-3', 'row-7']);   // replace selection; unknown keys ignored
+list.selectKeys(['row-3', 'row-7']);   // replace selection; keys with no row yet apply when the row appears
 list.addSelectedKeys(['row-9']);       // multi-select modes only
 list.removeSelectedKeys(['row-3']);
 list.selectedKeys;                     // ReadonlySet<string>

package/docs-user/grid-list.md

@@ -183,7 +183,7 @@ See `docs-user/grid-list.md`.
 item, drive selection by key instead — additive, the Element API is unchanged.
 
 ```typescript
-grid.selectKeys(['a', 'c']);        // replace; unknown keys ignored
+grid.selectKeys(['a', 'c']);        // replace; keys with no cell yet apply when the cell appears
 grid.addSelectedKeys(['b']);        // multi-select modes only
 grid.removeSelectedKeys(['a']);
 grid.selectedKeys;                  // ReadonlySet<string>
@@ -193,6 +193,9 @@ 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](./user-selection-intents.md): `list-select-intent`, `partialKeys`, and keys that arrive later.
+
 Restore across a reload:
 
 ```typescript

package/docs-user/index.json

@@ -1,7 +1,7 @@
 {
   "name": "@ixfx/components",
-  "version": "0.16.1",
-  "generated": "2026-10-26T15:36:19.925Z",
+  "version": "0.16.3",
+  "generated": "2026-11-02T20:40:41.501Z",
   "components": [
     {
       "name": "ac-text",
@@ -313,6 +313,10 @@
       "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/llms.txt

@@ -75,4 +75,5 @@ import '@ixfx/components/data-grid';
 ## Overviews
 - [infra-tickled.md](docs-user/infra-tickled.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/docs-user/menu.md

@@ -6,7 +6,7 @@ A custom menu system built on native HTML popovers with keyboard navigation, tic
 
 | Component | Description |
 |------------|-------------|
-| `ixfx-menu-bar` | Horizontal container for menu triggers; handles arrow-key navigation between top-level menus |
+| `ixfx-menu-bar` | Horizontal container for menu triggers; handles arrow-key navigation between top-level menus; while a menu is open, hovering another top-level trigger switches to its menu |
 | `ixfx-menu-trigger` | Button or slot that opens a menu popover. Modes: `trigger` (button), `dropdown` (slot-only), `context` (right-click) |
 | `ixfx-menu-container` | The popover panel holding menu items; manages keyboard focus and tickled state |
 | `ixfx-menu-item` | Basic menu item that dispatches a `command` event |
@@ -254,6 +254,16 @@ The trigger button and menu bar additionally expose a couple of underscore-prefi
 | `--_trigger-hover-bg` | `var(--surface-4)` | Trigger button hover background |
 | `--_trigger-hover-opacity` | `1` | Trigger button hover opacity |
 
+Public layout variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--ixfx-button-padding` | `var(--space-s) var(--space-m)` | Padding of the default trigger button |
+| `--menu-max-height` | `min(60vh, 400px)` | Max height of a menu panel; taller menus scroll, with an edge fade |
+| `--menu-popup-offset` | `var(--space-xs)` | Distance between a trigger and its menu popup |
+| `--menu-bar-gap` | `var(--space-xs)` | Gap between top-level triggers in `ixfx-menu-bar` |
+| `--menu-bar-padding` | `var(--space-xs)` | Padding around the items in `ixfx-menu-bar` |
+
 The popup surface uses these from `popupSurfaceStyles`:
 
 | Variable | Description |

package/docs-user/miller.md

@@ -149,6 +149,10 @@ The `change` event is fired on the component after every checkbox toggle.
 
 ---
 
+## Selection intents and partial rows
+
+`ixfx-miller-list` fires a cancelable `list-select-intent` before a click (all interaction modes, including `manual`), a checkbox toggle or a Shift+Arrow range changes the selection; `preventDefault()` means "I'll apply it". Navigation (opening the node's column) still happens. It also fires `list-select` `{ selectedKeys, previousKeys, previous }` next to `select`, and supports `partialKeys` (indeterminate checkbox in `checked` mode, `.partial` otherwise; selected wins; in `checked` mode it overrides the state derived from loaded descendants). In `checked` mode the checkbox intent is for the node only: the cascade to loaded descendants is the caller's call. See [Selection intents, partial rows, unloaded keys](./user-selection-intents.md).
+
 ## Selection API
 
 ```typescript

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/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/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

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. In `checked` mode a miller checkbox intent is for the node only; the descendant cascade is the caller's decision.
+
+## `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. Miller's `checked` mode still derives indeterminate from loaded descendants; `partialKeys` overrides that for the keys you set.
+
+## 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`** — see above; `checked` mode checkbox intents are for the node only.

package/docs-user/vertical-list.md

@@ -441,7 +441,7 @@ unchanged — the key API is additive.
 ```
 
 ```typescript
-list.selectKeys(['a', 'c']);          // replace selection; unknown keys ignored
+list.selectKeys(['a', 'c']);          // replace selection; keys with no row yet apply when the row appears
 list.addSelectedKeys(['b']);          // multi-select modes only
 list.removeSelectedKeys(['a']);
 list.selectedKeys;                    // ReadonlySet<string>, e.g. Set { 'b', 'c' }
@@ -512,6 +512,7 @@ All events **bubble** and are **composed** (they cross shadow-DOM boundaries).
 | Event | Detail type | When fired |
 |---|---|---|
 | `list-select` | `ListSelectDetail` | Selection changes by any means |
+| `list-select-intent` | `ListSelectIntentDetail` | Cancelable; a gesture is about to change the selection (see below) |
 | `list-tickle` | `ListTickleDetail` | An item enters cursor focus (hover or keyboard navigation) |
 | `list-activate` | `ListActivateDetail` | User explicitly activates an item: Enter key or double-click |
 | `list-item-click` | `ListItemClickDetail` | Raw click or Enter on any item |
@@ -524,6 +525,8 @@ All events **bubble** and are **composed** (they cross shadow-DOM boundaries).
 type ListSelectDetail = {
   readonly selected: ReadonlySet<Element>;  // Current full selection
   readonly previous: ReadonlySet<Element>;  // Selection before this change
+  readonly selectedKeys: ReadonlySet<string>;
+  readonly previousKeys: ReadonlySet<string>;
 };
 
 type ListTickleDetail   = { readonly item: Element };
@@ -531,6 +534,11 @@ type ListActivateDetail = { readonly item: Element };
 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](./user-selection-intents.md): `list-select-intent`, `partialKeys`, and keys that arrive later.
+
 ### Usage example
 
 ```typescript

package/llms.txt

@@ -75,4 +75,5 @@ import '@ixfx/components/data-grid';
 ## Overviews
 - [infra-tickled.md](docs-user/infra-tickled.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.1",
+  "version": "0.16.3",
   "packageManager": "pnpm@10.0.0",
   "description": "Web components for ixfx — Lit-based UI toolkit",
   "author": "Clint Heyer",

package/dist/list-selection-types-PjKdhF-a.d.ts

@@ -1,45 +0,0 @@
-//#region src/interaction/list-selection-types.d.ts
-type ListSelectionMode = `none` | `single` | `multiple`;
-/**
- * Controls how pointer and keyboard gestures map to selection changes.
- *
- * - `implicit`  — click always replaces selection (no modifier support)
- * - `standard`  — click replaces; Ctrl/Cmd+click toggles; Shift+click range-selects (multiple only)
- * - `manual`    — no auto-selection; drive state via select()/deselect()/clearSelection()
- * - `checked`   — every click toggles; implies multiple selection regardless of selectionMode
- * - `sticky`    — every tap/click toggles (no checkbox column); implies multiple selection, for touchscreens
- * - `vscode`    — like standard for clicks; Shift+Arrow extends range from the keyboard anchor
- *
- * Switching interactionMode clears the current selection.
- */
-type ListInteractionMode = `implicit` | `standard` | `manual` | `checked` | `sticky` | `vscode`;
-type ListSelectDetail = {
-  readonly selected: ReadonlySet<Element>;
-  readonly previous: ReadonlySet<Element>;
-  /**
-   * The selection as stable key strings (`data-key` / `data-value`). Empty
-   * when items carry no key. Additive to `selected`.
-   */
-  readonly selectedKeys: ReadonlySet<string>;
-};
-type ListTickleDetail = {
-  readonly item: Element;
-};
-type ListActivateDetail = {
-  readonly item: Element;
-};
-type ListItemClickDetail = {
-  readonly item: Element;
-};
-type ListSelectEvent = CustomEvent<ListSelectDetail>;
-type ListTickleEvent = CustomEvent<ListTickleDetail>;
-type ListActivateEvent = CustomEvent<ListActivateDetail>;
-type ListItemClickEvent = CustomEvent<ListItemClickDetail>;
-interface ListElementEventMap {
-  'list-select': ListSelectEvent;
-  'list-tickle': ListTickleEvent;
-  'list-activate': ListActivateEvent;
-  'list-item-click': ListItemClickEvent;
-}
-//#endregion
-export { ListItemClickDetail as a, ListSelectEvent as c, ListTickleEvent as d, ListInteractionMode as i, ListSelectionMode as l, ListActivateEvent as n, ListItemClickEvent as o, ListElementEventMap as r, ListSelectDetail as s, ListActivateDetail as t, ListTickleDetail as u };