@yewdiel21/motion-kit 0.9.1 → 0.14.0

package/src/components/tree-view/engine.ts

@@ -0,0 +1,569 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { requestFrame } from '../../core/frame';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { fromJson } from '../../core/dates';
+import { checkStates, findNode, isBranch, searchTree, toggleCheck, walk, type CheckState, type TreeNode } from '../../core/tree';
+import { foldText, markText } from '../../core/mark';
+
+/*
+ * Tree view (WAI-ARIA tree): nodes that open and close, three-state
+ * checkboxes and a search. A branch opens by its height (.32 s, signature)
+ * while its children slide in out of a blur (25 ms apart) and its chevron
+ * turns (.3 s, swing); it closes the same way back. The selected row sits on a
+ * pill that glides to each new choice (.3 s, swing). A check draws itself and
+ * its box pops; a branch with some children checked shows a dash. The search
+ * marks the letters that match, opens the branches that hold them and hides
+ * the rest; clearing it puts back what was open. loadChildren() fills a branch
+ * the first time it opens (a spinner row meanwhile). Keyboard: ↑ ↓ move, → opens
+ * or enters, ← closes or goes up, Home, End, * opens the siblings, Enter
+ * selects, Space checks (or selects), and typing jumps to a label.
+ */
+
+export type { TreeNode } from '../../core/tree';
+
+export interface TreeViewOptions {
+  nodes?: TreeNode[];
+  /** Three-state checkboxes (default false). */
+  checkable?: boolean;
+  checked?: string[];
+  /** Open at the start: ids, or true for every branch. */
+  expanded?: string[] | boolean;
+  selected?: string | null;
+  /** A search field above the tree: true, or its placeholder. */
+  search?: boolean | string;
+  /** Accessible name (default 'Árbol'). */
+  label?: string;
+  /** Children of a branch with hasChildren, the first time it opens. */
+  loadChildren?: (node: TreeNode) => Promise<TreeNode[]> | TreeNode[];
+  /** Draw a label yourself (json-viewer, file-explorer); `query` is the search, for marking. */
+  renderLabel?: (node: TreeNode, element: HTMLElement, query: string) => void;
+  /** The text the search looks in (default: the label). */
+  searchText?: (node: TreeNode) => string;
+  onSelect?: (node: TreeNode) => void;
+  onCheck?: (checked: string[]) => void;
+  onExpand?: (node: TreeNode, expanded: boolean) => void;
+}
+
+export interface TreeViewInstance extends Instance {
+  expand(id: string, animate?: boolean): void;
+  collapse(id: string, animate?: boolean): void;
+  toggle(id: string): void;
+  expandAll(): void;
+  collapseAll(): void;
+  /** Open the branches above it and bring it into view. */
+  reveal(id: string): void;
+  select(id: string | null, notify?: boolean): void;
+  setChecked(ids: string[]): void;
+  filter(query: string): void;
+  setNodes(nodes: TreeNode[]): void;
+  focusItem(id: string): void;
+  readonly selected: string | null;
+  readonly checked: string[];
+  readonly expanded: string[];
+  /** The tree element (role="tree"). */
+  readonly element: HTMLElement;
+}
+
+const CHEVRON = '<svg aria-hidden="true" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><path d="M9 6l6 6-6 6"/></svg>';
+const CHECK = '<svg aria-hidden="true" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"><path data-mk-tree-tick d="M5 12.5l4.5 4.5L19 7.5" pathLength="1"/><path data-mk-tree-dash d="M6 12h12"/></svg>';
+let sequence = 0;
+
+const fold = foldText;
+
+// Kept here too for code that imported it from the tree.
+export { markText };
+
+export function createTreeView(root: HTMLElement | null, options: TreeViewOptions = {}): TreeViewInstance {
+  if (!root) return inert({ expand() {}, collapse() {}, toggle() {}, expandAll() {}, collapseAll() {}, reveal() {}, select() {}, setChecked() {}, filter() {}, setNodes() {}, focusItem() {}, selected: null, checked: [], expanded: [], element: null as unknown as HTMLElement });
+  registerMotion();
+  const scope = createScope();
+  const uid = `mk-tree-${++sequence}`;
+  // JSON text too (data-mk-nodes through autoInit).
+  let nodes: TreeNode[] = fromJson(options.nodes) ?? [];
+  const expanded = new Set<string>();
+  if (options.expanded === true) walk(nodes, (node) => isBranch(node) && expanded.add(node.id));
+  else for (const id of options.expanded || []) expanded.add(id);
+  /** Every given id checked with what lies under it; branches follow their children. */
+  const normalised = (ids: string[]) => ids.reduce((set, id) => toggleCheck(nodes, set, id, true), new Set<string>());
+  let checked = normalised(fromJson(options.checked) ?? []);
+  let selected: string | null = options.selected ?? null;
+  let focused: string | null = selected;
+  let query = '';
+  let beforeSearch: Set<string> | null = null;
+  const loading = new Set<string>();
+  const effects = new Set<gsap.core.Animation>();
+  const keep = (animation: gsap.core.Animation | null) => {
+    if (!animation) return;
+    effects.add(animation);
+    // Finished ones leave as new ones arrive: the animation's own onComplete stays untouched.
+    for (const effect of effects) if (effect.totalProgress() === 1) effects.delete(effect);
+  };
+
+  let searchInput: HTMLInputElement | null = null;
+  const status = document.createElement('span');
+  status.className = 'mk-sr-only';
+  status.setAttribute('role', 'status');
+  if (options.search) {
+    searchInput = document.createElement('input');
+    searchInput.type = 'search';
+    searchInput.dataset.mkTreeSearch = '';
+    searchInput.placeholder = typeof options.search === 'string' ? options.search : 'Buscar…';
+    searchInput.setAttribute('aria-label', 'Buscar en el árbol');
+    searchInput.setAttribute('aria-controls', uid);
+  }
+  const box = document.createElement('div');
+  box.dataset.mkTreeBox = '';
+  const pill = document.createElement('span');
+  pill.dataset.mkTreePill = '';
+  pill.setAttribute('aria-hidden', 'true');
+  const tree = document.createElement('ul');
+  tree.id = uid;
+  tree.dataset.mkTree = '';
+  tree.setAttribute('role', 'tree');
+  tree.setAttribute('aria-label', options.label ?? 'Árbol');
+  if (options.checkable) tree.setAttribute('aria-multiselectable', 'true');
+  box.append(pill, tree);
+  const empty = document.createElement('p');
+  empty.dataset.mkTreeEmpty = '';
+  empty.textContent = 'Sin coincidencias';
+  empty.hidden = true;
+  if (searchInput) root.append(searchInput);
+  root.append(box, empty, status);
+  scope.add(() => {
+    for (const effect of effects) effect.kill();
+    effects.clear();
+    gsap.killTweensOf(pill);
+    searchInput?.remove();
+    box.remove();
+    empty.remove();
+    status.remove();
+  });
+  scope.attr(root, 'data-mk-ready', '');
+
+  const itemOf = (id: string) => [...tree.querySelectorAll<HTMLElement>('[role="treeitem"]')].find((item) => item.dataset.id === id) ?? null;
+  const nodeOf = (id: string) => findNode(nodes, id)?.node ?? null;
+  /** Items a reader can reach now: not inside a closed branch, not hidden by the search. */
+  const visibleItems = () =>
+    [...tree.querySelectorAll<HTMLElement>('[role="treeitem"]')].filter((item) => !item.hidden && !item.closest('[role="group"][hidden], [role="treeitem"][hidden]'));
+
+  const paintChecks = (animate: boolean) => {
+    if (!options.checkable) return;
+    const states = checkStates(nodes, checked);
+    for (const item of tree.querySelectorAll<HTMLElement>('[role="treeitem"]')) {
+      const state = states.get(item.dataset.id!) ?? 'false';
+      const before = item.getAttribute('aria-checked') as CheckState | null;
+      item.setAttribute('aria-checked', state);
+      if (!animate || before === state || reduced()) continue;
+      const box = item.querySelector<HTMLElement>(':scope > [data-mk-tree-row] [data-mk-tree-check]');
+      if (!box) continue;
+      keep(gsap.fromTo(box, { scale: 0.8 }, { scale: 1, duration: 0.35, ease: EASE.click, clearProps: 'transform' }));
+      const path = box.querySelector<SVGPathElement>(state === 'true' ? '[data-mk-tree-tick]' : '[data-mk-tree-dash]');
+      if (path && state !== 'false') keep(gsap.fromTo(path, { strokeDasharray: state === 'true' ? 1 : 12, strokeDashoffset: state === 'true' ? 1 : 12 }, { strokeDashoffset: 0, duration: 0.3, ease: EASE.wipe, clearProps: 'strokeDasharray,strokeDashoffset' }));
+    }
+  };
+
+  const fillLabel = (node: TreeNode, label: HTMLElement) => {
+    label.replaceChildren();
+    if (options.renderLabel) options.renderLabel(node, label, query);
+    else label.append(markText(node.label, query));
+  };
+
+  const row = (node: TreeNode, depth: number, index: number, count: number): HTMLElement => {
+    const item = document.createElement('li');
+    item.dataset.id = node.id;
+    item.setAttribute('role', 'treeitem');
+    item.setAttribute('aria-level', String(depth + 1));
+    item.setAttribute('aria-setsize', String(count));
+    item.setAttribute('aria-posinset', String(index + 1));
+    item.tabIndex = -1;
+    if (node.disabled) item.setAttribute('aria-disabled', 'true');
+    const branch = isBranch(node);
+    if (branch) item.setAttribute('aria-expanded', String(expanded.has(node.id)));
+    if (!options.checkable && selected === node.id) item.setAttribute('aria-selected', 'true');
+    const line = document.createElement('div');
+    line.dataset.mkTreeRow = '';
+    line.style.setProperty('--mk-tree-depth', String(depth));
+    const chevron = document.createElement('span');
+    chevron.dataset.mkTreeChevron = '';
+    if (branch) chevron.innerHTML = CHEVRON;
+    line.append(chevron);
+    if (options.checkable) {
+      const check = document.createElement('span');
+      check.dataset.mkTreeCheck = '';
+      check.innerHTML = CHECK;
+      line.append(check);
+    }
+    if (node.icon) {
+      const icon = document.createElement('span');
+      icon.dataset.mkTreeIcon = '';
+      icon.setAttribute('aria-hidden', 'true');
+      icon.textContent = node.icon;
+      line.append(icon);
+    }
+    const label = document.createElement('span');
+    label.dataset.mkTreeLabel = '';
+    fillLabel(node, label);
+    line.append(label);
+    item.append(line);
+    if (branch) {
+      const group = document.createElement('ul');
+      group.setAttribute('role', 'group');
+      group.hidden = !expanded.has(node.id);
+      (node.children ?? []).forEach((child, i, all) => group.append(row(child, depth + 1, i, all.length)));
+      item.append(group);
+    }
+    return item;
+  };
+
+  /** The pill under the selected row (or under nothing). */
+  const placePill = (animate: boolean) => {
+    const item = selected ? itemOf(selected) : null;
+    const line = item && visibleItems().includes(item) ? item.querySelector<HTMLElement>(':scope > [data-mk-tree-row]') : null;
+    if (!line) {
+      gsap.killTweensOf(pill);
+      pill.style.opacity = '0';
+      return;
+    }
+    const base = box.getBoundingClientRect();
+    const rect = line.getBoundingClientRect();
+    const target = { y: rect.top - base.top + box.scrollTop, height: rect.height };
+    if (!animate || reduced() || pill.style.opacity !== '1') {
+      gsap.killTweensOf(pill);
+      gsap.set(pill, target);
+      pill.style.opacity = '1';
+      return;
+    }
+    keep(gsap.to(pill, { ...target, duration: 0.3, ease: EASE.swatch, overwrite: 'auto' }));
+  };
+
+  const roving = () => {
+    const items = visibleItems();
+    const target = (focused && items.find((item) => item.dataset.id === focused)) || (selected && items.find((item) => item.dataset.id === selected)) || items[0];
+    for (const item of tree.querySelectorAll<HTMLElement>('[role="treeitem"]')) item.tabIndex = item === target ? 0 : -1;
+  };
+
+  const render = () => {
+    tree.replaceChildren(...nodes.map((node, i) => row(node, 0, i, nodes.length)));
+    paintChecks(false);
+    applySearch(false);
+    roving();
+    placePill(false);
+  };
+
+  // ── Opening and closing ──────────────────────────────────────────────────
+  const animateGroup = (group: HTMLElement, open: boolean) => {
+    if (reduced()) {
+      group.hidden = !open;
+      return placePill(false);
+    }
+    gsap.killTweensOf(group);
+    if (open) {
+      group.hidden = false;
+      const height = group.scrollHeight;
+      keep(gsap.fromTo(group, { height: 0, opacity: 0.5, overflow: 'hidden' }, { height, opacity: 1, duration: 0.32, ease: EASE.signature, clearProps: 'height,opacity,overflow', onUpdate: () => placePill(false) }));
+      const rows = [...group.children].slice(0, 14);
+      keep(gsap.fromTo(rows, { opacity: 0, x: -6, filter: 'blur(4px)' }, { opacity: 1, x: 0, filter: 'blur(0px)', duration: 0.3, stagger: 0.025, ease: 'power2.out', clearProps: 'opacity,transform,filter' }));
+    } else {
+      keep(
+        gsap.to(group, {
+          height: 0,
+          opacity: 0,
+          overflow: 'hidden',
+          duration: 0.24,
+          ease: 'power2.in',
+          onUpdate: () => placePill(false),
+          onComplete: () => {
+            group.hidden = true;
+            gsap.set(group, { clearProps: 'height,opacity,overflow' });
+            placePill(false);
+          },
+        }),
+      );
+    }
+  };
+
+  const setOpen = async (id: string, open: boolean, animate = true) => {
+    const node = nodeOf(id);
+    const item = itemOf(id);
+    if (!node || !item || !isBranch(node) || expanded.has(id) === open) return;
+    if (open) expanded.add(id);
+    else expanded.delete(id);
+    item.setAttribute('aria-expanded', String(open));
+    const group = item.querySelector<HTMLElement>(':scope > [role="group"]')!;
+    // A branch whose children come later: a spinner row, then them.
+    if (open && node.hasChildren && !node.children?.length && options.loadChildren && !loading.has(id)) {
+      loading.add(id);
+      const spinner = document.createElement('li');
+      spinner.dataset.mkTreeLoading = '';
+      spinner.setAttribute('role', 'none');
+      spinner.textContent = 'Cargando…';
+      spinner.style.setProperty('--mk-tree-depth', String(Number(item.getAttribute('aria-level'))));
+      group.replaceChildren(spinner);
+      group.hidden = false;
+      item.setAttribute('aria-busy', 'true');
+      try {
+        node.children = await options.loadChildren(node);
+      } catch {
+        node.children = [];
+      }
+      loading.delete(id);
+      if (scope.disposed) return;
+      item.removeAttribute('aria-busy');
+      const depth = Number(item.getAttribute('aria-level'));
+      group.replaceChildren(...(node.children ?? []).map((child, i, all) => row(child, depth, i, all.length)));
+      paintChecks(false);
+      if (!node.children?.length) {
+        item.removeAttribute('aria-expanded');
+        group.remove();
+        return;
+      }
+      if (animate) animateGroup(group, true);
+    } else if (animate) animateGroup(group, open);
+    else {
+      group.hidden = !open;
+      placePill(false);
+    }
+    roving();
+    options.onExpand?.(node, open);
+    root.dispatchEvent(new CustomEvent('mk:expand', { bubbles: true, detail: { id, expanded: open } }));
+  };
+
+  // ── Selecting and checking ───────────────────────────────────────────────
+  const select = (id: string | null, notify: boolean) => {
+    if (id && (nodeOf(id)?.disabled || !itemOf(id))) return;
+    const changed = id !== selected;
+    selected = id;
+    if (!options.checkable) for (const item of tree.querySelectorAll<HTMLElement>('[role="treeitem"]')) {
+      if (item.dataset.id === id) item.setAttribute('aria-selected', 'true');
+      else item.removeAttribute('aria-selected');
+    }
+    if (id) focused = id;
+    roving();
+    placePill(true);
+    if (!changed || !notify || !id) return;
+    const node = nodeOf(id)!;
+    options.onSelect?.(node);
+    root.dispatchEvent(new CustomEvent('mk:select', { bubbles: true, detail: { id, node } }));
+  };
+
+  const check = (id: string) => {
+    if (!options.checkable || nodeOf(id)?.disabled) return;
+    checked = toggleCheck(nodes, checked, id);
+    paintChecks(true);
+    const list = [...checked];
+    const state = checkStates(nodes, checked).get(id);
+    status.textContent = `${nodeOf(id)?.label ?? ''} ${state === 'true' ? 'marcado' : 'desmarcado'}`;
+    options.onCheck?.(list);
+    root.dispatchEvent(new CustomEvent('mk:check', { bubbles: true, detail: { checked: list } }));
+  };
+
+  // ── Search ───────────────────────────────────────────────────────────────
+  const applySearch = (announce: boolean) => {
+    const result = searchTree(nodes, query, options.searchText);
+    if (result.active) {
+      beforeSearch ??= new Set(expanded);
+      for (const id of result.open) expanded.add(id);
+    } else if (beforeSearch) {
+      expanded.clear();
+      for (const id of beforeSearch) expanded.add(id);
+      beforeSearch = null;
+    }
+    for (const item of tree.querySelectorAll<HTMLElement>('[role="treeitem"]')) {
+      const id = item.dataset.id!;
+      item.hidden = result.active && !result.visible.has(id);
+      if (item.hasAttribute('aria-expanded')) {
+        const open = expanded.has(id);
+        item.setAttribute('aria-expanded', String(open));
+        const group = item.querySelector<HTMLElement>(':scope > [role="group"]');
+        if (group) group.hidden = !open;
+      }
+      const node = nodeOf(id);
+      const label = item.querySelector<HTMLElement>(':scope > [data-mk-tree-row] [data-mk-tree-label]');
+      if (node && label) fillLabel(node, label);
+    }
+    empty.hidden = !result.active || result.matches.size > 0;
+    if (announce) status.textContent = !result.active ? '' : result.matches.size ? `${result.matches.size} ${result.matches.size === 1 ? 'coincidencia' : 'coincidencias'}` : 'Sin coincidencias';
+    roving();
+    placePill(false);
+  };
+  if (searchInput) {
+    scope.on(searchInput, 'input', () => {
+      query = searchInput!.value;
+      applySearch(true);
+    });
+    scope.on(searchInput, 'keydown', (event) => {
+      if ((event as KeyboardEvent).key === 'ArrowDown') {
+        event.preventDefault();
+        visibleItems()[0]?.focus();
+      }
+    });
+  }
+
+  // ── Pointer and keyboard ─────────────────────────────────────────────────
+  scope.on(tree, 'click', (event) => {
+    const target = event.target as Element | null;
+    const item = target?.closest<HTMLElement>('[role="treeitem"]');
+    if (!item || !tree.contains(item) || item.getAttribute('aria-disabled') === 'true') return;
+    const id = item.dataset.id!;
+    focused = id;
+    if (target?.closest('[data-mk-tree-chevron]') && item.hasAttribute('aria-expanded')) {
+      void setOpen(id, item.getAttribute('aria-expanded') !== 'true');
+      item.focus();
+      return;
+    }
+    if (options.checkable && target?.closest('[data-mk-tree-check]')) check(id);
+    else if (options.checkable) check(id);
+    else select(id, true);
+    item.focus();
+  });
+  scope.on(tree, 'dblclick', (event) => {
+    const item = (event.target as Element | null)?.closest<HTMLElement>('[role="treeitem"]');
+    if (item?.hasAttribute('aria-expanded') && !(event.target as Element).closest('[data-mk-tree-chevron]')) void setOpen(item.dataset.id!, item.getAttribute('aria-expanded') !== 'true');
+  });
+  scope.on(tree, 'focusin', (event) => {
+    const item = (event.target as Element | null)?.closest<HTMLElement>('[role="treeitem"]');
+    if (!item) return;
+    focused = item.dataset.id!;
+    roving();
+  });
+  let typed = '';
+  let typedAt = 0;
+  scope.on(tree, 'keydown', (event) => {
+    const key = event as KeyboardEvent;
+    const item = (key.target as Element | null)?.closest<HTMLElement>('[role="treeitem"]');
+    if (!item || key.ctrlKey || key.metaKey || key.altKey) return;
+    const items = visibleItems();
+    const index = items.indexOf(item);
+    const id = item.dataset.id!;
+    const go = (target: HTMLElement | undefined) => {
+      if (!target) return;
+      key.preventDefault();
+      target.focus();
+      target.scrollIntoView?.({ block: 'nearest' });
+    };
+    switch (key.key) {
+      case 'ArrowDown':
+        return go(items[index + 1]);
+      case 'ArrowUp':
+        return go(items[index - 1]);
+      case 'Home':
+        return go(items[0]);
+      case 'End':
+        return go(items[items.length - 1]);
+      case 'ArrowRight':
+        key.preventDefault();
+        if (item.getAttribute('aria-expanded') === 'false') void setOpen(id, true);
+        else if (item.getAttribute('aria-expanded') === 'true') go(item.querySelector<HTMLElement>(':scope > [role="group"] > [role="treeitem"]:not([hidden])') ?? undefined);
+        return;
+      case 'ArrowLeft':
+        key.preventDefault();
+        if (item.getAttribute('aria-expanded') === 'true') void setOpen(id, false);
+        else go(item.parentElement?.closest<HTMLElement>('[role="treeitem"]') ?? undefined);
+        return;
+      case 'Enter':
+        key.preventDefault();
+        if (options.checkable) check(id);
+        else select(id, true);
+        return;
+      case ' ':
+        key.preventDefault();
+        if (options.checkable) check(id);
+        else select(id, true);
+        return;
+      case '*': {
+        key.preventDefault();
+        const siblings = [...(item.parentElement?.children ?? [])].filter((sibling) => sibling.getAttribute('aria-expanded') === 'false') as HTMLElement[];
+        for (const sibling of siblings) void setOpen(sibling.dataset.id!, true);
+        return;
+      }
+    }
+    // Typing jumps to the next label that starts with what was typed.
+    if (key.key.length === 1 && /\S/.test(key.key)) {
+      const now = Date.now();
+      typed = now - typedAt > 600 ? key.key : typed + key.key;
+      typedAt = now;
+      const needle = fold(typed);
+      const order = [...items.slice(index + (typed.length === 1 ? 1 : 0)), ...items.slice(0, index + (typed.length === 1 ? 1 : 0))];
+      const match = order.find((candidate) => fold(nodeOf(candidate.dataset.id!)?.label ?? '').startsWith(needle));
+      if (match) go(match);
+    }
+  });
+
+  if (typeof ResizeObserver === 'function') {
+    let pending: (() => void) | null = null;
+    scope.observe(
+      new ResizeObserver(() => {
+        if (pending) return;
+        pending = requestFrame(() => {
+          pending = null;
+          placePill(false);
+        });
+      }),
+    ).observe(box);
+    scope.add(() => pending?.());
+  }
+
+  render();
+
+  return {
+    expand: (id, animate = true) => void setOpen(id, true, animate),
+    collapse: (id, animate = true) => void setOpen(id, false, animate),
+    toggle: (id) => void setOpen(id, !expanded.has(id)),
+    expandAll() {
+      walk(nodes, (node) => {
+        if (node.children?.length) expanded.add(node.id);
+      });
+      render();
+    },
+    collapseAll() {
+      expanded.clear();
+      render();
+    },
+    reveal(id) {
+      const found = findNode(nodes, id);
+      if (!found) return;
+      for (const ancestor of found.path.slice(0, -1)) expanded.add(ancestor.id);
+      for (const ancestor of found.path.slice(0, -1)) {
+        const item = itemOf(ancestor.id);
+        if (!item) continue;
+        item.setAttribute('aria-expanded', 'true');
+        const group = item.querySelector<HTMLElement>(':scope > [role="group"]');
+        if (group) group.hidden = false;
+      }
+      roving();
+      placePill(false);
+      itemOf(id)?.scrollIntoView?.({ block: 'nearest' });
+    },
+    select: (id, notify = false) => select(id, notify),
+    setChecked(ids) {
+      checked = normalised(ids);
+      paintChecks(false);
+    },
+    filter(next) {
+      query = next;
+      if (searchInput) searchInput.value = next;
+      applySearch(true);
+    },
+    setNodes(next) {
+      if (scope.disposed) return;
+      nodes = next;
+      render();
+    },
+    focusItem(id) {
+      itemOf(id)?.focus();
+    },
+    get selected() {
+      return selected;
+    },
+    get checked() {
+      return [...checked];
+    },
+    get expanded() {
+      return [...expanded];
+    },
+    element: tree,
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/tree-view/react.tsx

@@ -0,0 +1,78 @@
+'use client';
+import { forwardRef, useImperativeHandle, useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createTreeView, type TreeNode, type TreeViewInstance, type TreeViewOptions } from './engine';
+
+export interface TreeViewProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect' | 'children'>, Omit<TreeViewOptions, 'nodes'> {
+  nodes: TreeNode[];
+}
+
+export type TreeViewHandle = Pick<TreeViewInstance, 'expand' | 'collapse' | 'expandAll' | 'collapseAll' | 'reveal' | 'filter'>;
+
+/** <TreeView nodes={tree} checkable checked={ids} onCheck={setIds} search />. */
+export const TreeView = forwardRef<TreeViewHandle, TreeViewProps>(function TreeView(
+  { nodes, checkable, checked, expanded, selected, search, label, loadChildren, renderLabel, searchText, onSelect, onCheck, onExpand, className, ...props },
+  handle,
+) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<TreeViewInstance | null>(null);
+  const select = useLatest(onSelect);
+  const check = useLatest(onCheck);
+  const expand = useLatest(onExpand);
+  const load = useLatest(loadChildren);
+  const draw = useLatest(renderLabel);
+  const text = useLatest(searchText);
+  useImperativeHandle(
+    handle,
+    () => ({
+      expand: (id, animate) => instance.current?.expand(id, animate),
+      collapse: (id, animate) => instance.current?.collapse(id, animate),
+      expandAll: () => instance.current?.expandAll(),
+      collapseAll: () => instance.current?.collapseAll(),
+      reveal: (id) => instance.current?.reveal(id),
+      filter: (query) => instance.current?.filter(query),
+    }),
+    [],
+  );
+  const nodesKey = JSON.stringify(nodes);
+  useIsomorphicLayoutEffect(() => {
+    const created = createTreeView(ref.current, {
+      nodes: JSON.parse(nodesKey) as TreeNode[],
+      checkable,
+      checked,
+      expanded,
+      selected,
+      search,
+      label,
+      loadChildren: loadChildren ? (node) => load.current?.(node) ?? [] : undefined,
+      renderLabel: renderLabel ? (node, element, query) => draw.current?.(node, element, query) : undefined,
+      searchText: searchText ? (node) => text.current?.(node) ?? node.label : undefined,
+      onSelect: (node) => select.current?.(node),
+      onCheck: (ids) => check.current?.(ids),
+      onExpand: (node, open) => expand.current?.(node, open),
+    });
+    instance.current = created;
+    return () => {
+      created.destroy();
+      instance.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [checkable, String(search), label, Boolean(loadChildren), Boolean(renderLabel), Boolean(searchText)]);
+  const first = useRef(true);
+  useIsomorphicLayoutEffect(() => {
+    if (first.current) {
+      first.current = false;
+      return;
+    }
+    instance.current?.setNodes(JSON.parse(nodesKey) as TreeNode[]);
+  }, [nodesKey]);
+  const checkedKey = JSON.stringify(checked ?? null);
+  useIsomorphicLayoutEffect(() => {
+    if (checked && instance.current && JSON.stringify([...instance.current.checked].sort()) !== JSON.stringify([...checked].sort())) instance.current.setChecked(checked);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [checkedKey]);
+  useIsomorphicLayoutEffect(() => {
+    if (selected !== undefined && instance.current && instance.current.selected !== selected) instance.current.select(selected);
+  }, [selected]);
+  return <div {...props} ref={ref} className={['mk-tree-view', className].filter(Boolean).join(' ')} />;
+});