@zyncat/ui 0.10.0 → 0.12.0

package/src/components/composites/dropdown/Dropdown.tsx

@@ -0,0 +1,184 @@
+'use client';
+
+import './dropdown.css';
+
+import {
+  Fragment,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  type HTMLAttributes,
+  type ReactElement,
+  type RefObject,
+} from 'react';
+
+import type { DataAttributes } from '../../../dom-props';
+import { resolveMotionTiming } from '../../../motion/motion-timing';
+import { Presence } from '../../../motion/presence';
+import { popIn, popOut } from '../../../motion/presets';
+import type { DisableableAnimation } from '../../../motion/timing';
+import { UIMotion } from '../../../tokens/motion-tokens';
+import { useControllable } from '../../internal/hooks/use-controllable';
+import { ovCloneTrigger, OverlayPortal } from '../../internal/overlay/layer';
+import type { ActivateOn } from '../../internal/utils/activation';
+import { MenuPanel } from './menu-panel';
+import {
+  levelKey,
+  resolveLevels,
+  ROOT_LEVEL,
+  type DropdownItem,
+  type DropdownItems,
+  type MenuChain,
+  type SeedFocus,
+} from './types';
+
+export type { DropdownItem, DropdownGroup } from './types';
+
+const DROPDOWN_TIMING = {
+  open: { duration: 'base', ease: 'entrance' },
+  close: { duration: 'fast', ease: 'exit' },
+} as const;
+
+export interface DropdownProps {
+  /** The rows - a flat `DropdownItem[]`, or `DropdownGroup[]` to render divided sections.
+   *  A row with its own `items` opens a submenu instead of committing. @default [] */
+  items: DropdownItems;
+  /** Cloned to toggle the menu, and used as the anchor. Gets the `aria-haspopup="menu"` wiring. */
+  trigger: ReactElement;
+  /** Whether the trigger and the rows fire on `pointerdown` (snappier) or wait for `click`. @default 'pointerdown' */
+  activateOn?: ActivateOn;
+
+  /** Controlled open state. Omit to stay uncontrolled. */
+  open?: boolean;
+  /** Initial state when uncontrolled. @default false */
+  defaultOpen?: boolean;
+  /** Fires whenever the open state changes. Pair with `open` for controlled use. */
+  onOpenChange?: (open: boolean) => void;
+  /** Fires when a row commits - gets its `id` and the full item. Committing closes every level. */
+  onSelect?: (id: string, item: DropdownItem) => void;
+
+  /** Preferred side of the trigger; flips to the opposite side when cramped. @default 'bottom' */
+  side?: 'top' | 'bottom' | 'left' | 'right';
+  /** Cross-axis alignment against the trigger. Submenus always align to their row. @default 'start' */
+  align?: 'start' | 'center' | 'end';
+
+  /** Base id for the menu and its rows; drives the trigger's `aria-controls`. Auto-generated when omitted. */
+  id?: string;
+  /** Accessible name for the menu - supply when the trigger's own label does not describe it. */
+  ariaLabel?: string;
+  /** Standard attributes (className, style, data-*, ...) forwarded to the top-level menu panel. */
+  htmlProps?: HTMLAttributes<HTMLDivElement> & DataAttributes;
+  /** Open/close timing - motion tokens only, or `null` to disable. @default open 'base'/'entrance', close 'fast'/'exit' */
+  animation?: DisableableAnimation;
+}
+
+export function Dropdown({
+  items = [],
+  trigger,
+  activateOn = 'pointerdown',
+  open: controlledOpen,
+  defaultOpen = false,
+  onOpenChange,
+  onSelect,
+  side = 'bottom',
+  align = 'start',
+  id,
+  ariaLabel,
+  htmlProps,
+  animation,
+}: DropdownProps) {
+  const [open, setOpen] = useControllable(controlledOpen, defaultOpen, onOpenChange);
+  const [path, setPath] = useState<string[]>([]);
+  const [seed, setSeed] = useState({ key: ROOT_LEVEL, focus: 'first' as SeedFocus });
+
+  const refs = useRef(new Map<string, RefObject<HTMLElement>>());
+  const hoverDepth = useRef(-1);
+  const autoId = useId();
+  const menuId = id || 'dropdown-' + autoId;
+  const timings = resolveMotionTiming(animation, DROPDOWN_TIMING);
+  const levels = useMemo(() => resolveLevels(items, path), [items, path]);
+
+  const refFor = (key: string): RefObject<HTMLElement> => {
+    if (!refs.current.has(key)) refs.current.set(key, { current: null });
+    return refs.current.get(key)!;
+  };
+  const triggerRef = refFor('trigger');
+
+  const dismiss = (returnFocus: boolean) => {
+    setPath([]);
+    hoverDepth.current = -1;
+    setOpen(false);
+    if (returnFocus && triggerRef.current) triggerRef.current.focus();
+  };
+
+  const show = (focus: SeedFocus) => {
+    setSeed({ key: ROOT_LEVEL, focus });
+    setPath([]);
+    setOpen(true);
+  };
+
+  const chain: MenuChain = {
+    levels,
+    menuId,
+    activateOn,
+    side,
+    align,
+    ariaLabel,
+    htmlProps,
+    seed,
+    hoverDepth,
+    refFor,
+    dismiss,
+    openSub: (depth, item, focus) => {
+      setSeed({ key: levelKey(depth + 1, item.id), focus });
+      setPath([...path.slice(0, depth), item.id]);
+    },
+    closeSub: (depth) => {
+      if (path.length > depth) setPath(path.slice(0, depth));
+    },
+    cancel: (depth) => {
+      if (depth === 0) return dismiss(true);
+      setPath(path.slice(0, depth - 1));
+      const owner = refFor('row:' + levelKey(depth - 1, levels[depth].owner!.id)).current;
+      if (owner) owner.focus();
+    },
+    select: (item) => {
+      if (item.onSelect) item.onSelect();
+      if (onSelect) onSelect(item.id, item);
+      dismiss(true);
+    },
+  };
+
+  return (
+    <Fragment>
+      {ovCloneTrigger(trigger, {
+        open,
+        onPress: () => (open ? dismiss(false) : show('first')),
+        onKeyDown: (e) => {
+          if (open || (e.key !== 'ArrowDown' && e.key !== 'ArrowUp')) return;
+          e.preventDefault();
+          show(e.key === 'ArrowDown' ? 'first' : 'last');
+        },
+        panelId: menuId,
+        haspopup: 'menu',
+        triggerRef,
+        activateOn,
+      })}
+      <OverlayPortal>
+        <Presence>
+          {open &&
+            levels.map((level, depth) => (
+              <MenuPanel
+                key={level.key}
+                chain={chain}
+                depth={depth}
+                animate={popIn(UIMotion.scale.floating, timings.open)}
+                exit={popOut(UIMotion.scale.floating, timings.close)}
+              />
+            ))}
+        </Presence>
+      </OverlayPortal>
+    </Fragment>
+  );
+}

package/src/components/composites/dropdown/Dropdown.usage.md

@@ -0,0 +1,19 @@
+# Dropdown - @zyncat/ui/dropdown
+
+Group: overlays
+Docs: https://ui.zyncat.app/dropdown
+
+Menu button - a list of ACTIONS the trigger commits, with submenus.
+
+NOT a Select: it runs a command instead of holding a value, so there is no selected state and no
+form value. items takes DropdownItem[] or DropdownGroup[] (labelled sections); a row with its own
+items opens a submenu, nesting as deep as you like. Keyboard is the APG menu button: arrows move,
+Right/Left open and close a submenu, Enter/Space commit, typeahead, Esc one level, Tab the lot.
+
+```tsx
+<Dropdown trigger={<Button variant="secondary">Actions</Button>} onSelect={(id) => run(id)} items={[
+  { id: 'rename', label: 'Rename', shortcut: 'R' },
+  { id: 'move', label: 'Move to', items: [{ id: 'drafts', label: 'Drafts' }] },
+  { id: 'delete', label: 'Delete', danger: true }]} />
+<Dropdown open={o} onOpenChange={setO} side="top" align="end" ariaLabel="Row actions" trigger={<Button>...</Button>} items={groups} />
+```

package/src/components/composites/dropdown/dropdown.css

@@ -0,0 +1,65 @@
+@layer zyncat.tokens, zyncat.components;
+
+@layer zyncat.components {
+  /* Dropdown deltas on top of the shared menu surface (internal/menu/menu-surface.css):
+   group dividers and the row states a listbox has no use for. */
+
+  .dropdown__menu {
+    --menu-max-width: min(20rem, 92vw);
+    --menu-max-height: min(26rem, 70vh);
+    min-width: 11rem;
+  }
+
+  .dropdown__menu[data-danger-active='true'] {
+    --menu-glide-fill: var(--danger-wash);
+  }
+
+  .dropdown__group + .dropdown__group {
+    border-top: var(--border-hairline) solid var(--border-subtle);
+    margin-top: var(--space-1);
+    padding-top: var(--space-1);
+  }
+
+  .dropdown__item {
+    transition: color var(--duration-fast) var(--ease-standard);
+  }
+  .dropdown__item[data-active='true'] {
+    color: var(--text-strong);
+  }
+
+  .dropdown__item[data-danger='true'],
+  .dropdown__item[data-danger='true'][data-active='true'] {
+    color: var(--danger-text);
+  }
+  .dropdown__item[data-danger='true'] .menu-row__icon {
+    color: var(--danger);
+  }
+
+  .dropdown__item[data-disabled='true'] {
+    cursor: not-allowed;
+    color: var(--text-disabled);
+  }
+  .dropdown__item[data-disabled='true'] .menu-row__icon,
+  .dropdown__item[data-disabled='true'] .dropdown__item-shortcut,
+  .dropdown__item[data-disabled='true'] .menu-row__desc,
+  .dropdown__item[data-disabled='true'] .dropdown__item-caret {
+    color: var(--text-disabled);
+  }
+
+  .dropdown__item-caret {
+    flex: 0 0 auto;
+    color: var(--text-subtle);
+  }
+  .dropdown__item[data-active='true'] .menu-row__icon,
+  .dropdown__item[data-active='true'] .dropdown__item-caret {
+    color: var(--text-body);
+  }
+
+  .dropdown__item-shortcut {
+    flex: 0 0 auto;
+    font: var(--type-mono);
+    font-variant-numeric: tabular-nums;
+    color: var(--text-subtle);
+    padding-left: var(--space-2);
+  }
+}

package/src/components/composites/dropdown/menu-panel.tsx

@@ -0,0 +1,255 @@
+'use client';
+
+import '../../internal/menu/menu-surface.css';
+
+import { useEffect, useLayoutEffect, useMemo, useRef, useState, type KeyboardEvent, type RefObject } from 'react';
+
+import { GlidePill, useGlide } from '../../../motion/glide';
+import { useMotion, type MotionSpecs } from '../../../motion/use-motion';
+import { edgeEnabled, matchPrefix, stepEnabled } from '../../internal/collection/collection';
+import { useTypeahead } from '../../internal/hooks/use-typeahead';
+import { Icon } from '../../internal/icon/Icon';
+import { MenuRow } from '../../internal/menu/menu-row';
+import { useReturnFocus } from '../../internal/overlay/focus';
+import { useOutsidePress, useOverlayEntry } from '../../internal/overlay/layer';
+import { useAnchorPosition } from '../../internal/overlay/position';
+import { activationProps } from '../../internal/utils/activation';
+import { cx } from '../../internal/utils/cx';
+import { itemText, levelKey, normalize, submenuOf, type DropdownItem, type MenuChain } from './types';
+
+const SUBMENU_OPEN_DELAY = 90;
+const SUBMENU_TRAVEL_GRACE = 500;
+const MENU_KEYS = new Set('ArrowDown ArrowUp ArrowLeft ArrowRight Home End Enter Escape Tab'.split(' ').concat(' '));
+
+type Point = { x: number; y: number };
+
+/* Is the pointer inside the wedge from `from` to the submenu's near edge - travelling toward it
+   diagonally - rather than simply leaving the row? */
+function headingTo(point: Point, from: Point, panel: HTMLElement): boolean {
+  const box = panel.getBoundingClientRect();
+  const rightward = from.x <= box.left;
+  const gone = rightward ? point.x - from.x : from.x - point.x;
+  if (!box.width || gone <= 0) return false;
+  const reached = Math.min(gone / Math.max(rightward ? box.left - from.x : from.x - box.right, 1), 1);
+  const [a, b] = [from.y + (box.top - from.y) * reached, from.y + (box.bottom - from.y) * reached];
+  return point.y >= Math.min(a, b) && point.y <= Math.max(a, b);
+}
+
+export function MenuPanel({ chain, depth, ...motion }: { chain: MenuChain; depth: number } & MotionSpecs) {
+  const { levels, hoverDepth, refFor } = chain;
+  const [level, next, parent] = [levels[depth], levels[depth + 1], levels[depth - 1]];
+  const nested = Boolean(parent);
+
+  const panelId = (d: number) =>
+    d === 0 ? chain.menuId : chain.menuId + '-' + d + '-' + encodeURIComponent(levels[d].owner!.id);
+  const menuId = panelId(depth);
+  const openSubId = next ? next.owner!.id : null;
+  const seed = chain.seed.key === level.key ? chain.seed.focus : 'none';
+
+  const { groups, flat } = useMemo(() => normalize(level.items), [level.items]);
+  const indexOf = useMemo(() => new Map(flat.map((item, i) => [item.id, i] as const)), [flat]);
+  const [activeIdx, setActiveIdx] = useState(() => (seed === 'none' ? -1 : edgeEnabled(flat, seed === 'last')));
+
+  const panelRef = refFor('panel:' + level.key);
+  const rowFor = (i: number) => refFor('row:' + levelKey(depth, flat[i].id)) as unknown as RefObject<HTMLDivElement>;
+  const anchorRef = nested ? refFor('row:' + levelKey(depth - 1, level.owner!.id)) : refFor('trigger');
+
+  const glide = useGlide(panelRef);
+  const typeahead = useTypeahead();
+  const timers = useRef<Record<'open' | 'grace', ReturnType<typeof setTimeout> | 0>>({ open: 0, grace: 0 });
+  const travel = useRef({ from: null as Point | null, active: false, hovered: -1 });
+
+  const openIdx = openSubId != null ? (indexOf.get(openSubId) ?? -1) : -1;
+  const activeItem = activeIdx >= 0 ? flat[activeIdx] : undefined;
+  const cancel = () => chain.cancel(depth);
+  const closeSub = () => chain.closeSub(depth);
+
+  const entry = useOverlayEntry({ nodeRef: panelRef, dismissible: true, requestClose: cancel });
+  const place = { side: nested ? 'right' : chain.side, align: nested ? 'start' : chain.align } as const;
+  useMotion(panelRef, motion);
+  useReturnFocus(panelRef);
+  useAnchorPosition({ ...place, arrow: false, triggerRef: anchorRef, panelRef });
+  useOutsidePress({ entry, refs: [panelRef, anchorRef], enabled: !nested, onPress: () => chain.dismiss(false) });
+
+  useLayoutEffect(() => {
+    const row = activeIdx >= 0 && activeIdx < flat.length ? rowFor(activeIdx).current : null;
+    if (!row) return glide.leave();
+    row.focus();
+    glide.enter(row);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [activeIdx]);
+
+  useLayoutEffect(() => {
+    if (seed !== 'none') setActiveIdx(edgeEnabled(flat, seed === 'last'));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [seed]);
+
+  useEffect(() => () => stopTravel(), []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  function stopTravel() {
+    clearTimeout(timers.current.open);
+    clearTimeout(timers.current.grace);
+    travel.current.active = false;
+  }
+
+  function armOpen(i: number) {
+    clearTimeout(timers.current.open);
+    const item = flat[i];
+    if (!item || item.disabled || item.id === openSubId || !submenuOf(item)) return;
+    timers.current.open = setTimeout(() => chain.openSub(depth, item, 'none'), SUBMENU_OPEN_DELAY);
+  }
+
+  const heading = (point: Point) => {
+    const sub = next && refFor('panel:' + next.key).current;
+    return Boolean(sub && travel.current.from && headingTo(point, travel.current.from, sub));
+  };
+
+  function abortTravel() {
+    stopTravel();
+    closeSub();
+    const i = travel.current.hovered;
+    if (i >= 0 && i < flat.length && !flat[i].disabled) {
+      setActiveIdx(i);
+      armOpen(i);
+    }
+  }
+
+  function moveTo(i: number) {
+    stopTravel();
+    if (i < 0 || i >= flat.length) return;
+    setActiveIdx(i);
+    if (openIdx >= 0 && flat[i].id !== openSubId) closeSub();
+  }
+
+  function commit(item: DropdownItem | undefined) {
+    if (!item || item.disabled) return;
+    if (submenuOf(item)) chain.openSub(depth, item, 'first');
+    else chain.select(item);
+  }
+
+  function onRowEnter(point: Point, i: number) {
+    if (flat[i].disabled) return;
+    travel.current.hovered = i;
+    if (i === openIdx) {
+      stopTravel();
+      return setActiveIdx(i);
+    }
+    if (openIdx >= 0 && heading(point)) {
+      stopTravel();
+      travel.current.active = true;
+      timers.current.grace = setTimeout(() => hoverDepth.current <= depth && abortTravel(), SUBMENU_TRAVEL_GRACE);
+      return;
+    }
+    setActiveIdx(i);
+    if (openIdx >= 0) closeSub();
+    armOpen(i);
+  }
+
+  function onKeyDown(e: KeyboardEvent<HTMLDivElement>) {
+    const printable = e.key.length === 1 && !e.metaKey && !e.ctrlKey && !e.altKey;
+    if (!MENU_KEYS.has(e.key) && !printable) return;
+    e.stopPropagation();
+    if (printable && (e.key !== ' ' || typeahead.buffered())) {
+      const i = matchPrefix(flat, itemText, typeahead.push(e.key));
+      return i >= 0 ? moveTo(i) : undefined;
+    }
+    e.preventDefault();
+    const back = () => (openSubId != null ? closeSub() : cancel());
+    const opens = activeItem && !activeItem.disabled && submenuOf(activeItem);
+    switch (e.key) {
+      case 'ArrowDown':
+        return moveTo(stepEnabled(flat, activeIdx, 1));
+      case 'ArrowUp':
+        return moveTo(stepEnabled(flat, activeIdx, -1));
+      case 'Home':
+        return moveTo(edgeEnabled(flat, false));
+      case 'End':
+        return moveTo(edgeEnabled(flat, true));
+      case 'ArrowRight':
+        return opens ? chain.openSub(depth, activeItem!, 'first') : undefined;
+      case 'ArrowLeft':
+        return openSubId == null && !nested ? undefined : back();
+      case 'Escape':
+        return back();
+      case 'Tab':
+        return chain.dismiss(true);
+      default:
+        return commit(activeItem);
+    }
+  }
+
+  function renderRow(item: DropdownItem) {
+    const i = indexOf.get(item.id) ?? -1;
+    const sub = submenuOf(item);
+    const subOpen = sub != null && openSubId === item.id;
+    return (
+      <MenuRow
+        key={item.id}
+        ref={rowFor(i)}
+        id={menuId + '-item-' + i}
+        className="dropdown__item"
+        role="menuitem"
+        tabIndex={i === activeIdx ? 0 : -1}
+        aria-disabled={item.disabled || undefined}
+        aria-haspopup={sub ? 'menu' : undefined}
+        aria-expanded={sub ? subOpen : undefined}
+        aria-controls={subOpen ? panelId(depth + 1) : undefined}
+        aria-keyshortcuts={item.shortcut}
+        data-active={i === activeIdx ? 'true' : undefined}
+        data-disabled={item.disabled ? 'true' : undefined}
+        data-danger={item.danger ? 'true' : undefined}
+        onPointerEnter={(e) => onRowEnter({ x: e.clientX, y: e.clientY }, i)}
+        onPointerLeave={(e) => {
+          clearTimeout(timers.current.open);
+          if (i === openIdx) travel.current.from = { x: e.clientX, y: e.clientY };
+        }}
+        {...activationProps<HTMLDivElement>(() => commit(item), { on: chain.activateOn, holdFocus: true })}
+        icon={item.icon}
+        label={item.label}
+        description={item.description}
+        trailing={
+          <>
+            {item.shortcut && (
+              <span className="dropdown__item-shortcut" aria-hidden="true">
+                {item.shortcut}
+              </span>
+            )}
+            {sub && <Icon name="caret-right" size="sm" className="dropdown__item-caret" />}
+          </>
+        }
+      />
+    );
+  }
+
+  return (
+    <div
+      {...(nested ? undefined : chain.htmlProps)}
+      ref={panelRef as unknown as RefObject<HTMLDivElement>}
+      id={menuId}
+      className={cx('menu-surface menu-scroller dropdown__menu', !nested && chain.htmlProps?.className)}
+      role="menu"
+      tabIndex={-1}
+      aria-label={nested ? undefined : chain.ariaLabel}
+      aria-labelledby={nested ? panelId(depth - 1) + '-item-' + level.ownerIdx : undefined}
+      data-nested={nested ? 'true' : undefined}
+      data-danger-active={activeItem && activeItem.danger ? 'true' : undefined}
+      onKeyDown={onKeyDown}
+      onPointerEnter={() => {
+        if (hoverDepth.current > depth) travel.current.from = null;
+        hoverDepth.current = depth;
+        stopTravel();
+      }}
+      onPointerMove={(e) => travel.current.active && !heading({ x: e.clientX, y: e.clientY }) && abortTravel()}
+    >
+      <GlidePill className="menu-glide" glide={glide} />
+      {groups.length > 1 || groups[0]?.label
+        ? groups.map((group, gi) => (
+            <div className="dropdown__group" role="group" aria-label={group.label || undefined} key={gi}>
+              {group.label && <div className="menu-group-label">{group.label}</div>}
+              {group.items.map(renderRow)}
+            </div>
+          ))
+        : flat.map(renderRow)}
+    </div>
+  );
+}

package/src/components/composites/dropdown/types.ts

@@ -0,0 +1,95 @@
+import type { HTMLAttributes, ReactNode, RefObject } from 'react';
+
+import type { DataAttributes } from '../../../dom-props';
+import { normalizeCollection, type NormalizedGroup } from '../../internal/collection/collection';
+import type { ActivateOn } from '../../internal/utils/activation';
+
+export interface DropdownItem {
+  /** Unique id - what `onSelect` receives, and what identifies this row's open submenu. */
+  id: string;
+  /** Primary row text. */
+  label: ReactNode;
+  /** Optional secondary line under the label. */
+  description?: string;
+  /** Your own icon node shown before the label. */
+  icon?: ReactNode;
+  /** Keyboard hint shown at the trailing edge, mono. Display only - you still bind the key. */
+  shortcut?: string;
+  /** Destructive action - the row reads in the danger hue. @default false */
+  danger?: boolean;
+  /** Not selectable - skipped by arrow keys and typeahead, and marked `aria-disabled`. @default false */
+  disabled?: boolean;
+  /** Nested menu. The row opens it instead of committing, and can nest again without limit. */
+  items?: DropdownItem[] | DropdownGroup[];
+  /** Text used for typeahead. Required when `label` is not a string. */
+  searchText?: string;
+  /** Fires when this row commits, before the menu's own `onSelect`. */
+  onSelect?: () => void;
+}
+
+export interface DropdownGroup {
+  /** Section heading rendered above the rows; omit for an unlabeled but still divided group. */
+  label?: string;
+  /** The rows in this section. */
+  items: DropdownItem[];
+}
+
+export type DropdownItems = DropdownItem[] | DropdownGroup[];
+
+export const normalize = (source: DropdownItems): { groups: NormalizedGroup<DropdownItem>[]; flat: DropdownItem[] } =>
+  normalizeCollection<DropdownItem, DropdownGroup>(source, {
+    isGroup: (entry): entry is DropdownGroup => !('id' in entry),
+    itemsOf: (group) => group.items,
+    labelOf: (group) => group.label,
+  });
+
+export const itemText = (item: DropdownItem): string =>
+  item.searchText ?? (typeof item.label === 'string' ? item.label : item.id);
+
+export const submenuOf = (item: DropdownItem): DropdownItems | null =>
+  item.items && item.items.length > 0 ? item.items : null;
+
+export const ROOT_LEVEL = 'root';
+export const levelKey = (depth: number, ownerId: string) => depth + ':' + ownerId;
+
+export interface Level {
+  key: string;
+  items: DropdownItems;
+  owner: DropdownItem | null;
+  ownerIdx: number;
+}
+
+/* The open chain, root first: path[d] names the row in level d whose submenu is level d + 1. */
+export function resolveLevels(items: DropdownItems, path: string[]): Level[] {
+  const levels: Level[] = [{ key: ROOT_LEVEL, items, owner: null, ownerIdx: -1 }];
+  for (const id of path) {
+    const { flat } = normalize(levels[levels.length - 1].items);
+    const ownerIdx = flat.findIndex((item) => item.id === id);
+    const sub = ownerIdx >= 0 && submenuOf(flat[ownerIdx]);
+    if (!sub) break;
+    levels.push({ key: levelKey(levels.length, id), items: sub, owner: flat[ownerIdx], ownerIdx });
+  }
+  return levels;
+}
+
+export type SeedFocus = 'first' | 'last' | 'none';
+
+/* Everything a level needs to render itself and act on the chain. One object, built once by
+   Dropdown, so a panel takes its place in the chain rather than twenty separate props. */
+export interface MenuChain {
+  levels: Level[];
+  menuId: string;
+  activateOn?: ActivateOn;
+  side: 'top' | 'bottom' | 'left' | 'right';
+  align: 'start' | 'center' | 'end';
+  ariaLabel?: string;
+  htmlProps?: HTMLAttributes<HTMLDivElement> & DataAttributes;
+  seed: { key: string; focus: SeedFocus };
+  hoverDepth: { current: number };
+  refFor: (key: string) => RefObject<HTMLElement>;
+  openSub: (depth: number, item: DropdownItem, focus: SeedFocus) => void;
+  closeSub: (depth: number) => void;
+  cancel: (depth: number) => void;
+  dismiss: (returnFocus: boolean) => void;
+  select: (item: DropdownItem) => void;
+}