@ixfx/components 0.15.5 → 0.16.1

package/docs-user/dock.md

@@ -63,7 +63,7 @@ The tree is plain and mutable, owned exclusively by the host.
 
 Named containers: give a stack leaf `name` (e.g. `"primary-sidebar"`) in the
 initial layout JSON. Names must be unique per layout (first match wins),
-serialize with `saveLayout()` / `loadLayout()`, and render as
+are saved and restored with the [view state](#view-state), and render as
 `data-dock-name` on the leaf. Explicit leaf close still removes the stack.
 When a `tabs` drop empties a named stack into an *unnamed* one, the name
 (and its content rules) follows the panels to the merged leaf instead of
@@ -117,7 +117,7 @@ split resizes, and host resizes; handles are hidden during dock drags.
   `setLeafExclusiveContents(name, kinds)` admits only those kinds into the
   named leaf, `setLeafDenyContents(name, kinds)` refuses those kinds.
   `clearLeafContentRestrictions(name)` lifts both; `[]` seals (exclusive) or
-  lifts (deny). Rules are host policy — kept across `loadLayout()`, never
+  lifts (deny). Rules are host policy — kept across `setViewState()`, never
   serialized; already-docked panels are grandfathered.
 - Leaf placement policy — `setLeafPlacementPolicy(name, policy)` is a superset
   of the two calls above (`allowKinds` / `denyKinds`) plus `allowEdgeSplit`
@@ -181,7 +181,7 @@ While hidden:
 ## Events
 
 `ixfx-dock-host`: `dock-change` (`{ layout }` after structural mutations),
-`dock-panel-added`, `dock-panel-removed`, `dock-panel-activated`,
+`view-state-change` (debounced, see [View state](#view-state)), `dock-panel-added`, `dock-panel-removed`, `dock-panel-activated`,
 `dock-panel-drag-start`, `dock-panel-moved`, `dock-stack-empty`,
 `dock-tab-contextmenu`.
 
@@ -196,7 +196,7 @@ While hidden:
 - `dock-stack-empty` — `{ name, hostEmpty }` when a stack loses its last panel
   (`name` is the container name or `null`). `hostEmpty` is true when the host
   holds no panels at all — the cue to close an owning group. Fires before the
-  matching `dock-change`; not fired by `loadLayout()`.
+  matching `dock-change`; not fired by `setViewState()`.
 - `dock-tab-contextmenu` — `{ panelId, clientX, clientY }`, cancelable
   (`preventDefault()` suppresses the native menu). Visible tabs only; with a
   hidden strip handle `contextmenu` on your own element.
@@ -226,8 +226,11 @@ The host consumes `ixfx-split-layout` events: `ixfx-split-resize` /
 ## Public API — `ixfx-dock-host`
 
 ```ts
-saveLayout(): DockLayout                 // folds live split weights from the DOM
-loadLayout(layout: DockLayout): void
+getViewState(options?): DockHostViewState   // { v, kind: 'dock-host', layout }; folds live split weights
+setViewState(state: Partial<DockHostViewState>): void
+clearPendingViewState(): void               // drops placeholders (panels the host doesn't hold)
+saveLayout(): DockLayout                    // deprecated alias of getViewState().layout
+loadLayout(layout: DockLayout): void        // deprecated alias of setViewState({ layout })
 addPanel(panel: DockPanelElement | DockPanelInit, target?: DockAddPanelTarget): boolean
 type DockAddPanelTarget = {
   container?: string;   // named stack leaf — takes precedence over `stack`
@@ -258,6 +261,7 @@ getNeighbours(leaf: DockLeafRef): DockNeighbours | null
 moveLeaf(leaf: DockLeafRef, direction: 'up' | 'down' | 'left' | 'right'): boolean
 moveLeafToEdge(leaf: DockLeafRef, edge: 'top' | 'bottom' | 'left' | 'right'): boolean
 canAccept?: (panelId: string, op: DockOperation) => boolean
+placeholderLabel?: (panelId: string) => string   // tab label for placeholders (default: the id)
 
 // Cross-window hooks (serializable in/out; no element handoff)
 getPanelSnapshot(panelId: string): DockPanelSnapshot | null
@@ -427,13 +431,60 @@ it can measure.
 window. `acceptExternalPanel` returns `null` if that id is already docked in
 the target host (adopt / focus it yourself instead).
 
-## Serialization
+## View state
 
-`saveLayout()` folds live gutter weights from each rendered
-`ixfx-split-layout` (via `getSizes()`) into `DockSplitNode.sizes` before
-serializing, so a save → drag → save round-trip preserves user adjustments.
-`DockStackNode.collapsed` / `preCollapseSize` serialize so a saved layout can
-restore collapse state without a live element.
+The dock implements the shared view-state API
+([docs/infra-view-state.md](../../docs/infra-view-state.md)). The component
+never persists anything; the host does, e.g. with `bindViewState()`:
+
+```ts
+import { bindViewState } from '@ixfx/components';
+
+bindViewState(dock, {
+  load: () => JSON.parse(localStorage.getItem(`workspace`) ?? `null`),
+  save: s => localStorage.setItem(`workspace`, JSON.stringify(s)),
+});
+```
+
+| Field | Type | Meaning |
+|---|---|---|
+| `layout` | `DockLayout` | The whole tree: splits with `sizes`, stacks with tab order, `active`, `name`, `collapsed` / `preCollapseSize`, strip flags. Keyed by panel id. |
+
+The dock layout is close to structure, so the saved state *is* the tree
+(collapse and the active tab stay inside it rather than in separate
+`expanded` / `selected` fields).
+
+- `getViewState()` folds live gutter weights from each rendered
+  `ixfx-split-layout` (via `getSizes()`) into `DockSplitNode.sizes` first, so
+  a save → drag → save round-trip preserves user adjustments.
+- **Panels not in the host yet.** `setViewState()` keeps every panel id the
+  layout names, held or not. One the host doesn't hold is a *placeholder*:
+  it keeps its place in the tree (shown as a tab labelled by the
+  `placeholderLabel(panelId)` property, or its id when unset) and
+  the panel slots into that place when it arrives — appended as a light-DOM
+  child, `addPanel()` **without** a target, `acceptExternalPanel()` without
+  `at`, or a cross-host adoption. An explicit `addPanel()` target still wins.
+  Placeholders are saved by `getViewState()`; `includePending: false` leaves
+  them out (stacks they empty are dropped unless named). Remove one with
+  `removePanel(id)`, or all of them with `clearPendingViewState()`.
+- **Persisting with the default keeps stale ids.** A placeholder for a panel
+  that no longer exists is saved again on every `getViewState()`, so it never
+  goes away. Apps whose panels can disappear between save and restore should
+  call `clearPendingViewState()` once they have added the panels they hold,
+  or save with `includePending: false`.
+- Pooled panels the layout doesn't name are appended to the first stack
+  admitting their kind.
+- A panel that is closed / removed (`removePanel`, close button, removed from
+  the DOM, moved to another host) leaves the layout — closing is a structural
+  change, so its place is not remembered.
+- State set before the host is connected wins over the `layout` attribute.
+- A malformed `layout` (or a state for another `kind`) is ignored with a
+  warning.
+- `view-state-change` fires (debounced) after structural changes (drops,
+  add / remove, close, leaf moves), gutter resizes, collapse / expand and
+  tab activation. `reason` is `data` when the pool changed under the host,
+  `restore` for `setViewState()`. The dock's internal split layouts' own
+  `view-state-change` events don't escape the host.
 
 ## CSS variables
 

package/docs-user/flat-list.md

@@ -51,6 +51,7 @@ A node counts as a branch unless `item.isLeaf` is `true` or its `children` is `[
 | `beginEdit(key)` | Rename a row in place. Needs `validateEdit` and `item.editable`; `false` otherwise |
 | `registry` / `dispatch(id, args)` | The inner list's command registry, e.g. `dispatch('list.search.filter')` |
 | `list` | The inner `ixfx-vertical-list` |
+| `getViewState(options?)` / `setViewState(state)` / `clearPendingViewState()` | See [View state](#view-state) |
 
 ## Events
 
@@ -77,6 +78,32 @@ The inner list's `list-*` events also cross the shadow boundary, with row elemen
 
 Selection is cleared on every level change. Arrow Left and Backspace are ignored while the search field is focused.
 
+## View state
+
+The level shown and its selection, cursor and scroll, as plain JSON for the
+host to persist (see [docs/infra-view-state.md](../../docs/infra-view-state.md)):
+
+```ts
+{ v: 1, kind: 'flat-list', path: ['docs', 'work'], selected: ['a.txt'], focus: 'a.txt', scroll: { top: 0 } }
+```
+
+`selected`, `focus` and `scroll` belong to the level at `path`. They are held
+until that level is shown, then handed to the inner list, which applies them
+as its rows arrive (see the vertical-list README).
+
+- Keys not loaded yet stay pending: the list shows the deepest level it can
+  reach and continues as data arrives. Showing a level loads it (via
+  `loadChildren` / `model`), so a saved path through lazy levels loads one
+  level at a time.
+- If new data drops the level shown, the list steps up to the closest
+  ancestor and the level (with its selection) goes pending; it is returned to
+  when its keys reappear. This also applies to a `path` assigned before the
+  data has loaded.
+- An explicit navigation (gesture, `navigate*()`, or assigning `path`) drops
+  a pending level; an explicit selection drops a pending selection.
+- The inner crumb's and list's own `view-state-change` events are stopped at
+  this element; it fires its own.
+
 ## Drops
 
 With `items-droppable`, a drag over a row, or over empty space, is accepted unless `canDrop` refuses it. A drop fires `flat-list-drop` with that row's node, or the **current level's node** for empty space. Dropping on a branch row reports it and does **not** enter it. Native OS drags work: `dataTransfer` carries `files`, `text/uri-list` and any custom MIME type the source wrote. The row under the drag gets the vertical-list [drop highlight](../vertical-list/README.md#drop-targets).

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.
 
@@ -310,8 +311,11 @@ grid.registry.invoke('list.search.filter');   // or .navigate / .select
 
 Search matches `data-label` (or `[data-grid-list-caption]` text, then
 `data-search-label`, then `textContent`). Filter mode genuinely removes items
-from the virtualised layout. Add a page-level highlight rule to see matched
-characters:
+from the virtualised layout. Matched characters are highlighted under the
+`grid-list-search` key. In data mode (`itemAdapter`) the captions live in the
+shadow root and the grid styles them itself (`--search-highlight-bg` /
+`--search-highlight-color`, default `--accent` / `--accent-text`). In element
+mode the items are light DOM, so add a page-level rule:
 
 ```css
 ::highlight(grid-list-search) { background: var(--accent); color: var(--accent-text); }
@@ -402,11 +406,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 +446,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 +454,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.1",
+  "generated": "2026-10-26T15:36:19.925Z",
   "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