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

package/dist/docs/tree.md

@@ -0,0 +1,417 @@
+<!-- index: ./index.md -->
+# tree
+
+`data-ui="tree"` · Hierarchy of items that expand and select.
+
+## Import
+
+```tsx
+import {
+  Tree,
+  TreeDefaultsProvider,
+  TreeDescription,
+  TreeEmpty,
+  TreeGroup,
+  TreeIcon,
+  TreeLabel,
+  TreeMeta,
+  TreeNode,
+} from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<Tree aria-label="Project files" defaultExpandedKeys={['src']}>
+  <TreeNode value="src" label="src" meta="12">
+    <TreeNode value="index.ts" label="index.ts" />
+    <TreeNode value="lib" label="lib">
+      <TreeNode value="tree.ts" label="tree.ts" />
+    </TreeNode>
+  </TreeNode>
+  <TreeNode value="readme" label="README.md" />
+</Tree>;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div, or the element render returns | 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 with role="group" | no |
+| `empty` | div | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string \| readonly string[] \| null` | — | Tree | The chosen key, or the set of them in multiple. Present means controlled, for the life of the component |
+| `defaultValue` | `string \| readonly string[] \| null` | — | Tree | What an uncontrolled tree starts from, read once |
+| `expandedKeys` | `readonly string[]` | — | Tree | Which branches are open. Present means controlled; a filter never moves it |
+| `defaultExpandedKeys` | `readonly string[]` | — | Tree | The set an uncontrolled tree opens with |
+| `activeKey` | `string \| null` | — | Tree | The node the keyboard is on. It is not the selection, and the pattern says so |
+| `defaultActiveKey` | `string \| null` | — | Tree | Where the keyboard starts in an uncontrolled tree |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | Tree | The type step the rows sit at |
+| `variant` | `'plain' \| 'framed'` | plain | Tree | Whether the tree draws its own box |
+| `structure` | `'auto' \| 'nested' \| 'flat'` | auto | Tree | Whether the nodes nest in groups or lie flat with their level stated. auto answers flat while windowed |
+| `selectionMode` | `'none' \| 'single' \| 'multiple'` | single | Tree | How many nodes may be chosen at once |
+| `selectionBehavior` | `'toggle' \| 'replace'` | toggle | Tree | Which of the two models the pattern offers is in force. toggle is the one it recommends |
+| `selectionIndicator` | `'auto' \| 'highlight' \| 'checkbox' \| 'none'` | auto | Tree | How the selection is drawn, and which attribute states it. auto reads the mode beside it |
+| `selectionCascade` | `'none' \| 'descendants'` | none | Tree | Whether pressing a branch takes its enabled descendants with it. Needs nodes |
+| `expandOn` | `'row' \| 'expander'` | row | Tree | What a press on the row does to a branch |
+| `focusMode` | `'auto' \| 'roving' \| 'activedescendant'` | auto | Tree | How the keyboard position is expressed. auto answers activedescendant while windowed |
+| `guides` | `boolean` | true | Tree | Whether the lines that say which parent a row belongs to are drawn |
+| `loop` | `boolean` | false | Tree | Whether the arrows wrap past the ends |
+| `typeahead` | `boolean` | true | Tree | Whether typing a name moves the keyboard to it |
+| `typeaheadTimeout` | `number` | 500 | Tree | Milliseconds of silence before a new search begins |
+| `selectOnFocus` | `boolean` | false | Tree | Whether moving the keyboard also chooses |
+| `navigateDisabled` | `boolean` | false | Tree | Whether the arrows land on a disabled node |
+| `disallowEmptySelection` | `boolean` | false | Tree | Whether the last chosen node may be unchosen |
+| `disallowSelectAll` | `boolean` | false | Tree | Whether Control and A may take the whole set |
+| `pageSize` | `number` | 10 | Tree | How far the page keys travel |
+| `virtual` | `boolean` | false | Tree | Whether only the rows the viewport covers are rendered |
+| `itemSize` | `number` | 32 | Tree | The block size of one row, in pixels. Required whenever virtual |
+| `overscan` | `number` | 4 | Tree | Rows rendered either side of the viewport |
+| `disabled` | `boolean` | false | Tree | Whether the whole tree refuses the reader |
+| `readOnly` | `boolean` | false | Tree | Whether the tree may be read and not moved |
+| `required` | `boolean` | false | Tree | Whether a choice is required of the form around it |
+| `invalid` | `boolean` | false | Tree | Whether the tree is in error |
+| `loading` | `boolean` | false | Tree | Whether the set is still arriving. Writes aria-busy |
+| `name` | `string` | — | Tree | Submits one hidden input per chosen key |
+| `nodes` | `readonly T[]` | — | Tree | The hierarchy the tree holds. What a cascade, expandAll and the filter read |
+| `getKey` | `(node: T) => string` | — | Tree | The identity that survives a reorder |
+| `getLabel` | `(node: T) => string` | — | Tree | What the reader sees and what typeahead matches |
+| `getChildren` | `(node: T) => readonly T[] \| undefined` | — | Tree | The children, in the nested shape |
+| `getLevel` | `(node: T) => number` | — | Tree | The depth, in the already-flat shape a rowset backend returns |
+| `hasChildren` | `(node: T) => boolean` | — | Tree | Whether a node is a branch before it can prove it |
+| `getChildrenCount` | `(node: T) => number \| undefined` | — | Tree | How many children will arrive, which draws the placeholder |
+| `isNodeDisabled` | `(node: T) => boolean` | — | Tree | Which nodes refuse the reader |
+| `isNodeLoading` | `(node: T) => boolean` | — | Tree | Which branches are fetching their children |
+| `renderNode` | `(node: T, key: string) => ReactNode` | — | Tree | The content of one row. The family renders the row around it |
+| `query` | `string` | — | Tree | What the tree filters by. The consumer owns the string and the field |
+| `emptyContent` | `ReactNode` | — | Tree | What the tree shows when it holds nothing |
+| `render` | `(props: TreeRootProps) => ReactNode` | — | Tree | Substitutes the element the root renders |
+| `handleRef` | `Ref<TreeHandle>` | — | Tree | focus, scrollToKey, expand, collapse, expandAll, collapseAll, getActiveKey, getElement |
+| `label` | `ReactNode` | — | TreeNode | The node's name, and what names it |
+| `description` | `ReactNode` | — | TreeNode | A second line beside the name |
+| `icon` | `ReactNode` | — | TreeNode | The leading picture, which the consumer owns whole |
+| `meta` | `ReactNode` | — | TreeNode | The trailing count, size or badge |
+| `actions` | `ReactNode` | — | TreeNode | The trailing controls, which stay reachable |
+| `textValue` | `string` | — | TreeNode | What typeahead matches, when the label is not plain text |
+| `match` | `'hit' \| 'ancestor'` | — | TreeNode | Whether a query matched this name or one below it |
+| `pinned` | `boolean` | — | TreeNode | Rendered at its own place on the canvas, outside the window |
+| `offset` | `number` | — | TreeNode | Where a pinned row sits on the canvas, in pixels |
+| `depth` | `number` | — | TreeNode | Stated only by the flat shape; elsewhere the markup says it |
+| `TreeDefaultsProvider` | `{ size, variant, expandOn, … }` | — | a subtree | Sets twenty-one axes once for every tree under it. An explicit prop still wins |
+| `render` | `(props) => ReactNode` | — | Tree, TreeNode | Renders the part into another element, keeping every attribute and handler it was given |
+| `label, description, icon, meta, actions` | `ReactNode` | — | TreeNode | The cells of a row, each one whatever the consumer renders. The family owns no folder glyph of its own |
+| `handleRef` | `Ref<TreeHandle>` | — | Tree | focus, scrollToKey, expand, collapse, expandAll, collapseAll, getActiveKey and getElement — the actions a consumer cannot express declaratively |
+| `onClick` | `(event: MouseEvent) => void` | — | TreeNode | Runs before the family acts, and preventDefault stops it. Every handler composes rather than replaces |
+| `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 prop for it |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onValueChange` | `(value: string \| readonly string[] \| null, request: ChangeRequest)` | Before the selection moves. The value is one key in single and none, and the set in multiple. The request carries the value it replaces, the reason — pointer, keyboard, select, clear or programmatic — the originating event, and cancel(). |
+| `onExpandedKeysChange` | `(keys: readonly string[], 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. |
+| `onActiveKeyChange` | `(key: string \| null, request: ChangeRequest)` | Before the node the keyboard is on moves. Reasons: pointer, keyboard, programmatic. Closing a branch that holds the active node emits this first, so the pair stays coherent. |
+| `onNodeActivate` | `(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
+
+```tsx
+<Tree aria-label="Files" expandOn="expander" defaultExpandedKeys={['src']}>
+  {nodes}
+</Tree>;
+```
+
+### 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
+
+```tsx
+<Tree
+  aria-label="Permissions"
+  selectionMode="multiple"
+  defaultValue={['revenue']}
+  defaultExpandedKeys={['reports']}
+>
+  {nodes}
+</Tree>;
+```
+
+### 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
+
+```tsx
+<Tree
+  aria-label="Permissions"
+  selectionMode="multiple"
+  selectionCascade="descendants"
+  nodes={roots}
+  getKey={(node) => node.id}
+  getLabel={(node) => node.name}
+  getChildren={(node) => node.children}
+/>;
+```
+
+### 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
+
+```tsx
+<Tree aria-label="Files" selectionIndicator="checkbox" defaultValue="index.ts">
+  {nodes}
+</Tree>;
+```
+
+### 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
+
+```tsx
+<Tree aria-label="Packages" guides={false} defaultExpandedKeys={['a', 'b', 'c']}>
+  {nodes}
+</Tree>;
+```
+
+### 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
+
+```tsx
+<Tree aria-label="Files" size="sm" defaultExpandedKeys={['src']}>
+  {nodes}
+</Tree>;
+```
+
+### 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
+
+```tsx
+<Tree aria-label="Navigation" variant="plain" defaultExpandedKeys={['reports']}>
+  {nodes}
+</Tree>;
+```
+
+### 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
+
+```tsx
+<TreeNode value="payroll" label="Payroll" description="no access" disabled />;
+```
+
+### 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
+
+```tsx
+<Tree aria-label="Files" nodes={[]} getKey={(node) => node.id} emptyContent="No files here" />;
+```
+
+### 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
+
+```tsx
+<Tree
+  aria-label="Files"
+  nodes={roots}
+  getKey={(node) => node.id}
+  hasChildren={(node) => node.type === 'folder'}
+  getChildrenCount={(node) => node.count}
+  isNodeLoading={(node) => pending.has(node.id)}
+  onExpandedKeysChange={(keys, request) => {
+    if (request.reason !== 'programmatic') fetchChildren(keys);
+    setExpanded(keys);
+  }}
+/>;
+```
+
+### 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
+
+```tsx
+<>
+  <TextField aria-label="Search" value={query} onValueChange={setQuery} />
+  <Tree
+    aria-label="Files"
+    query={query}
+    nodes={roots}
+    getKey={(node) => node.id}
+    getLabel={(node) => node.name}
+    getChildren={(node) => node.children}
+  />
+</>;
+```
+
+### 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
+
+```tsx
+<Tree
+  aria-label="Regions"
+  virtual
+  itemSize={32}
+  nodes={roots}
+  getKey={(node) => node.id}
+  getLabel={(node) => node.name}
+  getChildren={(node) => node.children}
+/>;
+```
+
+### 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
+
+```tsx
+<TreeNode
+  value="report"
+  label="quarterly-report-2026.pdf"
+  description="edited"
+  icon={<FileIcon />}
+  meta="18 kB"
+/>;
+```
+
+### A tree that submits
+
+One hidden input per chosen key, under the name the form reads. The tree is the control, and a bare form carries the set without a controlled value anywhere.
+
+Excerpt — not a complete module
+
+```tsx
+<form action="/permissions" method="post">
+  <Tree aria-label="Permissions" name="scopes" selectionMode="multiple">
+    {nodes}
+  </Tree>
+  <Button type="submit">Save</Button>
+</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
+
+```tsx
+<TreeDefaultsProvider size="sm" expandOn="expander" guides={false}>
+  <Tree aria-label="Files">{nodes}</Tree>
+</TreeDefaultsProvider>;
+```
+
+### 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
+
+```tsx
+<Tree
+  aria-label="Files"
+  activeKey={active}
+  onActiveKeyChange={(key, request) => {
+    if (request.reason === 'keyboard') announce(key);
+    setActive(key);
+  }}
+>
+  {nodes}
+</Tree>;
+```
+
+### 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
+
+```tsx
+<Tree aria-labelledby="files-heading">{nodes}</Tree>;
+```