@ixfx/components 0.15.5 → 0.16.0

package/docs-user/tree.md

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

package/docs-user/treemap.md

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

package/docs-user/twosplit-layout.md

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

package/docs-user/user-catalog.md

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

package/docs-user/vertical-list.md

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

package/llms.txt

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ixfx/components",
   "type": "module",
-  "version": "0.15.5",
+  "version": "0.16.0",
   "packageManager": "pnpm@10.0.0",
   "description": "Web components for ixfx — Lit-based UI toolkit",
   "author": "Clint Heyer",