@ixfx/components 0.15.5 → 0.16.0

package/docs-user/grid-list.md

@@ -20,10 +20,11 @@ single vertical column, or a horizontally-scrolling strip.
 9. [Native drag-out](#native-drag-out)
 10. [Keyboard](#keyboard)
 11. [Grouping](#grouping)
-12. [Virtualisation](#virtualisation)
-13. [Performance](#performance)
-14. [CSS parts](#css-parts)
-15. [Choosing a list component](#choosing-a-list-component)
+12. [View state](#view-state)
+13. [Virtualisation](#virtualisation)
+14. [Performance](#performance)
+15. [CSS parts](#css-parts)
+16. [Choosing a list component](#choosing-a-list-component)
 
 ---
 
@@ -214,7 +215,7 @@ grid.tickledKey;         // key under the cursor, or undefined
 | Property / attribute | Default | Description |
 |---|---|---|
 | `disableHoverTickle` / `disable-hover-tickle` | `false` | When set, pointer hover no longer moves the cursor, fires `list-tickle`, or changes where arrow-key navigation resumes from, and the hover highlight is dropped so nothing *looks* interactive. Keyboard navigation, selection, and `focusKey()` are unaffected. |
-| `disableScrollHoverTickle` / `disable-scroll-hover-tickle` | `false` | When set, a scroll gesture moving cells beneath a stationary pointer no longer moves the cursor: virtualised `pointerenter` events from scrolling are ignored, so `list-tickle` and the highlight hold still. Hover resumes on the next real pointer movement, or after the pointer leaves and re-enters the list. Click selection, keyboard navigation, and `focusKey()` are unaffected. |
+| `scrollHoverTickle` / `scroll-hover-tickle` | `false` | Let hover follow cells that scroll beneath a stationary pointer. Off by default: during a scroll gesture, virtualised `pointerenter` events are ignored so `list-tickle` and the highlight hold still. Hover resumes on the next real pointer movement, or after the pointer leaves and re-enters the list. Click selection, keyboard navigation, and `focusKey()` are unaffected. |
 
 ```html
 <ixfx-grid-list disable-hover-tickle></ixfx-grid-list>
@@ -229,8 +230,8 @@ Because cells are virtualised, wheel / trackpad scrolling inserts new cells
 under a stationary pointer, and each fresh cell fires `pointerenter` — the
 cursor and any cursor-driven rendering (e.g. a large preview panel) churn for
 as long as the gesture lasts, even though the pointer never moved.
-`disable-scroll-hover-tickle` ignores those synthetic enters while the gesture
-is active. While suppressed, the host carries a `data-scroll-hover-suppress`
+By default those synthetic enters are ignored while the gesture is active
+(set `scroll-hover-tickle` to let hover follow the content instead). While suppressed, the host carries a `data-scroll-hover-suppress`
 attribute (the CSS `:hover` highlight is gated on it), which is removed on the
 next real pointer movement or when the pointer leaves the list.
 
@@ -402,11 +403,11 @@ Parts: `part="icon"` and `part="badge"` on the wrappers this adds.
 
 | Method | Effect |
 |---|---|
-| `setItems(items)` | Replace the collection. Selection / cursor keep any key still present. |
+| `setItems(items)` | Replace the collection. Selection / cursor keep any key still present; vanished keys are deselected silently and held pending (see [View state](#view-state)). |
 | `appendItems(items)` | Add to the end. Scroll, selection and cursor untouched; no reflow animation. |
 | `updateItem(key, item)` | Replace one item. A visible cell re-renders in place; an offscreen one updates when scrolled in. |
-| `removeItems(keys)` | Remove items. Removed keys drop out of selection / cursor. |
-| `clearItems()` | Drop everything. Resets selection / cursor and emits one empty `list-select`. |
+| `removeItems(keys)` | Remove items. Removed keys drop out of selection / cursor silently and are held pending. |
+| `clearItems()` | Drop everything. Resets selection / cursor and emits one empty `list-select`; the keys are held pending, so re-adding them restores the selection. |
 
 Selection, cursor, keyboard nav, search, filtering, `count`, `renderedCount`,
 `renderedKeys()` and `visibleKeys()` behave identically to element mode — all
@@ -442,7 +443,7 @@ grid.collapseAllGroups();
 
 - Groups appear in first-encounter order. Filters (`filterPredicate`, `itemFilterPredicate`, incremental filter) run first, so an emptied group loses its header and counts follow the filter.
 - **Collapsed groups** leave the effective order: not navigable, not rendered, not in select-all, range, marquee or drag-out. Their selection state is kept. A collapsed key is not auto-expanded by `focusKey()`.
-- Changing `groupBy` (from any path) clears the collapse state.
+- Changing `groupBy` (from any path) clears the collapse state. Saved collapse state from `setViewState()` that hasn't matched a group yet is kept.
 - **Layout:** in `grid` / `column` a header spans the full width and its items restart at column 0 beneath it. In `row` orientation the header is an inline cell of `group-header-width`.
 - **Keyboard:** Left/Right step through items, crossing groups. Up/Down keep the column, hop across headers and clamp on a short last row. Headers are never focused; collapsing is by click or the API.
 - Events: `list-group-toggle` `{ groupKey, collapsed }`, `list-group-change` `{ groupBy }`.
@@ -450,6 +451,58 @@ grid.collapseAllGroups();
 
 Differences from data-grid: group state is reset on every `groupBy` change, the empty key is labelled `(none)`, headers are skipped by arrow keys, and the collapse API and events are exposed.
 
+---
+
+## View state
+
+Snapshot and restore how the grid is showing its data, separately from the
+data. The contract is shared with the other list components; see
+[`docs/infra-view-state.md`](../../docs/infra-view-state.md).
+
+```ts
+import { bindViewState } from '@ixfx/components';
+
+bindViewState(grid, {
+  load: () => JSON.parse(localStorage.getItem(`photos-grid`) ?? `null`),
+  save: s => localStorage.setItem(`photos-grid`, JSON.stringify(s)),
+});
+grid.items = await fetchPhotos(); // pending state applies as items arrive
+```
+
+`kind`: `grid-list`. Type: `GridListViewState`.
+
+| Field | Shape | Meaning |
+|---|---|---|
+| `selected` | `string[]` | Selected item keys. |
+| `expanded` | `Record<string, boolean>` | Group key → open. Groups default open, so only collapsed groups (`false`) are recorded. |
+| `focus` | `string` | Keyboard-cursor key. Recorded only while the cursor was last moved by keyboard. |
+| `scroll` | `{ top, left?, anchor? }` | `anchor` is the first item of the first visible line plus the px offset into that line, along the main axis (`left` in `row` orientation, `top` otherwise). |
+
+Members: `getViewState(options?)`, `setViewState(state)`,
+`clearPendingViewState()`, and the debounced `view-state-change` event.
+
+Grid-specific behaviour:
+
+- Works the same in element mode (light-DOM children with `data-key`) and data
+  mode (`items` + `itemAdapter`). Keyless children have auto-assigned
+  positional keys, which never appear in view state.
+- A key counts as present when its item is in the effective order: an item
+  that is filtered out, or inside a collapsed group, keeps its saved selection
+  pending until it shows. Restoring `expanded` and `selected` together re-opens
+  groups first, so a saved selection inside a saved-open group resolves.
+- A collapsed group whose items all leave (data reset, filter) keeps its
+  collapsed state pending and is collapsed again when it comes back.
+  Restoring collapse state does not fire `list-group-toggle`.
+- Items that leave the data are deselected **without** a `list-select`; their
+  keys go pending and are re-selected (with a `list-select`) if they return.
+- A restored cursor puts the list in keyboard input mode, so it is shown and
+  recorded like a keyboard-moved cursor.
+- Scroll restore waits until the anchor item is present and the viewport is
+  measured, then until the content is long enough. It is cancelled by the
+  user's own wheel, touch, pointer or navigation key. The anchor is re-laid out
+  with the current geometry, so a different column count still lands on the
+  same item's line.
+
 ## Virtualisation
 
 Only the cells in (or near) the viewport are in the DOM — in both element and

package/docs-user/hyperbolic-tree.md

@@ -17,10 +17,11 @@ It implements the shared `TreeComponent` interface (see [`src/tree/README.md`](.
 7. [Targeting a specific node or edge](#targeting-a-specific-node-or-edge)
 8. [Custom edge rendering](#custom-edge-rendering)
 9. [Focus, selection, navigation](#focus-selection-navigation)
-10. [Events](#events)
-11. [Keyboard / pointer interaction](#keyboard--pointer-interaction)
-12. [CSS variables and parts](#css-variables-and-parts)
-13. [Types reference](#types-reference)
+10. [View state](#view-state)
+11. [Events](#events)
+12. [Keyboard / pointer interaction](#keyboard--pointer-interaction)
+13. [CSS variables and parts](#css-variables-and-parts)
+14. [Types reference](#types-reference)
 
 ---
 
@@ -56,6 +57,7 @@ el.root = {
 | `root` | `TreeNode \| undefined` | `undefined` | Root node of the tree |
 | `model` | `TreeDataModel \| undefined` | `undefined` | Shared data model; takes precedence over `loadChildren` |
 | `loadChildren` | `LoadChildrenCallback \| undefined` | `undefined` | Callback for lazy child loading |
+| `restoreLoads` | `boolean` | `true` | Whether restoring a saved `center` may load its unloaded ancestors. See [View state](#view-state) |
 | `interactionMode` (`interaction-mode`) | `'implicit' \| 'standard' \| 'manual'` | `'standard'` | Gesture mapping — see [`src/tree/README.md`](../tree/README.md#interactionmode-ixfx-tree-list--ixfx-miller-list) (`'checked'` is unsupported here) |
 | `selectionFilter` (`selection-filter`) | `'none' \| 'leaf' \| 'branch' \| 'all'` | `'all'` | Which node kinds can be selected |
 | `exclusivity` | `TreeExclusivity` | `'none'` | Accepted for interface compatibility, ignored |
@@ -252,6 +254,31 @@ el.navigateToNode(n => n.item.key === 'readme.md');
 const nodes = el.getNodes(); // ReadonlyArray<{ node: TreeNode; depth: number }>
 ```
 
+## View state
+
+Implements the shared view-state API (`getViewState()` / `setViewState()` / `clearPendingViewState()` / `view-state-change`) — see [`docs/infra-view-state.md`](../../docs/infra-view-state.md). `kind` is `hyperbolictree-list`.
+
+```typescript
+type HyperbolicTreeListViewState = ViewStateBase & {
+  center?: string[]; // key path from the root's children to the centred node; [] = root
+  zoom?: number;     // visual magnification (the `zoom` property)
+};
+```
+
+| Field | Meaning |
+|---|---|
+| `selected` | Selected item keys. |
+| `focus` | Keyboard cursor key — only recorded when the cursor was moved by keyboard or search navigation. |
+| `center` | The centred node, as a key path. A path rather than a lone key because keys may repeat across branches here (e.g. `readme.md` in many folders). |
+| `zoom` | Magnification. Not keyed: it doesn't depend on the data. |
+
+- **What isn't saved:** a free pan (dragging empty space) and the disk's rotation are raw transforms in the centred node's local frame — they break as soon as the data changes, so they are left out. A restored view sits exactly on `center`, unpanned.
+- **Data changes keep state.** A new `root`, a model `root` / `invalidate` event or a lazy load re-applies state by key. If the centred node goes away the view falls back to the root silently and `center` stays pending; selected nodes that go away are deselected silently and their keys stay pending.
+- **Lazy data.** With `restoreLoads` (default `true`), a saved `center` whose ancestors aren't loaded is reached by loading each one in turn via `loadChildren` / `model`.
+- **Events.** A restored selection fires `select`; a restored centre fires `focus` (no `expand`/`collapse`) and snaps rather than animating.
+- An explicit `focusOn()` (click, key, navigation) drops a pending `center`; any explicit selection change drops pending `selected`.
+- With repeated keys, a saved selection resolves to the first node (depth-first) with that key.
+
 ## Events
 
 All events **bubble** and are **composed**.

package/docs-user/icicle-tree.md

@@ -0,0 +1,36 @@
+# Icicle Tree
+
+`<ixfx-icicletree-list>` — an icicle (partition) view over tree data. Each depth is a band; each node a rectangle sized by its `valueAccessor` share of its parent. Clicking a branch zooms so it becomes the visual root, with its ancestors in a breadcrumb strip.
+
+It implements the shared `TreeComponent` interface (see [`src/tree/README.md`](../tree/README.md)). The [sunburst](../sunburst-tree/) is its polar counterpart.
+
+---
+
+## View state
+
+Implements the shared view-state API (`getViewState()` / `setViewState()` / `clearPendingViewState()` / `view-state-change`) — see [`docs/infra-view-state.md`](../../docs/infra-view-state.md). `kind` is `icicletree-list`.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `selected` | `string[]` | Selected `item.key`s |
+| `zoom` | `string[]` | Key path from the root's children to the zoom node; `[]` = full tree |
+| `focus` | `string` | Keyboard-cursor `item.key` (recorded only when the cursor was moved by keyboard) |
+| `scroll` | `{ top, left? }` | The host's scroll offset (pixels; rects aren't a linear list, so there is no anchor) |
+
+There is no `expanded` (expansion *is* zoom).
+
+```typescript
+const stop = bindViewState(el, {
+  load: () => JSON.parse(localStorage.getItem(`org`) ?? `null`),
+  save: s => localStorage.setItem(`org`, JSON.stringify(s)),
+});
+el.root = await fetchOrg(); // zoom + selection apply as their nodes arrive
+```
+
+- State for nodes not loaded yet stays pending and applies when they appear — whether the tree is reassigned, grown in place (then `requestUpdate()`), or lazily loaded. **Reassigning `root` keeps zoom, selection and cursor** where keys still exist; state for keys that have gone moves to pending (silently) and returns with them.
+- `zoom` is a path so a lazy tree can be opened down to it: while pending, the nodes along it are loaded one at a time via `loadChildren` / `model` (set `restoreLoads = false` to only apply it as the host loads them). A zoom node that moved elsewhere in the tree is still found by its key.
+- Restored selection fires `select`; a restored zoom fires `zoom` (and `expand`). Any explicit selection change drops pending selection; any explicit zoom (`zoomTo()`, `zoomOut()`, clicks, crumbs, `navigateTo()`…) drops a pending zoom.
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `restoreLoads` | `boolean` | `true` | Load nodes along a pending saved zoom path |

package/docs-user/index.json

@@ -1,7 +1,7 @@
 {
   "name": "@ixfx/components",
-  "version": "0.15.5",
-  "generated": "2026-10-23T07:10:01.881Z",
+  "version": "0.16.0",
+  "generated": "2026-10-23T13:15:45.063Z",
   "components": [
     {
       "name": "ac-text",
@@ -98,6 +98,11 @@
       "summary": "`<ixfx-hyperbolictree-list>` — a hyperbolic (Poincaré disk) browser over tree data. The focused node sits at the disk's center; its neighbourhood fans outward, shrinking toward the edge with tree-grap",
       "path": "docs-user/hyperbolic-tree.md"
     },
+    {
+      "name": "icicle-tree",
+      "summary": "`<ixfx-icicletree-list>` — an icicle (partition) view over tree data. Each depth is a band; each node a rectangle sized by its `valueAccessor` share of its parent. Clicking a branch zooms so it become",
+      "path": "docs-user/icicle-tree.md"
+    },
     {
       "name": "icons",
       "summary": "A centralized SVG icon system for `@ixfx/components`. Icons are stored by name, can be overridden globally, and all components that use a given icon re-render automatically when it changes.",
@@ -273,6 +278,11 @@
       "summary": "Three components share a common `TreeComponent` interface: **`ixfx-tree-list`**, **`ixfx-miller-list`**, and **`ixfx-crumb-navigation`**. This document describes the shared API, plus component-specifi",
       "path": "docs-user/tree.md"
     },
+    {
+      "name": "treemap",
+      "summary": "`<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 branc",
+      "path": "docs-user/treemap.md"
+    },
     {
       "name": "twosplit-layout",
       "summary": "A Lit web component that lays out two elements within a container with a split bar to adjust their proportions.",

package/docs-user/llms.txt

@@ -30,6 +30,7 @@ import '@ixfx/components/data-grid';
 - [grid-list](docs-user/grid-list.md): A virtualised grid of items — thumbnails, cards, or arbitrary slotted markup —
 - [grouped-item-lister](docs-user/grouped-item-lister.md): A meta-component that renders a typed item list using any sub-component you supply. Items can be displayed in a single sub-component (_ungrouped_ mode) or split into labelled groups, each with its own
 - [hyperbolic-tree](docs-user/hyperbolic-tree.md): `<ixfx-hyperbolictree-list>` — a hyperbolic (Poincaré disk) browser over tree data. The focused node sits at the disk's center; its neighbourhood fans outward, shrinking toward the edge with tree-grap
+- [icicle-tree](docs-user/icicle-tree.md): `<ixfx-icicletree-list>` — an icicle (partition) view over tree data. Each depth is a band; each node a rectangle sized by its `valueAccessor` share of its parent. Clicking a branch zooms so it become
 - [icons](docs-user/icons.md): A centralized SVG icon system for `@ixfx/components`. Icons are stored by name, can be overridden globally, and all components that use a given icon re-render automatically when it changes.
 - [incr-search](docs-user/incr-search.md): Utilities for incremental (type-ahead) search over data collections or DOM-backed lists.
 - [labelled-radial-input](docs-user/labelled-radial-input.md): A composite radial input that pairs an editable label (`ixfx-editable-number`) with a rotary dial (`ixfx-radial-input`). The two controls are always in sync — turning the dial updates the number, and 
@@ -65,6 +66,7 @@ import '@ixfx/components/data-grid';
 - [toolbar](docs-user/toolbar.md): Two components for building toolbars:
 - [transitory-label](docs-user/transitory-label.md): An inline text label that animates between values instead of changing instantly. Displays as `inline-block` and inherits text styling from its parent.
 - [tree](docs-user/tree.md): Three components share a common `TreeComponent` interface: **`ixfx-tree-list`**, **`ixfx-miller-list`**, and **`ixfx-crumb-navigation`**. This document describes the shared API, plus component-specifi
+- [treemap](docs-user/treemap.md): `<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 branc
 - [twosplit-layout](docs-user/twosplit-layout.md): A Lit web component that lays out two elements within a container with a split bar to adjust their proportions.
 - [util](docs-user/util.md): A tooltip component that renders a value with optional icon and formatted number display. Uses native render root (no shadow DOM).
 - [vertical-list](docs-user/vertical-list.md): A scrollable vertical list of items with selection, keyboard navigation, and incremental search. Items can be plain `<li>` elements declared in HTML or rich custom elements added programmatically. Lar

package/docs-user/miller.md

@@ -16,7 +16,8 @@ A Miller column component displays hierarchical data as multiple vertical column
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `root` | `MillerNode \| undefined` | — | The root node of the tree. Assigning a new root resets all columns and selection state. |
+| `root` | `MillerNode \| undefined` | — | The root node of the tree. Assigning a new root re-applies the open path, selection and cursor by key (see [View state](#view-state)); a rebased view is reset. |
+| `restoreLoads` | `boolean` | `true` | Whether restoring view state may call `loadChildren` / `model` to open a saved path through unloaded branches. |
 | `selectionMode` | `MillerSelectionMode` | `'implicit'` | Controls how items are selected. See [Selection Modes](#selection-modes) below. |
 | `selectedKeys` | `ReadonlySet<string>` (getter) / `Iterable<string>` (setter) | — | The set of currently selected item keys. Assigning replaces the entire selection and triggers a re-render. |
 | `loadChildren` | `MillerLoadChildrenCallback \| undefined` | — | Callback to load children for lazy nodes. If undefined, clicking a lazy node opens an empty column. |
@@ -57,18 +58,18 @@ Inherited from theme:
 navigateTo(keys: readonly string[], options?: { reveal?: 'edge' | 'center-if-hidden'; silent?: boolean }): boolean
 
 // Re-sync after children arrays were patched in place (used by MillerTreeController.sync()):
-// closes columns whose selected node was removed, then re-renders.
+// the open path and selection re-resolve by key; removed nodes close their
+// columns / are deselected, and come back if their key reappears.
 invalidateStructure(): void
 
 // Navigate to the first loaded node (breadth-first) matching a predicate.
 // Returns false if no match is found in the currently loaded tree.
 navigateToNode(predicate: (node: MillerNode) => boolean): boolean
 
-// Get current configuration (column widths, etc.)
-getConfig(): MillerConfig
-
-// Set configuration. Requires a full MillerConfig object.
-setConfig(config: MillerConfig): void
+// View state — see "View state" below
+getViewState(options?): MillerListViewState
+setViewState(state: Partial<MillerListViewState>): void
+clearPendingViewState(): void
 ```
 
 ### Events
@@ -190,10 +191,6 @@ type MillerNode = {
   item: MillerItem;
   children?: MillerNode[];  // undefined = unloaded, [] = confirmed empty
 };
-
-type MillerConfig = {
-  columnWidths: Record<number, number>;  // depth -> px
-};
 ```
 
 ### Per-item icon colour, text colour and badges
@@ -338,24 +335,58 @@ el.navigateToNode(node => node.item.label === 'System32');
 
 ### Column Resizing
 
-Columns can be resized by dragging the handle on the right edge of each column. The widths are persisted in the config:
+Columns can be resized by dragging the handle on the right edge of each
+column. Widths are part of the view state (`columnWidths`, keyed by depth):
 
 ```javascript
-// Serialize current state (e.g. to localStorage)
-const config = el.getConfig();
-localStorage.setItem('millerConfig', JSON.stringify(config));
-
-// Restore saved state
-el.setConfig(JSON.parse(localStorage.getItem('millerConfig')));
+el.setViewState({ columnWidths: { 0: 150, 1: 200, 2: 180 } });
 ```
 
-### Configuration
+### View state
+
+`getViewState()` / `setViewState()` snapshot and restore how the columns are
+showing the data, as plain JSON keyed by `item.key`. The component never
+stores it; `bindViewState()` wires it to storage. See
+[docs/infra-view-state.md](../../docs/infra-view-state.md).
 
 ```javascript
-// Set custom column widths (depth index → width in px)
-el.setConfig({ columnWidths: { 0: 150, 1: 200, 2: 180 } });
+import { bindViewState } from '@ixfx/components';
+
+bindViewState(el, {
+  load: () => JSON.parse(localStorage.getItem('miller') ?? 'null'),
+  save: s => localStorage.setItem('miller', JSON.stringify(s)),
+});
+el.root = await fetchRoot(); // saved state applies as nodes arrive
 ```
 
+`kind: 'miller-list'`. Fields:
+
+| Field | Type | Meaning |
+|---|---|---|
+| `path` | `string[]` | Key of the open branch at each depth, column 0 first, relative to the view root. |
+| `selected` | `string[]` | `selectedKeys` (the checked set in `checked` mode). |
+| `focus` | `string` | Keyboard cursor key, only when last moved by keyboard. |
+| `columnWidths` | `Record<string, number>` | User-resized widths in px, keyed by depth. |
+| `columnScroll` | `Record<string, ScrollState>` | Scroll of each scrolled column, keyed by the key of the node whose children it lists (the view root's key for column 0). |
+
+`path` is an ordered array rather than the shared `expanded` record because a
+Miller view has exactly one open branch per column.
+
+- State for keys not loaded yet stays **pending** and applies as nodes appear:
+  a new `root`, `invalidateStructure()` after children were patched in place,
+  or a lazy load. A saved path `a > b > c` opens as each node arrives.
+- With `restoreLoads` (default `true`) a saved path through unloaded branches
+  is opened via `loadChildren` / `model`, one load at a time, so it cascades.
+- New `root` data keeps the open path, selection and cursor for keys that
+  still exist; keys that left go pending (deselected silently) and come back
+  if they reappear. Restored selection fires `select` with
+  `origin: 'programmatic'`.
+- Any explicit selection change drops pending selection; any explicit
+  navigation (click, arrow keys, `navigateTo`, rebasing) drops the pending
+  path. The view root itself is not part of the state.
+- `view-state-change` fires (debounced) on selection, navigation, keyboard
+  cursor moves, column resize and column scroll.
+
 ---
 
 ## MillerTreeController

package/docs-user/multicol-list.md

@@ -22,14 +22,14 @@ provider returns that column's choices; items may carry a `count` for display.
 | `selectionMode` | `ListSelectionMode` | `'multiple'` | `'none'`, `'single'` or `'multiple'` selection within a column. |
 | `minColumns` | `number` | `1` | Floor for column removal. |
 | `maxColumns` | `number` | `5` | Ceiling for column addition; `0` = unlimited. |
-| `columns` | `readonly MulticolColumnState[]` (getter) | — | Current per-column config: `id`, `categoryKey`, `sort`, `grouped`, `menu` (default `true`), `width`. Persist this to restore a layout. |
 
 ### Methods
 
 ```typescript
-// Restore a saved layout. Matching ids re-use live columns; unknown categories are skipped.
-// A first assignment suppresses the default auto-seeded column.
-setColumns(states: readonly MulticolColumnState[]): void
+// View state: column layout, per-column selection and scroll (see below)
+getViewState(options?: GetViewStateOptions<MulticolListViewState>): MulticolListViewState
+setViewState(state: Partial<MulticolListViewState>): void
+clearPendingViewState(): void
 
 // Add a column for a category key, optionally at a position.
 addColumn(categoryKey: string, position?: number): void
@@ -49,15 +49,16 @@ clearSelection(): void
 autoSizeColumns(options?: { minWidth?: number; maxWidth?: number }): Promise<void>
 ```
 
-Without `setColumns`, the element auto-seeds one column (the first category) once
-`categories` is assigned.
+Unless a layout is restored with `setViewState({ columns })`, the element auto-seeds
+one column (the first category) once `categories` is assigned.
 
 ### Events
 
 | Event | Detail | Description |
 |-------|--------|-------------|
 | `multicol-select` | `{ columnId, columns }` | A column's selection changed. `columns` is a full snapshot (see `getSelection`). |
-| `multicol-columns-change` | `{ columns, reason }` | Column layout changed. `reason` is one of `'add' \| 'remove' \| 'reorder' \| 'category' \| 'sort' \| 'grouping' \| 'resize'`. Resize fires **once on pointer-up** with the final width — never during the drag. |
+| `multicol-columns-change` | `{ columns, reason }` | Column layout changed. `columns` is the live layout (`MulticolColumnState[]`, as in view state). `reason` is one of `'add' \| 'remove' \| 'reorder' \| 'category' \| 'sort' \| 'grouping' \| 'resize'` (a view-state restore reports `'add'`). Resize fires **once on pointer-up** with the final width — never during the drag. |
+| `view-state-change` | `{ state, reason }` | Debounced view-state snapshot; see [View state](#view-state). |
 
 ---
 
@@ -78,6 +79,47 @@ at the top, selected by default. Choosing values clears All; choosing All clears
 
 ---
 
+## View state
+
+Implements the shared view-state contract (`docs/infra-view-state.md`); `kind` is
+`multicol-list`. Persist it with `bindViewState()`:
+
+```typescript
+import { bindViewState } from '@ixfx/components';
+
+bindViewState(el, {
+  load: () => JSON.parse(localStorage.getItem(`photos-facets`) ?? `null`),
+  save: s => localStorage.setItem(`photos-facets`, JSON.stringify(s)),
+});
+```
+
+| Field | Type | Meaning |
+|---|---|---|
+| `columns` | `MulticolColumnState[]` | Layout in display order: `{ id, categoryKey, sort, grouped, menu?, width? }`. |
+| `selectedByColumn` | `Record<columnId, string[]>` | Selected item keys per column. A column that's absent (or `[]`) is at 'All'. |
+| `scrollByColumn` | `Record<columnId, ScrollState>` | Each column list's scroll, anchored to the first visible item key. |
+
+The shared `selected` / `scroll` / `focus` / `expanded` fields are not used.
+
+- **`columns`** re-uses live columns by `id` (re-pointing the category if it differs,
+  which resets that column to 'All' and applies the category defaults, then the
+  saved `sort` / `grouped` / `width`), creates the others, reorders to match and
+  removes columns not listed. A non-empty layout suppresses auto-seeding. A column
+  whose category isn't in `categories` stays **pending** and is inserted at its
+  saved position once `categories` includes it.
+- **Selection** keys a column's data doesn't contain stay pending and are selected
+  when items with those keys arrive (firing the normal `multicol-select` and
+  cascade). Keys that leave a column's data are deselected and go pending. Any
+  explicit selection change (click, the All row, `clearSelection()`) drops all
+  pending selection. Selection saved for a column id that doesn't exist yet is
+  handed over when that column is restored.
+- **Scroll** waits until the anchor item has rendered; the user scrolling the
+  column cancels it.
+- `getViewState()` includes pending state by default (`{ includePending: false }`
+  for live state only).
+
+---
+
 ## Header interactions
 
 - **Category label** — opens a menu of all categories; the current one is disabled.
@@ -126,7 +168,7 @@ el.dataProvider = (query: MulticolQuery, signal) => {
 };
 
 el.addEventListener(`multicol-select`, (event) => {
-  saveLayout(event.detail.columns);
+  showResults(event.detail.columns);
 });
 ```
 

package/docs-user/split-layout.md

@@ -12,7 +12,7 @@ A Lit web component that lays out any number of panels along one axis with dragg
 |-----------|------|---------|-------------|
 | `direction` | `row` \| `column` | `row` | Split direction. `row` creates side-by-side panels, `column` creates stacked panels. |
 | `sizes` | string | `''` | Positional weight shorthand, e.g. `"1 2 1"`, applied to children lacking an explicit `size`. |
-| `storageKey` | string | `''` | Enables `localStorage` persistence. |
+| `forget-absent` | boolean | `false` | Don't keep the saved size of children that leave (see [View state](#view-state)). |
 | `gutterSize` | string | — | Convenience mirror of `--split-gutter-size`. |
 | `snap` | string | — | Convenience mirror of `--split-snap`. |
 
@@ -116,7 +116,8 @@ Nested `<ixfx-split-layout>` elements create sub-groups:
 | `ixfx-split-collapse` | `{ id: string; index: number }` | no | Panel collapsed (drag or API). |
 | `ixfx-split-expand` | `{ id: string; index: number }` | no | Panel expanded. |
 | `ixfx-split-close` | `{ id: string; index: number }` | **yes** | Before a panel is removed; `preventDefault()` vetoes. |
-| `ixfx-split-change` | `{ layout: LayoutSnapshot }` | no | After any size/structure change (persistence hook). |
+| `ixfx-split-change` | `{ layout: LayoutSnapshot }` | no | After any size/structure change. For persistence use [view state](#view-state). |
+| `view-state-change` | `{ state: SplitLayoutViewState; reason }` | no | Debounced; see [View state](#view-state). |
 
 ---
 
@@ -194,25 +195,52 @@ split.beginGutterDrag(0, event.pointerId, event.clientX, event.clientY);
 handle that starts this drag alongside perpendicular drags on other nested
 layouts, resizing several splits with one gesture.
 
-### Layout Serialization
+---
 
-```javascript
-// Get current layout
-const layout = split.getLayout();
-// { version: 1, root: { kind: 'group', id: 'g-0', children: [...] } }
+## View state
 
-// Restore a layout
-split.setLayout(layout);
-```
+`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
+`bindViewState()`.
 
----
+```ts
+import { bindViewState } from '@ixfx/components';
 
-## Persistence
-
-Set `storage-key` to enable automatic localStorage persistence:
+bindViewState(split, {
+  load: () => JSON.parse(localStorage.getItem(`editor-split`) ?? `null`),
+  save: s => localStorage.setItem(`editor-split`, JSON.stringify(s)),
+});
 
-```html
-<ixfx-split-layout storage-key="my-app-layout" ...>
+split.getViewState();
+// { v: 1, kind: 'split-layout',
+//   layout: { editor: { weight: 0.7 }, terminal: { weight: 0.3, collapsed: true } } }
 ```
 
-The layout is saved automatically after each change and restored on page load.
+| Field | Type | Meaning |
+|---|---|---|
+| `layout` | `Record<id, { weight: number; collapsed?: boolean }>` | `weight` is the child's share (0..1) of the weighted flow; for a collapsed child, the share it expands back to. `collapsed` absent ⇒ expanded. |
+
+- **Keyed by `id`.** Children without an `id` (and nested layouts without
+  one) are not saved — generated ids are positional. A nested
+  `ixfx-split-layout` with an `id` is saved as one entry (its share in this
+  layout); its own children are in *its* view state.
+- **Pending.** An entry whose child isn't slotted yet is kept and applied when
+  a child with that id appears; a child that leaves goes back to pending, so
+  removing and re-adding it restores its size. `getViewState()` includes
+  pending entries (pass `includePending: false` to leave them out);
+  `clearPendingViewState()` drops them.
+- **Partial.** Children without an entry keep their relative size and share
+  what the restored children leave.
+- **Events.** `view-state-change` fires (debounced) after a gutter drag ends,
+  collapse / expand, close, `setSizes()`, and when pending entries are applied
+  (`reason: 'restore'`).
+- `forget-absent` (boolean attribute) turns off the pending behaviour for
+  children that leave — for hosts that drive child sizes themselves (used
+  by `ixfx-dock-host`).
+
+A rebuild caused by children being added / removed keeps the live (e.g.
+dragged) sizes of children that stayed; a changed `size` / `weight` /
+`sizes` / `fixed` / `collapsed` attribute on a direct child or the layout
+makes the DOM the source of truth again.

package/docs-user/sunburst-tree.md

@@ -17,7 +17,8 @@ It implements the shared `TreeComponent` interface (see [`src/tree/README.md`](.
 7. [Zoom, selection, navigation](#zoom-selection-navigation)
 8. [Events](#events)
 9. [Keyboard / pointer interaction](#keyboard--pointer-interaction)
-10. [CSS variables and parts](#css-variables-and-parts)
+10. [View state](#view-state)
+11. [CSS variables and parts](#css-variables-and-parts)
 
 ---
 
@@ -26,7 +27,7 @@ It implements the shared `TreeComponent` interface (see [`src/tree/README.md`](.
 - **Expand/collapse is reinterpreted as zoom.** `expand` fires on zoom-in, `collapse` on zoom-out.
 - **`interactionMode` drops `'checked'`**; **`exclusivity` is accepted but ignored**.
 - **`filterPredicate` dims** non-matching arcs instead of hiding them.
-- **Reassigning `root` keeps zoom and selection** wherever the same key paths still exist (the icicle and treemap reset instead). See [Progressive data](#progressive-data).
+- **Reassigning `root` keeps zoom and selection** wherever the same key paths still exist; state whose path has gone stays pending and comes back with it. See [Progressive data](#progressive-data) and [View state](#view-state).
 - Drag-and-drop is out of scope.
 
 ## Data model
@@ -171,6 +172,35 @@ All events **bubble** and are **composed**. `depth` counts from the root's child
 | `Enter` | Select, activate and zoom in |
 | `Escape` / `Backspace` | Zoom up one level |
 
+## 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`.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `selected` | `string[]` | Selected `item.key`s |
+| `zoom` | `string[]` | Key path from the root's children to the centre node; `[]` = full tree |
+| `focus` | `string` | Keyboard-cursor `item.key` (recorded only when the cursor was moved by keyboard) |
+
+There is no `expanded` (expansion *is* zoom) and no `scroll`.
+
+```typescript
+const stop = bindViewState(el, {
+  load: () => JSON.parse(localStorage.getItem(`disk`) ?? `null`),
+  save: s => localStorage.setItem(`disk`, JSON.stringify(s)),
+});
+el.root = await scan(); // zoom + selection apply as their nodes arrive
+```
+
+- State for nodes not loaded yet stays pending and applies when they appear — whether the tree is reassigned, grown in place, or lazily loaded. A data change that removes the zoom node or a selected node moves it back to pending (silently), so it returns with its path.
+- `zoom` is a path because keys only need to be unique among siblings. While it is pending, the nodes along it are loaded one at a time via `loadChildren` / `model` (set `restoreLoads = false` to only apply it as the host loads them).
+- Live selection follows its key path across data changes. A restored `selected` key matches the first node, depth-first, carrying it — so with repeated keys (`readme.md` in many folders) a restored selection can land on a different node.
+- Restored selection fires `select`; a restored zoom fires `zoom` (and `expand`). Any explicit selection change drops pending selection; any explicit zoom (`zoomTo()`, clicks, `navigateTo()`…) drops a pending zoom.
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `restoreLoads` | `boolean` | `true` | Load nodes along a pending saved zoom path |
+
 ## CSS variables and parts
 
 | Variable | Default | Description |