components/tree/tree.react.tsx

Functions

Imports

It imports components/listbox/listbox.ts, components/sortable-list/sortable-list.ts, components/tree/tree.ts. Imported by components/tree/examples.tsx.

Source

1import { useId, useLayoutEffect, useMemo, useRef, useState, type KeyboardEvent, type MouseEvent, type PointerEvent, type ReactNode } from "react";
2import { nextTypeahead, TYPEAHEAD_MS, type TypeaheadState } from "../listbox/listbox.ts";
3import { startPointerDrag } from "../sortable-list/sortable-list.ts";
4import { cannotMoveText, dropMove, findNode, movedText, applyMove, planMove, treeKey, visibleRows, zoneAt, type DropZone, type TreeMove, type TreeSelection } from "./tree.ts";
5
6export { applyMove, branchIds, dropMove, findNode, findPlace, movedText, planMove, reverseMove, treeKey, visibleRows } from "./tree.ts";
7export type { DropZone, MoveDir, TreeMove, TreePlace, TreeSelection, VisibleRow } from "./tree.ts";
8
9// The tree's HTML contract, rendered from props, with the roles and states the behaviour
10// module writes on the delivered markup. Which branches are open and which rows are chosen
11// can be the caller's (`expanded`, `selected`) or the tree's own (`defaultExpanded`,
12// `defaultSelected`). The nodes are always the caller's: a move calls `onMove`, and the
13// caller saves the new tree (`applyMove` makes it). Nothing here sets a `style` prop.
14
15export interface TreeNode {
16  id: string;
17  label: string;
18  // Makes the row a link.
19  href?: string;
20  // Beside the label, read as part of the row's name: a status, a word count. No controls.
21  meta?: ReactNode;
22  icon?: ReactNode;
23  disabled?: boolean;
24  // A branch, even when empty.
25  children?: TreeNode[];
26}
27
28export interface TreeProps {
29  nodes: TreeNode[];
30  "aria-label"?: string;
31  "aria-labelledby"?: string;
32  selection?: TreeSelection;
33  selected?: string[];
34  defaultSelected?: string[];
35  onSelectedChange?: (ids: string[], node: TreeNode) => void;
36  expanded?: string[];
37  defaultExpanded?: string[];
38  onExpandedChange?: (ids: string[]) => void;
39  // Turns on moving, by Alt with an arrow and by dragging a row. The caller saves the move.
40  onMove?: (move: TreeMove, next: TreeNode[]) => void;
41  // Refuses a move before it is offered (a scene may not sit at the top level, say).
42  canMove?: (move: TreeMove) => boolean;
43  // Draws its own border and surface, for a tree on its own.
44  variant?: "surface";
45  className?: string;
46}
47
48const Chevron = () => (
49  <svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round" focusable="false">
50    <path d="M6 3.5 10.5 8 6 12.5" />
51  </svg>
52);
53
54function useControllable<T>(value: T | undefined, initial: T, onChange?: (v: T) => void): [T, (v: T) => void] {
55  const [own, setOwn] = useState(initial);
56  const v = value ?? own;
57  return [
58    v,
59    (next: T) => {
60      if (value === undefined) setOwn(next);
61      onChange?.(next);
62    },
63  ];
64}
65
66export function Tree({ nodes, selection = "single", selected, defaultSelected = [], onSelectedChange, expanded, defaultExpanded = [], onExpandedChange, onMove, canMove, variant, className, ...name }: TreeProps) {
67  const [open, setOpen] = useControllable(expanded, defaultExpanded, onExpandedChange);
68  const [chosen, setChosenRaw] = useState(defaultSelected);
69  const picked = selected ?? chosen;
70  const openSet = useMemo(() => new Set(open), [open]);
71  const rows = useMemo(() => visibleRows(nodes, openSet), [nodes, openSet]);
72  const [current, setCurrent] = useState<string | null>(null);
73  const [said, setSaid] = useState("");
74  const [drop, setDrop] = useState<{ id: string; zone: DropZone } | null>(null);
75  const [dragging, setDragging] = useState<string | null>(null);
76  const rowEls = useRef(new Map<string, HTMLElement>());
77  const wantFocus = useRef<string | null>(null);
78  const typed = useRef<TypeaheadState>({ buffer: "", at: 0 });
79  const prefix = useId();
80  const movable = !!onMove;
81
82  // The tab stop: the focused row, else the chosen one that shows, else the first.
83  const stop = rows.some((r) => r.id === current) ? current : (rows.find((r) => picked.includes(r.id))?.id ?? rows[0]?.id ?? null);
84
85  useLayoutEffect(() => {
86    if (!wantFocus.current) return;
87    const el = rowEls.current.get(wantFocus.current);
88    wantFocus.current = null;
89    el?.focus({ preventScroll: true });
90    el?.scrollIntoView({ block: "nearest" });
91  });
92
93  const focusRow = (id: string) => {
94    setCurrent(id);
95    wantFocus.current = id;
96  };
97  const say = (text: string) => setSaid((prev) => (prev === text ? `${text} ` : text));
98  const toggle = (id: string, on: boolean) => {
99    if (openSet.has(id) === on) return;
100    setOpen(on ? [...open, id] : open.filter((x) => x !== id));
101  };
102  const choose = (node: TreeNode) => {
103    if (selection === "none" || node.disabled) return;
104    const next = selection === "single" ? [node.id] : picked.includes(node.id) ? picked.filter((x) => x !== node.id) : [...picked, node.id];
105    if (selected === undefined) setChosenRaw(next);
106    onSelectedChange?.(next, node);
107  };
108  const doMove = (m: TreeMove | null, dir?: Parameters<typeof cannotMoveText>[1]) => {
109    if (!onMove) return;
110    if (!m || (canMove && !canMove(m))) {
111      const node = m ? findNode(nodes, m.id) : current ? findNode(nodes, current) : undefined;
112      if (node && dir) say(cannotMoveText(node.label, dir));
113      return;
114    }
115    const next = applyMove(nodes, m);
116    if (m.to.parent !== null && !openSet.has(m.to.parent)) setOpen([...open, m.to.parent]);
117    say(movedText(next, m));
118    focusRow(m.id);
119    onMove(m, next);
120  };
121
122  const onKeyDown = (e: KeyboardEvent<HTMLUListElement>) => {
123    const id = (e.target as HTMLElement).closest<HTMLElement>("[data-cap-id]")?.dataset.capId ?? null;
124    if (!id || e.nativeEvent.isComposing) return;
125    const row = e.target as HTMLElement;
126    if (e.key === "Enter" && row.matches("a[href]")) return;
127    const typing = Date.now() - typed.current.at <= TYPEAHEAD_MS && typed.current.buffer !== "";
128    const r = e.key === " " && typing ? null : treeKey(rows, id, e.key, e, movable);
129    if (r) {
130      e.preventDefault();
131      if (r.expand?.length) setOpen([...open, ...r.expand.filter((x) => !openSet.has(x))]);
132      if (r.collapse) toggle(r.collapse, false);
133      if (r.focus) focusRow(r.focus);
134      if (r.select) {
135        const node = findNode(nodes, r.select);
136        if (node) choose(node);
137      }
138      if (r.move) doMove(planMove(nodes, id, r.move), r.move);
139      return;
140    }
141    if (e.key.length === 1 && (e.key !== " " || typing) && !e.altKey && !e.ctrlKey && !e.metaKey) {
142      const res = nextTypeahead(typed.current, e.key, Date.now(), rows.map((x) => x.label), rows.findIndex((x) => x.id === id));
143      typed.current = res.state;
144      const hit = rows[res.index];
145      if (hit) {
146        e.preventDefault();
147        focusRow(hit.id);
148      }
149    }
150  };
151
152  const onRowClick = (e: MouseEvent, node: TreeNode) => {
153    if ((e.target as Element).closest(".cap-tree-toggle")) {
154      e.preventDefault();
155      toggle(node.id, !openSet.has(node.id));
156      focusRow(node.id);
157      return;
158    }
159    setCurrent(node.id);
160    choose(node);
161  };
162
163  const onPointerDown = (e: PointerEvent, node: TreeNode) => {
164    if (!movable || node.disabled || (e.target as Element).closest(".cap-tree-toggle")) return;
165    let plan: TreeMove | null = null;
166    startPointerDrag(e.nativeEvent, {
167      onStart: () => setDragging(node.id),
168      onMove(x, y) {
169        plan = null;
170        const over = document.elementFromPoint(x, y)?.closest<HTMLElement>("[data-cap-id]");
171        const target = over?.dataset.capId;
172        if (!over || !target || target === node.id || !rowEls.current.has(target)) return setDrop(null);
173        const box = over.getBoundingClientRect();
174        const zone = zoneAt(y, box.top, box.height, findNode(nodes, target)?.children !== undefined);
175        const m = dropMove(nodes, node.id, target, zone);
176        plan = m && (!canMove || canMove(m)) ? m : null;
177        setDrop(plan ? { id: target, zone } : null);
178      },
179      onDrop() {
180        setDrop(null);
181        setDragging(null);
182        if (plan) doMove(plan);
183      },
184      onCancel() {
185        setDrop(null);
186        setDragging(null);
187        say(`Put ${node.label} back.`);
188      },
189    });
190  };
191
192  const render = (list: TreeNode[], level: number): ReactNode =>
193    list.map((node, i) => {
194      const branch = node.children !== undefined;
195      const isOpen = branch && openSet.has(node.id);
196      const groupId = `${prefix}-g-${node.id}`;
197      const Row = node.href ? "a" : "span";
198      return (
199        <li key={node.id} className="cap-tree-item" role="none" data-value={node.id}>
200          <Row
201            ref={(el: HTMLElement | null) => {
202              if (el) rowEls.current.set(node.id, el);
203              else rowEls.current.delete(node.id);
204            }}
205            className="cap-tree-row"
206            role="treeitem"
207            href={node.href}
208            draggable={false}
209            tabIndex={node.id === stop ? 0 : -1}
210            aria-level={level}
211            aria-posinset={i + 1}
212            aria-setsize={list.length}
213            aria-expanded={branch ? isOpen : undefined}
214            aria-owns={branch && node.children!.length > 0 ? groupId : undefined}
215            aria-selected={selection === "none" || node.disabled ? undefined : picked.includes(node.id)}
216            aria-disabled={node.disabled ? true : undefined}
217            data-cap-id={node.id}
218            data-drop={drop?.id === node.id ? drop.zone : undefined}
219            data-dragging={dragging === node.id ? "" : undefined}
220            onClick={(e: MouseEvent) => onRowClick(e, node)}
221            onFocus={() => setCurrent(node.id)}
222            onPointerDown={(e: PointerEvent) => onPointerDown(e, node)}
223          >
224            {branch ? (
225              <span className="cap-tree-toggle" aria-hidden="true">
226                <Chevron />
227              </span>
228            ) : null}
229            {node.icon != null ? <span className="cap-tree-icon">{node.icon}</span> : null}
230            <span className="cap-tree-label">{node.label}</span>
231            {node.meta != null ? <span className="cap-tree-meta">{node.meta}</span> : null}
232          </Row>
233          {branch && node.children!.length > 0 ? (
234            <ul className="cap-tree-group" role="group" id={groupId} hidden={!isOpen}>
235              {render(node.children!, level + 1)}
236            </ul>
237          ) : null}
238        </li>
239      );
240    });
241
242  return (
243    <>
244      <ul
245        {...name}
246        className={className ? `cap-tree ${className}` : "cap-tree"}
247        role="tree"
248        aria-multiselectable={selection === "multi" ? true : undefined}
249        data-variant={variant}
250        data-movable={movable ? "" : undefined}
251        data-sorting={dragging ? "" : undefined}
252        data-cap-ready=""
253        onKeyDown={onKeyDown}
254      >
255        {render(nodes, 1)}
256      </ul>
257      <div className="cap-sr-only" role="status" aria-atomic="true" data-cap-part="announce">
258        {said}
259      </div>
260    </>
261  );
262}