@yewdiel21/motion-kit 0.16.0 → 0.18.0

package/src/components/drilldown-menu/drilldown-menu.css

@@ -0,0 +1,133 @@
+/* Drilldown menu: a single live level travels in the navigation direction. */
+.mk-drilldown-menu,
+mk-drilldown-menu {
+  --mk-drilldown-radius: 28px;
+  --mk-drilldown-item-radius: 18px;
+  display: block;
+  box-sizing: border-box;
+  width: 100%;
+  max-width: 26rem;
+  min-width: 0;
+  padding: 12px;
+  border: 0;
+  border-radius: var(--mk-drilldown-radius);
+  background: var(--mk-surface-1);
+  color: var(--mk-text);
+  font-family: var(--md-sys-typescale-body-large-font, inherit);
+  font-family: var(--mk-font);
+}
+
+[data-mk-drilldown-header] {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  min-height: 48px;
+  padding: 4px 10px;
+}
+
+[data-mk-drilldown-heading] {
+  min-width: 0;
+  overflow-wrap: anywhere;
+  font-size: 1.1rem;
+  font-weight: 650;
+  letter-spacing: -0.025em;
+}
+
+[data-mk-drilldown-back] {
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  width: 36px;
+  height: 36px;
+  padding: 0;
+  border: 0;
+  border-radius: 50%;
+  background: var(--mk-surface-3);
+  color: var(--mk-text);
+  cursor: pointer;
+}
+
+[data-mk-drilldown-back] > svg { transform: rotate(180deg); }
+[data-mk-drilldown-back][hidden],
+[data-mk-drilldown-empty][hidden] { display: none; }
+
+[data-mk-drilldown-breadcrumb] ol {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 4px;
+  margin: 0;
+  padding: 0 12px 12px;
+  list-style: none;
+  color: var(--mk-muted);
+  font-size: 0.75rem;
+  line-height: 1.5;
+}
+
+[data-mk-drilldown-breadcrumb] li {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
+[data-mk-drilldown-breadcrumb] li + li::before { content: '/'; opacity: 0.5; }
+[data-mk-drilldown-breadcrumb] [aria-current] { color: var(--mk-text); }
+[data-mk-drilldown-crumb] {
+  padding: 2px;
+  border: 0;
+  border-radius: 4px;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  cursor: pointer;
+}
+
+[data-mk-drilldown-viewport] { position: relative; isolation: isolate; overflow: hidden; border-radius: var(--mk-drilldown-item-radius); }
+[data-mk-drilldown-highlight] { position: absolute; top: 0; left: 0; z-index: -1; border-radius: var(--mk-radius-lg); background: var(--mk-surface-3); pointer-events: none; opacity: 0; }
+[data-mk-drilldown-level] { position: relative; display: grid; gap: 6px; }
+[data-mk-drilldown-item] {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 18px;
+  width: 100%;
+  min-height: 58px;
+  padding: 13px 15px;
+  border: 0;
+  border-radius: var(--mk-drilldown-item-radius);
+  background: transparent;
+  color: var(--mk-text);
+  font: inherit;
+  font-size: 0.9rem;
+  line-height: 1.4;
+  text-align: start;
+  cursor: pointer;
+  transition: color .15s, border-radius .3s var(--mk-ease-playful);
+}
+
+[data-mk-drilldown-item]:enabled:hover,
+[data-mk-drilldown-item]:focus-visible { background: color-mix(in srgb, var(--mk-text) 3%, transparent); border-radius: var(--mk-radius-xl); }
+[data-mk-drilldown-item][data-mk-chosen]::after { content: '✓'; display: grid; place-items: center; flex: none; width: 26px; height: 26px; border-radius: 50%; color: var(--mk-on-accent); background: var(--mk-accent); }
+[data-mk-drilldown-item]:disabled { opacity: 0.42; cursor: default; }
+[data-mk-drilldown-text] { display: grid; gap: 3px; min-width: 0; overflow-wrap: anywhere; }
+[data-mk-drilldown-label] { font-weight: 550; }
+[data-mk-drilldown-description] { color: var(--mk-muted); font-size: 0.8rem; }
+[data-mk-drilldown-arrow] { display: inline-flex; flex: none; color: var(--mk-muted); }
+[data-mk-drilldown-arrow] svg { transition: transform .35s var(--mk-ease-swatch); }
+[data-mk-highlighted] [data-mk-drilldown-arrow] svg { transform: translateX(3px); }
+[data-mk-drilldown-empty] { margin: 0; padding: 24px 16px; color: var(--mk-muted); font-size: 0.875rem; }
+
+[data-mk-drilldown-item]:focus-visible,
+[data-mk-drilldown-back]:focus-visible,
+[data-mk-drilldown-crumb]:focus-visible,
+[data-mk-drilldown-level]:focus-visible {
+  outline: 2px solid var(--mk-accent);
+  outline-offset: -2px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-mk-drilldown-item] { transition: none; }
+}

package/src/components/drilldown-menu/element.ts

@@ -0,0 +1,59 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createDrilldownMenu, type DrilldownMenuInstance, type DrilldownMenuItem, type DrilldownMenuOptions } from './engine';
+
+/** Light DOM action menu; items/path accept JSON. Emits mk:select and mk:path-change. */
+export class MkDrilldownMenuElement extends MkElement<DrilldownMenuInstance> {
+  static options: Record<string, OptionType> = { items: 'json', path: 'json', label: 'string', backLabel: 'string', emptyText: 'string' };
+  private pendingItems: DrilldownMenuItem[] | undefined;
+  private pendingPath: string[] | undefined;
+
+  protected create(options: Record<string, unknown>) {
+    return createDrilldownMenu(this, {
+      ...options,
+      ...(this.pendingItems !== undefined ? { items: this.pendingItems } : {}),
+      ...(this.pendingPath !== undefined ? { path: this.pendingPath } : {}),
+    } as DrilldownMenuOptions);
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next) return;
+    if (name === 'items' || name === 'path') {
+      try {
+        const value: unknown = JSON.parse(next ?? '[]');
+        if (!Array.isArray(value)) return;
+        if (name === 'items') {
+          this.pendingItems = value as DrilldownMenuItem[];
+          this.instance?.setItems(this.pendingItems);
+        } else {
+          this.pendingPath = value as string[];
+          this.instance?.setPath(this.pendingPath);
+        }
+      } catch {
+        // Invalid JSON leaves the last valid data and path intact.
+      }
+    } else if (this.instance) {
+      const { label, backLabel, emptyText } = this.options;
+      this.instance.update({ label, backLabel, emptyText } as DrilldownMenuOptions);
+    }
+  }
+
+  get items() { return this.pendingItems ?? (this.options.items as DrilldownMenuItem[] | undefined) ?? []; }
+  set items(items: DrilldownMenuItem[]) {
+    this.pendingItems = items;
+    this.instance?.setItems(items);
+  }
+  get path() { return this.instance?.path ?? this.pendingPath ?? (this.options.path as string[] | undefined) ?? []; }
+  set path(path: string[]) {
+    this.pendingPath = path;
+    this.instance?.setPath(path);
+  }
+  open(id: string) { return this.instance?.open(id) ?? false; }
+  back() { return this.instance?.back() ?? false; }
+  root() { this.instance?.root(); }
+  reset() { this.instance?.reset(); }
+  setItems(items: DrilldownMenuItem[]) { this.items = items; }
+  setPath(path: string[]) { this.path = path; }
+  focusItem(id: string) { this.instance?.focusItem(id); }
+}
+
+export const defineDrilldownMenu = () => defineElement('mk-drilldown-menu', MkDrilldownMenuElement);

package/src/components/drilldown-menu/engine.ts

@@ -0,0 +1,378 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { press, ringPulse } from '../../motion/micro';
+
+export interface DrilldownMenuItem {
+  /** Unique among siblings; IDs form the navigation path. */
+  id: string;
+  label: string;
+  description?: string;
+  disabled?: boolean;
+  /** Present (even an empty array) for a level; absent for an action. */
+  children?: DrilldownMenuItem[];
+}
+
+export interface DrilldownMenuOptions {
+  items?: DrilldownMenuItem[];
+  /** IDs of branches from the root to the initial level. */
+  path?: string[];
+  /** Root heading and accessible name (default 'Actions'). */
+  label?: string;
+  backLabel?: string;
+  emptyText?: string;
+  /** An action's complete path, including the action's ID. */
+  onSelect?: (item: DrilldownMenuItem, path: string[]) => void;
+  /** Navigation only; the path contains branch IDs. */
+  onPathChange?: (path: string[]) => void;
+}
+
+export interface DrilldownMenuInstance extends Instance {
+  /** Open a branch in the current level; false for missing, disabled or leaf items. */
+  open(id: string): boolean;
+  back(): boolean;
+  root(): void;
+  reset(): void;
+  /** Invalid, disabled or non-branch IDs truncate the requested path safely. */
+  setPath(path: string[], notify?: boolean): void;
+  setItems(items: DrilldownMenuItem[]): void;
+  update(options: Partial<DrilldownMenuOptions>): void;
+  focusItem(id: string): void;
+  readonly path: string[];
+  /** Items in the current level. */
+  readonly items: DrilldownMenuItem[];
+  readonly element: HTMLElement;
+}
+
+const CHEVRON = '<svg aria-hidden="true" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m9 6 6 6-6 6"/></svg>';
+let sequence = 0;
+const samePath = (a: string[], b: string[]) => a.length === b.length && a.every((id, i) => id === b[i]);
+const branch = (item: DrilldownMenuItem) => Array.isArray(item.children);
+const copyItems = (items: DrilldownMenuItem[]): DrilldownMenuItem[] => items.map((item) => ({ ...item, ...(branch(item) ? { children: copyItems(item.children!) } : {}) }));
+
+/** A single live level: directional slide + blur, roving menu focus, and reversible DOM ownership. */
+export function createDrilldownMenu(root: HTMLElement | null, options: DrilldownMenuOptions = {}): DrilldownMenuInstance {
+  if (!root) return inert({ open: () => false, back: () => false, root() {}, reset() {}, setPath() {}, setItems() {}, update() {}, focusItem() {}, path: [], items: [], element: null as unknown as HTMLElement });
+  registerMotion();
+  const scope = createScope();
+  const uid = `mk-drilldown-${++sequence}`;
+  const authored = [...root.childNodes];
+  // Keep the authored nodes themselves, including any listeners, for destroy().
+  const holder = document.createDocumentFragment();
+  holder.append(...authored);
+  let config = { ...options };
+  let data = copyItems(options.items ?? []);
+  let path: string[] = [];
+  let focused: string | null = null;
+  const remembered = new Map<string, string>();
+  let animation: gsap.core.Timeline | null = null;
+  let hoverMotion: gsap.core.Tween | null = null;
+  const effects = new Set<gsap.core.Animation>();
+  const keep = (effect: gsap.core.Animation | null) => {
+    for (const animation of effects) if (animation.totalProgress() === 1) effects.delete(animation);
+    if (effect) effects.add(effect);
+  };
+
+  const header = document.createElement('div');
+  header.dataset.mkDrilldownHeader = '';
+  const backButton = document.createElement('button');
+  backButton.type = 'button';
+  backButton.dataset.mkDrilldownBack = '';
+  backButton.innerHTML = CHEVRON;
+  const heading = document.createElement('span');
+  heading.id = `${uid}-heading`;
+  heading.dataset.mkDrilldownHeading = '';
+  header.append(backButton, heading);
+  const breadcrumb = document.createElement('nav');
+  breadcrumb.dataset.mkDrilldownBreadcrumb = '';
+  const crumbs = document.createElement('ol');
+  breadcrumb.append(crumbs);
+  const viewport = document.createElement('div');
+  viewport.dataset.mkDrilldownViewport = '';
+  const menu = document.createElement('div');
+  menu.dataset.mkDrilldownLevel = '';
+  menu.id = `${uid}-level`;
+  menu.setAttribute('role', 'menu');
+  menu.setAttribute('aria-labelledby', heading.id);
+  const empty = document.createElement('p');
+  empty.dataset.mkDrilldownEmpty = '';
+  empty.setAttribute('role', 'status');
+  const highlight = document.createElement('span');
+  highlight.dataset.mkDrilldownHighlight = ''; highlight.setAttribute('aria-hidden', 'true');
+  viewport.append(highlight, menu, empty);
+  backButton.setAttribute('aria-controls', menu.id);
+  root.append(header, breadcrumb, viewport);
+  scope.attr(root, 'data-mk-ready', '');
+
+  const levelAt = (requested: string[]) => {
+    const valid: string[] = [];
+    const ancestors: DrilldownMenuItem[] = [];
+    let items = data;
+    for (const id of requested) {
+      const item = items.find((entry) => entry.id === id);
+      if (!item || item.disabled || !branch(item)) break;
+      valid.push(id);
+      ancestors.push(item);
+      items = item.children!;
+    }
+    return { valid, ancestors, items };
+  };
+  const level = () => levelAt(path);
+  const enabled = () => [...menu.querySelectorAll<HTMLButtonElement>('[data-mk-drilldown-item]')].filter((item) => !item.disabled);
+  const buttonOf = (id: string) => enabled().find((item) => item.dataset.mkDrilldownItem === id);
+  const highlightItem = (button?: HTMLButtonElement | null) => {
+    hoverMotion?.kill();
+    for (const item of enabled()) item.toggleAttribute('data-mk-highlighted', item === button);
+    if (!button) { highlight.style.opacity = '0'; return; }
+    const geometry = { x: button.offsetLeft + menu.offsetLeft, y: button.offsetTop + menu.offsetTop, width: button.offsetWidth, height: button.offsetHeight, opacity: 1 };
+    if (reduced()) gsap.set(highlight, geometry);
+    else hoverMotion = gsap.to(highlight, { ...geometry, duration: .35, ease: EASE.swatch });
+  };
+  const cancelMotion = () => {
+    animation?.kill();
+    hoverMotion?.kill();
+    animation = null;
+    gsap.set([menu, heading, breadcrumb, ...menu.children], { clearProps: 'transform,opacity,filter' });
+    gsap.set(viewport, { clearProps: 'height' });
+  };
+  const roving = (id: string | null, focus = false) => {
+    const items = enabled();
+    const target = items.find((item) => item.dataset.mkDrilldownItem === id) ?? items[0];
+    focused = target?.dataset.mkDrilldownItem ?? null;
+    for (const item of menu.querySelectorAll<HTMLButtonElement>('[data-mk-drilldown-item]')) item.tabIndex = item === target ? 0 : -1;
+    // Empty/all-disabled levels remain a keyboard stop so Left/Escape can return.
+    menu.tabIndex = target ? -1 : 0;
+    if (focused) remembered.set(JSON.stringify(path), focused);
+    if (focus) (target ?? menu).focus({ preventScroll: true });
+    if (focus) highlightItem(target);
+  };
+  const notifyPath = () => {
+    const next = [...path];
+    root.dispatchEvent(new CustomEvent('mk:path-change', { bubbles: true, detail: { path: [...next] } }));
+    config.onPathChange?.(next);
+  };
+
+  const render = (direction: number, focus: boolean, preferred?: string | null) => {
+    const oldHeight = viewport.getBoundingClientRect().height;
+    cancelMotion();
+    highlightItem(null);
+    const current = level();
+    const label = config.label ?? 'Actions';
+    const title = current.ancestors.at(-1)?.label ?? label;
+    heading.textContent = title;
+    backButton.hidden = path.length === 0;
+    backButton.setAttribute('aria-label', config.backLabel ?? 'Back');
+    breadcrumb.setAttribute('aria-label', `${label} path`);
+    // At the root the heading already names the only crumb.
+    breadcrumb.hidden = path.length === 0;
+    const labels = [label, ...current.ancestors.map((item) => item.label)];
+    crumbs.replaceChildren(...labels.map((text, index) => {
+      const li = document.createElement('li');
+      if (index === labels.length - 1) {
+        const span = document.createElement('span');
+        span.setAttribute('aria-current', 'location');
+        span.textContent = text;
+        li.append(span);
+      } else {
+        const button = document.createElement('button');
+        button.type = 'button';
+        button.dataset.mkDrilldownCrumb = String(index);
+        button.textContent = text;
+        button.setAttribute('aria-controls', menu.id);
+        li.append(button);
+      }
+      return li;
+    }));
+    menu.replaceChildren(...current.items.map((item, index) => {
+      const button = document.createElement('button');
+      button.type = 'button';
+      button.dataset.mkDrilldownItem = item.id;
+      button.setAttribute('role', 'menuitem');
+      button.disabled = Boolean(item.disabled);
+      if (item.disabled) button.setAttribute('aria-disabled', 'true');
+      const text = document.createElement('span');
+      text.dataset.mkDrilldownText = '';
+      const name = document.createElement('span');
+      name.id = `${uid}-item-${index}`;
+      name.dataset.mkDrilldownLabel = '';
+      name.textContent = item.label;
+      button.setAttribute('aria-labelledby', name.id);
+      text.append(name);
+      if (item.description) {
+        const description = document.createElement('span');
+        description.id = `${uid}-description-${index}`;
+        description.dataset.mkDrilldownDescription = '';
+        description.textContent = item.description;
+        button.setAttribute('aria-describedby', description.id);
+        text.append(description);
+      }
+      button.append(text);
+      if (branch(item)) {
+        button.setAttribute('aria-haspopup', 'menu');
+        const arrow = document.createElement('span');
+        arrow.dataset.mkDrilldownArrow = '';
+        arrow.innerHTML = CHEVRON;
+        button.append(arrow);
+      }
+      return button;
+    }));
+    empty.textContent = config.emptyText ?? 'No actions available';
+    empty.hidden = current.items.length !== 0;
+    roving(preferred ?? remembered.get(JSON.stringify(path)) ?? null);
+    if (direction && !reduced()) {
+      // There is only one live menu. Replacing its content before animating avoids
+      // duplicated menuitems and allows rapid navigation without stale callbacks.
+      animation = gsap.timeline({ onComplete: () => { animation = null; } })
+        .fromTo(menu, { x: 28 * direction, opacity: 0, filter: 'blur(6px)' }, { x: 0, opacity: 1, filter: 'blur(0px)', duration: 0.36, ease: EASE.signature, clearProps: 'transform,opacity,filter' });
+      animation.fromTo([heading, breadcrumb], { y: -6, opacity: .3, filter: 'blur(6px)' }, { y: 0, opacity: 1, filter: 'blur(0px)', duration: .3, ease: EASE.pop, clearProps: 'transform,opacity,filter' }, 0)
+        .fromTo([...menu.children], { x: 12 * direction, opacity: 0 }, { x: 0, opacity: 1, duration: .3, stagger: .035, ease: EASE.swatchLight, clearProps: 'transform,opacity' }, .04);
+      const nextHeight = viewport.getBoundingClientRect().height;
+      if (oldHeight > 0 && nextHeight > 0 && oldHeight !== nextHeight) {
+        animation.fromTo(viewport, { height: oldHeight }, { height: nextHeight, duration: 0.36, ease: EASE.signature, clearProps: 'height' }, 0);
+      }
+    }
+    // Transform measurement may temporarily detach a zero-size element. Restore
+    // focus after GSAP has measured, including in hidden surfaces and jsdom.
+    if (focus) roving(focused, true);
+  };
+
+  const navigate = (requested: string[], notify: boolean, focus: boolean, preferred?: string | null) => {
+    if (scope.disposed) return false;
+    const next = levelAt(requested).valid;
+    if (samePath(path, next)) return false;
+    const previous = path;
+    if (focused) remembered.set(JSON.stringify(previous), focused);
+    const direction = next.length > path.length ? 1 : -1;
+    path = next;
+    render(direction, focus, preferred);
+    if (notify) notifyPath();
+    return true;
+  };
+  const open = (id: string) => {
+    if (scope.disposed) return false;
+    const item = level().items.find((entry) => entry.id === id);
+    if (!item || item.disabled || !branch(item)) return false;
+    return navigate([...path, id], true, true);
+  };
+  const back = () => path.length ? navigate(path.slice(0, -1), true, true, path.at(-1)) : false;
+  const reset = () => navigate([], true, root.contains(document.activeElement), path[0]);
+  const activate = (id: string) => {
+    const item = level().items.find((entry) => entry.id === id);
+    if (!item || item.disabled) return;
+    if (branch(item)) return void open(id);
+    const button = buttonOf(id);
+    if (button) {
+      for (const row of enabled()) row.toggleAttribute('data-mk-chosen', row === button);
+      keep(press(button)); keep(ringPulse(button));
+    }
+    const selected = copyItems([item])[0]!;
+    const selectedPath = [...path, item.id];
+    root.dispatchEvent(new CustomEvent('mk:select', { bubbles: true, detail: { item: selected, path: [...selectedPath] } }));
+    config.onSelect?.(copyItems([item])[0]!, [...selectedPath]);
+  };
+
+  scope.on(menu, 'click', (event) => {
+    const button = (event.target as Element | null)?.closest<HTMLButtonElement>('[data-mk-drilldown-item]');
+    if (!button || !menu.contains(button) || button.disabled) return;
+    roving(button.dataset.mkDrilldownItem!, false);
+    activate(button.dataset.mkDrilldownItem!);
+  });
+  scope.on(menu, 'focusin', (event) => {
+    const button = (event.target as Element | null)?.closest<HTMLButtonElement>('[data-mk-drilldown-item]');
+    if (button && !button.disabled) { roving(button.dataset.mkDrilldownItem!, false); highlightItem(button); }
+  });
+  scope.on(menu, 'pointerover', event => {
+    const button = (event.target as Element | null)?.closest<HTMLButtonElement>('[data-mk-drilldown-item]');
+    if (button && !button.disabled) highlightItem(button);
+  });
+  scope.on(menu, 'pointerleave', () => highlightItem(menu.contains(document.activeElement) ? buttonOf(focused ?? '') : null));
+  if (typeof ResizeObserver === 'function') scope.observe(new ResizeObserver(() => {
+    const current = menu.querySelector<HTMLButtonElement>('[data-mk-highlighted]');
+    if (current) highlightItem(current);
+  })).observe(menu);
+  scope.on(root, 'keydown', (event) => {
+    const key = (event as KeyboardEvent).key;
+    if ((key === 'ArrowLeft' || key === 'Escape') && path.length) {
+      event.preventDefault();
+      event.stopPropagation();
+      back();
+      return;
+    }
+    if (!menu.contains(event.target as Node)) return;
+    const items = enabled();
+    const at = items.indexOf(document.activeElement as HTMLButtonElement);
+    const moves: Record<string, number> = { ArrowDown: (at + 1) % items.length, ArrowUp: at < 0 ? items.length - 1 : (at - 1 + items.length) % items.length, Home: 0, End: items.length - 1 };
+    if (key in moves && items.length) {
+      event.preventDefault();
+      roving(items[moves[key]]!.dataset.mkDrilldownItem!, true);
+      return;
+    }
+    const button = (event.target as Element | null)?.closest<HTMLButtonElement>('[data-mk-drilldown-item]');
+    if (!button || button.disabled || !menu.contains(button)) return;
+    if (key === 'Enter' || key === ' ' || key === 'ArrowRight') {
+      const item = level().items.find((entry) => entry.id === button.dataset.mkDrilldownItem);
+      if (key === 'ArrowRight' && (!item || !branch(item))) return;
+      event.preventDefault();
+      activate(button.dataset.mkDrilldownItem!);
+    }
+  });
+  scope.on(backButton, 'click', () => { keep(press(backButton)); back(); });
+  scope.on(breadcrumb, 'click', (event) => {
+    const button = (event.target as Element | null)?.closest<HTMLButtonElement>('[data-mk-drilldown-crumb]');
+    if (!button || !breadcrumb.contains(button)) return;
+    const depth = Number(button.dataset.mkDrilldownCrumb);
+    navigate(path.slice(0, depth), true, true, path[depth]);
+  });
+  scope.add(() => {
+    cancelMotion();
+    for (const effect of effects) effect.kill();
+    gsap.killTweensOf([heading, breadcrumb, highlight]);
+    remembered.clear();
+    header.remove();
+    breadcrumb.remove();
+    viewport.remove();
+    root.append(holder);
+  });
+  path = levelAt(options.path ?? []).valid;
+  render(0, false);
+
+  const update = (next: Partial<DrilldownMenuOptions>) => {
+    if (scope.disposed) return;
+    const active = document.activeElement as HTMLElement | null;
+    const hadFocus = root.contains(active);
+    const backFocused = active === backButton;
+    const crumbFocused = active?.dataset.mkDrilldownCrumb;
+    const previousPath = path;
+    const previousFocus = focused;
+    config = { ...config, ...next };
+    if (next.items !== undefined) data = copyItems(next.items);
+    path = levelAt(next.path ?? path).valid;
+    const changed = !samePath(previousPath, path);
+    const preferred = changed ? previousPath[path.length] : previousFocus;
+    render(0, hadFocus, preferred);
+    if (hadFocus && !changed) {
+      if (backFocused && !backButton.hidden) backButton.focus({ preventScroll: true });
+      else if (crumbFocused !== undefined) {
+        [...crumbs.querySelectorAll<HTMLButtonElement>('[data-mk-drilldown-crumb]')]
+          .find((button) => button.dataset.mkDrilldownCrumb === crumbFocused)?.focus({ preventScroll: true });
+      }
+    }
+    // Updating data may invalidate a controlled path; report the repaired path.
+    if (changed && next.path === undefined) notifyPath();
+  };
+  return {
+    open,
+    back,
+    root: reset,
+    reset,
+    setPath: (next, notify = false) => { navigate(next, notify, root.contains(document.activeElement)); },
+    setItems: (items) => update({ items }),
+    update,
+    focusItem(id) { if (!scope.disposed && buttonOf(id)) roving(id, true); },
+    get path() { return [...path]; },
+    get items() { return copyItems(level().items); },
+    element: root,
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/drilldown-menu/react.tsx

@@ -0,0 +1,76 @@
+'use client';
+
+import { forwardRef, useImperativeHandle, useReducer, useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createDrilldownMenu, type DrilldownMenuInstance, type DrilldownMenuItem, type DrilldownMenuOptions } from './engine';
+
+export interface DrilldownMenuProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'dangerouslySetInnerHTML' | 'onSelect'>, Omit<DrilldownMenuOptions, 'items' | 'path'> {
+  items: DrilldownMenuItem[];
+  /** Controlled branch path; pair with onPathChange. */
+  path?: string[];
+  /** Initial branch path when uncontrolled. */
+  defaultPath?: string[];
+}
+
+export type DrilldownMenuHandle = Pick<DrilldownMenuInstance, 'open' | 'back' | 'root' | 'reset' | 'setPath' | 'focusItem'>;
+
+/** Data-driven hierarchical actions with controlled or internal navigation. */
+export const DrilldownMenu = forwardRef<DrilldownMenuHandle, DrilldownMenuProps>(function DrilldownMenu(
+  { items, path, defaultPath, label, backLabel, emptyText, onSelect, onPathChange, className, ...props },
+  handle,
+) {
+  const { children: _children, dangerouslySetInnerHTML: _html, ...rootProps } = props as HTMLAttributes<HTMLDivElement>;
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<DrilldownMenuInstance | null>(null);
+  const select = useLatest(onSelect);
+  const changed = useLatest(onPathChange);
+  const controlled = useLatest(path);
+  const [, refresh] = useReducer((value: number) => value + 1, 0);
+  useImperativeHandle(handle, () => ({
+    open: (id) => instance.current?.open(id) ?? false,
+    back: () => instance.current?.back() ?? false,
+    root: () => instance.current?.root(),
+    reset: () => instance.current?.reset(),
+    setPath: (next, notify) => {
+      instance.current?.setPath(next, notify);
+      // Silent engine synchronization does not invoke onPathChange. Controlled
+      // refs must still reconcile with the parent's current path on a render.
+      if (controlled.current !== undefined) refresh();
+    },
+    focusItem: (id) => instance.current?.focusItem(id),
+  }), []);
+  const itemsKey = JSON.stringify(items);
+  useIsomorphicLayoutEffect(() => {
+    const created = createDrilldownMenu(ref.current, {
+      items,
+      path: path ?? defaultPath,
+      label,
+      backLabel,
+      emptyText,
+      onSelect: (item, selectedPath) => select.current?.(item, selectedPath),
+      onPathChange: (next) => {
+        changed.current?.(next);
+        // Also render if a controlled parent declines the navigation request.
+        if (controlled.current !== undefined) refresh();
+      },
+    });
+    instance.current = created;
+    return () => {
+      created.destroy();
+      instance.current = null;
+    };
+    // The engine owns its DOM for this mount; subsequent props update it below.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+  useIsomorphicLayoutEffect(() => {
+    // Controlled data and its path are one external model. Applying the path in
+    // this update avoids repairing a stale level against replacement items.
+    instance.current?.update({ items, label, backLabel, emptyText, ...(path !== undefined ? { path } : {}) });
+    // JSON keys also catch edited data without forcing redraws on equal arrays.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [itemsKey, label, backLabel, emptyText]);
+  useIsomorphicLayoutEffect(() => {
+    if (path !== undefined) instance.current?.setPath(path);
+  });
+  return <div {...rootProps} ref={ref} className={['mk-drilldown-menu', className].filter(Boolean).join(' ')} />;
+});