@cardstack/boxel-cli 0.10.0 → 0.10.1-unstable.0

package/bundled-realms/pretui/components/tree-select.usage.gts

@@ -0,0 +1,75 @@
+// Pretui — TreeSelect usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { TreeSelect } from './tree-select';
+import type { TreeNode } from './tree';
+
+const TEAS: TreeNode[] = [
+  { id: 'green', label: 'Green', children: [{ id: 'sencha', label: 'Sencha' }, { id: 'gyokuro', label: 'Gyokuro' }, { id: 'matcha', label: 'Matcha' }] },
+  { id: 'oolong', label: 'Oolong', children: [{ id: 'dhp', label: 'Da Hong Pao' }, { id: 'tgy', label: 'Tieguanyin' }] },
+  { id: 'black', label: 'Black', children: [{ id: 'assam', label: 'Assam' }, { id: 'keemun', label: 'Keemun' }] },
+  { id: 'puer', label: 'Pu-erh' },
+];
+
+export class TreeSelectUsage extends Component {
+  teas = TEAS;
+  @tracked value: string[] = ['green', 'sencha', 'gyokuro', 'matcha', 'dhp'];
+  @tracked multiple = true;
+  @tracked cascade = true;
+  setValue = (v: string[]) => (this.value = v);
+  setMultiple = (v: boolean) => {
+    this.multiple = v;
+    this.value = [];
+  };
+  setCascade = (v: boolean) => (this.cascade = v);
+  get usage() {
+    let bits = ['@nodes={{this.teas}}', '@value={{this.checked}}', '@onChange={{this.setChecked}}', "@label='Teas'"];
+    if (!this.multiple) bits.push('@multiple={{false}}');
+    if (!this.cascade) bits.push('@cascade={{false}}');
+    return `<TreeSelect ${bits.join(' ')} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='TreeSelect'
+      @description='A select whose popup is a checkable tree. With cascade on, checking a branch checks everything under it, a partly checked branch reads as mixed, and a fully checked branch shows as one chip. The value is every checked id in tree order. Single mode picks one node and closes.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='tsl-demo'>
+          <TreeSelect @nodes={{this.teas}} @value={{this.value}} @onChange={{this.setValue}} @multiple={{this.multiple}} @cascade={{this.cascade}} @label='Teas' @placeholder='Any tea' />
+          <p class='tsl-demo-value'>Value: <code>{{#each this.value as |v|}}{{v}} {{/each}}</code></p>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.Object @name='nodes' @required={{true}} @description='The same TreeNode shape as Tree.' />
+        <Args.Object @name='value' @description='Checked ids in tree order. defaultValue seeds the uncontrolled form.' />
+        <Args.Action @name='onChange' />
+        <Args.Bool @name='multiple' @value={{this.multiple}} @defaultValue={{true}} @onInput={{this.setMultiple}} />
+        <Args.Bool @name='cascade' @value={{this.cascade}} @defaultValue={{true}} @onInput={{this.setCascade}} />
+        <Args.Object @name='defaultExpanded' @description='Branches open when the popup opens.' />
+        <Args.Number @name='maxChips' @defaultValue={{3}} @description='Chips before +N.' />
+        <Args.String @name='label' />
+        <Args.String @name='placeholder' />
+        <Args.Bool @name='disabled' @defaultValue={{false}} />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .tsl-demo {
+        display: grid;
+        gap: var(--space-2, 0.375rem);
+        max-inline-size: 22rem;
+        padding-block-end: 18rem;
+      }
+      .tsl-demo-value {
+        margin: 0;
+        font-size: var(--text-ui-sm, 0.72rem);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_TREE_SELECT: Record<string, unknown> = {
+  TreeSelect: TreeSelectUsage,
+};

package/bundled-realms/pretui/components/tree.gts

@@ -0,0 +1,532 @@
+// Pretui — Tree: the WAI-ARIA APG treeview, complete: roles, levels, roving tabindex, arrow keys and type-ahead.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { htmlSafe } from '@ember/template';
+import { focusWhen, listen, rovingTabindex } from '../focus';
+import { StatusChip } from './status-chip';
+import { EmptyState } from './empty-state';
+import { iconFor } from '../icon-registry';
+
+// ── Tree ─────────────────────────────────────────────────────────────────
+// The ARIA treeview pattern, complete.
+//
+// PRESENTATION NOTE (deliberate, not a shortcut): the tree renders FLAT —
+// one <ul role='tree'> whose <li role='treeitem'> children each carry
+// aria-level / aria-posinset / aria-setsize — rather than nesting a
+// <ul role='group'> per branch. Both are conformant; the flat form is what
+// production trees that must stay fast (VS Code's explorer, every virtualized
+// tree) use, because DOM depth stays O(1) in the hierarchy depth, keyboard
+// order is literally DOM order, and no self-recursive component is needed.
+// aria-level carries the depth that the nesting would have carried.
+//
+// Dropped from the upstream surfaces on purpose: multi-select (aria-multi-
+// selectable + Shift/Ctrl ranges — a second selection model the kit has no
+// consumer for yet; say so rather than half-ship it, Law 7), drag-to-reorder
+// (that is <Reorder>'s job), and inline rename (an editing surface, not a
+// reading one). Multi-CHARACTER type-ahead is dropped for a hard reason: the
+// buffer reset needs a timer and the realm forbids timers, so type-ahead here
+// is single-character cycling — press 'd' repeatedly to walk every visible
+// node starting with "d".
+
+export interface TreeNode {
+  /** stable id — the expansion and selection key */
+  id: string;
+  /** the node's text; override the rendering with the <:label> block */
+  label: string;
+  /** icon-registry name (see icon-registry.gts) rendered before the label */
+  icon?: string;
+  /** status value → StatusChip, hue derived from the value (Law 2) */
+  badge?: string;
+  /** quiet trailing text (counts, sizes, ids) */
+  meta?: string;
+  /** node cannot be selected; it still takes keyboard focus so the branch
+   * below it stays reachable */
+  disabled?: boolean;
+  /** child nodes — presence is what makes a node a branch */
+  children?: TreeNode[];
+}
+
+/** One VISIBLE row of the flattened tree: the node plus everything the ARIA
+ * attributes and the keyboard need. Yielded to the <:label> block. */
+export interface TreeRow {
+  node: TreeNode;
+  id: string;
+  /** 1-based depth, straight into aria-level */
+  level: number;
+  /** 1-based position among its siblings */
+  posinset: number;
+  /** sibling count */
+  setsize: number;
+  parentId?: string;
+  hasChildren: boolean;
+  expanded: boolean;
+  style: ReturnType<typeof htmlSafe>;
+}
+
+export interface TreeSignature {
+  Args: {
+    /** the hierarchy; each node may carry children recursively */
+    nodes: TreeNode[];
+    /** accessible name for the tree — required in spirit, defaulted so
+     * nothing is required in practice (Law 7) */
+    label?: string;
+    /** controlled expanded ids; omit for uncontrolled */
+    expanded?: string[];
+    /** initial expanded ids when uncontrolled */
+    defaultExpanded?: string[];
+    /** fires with the full expanded-id list on every expand/collapse */
+    onExpandedChange?: (ids: string[]) => void;
+    /** controlled selected id; omit for uncontrolled */
+    selected?: string | null;
+    /** initial selected id when uncontrolled */
+    defaultSelected?: string;
+    /** fires with the node on Enter/Space/click */
+    onSelect?: (node: TreeNode) => void;
+    /** px of indent per level — also settable as --pretui-tree-indent */
+    indent?: number;
+    /** row height preset: 'compact' 22px, 'comfortable' 26px (default) */
+    density?: 'compact' | 'comfortable';
+    /** single-character type-ahead (default true) */
+    typeahead?: boolean;
+  };
+  Blocks: {
+    /** replaces the label text; receives the node and its row state */
+    label?: [node: TreeNode, row: TreeRow];
+    /** replaces the default EmptyState when @nodes is empty */
+    empty?: [];
+  };
+  Element: HTMLDivElement;
+}
+
+export class Tree extends Component<TreeSignature> {
+  @tracked private internalExpanded: string[] =
+    this.args.defaultExpanded ?? [];
+  @tracked private internalSelected: string | undefined =
+    this.args.defaultSelected;
+  @tracked private focusId: string | undefined = this.args.defaultSelected;
+  // true only while the keyboard is driving — focusWhen never fires on a
+  // pointer path or a plain re-render
+  @tracked private navigating = false;
+
+  get label(): string {
+    return this.args.label ?? 'Tree';
+  }
+  get density(): 'compact' | 'comfortable' {
+    return this.args.density ?? 'comfortable';
+  }
+  get hostStyle(): ReturnType<typeof htmlSafe> | undefined {
+    let indent = this.args.indent;
+    return indent === undefined
+      ? undefined
+      : htmlSafe(`--pretui-tree-indent: ${Math.max(0, indent)}px`);
+  }
+  private get expandedSet(): Set<string> {
+    return new Set(this.args.expanded ?? this.internalExpanded);
+  }
+  get selectedId(): string | undefined {
+    let controlled = this.args.selected;
+    if (controlled !== undefined) {
+      return controlled ?? undefined;
+    }
+    return this.internalSelected;
+  }
+
+  /** The visible rows, depth-first, in DOM order. */
+  get rows(): TreeRow[] {
+    let expanded = this.expandedSet;
+    let out: TreeRow[] = [];
+    let walk = (nodes: TreeNode[], level: number, parentId?: string) => {
+      let setsize = nodes.length;
+      for (let i = 0; i < setsize; i++) {
+        let node = nodes[i];
+        let hasChildren = !!node.children?.length;
+        let isOpen = hasChildren && expanded.has(node.id);
+        out.push({
+          node,
+          id: node.id,
+          level,
+          posinset: i + 1,
+          setsize,
+          parentId,
+          hasChildren,
+          expanded: isOpen,
+          style: htmlSafe(`--_level: ${level}`),
+        });
+        if (isOpen) {
+          walk(node.children as TreeNode[], level + 1, node.id);
+        }
+      }
+    };
+    walk(this.args.nodes ?? [], 1, undefined);
+    return out;
+  }
+  get hasRows(): boolean {
+    return this.rows.length > 0;
+  }
+  /** The single tab stop: the focused row, or the first row if the focused
+   * one scrolled out of visibility (its branch was collapsed). */
+  get rovingId(): string | undefined {
+    let rows = this.rows;
+    let current = this.focusId;
+    if (current && rows.some((r) => r.id === current)) {
+      return current;
+    }
+    return rows[0]?.id;
+  }
+
+  isSelected = (row: TreeRow): boolean => row.id === this.selectedId;
+  isRoving = (row: TreeRow): boolean => row.id === this.rovingId;
+  isFocusTarget = (row: TreeRow): boolean =>
+    this.navigating && row.id === this.rovingId;
+  /** 'true' | 'false' for branches, undefined (attribute removed) for leaves */
+  expandedAttr = (row: TreeRow): string | undefined =>
+    row.hasChildren ? (row.expanded ? 'true' : 'false') : undefined;
+  // returns the boxel-ui icon component for the node's icon name (any-typed
+  // by the registry)
+  iconOf = (row: TreeRow) => iconFor(row.node.icon);
+
+  private setExpanded(id: string, open: boolean) {
+    let next = this.expandedSet;
+    if (open) {
+      next.add(id);
+    } else {
+      next.delete(id);
+    }
+    let ids = Array.from(next);
+    if (this.args.expanded === undefined) {
+      this.internalExpanded = ids;
+    }
+    this.args.onExpandedChange?.(ids);
+  }
+  private toggle(row: TreeRow) {
+    if (!row.hasChildren) {
+      return;
+    }
+    // collapsing can hide the focused descendant — park the tab stop on the
+    // branch the reader just closed rather than snapping to the tree's top
+    this.focusId = row.id;
+    this.setExpanded(row.id, !row.expanded);
+  }
+  private select(row: TreeRow) {
+    if (row.node.disabled) {
+      return;
+    }
+    if (this.args.selected === undefined) {
+      this.internalSelected = row.id;
+    }
+    this.args.onSelect?.(row.node);
+  }
+  private moveTo(row: TreeRow | undefined) {
+    if (!row) {
+      return;
+    }
+    this.navigating = true;
+    this.focusId = row.id;
+  }
+
+  private rowFromEvent(event: Event): TreeRow | undefined {
+    let target = event.target as HTMLElement | null;
+    let el = target?.closest('[data-tree-id]') as HTMLElement | null;
+    let id = el?.dataset.treeId;
+    return id ? this.rows.find((r) => r.id === id) : undefined;
+  }
+
+  onClick = (event: Event) => {
+    let row = this.rowFromEvent(event);
+    if (!row) {
+      return;
+    }
+    // the pointer already moved focus (tabindex=-1 elements are mouse
+    // focusable) — do not let focusWhen fire a second time
+    this.navigating = false;
+    this.focusId = row.id;
+    let target = event.target as HTMLElement | null;
+    if (target?.closest('[data-tree-twisty]')) {
+      this.toggle(row);
+      return;
+    }
+    this.select(row);
+  };
+
+  // Keeps the tab stop wherever the reader last was, including after a Tab
+  // into the tree from elsewhere on the page.
+  //
+  // The early return is load-bearing, not an optimisation: focusWhen's
+  // el.focus() dispatches focusin SYNCHRONOUSLY from inside the modifier,
+  // i.e. during the render transaction. Writing tracked state there is a
+  // backtracking re-render. When the incoming target is already the roving
+  // row, the focus was ours and there is nothing to record.
+  onFocusIn = (event: Event) => {
+    let row = this.rowFromEvent(event);
+    if (!row || row.id === this.rovingId) {
+      return;
+    }
+    this.navigating = false;
+    this.focusId = row.id;
+  };
+
+  onKeydown = (event: Event) => {
+    let ev = event as KeyboardEvent;
+    if (ev.altKey || ev.metaKey || ev.ctrlKey) {
+      return;
+    }
+    let rows = this.rows;
+    let index = rows.findIndex((r) => r.id === this.rovingId);
+    if (index < 0) {
+      return;
+    }
+    let row = rows[index];
+    let key = ev.key;
+    if (key === 'ArrowDown') {
+      ev.preventDefault();
+      this.moveTo(rows[Math.min(rows.length - 1, index + 1)]);
+    } else if (key === 'ArrowUp') {
+      ev.preventDefault();
+      this.moveTo(rows[Math.max(0, index - 1)]);
+    } else if (key === 'ArrowRight') {
+      ev.preventDefault();
+      if (row.hasChildren && !row.expanded) {
+        this.setExpanded(row.id, true);
+      } else if (row.expanded) {
+        // descend to the first child — it is the next visible row
+        this.moveTo(rows[index + 1]);
+      }
+    } else if (key === 'ArrowLeft') {
+      ev.preventDefault();
+      if (row.expanded) {
+        this.setExpanded(row.id, false);
+      } else if (row.parentId) {
+        this.moveTo(rows.find((r) => r.id === row.parentId));
+      }
+    } else if (key === 'Home') {
+      ev.preventDefault();
+      this.moveTo(rows[0]);
+    } else if (key === 'End') {
+      ev.preventDefault();
+      this.moveTo(rows[rows.length - 1]);
+    } else if (key === 'Enter' || key === ' ') {
+      ev.preventDefault();
+      if (row.hasChildren) {
+        this.setExpanded(row.id, !row.expanded);
+      }
+      this.select(row);
+    } else if (key === '*') {
+      // APG: expand every sibling at the focused node's level
+      ev.preventDefault();
+      let next = this.expandedSet;
+      for (let sibling of rows) {
+        if (sibling.parentId === row.parentId && sibling.hasChildren) {
+          next.add(sibling.id);
+        }
+      }
+      let ids = Array.from(next);
+      if (this.args.expanded === undefined) {
+        this.internalExpanded = ids;
+      }
+      this.args.onExpandedChange?.(ids);
+    } else if (
+      (this.args.typeahead ?? true) &&
+      key.length === 1 &&
+      /\S/.test(key)
+    ) {
+      // single-character cycling type-ahead — a multi-character buffer would
+      // need a debounce timer, and the realm forbids timers
+      let ch = key.toLowerCase();
+      for (let step = 1; step <= rows.length; step++) {
+        let candidate = rows[(index + step) % rows.length];
+        if (candidate.node.label.toLowerCase().startsWith(ch)) {
+          ev.preventDefault();
+          this.moveTo(candidate);
+          break;
+        }
+      }
+    }
+  };
+
+  <template>
+    <div
+      class='pretui-tree-host'
+      data-density={{this.density}}
+      style={{this.hostStyle}}
+      data-test-pretui-tree
+      ...attributes
+    >
+      {{#if this.hasRows}}
+        <ul
+          class='pretui-tree'
+          role='tree'
+          aria-label={{this.label}}
+          {{listen 'click' this.onClick}}
+          {{listen 'keydown' this.onKeydown}}
+          {{listen 'focusin' this.onFocusIn}}
+        >
+          {{#each this.rows key='id' as |row|}}
+            <li
+              class='pretui-tree-item'
+              role='treeitem'
+              data-tree-id={{row.id}}
+              data-selected={{if (this.isSelected row) 'true'}}
+              data-branch={{if row.hasChildren 'true'}}
+              aria-level={{row.level}}
+              aria-posinset={{row.posinset}}
+              aria-setsize={{row.setsize}}
+              aria-expanded={{this.expandedAttr row}}
+              aria-selected={{if (this.isSelected row) 'true' 'false'}}
+              aria-disabled={{if row.node.disabled 'true'}}
+              style={{row.style}}
+              {{rovingTabindex (this.isRoving row)}}
+              {{focusWhen (this.isFocusTarget row)}}
+            >
+              <span
+                class='pretui-tree-twisty'
+                data-tree-twisty
+                data-open={{if row.expanded 'true'}}
+                data-leaf={{unless row.hasChildren 'true'}}
+                aria-hidden='true'
+              ></span>
+              {{#let (this.iconOf row) as |NodeIcon|}}
+                {{#if NodeIcon}}
+                  <NodeIcon class='pretui-tree-icon' role='presentation' />
+                {{/if}}
+              {{/let}}
+              <span class='pretui-tree-label'>
+                {{#if (has-block 'label')}}
+                  {{yield row.node row to='label'}}
+                {{else}}
+                  {{row.node.label}}
+                {{/if}}
+              </span>
+              {{#if row.node.badge}}
+                <StatusChip @value={{row.node.badge}} />
+              {{/if}}
+              {{#if row.node.meta}}
+                <span class='pretui-tree-meta'>{{row.node.meta}}</span>
+              {{/if}}
+            </li>
+          {{/each}}
+        </ul>
+      {{else if (has-block 'empty')}}
+        {{yield to='empty'}}
+      {{else}}
+        <EmptyState
+          @title='Nothing to expand'
+          @message='This hierarchy has no nodes yet.'
+          @texture={{false}}
+        />
+      {{/if}}
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-tree-host {
+          min-width: 0;
+        }
+        .pretui-tree {
+          list-style: none;
+          margin: 0;
+          padding: var(--pretui-tree-pad, 4px);
+          display: grid;
+          gap: 1px;
+          font-size: var(--text-ui-md, 12.5px);
+          color: var(--foreground);
+        }
+        .pretui-tree-item {
+          position: relative;
+          display: flex;
+          align-items: center;
+          gap: 6px;
+          min-width: 0;
+          min-height: var(--pretui-tree-row-height, 26px);
+          padding-block: 0;
+          padding-inline: calc(
+              8px + var(--pretui-tree-indent, 14px) * (var(--_level, 1) - 1)
+            )
+            8px;
+          border-radius: var(--radius-chip, 6px);
+          cursor: default;
+          user-select: none;
+        }
+        .pretui-tree-host[data-density='compact'] .pretui-tree-item {
+          min-height: var(--pretui-tree-row-height, 22px);
+          font-size: var(--text-ui, 12px);
+        }
+        .pretui-tree-item:hover {
+          background: var(--hover, var(--boxel-100));
+        }
+        .pretui-tree-item[data-selected='true'] {
+          background: var(--pretui-selected, var(--boxel-100));
+          color: var(--pretui-primary-ink, var(--primary));
+          font-weight: 500;
+        }
+        /* Law 8 — the selection is legible in a still frame: tint plus a rail */
+        .pretui-tree-item[data-selected='true']::before {
+          content: '';
+          position: absolute;
+          left: 2px;
+          top: 3px;
+          bottom: 3px;
+          width: 2px;
+          border-radius: 1px;
+          background: var(--pretui-primary-ink, var(--primary));
+        }
+        .pretui-tree-item[aria-disabled='true'] {
+          opacity: 0.45;
+        }
+        .pretui-tree-item:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: -1px;
+        }
+        .pretui-tree-twisty {
+          width: 14px;
+          height: 14px;
+          flex: none;
+          display: inline-flex;
+          align-items: center;
+          justify-content: center;
+          color: var(--ink-3, var(--boxel-400));
+          transition: transform 140ms var(--pretui-ease-snap, ease);
+        }
+        /* the twisty is drawn, not typed — no glyph, no font dependency, and
+           it scales with the row */
+        .pretui-tree-twisty::before {
+          content: '';
+          width: 0;
+          height: 0;
+          border-left: 4px solid currentColor;
+          border-top: 3.5px solid transparent;
+          border-bottom: 3.5px solid transparent;
+        }
+        .pretui-tree-twisty[data-open='true'] {
+          transform: rotate(90deg);
+        }
+        .pretui-tree-twisty[data-leaf='true']::before {
+          border-left-color: transparent;
+        }
+        .pretui-tree-icon {
+          width: 14px;
+          height: 14px;
+          flex: none;
+          color: var(--muted-foreground);
+        }
+        .pretui-tree-label {
+          overflow: hidden;
+          text-overflow: ellipsis;
+          white-space: nowrap;
+          min-width: 0;
+        }
+        .pretui-tree-meta {
+          margin-left: auto;
+          padding-left: 8px;
+          font-size: var(--text-ui-sm, 11.5px);
+          color: var(--muted-foreground);
+          font-variant-numeric: tabular-nums;
+          white-space: nowrap;
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-tree-twisty {
+            transition: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/tree.md

@@ -0,0 +1,68 @@
+## What it is
+
+A hierarchical list you expand, collapse and navigate — a file explorer, a taxonomy, a nested outline. Reach for it when the nesting is the point and a node's position in the hierarchy carries meaning. If the levels are just visual grouping, **Accordion** or **FormSection** is lighter. If the hierarchy is a path you are _in_ rather than one you are browsing, **Breadcrumb**. If the data is tabular with a nesting column, that is a treegrid and this is not it.
+
+## The contract
+
+```
+@nodes: TreeNode[]   (recursive; children presence makes a node a branch)
+@label? ('Tree'), @indent?, @density? ('compact' 22px | 'comfortable' 26px)
+@expanded? / @defaultExpanded? / @onExpandedChange?(ids)
+@selected? / @defaultSelected? / @onSelect?(node)
+@typeahead? (default true)
+<:label as |node, row|>   <:empty>
+```
+
+Two hybrid controlled/uncontrolled pairs — expansion and selection are independent, so you can control one and let the component own the other.
+
+**The DOM is one flat `<ul role="tree">` with `aria-level`/`aria-posinset`/`aria-setsize` per item**, rather than a nested `<ul role="group">` per branch. Both forms are conformant; the flat one is what makes a single `{{#each}}` over a computed `rows` getter possible, and `aria-level` carries the depth the nesting would have carried. The practical payoff is that keyboard navigation is index arithmetic over a flat array rather than a tree walk.
+
+**Disabled nodes still take keyboard focus.** `aria-disabled` marks them unselectable, but they remain reachable — otherwise a disabled branch would make everything under it unreachable.
+
+**Type-ahead is single-character cycling, and that is a realm constraint made visible.** A multi-character type-ahead buffer needs a debounce timer, and realm components own no timers. So pressing `d` repeatedly cycles through nodes starting with `d` rather than accumulating "doc". Worth knowing before you file it as a bug.
+
+Deliberately dropped: multi-select (`aria-multiselectable`), and drag-to-reorder.
+
+## Prior art
+
+**Most kits ship a tree as nested `<div>`s with `onClick`** — no roles, no `aria-expanded`, no keyboard, and every node a tab stop. The shape here comes from **VS Code's explorer** and **MUI `SimpleTreeView`**; the semantics come from the APG directly.
+
+**Web Awesome `wa-tree`** is the closest conformant peer: `selection` (`single | multiple | leaf | leaf-multiple`), `role="tree"` with `tabindex=0`, APG-conformant Arrow/Home/End/Enter/Space handling, a `role="group"` children container, `aria-expanded` **removed for leaves**, and a `lazy` flag firing `wa-lazy-load`. **React Aria** is the outlier: its `useTree` is a thin wrapper over `useGridList` that overwrites the role to **`treegrid`** — a single-column treegrid, not `role="tree"`.
+
+Where Pretui matches Web Awesome and beats the field: it implements the pattern in full — roles, `aria-level`/`posinset`/`setsize`, roving tabindex, Up/Down/Left/Right/Home/End, and type-ahead. That is the whole claim of this territory's header comment, and it holds.
+
+Where it is behind Web Awesome: **no lazy loading** (a big tree renders entirely), **no multi-select**, and **single-character type-ahead** rather than a buffered one.
+
+## Accessibility
+
+Governing pattern: APG **Tree View**. This is one of the two or three best-implemented components in the kit.
+
+Present and correct: `role="tree"` with `aria-label`; `role="treeitem"` per row; `aria-level`, `aria-posinset`, `aria-setsize` (required when the full node set is not in the DOM, and correct to include always in a flat structure); `aria-expanded` on branches; `aria-selected` explicitly `'true'`/`'false'`; `aria-disabled` on disabled nodes; a roving tabindex so the tree is **one tab stop**; and the icon marked `aria-hidden` / `role="presentation"`.
+
+The keyboard contract matches the pattern: Right opens a closed node without moving focus, else moves to the first child; Left closes an open node, else moves to the parent; Up/Down move without opening or closing; Home/End jump to the first and last visible rows; Enter/Space select.
+
+Remaining gaps, small but real:
+
+- **`aria-expanded` must be absent on leaves, not `false`** — a leaf with `aria-expanded="false"` is announced as a collapsed parent. The component sets it only on rows with children, so a leaf carries no `aria-expanded` at all.
+- **`@label` defaults to the literal `'Tree'`.** Two trees on a page are both announced "Tree". The source calls this "required in spirit, defaulted so nothing is required in practice" — a reasonable Law 7 stance, and one that still produces bad output when ignored. Always pass it.
+- **Single-character type-ahead** (above) diverges from APG's "next item whose label _begins with_ the typed string". For trees with many similarly-prefixed nodes, cycling is materially worse than buffering.
+- **`*` to expand all siblings at the current level** is an optional APG key and is not implemented.
+- **No `aria-activedescendant` alternative** — roving tabindex only, which APG blesses equally.
+- **Selection changes are not announced** beyond `aria-selected` being re-read on focus.
+- Target size: a 22px compact row is below WCAG **2.5.8**'s 24×24 minimum for pointer users.
+
+## Theming
+
+`--pretui-tree-indent` (per-level indent, settable as a token or via `@indent`), the density presets (22/26px, fixed), plus `--foreground`, `--muted-foreground`, `--hover`, `--pretui-selected`, `--border`, `--text-ui-md`, and **StatusChip**/**Token** tokens if a node carries a badge or meta.
+
+`aria-disabled` is styled directly (`.pretui-tree-item[aria-disabled='true']`), which is a nice detail — the visual disabled state and the announced one cannot drift, because they are the same attribute.
+
+A theme must keep `--pretui-selected` distinct from `--hover`: a tree shows both simultaneously (the selected row, and whichever row the pointer is over), and if they collapse the user loses track of the selection while browsing.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+Browse-only tree. A tree _as a select value_ is **TreeSelect**. A
+single _path_ is **Cascader**. Accept `expanded` / `onExpandedChange`
+and `selected` / `onSelectionChange` names from Aria / Ant / Mantine.