@ixfx/components 0.15.5 → 0.16.1

package/dist/view-state-controller-BdyXWUUM.js

@@ -0,0 +1,305 @@
+//#region src/common/view-state/types.ts
+/**
+* Shared view-state contract for list-like components.
+*
+* View state is everything about *how* a component is showing its data —
+* selection, expansion, scroll, column sizes — kept separate from the data
+* itself. It is plain JSON (arrays and records, never Sets or Maps) so a host
+* can `JSON.stringify` it straight into whatever storage it likes. Components
+* never persist it themselves; see `bindViewState()`.
+*
+* Every field is keyed by the stable item / column / group key, never by
+* index, so state can be re-applied to data that has been rebuilt, re-sorted
+* or streamed in over time. Keys the current data doesn't contain are kept
+* as pending and applied once a matching item appears.
+*/
+/** Current schema version. Bump on breaking shape changes. */
+const VIEW_STATE_VERSION = 1;
+/** Name of the debounced change event every view-stateful component fires. */
+const VIEW_STATE_CHANGE = `view-state-change`;
+//#endregion
+//#region src/common/view-state/scroll-anchor.ts
+/**
+* Capture a {@link ScrollState} for a DOM-rendered list. `items` must be in
+* visual order along `axis`; the first one whose far edge is below / right of
+* the viewport start is the anchor (found by binary search).
+*/
+function captureElementScroll(viewport, items, getKey, axis = `vertical`) {
+	const top = viewport.scrollTop;
+	const left = viewport.scrollLeft;
+	const base = left === 0 ? { top } : {
+		top,
+		left
+	};
+	if (items.length === 0) return base;
+	const vpRect = viewport.getBoundingClientRect();
+	const start = axis === `vertical` ? vpRect.top : vpRect.left;
+	const edges = (el) => {
+		const r = el.getBoundingClientRect();
+		return axis === `vertical` ? {
+			lo: r.top,
+			hi: r.bottom
+		} : {
+			lo: r.left,
+			hi: r.right
+		};
+	};
+	let lo = 0;
+	let hi = items.length - 1;
+	let found = -1;
+	while (lo <= hi) {
+		const mid = lo + hi >> 1;
+		if (edges(items[mid]).hi > start) {
+			found = mid;
+			hi = mid - 1;
+		} else lo = mid + 1;
+	}
+	if (found === -1) return base;
+	for (let i = found; i < items.length; i++) {
+		const key = getKey(items[i]);
+		if (key !== void 0) return {
+			...base,
+			anchor: {
+				key,
+				offset: Math.round(start - edges(items[i]).lo)
+			}
+		};
+	}
+	return base;
+}
+/**
+* Scroll `viewport` so `item` sits at the anchor's offset. Returns `false`
+* when the viewport can't scroll far enough yet (content still arriving),
+* so the caller can keep the anchor pending.
+*/
+function restoreElementScroll(viewport, item, offset, axis = `vertical`) {
+	const vpRect = viewport.getBoundingClientRect();
+	const r = item.getBoundingClientRect();
+	if (axis === `vertical`) return scrollToOffset(viewport, viewport.scrollTop + (r.top - vpRect.top) + offset, axis);
+	return scrollToOffset(viewport, viewport.scrollLeft + (r.left - vpRect.left) + offset, axis);
+}
+/**
+* Set the scroll offset along `axis`. Returns `false` when `target` is beyond
+* the current scroll range (it is clamped and should be retried later).
+*/
+function scrollToOffset(viewport, target, axis = `vertical`) {
+	const max = axis === `vertical` ? viewport.scrollHeight - viewport.clientHeight : viewport.scrollWidth - viewport.clientWidth;
+	const clamped = Math.max(0, Math.min(target, max));
+	if (axis === `vertical`) viewport.scrollTop = clamped;
+	else viewport.scrollLeft = clamped;
+	return target <= max + 1;
+}
+/**
+* Anchor for a virtualised list with arithmetic row geometry: pass the first
+* visible index, the key at that index and that row's start offset.
+*/
+function anchorFromRow(scrollOffset, key, rowStart, crossOffset = 0) {
+	const base = crossOffset === 0 ? { top: scrollOffset } : {
+		top: scrollOffset,
+		left: crossOffset
+	};
+	if (key === void 0) return base;
+	return {
+		...base,
+		anchor: {
+			key,
+			offset: Math.round(scrollOffset - rowStart)
+		}
+	};
+}
+const SCROLL_KEYS = /* @__PURE__ */ new Set([
+	`ArrowUp`,
+	`ArrowDown`,
+	`ArrowLeft`,
+	`ArrowRight`,
+	`PageUp`,
+	`PageDown`,
+	`Home`,
+	`End`,
+	` `
+]);
+/**
+* Call `onIntent` the first time the user does something that scrolls or
+* moves within `target` (wheel, touch, pointer on the scrollbar, navigation
+* key). Used to cancel a pending scroll restore — the user's own scroll wins.
+* Programmatic `scrollTop` writes do not trigger it. Returns a disposer.
+*/
+function onUserScrollIntent(target, onIntent) {
+	const events = [
+		`wheel`,
+		`touchstart`,
+		`pointerdown`,
+		`keydown`
+	];
+	const handler = (event) => {
+		if (event.type === `keydown` && !SCROLL_KEYS.has(event.key)) return;
+		onIntent();
+	};
+	for (const type of events) target.addEventListener(type, handler, {
+		passive: true,
+		capture: true
+	});
+	return () => {
+		for (const type of events) target.removeEventListener(type, handler, { capture: true });
+	};
+}
+//#endregion
+//#region src/common/view-state/view-state-controller.ts
+const REASON_RANK = {
+	restore: 0,
+	data: 1,
+	user: 2
+};
+/**
+* Plumbing shared by every view-stateful component:
+*
+* - **change events** — `notify(reason)` coalesces changes into one debounced
+*   `view-state-change` event (strongest reason wins: user > data > restore),
+*   flushed immediately on disconnect so the last change is never lost.
+* - **restore marking** — changes made inside `restoring(fn)` are reported as
+*   `restore`, so persistence code can skip writing back what it just loaded.
+* - **validation** — `accepts(state)` rejects a state for another kind / version.
+* - **pending scroll** — a scroll position waiting for its anchor item (or for
+*   enough content). Cancelled by the user's own scroll intent on the target
+*   given to `observeScrollTarget()`.
+*
+* The component owns its facets (selection, expansion, columns) and decides
+* what's pending; this controller only carries the cross-cutting parts.
+*/
+var ViewStateController = class {
+	#host;
+	#opts;
+	#timer;
+	#reason;
+	#restoreDepth = 0;
+	#pendingScroll;
+	/** Set when a restore wrote the scroll offset; the scroll event that follows is not the user's. */
+	#restoreScrolled = false;
+	#disposeScrollIntent;
+	#scrollTarget;
+	constructor(host, options) {
+		this.#host = host;
+		this.#opts = options;
+		host.addController(this);
+	}
+	get kind() {
+		return this.#opts.kind;
+	}
+	hostConnected() {
+		if (this.#scrollTarget && !this.#disposeScrollIntent) this.observeScrollTarget(this.#scrollTarget);
+	}
+	hostDisconnected() {
+		this.flush();
+		this.#disposeScrollIntent?.();
+		this.#disposeScrollIntent = void 0;
+	}
+	/** Record a change. Inside `restoring()` the reason is forced to `restore`. */
+	notify(reason = `user`) {
+		const effective = this.#restoreDepth > 0 ? `restore` : reason;
+		if (this.#reason === void 0 || REASON_RANK[effective] > REASON_RANK[this.#reason]) this.#reason = effective;
+		if (this.#timer !== void 0) clearTimeout(this.#timer);
+		this.#timer = setTimeout(() => this.flush(), this.#opts.debounceMs ?? 150);
+	}
+	/** Fire any pending change event now. */
+	flush() {
+		if (this.#timer !== void 0) {
+			clearTimeout(this.#timer);
+			this.#timer = void 0;
+		}
+		const reason = this.#reason;
+		if (reason === void 0) return;
+		this.#reason = void 0;
+		this.#host.dispatchEvent(new CustomEvent(VIEW_STATE_CHANGE, {
+			detail: {
+				state: this.#opts.capture(),
+				reason
+			},
+			bubbles: true
+		}));
+	}
+	/** Run `fn` with every `notify()` inside it reported as `restore`. */
+	restoring(fn) {
+		this.#restoreDepth++;
+		try {
+			return fn();
+		} finally {
+			this.#restoreDepth--;
+		}
+	}
+	/** True while inside `restoring()`. */
+	get isRestoring() {
+		return this.#restoreDepth > 0;
+	}
+	/** Whether `state` is for this component kind and schema version. Warns when not. */
+	accepts(state) {
+		if (state === null || typeof state !== `object`) return false;
+		if (state.v !== void 0 && state.v !== 1) {
+			console.warn(`[${this.#opts.kind}] ignoring view state with version ${String(state.v)}`);
+			return false;
+		}
+		if (state.kind !== void 0 && state.kind !== this.#opts.kind) {
+			console.warn(`[${this.#opts.kind}] ignoring view state for kind '${state.kind}'`);
+			return false;
+		}
+		return true;
+	}
+	/**
+	* Stamp `v` / `kind` onto `fields` and apply `include`. Components build
+	* their full field set and pass it through here from `getViewState()`.
+	*/
+	shape(fields, options) {
+		const out = {
+			v: 1,
+			kind: this.#opts.kind
+		};
+		const include = options?.include;
+		for (const [key, value] of Object.entries(fields)) {
+			if (value === void 0) continue;
+			if (include && !include.includes(key)) continue;
+			out[key] = value;
+		}
+		return out;
+	}
+	/**
+	* Watch `target` for user scroll intent (wheel / touch / pointer / nav key);
+	* any intent drops the pending scroll. Call again if the scroll container
+	* is replaced.
+	*/
+	observeScrollTarget(target) {
+		this.#disposeScrollIntent?.();
+		this.#scrollTarget = target;
+		this.#disposeScrollIntent = onUserScrollIntent(target, () => {
+			this.#pendingScroll = void 0;
+		});
+	}
+	get pendingScroll() {
+		return this.#pendingScroll;
+	}
+	set pendingScroll(scroll) {
+		this.#pendingScroll = scroll;
+	}
+	/**
+	* Try the pending scroll with `apply`; it returns `true` once the position
+	* was fully reached (anchor present, content long enough), which clears it.
+	* Call after each render that may have added items.
+	*/
+	applyPendingScroll(apply) {
+		const scroll = this.#pendingScroll;
+		if (!scroll) return;
+		this.#restoreScrolled = true;
+		if (apply(scroll)) this.#pendingScroll = void 0;
+	}
+	/**
+	* Call from the viewport's `scroll` listener. Ignored while a scroll restore
+	* is still pending; the event caused by a restore's own write is reported
+	* as `restore`, anything else as `user`.
+	*/
+	notifyScroll() {
+		if (this.#pendingScroll) return;
+		const reason = this.#restoreScrolled ? `restore` : `user`;
+		this.#restoreScrolled = false;
+		this.notify(reason);
+	}
+};
+//#endregion
+export { restoreElementScroll as a, VIEW_STATE_VERSION as c, onUserScrollIntent as i, anchorFromRow as n, scrollToOffset as o, captureElementScroll as r, VIEW_STATE_CHANGE as s, ViewStateController as t };

package/docs-user/README.md

@@ -23,6 +23,7 @@ This directory contains documentation for each component and some architectural
 - [grid-list](./grid-list.md)
 - [grouped-item-lister](./grouped-item-lister.md)
 - [hyperbolic-tree](./hyperbolic-tree.md)
+- [icicle-tree](./icicle-tree.md)
 - [icons](./icons.md)
 - [incr-search](./incr-search.md)
 - [labelled-radial-input](./labelled-radial-input.md)
@@ -58,6 +59,7 @@ This directory contains documentation for each component and some architectural
 - [toolbar](./toolbar.md)
 - [transitory-label](./transitory-label.md)
 - [tree](./tree.md)
+- [treemap](./treemap.md)
 - [twosplit-layout](./twosplit-layout.md)
 - [util](./util.md)
 - [vertical-list](./vertical-list.md)

package/docs-user/crumbs.md

@@ -38,6 +38,7 @@ nav.model = {
 | `inputMode`           | `string`                       | `''`        | Input mode for styling (`'keyboard'`, etc.)      |
 | `padEnding`           | `boolean`                      | `false`     | Pad trailing space to enable left-align scroll   |
 | `withUp`              | `boolean`                      | `false`     | Show an Up button to navigate to parent         |
+| `restoreLoads`        | `boolean`                      | `true`      | Let a restored location load unloaded branches via `loadChildren` |
 
 ### Events
 
@@ -55,6 +56,32 @@ nav.model = {
 |-------------------------|---------|------------------------------------------------|
 | `navigateTo(keys)`      | `boolean` | Navigate to a node by key path. Returns false if not found. |
 | `navigateToNode(predicate)` | `boolean` | Navigate to the first node matching a predicate. |
+| `getViewState(options?)` | `CrumbNavigationViewState` | Snapshot the location. See [View state](#view-state). |
+| `setViewState(state)` | `void` | Go to a saved location, now or as its nodes arrive. |
+| `clearPendingViewState()` | `void` | Forget a saved location not reached yet. |
+
+### View state
+
+The current location as plain JSON, for the host to persist (see
+[docs/infra-view-state.md](../../docs/infra-view-state.md)):
+
+```ts
+{ v: 1, kind: 'crumb-navigation', path: ['dev', 'workspace'] } // keys below the root; [] = root
+```
+
+The location *is* the selection, so there is no separate `selected` field, and
+it is a key path rather than a lone key so a deep saved location can be loaded
+down to. The keyboard cursor is transient and not recorded.
+
+- Keys not loaded yet stay pending: the crumb moves to the deepest loaded
+  ancestor and continues as nodes arrive (new `root`, or children filled in
+  followed by `requestUpdate()`). With `restoreLoads` it calls `loadChildren`
+  itself, one branch at a time. Each step fires `select`.
+- New `root` data keeps the location by key. If it's gone, the crumb steps
+  back to the closest ancestor silently and returns when the key reappears.
+- Any explicit navigation — a click, `select()`, `navigateTo()`, or the host
+  assigning `selectedNode` — drops a pending location. Set the initial
+  `selectedNode` *before* `setViewState()` / `bindViewState()`.
 
 ### CSS custom properties
 

package/docs-user/data-grid.md

@@ -223,7 +223,8 @@ grid.tickledKey;                   // row key under the cursor, or undefined
 ```
 
 The setter fires `datagrid-select` `{ selectedKeys, previous }` only when the
-selection actually changes.
+selection actually changes. Selected rows that leave `rows` are deselected
+silently, and reselected if they return. See [View state](#view-state).
 
 ---
 
@@ -505,10 +506,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).
 
@@ -549,6 +559,7 @@ still shadow-internal.
 | `appendRows` | `(rows)` | Add rows without a full re-sort/rebuild — for streaming |
 | `selectKeys` / `set selectedKeys` | `(keys)` | Replace the selection by row key |
 | `tickleRow` | `(key)` | Move the row cursor and scroll it into view |
+| `getViewState` / `setViewState` / `clearPendingViewState` | see [View state](#view-state) | Snapshot / restore selection, cursor, scroll, groups, columns, sort |
 | `autoSizeColumn` | `(key)=>boolean` | Resize a column to fit its contents, animating the width. Returns `false` (no-op) for an unknown column, `resizable: false`, or a `renderer` column without `measure`/`fixedExtraWidth` — see [Auto-sizing a column](#auto-sizing-a-column). |
 
 | Getter | Type | |
@@ -567,6 +578,69 @@ when the key sets actually differ from the last dispatch. Mirrors
 
 ---
 
+## View state
+
+The grid implements the shared view-state API (`docs/infra-view-state.md`):
+`getViewState()`, `setViewState()`, `clearPendingViewState()` and a debounced
+`view-state-change` event. `bindViewState()` persists it in two lines:
+
+```ts
+import { bindViewState } from '@ixfx/components';
+
+bindViewState(grid, {
+  load: () => JSON.parse(localStorage.getItem(`orders-grid`) ?? `null`),
+  save: s => localStorage.setItem(`orders-grid`, JSON.stringify(s)),
+});
+grid.columns = defs;
+for await (const batch of stream)
+  grid.appendRows(batch); // saved selection / cursor / scroll apply as rows arrive
+```
+
+`kind: 'data-grid'`. Fields (all optional on `setViewState`; present fields
+replace, absent ones are untouched):
+
+| Field | Shape | |
+|---|---|---|
+| `selected` | `string[]` | Selected row keys (the checked set in `checked` mode) |
+| `focus` | `string` | Row cursor key — recorded only after keyboard navigation |
+| `scroll` | `{ top, left?, anchor?: { key, offset } }` | `anchor` is the first visible row's key; `left` is raw px |
+| `expanded` | `Record<groupKey, boolean>` | Groups default open, so only collapsed groups (`false`) are recorded |
+| `columns` | `Record<columnKey, { width?, visible?, order? }>` | `order` is a rank: lower is further left |
+| `sort` | `{ key, direction } \| null` | `null` = unsorted |
+| `groupBy` | `string \| null` | Only recorded when `allowGrouping` is on (the user can change it); a function `groupBy` is never recorded |
+
+**Pending state.** Keys that aren't in the data stay pending and are applied
+when a matching row, group or column appears, which covers restoring before
+data, `rows` resets and rebuilds, and `appendRows()` streams. When a selected
+row leaves `rows` it is deselected silently and its key goes pending. When it
+comes back it is reselected and `datagrid-select` fires. Any explicit
+selection change (`selectKeys`, click, key, `Esc`) drops pending selection.
+Resolving pending state on `appendRows()` looks only at the appended slice.
+
+**Columns.** Saved width and visibility for a column apply once, when the
+column is first defined. After that the column definition is the source of
+truth, so a host that later redefines the column wins. A column that is
+removed from `columns` keeps its last width and visibility pending until it
+returns. A saved `order` reorders the columns it names within the positions
+they occupy. Columns it doesn't name keep their place. It is kept until every
+column it names has appeared, so late columns still land in their saved
+position. Dragging a header to reorder drops it. Applied layout goes onto
+copies of the column objects, and `columns` is reassigned.
+
+**Rows keyed by index.** With the default `getRowKey`, a row with neither
+`key` nor `id` is keyed by its sorted index. Index keys change on every sort,
+insert or rebuild, so these rows are never recorded in `selected`, `focus` or
+the scroll anchor (`scroll.top` / `left` are still recorded). Supply a
+`getRowKey` (or `key` / `id` fields) to make their state restorable. A
+custom `getRowKey` is trusted to be stable.
+
+Change events: `user` for selection, cursor moves, scrolling, sort clicks,
+column resize / auto-size / reorder / visibility, group collapse and group-by
+menu choices; `restore` for state applied from `setViewState()` or pending
+state.
+
+---
+
 ## Demo
 
 `demo/data-grid.html` + `demo/data-grid.ts`: 200 rows, `Department` random, `Score` float, `Name`/`Department` editable (`user` mode, slow double-click; `Tab`/`Up`/`Down` navigation; `Enter` from tickled row). Controls: Selection/Interaction/Group by/Editability/`column-menu` + `Edit first row` (manual), a `Stream +5,000 rows` button (`appendRows`), and `selectKeys` / `tickleRow` buttons.

package/docs-user/detail-list.md

@@ -38,6 +38,7 @@ Selection semantics match `ixfx-vertical-list` — same modes, same `list-*` eve
   - [Asynchronous data](#asynchronous-data)
     - [Promise provider](#promise-provider)
     - [Streaming provider](#streaming-provider)
+  - [View state](#view-state)
   - [CSS variables](#css-variables)
   - [CSS parts](#css-parts)
   - [Performance](#performance)
@@ -161,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) => {
@@ -176,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
@@ -458,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:
@@ -587,6 +603,59 @@ replaced) falls back to a full rebuild.
 
 ---
 
+## View state
+
+Snapshot and restore *how* the list is showing its data, separately from the
+data, as plain JSON keyed by item / group key. See
+[`docs/infra-view-state.md`](../../docs/infra-view-state.md) for the shared
+contract.
+
+```ts
+import { bindViewState } from '@ixfx/components';
+
+bindViewState(list, {
+  load: () => JSON.parse(localStorage.getItem(`files`) ?? `null`),
+  save: s => localStorage.setItem(`files`, JSON.stringify(s)),
+});
+list.provider = fetchFiles; // pending state applies as batches arrive
+```
+
+`kind: 'detail-list'`. Fields (`DetailListViewState`):
+
+| Field | Shape | Notes |
+|---|---|---|
+| `selected` | `string[]` | Selected item keys (`data-key` / `data-value`, or `keyProperty`). In `checked` mode this is the checked set — `data-checked` is derived from the selection, so there is no separate field. |
+| `expanded` | `Record<string, boolean>` | `{ [groupKey]: false }` per collapsed group. Groups default open, so only collapses are recorded; `true` re-opens. |
+| `focus` | `string` | Keyboard-cursor key, recorded only when the cursor was moved by keyboard. Restoring it puts the list in keyboard mode. |
+| `scroll` | `{ top, left?, anchor? }` | Horizontal: `left`, plus `anchor` = the top item of the first visible column and the px offset into it. |
+
+`sort` is not view state: the list has no UI to change it, so it stays host
+configuration.
+
+- **Pending.** Keys not in the data stay pending and apply when a matching
+  item appears — via `items`, a provider batch (only the new slice is
+  searched), `addItem` / `setItems`, or a light-DOM append. Selected items that
+  leave the data (rebuild, `clearItems`, removed `<li>`) are deselected
+  silently and their keys go pending.
+- Restored selection fires `list-select`; restored collapses fire
+  `list-group-toggle` for groups that are present. Any explicit selection
+  change drops pending selection.
+- Changing `groupBy` drops collapses of the current groups but keeps pending
+  (never-matched) collapsed keys, so a state restored before `groupBy` is set
+  still applies.
+- A pending scroll waits until its anchor item is laid out and the columns are
+  wide enough; a wheel, pointer or navigation key cancels it.
+
+```ts
+list.getViewState();                          // pending included
+list.getViewState({ includePending: false });
+list.setViewState({ selected: [`row-3`] });   // partial: only fields present apply
+list.clearPendingViewState();
+list.addEventListener(`view-state-change`, e => e.detail /* { state, reason } */);
+```
+
+---
+
 ## CSS variables
 
 | Variable | Default | Description |