@ixfx/components 0.15.5 → 0.16.1

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 |

package/docs-user/tree.md

@@ -20,6 +20,7 @@ Three components share a common `TreeComponent` interface: **`ixfx-tree-list`**,
 7. [ARIA](#aria)
 8. [CSS variables](#css-variables)
 9. [Controller authoring guide](#controller-authoring-guide)
+10. [View state](#view-state-ixfx-tree-list)
 
 ---
 
@@ -148,11 +149,12 @@ These properties are present on all three components (`ixfx-tree-list`, `ixfx-mi
 | `interactionMode` | `TreeInteractionMode` | `'standard'` | How gestures map to selection changes (`ixfx-tree-list` / `ixfx-miller-list` only) |
 | `selectionFilter` | `'none' \| 'leaf' \| 'branch'` | `'leaf'` | Which node kinds can be selected (reflected attribute) |
 | `alignCheckboxes` (`align-checkboxes`) | `boolean` | `false` | In `checked` mode, unselectable rows keep the space their checkbox would take so they line up with selectable siblings (`ixfx-tree-list` only). See [Unselectable items](#unselectable-items-selectable-aligncheckboxes) |
-| `filterPredicate` | `TreeFilterPredicate \| undefined` | `undefined` | Filter; only matching nodes and their ancestors are rendered (non-matching rows are not in the DOM, keyboard navigation, `selectAll` and Shift-range skip them) |
+| `filterPredicate` | `TreeFilterPredicate \| undefined` | `undefined` | Filter; only matching nodes and their ancestors are rendered (non-matching rows are not in the DOM; keyboard navigation, `selectAll`/`deselectAll` and Shift-range skip them) |
 | `exclusivity` | `'none' \| 'depth' \| 'global'` | `'none'` | Expansion exclusivity (reflected attribute) |
 | `stickyHeaders` (`sticky-headers`) | `boolean` | `true` | VS Code-style sticky headers; set `sticky-headers="false"` to opt out (`ixfx-tree-list` only) |
 | `virtualize` | `'auto' \| 'on' \| 'off'` | `'auto'` | Render only the rows near the viewport; `auto` switches on above `virtualizeThreshold` visible rows (`ixfx-tree-list` only). See [Virtualisation](#virtualisation-ixfx-tree-list) |
 | `virtualizeThreshold` (`virtualize-threshold`) | `number` | `200` | Visible-row count above which `virtualize="auto"` windows the list |
+| `scrollHoverTickle` (`scroll-hover-tickle`) | `boolean` | `false` | Let the hover cursor follow rows that scroll beneath a stationary pointer. Off by default: during a scroll gesture row `pointerenter` is ignored (host carries `data-scroll-hover-suppress`), so the hover highlight and `tickle` hold still instead of trailing the content. Hover resumes on the next real pointer movement or when the pointer leaves |
 | `animation` | `'auto' \| 'always' \| 'never'` | `'auto'` | Controls row enter/leave animations. `'auto'` respects `prefers-reduced-motion`; `'always'` always animates; `'never'` skips all animations. Can be overridden per-call on `expandAll`, `collapseAll`, `navigateTo`, `revealKey`, and `navigateToNode` |
 
 ### Replacing `root`
@@ -387,14 +389,14 @@ el.selectAll();
 el.deselectAll();
 ```
 
-`selectAll()` and `deselectAll()` behaviour depends on `interactionMode`:
+`selectAll()` selects every selectable node in the tree, including nodes inside collapsed branches (unloaded lazy children are not included). `deselectAll()` deselects the same set. Pass `{ visibleOnly: true }` to act only on the rows that are showing; Ctrl+A and the `select-all` command do this.
 
-| Mode | `selectAll()` | `deselectAll()` |
+| Mode | `selectAll()` | `selectAll({ visibleOnly: true })` |
 |------|---------------|-----------------|
-| `checked` | Checks the checkbox of each visible node (recursively toggles descendants) | Unchecks each visible node |
-| All other modes | Adds every visible selectable node to the selection | Clears the selection |
+| `checked` | Checks every selectable node | Same: checking a row checks its descendants |
+| All other modes | Adds every selectable node to the selection | Adds the showing selectable rows |
 
-While a `filterPredicate` is active, `selectAll()` / `deselectAll()` and Shift-range selection cover only the rows that are shown (as in `ixfx-vertical-list`).
+While a `filterPredicate` is active, `selectAll()` / `deselectAll()` cover only the matching nodes (and their matching ancestors), and Shift-range selection covers only the rows that are shown (as in `ixfx-vertical-list`). `deselectAll()` leaves selected nodes the filter hides alone.
 
 Both methods dispatch a single `select` event with the full old and new selection sets. `selectAll` respects `selectionFilter` — only nodes that pass the filter are selected.
 
@@ -455,6 +457,43 @@ Notes:
 
 ---
 
+## View state (`ixfx-tree-list`)
+
+Snapshot and restore selection, expansion, keyboard cursor and scroll
+separately from the data — see [`docs/infra-view-state.md`](../../docs/infra-view-state.md)
+for the shared contract. `kind: 'tree-list'`; fields `selected`, `expanded`,
+`focus`, `scroll`, all keyed by `item.key`.
+
+```typescript
+import { bindViewState } from '@ixfx/components';
+
+bindViewState(tree, {
+  load: () => JSON.parse(localStorage.getItem(`tree`) ?? `null`),
+  save: s => localStorage.setItem(`tree`, JSON.stringify(s)),
+});
+tree.root = initialRoot; // any time, before or after
+```
+
+- **Keys, not nodes.** Replacing `root` keeps selection, expansion and cursor
+  for every key the new root still has. State for keys that disappear is kept
+  *pending* and comes back if they reappear — expand `C`, swap in a root
+  without it, swap back, and `C` is open again.
+- **Built up over time.** `setViewState({ expanded: { A: true, B: true, C: true } })`
+  then grow the tree (new `root`, or mutate `children` + `invalidateStructure()`):
+  each branch opens as it arrives.
+- **Lazy trees.** With `restoreLoads` (default `true`) saved-open branches that
+  aren't loaded are fetched through `loadChildren` / `model`, one at a time, so
+  a saved path cascades open. `el.restoreLoads = false` to only open branches
+  the host loads itself.
+- **Selection.** A restored key fires the normal `select` event
+  (`origin: 'programmatic'`). Any explicit selection change — click, key,
+  `select()`, `clearSelection()` — drops a saved selection that hasn't matched yet.
+- **Scroll** is saved as the first visible row's key plus an offset, and is
+  applied once that row exists. The user's own scroll cancels it.
+- `focus` is recorded only for a keyboard-moved cursor, not mouse hover.
+
+---
+
 ## Events
 
 All events **bubble** and are **composed** (cross shadow-DOM boundaries).

package/docs-user/treemap.md

@@ -0,0 +1,32 @@
+# Treemap
+
+`<ixfx-treemap-list>` — a nested-area (treemap) view over tree data. The zoom root fills the viewport; each node's rectangle is subdivided among its children by `valueAccessor` share. Clicking a branch zooms into it, and ancestors collapse into a breadcrumb strip. It implements the shared `TreeComponent` interface (see [`src/tree/README.md`](../tree/README.md)). See the class docs in `treemap-list.ts` for properties and events.
+
+---
+
+## View state
+
+Implements the shared view-state API (`getViewState()` / `setViewState()` / `clearPendingViewState()` / `view-state-change`) — see [`docs/infra-view-state.md`](../../docs/infra-view-state.md). `kind` is `treemap-list`.
+
+```typescript
+type TreemapListViewState = ViewStateBase & {
+  zoom?: string[]; // key path from the root's children to the zoom root; [] = full tree
+};
+```
+
+| Field | Meaning |
+|---|---|
+| `selected` | Selected item keys. |
+| `focus` | Keyboard cursor key. It is only recorded when the cursor was moved by keyboard or search navigation. |
+| `zoom` | The zoomed-into node, as a key path. The target is matched by key anywhere in the tree. The ancestors in the path only matter when the target isn't loaded yet. |
+
+There is no `expanded` (zoom stands in for it) and no `scroll` (the treemap fills its box).
+
+- **Data changes keep state.** A new `root`, a model `root` / `invalidate` event or a lazy load re-applies state by key. If the zoom root goes away, the view falls back to the full tree silently and `zoom` stays pending. Selected nodes that go away are deselected silently and their keys stay pending.
+- **Lazy data.** With `restoreLoads` (default `true`), a saved `zoom` whose target isn't loaded yet is reached by loading each ancestor in turn via `loadChildren` / `model`.
+- **Events.** A restored selection fires `select`. A restored zoom fires `zoom` (not `expand`/`collapse`) and doesn't animate.
+- An explicit zoom (click, key, wheel, crumbs, `zoomTo()` / `zoomOut()`) drops a pending `zoom`. Any explicit selection change drops pending `selected`.
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `restoreLoads` | `boolean` | `true` | Whether restoring a saved `zoom` may load its unloaded ancestors. |

package/docs-user/twosplit-layout.md

@@ -46,6 +46,28 @@ theme it with the `--ixfx-handle-*` variables (see
 | Event | Detail | Description |
 |-------|--------|-------------|
 | `ixfx-split-collapsed` | `{ panel: 'A' \| 'B', collapsed: boolean }` | Fired when a panel is collapsed or uncollapsed via drag. |
+| `view-state-change` | `{ state: TwoSplitLayoutViewState, reason }` | Debounced, after a drag that changed the sizes and after `setViewState()`. See [View state](#view-state). |
+
+### View state
+
+`getViewState()` / `setViewState()` snapshot and restore both sides as plain
+JSON (`kind: 'twosplit-layout'`), keyed by slot name. The component never
+persists anything itself — see
+[docs/infra-view-state.md](../../docs/infra-view-state.md) and `bindViewState()`.
+
+```ts
+split.getViewState();
+// { v: 1, kind: 'twosplit-layout', layout: { a: { size: '30%' }, b: { size: '70%' } } }
+split.setViewState({ layout: { a: { size: '0px', collapsed: true }, b: { size: '100%' } } });
+```
+
+| Field | Type | Meaning |
+|---|---|---|
+| `layout` | `{ a?, b?: { size: string; collapsed?: boolean } }` | `size` as in `sizeA` / `sizeB`; `collapsed` absent ⇒ expanded. A side missing from a restored `layout` is left as it is. |
+
+Both slots always exist, so nothing is ever pending (`clearPendingViewState()`
+is a no-op). Note the `layout` *field* is unrelated to the `layout`
+(orientation) attribute.
 
 ---
 

package/docs-user/user-catalog.md

@@ -124,7 +124,7 @@ A meta-component that renders a typed item list using any sub-component you supp
 ## Layout Components
 
 ### ixfx-dock-host / ixfx-dock-panel
-A dockable panel system in the style of VS Code. Author a flat pool of `ixfx-dock-panel` elements inside an `ixfx-dock-host`; drag panels by titlebar or tab to tab them together, split panels horizontally/vertically, or drag between hosts. Layouts serialize via `saveLayout()` / `loadLayout()` for persistence. Drop restrictions are available per host (`accepts` attribute, `canAccept()` callback) and per panel (`accepts`). Use for IDE-like workspaces, dashboards, or any composable multi-panel UI.
+A dockable panel system in the style of VS Code. Author a flat pool of `ixfx-dock-panel` elements inside an `ixfx-dock-host`; drag panels by titlebar or tab to tab them together, split panels horizontally/vertically, or drag between hosts. Layouts save and restore via `getViewState()` / `setViewState()` (see `docs/infra-view-state.md`). Drop restrictions are available per host (`accepts` attribute, `canAccept()` callback) and per panel (`accepts`). Use for IDE-like workspaces, dashboards, or any composable multi-panel UI.
 
 ### ixfx-split-layout
 A resizable n-way split pane that allows users to adjust the proportion between adjacent sections. Supports `row`/`column` directions, positional `sizes` weights, per-child `size`/`min`/`collapsed` attributes, and nested splits for cross-axis layouts. Use for editor layouts, file explorers with previews, or any interface where users need to control space allocation.

package/docs-user/vertical-list.md

@@ -20,8 +20,9 @@ A scrollable vertical list of items with selection, keyboard navigation, and inc
 12. [Context menu](#context-menu)
 13. [In-place rename](#in-place-rename)
 14. [Virtualisation](#virtualisation)
-15. [CSS variables](#css-variables)
-16. [CSS parts](#css-parts)
+15. [View state](#view-state)
+16. [CSS variables](#css-variables)
+17. [CSS parts](#css-parts)
 
 ---
 
@@ -387,7 +388,8 @@ list.addItem(myElement);
 // In checked mode, add a row that shows no checkbox and can't be checked
 list.addItem('Header', { notChecked: true });
 
-// Remove a specific element (returns a Promise that resolves once it's gone)
+// Remove a specific element (returns a Promise that resolves once it's gone).
+// A selected item is deselected silently; its key stays pending (see View state).
 list.removeItem(element);
 list.removeItems(list.selectedItems);
 
@@ -453,12 +455,13 @@ list.addEventListener('list-select', ({ detail }) => {
 });
 ```
 
-Restore a selection across a data reload:
+Selection survives a data reload by itself: keys of selected items that
+leave the list (`clearItems`, `removeItem`, a DOM removal, an adapter rebuild)
+go pending and are re-selected when items with the same keys come back.
 
 ```typescript
-const keep = [...list.selectedKeys];
-list.setItems(await fetchRows());     // Element refs are now stale
-list.selectKeys(keep);               // ...but the keys still resolve
+list.clearItems();
+list.setItems(await fetchRows());     // previously-selected keys re-select
 ```
 
 The `data-key` requirement is documented, not enforced: items without a key
@@ -768,6 +771,51 @@ dispatch. Mirrors `ixfx-grid-list`'s `grid-list-viewport-change`.
 
 ---
 
+## View state
+
+The list implements the shared view-state API (see `docs/infra-view-state.md`):
+snapshot *how* it shows its items as plain JSON and restore it later, before or
+after the items exist. Kind: `vertical-list`. All state is keyed by each row's
+`data-key` / `data-value`, so rows without a key don't take part.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `selected` | `string[]` | Selected keys. In `checked` mode this is the checked set. |
+| `focus` | `string` | Keyboard cursor key. Only recorded while the cursor was last moved by keyboard. |
+| `scroll` | `{ top, left?, anchor?: { key, offset } }` | First visible row's key plus px offset into it. Works with `virtualize` too. |
+
+```typescript
+import { bindViewState } from '@ixfx/components';
+
+bindViewState(list, {
+  load: () => JSON.parse(localStorage.getItem('files') ?? 'null'),
+  save: s => localStorage.setItem('files', JSON.stringify(s)),
+});
+
+list.getViewState();                       // { v: 1, kind: 'vertical-list', selected, focus, scroll }
+list.setViewState({ selected: ['a'] });    // partial: only fields present apply
+list.clearPendingViewState();
+list.addEventListener('view-state-change', e => e.detail /* { state, reason } */);
+```
+
+- **Pending state.** Keys that aren't in the list yet stay pending and apply as
+  matching rows arrive through `addItem`, `setItems`, a plain `appendChild`, an
+  `items` rebuild, or a virtual registry change. `getViewState()` includes pending
+  state by default (`includePending: false` leaves it out).
+- **Selection.** A restored selection fires the normal `list-select`. Any explicit
+  selection change (click, key, `select*()`, `clearSelection()`) drops pending
+  selection. A selected row that leaves the list is deselected **silently** (no
+  `list-select`) and its key goes pending.
+- **Scroll** is applied once the anchor row exists and the list is laid out
+  (it is retried on data changes and resizes). The user's own wheel, touch,
+  pointer or navigation key cancels a pending scroll.
+- **Focus.** A keyboard cursor whose row leaves the list goes pending and comes
+  back when the key reappears. Moving the cursor by keyboard, or `focusKey()`,
+  drops a pending one.
+- `view-state-change` is debounced (150 ms), bubbles and is composed.
+
+---
+
 ## CSS variables
 
 | Variable | Default | Description |

package/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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ixfx/components",
   "type": "module",
-  "version": "0.15.5",
+  "version": "0.16.1",
   "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",