@slotted/angular 0.0.0-stage → 0.1.0-beta.1

package/docs/tree.md

@@ -0,0 +1,397 @@
+<!-- index: ./index.md -->
+# tree
+
+`data-ui="tree"` · Hierarchy of items that expand and select.
+
+## Import
+
+```ts
+import {
+  provideTreeDefaults,
+  SlTree,
+  SlTreeActions,
+  SlTreeDescription,
+  SlTreeEmpty,
+  SlTreeGroup,
+  SlTreeIcon,
+  SlTreeLabel,
+  SlTreeMeta,
+  SlTreeNode,
+} from '@slotted/angular/tree';
+```
+
+Selector: `[slTree], li[slTreeNode], ul[slTreeGroup], [slTreeIcon], [slTreeLabel], [slTreeDescription], [slTreeMeta], [slTreeActions], [slTreeEmpty]` · exportAs: `slTree, slTreeNode`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div slTree aria-label="Project files" [expandedKeys]="['src']">
+  <li slTreeNode value="src" label="src">
+    <span slTreeMeta>12</span>
+    <ul slTreeGroup>
+      <li slTreeNode value="index.ts" label="index.ts"></li>
+      <li slTreeNode value="lib" label="lib"></li>
+    </ul>
+  </li>
+  <li slTreeNode value="readme" label="README.md"></li>
+</div>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the element carrying slTree | yes |
+| `canvas` | ul with role="tree" | yes |
+| `node` | li with role="treeitem" | yes |
+| `row` | div | yes |
+| `guide` | span | no |
+| `expander` | span | yes |
+| `indicator` | span | no |
+| `icon` | span | no |
+| `label` | span | yes |
+| `description` | span | no |
+| `meta` | span | no |
+| `loader` | span with data-ui="spinner" | no |
+| `actions` | div | no |
+| `group` | ul[slTreeGroup] with role="group" | no |
+| `empty` | div | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `model<string \| readonly string[] \| null>` | — | SlTree | The chosen key, or the set of them in multiple. Two-way, and the control a reactive form writes into |
+| `expandedKeys` | `model<readonly string[]>` | — | SlTree | Which branches are open. Two-way, and a filter never moves it |
+| `activeKey` | `model<string \| null>` | — | SlTree | The node the keyboard is on. It is not the selection, and the pattern says so |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | SlTree | The type step the rows sit at |
+| `variant` | `'plain' \| 'framed'` | plain | SlTree | Whether the tree draws its own box |
+| `structure` | `'auto' \| 'nested' \| 'flat'` | auto | SlTree | Whether the nodes nest in groups or lie flat with their level stated. auto answers flat while windowed |
+| `selectionMode` | `'none' \| 'single' \| 'multiple'` | single | SlTree | How many nodes may be chosen at once |
+| `selectionBehavior` | `'toggle' \| 'replace'` | toggle | SlTree | Which of the two models the pattern offers is in force. toggle is the one it recommends |
+| `selectionIndicator` | `'auto' \| 'highlight' \| 'checkbox' \| 'none'` | auto | SlTree | How the selection is drawn, and which attribute states it. auto reads the mode beside it |
+| `selectionCascade` | `'none' \| 'descendants'` | none | SlTree | Whether pressing a branch takes its enabled descendants with it. Needs nodes |
+| `expandOn` | `'row' \| 'expander'` | row | SlTree | What a press on the row does to a branch |
+| `focusMode` | `'auto' \| 'roving' \| 'activedescendant'` | auto | SlTree | How the keyboard position is expressed. auto answers activedescendant while windowed |
+| `guides` | `boolean` | true | SlTree | Whether the lines that say which parent a row belongs to are drawn |
+| `loop` | `boolean` | false | SlTree | Whether the arrows wrap past the ends |
+| `typeahead` | `boolean` | true | SlTree | Whether typing a name moves the keyboard to it |
+| `typeaheadTimeout` | `number` | 500 | SlTree | Milliseconds of silence before a new search begins |
+| `selectOnFocus` | `boolean` | false | SlTree | Whether moving the keyboard also chooses |
+| `navigateDisabled` | `boolean` | false | SlTree | Whether the arrows land on a disabled node |
+| `disallowEmptySelection` | `boolean` | false | SlTree | Whether the last chosen node may be unchosen |
+| `disallowSelectAll` | `boolean` | false | SlTree | Whether Control and A may take the whole set |
+| `pageSize` | `number` | 10 | SlTree | How far the page keys travel |
+| `virtual` | `boolean` | false | SlTree | Whether only the rows the viewport covers are rendered |
+| `itemSize` | `number` | 32 | SlTree | The block size of one row, in pixels. Required whenever virtual |
+| `overscan` | `number` | 4 | SlTree | Rows rendered either side of the viewport |
+| `disabled` | `boolean` | false | SlTree | Whether the whole tree refuses the reader |
+| `readOnly` | `boolean` | false | SlTree | Whether the tree may be read and not moved |
+| `required` | `boolean` | false | SlTree | Whether a choice is required. The family validates this one rule and no other |
+| `invalid` | `boolean` | false | SlTree | Whether the tree is in error |
+| `loading` | `boolean` | false | SlTree | Whether the set is still arriving. Writes aria-busy |
+| `nodes` | `readonly T[]` | — | SlTree | The hierarchy the tree holds. What a cascade, expandAll and the filter read |
+| `getKey` | `(node: T) => string` | — | SlTree | The identity that survives a reorder |
+| `getLabel` | `(node: T) => string` | — | SlTree | What the reader sees and what typeahead matches |
+| `getChildren` | `(node: T) => readonly T[] \| undefined` | — | SlTree | The children, in the nested shape |
+| `getLevel` | `(node: T) => number` | — | SlTree | The depth, in the already-flat shape a rowset backend returns |
+| `hasChildren` | `(node: T) => boolean` | — | SlTree | Whether a node is a branch before it can prove it |
+| `getChildrenCount` | `(node: T) => number \| undefined` | — | SlTree | How many children will arrive, which draws the placeholder |
+| `isNodeDisabled` | `(node: T) => boolean` | — | SlTree | Which nodes refuse the reader |
+| `isNodeLoading` | `(node: T) => boolean` | — | SlTree | Which branches are fetching their children |
+| `query` | `string` | — | SlTree | What the tree filters by. The consumer owns the string and the field |
+| `label` | `string` | — | SlTreeNode | The node's name, and what names it |
+| `hasChildren` | `boolean` | — | SlTreeNode | Whether this node is a branch whose children have not been written yet |
+| `loading` | `boolean` | — | SlTreeNode | Whether the children are on their way |
+| `disabled` | `boolean` | — | SlTreeNode | Unstated rather than false, so the node defers |
+| `textValue` | `string` | — | SlTreeNode | What typeahead matches, when the label is not plain text |
+| `match` | `'hit' \| 'ancestor'` | — | SlTreeNode | Whether a query matched this name or one below it |
+| `pinned` | `boolean` | — | SlTreeNode | Rendered at its own place on the canvas, outside the window |
+| `offset` | `number` | — | SlTreeNode | Where a pinned row sits on the canvas, in pixels |
+| `level` | `number` | — | SlTreeNode | Stated only by the flat shape; elsewhere the markup says it |
+| `busy` | `boolean` | — | SlTreeGroup | Whether the children in this group are still arriving |
+| `provideTreeDefaults` | `(defaults: Partial<TreeDefaults>)` | — | an injector | Sets twenty-one axes once for every tree under it. An explicit input still wins |
+| `slTreeGroup` | `directive on a ul` | — | inside a node | The list a branch's children are written in. Angular parses a template as HTML, where an li closes the li before it, so a node inside a node needs the list between them |
+| `slTreeIcon, slTreeDescription, slTreeMeta, slTreeActions` | `directives` | — | inside a node | The cells of a row, each one whatever the consumer projects. The family owns no folder glyph of its own |
+| `exportAs` | `slTree, slTreeNode` | — | a template | Reaches the instance for focus, scrollToKey, expand, collapse, expandAll and collapseAll |
+| `ControlValueAccessor` | `formControlName, ngModel` | — | SlTree | The tree is the form control over its selection, and validates required |
+| `data-expanded, data-selected, data-loading` | `attribute` | — | the node | Every state the contract declares is in the DOM, so an icon can be swapped by state in CSS alone with no input for it |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `valueChange` | `(value: string \| readonly string[] \| null)` | The two-way half of value. The set in multiple, one key otherwise. |
+| `valueRequest` | `(request: ChangeRequest)` | Before the selection moves. The request carries the value it replaces, the reason — pointer, keyboard, select, clear or programmatic — the originating event, and cancel(). |
+| `expandedKeysRequest` | `(request: ChangeRequest)` | Before a branch opens or closes. Reasons: pointer, keyboard, programmatic. A filter is not among them: it holds a path open without moving the set. |
+| `activeKeyRequest` | `(request: ChangeRequest)` | Before the node the keyboard is on moves. Closing a branch that holds the active node emits this first, so the pair stays coherent. |
+| `nodeActivate` | `({ key: string; reason: 'pointer' \| 'keyboard' })` | When a node is pressed, or Enter is pressed on it. It is not the selection: a navigation tree opens a page here and chooses nothing. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `variant` | `plain`, `framed` | `plain` |
+| `structure` | `auto`, `nested`, `flat` | `auto` |
+| `selectionMode` | `none`, `single`, `multiple` | `single` |
+| `selectionBehavior` | `toggle`, `replace` | `toggle` |
+| `selectionIndicator` | `auto`, `highlight`, `checkbox`, `none` | `auto` |
+| `selectionCascade` | `none`, `descendants` | `none` |
+| `expandOn` | `row`, `expander` | `row` |
+| `focusMode` | `auto`, `roving`, `activedescendant` | `auto` |
+| `guides` | `true`, `false` | `true` |
+| `loop` | `true`, `false` | `false` |
+| `typeahead` | `true`, `false` | `true` |
+| `selectOnFocus` | `true`, `false` | `false` |
+| `navigateDisabled` | `true`, `false` | `false` |
+| `disallowEmptySelection` | `true`, `false` | `false` |
+| `disallowSelectAll` | `true`, `false` | `false` |
+| `virtual` | `true`, `false` | `false` |
+| `disabled` | `true`, `false` | `false` |
+
+## Rules
+
+- The tree carries its own accessible name, which the pattern requires: aria-label or aria-labelledby reaches the element with role="tree".
+- Each node is named by its own label through aria-labelledby, because a treeitem contains the group holding its children and a name computed from its contents is the whole subtree read aloud.
+- aria-expanded is on branches and never on leaves: a leaf carrying it is announced as a parent.
+- Selection is stated with aria-selected or with aria-checked and never with both, which the pattern allows only under three conditions it calls extremely rare.
+- aria-level, aria-setsize and aria-posinset are written only while the rows are flat — the condition the pattern names — because the nesting is what the browser computes them from otherwise.
+- The whole tree is one tab stop. Focus lands on the chosen node when there is one and on the first node otherwise, and a windowed tree keeps the active node in the document rather than letting a recycled row take it away.
+
+## Tokens
+
+`--slotted-border-strong`, `--slotted-border-subtle`, `--slotted-border-width-medium`, `--slotted-border-width-thin`, `--slotted-control-border-color`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-gap-lg`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-invalid-edge-width`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-shadow`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-color-invalid`, `--slotted-focus-ring-width`, `--slotted-font-family-sans`, `--slotted-font-size-xs`, `--slotted-font-weight-semibold`, `--slotted-highlight-tint-opacity`, `--slotted-line-height-sm`, `--slotted-radius-md`, `--slotted-radius-xs`, `--slotted-selection-size-lg`, `--slotted-selection-size-md`, `--slotted-selection-size-sm`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-surface`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-on-solid`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-danger-border`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-tree-border-color`, `--slotted-tree-guide-color`, `--slotted-tree-highlight`, `--slotted-tree-highlight-active`, `--slotted-tree-indent`, `--slotted-tree-mark-inset`, `--slotted-tree-measure`, `--slotted-tree-padding-block`, `--slotted-tree-padding-inline`, `--slotted-tree-radius`, `--slotted-tree-rows`, `--slotted-tree-selected-edge`, `--slotted-tree-selected-surface`, `--slotted-tree-selected-text`, `--slotted-tree-shadow`, `--slotted-tree-surface`, `--slotted-tree-text`, `--slotted-tree-text-muted`
+
+## Examples
+
+### Opening and closing a branch
+
+The row opens the branch by default; the second tree gives that job to the chevron alone. Press each of them, then use the sideways arrows on both.
+
+Excerpt — not a complete module
+
+```html
+<div slTree aria-label="Files" expandOn="expander" [(expandedKeys)]="open">
+  <ng-container [ngTemplateOutlet]="nodes" />
+</div>
+```
+
+### One choice, several, or none
+
+Three trees side by side. The multi-select one writes aria-checked and draws a box; the single one writes aria-selected and says it with the band; the third writes neither.
+
+Excerpt — not a complete module
+
+```html
+<div slTree aria-label="Permissions" selectionMode="multiple" [(value)]="chosen">
+  <ng-container [ngTemplateOutlet]="nodes" />
+</div>
+```
+
+### A branch that takes its descendants with it
+
+Press the folder and watch every enabled file under it follow, including the ones inside a branch that is closed. The locked file is left exactly where it was.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slTree
+  aria-label="Permissions"
+  selectionMode="multiple"
+  selectionCascade="descendants"
+  [nodes]="roots"
+  [getKey]="key"
+  [getLabel]="name"
+  [getChildren]="children"
+  [(value)]="chosen"
+></div>
+```
+
+### How the selection is said
+
+The same value under the two indicators. The box states aria-checked and is the box the checkbox family draws; the highlight states aria-selected and spends no cell at all.
+
+Excerpt — not a complete module
+
+```html
+<div slTree aria-label="Files" selectionIndicator="checkbox" [(value)]="chosen">
+  <ng-container [ngTemplateOutlet]="nodes" />
+</div>
+```
+
+### The lines that say which parent a row belongs to
+
+Depth four with the guides on and off. Each line sits under the chevron of the level above it, at one distance from the row it belongs to, at every size.
+
+Excerpt — not a complete module
+
+```html
+<div slTree aria-label="Packages" [guides]="false" [(expandedKeys)]="open">
+  <ng-container [ngTemplateOutlet]="nodes" />
+</div>
+```
+
+### The three type steps
+
+Small, medium and large in a column. The row height, the type, the glyph and the indent all move together, and the distance from a guide to its chevron does not.
+
+Excerpt — not a complete module
+
+```html
+<div slTree aria-label="Files" size="sm" [(expandedKeys)]="open">
+  <ng-container [ngTemplateOutlet]="nodes" />
+</div>
+```
+
+### Framed, and inside something that already has an edge
+
+The framed tree draws its own box; the plain one draws none, for a panel or a drawer that has drawn one already. Both keep the same row.
+
+Excerpt — not a complete module
+
+```html
+<div slTree aria-label="Navigation" variant="plain" [(expandedKeys)]="open">
+  <ng-container [ngTemplateOutlet]="nodes" />
+</div>
+```
+
+### Every state a row can be in
+
+At rest, hovered, where the keyboard is, chosen, both at once, out of reach, and fetching. Chosen outranks the keyboard, and disabled outranks everything.
+
+Excerpt — not a complete module
+
+```html
+<li slTreeNode value="payroll" label="Payroll" disabled>
+  <span slTreeDescription>no access</span>
+</li>
+```
+
+### Nothing yet, and nothing at all
+
+A tree still loading its roots, and one whose query matched nothing. The empty part replaces no row: the tree keeps its name and its role either way.
+
+Excerpt — not a complete module
+
+```html
+<div slTree aria-label="Files" [nodes]="[]" [getKey]="key">
+  <p slTreeEmpty>No files here</p>
+</div>
+```
+
+### Children that arrive after the branch opens
+
+Press the folder. The request goes out, the ring stands where the chevron stood, the group says aria-busy, and the placeholder rows are the width names would have been.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slTree
+  aria-label="Files"
+  [nodes]="roots"
+  [getKey]="key"
+  [hasChildren]="isFolder"
+  [getChildrenCount]="count"
+  [isNodeLoading]="pending"
+  [expandedKeys]="open()"
+  (expandedKeysRequest)="fetch($event)"
+></div>
+```
+
+### Searching a tree without losing where things are
+
+Type in the field. Every hit keeps its ancestors, the matched span is marked, and the path is held open for as long as the query lasts without moving the set the reader opened.
+
+Excerpt — not a complete module
+
+```html
+<input slTextField aria-label="Search" [(ngModel)]="query" />
+<div slTree aria-label="Files" [query]="query()" [nodes]="roots" [getKey]="key"></div>
+```
+
+### Four thousand rows, and the ones on screen
+
+Scroll it. Only the covered slice is rendered, the rows are laid flat with their level stated, and the node the keyboard is on stays in the document however far it is scrolled away.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slTree
+  aria-label="Regions"
+  virtual
+  [itemSize]="32"
+  [nodes]="roots"
+  [getKey]="key"
+  [getLabel]="name"
+  [getChildren]="children"
+></div>
+```
+
+### Content the tree did not choose
+
+A name that is one unbroken token, a translated name twice the length, and a right-to-left name in a left-to-right tree. Each takes its own direction and truncates rather than pushing the count out.
+
+Excerpt — not a complete module
+
+```html
+<li slTreeNode value="report" label="quarterly-report-2026.pdf">
+  <span slTreeIcon><svg viewBox="0 0 24 24"></svg></span>
+  <span slTreeDescription>edited</span>
+  <span slTreeMeta>18 kB</span>
+</li>
+```
+
+### A tree that belongs to a form
+
+The tree is the control: a reactive control writes into it and reads back out of it, and required is the one rule the family can decide from the value alone.
+
+Excerpt — not a complete module
+
+```html
+<form [formGroup]="form">
+  <div slTree aria-label="Permissions" formControlName="scopes" selectionMode="multiple" required>
+    <ng-container [ngTemplateOutlet]="nodes" />
+  </div>
+</form>
+```
+
+### What a consumer can put in a row, and set once
+
+A row with an icon, a count and a trailing control, beside a provider that gives every tree under it the same size and the same expansion target.
+
+Excerpt — not a complete module
+
+```ts
+providers: [provideTreeDefaults({ size: 'sm', expandOn: 'expander', guides: false })];
+```
+
+### Every key the pattern gives a tree
+
+Tab in and try them: the sideways arrows open, enter and leave a branch; Home and End cross the whole list; the asterisk opens every sibling at the level.
+
+Excerpt — not a complete module
+
+```html
+<div slTree aria-label="Files" [(activeKey)]="active" (activeKeyRequest)="announce($event)">
+  <ng-container [ngTemplateOutlet]="nodes" />
+</div>
+```
+
+### What a reader hears
+
+The tree carries its own name, each node is named by its own label rather than by the subtree under it, and a branch that is fetching says so through a live region once.
+
+Excerpt — not a complete module
+
+```html
+<h2 id="files-heading">Project files</h2>
+<div slTree aria-labelledby="files-heading">
+  <ng-container [ngTemplateOutlet]="nodes" />
+</div>
+```