@ixfx/components 0.15.5 → 0.16.0

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

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

package/docs-user/README.md

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

package/docs-user/crumbs.md

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

package/docs-user/data-grid.md

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

package/docs-user/detail-list.md

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

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,9 @@ 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               // no-op: placeholders live in the layout tree
 addPanel(panel: DockPanelElement | DockPanelInit, target?: DockAddPanelTarget): boolean
 type DockAddPanelTarget = {
   container?: string;   // named stack leaf — takes precedence over `stack`
@@ -427,13 +428,54 @@ 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 with its id) and
+  the panel slots into that place when it arrives — appended as a light-DOM
+  child, `addPanel()` **without** a target, `acceptExternalPanel()` without
+  `at`, or a cross-host adoption. An explicit `addPanel()` target still wins.
+  Placeholders are saved by `getViewState()`; `includePending: false` leaves
+  them out (stacks they empty are dropped unless named). Remove one with
+  `removePanel(id)`; `clearPendingViewState()` is a no-op.
+- 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).