@yewdiel21/motion-kit 0.14.0 → 0.15.0

package/src/components/toolbar/engine.ts

@@ -0,0 +1,230 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, warnOnce, type Instance } from '../../core/types';
+import { press } from '../../motion/micro';
+
+/*
+ * Toolbar: a rail of tools where one is chosen, marked by a light blob under
+ * its icon. Choosing another stretches the blob like slime: its leading edge
+ * reaches the new tool first (.2 s) while it narrows, then the trailing edge
+ * lets go and catches up on the swatch curve (.38,.49,0,1.5), so it wobbles
+ * into place; choosing the same tool squeezes it. A label slides out beside
+ * the tool under the pointer (or focus) and glides between tools. A toolbar
+ * for the keyboard: arrows and Home/End move and choose (roving tabindex),
+ * each tool says aria-pressed. Vertical by default, or horizontal.
+ */
+
+export interface ToolbarOptions {
+  /** The chosen tool (its data-mk-tool, else its position); default: the first one. */
+  value?: string;
+  /** Default 'vertical'. */
+  orientation?: 'vertical' | 'horizontal';
+  /** The label beside the tool under the pointer or focus (default true). */
+  tips?: boolean;
+  onChange?: (value: string) => void;
+}
+
+export interface ToolbarInstance extends Instance {
+  setValue(value: string, notify?: boolean): void;
+  readonly value: string;
+}
+
+export function createToolbar(root: HTMLElement | null, options: ToolbarOptions = {}): ToolbarInstance {
+  const tools = root ? [...root.querySelectorAll<HTMLButtonElement>('button')] : [];
+  if (!root || !tools.length) {
+    if (root) warnOnce('toolbar: needs at least one <button>');
+    return inert({ setValue() {}, value: '' });
+  }
+  registerMotion();
+  const scope = createScope();
+  const vertical = options.orientation !== 'horizontal';
+  const valueOf = (tool: HTMLElement) => tool.dataset.mkTool ?? String(tools.indexOf(tool as HTMLButtonElement));
+  const labelOf = (tool: HTMLElement) => tool.getAttribute('aria-label') ?? tool.title ?? tool.textContent?.trim() ?? '';
+
+  scope.attr(root, 'role', 'toolbar');
+  scope.attr(root, 'aria-orientation', vertical ? 'vertical' : 'horizontal');
+  scope.attr(root, 'data-mk-orientation', vertical ? 'vertical' : 'horizontal');
+  for (const tool of tools) {
+    scope.attr(tool, 'type', tool.getAttribute('type') ?? 'button');
+    scope.attr(tool, 'aria-pressed', 'false');
+    scope.attr(tool, 'tabindex', '-1');
+    // A title would show the browser's own tooltip over ours.
+    if (options.tips !== false && tool.title) {
+      scope.attr(tool, 'aria-label', tool.getAttribute('aria-label') ?? tool.title);
+      scope.attr(tool, 'title', null);
+    }
+  }
+
+  const blob = document.createElement('span');
+  blob.dataset.mkToolbarBlob = '';
+  blob.setAttribute('aria-hidden', 'true');
+  root.prepend(blob);
+  const tip = document.createElement('span');
+  tip.dataset.mkToolbarTip = '';
+  tip.setAttribute('aria-hidden', 'true');
+  tip.hidden = true;
+  if (options.tips !== false) root.append(tip);
+  scope.add(() => {
+    gsap.killTweensOf([blob, tip]);
+    blob.remove();
+    tip.remove();
+  });
+  scope.attr(root, 'data-mk-ready', '');
+
+  const find = (value: string | undefined) => tools.find((tool) => valueOf(tool) === value);
+  let current = find(options.value) ?? tools.find((tool) => !tool.disabled) ?? tools[0]!;
+
+  /** Where a tool sits inside the rail (offsets, so transforms on the rail do not count). */
+  const box = (tool: HTMLElement) => ({ start: vertical ? tool.offsetTop : tool.offsetLeft, size: vertical ? tool.offsetHeight : tool.offsetWidth, cross: vertical ? tool.offsetLeft : tool.offsetTop, crossSize: vertical ? tool.offsetWidth : tool.offsetHeight });
+  const along = vertical ? 'y' : 'x';
+  const across = vertical ? 'x' : 'y';
+  const length = vertical ? 'height' : 'width';
+  const thickness = vertical ? 'width' : 'height';
+
+  let timeline: gsap.core.Timeline | null = null;
+  const place = () => {
+    const at = box(current);
+    timeline?.kill();
+    gsap.set(blob, { [along]: at.start, [across]: at.cross, [length]: at.size, [thickness]: at.crossSize, scaleX: 1, scaleY: 1 });
+  };
+
+  /** The slime: the leading edge reaches the tool, then the trailing edge lets go and wobbles in. */
+  const slide = (from: HTMLElement, to: HTMLElement) => {
+    if (reduced() || from === to) return place();
+    const a = box(from);
+    const b = box(to);
+    const forward = b.start > a.start;
+    const reach = forward ? b.start + b.size - a.start : a.start + a.size - b.start;
+    const squeeze = vertical ? { scaleX: 0.84 } : { scaleY: 0.84 };
+    const relax = vertical ? { scaleX: 1 } : { scaleY: 1 };
+    timeline?.kill();
+    timeline = gsap.timeline();
+    timeline.to(blob, { [along]: forward ? a.start : b.start, [length]: reach, ...squeeze, duration: 0.2, ease: 'power2.in' }, 0);
+    timeline.to(blob, { [along]: b.start, [length]: b.size, duration: 0.42, ease: EASE.swatch }, 0.16);
+    timeline.to(blob, { ...relax, duration: 0.5, ease: 'elastic.out(1, 0.45)' }, 0.18);
+  };
+
+  const squish = () => {
+    if (reduced()) return;
+    timeline?.kill();
+    place();
+    timeline = gsap.timeline();
+    timeline.to(blob, { scaleX: 0.88, scaleY: 0.88, duration: 0.1, ease: 'power2.out' }).to(blob, { scaleX: 1, scaleY: 1, duration: 0.45, ease: 'elastic.out(1, 0.4)' });
+  };
+
+  const paint = () => {
+    for (const tool of tools) {
+      tool.setAttribute('aria-pressed', String(tool === current));
+      tool.setAttribute('tabindex', tool === current ? '0' : '-1');
+    }
+  };
+
+  // ── The label beside a tool ───────────────────────────────────────────────
+  let tipFor: HTMLElement | null = null;
+  let tipTimer: ReturnType<typeof setTimeout> | undefined;
+  scope.add(() => clearTimeout(tipTimer));
+  const showTip = (tool: HTMLElement, linger = 0) => {
+    if (options.tips === false) return;
+    clearTimeout(tipTimer);
+    const text = labelOf(tool);
+    if (!text) return hideTip();
+    const at = box(tool);
+    const appearing = tip.hidden;
+    const changed = tipFor !== tool;
+    tipFor = tool;
+    tip.textContent = text;
+    tip.hidden = false;
+    const tipSize = vertical ? tip.offsetHeight : tip.offsetWidth;
+    const spot = at.start + at.size / 2 - tipSize / 2;
+    if (appearing || reduced()) {
+      gsap.killTweensOf(tip);
+      gsap.set(tip, { [along]: spot });
+      if (!reduced()) gsap.fromTo(tip, { opacity: 0, [across]: -8, filter: 'blur(4px)', scale: 0.9 }, { opacity: 1, [across]: 0, filter: 'blur(0px)', scale: 1, duration: 0.28, ease: EASE.pop });
+      else gsap.set(tip, { opacity: 1, [across]: 0, scale: 1, filter: 'none' });
+    } else if (changed) {
+      gsap.to(tip, { [along]: spot, opacity: 1, [across]: 0, scale: 1, filter: 'blur(0px)', duration: 0.32, ease: EASE.swatch, overwrite: 'auto' });
+    }
+    if (linger) tipTimer = setTimeout(hideTip, linger);
+  };
+  const hideTip = () => {
+    clearTimeout(tipTimer);
+    tipFor = null;
+    if (tip.hidden) return;
+    if (reduced()) {
+      tip.hidden = true;
+      return;
+    }
+    gsap.to(tip, { opacity: 0, [across]: -6, filter: 'blur(4px)', scale: 0.92, duration: 0.18, ease: 'power2.in', overwrite: 'auto', onComplete: () => {
+      tip.hidden = true;
+    } });
+  };
+
+  const choose = (tool: HTMLElement, notify: boolean) => {
+    if ((tool as HTMLButtonElement).disabled) return;
+    const previous = current;
+    current = tool as HTMLButtonElement;
+    paint();
+    if (previous === current) squish();
+    else slide(previous, current);
+    if (previous === current || !notify) return;
+    const value = valueOf(current);
+    options.onChange?.(value);
+    root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: { value } }));
+  };
+
+  scope.on(root, 'click', (event) => {
+    const tool = (event.target as Element).closest<HTMLButtonElement>('button');
+    if (!tool || !tools.includes(tool)) return;
+    press(tool);
+    choose(tool, true);
+    showTip(tool, 1200);
+  });
+  scope.on(root, 'pointerover', (event) => {
+    const tool = (event.target as Element).closest<HTMLButtonElement>('button');
+    if (tool && tools.includes(tool) && (event as PointerEvent).pointerType !== 'touch') showTip(tool);
+  });
+  scope.on(root, 'pointerleave', () => {
+    tipTimer = setTimeout(hideTip, 120);
+  });
+  scope.on(root, 'focusin', (event) => {
+    const tool = event.target as HTMLElement;
+    if (tools.includes(tool as HTMLButtonElement) && tool.matches(':focus-visible')) showTip(tool);
+  });
+  scope.on(root, 'focusout', (event) => {
+    if (!root.contains((event as FocusEvent).relatedTarget as Node)) hideTip();
+  });
+  scope.on(root, 'keydown', (event) => {
+    const key = (event as KeyboardEvent).key;
+    const enabled = tools.filter((tool) => !tool.disabled);
+    const at = enabled.indexOf(document.activeElement as HTMLButtonElement);
+    if (at < 0) return;
+    const next =
+      key === 'ArrowDown' || key === 'ArrowRight' ? enabled[(at + 1) % enabled.length]
+      : key === 'ArrowUp' || key === 'ArrowLeft' ? enabled[(at - 1 + enabled.length) % enabled.length]
+      : key === 'Home' ? enabled[0]
+      : key === 'End' ? enabled[enabled.length - 1]
+      : null;
+    if (!next) return;
+    event.preventDefault();
+    choose(next, true);
+    next.focus();
+    showTip(next, 1200);
+  });
+
+  if (typeof ResizeObserver === 'function') scope.observe(new ResizeObserver(() => place())).observe(root);
+
+  paint();
+  place();
+
+  return {
+    setValue(value, notify = false) {
+      const tool = find(value);
+      if (tool) choose(tool, notify);
+    },
+    get value() {
+      return valueOf(current);
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/toolbar/react.tsx

@@ -0,0 +1,34 @@
+'use client';
+import { useRef, type HTMLAttributes, type MutableRefObject } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createToolbar, type ToolbarInstance, type ToolbarOptions } from './engine';
+
+export interface ToolbarProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'>, ToolbarOptions {
+  instanceRef?: MutableRefObject<ToolbarInstance | null>;
+}
+
+/** <Toolbar aria-label="Herramientas" value={tool} onChange={setTool}><button data-mk-tool="lapiz" aria-label="Lápiz">…</button></Toolbar> */
+export function Toolbar({ value, orientation, tips, onChange, instanceRef, className, children, ...props }: ToolbarProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const changed = useLatest(onChange);
+  const instance = useRef<ToolbarInstance | null>(null);
+  useIsomorphicLayoutEffect(() => {
+    const created = createToolbar(ref.current, { value, orientation, tips, onChange: (next) => changed.current?.(next) });
+    instance.current = created;
+    if (instanceRef) instanceRef.current = created;
+    return () => {
+      created.destroy();
+      instance.current = null;
+      if (instanceRef) instanceRef.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [orientation, tips]);
+  useIsomorphicLayoutEffect(() => {
+    if (value !== undefined && instance.current && instance.current.value !== value) instance.current.setValue(value);
+  }, [value]);
+  return (
+    <div {...props} ref={ref} className={['mk-toolbar', className].filter(Boolean).join(' ')}>
+      {children}
+    </div>
+  );
+}

package/src/components/toolbar/toolbar.css

@@ -0,0 +1,121 @@
+/* toolbar — a dark rail of round tools; a light blob sits under the chosen one and stretches like slime to the next.
+   The label beside a tool is a small dark pill. In the dark theme the rail turns light and the blob dark. */
+.mk-toolbar,
+mk-toolbar {
+  --mk-toolbar-rail: color-mix(in srgb, var(--mk-text) 86%, var(--mk-bg));
+  --mk-toolbar-on-rail: var(--mk-bg);
+  --mk-toolbar-blob: var(--mk-bg);
+  --mk-toolbar-on-blob: var(--mk-text);
+  --mk-toolbar-tool: 3.5rem;
+  position: relative;
+  display: inline-flex;
+  width: max-content;
+  max-width: 100%;
+  flex-direction: column;
+  gap: 0.25rem;
+  padding: 0.5rem;
+  border-radius: var(--mk-radius-full);
+  background: var(--mk-toolbar-rail);
+  box-shadow: 0 10px 30px -12px var(--mk-shadow-color, rgb(0 0 0 / 0.35));
+}
+
+:is(.mk-toolbar, mk-toolbar)[data-mk-orientation='horizontal'] {
+  flex-direction: row;
+}
+
+:is(.mk-toolbar, mk-toolbar) > button {
+  position: relative;
+  z-index: 1;
+  display: grid;
+  place-items: center;
+  width: var(--mk-toolbar-tool);
+  height: var(--mk-toolbar-tool);
+  padding: 0;
+  border: 0;
+  border-radius: var(--mk-radius-full);
+  background: transparent;
+  color: var(--mk-toolbar-on-rail);
+  cursor: pointer;
+  transition: color 0.2s ease;
+  -webkit-tap-highlight-color: transparent;
+}
+
+:is(.mk-toolbar, mk-toolbar) > button svg {
+  width: 1.5rem;
+  height: 1.5rem;
+  transition: transform 0.35s var(--mk-ease-swatch);
+}
+
+/* The chosen tool's icon turns dark as the blob arrives under it. */
+:is(.mk-toolbar, mk-toolbar) > button[aria-pressed='true'] {
+  color: var(--mk-toolbar-on-blob);
+  transition-delay: 0.12s;
+}
+
+@media (hover: hover) {
+  :is(.mk-toolbar, mk-toolbar) > button:hover svg {
+    transform: scale(1.1);
+  }
+}
+
+:is(.mk-toolbar, mk-toolbar) > button:focus-visible {
+  outline: 2px solid var(--mk-accent);
+  outline-offset: 2px;
+}
+
+:is(.mk-toolbar, mk-toolbar) > button:disabled {
+  cursor: not-allowed;
+  opacity: 0.4;
+}
+
+[data-mk-toolbar-blob] {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: var(--mk-toolbar-tool);
+  height: var(--mk-toolbar-tool);
+  border-radius: var(--mk-radius-full);
+  background: var(--mk-toolbar-blob);
+  pointer-events: none;
+  will-change: transform, height, width;
+}
+
+[data-mk-toolbar-tip] {
+  position: absolute;
+  top: 0;
+  left: calc(100% + 0.75rem);
+  z-index: 2;
+  padding: 0.4rem 0.9rem;
+  border-radius: var(--mk-radius-full);
+  background: var(--mk-toolbar-rail);
+  color: var(--mk-toolbar-on-rail);
+  font: 500 0.875rem/1.2 var(--mk-font);
+  white-space: nowrap;
+  pointer-events: none;
+}
+
+:is(.mk-toolbar, mk-toolbar)[data-mk-orientation='horizontal'] [data-mk-toolbar-tip] {
+  top: auto;
+  bottom: calc(100% + 0.75rem);
+  left: 0;
+}
+
+[data-mk-toolbar-tip][hidden] {
+  display: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :is(.mk-toolbar, mk-toolbar) > button,
+  :is(.mk-toolbar, mk-toolbar) > button svg {
+    transition: none;
+  }
+}
+
+@media (forced-colors: active) {
+  [data-mk-toolbar-blob] {
+    background: Highlight;
+  }
+  :is(.mk-toolbar, mk-toolbar) > button[aria-pressed='true'] {
+    color: HighlightText;
+  }
+}

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

@@ -7,7 +7,7 @@ import { createTreeView, type TreeNode, type TreeViewInstance } from './engine';
  * Emits mk:select ({id, node}), mk:check ({checked}), mk:expand ({id, expanded}).
  */
 export class MkTreeViewElement extends MkElement<TreeViewInstance> {
-  static options: Record<string, OptionType> = { nodes: 'json', checkable: 'boolean', checked: 'list', expanded: 'list', selected: 'string', search: 'string', label: 'string' };
+  static options: Record<string, OptionType> = { nodes: 'json', checkable: 'boolean', checked: 'list', expanded: 'list', selected: 'string', search: 'string', label: 'string', icons: 'boolean', draggable: 'boolean' };
 
   protected create(options: Record<string, unknown>) {
     // search="" (present without text) turns the field on with its default placeholder.

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

@@ -19,6 +19,11 @@ import { foldText, markText } from '../../core/mark';
  * 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';
@@ -44,6 +49,12 @@ export interface TreeViewOptions {
   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 {
@@ -66,6 +77,30 @@ export interface TreeViewInstance extends Instance {
   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;
@@ -201,6 +236,12 @@ export function createTreeView(root: HTMLElement | null, options: TreeViewOption
       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 = '';
@@ -244,12 +285,30 @@ export function createTreeView(root: HTMLElement | null, options: TreeViewOption
     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 ──────────────────────────────────────────────────
@@ -401,6 +460,121 @@ export function createTreeView(root: HTMLElement | null, options: TreeViewOption
     });
   }
 
+  // ── 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;

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

@@ -3,7 +3,7 @@ import { forwardRef, useImperativeHandle, useRef, type HTMLAttributes } from 're
 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'> {
+export interface TreeViewProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect' | 'children' | 'draggable'>, Omit<TreeViewOptions, 'nodes'> {
   nodes: TreeNode[];
 }
 
@@ -11,7 +11,7 @@ export type TreeViewHandle = Pick<TreeViewInstance, 'expand' | 'collapse' | 'exp
 
 /** <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 },
+  { nodes, checkable, checked, expanded, selected, search, label, loadChildren, renderLabel, searchText, icons, draggable, onSelect, onCheck, onExpand, onMove, className, ...props },
   handle,
 ) {
   const ref = useRef<HTMLDivElement>(null);
@@ -22,6 +22,7 @@ export const TreeView = forwardRef<TreeViewHandle, TreeViewProps>(function TreeV
   const load = useLatest(loadChildren);
   const draw = useLatest(renderLabel);
   const text = useLatest(searchText);
+  const moved = useLatest(onMove);
   useImperativeHandle(
     handle,
     () => ({
@@ -50,6 +51,9 @@ export const TreeView = forwardRef<TreeViewHandle, TreeViewProps>(function TreeV
       onSelect: (node) => select.current?.(node),
       onCheck: (ids) => check.current?.(ids),
       onExpand: (node, open) => expand.current?.(node, open),
+      icons,
+      draggable,
+      onMove: (node, into) => moved.current?.(node, into),
     });
     instance.current = created;
     return () => {
@@ -57,7 +61,7 @@ export const TreeView = forwardRef<TreeViewHandle, TreeViewProps>(function TreeV
       instance.current = null;
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [checkable, String(search), label, Boolean(loadChildren), Boolean(renderLabel), Boolean(searchText)]);
+  }, [checkable, String(search), label, Boolean(loadChildren), Boolean(renderLabel), Boolean(searchText), icons, draggable]);
   const first = useRef(true);
   useIsomorphicLayoutEffect(() => {
     if (first.current) {