components/tree/tree.ts

Functions

Imports

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

Source

1// The tree: nested items a person opens and closes, chooses, and (optionally) moves, after
2// the WAI-ARIA tree pattern. Delivered with no script it is nested lists with every level
3// shown and every link working; `enhance` adds the roles, the closed branches, one tab stop
4// with the arrow keys moving focus, selection, and moving by keyboard and by dragging. The
5// tree owns no storage: a move is a cancelable `cap:tree-move` event, and the host saves it.
6// No framework; the React wrapper uses the same pure functions.
7
8import { TYPEAHEAD_MS, type TypeaheadState, nextTypeahead } from "../listbox/listbox.ts";
9import { announcer, startPointerDrag } from "../sortable-list/sortable-list.ts";
10import { type TreeMove, type TreeNodeLike, cannotMoveText, dropMove, findNode, movedText, planMove, treeKey, visibleRows, zoneAt } from "./tree-model.ts";
11
12export { visibleRows, branchIds, treeKey, findNode, findPlace, isWithin, planMove, dropMove, zoneAt, applyMove, reverseMove, movedText, cannotMoveText } from "./tree-model.ts";
13export type { TreeNodeLike, VisibleRow, TreeKeyResult, KeyMods, MoveDir, TreePlace, TreeMove, DropZone } from "./tree-model.ts";
14
15// ---------------------------------------------------------------------------------------
16// The controller, over the HTML contract: `[data-cap="tree"]`, a `ul.cap-tree` of
17// `li.cap-tree-item[data-value]`, each holding its `.cap-tree-row` (a link, or a span) and,
18// for a branch, a `ul.cap-tree-group`.
19
20export type TreeSelection = "none" | "single" | "multi";
21
22export interface TreeSelectDetail {
23  id: string;
24  label: string;
25  selected: boolean;
26  values: string[];
27}
28
29export interface Tree {
30  readonly el: HTMLElement;
31  nodes(): TreeNodeLike[];
32  expanded(): string[];
33  setExpanded(id: string, open: boolean): void;
34  selected(): string[];
35  focus(id?: string): void;
36  // Makes a move, as the keyboard or a drop would: emits cap:tree-move, and unless that is
37  // cancelled, moves the item and says so. Returns whether it moved.
38  move(move: TreeMove): boolean;
39  refresh(): void;
40  detach(): void;
41}
42
43let counter = 0;
44const uid = (p: string) => `${p}-${++counter}`;
45
46interface Parts {
47  li: HTMLElement;
48  row: HTMLElement;
49  group: HTMLElement | null;
50}
51
52const partsOf = (li: HTMLElement): Parts => ({
53  li,
54  row: li.querySelector<HTMLElement>(":scope > .cap-tree-row")!,
55  group: li.querySelector<HTMLElement>(":scope > .cap-tree-group"),
56});
57const itemsIn = (ul: Element) => Array.from(ul.querySelectorAll<HTMLElement>(":scope > .cap-tree-item")).filter((li) => li.querySelector(":scope > .cap-tree-row"));
58const rowLabel = (row: HTMLElement) => (row.querySelector(".cap-tree-label")?.textContent ?? row.textContent ?? "").trim().replace(/\s+/g, " ");
59
60const TOGGLE = '<svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" focusable="false"><path d="M6 3.5 10.5 8 6 12.5"/></svg>';
61
62export function createTree(el: HTMLElement): Tree {
63  const selection: TreeSelection = (el.dataset.selection as TreeSelection | undefined) ?? "single";
64  const movable = el.hasAttribute("data-movable");
65  const { region, made } = announcer(el);
66  const say = (text: string) => {
67    region.textContent = "";
68    requestAnimationFrame(() => (region.textContent = text));
69  };
70
71  const parts = new Map<string, Parts>();
72  const open = new Set<string>();
73  const chosen = new Set<string>();
74  let current: string | null = null;
75
76  const read = (ul: Element): TreeNodeLike[] =>
77    itemsIn(ul).map((li) => {
78      const p = partsOf(li);
79      li.dataset.value ||= uid("cap-tree-item");
80      const id = li.dataset.value;
81      parts.set(id, p);
82      const node: TreeNodeLike = { id, label: rowLabel(p.row), disabled: p.row.getAttribute("aria-disabled") === "true" };
83      if (p.group || li.hasAttribute("data-branch")) node.children = p.group ? read(p.group) : [];
84      return node;
85    });
86  let model: TreeNodeLike[] = [];
87
88  // Writes the roles and states from the model, the open set and the chosen set.
89  const paint = () => {
90    parts.clear();
91    model = read(el);
92    el.setAttribute("role", "tree");
93    if (selection === "multi") el.setAttribute("aria-multiselectable", "true");
94    const walk = (list: readonly TreeNodeLike[], level: number) => {
95      list.forEach((n, i) => {
96        const p = parts.get(n.id)!;
97        p.li.setAttribute("role", "none");
98        const r = p.row;
99        r.setAttribute("role", "treeitem");
100        r.id ||= uid("cap-tree-row");
101        r.setAttribute("aria-level", String(level));
102        r.setAttribute("aria-posinset", String(i + 1));
103        r.setAttribute("aria-setsize", String(list.length));
104        r.setAttribute("draggable", "false");
105        if (selection !== "none" && !(r.getAttribute("aria-disabled") === "true")) r.setAttribute("aria-selected", String(chosen.has(n.id)));
106        if (n.children) {
107          const isOpen = open.has(n.id);
108          r.setAttribute("aria-expanded", String(isOpen));
109          if (!r.querySelector(":scope > .cap-tree-toggle")) {
110            const t = document.createElement("span");
111            t.className = "cap-tree-toggle";
112            t.setAttribute("aria-hidden", "true");
113            t.innerHTML = TOGGLE;
114            r.prepend(t);
115          }
116          if (p.group) {
117            p.group.id ||= uid("cap-tree-group");
118            p.group.setAttribute("role", "group");
119            p.group.hidden = !isOpen;
120            r.setAttribute("aria-owns", p.group.id);
121            walk(n.children, level + 1);
122          }
123        } else {
124          r.removeAttribute("aria-expanded");
125          r.removeAttribute("aria-owns");
126          r.querySelector(":scope > .cap-tree-toggle")?.remove();
127        }
128      });
129    };
130    walk(model, 1);
131    const rows = visibleRows(model, open);
132    if (!current || !rows.some((r) => r.id === current)) {
133      // The tab stop: the chosen row if one shows, otherwise the first.
134      current = rows.find((r) => chosen.has(r.id))?.id ?? rows[0]?.id ?? null;
135    }
136    for (const [id, p] of parts) p.row.tabIndex = id === current ? 0 : -1;
137  };
138
139  const focusRow = (id: string) => {
140    current = id;
141    for (const [k, p] of parts) p.row.tabIndex = k === id ? 0 : -1;
142    const r = parts.get(id)?.row;
143    r?.focus({ preventScroll: true });
144    r?.scrollIntoView({ block: "nearest" });
145  };
146
147  const setExpanded = (id: string, isOpen: boolean) => {
148    const node = findNode(model, id);
149    if (!node?.children || open.has(id) === isOpen) return;
150    if (isOpen) open.add(id);
151    else open.delete(id);
152    const p = parts.get(id)!;
153    p.row.setAttribute("aria-expanded", String(isOpen));
154    if (p.group) p.group.hidden = !isOpen;
155    el.dispatchEvent(new CustomEvent("cap:tree-toggle", { bubbles: true, detail: { id, expanded: isOpen } }));
156  };
157
158  const select = (id: string) => {
159    if (selection === "none") return;
160    const p = parts.get(id);
161    if (!p || p.row.getAttribute("aria-disabled") === "true") return;
162    if (selection === "single") chosen.clear();
163    const on = selection === "multi" ? !chosen.has(id) : true;
164    if (on) chosen.add(id);
165    else chosen.delete(id);
166    for (const [k, q] of parts) if (q.row.hasAttribute("aria-selected")) q.row.setAttribute("aria-selected", String(chosen.has(k)));
167    const detail: TreeSelectDetail = { id, label: rowLabel(p.row), selected: on, values: [...chosen] };
168    el.dispatchEvent(new CustomEvent("cap:tree-select", { bubbles: true, detail }));
169  };
170
171  const move = (m: TreeMove): boolean => {
172    if (!el.dispatchEvent(new CustomEvent("cap:tree-move", { bubbles: true, cancelable: true, detail: m }))) return false;
173    const li = parts.get(m.id)?.li;
174    if (!li) return false;
175    const hadFocus = li.contains(document.activeElement);
176    let ul: HTMLElement | null = el;
177    if (m.to.parent !== null) {
178      const p = parts.get(m.to.parent)!;
179      if (!p.group) {
180        p.group = document.createElement("ul");
181        p.group.className = "cap-tree-group";
182        p.li.append(p.group);
183      }
184      ul = p.group;
185      open.add(m.to.parent);
186    }
187    li.remove();
188    ul.insertBefore(li, itemsIn(ul)[m.to.index] ?? null);
189    paint();
190    say(movedText(model, m));
191    if (hadFocus) focusRow(m.id);
192    return true;
193  };
194
195  // ---- keys
196  let typed: TypeaheadState = { buffer: "", at: 0 };
197  const onKey = (e: KeyboardEvent) => {
198    const row = (e.target as Element | null)?.closest<HTMLElement>("[role='treeitem']");
199    if (!row || !el.contains(row) || e.defaultPrevented || e.isComposing) return;
200    const id = row.closest<HTMLElement>(".cap-tree-item")?.dataset.value ?? null;
201    const rows = visibleRows(model, open);
202    // Enter on a link is the link's own: the browser follows it, and the click selects.
203    if (e.key === "Enter" && row.matches("a[href]")) return;
204    // A space while letters are being typed is part of them ("02 f"), as in the listbox.
205    const typing = Date.now() - typed.at <= TYPEAHEAD_MS && typed.buffer !== "";
206    const r = e.key === " " && typing ? null : treeKey(rows, id, e.key, e, movable);
207    if (r) {
208      e.preventDefault();
209      if (r.expand) for (const x of r.expand) setExpanded(x, true);
210      if (r.collapse) setExpanded(r.collapse, false);
211      if (r.focus) focusRow(r.focus);
212      if (r.select) select(r.select);
213      if (r.move && id) {
214        const m = planMove(model, id, r.move);
215        if (m) move(m);
216        else say(cannotMoveText(rowLabel(row), r.move));
217      }
218      return;
219    }
220    if (e.key.length === 1 && (e.key !== " " || typing) && !e.altKey && !e.ctrlKey && !e.metaKey) {
221      const res = nextTypeahead(typed, e.key, Date.now(), rows.map((x) => x.label), rows.findIndex((x) => x.id === id));
222      typed = res.state;
223      const hit = rows[res.index];
224      if (hit) {
225        e.preventDefault();
226        focusRow(hit.id);
227      }
228    }
229  };
230
231  // ---- the pointer: the toggle opens and closes, the rest of the row chooses
232  const rowAt = (target: EventTarget | null) => {
233    const row = (target as Element | null)?.closest<HTMLElement>(".cap-tree-row");
234    return row && el.contains(row) ? row : null;
235  };
236  const idOfRow = (row: HTMLElement) => row.closest<HTMLElement>(".cap-tree-item")?.dataset.value ?? "";
237  const onClick = (e: MouseEvent) => {
238    const row = rowAt(e.target);
239    if (!row) return;
240    const id = idOfRow(row);
241    if ((e.target as Element).closest(".cap-tree-toggle")) {
242      e.preventDefault();
243      setExpanded(id, !open.has(id));
244      focusRow(id);
245      return;
246    }
247    focusRow(id);
248    select(id);
249  };
250
251  let dropOn: HTMLElement | null = null;
252  const clearDrop = () => {
253    dropOn?.removeAttribute("data-drop");
254    dropOn = null;
255  };
256  const onDown = (e: PointerEvent) => {
257    const row = rowAt(e.target);
258    if (!movable || !row || (e.target as Element).closest(".cap-tree-toggle") || row.getAttribute("aria-disabled") === "true") return;
259    const id = idOfRow(row);
260    let plan: TreeMove | null = null;
261    startPointerDrag(e, {
262      onStart() {
263        row.setAttribute("data-dragging", "");
264        el.setAttribute("data-sorting", "");
265      },
266      onMove(x, y) {
267        clearDrop();
268        plan = null;
269        const over = rowAt(document.elementFromPoint(x, y));
270        if (!over || over === row) return;
271        const target = idOfRow(over);
272        const box = over.getBoundingClientRect();
273        const zone = zoneAt(y, box.top, box.height, findNode(model, target)?.children !== undefined);
274        plan = dropMove(model, id, target, zone);
275        if (plan) {
276          dropOn = over;
277          over.setAttribute("data-drop", zone);
278        }
279      },
280      onDrop() {
281        clearDrop();
282        row.removeAttribute("data-dragging");
283        el.removeAttribute("data-sorting");
284        if (plan) {
285          move(plan);
286          focusRow(id);
287        }
288      },
289      onCancel() {
290        clearDrop();
291        row.removeAttribute("data-dragging");
292        el.removeAttribute("data-sorting");
293        say(`Put ${rowLabel(row)} back.`);
294      },
295    });
296  };
297
298  // ---- start: read the delivered markup's own state
299  model = read(el);
300  for (const [id, p] of parts) {
301    const node = findNode(model, id);
302    if (node?.children && !p.li.hasAttribute("data-collapsed")) open.add(id);
303    if (p.row.hasAttribute("data-selected") || p.row.getAttribute("aria-current") === "page") {
304      if (selection === "multi" || chosen.size === 0) chosen.add(id);
305    }
306  }
307  if (selection === "none") chosen.clear();
308  paint();
309
310  el.addEventListener("keydown", onKey);
311  el.addEventListener("click", onClick);
312  el.addEventListener("pointerdown", onDown);
313
314  return {
315    el,
316    nodes: () => model,
317    expanded: () => [...open],
318    setExpanded,
319    selected: () => [...chosen],
320    focus: (id) => {
321      const target = id ?? current;
322      if (target) focusRow(target);
323    },
324    move,
325    refresh: paint,
326    detach() {
327      el.removeEventListener("keydown", onKey);
328      el.removeEventListener("click", onClick);
329      el.removeEventListener("pointerdown", onDown);
330      if (made) region.remove();
331      delete el.dataset.capReady;
332    },
333  };
334}
335
336const trees = new WeakMap<HTMLElement, Tree>();
337
338// The controller `enhance` made for this element, if any.
339export function treeFor(el: Element | null): Tree | undefined {
340  return el instanceof HTMLElement ? trees.get(el) : undefined;
341}
342
343// Attaches to every `[data-cap="tree"]` under root not yet marked `data-cap-ready`.
344// Reads data-selection ("none", "single" by default, "multi") and data-movable. Returns a
345// function that detaches them all.
346export function enhance(root: ParentNode = document): () => void {
347  const undo: Array<() => void> = [];
348  for (const el of root.querySelectorAll<HTMLElement>("[data-cap='tree']:not([data-cap-ready])")) {
349    el.dataset.capReady = "";
350    const t = createTree(el);
351    trees.set(el, t);
352    undo.push(() => {
353      t.detach();
354      trees.delete(el);
355    });
356  }
357  return () => undo.forEach((f) => f());
358}