@pindoba/astro-menu 0.0.0-alpha-20260829223243

package/src/__test__/runtime.test.ts

@@ -0,0 +1,57 @@
+// @vitest-environment happy-dom
+import { describe, it, expect, beforeEach } from "vitest";
+import { getMenu, type MenuHandle, type MenuRootElement } from "../runtime.js";
+
+/**
+ * `getMenu` is the documented consumer entry point for driving an Astro menu
+ * imperatively (`getMenu(root)?.open()`), so it has to be safe to call against
+ * anything a consumer might hand it — including a root that has not booted yet
+ * and a nullable `querySelector` result.
+ */
+
+function makeHandle(): MenuHandle {
+  return {
+    open: () => {},
+    close: () => {},
+    toggle: () => {},
+    isOpen: () => false,
+    setRadioValue: () => {},
+    getRadioValue: () => undefined,
+    destroy: () => {},
+  };
+}
+
+let root: MenuRootElement;
+
+beforeEach(() => {
+  document.body.innerHTML = "";
+  root = document.createElement("div");
+  document.body.appendChild(root);
+});
+
+describe("getMenu", () => {
+  it("returns the handle a booted root carries", () => {
+    const handle = makeHandle();
+    root.menu = handle;
+    expect(getMenu(root)).toBe(handle);
+  });
+
+  it("returns null for a root that has not booted", () => {
+    // The boot may not have run yet (module order, an early script), and the
+    // consumer must get null rather than a crash.
+    expect(getMenu(root)).toBeNull();
+  });
+
+  it("returns null for null and undefined", () => {
+    // `getMenu(document.querySelector("…"))` is the documented call shape, and
+    // that returns null when the selector misses.
+    expect(getMenu(null)).toBeNull();
+    expect(getMenu(undefined)).toBeNull();
+  });
+
+  it("returns null again once the menu is destroyed", () => {
+    root.menu = makeHandle();
+    delete root.menu;
+    expect(getMenu(root)).toBeNull();
+  });
+});

package/src/boot-menu.ts

@@ -0,0 +1,598 @@
+/**
+ * Client controller for the Astro Menu — the vanilla-DOM translation of
+ * `menu.svelte` + `menu-level.svelte` + `menu-context.svelte.ts`.
+ *
+ * Astro has no client reactivity framework, so this rebuilds the interaction
+ * model by hand from the `data-menu-config` payload `menu.astro` serialized:
+ *
+ *  - a cross-level open PATH (root→leaf submenu ids),
+ *  - the root Popover driven by a click trigger,
+ *  - submenu Popovers opened/closed imperatively (open-driven, never torn down),
+ *  - safe-triangle pointer gating with a 300ms grace,
+ *  - hover opens a submenu / hovering a sibling closes it (unless the triangle
+ *    still defers),
+ *  - capture-phase scroll closes the open submenu,
+ *  - keyboard: list nav delegated to each level's self-booting ListBox
+ *    (roving), while ArrowRight/ArrowLeft/Escape are scoped here with
+ *    stopPropagation,
+ *  - explicit first-row focus on open (retry + preventScroll — native dialog
+ *    autofocus is disabled and every menu row is `tabindex -1`),
+ *  - activation dispatched as `pindoba:menu:*` CustomEvents (no callbacks).
+ */
+import {
+  createPopover,
+  type HeadlessPopover,
+  type Placement,
+} from "@pindoba/core-popover";
+import {
+  createSubmenuAimTracker,
+  type Point,
+  type Rect,
+  type SubmenuSide,
+} from "@pindoba/core-menu";
+import { isSectionInput, type ListBoxNodeInput } from "@pindoba/core-listbox";
+import type { ListBoxRootElement } from "@pindoba/astro-listbox/boot-listbox";
+import type {
+  MenuConfig,
+  MenuHandle,
+  MenuLevelConfig,
+  MenuRootElement,
+  MenuSubmenuRef,
+} from "./runtime";
+
+export interface BootResult {
+  destroy: () => void;
+}
+
+type MenuConfigWithOpen = MenuConfig & { open?: boolean };
+
+// The dialog instance type, derived from the popover's own `setDialog` signature
+// so we don't need a direct dependency on `@pindoba/core-dialog`.
+type DialogInstance = Parameters<HeadlessPopover["setDialog"]>[0];
+
+declare global {
+  interface Window {
+    __PindobaDialogManager?: {
+      getInstance(dialogId: string): DialogInstance;
+    };
+  }
+}
+
+function waitForManager(): Promise<
+  NonNullable<Window["__PindobaDialogManager"]>
+> {
+  if (window.__PindobaDialogManager) {
+    return Promise.resolve(window.__PindobaDialogManager);
+  }
+  return new Promise((resolve) => {
+    document.addEventListener(
+      "pindoba:dialog-manager-ready",
+      () => resolve(window.__PindobaDialogManager!),
+      { once: true },
+    );
+  });
+}
+
+interface LevelRuntime {
+  cfg: MenuLevelConfig;
+  popover: HeadlessPopover;
+}
+
+/**
+ * Wire one server-rendered menu. `triggerEl` carries the `data-menu-config`
+ * payload; the popovers/listboxes are found by their serialized ids.
+ */
+export function bootMenu(triggerEl: HTMLElement): BootResult | null {
+  if (triggerEl.hasAttribute("data-menu-initialized")) return null;
+
+  // Ownership checks come BEFORE any mutation: every framework's menu trigger
+  // carries `data-menu-trigger` (from the shared core bag), and pages can mix
+  // frameworks — marking or wiring a foreign (React/Vue/Svelte) trigger causes
+  // hydration mismatches and steals their interactions.
+  let config: MenuConfigWithOpen;
+  try {
+    config = JSON.parse(
+      triggerEl.getAttribute("data-menu-config") || "{}",
+    ) as MenuConfigWithOpen;
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(config.levels)) return null;
+
+  const root = triggerEl.closest<HTMLElement>("[data-pindoba-menu]");
+  if (!root) return null;
+
+  triggerEl.setAttribute("data-menu-initialized", "true");
+
+  const side: SubmenuSide = config.side ?? "right";
+  const ac = new AbortController();
+  const { signal } = ac;
+
+  // --- Cross-level state (mirrors menu.svelte) ------------------------------
+  let openPath: string[] = [];
+  // Safe-triangle bookkeeping — the shared core tracker.
+  const aimTracker = createSubmenuAimTracker();
+
+  // Checkbox / radio state lives here; the server render seeded the initial
+  // aria-checked. Toggles are written back into each level ListBox's own items
+  // (via its `setItems` handle), so the pattern-aware boot keeps rendering the
+  // correct aria-checked on every internal re-render.
+  const checkedState = new Map<string, boolean>();
+  const radioState = new Map<string, string>(
+    Object.entries(config.radioInitial ?? {}),
+  );
+  for (const [id, meta] of Object.entries(config.nodeIndex)) {
+    if (meta.type === "checkbox") checkedState.set(id, meta.checked);
+  }
+
+  // --- Popover per level ----------------------------------------------------
+  const levels: LevelRuntime[] = [];
+  const byId = new Map<string, LevelRuntime>();
+  let rootRuntime: LevelRuntime | null = null;
+
+  for (const cfg of config.levels) {
+    const dialogEl = document.getElementById(
+      cfg.popoverId,
+    ) as HTMLDialogElement | null;
+
+    const isRoot = cfg.id === null;
+    const popover = createPopover(
+      isRoot
+        ? {
+            id: cfg.popoverId,
+            placement: config.placement as Placement,
+            triggerStrategy: "click",
+            anchorElement: triggerEl,
+            autoFocus: false,
+            minWidthReference: true,
+          }
+        : {
+            id: cfg.popoverId,
+            placement: "right-start",
+            triggerStrategy: "manual",
+            autoFocus: false,
+            // A small positive mainAxis tucks the submenu under the parent
+            // panel edge; the negative crossAxis lifts its first row to align
+            // with the trigger row (see connect-menu). Per-depth z-index keeps
+            // a nested non-modal dialog above the panel it overlaps.
+            positionOffset: { mainAxis: 2, crossAxis: -8 },
+            zIndex: 10000 + cfg.depth,
+          },
+    );
+
+    if (dialogEl) {
+      // Relocate the non-modal dialog out of any clipping subtree (mirrors
+      // usePopover / boot-select). Prefer <body>; nest into an ancestor only
+      // when it's a MODAL <dialog> so a menu inside a modal isn't occluded
+      // behind it — never a non-modal ancestor whose clip would clip the menu.
+      if (dialogEl.dataset.isModal === "false") {
+        const target =
+          dialogEl.parentElement?.closest(
+            'dialog:modal, dialog[data-is-modal="true"]',
+          ) ?? document.body;
+        if (dialogEl.parentElement !== target) target.appendChild(dialogEl);
+      }
+      popover.setDialogElement(dialogEl);
+    }
+    if (isRoot) popover.setTriggerElement(triggerEl);
+
+    void waitForManager().then((manager) => {
+      const instance = manager.getInstance(cfg.popoverId);
+      if (instance) popover.setDialog(instance);
+    });
+
+    const rt: LevelRuntime = { cfg, popover };
+    levels.push(rt);
+    if (isRoot) rootRuntime = rt;
+    else byId.set(cfg.id as string, rt);
+  }
+
+  if (!rootRuntime) {
+    // A level-less payload is a render bug, but bailing here happens *after* the
+    // per-level popovers were built — leaving them alive would keep their
+    // Floating UI autoUpdate loops and dialog listeners running forever. Unmark
+    // the trigger too, so a corrected re-render can still boot.
+    ac.abort();
+    for (const rt of levels) rt.popover.destroy();
+    triggerEl.removeAttribute("data-menu-initialized");
+    return null;
+  }
+  const rootPopover = rootRuntime.popover;
+
+  // The submenu dialogs are "inside" the root's outside-click boundary (they
+  // portal outside its subtree). Additive `insideElements` on the core popover.
+  const submenuDialogEls = config.levels
+    .filter((l) => l.id !== null)
+    .map((l) => document.getElementById(l.popoverId))
+    .filter((el): el is HTMLElement => el != null);
+  rootPopover.setInsideElements(submenuDialogEls);
+
+  // --- Helpers --------------------------------------------------------------
+  function emit(type: string, detail: Record<string, unknown>) {
+    root!.dispatchEvent(new CustomEvent(type, { detail, bubbles: true }));
+  }
+
+  function focusFirstRow(menuId: string, attempts = 10) {
+    const first = document
+      .getElementById(menuId)
+      ?.querySelector<HTMLElement>("[data-key]");
+    if (first) {
+      first.focus({ preventScroll: true });
+      if (document.activeElement === first) return;
+    }
+    if (attempts > 0) {
+      requestAnimationFrame(() => focusFirstRow(menuId, attempts - 1));
+    }
+  }
+
+  function focusSubmenuFirstItem(subId: string, attempts = 10) {
+    const dialog = document.getElementById(`${subId}-popover`);
+    const first = dialog?.querySelector<HTMLElement>("[data-key]");
+    if (first) {
+      first.focus({ preventScroll: true });
+      if (document.activeElement === first) return;
+    }
+    if (attempts > 0) {
+      requestAnimationFrame(() => focusSubmenuFirstItem(subId, attempts - 1));
+    }
+  }
+
+  /** Open every submenu whose id is in the path; close the rest. */
+  function reconcile() {
+    for (const rt of levels) {
+      if (rt.cfg.id === null) continue;
+      const want = openPath.includes(rt.cfg.id);
+      if (want) {
+        // Anchor re-resolved per open (the parent row is guaranteed rendered).
+        if (rt.cfg.parentTriggerItemId) {
+          rt.popover.setAnchorElement(
+            document.getElementById(rt.cfg.parentTriggerItemId),
+          );
+        }
+        if (!rt.popover.$open.get()) rt.popover.$open.set(true);
+      } else if (rt.popover.$open.get()) {
+        rt.popover.$open.set(false);
+      }
+    }
+  }
+
+  function openSubmenu(
+    id: string,
+    parentId: string | null,
+    via: "pointer" | "keyboard" = "pointer",
+    /** The submenu's instance-unique id (desc.qualifiedId) for DOM lookups. */
+    qualifiedId?: string,
+  ) {
+    if (openPath.includes(id)) return;
+    const prevActive = document.activeElement as HTMLElement | null;
+    if (parentId == null) {
+      openPath = [id];
+    } else {
+      const idx = openPath.indexOf(parentId);
+      openPath =
+        idx === -1 ? [parentId, id] : [...openPath.slice(0, idx + 1), id];
+    }
+    reconcile();
+    // A pointer open must not move focus. The native `<dialog>.show()` may still
+    // focus the dialog itself; if it did, put focus back — scroll untouched.
+    if (via === "pointer" && prevActive && prevActive !== document.body) {
+      requestAnimationFrame(() => {
+        const dialog = document.getElementById(`${qualifiedId ?? id}-popover`);
+        const active = document.activeElement;
+        if (
+          dialog &&
+          active &&
+          (dialog === active || dialog.contains(active))
+        ) {
+          prevActive.focus({ preventScroll: true });
+        }
+      });
+    }
+  }
+
+  function closeSubmenu(id: string) {
+    const idx = openPath.indexOf(id);
+    if (idx === -1) return;
+    openPath = openPath.slice(0, idx);
+    reconcile();
+  }
+
+  function closeRoot() {
+    rootPopover.$open.set(false);
+  }
+
+  function trackPointer(pointer: Point, rect: Rect) {
+    aimTracker.trackPointer(pointer, rect, side);
+  }
+
+  function shouldDeferSiblingHover() {
+    return aimTracker.shouldDeferSiblingHover();
+  }
+
+  /** The key of the roving-focused row inside a level's list, if any. */
+  function activeRowKey(menuId: string): string | null {
+    const ul = document.getElementById(menuId);
+    const active = document.activeElement;
+    if (!ul || !(active instanceof HTMLElement)) return null;
+    const row = active.closest<HTMLElement>("[data-key]");
+    if (row && ul.contains(row)) return row.dataset.key ?? null;
+    return null;
+  }
+
+  /** What `checked` should be for a node, per the live toggle state. */
+  function desiredChecked(key: string): boolean | undefined {
+    const meta = config.nodeIndex[key];
+    if (meta?.type === "checkbox") return Boolean(checkedState.get(key));
+    if (meta?.type === "radio")
+      return radioState.get(meta.groupId) === meta.value;
+    return undefined;
+  }
+
+  // Each level ListBox's own items (parsed once from its config blob) — the
+  // source the pattern-aware boot renders aria-checked/data-checked from.
+  const levelItems = new Map<string, ListBoxNodeInput[]>();
+
+  /**
+   * Write the toggle state into a level's items and re-feed its ListBox.
+   * Returns whether the repaint actually happened — `false` means the level's
+   * ListBox hasn't booted yet (see `setRadioValue`, which retries).
+   */
+  function syncChecks(lvl: MenuLevelConfig): boolean {
+    const ul = document.getElementById(lvl.menuId) as ListBoxRootElement | null;
+    const lb = ul?.listbox;
+    if (!ul || !lb) return false;
+    let items = levelItems.get(lvl.menuId);
+    if (!items) {
+      try {
+        items = (
+          JSON.parse(ul.getAttribute("data-listbox-config") || "{}") as {
+            items?: ListBoxNodeInput[];
+          }
+        ).items;
+      } catch {
+        return false;
+      }
+      if (!Array.isArray(items)) return false;
+      levelItems.set(lvl.menuId, items);
+    }
+    const update = (nodes: ListBoxNodeInput[]) => {
+      for (const node of nodes) {
+        if (isSectionInput(node)) {
+          update(node.items);
+          continue;
+        }
+        const want = desiredChecked(String(node.id));
+        if (want !== undefined) {
+          (node as { checked?: boolean }).checked = want;
+        }
+      }
+    };
+    update(items);
+    lb.setItems(items);
+    return true;
+  }
+
+  // --- Activation (from each list's `listbox:action`) -----------------------
+  function onAction(lvl: MenuLevelConfig, key: string) {
+    const meta = config.nodeIndex[key];
+    if (!meta) return;
+    switch (meta.type) {
+      case "action":
+        emit("pindoba:menu:action", { id: key });
+        if (meta.closeOnSelect) closeRoot();
+        break;
+      case "link":
+        // Native <a> navigation already fired on the click / Enter.
+        closeRoot();
+        break;
+      case "checkbox": {
+        const next = !checkedState.get(key);
+        checkedState.set(key, next);
+        syncChecks(lvl);
+        emit("pindoba:menu:checkedchange", { id: key, checked: next });
+        if (meta.closeOnSelect) closeRoot();
+        break;
+      }
+      case "radio":
+        radioState.set(meta.groupId, meta.value);
+        syncChecks(lvl);
+        emit("pindoba:menu:valuechange", {
+          groupId: meta.groupId,
+          value: meta.value,
+        });
+        break;
+      case "submenu": {
+        const desc = lvl.submenus.find((s) => s.id === meta.subId);
+        openSubmenu(meta.subId, lvl.id, "keyboard", desc?.qualifiedId);
+        focusSubmenuFirstItem(desc?.qualifiedId ?? meta.subId);
+        break;
+      }
+    }
+  }
+
+  // --- Per-level DOM handlers (attached to each dialog) ----------------------
+  function openChildOf(lvl: MenuLevelConfig): MenuSubmenuRef | null {
+    for (const s of lvl.submenus) if (openPath.includes(s.id)) return s;
+    return null;
+  }
+
+  function closeSelf(lvl: MenuLevelConfig) {
+    if (lvl.id == null) return;
+    closeSubmenu(lvl.id);
+    if (lvl.parentTriggerItemId) {
+      document.getElementById(lvl.parentTriggerItemId)?.focus();
+    }
+  }
+
+  function onKeydown(lvl: MenuLevelConfig, event: KeyboardEvent) {
+    switch (event.key) {
+      case "ArrowRight": {
+        const focusedKey = activeRowKey(lvl.menuId);
+        const desc = lvl.submenus.find((s) => s.id === focusedKey);
+        if (desc) {
+          event.preventDefault();
+          event.stopPropagation();
+          openSubmenu(desc.id, lvl.id, "keyboard", desc.qualifiedId);
+          focusSubmenuFirstItem(desc.qualifiedId);
+        }
+        break;
+      }
+      case "ArrowLeft":
+        if (lvl.id != null) {
+          event.preventDefault();
+          event.stopPropagation();
+          closeSelf(lvl);
+        }
+        break;
+      case "Escape":
+        // Escape closes just the topmost level. stopPropagation prevents the
+        // native <dialog> cancel (which would desync state) and an ancestor
+        // level from closing on the same keystroke.
+        event.preventDefault();
+        event.stopPropagation();
+        if (lvl.id != null) closeSelf(lvl);
+        else closeRoot();
+        break;
+    }
+  }
+
+  function onPointerMove(lvl: MenuLevelConfig, event: PointerEvent) {
+    const openChild = openChildOf(lvl);
+    if (openChild) {
+      const dialog = document.getElementById(
+        `${openChild.qualifiedId}-popover`,
+      );
+      if (dialog) {
+        const r = dialog.getBoundingClientRect();
+        trackPointer(
+          { x: event.clientX, y: event.clientY },
+          { top: r.top, right: r.right, bottom: r.bottom, left: r.left },
+        );
+      }
+    }
+    const target = event.target as Element | null;
+    const el = target?.closest?.<HTMLElement>("[data-key]");
+    const key = el?.dataset.key;
+    if (!key) return;
+    const desc = lvl.submenus.find((s) => s.id === key);
+    if (desc) {
+      openSubmenu(desc.id, lvl.id, "pointer", desc.qualifiedId);
+    } else if (openChild && !shouldDeferSiblingHover()) {
+      closeSubmenu(openChild.id);
+    }
+  }
+
+  function onScroll(lvl: MenuLevelConfig) {
+    const openChild = openChildOf(lvl);
+    if (openChild) closeSubmenu(openChild.id);
+  }
+
+  // Attach handlers to every level's dialog + list.
+  for (const lvl of config.levels) {
+    const dialogEl = document.getElementById(lvl.popoverId);
+    const ul = document.getElementById(lvl.menuId);
+    if (dialogEl) {
+      dialogEl.addEventListener(
+        "keydown",
+        (e) => onKeydown(lvl, e as KeyboardEvent),
+        { capture: true, signal },
+      );
+      dialogEl.addEventListener(
+        "pointermove",
+        (e) => onPointerMove(lvl, e as PointerEvent),
+        { signal },
+      );
+      dialogEl.addEventListener("scroll", () => onScroll(lvl), {
+        capture: true,
+        signal,
+      });
+    }
+    if (ul) {
+      ul.addEventListener(
+        "listbox:action",
+        (e) => {
+          const key = (e as CustomEvent<{ key: string }>).detail?.key;
+          if (typeof key === "string") onAction(lvl, key);
+        },
+        { signal },
+      );
+    }
+  }
+
+  // --- Root open/close orchestration ----------------------------------------
+  const unsubOpen = rootPopover.$open.listen((isOpen) => {
+    triggerEl.setAttribute("aria-expanded", isOpen ? "true" : "false");
+    triggerEl.setAttribute("data-state", isOpen ? "open" : "closed");
+    if (isOpen) {
+      focusFirstRow(config.menuId);
+    } else {
+      if (openPath.length) {
+        openPath = [];
+        reconcile();
+      }
+      aimTracker.reset();
+    }
+    emit("pindoba:menu:openchange", { id: config.rootId, open: isOpen });
+  });
+
+  // Initial open (SSR `open` prop) — after wiring + manager readiness.
+  if (config.open) {
+    void waitForManager().then(() => rootPopover.$open.set(true));
+  }
+
+  // --- Handle + teardown ----------------------------------------------------
+  const destroy = () => {
+    ac.abort();
+    unsubOpen();
+    for (const rt of levels) rt.popover.destroy();
+    delete (root as MenuRootElement).menu;
+    // Allow a later re-boot (transition:persist islands re-run page-load).
+    triggerEl.removeAttribute("data-menu-initialized");
+  };
+
+  const handle: MenuHandle = {
+    open: () => rootPopover.$open.set(true),
+    close: () => rootPopover.$open.set(false),
+    toggle: () => rootPopover.$open.set(!rootPopover.$open.get()),
+    isOpen: () => rootPopover.$open.get(),
+    // Every level is repainted, not just the one holding the group: a radio
+    // group lives at exactly one level, but the caller doesn't know which, and
+    // `syncChecks` is a no-op for levels whose items don't carry the ids.
+    setRadioValue: (groupId, value) => {
+      radioState.set(groupId, value);
+      // Retried across frames: an owner restoring persisted state can call this
+      // before the level's ListBox has booted, and a dropped repaint would
+      // leave the panel showing the server-rendered value forever.
+      let tries = 0;
+      const paint = () => {
+        let allPainted = true;
+        for (const lvl of levels) {
+          if (!syncChecks(lvl.cfg)) allPainted = false;
+        }
+        if (!allPainted && tries++ < 15) requestAnimationFrame(paint);
+      };
+      paint();
+    },
+    getRadioValue: (groupId) => radioState.get(groupId),
+    destroy,
+  };
+  (root as MenuRootElement).menu = handle;
+
+  return { destroy };
+}
+
+/** Boot every server-rendered menu on the page. Returns teardown handles. */
+export function bootAllMenus(): BootResult[] {
+  // Scoped to astro-owned menu roots: other frameworks' triggers carry the
+  // same `data-menu-trigger` attribute (shared core bag) and must not be
+  // touched by this boot.
+  const triggers = document.querySelectorAll<HTMLElement>(
+    "[data-pindoba-menu] [data-menu-trigger]",
+  );
+  const results: BootResult[] = [];
+  for (const trigger of triggers) {
+    const result = bootMenu(trigger);
+    if (result) results.push(result);
+  }
+  return results;
+}