@pindoba/astro-menu 0.0.0-alpha-20260829223243

package/src/menu.astro

@@ -0,0 +1,396 @@
+---
+import {
+  connectMenu,
+  connectMenuSub,
+  optionElementId,
+  type MenuBaseProps,
+  type MenuNode,
+  type MenuSubNode,
+  type MenuSubDescriptor,
+  type MenuListboxBag,
+} from "@pindoba/core-menu";
+import Popover from "@pindoba/astro-popover";
+import DialogScript from "@pindoba/astro-dialog/script";
+import ListBox from "@pindoba/astro-listbox";
+import Button from "@pindoba/astro-button";
+import { generateShortUUID } from "@pindoba/utils";
+import type {
+  MenuConfig,
+  MenuLevelConfig,
+  MenuNodeActivation,
+} from "./runtime";
+
+export interface Props extends MenuBaseProps {
+  /** The menu content (data-driven authoring mode). Required in Astro. */
+  items: MenuNode[];
+  /** Stable id root (auto-generated when omitted); also the root element id. */
+  id?: string;
+  /** Initial open state (opened client-side after boot). @default false */
+  open?: boolean;
+  /** Emphasis of the default trigger `<Button>`. @default "secondary" */
+  triggerEmphasis?: "primary" | "secondary" | "ghost";
+  /** Extra class on the root wrapper. */
+  class?: string;
+}
+
+const {
+  items,
+  id: consumerId,
+  open = false,
+  size = "md",
+  placement = "bottom-start",
+  listboxRadius,
+  listboxShadow,
+  listboxBorder,
+  listboxBackground,
+  "aria-label": ariaLabel,
+  triggerEmphasis = "secondary",
+  passThrough,
+  class: className,
+} = Astro.props;
+
+// Stable id root. Deterministic ids below (`${rootId}-menu`, `${subId}-popover`,
+// …) mirror the connect / lower conventions so the boot can find every level.
+const rootId = consumerId ?? `menu-${generateShortUUID()}`;
+
+// --- Serialize the tree (function-free) for the boot controller --------------
+// Submenu triggers can live at top level OR inside a group (MenuGroupChild).
+function levelSubmenuNodes(nodes: MenuNode[]): MenuSubNode[] {
+  const out: MenuSubNode[] = [];
+  for (const n of nodes) {
+    if (n.type === "submenu") out.push(n);
+    else if (n.type === "group") {
+      for (const c of n.items) if (c.type === "submenu") out.push(c);
+    }
+  }
+  return out;
+}
+
+const levels: MenuLevelConfig[] = [];
+const nodeIndex: Record<string, MenuNodeActivation> = {};
+const radioInitial: Record<string, string> = {};
+
+function indexNodes(nodes: MenuNode[]): void {
+  for (const n of nodes) {
+    switch (n.type) {
+      case "action":
+        nodeIndex[n.id] = {
+          type: "action",
+          closeOnSelect: n.closeOnSelect !== false,
+        };
+        break;
+      case "link":
+        nodeIndex[n.id] = { type: "link" };
+        break;
+      case "checkbox":
+        nodeIndex[n.id] = {
+          type: "checkbox",
+          checked: Boolean(n.checked),
+          closeOnSelect: n.closeOnSelect === true,
+        };
+        break;
+      case "submenu":
+        nodeIndex[n.id] = { type: "submenu", subId: n.id };
+        indexNodes(n.items);
+        break;
+      case "group":
+        indexNodes(n.items);
+        break;
+      case "radiogroup":
+        if (n.value !== undefined) radioInitial[n.id] = n.value;
+        for (const r of n.items) {
+          nodeIndex[r.id] = { type: "radio", groupId: n.id, value: r.value };
+        }
+        break;
+      case "separator":
+        break;
+    }
+  }
+}
+
+function buildLevel(
+  nodes: MenuNode[],
+  id: string | null,
+  menuId: string,
+  popoverId: string,
+  depth: number,
+  parentTriggerItemId: string | null,
+): void {
+  const subs = levelSubmenuNodes(nodes);
+  // Namespaced by the owning level's (already instance-unique) listbox id, so
+  // several menus on one page never collide — mirrors `lower.ts`'s
+  // `qualifiedId: ${ctx.listboxId}-sub-${node.id}` (this level's `menuId` is
+  // exactly that `ctx.listboxId`).
+  const qualifiedIds = new Map(
+    subs.map((s) => [s.id, `${menuId}-sub-${s.id}`]),
+  );
+  levels.push({
+    id,
+    popoverId,
+    menuId,
+    depth,
+    parentTriggerItemId,
+    submenus: subs.map((s) => {
+      const qualifiedId = qualifiedIds.get(s.id)!;
+      return {
+        id: s.id,
+        qualifiedId,
+        triggerItemId: optionElementId(menuId, s.id),
+        popoverId: `${qualifiedId}-popover`,
+        menuId: `${qualifiedId}-menu`,
+      };
+    }),
+  });
+  for (const s of subs) {
+    const qualifiedId = qualifiedIds.get(s.id)!;
+    buildLevel(
+      s.items,
+      s.id,
+      `${qualifiedId}-menu`,
+      `${qualifiedId}-popover`,
+      depth + 1,
+      optionElementId(menuId, s.id),
+    );
+  }
+}
+
+indexNodes(items);
+buildLevel(items, null, `${rootId}-menu`, `${rootId}-popover`, 0, null);
+
+// --- Forward per-item rich content (Stamp/Badge) into each level's ListBox ---
+// Astro items are JSON-serialized for hydration, so components can't ride in
+// `items` — instead Menu adopts the ListBox's own convention (per-item named
+// slots keyed `<id>:leading` / `<id>:trailing`) and forwards its resolved
+// slot HTML down to each level's ListBox via `optionSlotsHtml`. Node ids must
+// be unique across the WHOLE tree (they already are — they key `nodeIndex`
+// and the boot's `openPath`), so a flat `<id>:region` slot name never
+// collides across levels.
+//
+// Only ids that are rendered as an option ROW at a given level get resolved
+// there — a submenu's own row lives at its parent's level, its nested
+// `items` render at the next level down.
+function levelItemIds(nodes: MenuNode[]): string[] {
+  const ids: string[] = [];
+  for (const n of nodes) {
+    switch (n.type) {
+      case "action":
+      case "link":
+      case "checkbox":
+      case "submenu":
+        ids.push(n.id);
+        break;
+      case "radiogroup":
+        for (const r of n.items) ids.push(r.id);
+        break;
+      case "group":
+        for (const c of n.items) ids.push(c.id);
+        break;
+      case "separator":
+        break;
+    }
+  }
+  return ids;
+}
+
+async function resolveOptionSlotsHtml(
+  ids: string[],
+): Promise<Record<string, string>> {
+  const out: Record<string, string> = {};
+  for (const id of ids) {
+    for (const region of ["leading", "trailing"] as const) {
+      const name = `${id}:${region}`;
+      if (!Astro.slots.has(name)) continue;
+      const html = await Astro.slots.render(name);
+      if (html && html.trim() !== "") out[name] = html;
+    }
+  }
+  return out;
+}
+
+// Non-interactive `type:"custom"` blocks (content keyed by the node id) and
+// rich `group` headers (keyed `<id>:title`) ride the same named-slot →
+// forwarded-HTML path as leading/trailing, but into the ListBox's
+// `customSlotsHtml` instead. Custom blocks live at the top level; groups can
+// nest, so this runs per level like the option resolver.
+function levelCustomSlotNames(nodes: MenuNode[]): string[] {
+  const names: string[] = [];
+  for (const n of nodes) {
+    if (n.type === "custom") names.push(n.id);
+    else if (n.type === "group") names.push(`${n.id}:title`);
+  }
+  return names;
+}
+
+async function resolveCustomSlotsHtml(
+  names: string[],
+): Promise<Record<string, string>> {
+  const out: Record<string, string> = {};
+  for (const name of names) {
+    if (!Astro.slots.has(name)) continue;
+    const html = await Astro.slots.render(name);
+    if (html && html.trim() !== "") out[name] = html;
+  }
+  return out;
+}
+
+const rootOptionSlotsHtml = await resolveOptionSlotsHtml(levelItemIds(items));
+const rootCustomSlotsHtml = await resolveCustomSlotsHtml(
+  levelCustomSlotNames(items),
+);
+
+const config: MenuConfig & { open: boolean } = {
+  rootId,
+  triggerId: `${rootId}-trigger`,
+  popoverId: `${rootId}-popover`,
+  menuId: `${rootId}-menu`,
+  side: "right",
+  placement,
+  levels,
+  nodeIndex,
+  radioInitial,
+  open,
+};
+
+// --- Lower each level via the pure connect functions -------------------------
+const rootApi = connectMenu({
+  items,
+  id: rootId,
+  size,
+  placement,
+  listboxRadius,
+  listboxShadow,
+  listboxBorder,
+  listboxBackground,
+  "aria-label": ariaLabel ?? null,
+  passThrough,
+  openSubmenuIds: [],
+  triggerAttrs: {
+    // The whole hydration payload rides on the trigger (mirrors select's
+    // `data-select-config`); the emphasis is baked into the bag so the template
+    // spreads a single connect bag onto <Button> (Connect Contract v1.1).
+    "data-menu-config": JSON.stringify(config),
+    emphasis: triggerEmphasis,
+  },
+});
+
+interface SubLevelRender {
+  popoverProps: Record<string, unknown>;
+  listboxProps: MenuListboxBag;
+}
+const subLevels: SubLevelRender[] = [];
+
+async function collectSub(
+  descriptors: MenuSubDescriptor[],
+  depth: number,
+): Promise<void> {
+  for (const desc of descriptors) {
+    const subApi = connectMenuSub({
+      items: desc.items,
+      // Instance-unique (multiple menus can share node ids on one page).
+      id: desc.qualifiedId,
+      triggerItemId: desc.triggerItemId,
+      depth,
+      size,
+      // The level surface travels with `size`, so a submenu paints exactly
+      // like the root that spawned it.
+      listboxRadius,
+      listboxShadow,
+      listboxBorder,
+      listboxBackground,
+      openSubmenuIds: [],
+      passThrough,
+    });
+    const optionSlotsHtml = await resolveOptionSlotsHtml(
+      levelItemIds(desc.items),
+    );
+    const customSlotsHtml = await resolveCustomSlotsHtml(
+      levelCustomSlotNames(desc.items),
+    );
+    subLevels.push({
+      popoverProps: subApi.popoverProps,
+      listboxProps: {
+        ...subApi.listboxProps,
+        optionSlotsHtml,
+        customSlotsHtml,
+      },
+    });
+    await collectSub(subApi.submenus, depth + 1);
+  }
+}
+await collectSub(rootApi.submenus, 1);
+
+// The Astro <Popover> is an SSR Dialog wrapper: it only consumes markup props.
+// Interactive positioning (placement / offset / z-index / anchor / trigger
+// strategy) is applied at runtime in boot-menu via createPopover — exactly the
+// split the astro-popover component documents. So pick only the SSR keys here.
+function toAstroPopover(pp: Record<string, unknown>) {
+  return {
+    id: pp.id as string,
+    isModal: false as const,
+    fitContentWidth: true as const,
+    // The core bag already carries the menu panel's chrome (`transparent` /
+    // `none`) — the ListBox draws its own border. Without these, the Astro
+    // <Popover> falls back to the Dialog's default panel chrome, painting a
+    // second border around the ListBox's own.
+    background: pp.background as string | undefined,
+    border: pp.border as string | undefined,
+    passThrough: pp.passThrough as Record<string, unknown> | undefined,
+  };
+}
+
+const rootPopover = toAstroPopover(rootApi.popoverProps);
+const rootListboxProps: MenuListboxBag = {
+  ...rootApi.listboxProps,
+  optionSlotsHtml: rootOptionSlotsHtml,
+  customSlotsHtml: rootCustomSlotsHtml,
+};
+---
+
+<div
+  data-pindoba-menu
+  id={consumerId}
+  class={className}
+  data-connect-allow="menu root: boot scope + custom-event dispatch target (no core bag owns the wrapper)"
+>
+  <Button {...rootApi.triggerProps}>
+    {/* Trigger button label / content. @group Slots */}
+    <slot />
+  </Button>
+
+  {/* Root level: the menu-pattern ListBox inside its Popover shell. */}
+  <Popover {...rootPopover}>
+    <ListBox {...rootListboxProps} />
+  </Popover>
+
+  {
+    /* Every submenu level, always in the DOM (open-driven). Each dialog portals
+      to <body> and is positioned/opened only by the boot controller. Rendered
+      flat — the boot re-parents + anchors them per open. */
+  }
+  {
+    subLevels.map((lvl) => (
+      <Popover {...toAstroPopover(lvl.popoverProps)}>
+        <ListBox {...lvl.listboxProps} />
+      </Popover>
+    ))
+  }
+
+  {/* Bootstraps the global dialog manager the popovers rely on. */}
+  <DialogScript />
+</div>
+
+<script>
+  import { bootAllMenus } from "./boot-menu";
+
+  function boot() {
+    const results = bootAllMenus();
+    const teardown = () => {
+      for (const r of results) r.destroy();
+    };
+    window.addEventListener("pagehide", teardown, { once: true });
+    document.addEventListener("astro:before-swap", teardown, { once: true });
+  }
+
+  boot();
+  document.addEventListener("astro:page-load", boot);
+</script>

package/src/runtime.ts

@@ -0,0 +1,102 @@
+/**
+ * Shared runtime types for the Astro Menu: the hydration payload serialized by
+ * `menu.astro` and parsed by `boot-menu.ts`, plus the imperative handle stashed
+ * on the root element (`getMenu(el)`).
+ *
+ * The Menu is a data-driven, boot-script-controlled component: Astro has no
+ * client reactivity framework, so `menu.astro` SSR-renders the trigger + every
+ * level's Popover/ListBox pair, serializes a function-free description of the
+ * MenuNode tree here, and `boot-menu.ts` rebuilds the interaction model in
+ * vanilla DOM — mirroring `menu.svelte` / `menu-level.svelte`.
+ */
+
+/** How a single activatable node behaves when its ListBox row fires. */
+export type MenuNodeActivation =
+  | { type: "action"; closeOnSelect: boolean }
+  | { type: "link" }
+  | { type: "checkbox"; checked: boolean; closeOnSelect: boolean }
+  | { type: "radio"; groupId: string; value: string }
+  | { type: "submenu"; subId: string };
+
+/** A submenu reachable from a given level (its trigger row + child dialog). */
+export interface MenuSubmenuRef {
+  /** The submenu node id. */
+  id: string;
+  /** Instance-unique id (chains with the owning level's listbox id) — used for
+   * DOM lookups (`${qualifiedId}-popover`) so several menus on one page never
+   * collide. Node-id state (`id` above) stays as the open-path key. */
+  qualifiedId: string;
+  /** The rendered element id of the trigger row (a `[data-key]` option). */
+  triggerItemId: string;
+  /** The submenu dialog's id. */
+  popoverId: string;
+  /** The submenu ListBox `<ul>` id. */
+  menuId: string;
+}
+
+/** One menu level (the root or a submenu): its dialog + list + child submenus. */
+export interface MenuLevelConfig {
+  /** `null` for the root level; the submenu node id for a submenu level. */
+  id: string | null;
+  /** This level's dialog id. */
+  popoverId: string;
+  /** This level's ListBox `<ul>` id. */
+  menuId: string;
+  /** Nesting depth (0 = root). */
+  depth: number;
+  /** The parent trigger row element id (submenu levels only; focus restore). */
+  parentTriggerItemId: string | null;
+  /** Submenus opened from this level. */
+  submenus: MenuSubmenuRef[];
+}
+
+/** The full hydration payload carried on the trigger's `data-menu-config`. */
+export interface MenuConfig {
+  rootId: string;
+  triggerId: string;
+  /** The root dialog id. */
+  popoverId: string;
+  /** The root ListBox `<ul>` id. */
+  menuId: string;
+  /** Which physical side submenus open on (always `"right"` today). */
+  side: "right" | "left";
+  /** Preferred placement of the root panel relative to the trigger. */
+  placement: string;
+  /** Every level, root first. */
+  levels: MenuLevelConfig[];
+  /** Activation metadata keyed by node id (across all levels). */
+  nodeIndex: Record<string, MenuNodeActivation>;
+  /** Initially-selected value per radio group id (server-rendered state). */
+  radioInitial: Record<string, string>;
+}
+
+/** Imperative controls exposed on the Menu root via {@link getMenu}. */
+export interface MenuHandle {
+  /** Open the menu. */
+  open: () => void;
+  /** Close the menu (and every submenu). */
+  close: () => void;
+  /** Toggle the menu open/closed. */
+  toggle: () => void;
+  /** Whether the root menu is currently open. */
+  isOpen: () => boolean;
+  /**
+   * Select a value in one of the menu's radio groups from outside the menu —
+   * the counterpart of the `pindoba:menu:valuechange` event. Repaints the
+   * checked row without dispatching (so an owner restoring persisted state
+   * doesn't echo its own event back).
+   */
+  setRadioValue: (groupId: string, value: string) => void;
+  /** The currently selected value of a radio group, if any. */
+  getRadioValue: (groupId: string) => string | undefined;
+  /** Tear down all listeners/popovers. */
+  destroy: () => void;
+}
+
+/** The Menu root element with its handle stashed after boot. */
+export type MenuRootElement = HTMLElement & { menu?: MenuHandle };
+
+/** Retrieve the imperative handle for a booted Menu root element. */
+export function getMenu(el: HTMLElement | null | undefined): MenuHandle | null {
+  return (el as MenuRootElement | null | undefined)?.menu ?? null;
+}