@ixfx/components 0.14.1 → 0.14.3

package/docs-user/tree.md

@@ -11,6 +11,7 @@ Three components share a common `TreeComponent` interface: **`ixfx-tree-list`**,
 1. [Data model](#data-model)
 2. [Properties](#properties)
    - [Custom checkbox (`checkboxRenderer`)](#custom-checkbox-ixfx-tree-list-only--checkboxrenderer)
+   - [Unselectable items (`selectable`, `alignCheckboxes`)](#unselectable-items-selectable-aligncheckboxes)
    - [Virtualisation](#virtualisation-ixfx-tree-list)
 3. [Selection](#selection)
 4. [Events](#events)
@@ -31,6 +32,7 @@ type TreeItem = {
   key: string;        // Unique identifier across the whole tree
   label: string;      // Display text
   isLeaf?: boolean;   // true = never expandable; undefined/false = branch
+  selectable?: boolean; // false = can never be selected (and gets no checkbox in `checked` mode)
   data?: unknown;     // Arbitrary user payload
   icon?: string;      // Icon name (passed to <ixfx-icon>)
   tooltip?: string;   // Tooltip content
@@ -138,19 +140,33 @@ These properties are present on all three components (`ixfx-tree-list`, `ixfx-mi
 
 | Property / Attribute | Type | Default | Description |
 |----------------------|------|---------|-------------|
-| `root` | `TreeNode \| undefined` | `undefined` | Root node of the tree |
+| `root` | `TreeNode \| undefined` | `undefined` | Root node of the tree. Replacing it keeps expansion for every `item.key` still present (see [Replacing `root`](#replacing-root)); selection and focus are reset |
 | `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) |
+| `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) |
 | `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 |
 
+### Replacing `root`
+
+Because `TreeNode` is immutable, any structural change means assigning a new `root`. When you do:
+
+- **Expansion is kept** for every branch whose `item.key` still exists in the new root, and dropped for keys that are gone. A key that disappears and later returns comes back collapsed. Call `collapseAll()` if you want a fresh tree.
+- **Selection, focus and any pending lazy load are reset**, since they may refer to nodes that no longer exist.
+- The reconciliation happens before the render, so assigning `root` and then calling `expandAll()` (or `navigateTo()`) synchronously works as you'd expect:
+
+```ts
+tree.root = rebuild();
+tree.expandAll(); // stays expanded after the update
+```
+
 ### `interactionMode` (`ixfx-tree-list` / `ixfx-miller-list`)
 
 Controls how pointer and keyboard gestures translate to selection changes.
@@ -160,7 +176,7 @@ Controls how pointer and keyboard gestures translate to selection changes.
 | `'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 |
+| `'checked'` | Checkboxes on every row; clicking the checkbox — or anywhere left of the label (indent, caret, icon) — recursively selects/deselects loaded descendants; label 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.
@@ -190,6 +206,8 @@ tree.checkboxRenderer = (state) => state === `unchecked`
 
 When `checkboxRenderer` is set, the checkbox becomes a `<span class="tree-checkbox" role="checkbox" part="checkbox">` holding your template, with `aria-checked` set to `"true"`, `"false"`, or `"mixed"` to match the tri-state. The span owns the click (same as the native input), so clicking anywhere in it — including empty space when you render nothing for `unchecked` — toggles the row.
 
+To keep the checkbox easy to aim at, the entire row region left of the label — indent gutter, checkbox, caret and icon — acts as one checkbox hit target in `checked` mode. Only clicks on the label itself expand/collapse.
+
 Both the native input and the custom span expose the `checkbox` CSS part for external styling:
 
 ```css
@@ -199,12 +217,47 @@ ixfx-tree-list::part(checkbox) {
 }
 ```
 
+### Unselectable items (`ixfx-tree-list`) — `selectable`, `alignCheckboxes`
+
+Set `selectable: false` on a `TreeItem` to stop that one node being selected, independent of `selectionFilter` and of the interaction mode. Selection APIs (`selectNode`, `selectAll`, `Shift`-range, search "select" mode) skip it.
+
+```typescript
+const root: TreeNode = {
+  item: { key: 'root', label: 'root' },
+  children: [
+    {
+      item: { key: 'fruit', label: 'Fruit', selectable: false },   // heading only
+      children: [
+        { item: { key: 'apple', label: 'Apple', isLeaf: true } },  // selectable
+        { item: { key: 'pear', label: 'Pear', isLeaf: true } },
+      ],
+    },
+  ],
+};
+```
+
+In `checked` mode:
+
+- An unselectable row is drawn **without a checkbox**, and clicks in its leading region (indent, caret, icon) expand/collapse it like a normal row instead of toggling a checkbox.
+- Its selectable descendants behave as normal. Unselectable leaves are ignored when working out a parent's `checked` / `indeterminate` state, so a branch whose only selectable children are all checked shows as checked.
+- Only the item's own flag decides whether a checkbox is drawn. A branch that `selectionFilter="leaf"` stops being selected itself still gets a checkbox, because that checkbox toggles its descendants.
+
+**Alignment.** By default an unselectable row reserves no space where the checkbox would be, so its caret and label sit further left than its selectable siblings. Set the `align-checkboxes` attribute (or `alignCheckboxes = true`) to keep that space:
+
+```html
+<ixfx-tree-list interaction-mode="checked" align-checkboxes></ixfx-tree-list>
+```
+
+The reserved space is an empty `<span class="tree-checkbox-spacer" aria-hidden="true">` the same size as a checkbox (`--tree-checkbox-size`, default `14px`, plus a `--space-xs` right margin). The native checkbox uses the same size, so rows line up exactly.
+
+`alignCheckboxes` has no effect outside `checked` mode. `selectable: false` is honoured by the other tree components for selection, but only `ixfx-tree-list` draws checkboxes. See the "Unselectable items" section of `demo/tree-list.html` for a live example with a toggle.
+
 ### `selectionFilter`
 
 | Value | Behaviour |
 |-------|-----------|
 | `'none'` | No nodes can be selected |
-| `'leaf'` | Only leaf nodes (`isLeaf: true` or `children: []`) can be selected |
+| `'leaf'` | Only leaf nodes can be selected: `isLeaf: true`, or a loaded node with `children: []` (unless `isLeaf: false`). A node whose `children` are not loaded yet is not a leaf |
 | `'branch'` | Only branch nodes can be selected |
 
 ### `exclusivity`

package/package.json

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