@ixfx/components 0.14.2 → 0.14.4

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.
@@ -201,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.2",
+  "version": "0.14.4",
   "packageManager": "pnpm@10.0.0",
   "description": "Web components for ixfx — Lit-based UI toolkit",
   "author": "Clint Heyer",