@yewdiel21/motion-kit 0.10.0 → 0.15.0

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

@@ -0,0 +1,743 @@
+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.
+ * Like the file explorer: with `icons`, branches are folders whose lid opens
+ * with them and leaves are pages; nodes that arrive (setNodes, a move) come in
+ * out of a blur; with `draggable`, a dragged row lifts a card that follows the
+ * pointer and tilts with its speed, the folder under it opens its lid (and the
+ * branch after a moment), and dropping flies the card into it.
+ */
+
+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;
+  /** Folder and page icons (default false); a node's own `icon` still wins. */
+  icons?: boolean;
+  /** Rows can be dragged into another branch (default false). */
+  draggable?: boolean;
+  /** A node was dropped into a branch (the tree has moved it). */
+  onMove?: (node: TreeNode, into: TreeNode) => 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 FOLDER =
+  '<svg aria-hidden="true" viewBox="0 0 48 40"><path data-mk-tree-folder-back d="M2 6a4 4 0 0 1 4-4h11.6a4 4 0 0 1 2.9 1.2L23.4 6H42a4 4 0 0 1 4 4v24a4 4 0 0 1-4 4H6a4 4 0 0 1-4-4z"/><path data-mk-tree-folder-front d="M2 14a4 4 0 0 1 4-4h36a4 4 0 0 1 4 4v20a4 4 0 0 1-4 4H6a4 4 0 0 1-4-4z"/></svg>';
+const PAGE =
+  '<svg aria-hidden="true" viewBox="0 0 40 48"><path data-mk-tree-sheet d="M7 2h18.5L37 13.5V42a4 4 0 0 1-4 4H7a4 4 0 0 1-4-4V6a4 4 0 0 1 4-4z"/><path data-mk-tree-fold d="M25.5 2v8.5a3 3 0 0 0 3 3H37z"/></svg>';
+
+/** `nodes` with the node `id` moved to the end of `into`'s children (a new tree: the given one is not changed). */
+export function moveTreeNode(nodes: TreeNode[], id: string, into: string): TreeNode[] {
+  let taken: TreeNode | null = null;
+  const without = (list: TreeNode[]): TreeNode[] =>
+    list
+      .filter((node) => {
+        if (node.id !== id) return true;
+        taken = node;
+        return false;
+      })
+      .map((node) => (node.children ? { ...node, children: without(node.children) } : node));
+  const rest = without(nodes);
+  const moved = taken as TreeNode | null;
+  if (!moved) return nodes;
+  const put = (list: TreeNode[]): TreeNode[] =>
+    list.map((node) => (node.id === into ? { ...node, children: [...(node.children ?? []), moved] } : node.children ? { ...node, children: put(node.children) } : node));
+  return put(rest);
+}
+
+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);
+    } else if (options.icons) {
+      const icon = document.createElement('span');
+      if (branch) icon.dataset.mkTreeFolder = '';
+      else icon.dataset.mkTreePage = '';
+      icon.innerHTML = branch ? FOLDER : PAGE;
+      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;
+  };
+
+  let known: Set<string> | null = null;
+  const allIds = (list: TreeNode[], into = new Set<string>()) => {
+    for (const node of list) {
+      into.add(node.id);
+      if (node.children) allIds(node.children, into);
+    }
+    return into;
+  };
+  /** Rows of nodes that just arrived come in out of a blur (not on the first drawing). */
+  const welcome = () => {
+    const now = allIds(nodes);
+    const fresh = known ? [...now].filter((id) => !known!.has(id)) : [];
+    known = now;
+    if (reduced() || !fresh.length) return;
+    const rows = fresh.map((id) => itemOf(id)?.querySelector<HTMLElement>(':scope > [data-mk-tree-row]')).filter((line): line is HTMLElement => !!line && visibleItems().includes(line.parentElement!));
+    if (rows.length) keep(gsap.fromTo(rows, { opacity: 0, x: -8, filter: 'blur(6px)' }, { opacity: 1, x: 0, filter: 'blur(0px)', duration: 0.35, stagger: 0.03, ease: 'power2.out', clearProps: 'opacity,transform,filter' }));
+  };
+  const render = () => {
+    tree.replaceChildren(...nodes.map((node, i) => row(node, 0, i, nodes.length)));
+    paintChecks(false);
+    applySearch(false);
+    roving();
+    placePill(false);
+    welcome();
+  };
+
+  // ── 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();
+      }
+    });
+  }
+
+  // ── Dragging into another branch ─────────────────────────────────────────
+  if (options.draggable) {
+    let drag: { id: string; x: number; y: number; pointer: number; card: HTMLElement | null; over: HTMLElement | null; lastX: number; lastT: number } | null = null;
+    let opening: ReturnType<typeof setTimeout> | undefined;
+    const clearOver = () => {
+      clearTimeout(opening);
+      drag?.over?.removeAttribute('data-mk-tree-over');
+      if (drag) drag.over = null;
+    };
+    /** The branch a node may go into under the pointer (a leaf counts as its branch), or null. */
+    const branchAt = (x: number, y: number) => {
+      const under = document.elementFromPoint(x, y)?.closest<HTMLElement>('[role="treeitem"]');
+      if (!under || !tree.contains(under) || !drag) return null;
+      const node = nodeOf(under.dataset.id!);
+      const candidate = node && isBranch(node) ? under : under.parentElement?.closest<HTMLElement>('[role="treeitem"]') ?? null;
+      if (!candidate) return null;
+      const path = findNode(nodes, candidate.dataset.id!)?.path.map((each) => each.id) ?? [];
+      // Not into itself, one of its own branches, or where it already is.
+      const parent = findNode(nodes, drag.id)?.path.at(-2)?.id;
+      if (path.includes(drag.id) || candidate.dataset.id === parent) return null;
+      return candidate;
+    };
+    const lift = (id: string, x: number, y: number) => {
+      const node = nodeOf(id)!;
+      const card = document.createElement('div');
+      card.dataset.mkTreeDrag = '';
+      card.setAttribute('aria-hidden', 'true');
+      if (options.icons) {
+        const icon = document.createElement('span');
+        if (isBranch(node)) icon.dataset.mkTreeFolder = '';
+        else icon.dataset.mkTreePage = '';
+        icon.innerHTML = isBranch(node) ? FOLDER : PAGE;
+        card.append(icon);
+      }
+      const text = document.createElement('span');
+      text.textContent = node.label;
+      card.append(text);
+      Object.assign(card.style, { left: '0px', top: '0px' });
+      root.append(card);
+      gsap.set(card, { x: x + 14, y: y + 10 });
+      if (!reduced()) keep(gsap.fromTo(card, { scale: 0.85, opacity: 0 }, { scale: 1.04, opacity: 1, duration: 0.3, ease: EASE.pop }));
+      itemOf(id)?.setAttribute('data-mk-tree-dragging', '');
+      return card;
+    };
+    const end = (drop: boolean) => {
+      if (!drag) return;
+      const { id, card, over } = drag;
+      clearOver();
+      drag = null;
+      itemOf(id)?.removeAttribute('data-mk-tree-dragging');
+      if (!card) return;
+      const into = drop && over ? over.dataset.id! : null;
+      const fly = (to: HTMLElement | null) => {
+        const box = to?.querySelector<HTMLElement>(':scope > [data-mk-tree-row]')?.getBoundingClientRect();
+        if (reduced() || !box || !box.width) return card.remove();
+        keep(gsap.to(card, { x: box.left + 24, y: box.top + box.height / 2 - 14, scale: 0.4, opacity: 0, duration: 0.32, ease: 'power2.in', onComplete: () => card.remove() }));
+      };
+      if (!into) return fly(itemOf(id));
+      fly(over);
+      const node = nodeOf(id)!;
+      nodes = moveTreeNode(nodes, id, into);
+      expanded.add(into);
+      render();
+      const target = nodeOf(into)!;
+      options.onMove?.(nodeOf(id)!, target);
+      root.dispatchEvent(new CustomEvent('mk:move', { bubbles: true, detail: { node, into: target } }));
+    };
+    scope.on(tree, 'pointerdown', (event) => {
+      const down = event as PointerEvent;
+      const target = down.target as Element;
+      const line = target.closest<HTMLElement>('[data-mk-tree-row]');
+      const item = line?.parentElement;
+      if (!line || !item || down.button !== 0 || target.closest('[data-mk-tree-chevron], [data-mk-tree-check]') || item.getAttribute('aria-disabled') === 'true') return;
+      drag = { id: item.dataset.id!, x: down.clientX, y: down.clientY, pointer: down.pointerId, card: null, over: null, lastX: down.clientX, lastT: performance.now() };
+    });
+    scope.on(window, 'pointermove', (event) => {
+      const move = event as PointerEvent;
+      if (!drag || move.pointerId !== drag.pointer) return;
+      if (!drag.card) {
+        if (Math.hypot(move.clientX - drag.x, move.clientY - drag.y) < 6) return;
+        drag.card = lift(drag.id, move.clientX, move.clientY);
+      }
+      // The card follows and leans with the pointer's speed.
+      const now = performance.now();
+      const speed = (move.clientX - drag.lastX) / Math.max(1, now - drag.lastT);
+      drag.lastX = move.clientX;
+      drag.lastT = now;
+      gsap.set(drag.card, { x: move.clientX + 14, y: move.clientY + 10 });
+      if (!reduced()) keep(gsap.to(drag.card, { rotation: Math.max(-10, Math.min(10, speed * 12)), duration: 0.25, ease: 'power2.out' }));
+      const over = branchAt(move.clientX, move.clientY);
+      if (over === drag.over) return;
+      clearOver();
+      if (!over) return;
+      drag.over = over;
+      over.setAttribute('data-mk-tree-over', '');
+      // A closed branch opens after a moment under the card.
+      if (over.getAttribute('aria-expanded') === 'false') opening = setTimeout(() => void setOpen(over.dataset.id!, true), 600);
+    });
+    scope.on(window, 'pointerup', (event) => {
+      if (drag && (event as PointerEvent).pointerId === drag.pointer) end(true);
+    });
+    scope.on(window, 'pointercancel', () => end(false));
+    scope.on(document, 'keydown', (event) => {
+      if ((event as KeyboardEvent).key === 'Escape' && drag?.card) end(false);
+    });
+    // A drag is not a click: the row under the pointer keeps its selection.
+    scope.on(tree, 'click', (event) => {
+      if (drag?.card) event.stopImmediatePropagation();
+    }, true);
+    scope.add(() => {
+      clearTimeout(opening);
+      drag?.card?.remove();
+    });
+  }
+
+  // ── 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(),
+  };
+}