@ixfx/components 0.15.4 → 0.16.0

package/docs-user/sunburst-tree.md

@@ -0,0 +1,223 @@
+# Sunburst Tree
+
+`<ixfx-sunbursttree-list>` — a zoomable sunburst over weighted tree data. The zoom node is the centre disc; each ring outward is one generation, and each arc's angle is its share of its parent's value. Every change — data arriving, a different weighting, a zoom — animates from what's on screen to the new layout.
+
+It implements the shared `TreeComponent` interface (see [`src/tree/README.md`](../tree/README.md)), so `TreeDataModel`, `IncrSearchTreeController`, and `TreeComponent`-typed code work unmodified. Geometrically it is a polar [icicle](../icicle-tree/), and shares its API shape.
+
+---
+
+## Contents
+
+1. [Differences from `ixfx-tree-list`](#differences-from-ixfx-tree-list)
+2. [Data model](#data-model)
+3. [Values and weighting](#values-and-weighting)
+4. [Progressive data](#progressive-data)
+5. [Colour](#colour)
+6. [Properties](#properties)
+7. [Zoom, selection, navigation](#zoom-selection-navigation)
+8. [Events](#events)
+9. [Keyboard / pointer interaction](#keyboard--pointer-interaction)
+10. [View state](#view-state)
+11. [CSS variables and parts](#css-variables-and-parts)
+
+---
+
+## Differences from `ixfx-tree-list`
+
+- **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; 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
+
+Same `TreeNode` / `TreeItem` shapes as the rest of the tree family, including `root`, `model` and `loadChildren` for lazy loading (children are fetched for every visible arc).
+
+Keys only need to be unique **among siblings**: arcs are identified by their key *path* from the root, so file-system data — where `readme.md` recurs in many folders — works. Lookups that only have a bare key (`revealKey`) match the first node, depth-first, carrying it.
+
+## Values and weighting
+
+Every node — branches included — has a value. A child's arc is its share of its parent's:
+
+```
+childAngle = parentAngle × child / max(parent, Σ siblings)
+```
+
+- Children summing to **less** than their parent leave an unfilled gap — "unaccounted for" space (unscanned disk, an unknown remainder).
+- Children summing to **more** are scaled down to fit.
+
+Give values as a plain number on `item.weight` (the default accessor reads it), or as a function:
+
+```typescript
+el.root = {
+  item: { key: 'hd', label: 'Disk', weight: 500e9 },
+  children: [
+    { item: { key: 'apps', label: 'Applications', weight: 120e9 }, children: [] },
+    { item: { key: 'users', label: 'Users', weight: 300e9 }, children: [] },
+  ],
+};
+
+// Swap weighting scheme: no DOM is rebuilt, the chart animates to the new layout.
+el.valueAccessor = (item, node) => (item.data as Stats).fileCount;
+```
+
+`valueAccessor` is `(item, node) => number | undefined`. When it returns `undefined` (or a negative / non-finite number) the node falls back to the **sum of its loaded children**, or `1` for a leaf or not-yet-loaded node. So unweighted data shows descendant counts, and an accessor can value only leaves and let branches sum:
+
+```typescript
+el.valueAccessor = (item, node) => node.children ? undefined : Math.log2(bytes(item) + 1);
+```
+
+`valueFormatter` (`(value, node) => string`) formats the value in the centre readout:
+
+```typescript
+el.valueFormatter = v => `${(v / 1e9).toFixed(1)} GB`;
+```
+
+## Progressive data
+
+Any update re-lays out and animates: new arcs grow from zero width, removed ones shrink away, the rest slide to their new angles. An update arriving mid-animation retargets from wherever things currently are.
+
+Either rebuild the tree immutably and reassign it:
+
+```typescript
+el.root = snapshotOfScanSoFar(); // zoom + selection carry over by key path
+```
+
+or mutate in place and nudge the element — or let a `TreeDataModel` notify it:
+
+```typescript
+folder.children.push(newFile);
+el.requestUpdate();
+```
+
+## Colour
+
+Hue is set by the ring around the centre: each first-ring arc takes the hue at its angular midpoint (so the ring spans the colour wheel), and every descendant takes a tone of that hue — lighter and less saturated each ring out, with a small per-sibling shift so neighbours stay distinct. Zooming re-anchors hues to the new first ring, cross-fading as it goes. The centre disc mixes towards `--sunbursttree-center-color`.
+
+All of it is computed in CSS from per-arc custom properties, so the palette is themeable:
+
+| Per-arc property | Value |
+|---|---|
+| `--arc-hue` | Degrees, added to `--sunbursttree-hue-start` |
+| `--arc-depth` | Ring index from the centre (`0` = first ring) |
+| `--arc-shade` | Sibling-position offset, `-0.5..0.5` |
+| `--arc-centre` | `0..1`, how far the arc has become the centre disc |
+
+## Properties
+
+| Property (attribute) | Type | Default | Description |
+|---|---|---|---|
+| `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 |
+| `valueAccessor` | `SunburstValueAccessor` | `item => item.weight` | Node value. See [Values and weighting](#values-and-weighting) |
+| `valueFormatter` | `SunburstValueFormatter` | locale number | Formats the centre readout's value |
+| `interactionMode` (`interaction-mode`) | `'implicit' \| 'standard' \| 'manual'` | `'standard'` | Gesture mapping |
+| `selectionFilter` (`selection-filter`) | `'none' \| 'leaf' \| 'branch' \| 'all'` | `'all'` | Which node kinds can be selected |
+| `maxDepth` (`max-depth`) | `number` | `5` | Rings drawn around the centre |
+| `centerRatio` (`center-ratio`) | `number` | `0.22` | Centre disc radius as a fraction of the overall radius |
+| `minArcLength` (`min-arc-length`) | `number` | `1.5` | Arcs whose outer edge is shorter than this (px) aren't drawn — bounds DOM size for big trees |
+| `disableLabels` (`disable-labels`) | `boolean` | `false` | Hide in-arc labels (the centre readout remains) |
+| `curvedLabels` (`curved-labels`) | `boolean` | `false` | Curve labels along their ring instead of drawing them straight. See below |
+| `animationDuration` (`animation-duration`) | `number` | `600` | Transition length in ms; `0` snaps. Respects `prefers-reduced-motion` |
+| `filterPredicate` | `TreeFilterPredicate \| undefined` | `undefined` | Non-matching arcs (with no matching descendant) are dimmed |
+| `disableKeyboardNavigation` (`disable-keyboard-navigation`) | `boolean` | `false` | Turn off keyboard handling |
+| `searchModes` (`search-modes`) | `string \| undefined` | `undefined` | Subset of `navigate select filter` — see [`docs/infra-incremental.md`](../../docs/infra-incremental.md) |
+| `exclusivity` | `TreeExclusivity` | `'none'` | Accepted for interface compatibility, ignored |
+| `selectedNode` / `selectedNodes` | | | Same contract as `ixfx-tree-list` |
+| `focusedNode` | `TreeNode \| undefined` (read-only) | `undefined` | Current zoom node; `undefined` when showing the full tree |
+
+In-arc labels run along the ring when the arc is long enough, otherwise radially (truncated to the ring width); both flip to stay upright. With `curved-labels`, ring-following labels bend to the arc (an SVG `<textPath>` along the ring's middle, reversed in the bottom half so it reads upright). Since the whole arc length is usable, long labels are truncated with `…` rather than dropped; arcs too narrow for a few characters still fall back to straight radial text. Arcs too thin for either are unlabelled — hover or keyboard-cursor them and the centre readout shows their label, value and share of the centre.
+
+## Zoom, selection, navigation
+
+```typescript
+el.zoomTo(node);   // node becomes the centre
+el.zoomUp();       // centre's parent becomes the centre
+el.zoomOut();      // back to the full tree
+
+el.select(node); el.deselect(node); el.clearSelection(); el.selectAll(); el.deselectAll();
+
+// Zooms so the target sits in the first ring (its parent at the centre), then selects it.
+el.navigateTo(['users', 'me', 'photos']);
+el.navigateToNode(n => n.item.key === 'photos');
+
+el.getNodes(); // visible arcs (centre excluded), ring-major
+```
+
+## Events
+
+All events **bubble** and are **composed**. `depth` counts from the root's children (`0`).
+
+| Event | Detail | When |
+|---|---|---|
+| `zoom` | `SunburstZoomDetail` — `{ node: TreeNode \| undefined; depth }` | Zoom node changes (`node` undefined = full tree) |
+| `expand` / `collapse` | `{ node; depth }` | Zoomed into a descendant / out of the previous centre |
+| `select` | `TreeSelectDetail` | Selection changes |
+| `tickle` | `TreeTickleDetail` | Pointer or keyboard cursor enters an arc |
+| `activate` | `TreeActivateDetail` | Enter or double-click |
+| `item-click` / `item-dblclick` | `{ node; depth }` | Raw pointer clicks on an arc |
+
+## Keyboard / pointer interaction
+
+| Input | Action |
+|---|---|
+| Click an arc | Select (per `interactionMode`) and zoom in, if it has children |
+| Ctrl/⌘-click, Shift-click | Toggle / range-select (`standard` mode), without zooming |
+| Click the centre | Zoom up one level |
+| `←` / `→` | Previous / next sibling (wraps) |
+| `↑` / `↓` | Parent (inward) / first child (outward) |
+| `Home` / `End` | First / last visible arc |
+| `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 |
+|---|---|---|
+| `--sunbursttree-hue-start` | `250` | Hue at 12 o'clock |
+| `--sunbursttree-chroma` | `0.14` | First-ring chroma |
+| `--sunbursttree-chroma-step` | `0.015` | Chroma lost per ring outward |
+| `--sunbursttree-lightness` | `60%` | First-ring lightness |
+| `--sunbursttree-lightness-step` | `5%` | Lightness gained per ring outward |
+| `--sunbursttree-shade-step` | `10%` | Lightness spread across siblings |
+| `--sunbursttree-center-color` | `var(--surface-4)` | Centre disc fill |
+| `--sunbursttree-center-text` | `var(--surface-4-text)` | Centre readout text |
+| `--sunbursttree-gap-color` | `var(--surface-2)` | Stroke between arcs — match it to the background |
+| `--sunbursttree-gap` | `1px` | Width of that stroke |
+| `--sunbursttree-font-size` | `11px` | Label size (px; read for label fitting) |
+| `--sunbursttree-label-lightness` | `22%` | Label lightness (hue follows the arc) |
+
+Parts: `arc`, `center`, `label`, `center-readout`.
+
+The host defaults to `aspect-ratio: 1` with a `200px` minimum height; give it a width (or both dimensions) to size it.

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)
 
 ---
 
@@ -37,7 +38,7 @@ type TreeItem = {
   icon?: string;      // Icon name (passed to <ixfx-icon>)
   tooltip?: string;   // Tooltip content
   value?: string;     // Optional machine-readable value
-  weight?: number;    // Relative importance/magnitude; only ixfx-hyperbolictree-list uses it today
+  weight?: number;    // Relative importance/magnitude; used by ixfx-hyperbolictree-list and ixfx-sunbursttree-list
 };
 
 type TreeNode = {
@@ -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 
@@ -56,6 +57,7 @@ import '@ixfx/components/data-grid';
 - [snackbar](docs-user/snackbar.md): A small floating toolbar anchored in visual proximity to another element on the page (the "target"), built on the native Popover and CSS Anchor Positioning APIs.
 - [snap-container](docs-user/snap-container.md): A container that positions its child element at configurable snap positions along an axis. The child can be dragged, clicked to snap, or controlled via keyboard.
 - [split-layout](docs-user/split-layout.md): A Lit web component that lays out any number of panels along one axis with draggable gutters between them.
+- [sunburst-tree](docs-user/sunburst-tree.md): `<ixfx-sunbursttree-list>` — a zoomable sunburst over weighted tree data. The zoom node is the centre disc; each ring outward is one generation, and each arc's angle is its share of its parent's value
 - [swipe](docs-user/swipe.md): A touch-friendly swipe/nudge component. User taps and drags to generate a value in range [-1, 1]. Value is emitted only on pointer release.
 - [tabs](docs-user/tabs.md): A complete tabbed interface system using several coordinated components:
 - [text-shimmer](docs-user/text-shimmer.md): A label with a sweeping highlight band across the text. Useful as a lightweight "still working…" or "loading…" indicator.
@@ -64,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.4",
+  "version": "0.16.0",
   "packageManager": "pnpm@10.0.0",
   "description": "Web components for ixfx — Lit-based UI toolkit",
   "author": "Clint Heyer",
@@ -141,6 +141,10 @@
       "types": "./dist/tabs.d.ts",
       "import": "./dist/tabs.js"
     },
+    "./sunburst-tree": {
+      "types": "./dist/sunburst-tree.d.ts",
+      "import": "./dist/sunburst-tree.js"
+    },
     "./timeline": {
       "types": "./dist/timeline.d.ts",
       "import": "./dist/timeline.js"