@ixfx/components 0.16.0 → 0.16.2

package/dist/{vertical-list-1V1Vg2O5.js → vertical-list-qMRIxZIT.js}

@@ -1,13 +1,13 @@
 import { t as TickledController } from "./tickled-controller-D-HZymaZ.js";
 import { t as themeFallbacks } from "./fallbacks-DQ_5OsmR.js";
 import { n as safeCustomElement, t as __decorate } from "./decorate-VRK8rslU.js";
-import { c as createElementListSearchAdapter, i as ListSearchController, n as listSearchStyles, o as registerListSearchCommands, r as LIST_SEARCH_MODES, u as keyForElement } from "./incr-search-JIhwB49y.js";
+import { c as createElementListSearchAdapter, d as keysOfElements, i as ListSearchController, n as listSearchStyles, o as registerListSearchCommands, r as LIST_SEARCH_MODES, u as keyForElement } from "./incr-search-2YaxUUA9.js";
 import { i as animateListItemOut, r as animateListItemIn, t as ListNativeDragController } from "./list-native-drag-controller-CcXoS0YX.js";
-import { r as ListDragSelectController, t as ListSelectionController } from "./list-selection-controller-5L0Nj9tR.js";
+import { i as ListDragSelectController, n as gestureOf, t as ListSelectionController } from "./list-selection-controller-CJDdjH7E.js";
 import { l as keysToArray } from "./pending-BGidHppL.js";
-import { a as restoreElementScroll, n as anchorFromRow, o as scrollToOffset, r as captureElementScroll, t as ViewStateController } from "./view-state-controller-BdyXWUUM.js";
+import { a as isPartialKey, i as applyPartialAttributes, n as appearanceColor, o as sameKeySet, t as appearanceAbsent } from "./item-appearance-Bl6rMIID.js";
 import { t as scrollFadeStyles } from "./scroll-fade-Xx28D7mH.js";
-import { n as appearanceColor, t as appearanceAbsent } from "./item-appearance-BjcMyauw.js";
+import { a as restoreElementScroll, n as anchorFromRow, o as scrollToOffset, r as captureElementScroll, t as ViewStateController } from "./view-state-controller-BdyXWUUM.js";
 import "./editable-label.js";
 import { LitElement, css, html, render } from "lit";
 import { property } from "lit/decorators.js";
@@ -153,13 +153,15 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 				interactionMode: this.interactionMode
 			}),
 			getKey: keyForElement,
+			onIntent: (intent) => this._dispatchCancelable(`list-select-intent`, intent) === false,
 			onChange: (selected, previous) => {
 				this._syncItemStates();
 				this.#viewState.notify();
 				this._dispatch(`list-select`, {
 					selected,
 					previous,
-					selectedKeys: this.selection.selectedKeys
+					selectedKeys: this.selection.selectedKeys,
+					previousKeys: keysOfElements(previous)
 				});
 			}
 		});
@@ -245,6 +247,7 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 			getAllItems: () => this.#selectionOrder(),
 			observeContainer: false
 		}) });
+		this.#partialKeys = /* @__PURE__ */ new Set();
 		this.#onScroll = () => {
 			if (!this.#viewState.pendingScroll) this.#viewState.notify();
 			if (this.#scrollRaf !== 0) return;
@@ -275,7 +278,7 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 			if ((e.ctrlKey || e.metaKey) && e.key === `a`) {
 				if (this.selection.canSelectAll()) {
 					e.preventDefault();
-					this.selection.selectAll();
+					this.selection.selectAll(`keyboard`);
 				}
 				return;
 			}
@@ -284,18 +287,18 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 					e.preventDefault();
 					this.tickled.handleKeyboardNavigation(`next`);
 					this.#revealCursor();
-					if (e.shiftKey && this.interactionMode === `vscode`) {
+					if (e.shiftKey && (this.interactionMode === `vscode` || this.interactionMode === `manual`)) {
 						const cur = this.tickled.tickledId;
-						if (cur) this.selection.rangeTo(cur);
+						if (cur) this.selection.handleExtend(cur);
 					}
 					break;
 				case `ArrowUp`:
 					e.preventDefault();
 					this.tickled.handleKeyboardNavigation(`previous`);
 					this.#revealCursor();
-					if (e.shiftKey && this.interactionMode === `vscode`) {
+					if (e.shiftKey && (this.interactionMode === `vscode` || this.interactionMode === `manual`)) {
 						const cur = this.tickled.tickledId;
-						if (cur) this.selection.rangeTo(cur);
+						if (cur) this.selection.handleExtend(cur);
 					}
 					break;
 				case `Home`:
@@ -321,7 +324,7 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 					if (id) {
 						e.preventDefault();
 						this._dispatch(`list-item-click`, { item: id });
-						this._activateItem(id);
+						this._activateItem(id, `keyboard`);
 					}
 					break;
 				}
@@ -333,7 +336,7 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 					}
 					break;
 				}
-				case `Escape`: this.selection.clear();
+				case `Escape`: this.selection.handleClear(`keyboard`);
 			}
 		};
 		this._onClick = (e) => {
@@ -342,7 +345,7 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 			const item = this._findListItem(e.composedPath());
 			if (!item) return;
 			this._dispatch(`list-item-click`, { item });
-			this.selection.handleClick(item, e);
+			this.selection.handleClick(item, gestureOf(e));
 		};
 		this._onDblClick = (e) => {
 			if (this.#isEditEvent(e)) return;
@@ -773,6 +776,23 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 	get selectedKeys() {
 		return this.selection.selectedKeys;
 	}
+	#partialKeys;
+	/**
+	* Rows shown as *partially* selected (a part of the resource is selected):
+	* `data-partial`, an indeterminate checkbox in `checked` mode, and an
+	* accessible description. Independent of `selectedKeys` — a key in both
+	* counts as selected. Replace-on-set; keys without a row are kept for when
+	* the row appears.
+	*/
+	get partialKeys() {
+		return this.#partialKeys;
+	}
+	set partialKeys(keys) {
+		const next = new Set(keys);
+		if (sameKeySet(next, this.#partialKeys)) return;
+		this.#partialKeys = next;
+		this._syncItemStates();
+	}
 	/** The key of the item under the cursor, or `undefined`. */
 	get tickledKey() {
 		const id = this.tickled.tickledId;
@@ -1468,6 +1488,7 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 			const item = this.#customWrappers.get(el) ?? el;
 			el.toggleAttribute(`data-tickled`, this.tickled.isTickled(el));
 			el.toggleAttribute(`data-selected`, this.selection.selected.has(el));
+			applyPartialAttributes(el, isPartialKey(keyForElement(el), this.#partialKeys, this.selection.selected.has(el)));
 			if (el.hasAttribute(`data-aria-role`)) el.setAttribute(`aria-selected`, String(this.selection.selected.has(el)));
 			if (this.interactionMode === `checked`) el.toggleAttribute(`data-checked`, !item.hasAttribute(`not-checked`) && this.selection.selected.has(el));
 			else el.removeAttribute(`data-checked`);
@@ -1532,16 +1553,22 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 				el.prepend(cb);
 			}
 			const checked = this.selection.selected.has(el);
+			const partial = isPartialKey(keyForElement(el), this.#partialKeys, checked);
 			if (wantsCustom) {
-				cb.setAttribute(`aria-checked`, String(checked));
+				cb.setAttribute(`aria-checked`, partial ? `mixed` : String(checked));
 				cb.toggleAttribute(`data-checked`, checked);
+				cb.toggleAttribute(`data-partial`, partial);
 				if (this.checkboxRenderer) {
 					const renderer = typeof this.checkboxRenderer === `function` ? this.checkboxRenderer : this.checkboxRenderer.renderer;
 					render(renderer(checked), cb);
 				}
 			} else {
 				const input = cb.querySelector(`input.ixfx-list-checkbox`);
-				if (input) input.checked = checked;
+				if (input) {
+					input.checked = checked;
+					input.indeterminate = partial;
+				}
+				cb.setAttribute(`aria-checked`, partial ? `mixed` : String(checked));
 			}
 		}
 	}
@@ -1560,7 +1587,7 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 		cell.setAttribute(`part`, `checkbox`);
 		cell.addEventListener(`click`, (e) => {
 			e.stopPropagation();
-			this.selection.toggle(el);
+			this.selection.handleCheckbox(el);
 		});
 		const input = document.createElement(`input`);
 		input.type = `checkbox`;
@@ -1582,7 +1609,7 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 		span.setAttribute(`part`, `checkbox`);
 		span.addEventListener(`click`, (e) => {
 			e.stopPropagation();
-			this.selection.toggle(el);
+			this.selection.handleCheckbox(el);
 		});
 		return span;
 	}
@@ -1608,13 +1635,13 @@ let VerticalListElement = class VerticalListElement extends LitElement {
 			cancelable: true
 		}));
 	}
-	_activateItem(item) {
-		if (this.interactionMode !== `manual`) this.selection.replace(item);
+	_activateItem(item, source = `pointer`) {
+		this.selection.handleReplace(item, source);
 		this._dispatch(`list-activate`, { item });
 	}
 	activateKey(key) {
 		const item = this.#itemForKey(key);
-		if (item) this._activateItem(item);
+		if (item) this._activateItem(item, `api`);
 	}
 	/** The row (or `undefined` for empty space) the last `list-drag-over` was fired for. */
 	#dragOver;
@@ -1862,6 +1889,13 @@ let VerticalListElement = class VerticalListElement extends LitElement {
       outline: 1px solid transparent;
     }
 
+    /* Partially selected: a dashed edge, lighter than a full selection. Hook: --item-bg-partial. */
+    ::slotted([data-partial]) {
+      background: var(--item-bg-partial, color-mix(in srgb, var(--item-bg-selected) 35%, transparent));
+      outline: 1px dashed var(--item-border-partial, var(--border));
+      outline-offset: -1px;
+    }
+
     ::slotted([data-selected][data-tickled]) {
       background: var(--item-bg-selected-tickled);
       outline: 2px dashed var(--surface-3);

package/dist/vertical-list.d.ts

@@ -1,5 +1,5 @@
 import { B as ListNativeDragStartDetail, F as ListDragPreview, I as ListDragPreviewContext, L as ListDragPreviewRenderer, P as ListDragEntry, V as ListNativeDragStartEvent, z as ListDragSource } from "./tree-component-DgfkxmVY.js";
 import { n as ListViewportChangeEvent, t as ListViewportChangeDetail } from "./list-viewport-types-BRZsLcvp.js";
-import { a as ListItemClickDetail, c as ListSelectEvent, d as ListTickleEvent, i as ListInteractionMode, l as ListSelectionMode, n as ListActivateEvent, o as ListItemClickEvent, r as ListElementEventMap, s as ListSelectDetail, t as ListActivateDetail, u as ListTickleDetail } from "./list-selection-types-PjKdhF-a.js";
-import { a as VerticalListViewState, c as ListDragLeaveDetail, d as ListDropDetail, f as ListDropEvent, g as ListEditCommitEvent, h as ListEditCommitDetail, i as VerticalListElementEventMap, l as ListDragLeaveEvent, m as ListEditCancelEvent, n as CustomCheckboxOptions, o as ListContextMenuDetail, p as ListEditCancelDetail, r as VerticalListElement, s as ListContextMenuEvent, t as AddItemOptions, u as ListDragOverEvent } from "./vertical-list-BPDmZx6T.js";
+import { a as ListItemClickDetail, c as ListSelectEvent, g as ListTickleEvent, h as ListTickleDetail, i as ListInteractionMode, m as ListSelectionMode, n as ListActivateEvent, o as ListItemClickEvent, r as ListElementEventMap, s as ListSelectDetail, t as ListActivateDetail } from "./list-selection-types-hj9Njei3.js";
+import { a as VerticalListViewState, c as ListDragLeaveDetail, d as ListDropDetail, f as ListDropEvent, g as ListEditCommitEvent, h as ListEditCommitDetail, i as VerticalListElementEventMap, l as ListDragLeaveEvent, m as ListEditCancelEvent, n as CustomCheckboxOptions, o as ListContextMenuDetail, p as ListEditCancelDetail, r as VerticalListElement, s as ListContextMenuEvent, t as AddItemOptions, u as ListDragOverEvent } from "./vertical-list-od4050Bo.js";
 export { AddItemOptions, CustomCheckboxOptions, type ListActivateDetail, type ListActivateEvent, type ListContextMenuDetail, type ListContextMenuEvent, type ListDragEntry, type ListDragLeaveDetail, type ListDragLeaveEvent, type ListDragOverEvent, type ListDragPreview, type ListDragPreviewContext, type ListDragPreviewRenderer, type ListDragSource, type ListDropDetail, type ListDropEvent, type ListEditCancelDetail, type ListEditCancelEvent, type ListEditCommitDetail, type ListEditCommitEvent, type ListElementEventMap, type ListInteractionMode, type ListItemClickDetail, type ListItemClickEvent, type ListNativeDragStartDetail, type ListNativeDragStartEvent, type ListSelectDetail, type ListSelectEvent, type ListSelectionMode, type ListTickleDetail, type ListTickleEvent, type ListViewportChangeDetail, type ListViewportChangeEvent, VerticalListElement, VerticalListElementEventMap, type VerticalListViewState };

package/dist/vertical-list.js

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

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](../../docs/infra-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.
 
 ---
 
@@ -506,10 +513,19 @@ rows dropped from the flat list) modes. No default shortcut:
 grid.registry.invoke('list.search.filter');   // or .navigate / .select
 ```
 
-A row is matched against `rowSearchText(row)` — by default its visible cells'
-values joined by a space; override with the `rowSearchText` property. `select`
-mode needs `selection-mode="multiple"` to hold more than one row. Character
-highlights are not drawn (a match position spans multiple cells). `filterPredicate`
+A row is matched against the displayed (formatted) text of one column: the
+`search-column` attribute (`searchColumn` property) names it, defaulting to the
+first visible column. Searching every column makes dates and sizes match
+queries like `12`, which is rarely what Find is for. Set the `rowSearchText`
+property, `(row) => string`, to match against something else, e.g. several
+columns joined. `select` mode needs `selection-mode="multiple"` to hold more
+than one row.
+
+Matched characters in the search column are highlighted under the
+`data-grid-search` key, coloured by `--search-highlight-bg` /
+`--search-highlight-color` (default `--accent` / `--accent-text`). Matches
+against a custom `rowSearchText` aren't highlighted, since they can't be
+mapped onto a cell, and neither are cells drawn by a column `renderer`. `filterPredicate`
 (a `(row) => boolean` property) filters rows directly. `search-modes` limits the
 offered modes. Full model: [`docs/infra-incremental.md`](../../docs/infra-incremental.md).
 

package/docs-user/detail-list.md

@@ -162,6 +162,7 @@ list.keyProperty = 'name'; // Preserves selection across rebuilds
 | `textColorProperty` | `string` | Property name for the caption's CSS colour |
 | `badgeProperty` | `string` | Property name for a Finder-style badge |
 | `formatter` | `(item: unknown, index: number) => string \| Node` | Custom renderer |
+| `searchText` | `(item: unknown, index: number) => string` | Text incremental search matches (default: the caption if a string, else the row's whole text) |
 
 ```typescript
 list.formatter = (item, index) => {
@@ -177,6 +178,18 @@ put, and the new row animates in like `addItem()`. Pass new objects (or change
 `displayProperty`, `formatter`, …) to rebuild rows. With a `formatter`, a row
 is only kept at the same index, since the formatter receives the index.
 
+Because reused rows aren't re-run through the `formatter`, state it reads from
+outside the item (sizes, fit mode, …) doesn't reach existing rows when the same
+objects are reassigned. Call `list.reformat()` to rebuild every row, or assign a
+new `formatter` function (a new identity counts as a shape change).
+
+When `formatter` returns a `Node`, search falls back to the row's whole text
+(sublines, sizes, dates). Set `searchText` to match on just the name:
+
+```typescript
+list.searchText = item => (item as { name: string }).name;
+```
+
 Retrieve the original data for an element:
 
 ```typescript
@@ -297,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>
@@ -459,6 +472,8 @@ Search matches against `data-search-label` (or `textContent` as fallback). Use `
 <li data-search-label="document a alpha">Document A</li>
 ```
 
+For object items, `searchText` sets `data-search-label` per row (see [Object items](#object-items)).
+
 ### Highlight styling
 
 Matched characters are highlighted with the `detail-list-search` highlight key. Style matches with:

package/docs-user/dock.md

@@ -228,7 +228,9 @@ The host consumes `ixfx-split-layout` events: `ixfx-split-resize` /
 ```ts
 getViewState(options?): DockHostViewState   // { v, kind: 'dock-host', layout }; folds live split weights
 setViewState(state: Partial<DockHostViewState>): void
-clearPendingViewState(): void               // no-op: placeholders live in the layout tree
+clearPendingViewState(): void               // drops placeholders (panels the host doesn't hold)
+saveLayout(): DockLayout                    // deprecated alias of getViewState().layout
+loadLayout(layout: DockLayout): void        // deprecated alias of setViewState({ layout })
 addPanel(panel: DockPanelElement | DockPanelInit, target?: DockAddPanelTarget): boolean
 type DockAddPanelTarget = {
   container?: string;   // named stack leaf — takes precedence over `stack`
@@ -259,6 +261,7 @@ getNeighbours(leaf: DockLeafRef): DockNeighbours | null
 moveLeaf(leaf: DockLeafRef, direction: 'up' | 'down' | 'left' | 'right'): boolean
 moveLeafToEdge(leaf: DockLeafRef, edge: 'top' | 'bottom' | 'left' | 'right'): boolean
 canAccept?: (panelId: string, op: DockOperation) => boolean
+placeholderLabel?: (panelId: string) => string   // tab label for placeholders (default: the id)
 
 // Cross-window hooks (serializable in/out; no element handoff)
 getPanelSnapshot(panelId: string): DockPanelSnapshot | null
@@ -456,13 +459,19 @@ The dock layout is close to structure, so the saved state *is* the tree
   a save → drag → save round-trip preserves user adjustments.
 - **Panels not in the host yet.** `setViewState()` keeps every panel id the
   layout names, held or not. One the host doesn't hold is a *placeholder*:
-  it keeps its place in the tree (shown as a tab labelled with its id) and
+  it keeps its place in the tree (shown as a tab labelled by the
+  `placeholderLabel(panelId)` property, or its id when unset) and
   the panel slots into that place when it arrives — appended as a light-DOM
   child, `addPanel()` **without** a target, `acceptExternalPanel()` without
   `at`, or a cross-host adoption. An explicit `addPanel()` target still wins.
   Placeholders are saved by `getViewState()`; `includePending: false` leaves
   them out (stacks they empty are dropped unless named). Remove one with
-  `removePanel(id)`; `clearPendingViewState()` is a no-op.
+  `removePanel(id)`, or all of them with `clearPendingViewState()`.
+- **Persisting with the default keeps stale ids.** A placeholder for a panel
+  that no longer exists is saved again on every `getViewState()`, so it never
+  goes away. Apps whose panels can disappear between save and restore should
+  call `clearPendingViewState()` once they have added the panels they hold,
+  or save with `includePending: false`.
 - Pooled panels the layout doesn't name are appended to the first stack
   admitting their kind.
 - A panel that is closed / removed (`removePanel`, close button, removed from

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](../../docs/infra-selection-intents.md): `list-select-intent`, `partialKeys`, and keys that arrive later.
+
 Restore across a reload:
 
 ```typescript
@@ -311,8 +314,11 @@ grid.registry.invoke('list.search.filter');   // or .navigate / .select
 
 Search matches `data-label` (or `[data-grid-list-caption]` text, then
 `data-search-label`, then `textContent`). Filter mode genuinely removes items
-from the virtualised layout. Add a page-level highlight rule to see matched
-characters:
+from the virtualised layout. Matched characters are highlighted under the
+`grid-list-search` key. In data mode (`itemAdapter`) the captions live in the
+shadow root and the grid styles them itself (`--search-highlight-bg` /
+`--search-highlight-color`, default `--accent` / `--accent-text`). In element
+mode the items are light DOM, so add a page-level rule:
 
 ```css
 ::highlight(grid-list-search) { background: var(--accent); color: var(--accent-text); }

package/docs-user/index.json

@@ -1,7 +1,7 @@
 {
   "name": "@ixfx/components",
-  "version": "0.16.0",
-  "generated": "2026-10-23T13:15:45.063Z",
+  "version": "0.16.2",
+  "generated": "2026-11-02T19:16:08.207Z",
   "components": [
     {
       "name": "ac-text",

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/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](../../docs/infra-selection-intents.md): `list-select-intent`, `partialKeys`, and keys that arrive later.
+
 ### Usage example
 
 ```typescript

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ixfx/components",
   "type": "module",
-  "version": "0.16.0",
+  "version": "0.16.2",
   "packageManager": "pnpm@10.0.0",
   "description": "Web components for ixfx — Lit-based UI toolkit",
   "author": "Clint Heyer",
@@ -247,7 +247,7 @@
     "lit": { "optional": false }
   },
   "dependencies": {
-    "@clinth/ui-commands": "1.1.0",
+    "@clinth/ui-commands": "1.1.1",
     "@clinth/vcanvas": "0.0.5",
     "@ixfx/arrays": "0.56.14",
     "@ixfx/collections": "0.56.14",

package/dist/item-appearance-BjcMyauw.js

@@ -1,29 +0,0 @@
-//#region src/common/item-appearance.ts
-/**
-* Shared helpers for the list components' per-item appearance hooks — the
-* per-item icon colour / text colour / badge that miller-list, detail-list,
-* grid-list, data-grid and vertical-list all accept.
-*
-* Every component takes these three features in its own idiom (plain fields
-* on a `TreeItem`, a property-name lookup, an adapter function, a nominated
-* column) but they all agree on what "not supplied" means, and on never
-* emitting an empty slot for an absent value.
-*/
-/**
-* Whether a per-item appearance value counts as "not supplied". `false` and
-* `''` are included so a consumer can clear a feature without rebuilding the
-* collection — e.g. `badge: flags && tagChip(flags.colour)`.
-*/
-function appearanceAbsent(value) {
-	return value === void 0 || value === null || value === false || value === ``;
-}
-/**
-* A usable CSS colour from a per-item value, or `undefined`. Non-strings and
-* empty strings are ignored rather than stringified, so a stray number or
-* `0` never lands in a `style` attribute.
-*/
-function appearanceColor(value) {
-	return typeof value === `string` && value.length > 0 ? value : void 0;
-}
-//#endregion
-export { appearanceColor as n, appearanceAbsent as t };

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 };