@ixfx/components 0.3.2 → 0.4.0

package/docs-user/tree.md

@@ -0,0 +1,592 @@
+# Tree Components — Common API Reference
+
+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-specific behaviour where noted.
+
+`ixfx-crumb-path` uses a fundamentally different string-based model and is not covered here.
+
+---
+
+## Contents
+
+1. [Data model](#data-model)
+2. [Properties](#properties)
+3. [Selection](#selection)
+4. [Events](#events)
+5. [Keyboard navigation](#keyboard-navigation)
+6. [Incremental search](#incremental-search)
+7. [ARIA](#aria)
+8. [CSS variables](#css-variables)
+9. [Controller authoring guide](#controller-authoring-guide)
+
+---
+
+## Data model
+
+### Core types
+
+```typescript
+type TreeItem = {
+  key: string;        // Unique identifier across the whole tree
+  label: string;      // Display text
+  isLeaf?: boolean;   // true = never expandable; undefined/false = branch
+  data?: unknown;     // Arbitrary user payload
+  icon?: string;      // Icon name (passed to <ixfx-icon>)
+  tooltip?: string;   // Tooltip content
+  value?: string;     // Optional machine-readable value
+};
+
+type TreeNode = {
+  item: TreeItem;
+  children?: TreeNode[];  // undefined = unloaded; [] = confirmed empty
+};
+```
+
+`TreeNode` is **immutable** — structural changes always produce a new root. Never mutate a node in place; use `TreeDataModel` convenience methods or replace `root` directly.
+
+---
+
+### Static trees
+
+Set `root` directly when the tree data is available up-front:
+
+```typescript
+el.root = {
+  item: { key: 'root', label: 'My Files' },
+  children: [
+    { item: { key: 'docs', label: 'Documents' }, children: [] },
+    { item: { key: 'img', label: 'Images', isLeaf: true } },
+  ],
+};
+```
+
+---
+
+### Lazy loading via `loadChildren`
+
+Set `loadChildren` to fetch children on demand (called when a branch is expanded):
+
+```typescript
+el.loadChildren = async ({ node, depth }, signal) => {
+  const res = await fetch(`/api/children/${node.item.key}`, { signal });
+  return res.json(); // TreeNode[]
+};
+```
+
+The callback receives an `AbortSignal`; honour it to avoid races when the user collapses quickly. It may return `TreeNode[]`, `Promise<TreeNode[]>`, or `AsyncIterable<DataBatch<TreeNode>>` for streaming children.
+
+---
+
+### `TreeDataModel` — shared, cached data layer
+
+`TreeDataModel` is an optional shared data layer that owns child-loading and caching. It is useful when:
+
+- Multiple components display the same dataset (e.g. a tree-list and a miller-list side-by-side).
+- You need programmatic tree mutation without tracking the root yourself.
+- You need to invalidate (refresh) individual branches without a full re-render.
+
+```typescript
+import { TreeDataModel } from '@ixfx/components';
+
+const model = new TreeDataModel({
+  root: { item: { key: 'root', label: 'Root' }, children: undefined },
+  loadChildren: async ({ node }, signal) => {
+    const res = await fetch(`/api/children/${node.item.key}`, { signal });
+    return res.json();
+  },
+});
+
+treeEl.model = model;
+millerEl.model = model;   // Both components share the same cache
+```
+
+#### Model API
+
+| Member | Signature | Description |
+|--------|-----------|-------------|
+| `root` | `get root(): TreeNode` | Current immutable root snapshot |
+| `setRoot` | `(root: TreeNode): void` | Replace the root; notifies all connected components |
+| `getChildren` | `(node, depth, signal): Promise<TreeNode[]>` | Returns cached children or calls `loadChildren`; cache keyed by `node.item.key` |
+| `invalidate` | `(nodeKey: string): void` | Clears cached children for `nodeKey`; connected components collapse that branch so the next expand triggers a fresh fetch |
+| `addNode` | `(parentKey, node): TreeNode` | Appends a child; returns new root |
+| `removeNode` | `(key): TreeNode` | Removes node and all descendants; returns new root |
+| `updateItem` | `(key, patch): TreeNode` | Merges `patch` into the item at `key`; returns new root |
+| `moveNode` | `(key, newParentKey): TreeNode` | Moves a node under a new parent; returns new root |
+| `_subscribe` | `(cb): () => void` | Internal subscription used by components; returns unsubscribe |
+
+#### How caching works
+
+`getChildren()` stores results in a `Map<string, TreeNode[]>` keyed by `node.item.key`. A cache hit returns the stored array synchronously (wrapped in a resolved `Promise`). `invalidate(key)` deletes the cache entry and emits an `invalidate` event; connected components collapse the branch so the next expand triggers a fresh load.
+
+Mutator methods (`addNode`, `removeNode`, `updateItem`, `moveNode`) apply pure transformations to produce a new immutable root, then emit a `root` event so all connected components re-render.
+
+#### Model vs `loadChildren`
+
+When both `model` and `loadChildren` are set, `model` takes precedence. `loadChildren` remains available for simple cases that do not need sharing or programmatic mutation.
+
+---
+
+## Properties
+
+These properties are present on all three components (`ixfx-tree-list`, `ixfx-miller-list`, `ixfx-crumb-navigation`).
+
+| 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 |
+| `selectedNode` | `TreeNode \| undefined` | `undefined` | Primary (most recent) selected node |
+| `selectedNodes` | `ReadonlySet<TreeNode>` | `{}` | Full selection set (read-only) |
+| `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) |
+| `filterPredicate` | `TreeFilterPredicate \| undefined` | `undefined` | Filter; only nodes returning `true` are shown |
+| `exclusivity` | `'none' \| 'depth' \| 'global'` | `'none'` | Expansion exclusivity (reflected attribute) |
+
+### `interactionMode` (`ixfx-tree-list` / `ixfx-miller-list`)
+
+Controls how pointer and keyboard gestures translate to selection changes.
+
+| Value | Behaviour |
+|-------|-----------|
+| `'implicit'` | Single selection follows every click; click also toggles expand/collapse |
+| `'standard'` | Plain click selects + toggles expand; Ctrl/Cmd+click toggles item; Shift+click range-selects |
+| `'manual'` | Component never auto-selects; use `select()` / `deselect()` / `clearSelection()` to drive state |
+| `'checked'` | Checkboxes on every row; checkbox click recursively selects/deselects loaded descendants; row click only expands/collapses |
+| `'vscode'` | Like `standard` for clicks; Shift+Up/Down uses snapshot-based toggle-range (VS Code file-explorer style) |
+
+Switching `interactionMode` clears the current selection.
+
+### `selectionFilter`
+
+| Value | Behaviour |
+|-------|-----------|
+| `'none'` | No nodes can be selected |
+| `'leaf'` | Only leaf nodes (`isLeaf: true` or `children: []`) can be selected |
+| `'branch'` | Only branch nodes can be selected |
+
+### `exclusivity`
+
+Controls how expansion of one branch affects others.
+
+| Value | Behaviour |
+|-------|-----------|
+| `'none'` | Any number of branches can be open simultaneously |
+| `'depth'` | Opening a branch collapses its siblings at the same depth (accordion) |
+| `'global'` | Opening any branch collapses all other open branches in the tree |
+
+`exclusivity="depth"` replaces the old `accordion` boolean attribute. To migrate: `accordion` → `exclusivity="depth"`.
+
+---
+
+## Selection
+
+### Programmatic selection
+
+```typescript
+// Select a node (respects selectionFilter; always replaces selection)
+el.select(node);
+
+// Remove a specific node from the selection
+el.deselect(node);
+
+// Clear the entire selection
+el.clearSelection();
+```
+
+### Reading the selection
+
+```typescript
+// Primary (most-recent) selected node
+console.log(el.selectedNode?.item.label);
+
+// Full selection set (for multi-select)
+for (const node of el.selectedNodes) {
+  console.log(node.item.label);
+}
+```
+
+### Listening for selection changes
+
+```typescript
+el.addEventListener('select', ({ detail }) => {
+  const { selected, previous } = detail;
+  console.log('Selected:', [...selected].map(n => n.item.label));
+  console.log('Previously:', [...previous].map(n => n.item.label));
+});
+```
+
+---
+
+## Events
+
+All events **bubble** and are **composed** (cross shadow-DOM boundaries).
+
+| Event | Detail type | When fired |
+|-------|-------------|------------|
+| `select` | `TreeSelectDetail` | Selection set changes by any means (click, keyboard, programmatic) |
+| `tickle` | `TreeTickleDetail` | An item enters cursor focus: pointer hover OR keyboard navigation cursor |
+| `activate` | `TreeActivateDetail` | User explicitly activates an item (Enter key or double-click) |
+| `item-click` | `{ node: TreeNode; depth: number }` | Raw pointer click on any item |
+| `expand` | `{ node: TreeNode; depth: number }` | A branch expands |
+| `collapse` | `{ node: TreeNode; depth: number }` | A branch collapses |
+
+### Detail types
+
+```typescript
+type TreeSelectDetail = {
+  readonly selected: ReadonlySet<TreeNode>;   // Current full selection
+  readonly previous: ReadonlySet<TreeNode>;   // Selection before this change
+};
+
+type TreeTickleDetail = {
+  readonly node: TreeNode;
+  readonly depth: number;
+};
+
+type TreeActivateDetail = {
+  readonly node: TreeNode;
+  readonly depth: number;
+};
+```
+
+### Usage example
+
+```typescript
+el.addEventListener('select', ({ detail }) => {
+  // Works for both single and multi-select
+  const first = [...detail.selected][0];
+  if (first) console.log('Primary selection:', first.item.label);
+});
+
+el.addEventListener('tickle', ({ detail }) => {
+  // Show a preview pane as the user hovers
+  preview.setNode(detail.node);
+});
+
+el.addEventListener('activate', ({ detail }) => {
+  // Open the item (e.g. navigate to a route)
+  router.navigate(detail.node.item.key);
+});
+```
+
+### Migration from old event shapes
+
+| Old | New |
+|-----|-----|
+| `select` → `{ selected: TreeNode, previous: TreeNode \| undefined }` | `select` → `TreeSelectDetail` (set-based) |
+| `change` (Miller) | `select` (set-based) |
+| Miller `select` (Enter key) | `activate` |
+| no tickle event | `tickle` |
+
+---
+
+## Keyboard navigation
+
+The element must be focused (click it or tab to it) before keyboard navigation works.
+
+### `ixfx-tree-list`
+
+| Key | Action |
+|-----|--------|
+| `Arrow Up` | Move cursor to previous visible item |
+| `Arrow Down` | Move cursor to next visible item |
+| `Arrow Right` (on collapsed branch) | Expand and move into first child |
+| `Arrow Right` (on expanded branch) | Move into first child |
+| `Arrow Right` (on leaf) | No-op |
+| `Arrow Left` (on expanded branch) | Collapse branch |
+| `Arrow Left` (on leaf or collapsed branch) | Move to parent |
+| `Enter` | Select and activate focused item |
+| `Escape` | Cancel in-flight lazy load |
+
+Moving the cursor fires a `tickle` event. Pressing Enter fires `select` then `activate`.
+
+### `ixfx-miller-list`
+
+| Key | Action |
+|-----|--------|
+| `Arrow Up / Down` | Move within the active column |
+| `Arrow Right` | Expand (open next column for) highlighted branch |
+| `Arrow Left` | Go back to the parent column |
+| `Enter` | Activate the highlighted item (`activate` event) |
+| `Escape` | Cancel pending operations |
+
+### `ixfx-crumb-navigation`
+
+Keyboard navigation follows the crumb path. Arrow keys move between breadcrumb segments; clicking or Enter expands the next level.
+
+---
+
+## Incremental search
+
+Wire up a text input to filter and highlight matching nodes using `IncrSearchTreeController`:
+
+```typescript
+import { IncrSearchTreeController } from '@ixfx/components';
+
+const ctrl = new IncrSearchTreeController(el, {
+  selector: item => item.node.item.label,   // Text to search against
+  input: document.querySelector('#search'), // Optional: auto-wires input/keydown
+});
+ctrl.connect();
+
+// Clean up when done
+ctrl.disconnect();
+```
+
+### Options
+
+```typescript
+type IncrSearchTreeOptions = {
+  /** How to extract searchable text from each node */
+  selector: (item: { node: TreeNode; depth: number }) => string;
+
+  /**
+   * CSS selector for label elements inside the shadow root.
+   * Default: '.tree-label' (ixfx-tree-list)
+   * Use '.label' for ixfx-miller-list
+   */
+  labelSelector?: string;
+
+  /** Input element to auto-wire. Esc clears the query. */
+  input?: HTMLInputElement;
+
+  /** fzf matching options */
+  fzf?: Partial<FzfOptions<{ node: TreeNode; depth: number }>>;
+};
+```
+
+### Manual control
+
+```typescript
+await ctrl.setQuery('search text');
+await ctrl.clearQuery();
+```
+
+### Using with miller-list
+
+```typescript
+const ctrl = new IncrSearchTreeController(millerEl, {
+  selector: item => item.node.item.label,
+  labelSelector: '.label',   // Miller uses .label, not .tree-label
+  input: searchInput,
+});
+ctrl.connect();
+```
+
+### How it works
+
+1. `connect()` calls `el.getNodes()` to snapshot the full item list.
+2. On each query change the controller runs fzf fuzzy matching and sets `el.filterPredicate` to a function that returns `true` only for matching nodes.
+3. Matched label text is highlighted in the shadow DOM using the CSS Highlight API via `applyHighlights()`.
+4. `disconnect()` clears `filterPredicate` and all highlights.
+
+---
+
+## ARIA
+
+Each tree-like component must implement the following. These are enforced by the shared `TreeComponent` interface and implemented in `TreeBaseElement` / `MillerBaseElement` / `CrumbNavigationElement`.
+
+**Container element**
+
+- [ ] `role="tree"` on the outermost interactive container
+- [ ] `aria-label` or `aria-labelledby` to name the tree
+
+**Each item element**
+
+- [ ] `role="treeitem"`
+- [ ] `aria-level` (1-based depth)
+- [ ] `aria-setsize` (total siblings in the same group)
+- [ ] `aria-posinset` (1-based position among siblings)
+- [ ] `aria-selected="true|false"`
+
+**Expandable items**
+
+- [ ] `aria-expanded="true"` when open, `"false"` when closed
+- [ ] Omit `aria-expanded` on leaf nodes
+
+**Child groups**
+
+- [ ] Wrap children in `<ul role="group">` (or equivalent `role="group"` container)
+
+**Miller columns specifically**
+
+Each column is a separate `role="listbox"` with `aria-label` showing the parent node label. Items use `role="option"` and `aria-selected`.
+
+---
+
+## CSS variables
+
+### Shared / themed
+
+These are set by the global theme and inherited by all tree components.
+
+| Variable | Description |
+|----------|-------------|
+| `--accent` | Selected item background |
+| `--accent-text` | Selected item text |
+| `--surface-3` | Panel background |
+| `--surface-3-text` | Default item text |
+| `--surface-muted-text` | Muted text (carets, secondary info) |
+| `--surface-h` | Hover background |
+| `--radius-s` | Small border radius |
+| `--transition` | Default transition timing |
+| `--space-xs` | Extra-small spacing |
+| `--space-s` | Small spacing |
+| `--space-m` | Medium spacing |
+| `--font-family` | Font family |
+| `--text-m` | Base text size |
+| `--text-l` | Large text size |
+
+### `ixfx-tree-list` specific
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--tree-indent` | `20px` | Indentation per depth level |
+| `--tree-item-height` | `28px` | Height of each row |
+| `--tree-caret-size` | `10px` | Expand/collapse caret size |
+
+### `ixfx-miller-list` specific
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--miller-column-width` | `180px` | Width of each column |
+| `--miller-column-max-height` | `320px` | Maximum column height before scroll |
+| `--item-hover-bg` | `var(--surface-h)` | Hover background |
+| `--item-selected-bg` | `var(--accent)` | Selected item background |
+| `--item-selected-text` | `#fff` | Selected item text |
+| `--item-open-bg` | (theme) | Background for items on the open path |
+| `--icon-size` | `1em` | Icon dimensions |
+| `--icon-spacing` | `0.3em` | Gap between icon and label |
+
+---
+
+## Controller authoring guide
+
+A controller operates against the `TreeComponent` interface. This means the same controller works with any of the three components.
+
+### Minimal controller
+
+```typescript
+import type { TreeComponent, TreeNode } from '@ixfx/components';
+
+export class MyController {
+  #el: TreeComponent;
+  #unsub?: () => void;
+
+  constructor(el: TreeComponent) {
+    this.#el = el;
+  }
+
+  connect(): void {
+    this.disconnect();
+    this.#el.addEventListener('select', this.#onSelect);
+    this.#el.addEventListener('tickle', this.#onTickle);
+  }
+
+  disconnect(): void {
+    this.#el.removeEventListener('select', this.#onSelect);
+    this.#el.removeEventListener('tickle', this.#onTickle);
+    this.#unsub?.();
+    this.#unsub = undefined;
+  }
+
+  #onSelect = (e: CustomEvent) => {
+    const { selected } = e.detail;
+    for (const node of selected as ReadonlySet<TreeNode>) {
+      console.log('selected:', node.item.label);
+    }
+  };
+
+  #onTickle = (e: CustomEvent) => {
+    const { node, depth } = e.detail;
+    console.log('tickled:', node.item.label, 'at depth', depth);
+  };
+}
+```
+
+### Querying all nodes
+
+```typescript
+// Snapshot of all visible nodes with their depth
+const nodes = el.getNodes(); // ReadonlyArray<{ node: TreeNode; depth: number }>
+```
+
+### Filtering
+
+```typescript
+// Only show nodes matching a predicate
+el.filterPredicate = (node, depth) => node.item.label.startsWith('A');
+
+// Clear filter
+el.filterPredicate = undefined;
+```
+
+### Selecting programmatically
+
+```typescript
+// Honour selectionMode and selectionFilter automatically
+el.select(someNode);
+
+// Or navigate to a node by key path and select it
+el.navigateTo(['root', 'documents', 'readme.md']);
+```
+
+### Using `TreeSearchHost` for shadow-DOM access
+
+Controllers that need to touch the shadow DOM (e.g. for highlight injection) should type the host as `TreeSearchHost` rather than `TreeComponent`:
+
+```typescript
+import type { TreeSearchHost } from '@ixfx/components';
+
+export class HighlightController {
+  #el: TreeSearchHost;
+
+  constructor(el: TreeSearchHost) {
+    this.#el = el;
+  }
+
+  async highlight(selector: string): Promise<void> {
+    await this.#el.updateComplete;
+    const labels = this.#el.shadowRoot?.querySelectorAll(selector);
+    // ...
+  }
+}
+```
+
+---
+
+## Types reference
+
+```typescript
+type LoadChildrenCallback = (
+  query: { node: TreeNode; depth: number },
+  signal: AbortSignal
+) => TreeNode[] | Promise<TreeNode[]> | AsyncIterable<DataBatch<TreeNode>>;
+
+type TreeFilterPredicate = (node: TreeNode, depth: number) => boolean;
+
+type TreeExclusivity = 'none' | 'depth' | 'global';
+type TreeSelectionFilter = 'none' | 'leaf' | 'branch';
+type TreeInteractionMode = 'implicit' | 'standard' | 'manual' | 'checked' | 'vscode';
+
+interface TreeComponent extends EventTarget {
+  root: TreeNode | undefined;
+  model: TreeDataModel | undefined;
+  loadChildren: LoadChildrenCallback | undefined;
+  selectedNode: TreeNode | undefined;
+  readonly selectedNodes: ReadonlySet<TreeNode>;
+  selectionFilter: TreeSelectionFilter;
+  filterPredicate: TreeFilterPredicate | undefined;
+  exclusivity: TreeExclusivity;
+  select(node: TreeNode): void;
+  deselect(node: TreeNode): void;
+  clearSelection(): void;
+  navigateTo(keys: readonly string[]): boolean;
+  navigateToNode(predicate: (node: TreeNode) => boolean): boolean;
+  getNodes(): ReadonlyArray<{ node: TreeNode; depth: number }>;
+}
+
+interface TreeSearchHost extends TreeComponent {
+  readonly shadowRoot: ShadowRoot | null;
+  readonly updateComplete: Promise<boolean>;
+}
+```