@ixfx/components 0.3.1 → 0.4.0

package/docs-user/miller.md

@@ -0,0 +1,453 @@
+# Miller Columns
+
+A Miller column component displays hierarchical data as multiple vertical columns, like macOS Finder or email clients. Each column shows the children of the selected item in the previous column.
+
+---
+
+## MillerBaseElement / MillerListElement
+
+### Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `headers` | boolean | `false` | Show column headers labeling each column with its parent item |
+
+### Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `root` | `MillerNode \| undefined` | — | The root node of the tree. Assigning a new root resets all columns and selection state. |
+| `selectionMode` | `MillerSelectionMode` | `'implicit'` | Controls how items are selected. See [Selection Modes](#selection-modes) below. |
+| `selectedKeys` | `ReadonlySet<string>` (getter) / `Iterable<string>` (setter) | — | The set of currently selected item keys. Assigning replaces the entire selection and triggers a re-render. |
+| `loadChildren` | `MillerLoadChildrenCallback \| undefined` | — | Callback to load children for lazy nodes. If undefined, clicking a lazy node opens an empty column. |
+
+### CSS Variables
+
+These can be overridden in your CSS:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--column-bg` | `var(--surface-l)` | Background color of columns |
+| `--column-header-bg` | `var(--surface)` | Background color of column headers |
+| `--column-header-text` | `var(--surface-muted-text)` | Text color of column headers |
+| `--column-separator` | `var(--surface-h)` | Color of column borders/dividers |
+| `--column-resize-handle` | `var(--surface-h)` | Color of resize handles |
+| `--column-resize-handle-hover` | `var(--accent)` | Color of resize handle on hover |
+| `--column-resize-width` | `4px` | Width of resize handles |
+| `--item-hover-bg` | `var(--item-bg-tickled)` | Background on item hover |
+| `--item-selected-bg` | `var(--item-bg-selected)` | Background of selected item |
+| `--item-selected-text` | `var(--item-text-selected)` | Text color of selected item |
+
+Inherited from theme:
+- `--font-family` - Font family
+- `--font-weight-bold` - Bold font weight
+- `--text-s`, `--text-m`, `--text-l` - Font sizes
+- `--space-xs`, `--space-s`, `--space-m` - Spacing
+- `--radius-s` - Border radius
+- `--transition` - Transition timing
+
+### Methods
+
+```typescript
+// Navigate to a node by key path (root-to-target keys, excluding root itself).
+// Only works with already-loaded children — returns false if any node along
+// the path has unloaded children or if a key is not found.
+navigateTo(keys: readonly string[]): boolean
+
+// Navigate to the first loaded node (breadth-first) matching a predicate.
+// Returns false if no match is found in the currently loaded tree.
+navigateToNode(predicate: (node: MillerNode) => boolean): boolean
+
+// Get current configuration (column widths, etc.)
+getConfig(): MillerConfig
+
+// Set configuration. Requires a full MillerConfig object.
+setConfig(config: MillerConfig): void
+```
+
+### Events
+
+All events bubble and are composed.
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `expand` | `{ node: MillerNode, depth: number }` | FYI - fired after a column opens. |
+| `collapse` | `{ node: MillerNode, depth: number }` | FYI - fired when a column closes. |
+| `item-click` | `{ node: MillerNode, depth: number }` | Fired when any item is clicked. |
+| `select` | `{ node: MillerNode, depth: number }` | Fired when Enter is pressed on an item. |
+| `header-click` | `{ depth: number, label: string, path: MillerNode[] }` | Fired when a column header is clicked (requires `headers` attribute). `path` is the ancestry chain from root down to the node whose label is shown in the header. |
+| `change` | — | Fired when selection changes in `checked` mode (checkbox toggled). |
+
+---
+
+## Selection Modes
+
+Set via the `selectionMode` property (not an HTML attribute). Default: `'implicit'`.
+
+```typescript
+type MillerSelectionMode = 'implicit' | 'standard' | 'manual' | 'checked' | 'vscode';
+```
+
+### `implicit` (default)
+
+Selection follows the cursor path — whatever is open in the column pane is considered selected. This is the classic Miller column behaviour and is unchanged from prior versions.
+
+### `standard`
+
+Explicit multi-select similar to a file manager:
+
+| Input | Action |
+|-------|--------|
+| Click | Single-select item and expand (sets anchor, clears others) |
+| Shift+Click | Contiguous range from anchor to item (within same depth) |
+| Cmd/Ctrl+Click | Toggle item without expanding (no anchor change) |
+| Arrow Up/Down | Move focus; re-seats anchor |
+| Shift+Arrow | Extend range from anchor (bootstraps anchor from current position if unset) |
+| Enter | Select focused item (sets anchor) |
+| Shift+Enter | Extend range to focused item |
+
+### `vscode`
+
+Extends `standard` with persistent multi-selection across cursor movement:
+
+| Input | Action |
+|-------|--------|
+| Click | Single-select item and expand (clears others) — same as `standard` |
+| Shift+Click | Contiguous range from anchor — same as `standard` |
+| Cmd/Ctrl+Click | Toggle item without expanding — same as `standard` |
+| Arrow Up/Down | Move cursor **only** — selection is preserved, anchor is not re-seated |
+| Shift+Arrow | Extend range from anchor — same as `standard` |
+| Arrow Right | Expand/navigate into branch — selection is preserved (does not clear) |
+| Enter | Add focused item to selection (sets anchor) |
+| Shift+Enter | Extend range to focused item |
+
+The key difference from `standard`: in `vscode` mode the cursor is free to move without disturbing the accumulated multi-selection. Only a plain unmodified click clears the selection.
+
+### `manual`
+
+The component never modifies `selectedKeys`. All clicks and keyboard actions fire events as normal but selection state is entirely driven by the caller via the public API. Use this when you want to implement custom selection logic.
+
+### `checked`
+
+A checkbox appears beside each item. Clicking the row navigates/expands as usual; clicking the checkbox toggles selection. Selecting a branch recursively selects all loaded descendants. Checkbox state follows a three-state cycle: **indeterminate → checked → unchecked**.
+
+- **Checked**: item key is in `selectedKeys`
+- **Unchecked**: item key is not in `selectedKeys` and no loaded descendants are selected
+- **Indeterminate**: some (but not all) loaded descendants are selected
+
+The `change` event is fired on the component after every checkbox toggle.
+
+---
+
+## Selection API
+
+```typescript
+// Read current selection
+const keys: ReadonlySet<string> = el.selectedKeys;
+
+// Replace entire selection (triggers re-render)
+el.selectedKeys = ['key-a', 'key-b'];
+
+// Select or deselect a single node
+// In 'checked' mode, selecting a branch recursively selects all loaded descendants
+el.setSelected(node: MillerNode, selected: boolean): void
+
+// Return all currently-selected MillerNodes (searches loaded tree only)
+el.getSelected(): MillerNode[]
+
+// Clear all selection state
+el.clearSelection(): void
+```
+
+---
+
+## Types
+
+```typescript
+type MillerItem = {
+  key: string;        // Unique identifier
+  label: string;      // Display text
+  isLeaf?: boolean;   // If true, clicking never fires 'expand'
+  data?: unknown;     // Arbitrary user data
+  icon?: string;      // Optional icon name
+  tooltip?: string;   // Optional tooltip text
+  value?: string;     // Optional string value
+};
+
+type MillerNode = {
+  item: MillerItem;
+  children?: MillerNode[];  // undefined = unloaded, [] = confirmed empty
+};
+
+type MillerConfig = {
+  columnWidths: Record<number, number>;  // depth -> px
+};
+```
+
+---
+
+## Basic Usage
+
+### Static Columns
+
+```html
+<ixfx-miller-list id="miller" headers></ixfx-miller-list>
+
+<script type="module">
+  const el = document.getElementById('miller');
+  
+  el.root = {
+    item: { key: 'root', label: 'My Computer' },
+    children: [
+      {
+        item: { key: 'c', label: 'C:' },
+        children: [
+          { 
+            item: { key: 'users', label: 'Users' },
+            children: [
+              { item: { key: 'jane', label: 'Jane', isLeaf: true } },
+              { item: { key: 'barry', label: 'Barry', isLeaf: true } }
+            ]
+          },
+          { item: { key: 'windows', label: 'Windows', isLeaf: true } }
+        ]
+      },
+      {
+        item: { key: 'd', label: 'D:' },
+        children: [
+          { item: { key: 'games', label: 'Games', isLeaf: true } }
+        ]
+      }
+    ]
+  };
+
+  // Respond to clicks
+  el.addEventListener('item-click', ({ detail }) => {
+    console.log('Clicked:', detail.node.item.label, 'at column', detail.depth);
+  });
+
+  // Respond to header clicks (if headers enabled)
+  el.addEventListener('header-click', ({ detail }) => {
+    console.log('Header clicked:', detail.label, 'at depth', detail.depth);
+    console.log('Path:', detail.path.map(n => n.item.label));
+  });
+</script>
+```
+
+### Lazy Loading
+
+Set the `loadChildren` callback to handle loading children on demand. The callback
+receives the node, depth, and an AbortSignal. It should return the children array
+(or a Promise that resolves to it). The callback is debounced by 150ms.
+
+```html
+<ixfx-miller-list id="miller"></ixfx-miller-list>
+
+<script type="module">
+  const el = document.getElementById('miller');
+  
+  // Children at root level are pre-loaded; deeper nodes will be loaded on demand
+  el.root = {
+    item: { key: 'root', label: 'Root' },
+    children: [
+      { item: { key: 'a', label: 'Alpha' } },  // children: undefined → lazy
+      { item: { key: 'b', label: 'Beta' } },
+    ]
+  };
+
+  el.loadChildren = async (node, depth, signal) => {
+    // Return children array (sync or async)
+    return fetchChildren(node.item.key, signal);
+  };
+
+  async function fetchChildren(key, signal) {
+    const response = await fetch(`/api/children/${key}`, { signal });
+    return response.json();
+  }
+</script>
+```
+
+If no `loadChildren` callback is set, clicking a lazy node opens an empty column.
+
+**FYI Events:**
+- `expand`: fired after a column opens. Detail: `{ node, depth }`
+- `collapse`: fired when a column closes (user navigates away or load is aborted). Detail: `{ node, depth }`
+
+### Programmatic Navigation
+
+```javascript
+// Navigate by key path — keys are item.key values from root's children downwards.
+// Returns false (silently) if any node along the path has not yet been loaded.
+el.navigateTo(['c', 'users', 'jane']);
+
+// Or find by predicate across already-loaded nodes
+el.navigateToNode(node => node.item.label === 'System32');
+```
+
+### Column Resizing
+
+Columns can be resized by dragging the handle on the right edge of each column. The widths are persisted in the config:
+
+```javascript
+// Serialize current state (e.g. to localStorage)
+const config = el.getConfig();
+localStorage.setItem('millerConfig', JSON.stringify(config));
+
+// Restore saved state
+el.setConfig(JSON.parse(localStorage.getItem('millerConfig')));
+```
+
+### Configuration
+
+```javascript
+// Set custom column widths (depth index → width in px)
+el.setConfig({ columnWidths: { 0: 150, 1: 200, 2: 180 } });
+```
+
+---
+
+## MillerTreeController
+
+Bridge an ixfx `TraversableTree` to a Miller component. Children are populated
+lazily — the controller handles `expand` events by synchronously reading from
+the underlying tree.
+
+```typescript
+import { Trees } from '@ixfx/collections';
+import { MillerTreeController } from './miller-tree-controller.js';
+
+const root = Trees.Mutable.createNode({ key: 'root', label: 'Root' });
+Trees.Mutable.addValue({ key: 'a', label: 'Alpha' }, root);
+
+const ctrl = new MillerTreeController(
+  Trees.Mutable.asDynamicTraversable(root),
+  document.querySelector('ixfx-miller-list'),
+  { 
+    // Both the value and the raw tree node are provided so you can inspect
+    // child count, identity, etc. when building the MillerItem.
+    valueToItem: (value, treeNode) => ({ 
+      key: value.key, 
+      label: value.label,
+      isLeaf: value.isLeaf 
+    }) 
+  }
+);
+
+ctrl.connect();
+
+// Navigate to a value — ancestors with unloaded children are populated first
+ctrl.navigateToValue(v => v.label === 'Target');
+
+// Clean up event listeners when done
+ctrl.disconnect();
+```
+
+### MillerTreeControllerOptions
+
+```typescript
+type MillerTreeControllerOptions<T> = {
+  // Convert a tree node's value to a MillerItem.
+  // key and label are required. If isLeaf is omitted, it is inferred
+  // from whether the TraversableTree node has any children.
+  valueToItem: (value: T, node: TraversableTree<T>) => MillerItem;
+};
+```
+
+### Methods
+
+```typescript
+// Wire up the controller — sets element.root and provides loadChildren callback.
+// Safe to call again after disconnect().
+connect(): void
+
+// Remove all event listeners and release internal state.
+disconnect(): void
+
+// Navigate the component to the first node (depth-first) whose value matches predicate.
+// Any ancestor MillerNodes with unloaded children are populated synchronously first.
+// Returns false if no matching node is found.
+navigateToValue(predicate: (value: T) => boolean): boolean
+```
+
+---
+
+## Keyboard Navigation
+
+Miller columns support full keyboard navigation when the component has focus:
+
+| Key | Action |
+|-----|--------|
+| `Arrow Up` | Move focus to previous item in column |
+| `Arrow Down` | Move focus to next item in column |
+| `Arrow Right` | Select focused item and open its children (if any) |
+| `Arrow Left` | Go back to previous column |
+| `Enter` | Fire `select` event on focused item; in `standard` mode also selects and sets anchor |
+| `Shift+Arrow` | In `standard` mode: extend selection range from anchor |
+| `Shift+Enter` | In `standard` mode: extend selection range to focused item |
+| `Escape` | Cancel pending lazy load / go back one column |
+
+---
+
+## Subclassing MillerBaseElement
+
+Create custom column renderers by subclassing `MillerBaseElement`. Override
+`renderColumnContent` to control how items are rendered. The following protected
+members are available for subclasses to use:
+
+```typescript
+// True if node is currently selected at the given depth
+_isSelected(node: MillerNode, depth: number): boolean
+
+// True if node has keyboard focus at the given depth
+_isFocused(node: MillerNode, depth: number): boolean
+
+// Returns the index of the focused item at the given depth
+_getFocusedIndex(depth: number): number
+
+// Call this to handle an item click (selection, expand, events)
+_handleItemClick(node: MillerNode, depth: number): void
+
+// Handle a checkbox click for the given node (used in 'checked' mode).
+// Returns the new checked state (true = selected) after the toggle.
+// Also fires the 'change' event on the element.
+_handleCheckboxClick(event: MouseEvent, node: MillerNode, depth: number): boolean
+
+// The current selection set — read/write in subclasses
+_selectedKeys: Set<string>
+```
+
+Example:
+
+```typescript
+import { MillerBaseElement } from './miller-base.js';
+import { html, css } from 'lit';
+import { customElement } from 'lit/decorators.js';
+import type { MillerNode } from './types.js';
+
+@customElement('ixfx-miller-custom')
+export class MillerCustomElement extends MillerBaseElement {
+  protected override renderColumnContent(nodes: MillerNode[], depth: number) {
+    return html`
+      <div class="custom-column">
+        ${nodes.map(node => html`
+          <div
+            class="custom-item ${this._isSelected(node, depth) ? 'selected' : ''} 
+                               ${this._isFocused(node, depth) ? 'focused' : ''}"
+            @click=${() => this._handleItemClick(node, depth)}
+          >
+            ${node.item.label}
+          </div>
+        `)}
+      </div>
+    `;
+  }
+
+  static override styles = [
+    ...MillerBaseElement.styles,
+    css`
+      .custom-item.selected { background: var(--item-selected-bg); }
+      .custom-item.focused  { outline: 2px solid var(--accent); }
+    `,
+  ];
+}
+```

package/docs-user/narrowed-text.md

@@ -0,0 +1,72 @@
+# `ixfx-narrowed-text`
+
+A filtered text selection component with inline search. Shows slotted items filtered by a query string as the user types.
+
+```html
+<ixfx-narrowed-text selection-mode="single" value="beta">
+  <span data-value="alpha">Alpha</span>
+  <span data-value="beta">Beta</span>
+  <span data-value="gamma">Gamma</span>
+</ixfx-narrowed-text>
+
+<ixfx-narrowed-text selection-mode="multiple">
+  <span data-value="opt1" data-label="Option One">Option One</span>
+  <span data-value="opt2" data-label="Option Two">Option Two</span>
+</ixfx-narrowed-text>
+```
+
+### Properties / attributes
+
+| Attribute / Property     | Type            | Default     | Description                                    |
+|-------------------------|-----------------|-------------|------------------------------------------------|
+| `selectionMode`         | `'single' \| 'multiple'` | `'single'` | Number of items that can be selected |
+| `requiredSelection`     | `boolean`        | `false`     | Prevent deselecting last item in single mode   |
+| `orientation`           | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction       |
+| `nowrap`               | `boolean`        | `false`     | Prevent items from wrapping                   |
+| `separator`            | `string`          | `' '`       | Separator for multi-value string              |
+| `width`                | `string \| undefined` | `undefined` | Container width (e.g. `'200px'`)            |
+| `height`               | `string \| undefined` | `undefined` | Container height                          |
+| `preserveFilter`        | `boolean`        | `false`     | Keep filter query after selection             |
+| `value`                | `string`          | `''`        | Selected value(s) as string                  |
+
+### CSS parts
+
+| Part       | Description         |
+|------------|---------------------|
+| `container` | Main container      |
+| `items`    | Items container     |
+| `item`     | Individual item     |
+| `label`    | Item label text     |
+
+### Events
+
+| Event    | Detail                                          | Description                |
+|----------|-------------------------------------------------|----------------------------|
+| `change` | `{ item, query, selected }`                    | Fired when selection changes |
+
+```js
+const nt = document.querySelector('ixfx-narrowed-text');
+nt.addEventListener('change', e => {
+  console.log(e.detail.selected); // array of selected items
+});
+```
+
+### Properties of slotted items
+
+Items should have `data-value` attribute. Optional attributes:
+- `data-label`: Display label (defaults to textContent)
+- `data-description`: Optional description text
+- `data-icon-name`: Optional icon name
+
+### CSS custom properties
+
+| Property                                     | Default | Description                          |
+|----------------------------------------------|---------|--------------------------------------|
+| `--item-padding`                             | `var(--space-xs) var(--space-m)` | Item padding            |
+| `--item-border-radius`                       | `var(--radius-s)` | Item border radius             |
+| `--item-icon-spacing`                        | `var(--space-xs)` | Gap between icon and label   |
+| `--item-height`                              | `28px`  | Minimum item container height        |
+| `--item-label-font-style-default`            | `normal` | Default font style                |
+| `--item-label-text-decoration-tickled`       | `underline dotted` | Tickled item decoration  |
+| `--highlight-background`                     | `var(--accent)` | Query match highlight bg     |
+| `--highlight-color`                         | `var(--accent-text)` | Query match highlight color |