@c9up/nebula 0.1.0

package/dist/primitives/focusable.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Which elements can take focus.
+ *
+ * The focus trap, the roving-focus groups and every overlay that restores
+ * focus on close all need the same answer, and getting it slightly different
+ * in each place is how keyboard navigation rots. One implementation here.
+ *
+ * The selector is the standard tabbable set, but a selector alone is not the
+ * answer: it matches nodes that are disabled, `inert`, hidden by CSS, or
+ * inside a collapsed `<details>`. Those have to be filtered by asking the
+ * layout engine, which is why `isVisible` reads `offsetParent` and computed
+ * styles rather than trusting the markup.
+ */
+/**
+ * Is the element rendered and interactive right now?
+ *
+ * `offsetParent === null` catches `display: none` on the element or any
+ * ancestor in one property read, which is much cheaper than walking the tree.
+ * It reports null for `position: fixed` elements too, so those fall through to
+ * the explicit style checks — that branch is why dialogs and popovers, which
+ * are routinely fixed, are not wrongly treated as hidden.
+ */
+export declare function isVisible(el: HTMLElement): boolean;
+/**
+ * Can this element receive focus via the keyboard?
+ *
+ * Focusability is decided from the selector match plus the `tabindex`
+ * *attribute* — deliberately not the `tabIndex` property. The property is
+ * derived: a browser reports `0` for a native `<button>` that never declared
+ * one, and DOM implementations disagree about which elements get that
+ * treatment. Reading the attribute asks what the markup actually says, and
+ * "natively focusable unless it opted out" is then a rule this function states
+ * rather than one it inherits from whichever DOM it is running in.
+ */
+export declare function isFocusable(el: Element): el is HTMLElement;
+/**
+ * Every focusable descendant of `root`, in tab order.
+ *
+ * Document order is returned as-is. Honouring positive `tabindex` values would
+ * mean a second sort, and nebula never emits one — a positive tabindex breaks
+ * the tab order of the whole page, so the library treats its presence in host
+ * markup as the host's problem rather than reordering around it.
+ */
+export declare function focusableWithin(root: ParentNode): HTMLElement[];
+/** First focusable descendant, or `null` when the subtree has none. */
+export declare function firstFocusable(root: ParentNode): HTMLElement | null;
+/**
+ * Focus an element without scrolling the page to it.
+ *
+ * Overlays position themselves; letting the browser scroll to the newly
+ * focused node fights that positioning and visibly jumps the page.
+ */
+export declare function focusSilently(el: HTMLElement | null | undefined): void;

package/dist/primitives/focusable.js

@@ -0,0 +1,109 @@
+/// <reference lib="dom" />
+/**
+ * Which elements can take focus.
+ *
+ * The focus trap, the roving-focus groups and every overlay that restores
+ * focus on close all need the same answer, and getting it slightly different
+ * in each place is how keyboard navigation rots. One implementation here.
+ *
+ * The selector is the standard tabbable set, but a selector alone is not the
+ * answer: it matches nodes that are disabled, `inert`, hidden by CSS, or
+ * inside a collapsed `<details>`. Those have to be filtered by asking the
+ * layout engine, which is why `isVisible` reads `offsetParent` and computed
+ * styles rather than trusting the markup.
+ */
+const FOCUSABLE_SELECTOR = [
+    "a[href]",
+    "area[href]",
+    "button:not([disabled])",
+    "input:not([disabled]):not([type='hidden'])",
+    "select:not([disabled])",
+    "textarea:not([disabled])",
+    "iframe",
+    "object",
+    "embed",
+    "audio[controls]",
+    "video[controls]",
+    "summary",
+    "[contenteditable]:not([contenteditable='false'])",
+    "[tabindex]",
+].join(",");
+/**
+ * Is the element rendered and interactive right now?
+ *
+ * `offsetParent === null` catches `display: none` on the element or any
+ * ancestor in one property read, which is much cheaper than walking the tree.
+ * It reports null for `position: fixed` elements too, so those fall through to
+ * the explicit style checks — that branch is why dialogs and popovers, which
+ * are routinely fixed, are not wrongly treated as hidden.
+ */
+export function isVisible(el) {
+    if (el.hasAttribute("inert"))
+        return false;
+    if (el.closest("[inert]") !== null)
+        return false;
+    if (el.offsetParent !== null)
+        return true;
+    const style = getComputedStyle(el);
+    if (style.position !== "fixed")
+        return false;
+    return style.display !== "none" && style.visibility !== "hidden";
+}
+/**
+ * Can this element receive focus via the keyboard?
+ *
+ * Focusability is decided from the selector match plus the `tabindex`
+ * *attribute* — deliberately not the `tabIndex` property. The property is
+ * derived: a browser reports `0` for a native `<button>` that never declared
+ * one, and DOM implementations disagree about which elements get that
+ * treatment. Reading the attribute asks what the markup actually says, and
+ * "natively focusable unless it opted out" is then a rule this function states
+ * rather than one it inherits from whichever DOM it is running in.
+ */
+export function isFocusable(el) {
+    if (!(el instanceof HTMLElement))
+        return false;
+    if (!el.matches(FOCUSABLE_SELECTOR))
+        return false;
+    if (el.hasAttribute("disabled"))
+        return false;
+    if (el.getAttribute("aria-hidden") === "true")
+        return false;
+    const declared = el.getAttribute("tabindex");
+    if (declared !== null && Number.parseInt(declared, 10) < 0)
+        return false;
+    return isVisible(el);
+}
+/**
+ * Every focusable descendant of `root`, in tab order.
+ *
+ * Document order is returned as-is. Honouring positive `tabindex` values would
+ * mean a second sort, and nebula never emits one — a positive tabindex breaks
+ * the tab order of the whole page, so the library treats its presence in host
+ * markup as the host's problem rather than reordering around it.
+ */
+export function focusableWithin(root) {
+    const found = [];
+    for (const candidate of root.querySelectorAll(FOCUSABLE_SELECTOR)) {
+        if (isFocusable(candidate))
+            found.push(candidate);
+    }
+    return found;
+}
+/** First focusable descendant, or `null` when the subtree has none. */
+export function firstFocusable(root) {
+    for (const candidate of root.querySelectorAll(FOCUSABLE_SELECTOR)) {
+        if (isFocusable(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Focus an element without scrolling the page to it.
+ *
+ * Overlays position themselves; letting the browser scroll to the newly
+ * focused node fights that positioning and visibly jumps the page.
+ */
+export function focusSilently(el) {
+    el?.focus({ preventScroll: true });
+}

package/dist/primitives/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Headless primitives — the behaviour layer nebula owns instead of Radix.
+ *
+ * shadcn/ui is styling on top of Radix. Radix is React-only, so porting the
+ * styling alone would leave every interactive component inert. These modules
+ * are that missing half, written against Aurora's signals and DOM: focus
+ * management, layer dismissal, placement, presence, roving focus, type-ahead
+ * and controlled/uncontrolled state.
+ *
+ * They are deliberately usable on their own. A component the registry does not
+ * ship — an app's own combobox, a bespoke overlay — should be able to reach
+ * for the same trap and the same layer stack rather than growing a second,
+ * subtly different implementation next door.
+ */
+export { type Controllable, type ControllableOptions, controllable, } from "./controllable.js";
+export { type DismissableLayer, type DismissableOptions, type DismissReason, dismissable, layerCount, } from "./dismissable.js";
+export { type Align, type AutoPosition, type AutoPositionOptions, autoPosition, type Placement, type Position, type PositionOptions, type Rect, resolvePosition, type Side, type Viewport, } from "./floating.js";
+export { type FloatingSurfaceOptions, floatingSurface, } from "./floatingSurface.js";
+export { firstFocusable, focusableWithin, focusSilently, isFocusable, isVisible, } from "./focusable.js";
+export { type FocusTrap, type FocusTrapOptions, focusTrap, } from "./focusTrap.js";
+export { type MenuAction, type MenuCheckbox, type MenuEntry, type MenuLabel, type MenuRadioGroup, type MenuSeparator, type MenuSubmenu, menuPanel, menuPanelClasses, wireMenu, } from "./menu.js";
+export { type ModalSurfaceOptions, modalSurface } from "./modalSurface.js";
+export { type Portal, type PortalOptions, portal } from "./portal.js";
+export { onExitFinished, type Presence, type PresenceState, presence, } from "./presence.js";
+export { type Orientation, type RovingFocus, type RovingFocusOptions, rovingFocus, } from "./rovingFocus.js";
+export { isScrollLocked, lockScroll } from "./scrollLock.js";
+export { type Typeahead, type TypeaheadOptions, typeahead, } from "./typeahead.js";

package/dist/primitives/index.js

@@ -0,0 +1,27 @@
+/**
+ * Headless primitives — the behaviour layer nebula owns instead of Radix.
+ *
+ * shadcn/ui is styling on top of Radix. Radix is React-only, so porting the
+ * styling alone would leave every interactive component inert. These modules
+ * are that missing half, written against Aurora's signals and DOM: focus
+ * management, layer dismissal, placement, presence, roving focus, type-ahead
+ * and controlled/uncontrolled state.
+ *
+ * They are deliberately usable on their own. A component the registry does not
+ * ship — an app's own combobox, a bespoke overlay — should be able to reach
+ * for the same trap and the same layer stack rather than growing a second,
+ * subtly different implementation next door.
+ */
+export { controllable, } from "./controllable.js";
+export { dismissable, layerCount, } from "./dismissable.js";
+export { autoPosition, resolvePosition, } from "./floating.js";
+export { floatingSurface, } from "./floatingSurface.js";
+export { firstFocusable, focusableWithin, focusSilently, isFocusable, isVisible, } from "./focusable.js";
+export { focusTrap, } from "./focusTrap.js";
+export { menuPanel, menuPanelClasses, wireMenu, } from "./menu.js";
+export { modalSurface } from "./modalSurface.js";
+export { portal } from "./portal.js";
+export { onExitFinished, presence, } from "./presence.js";
+export { rovingFocus, } from "./rovingFocus.js";
+export { isScrollLocked, lockScroll } from "./scrollLock.js";
+export { typeahead, } from "./typeahead.js";

package/dist/primitives/menu.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The menu panel, shared by every menu-shaped surface.
+ *
+ * DropdownMenu, ContextMenu and Menubar differ only in what opens them — a
+ * button, a right-click, a bar of buttons. The panel itself, its entries, its
+ * keyboard model and its submenus are identical, and live here.
+ *
+ * **Entries are data.** A menu is a list, and describing it as one is what
+ * lets the panel enforce things no individual item can see: which radio in a
+ * group is selected, where the separators fall, and — the one that matters
+ * most — that activating any item closes the whole stack, submenus included.
+ *
+ * **Submenus are imperative.** `floatingSurface` registers mount and unmount
+ * hooks, so it can only be called from a component setup. A submenu opens from
+ * inside portalled content, long after setup has run, so it wires `portal`,
+ * `autoPosition` and `dismissable` directly. The stack of open submenus is
+ * held here and unwound together.
+ *
+ * The keyboard model is the WAI-ARIA menu pattern: arrows move, Home and End
+ * jump, typing seeks, ArrowRight opens a submenu, ArrowLeft closes it, Escape
+ * closes one level, and activating an item closes everything.
+ */
+import { type TemplateResult } from "@c9up/aurora";
+import type { Child } from "../lib/children.js";
+export interface MenuAction {
+    type?: "item";
+    label: Child;
+    icon?: Child;
+    /** Rendered right-aligned. Display only — bind the real shortcut yourself. */
+    shortcut?: string;
+    disabled?: boolean;
+    /** Styles the entry as a destructive action. */
+    destructive?: boolean;
+    onSelect?: () => void;
+}
+export interface MenuCheckbox {
+    type: "checkbox";
+    label: Child;
+    checked: boolean;
+    disabled?: boolean;
+    onCheckedChange?: (checked: boolean) => void;
+}
+export interface MenuRadioGroup {
+    type: "radio-group";
+    value: string;
+    options: ReadonlyArray<{
+        value: string;
+        label: Child;
+        disabled?: boolean;
+    }>;
+    onValueChange?: (value: string) => void;
+}
+export interface MenuLabel {
+    type: "label";
+    label: Child;
+}
+export interface MenuSeparator {
+    type: "separator";
+}
+export interface MenuSubmenu {
+    type: "submenu";
+    label: Child;
+    icon?: Child;
+    disabled?: boolean;
+    entries: readonly MenuEntry[];
+}
+export type MenuEntry = MenuAction | MenuCheckbox | MenuRadioGroup | MenuLabel | MenuSeparator | MenuSubmenu;
+export declare const menuPanelClasses = "bg-popover text-popover-foreground z-50 min-w-[8rem] max-h-(--nebula-available-height) overflow-x-hidden overflow-y-auto rounded-md border p-1 shadow-md outline-none";
+export interface MenuPanelOptions {
+    id: string;
+    entries: readonly MenuEntry[];
+    /** Close the whole menu stack — called after an item is activated. */
+    onCloseAll: () => void;
+    labelledBy?: string;
+    class?: string;
+}
+/** The panel's markup. Behaviour is attached separately by `wireMenu`. */
+export declare function menuPanel(options: MenuPanelOptions): TemplateResult;
+export interface WireMenuOptions {
+    /** Close the whole stack, back to the original trigger. */
+    onCloseAll: () => void;
+    /** Focus the first item as soon as the panel opens. */
+    autoFocusFirst?: boolean;
+    /**
+     * Close *this* panel and return focus to whatever opened it.
+     *
+     * Supplied only when wiring a submenu, and it is what makes ArrowLeft and
+     * Escape work inside one. A submenu is portalled, so its keydowns never
+     * bubble to the parent panel's listener — the parent hands down a way to be
+     * called instead. Without it the two keys fall through: ArrowLeft does
+     * nothing at all, and Escape reaches the document and closes the entire
+     * stack rather than one level.
+     */
+    onCloseSelf?: () => void;
+}
+/**
+ * Attach the keyboard model and submenu handling to a live panel.
+ *
+ * Returns a teardown that also closes any submenus still open, which is what
+ * keeps a stack of three from leaving two behind when the root closes.
+ */
+export declare function wireMenu(panel: HTMLElement, options: WireMenuOptions): () => void;

package/dist/primitives/menu.js

@@ -0,0 +1,356 @@
+/// <reference lib="dom" />
+/**
+ * The menu panel, shared by every menu-shaped surface.
+ *
+ * DropdownMenu, ContextMenu and Menubar differ only in what opens them — a
+ * button, a right-click, a bar of buttons. The panel itself, its entries, its
+ * keyboard model and its submenus are identical, and live here.
+ *
+ * **Entries are data.** A menu is a list, and describing it as one is what
+ * lets the panel enforce things no individual item can see: which radio in a
+ * group is selected, where the separators fall, and — the one that matters
+ * most — that activating any item closes the whole stack, submenus included.
+ *
+ * **Submenus are imperative.** `floatingSurface` registers mount and unmount
+ * hooks, so it can only be called from a component setup. A submenu opens from
+ * inside portalled content, long after setup has run, so it wires `portal`,
+ * `autoPosition` and `dismissable` directly. The stack of open submenus is
+ * held here and unwound together.
+ *
+ * The keyboard model is the WAI-ARIA menu pattern: arrows move, Home and End
+ * jump, typing seeks, ArrowRight opens a submenu, ArrowLeft closes it, Escape
+ * closes one level, and activating an item closes everything.
+ */
+import { html } from "@c9up/aurora";
+import { cn } from "../lib/cn.js";
+import { CheckIcon, ChevronRightIcon, DotIcon } from "../lib/icons.js";
+import { uid } from "../lib/id.js";
+import { zoomInOut } from "../lib/motion.js";
+import { dismissable } from "./dismissable.js";
+import { autoPosition } from "./floating.js";
+import { focusSilently } from "./focusable.js";
+import { portal } from "./portal.js";
+import { rovingFocus } from "./rovingFocus.js";
+import { typeahead } from "./typeahead.js";
+// ─── classes ─────────────────────────────────────────────────────────
+export const menuPanelClasses = "bg-popover text-popover-foreground z-50 min-w-[8rem] max-h-(--nebula-available-height) overflow-x-hidden overflow-y-auto rounded-md border p-1 shadow-md outline-none";
+const itemClasses = "relative flex cursor-default select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4";
+const destructiveClasses = "text-destructive focus:bg-destructive/10 focus:text-destructive [&_svg]:text-destructive";
+const indentedItemClasses = `${itemClasses} py-1.5 pr-2 pl-8`;
+/** The panel's markup. Behaviour is attached separately by `wireMenu`. */
+export function menuPanel(options) {
+    return html `<div
+		data-slot="menu-content"
+		id="${options.id}"
+		role="menu"
+		aria-labelledby="${options.labelledBy}"
+		aria-orientation="vertical"
+		tabindex="-1"
+		class="${cn(menuPanelClasses, zoomInOut, options.class)}"
+	>${options.entries.map((entry) => renderEntry(entry, options.onCloseAll))}</div>`;
+}
+function renderEntry(entry, closeAll) {
+    if (isSeparator(entry)) {
+        return html `<div role="separator" class="bg-border -mx-1 my-1 h-px"></div>`;
+    }
+    if (isLabel(entry)) {
+        return html `<div
+			role="presentation"
+			class="px-2 py-1.5 text-sm font-medium text-muted-foreground"
+		>${entry.label}</div>`;
+    }
+    if (isCheckbox(entry))
+        return renderCheckbox(entry, closeAll);
+    if (isRadioGroup(entry))
+        return renderRadioGroup(entry, closeAll);
+    if (isSubmenu(entry))
+        return renderSubmenuTrigger(entry);
+    return renderAction(entry, closeAll);
+}
+function renderAction(entry, closeAll) {
+    return html `<div
+		role="menuitem"
+		data-nebula-item
+		data-disabled="${entry.disabled === true ? "" : undefined}"
+		aria-disabled="${entry.disabled === true ? "true" : undefined}"
+		tabindex="-1"
+		class="${cn(itemClasses, entry.destructive === true ? destructiveClasses : "")}"
+		@click="${() => activate(entry.disabled, entry.onSelect, closeAll)}"
+	>
+		${entry.icon}
+		<span class="flex-1 truncate">${entry.label}</span>
+		${entry.shortcut === undefined
+        ? null
+        : html `<span class="text-muted-foreground ml-auto text-xs tracking-widest"
+					>${entry.shortcut}</span
+				>`}
+	</div>`;
+}
+function renderCheckbox(entry, closeAll) {
+    return html `<div
+		role="menuitemcheckbox"
+		data-nebula-item
+		aria-checked="${entry.checked ? "true" : "false"}"
+		data-disabled="${entry.disabled === true ? "" : undefined}"
+		tabindex="-1"
+		class="${indentedItemClasses}"
+		@click="${() => activate(entry.disabled, () => entry.onCheckedChange?.(!entry.checked), closeAll)}"
+	>
+		<span class="pointer-events-none absolute left-2 flex size-3.5 items-center justify-center">
+			${entry.checked ? CheckIcon({ class: "size-4" }) : null}
+		</span>
+		${entry.label}
+	</div>`;
+}
+function renderRadioGroup(entry, closeAll) {
+    return html `<div role="group">
+		${entry.options.map((option) => html `<div
+				role="menuitemradio"
+				data-nebula-item
+				aria-checked="${option.value === entry.value ? "true" : "false"}"
+				data-disabled="${option.disabled === true ? "" : undefined}"
+				tabindex="-1"
+				class="${indentedItemClasses}"
+				@click="${() => activate(option.disabled, () => entry.onValueChange?.(option.value), closeAll)}"
+			>
+				<span class="pointer-events-none absolute left-2 flex size-3.5 items-center justify-center">
+					${option.value === entry.value ? DotIcon({ class: "size-2" }) : null}
+				</span>
+				${option.label}
+			</div>`)}
+	</div>`;
+}
+/**
+ * A submenu's trigger row.
+ *
+ * The entries are stashed on the element through a WeakMap rather than an
+ * attribute — they contain callbacks and nested structures, and serialising
+ * those into the DOM is not possible. `wireMenu` reads them back when the row
+ * is opened.
+ */
+const submenuEntries = new WeakMap();
+function renderSubmenuTrigger(entry) {
+    const id = uid("menu-sub-trigger");
+    const row = html `<div
+		role="menuitem"
+		data-nebula-item
+		data-submenu="${id}"
+		data-disabled="${entry.disabled === true ? "" : undefined}"
+		aria-haspopup="menu"
+		aria-expanded="false"
+		tabindex="-1"
+		class="${itemClasses}"
+	>
+		${entry.icon}
+		<span class="flex-1 truncate">${entry.label}</span>
+		${ChevronRightIcon({ class: "ml-auto size-4" })}
+	</div>`;
+    pendingSubmenus.set(id, entry.entries);
+    return row;
+}
+/**
+ * Entries waiting to be claimed by their element.
+ *
+ * The trigger's entries are known while the template is built, but the element
+ * does not exist until it is mounted. This bridges the two: `wireMenu` moves
+ * each set from here onto the real element and clears the id, so nothing is
+ * retained after the menu closes.
+ */
+const pendingSubmenus = new Map();
+function activate(disabled, onSelect, closeAll) {
+    if (disabled === true)
+        return;
+    onSelect?.();
+    closeAll();
+}
+/**
+ * Attach the keyboard model and submenu handling to a live panel.
+ *
+ * Returns a teardown that also closes any submenus still open, which is what
+ * keeps a stack of three from leaving two behind when the root closes.
+ */
+export function wireMenu(panel, options) {
+    claimSubmenuEntries(panel);
+    const open = [];
+    function closeSubmenusFrom(depth) {
+        while (open.length > depth)
+            open.pop()?.close();
+    }
+    const group = rovingFocus({
+        container: () => panel,
+        itemSelector: "[data-nebula-item]",
+        orientation: "vertical",
+        // Moving off a submenu's trigger closes it, so the pointer travelling
+        // down a menu does not leave a trail of open panels behind it.
+        onFocusChange: (item) => {
+            if (item.getAttribute("data-submenu") === null)
+                closeSubmenusFrom(0);
+        },
+        onSelect: (item) => {
+            if (item.getAttribute("data-submenu") !== null)
+                openSubmenu(item);
+            else
+                item.click();
+        },
+    });
+    group.sync();
+    const seek = typeahead({
+        items: () => group.items(),
+        onMatch: (item) => focusSilently(item),
+    });
+    function openSubmenu(trigger) {
+        const entries = submenuEntries.get(trigger);
+        if (entries === undefined || entries.length === 0)
+            return;
+        closeSubmenusFrom(0);
+        const panelId = uid("menu-sub");
+        const mount = portal(menuPanel({ id: panelId, entries, onCloseAll: options.onCloseAll }));
+        const element = mount.host.firstElementChild;
+        if (!(element instanceof HTMLElement)) {
+            mount.close();
+            return;
+        }
+        element.setAttribute("data-state", "open");
+        trigger.setAttribute("aria-expanded", "true");
+        trigger.setAttribute("aria-controls", panelId);
+        // Submenus sit beside their parent, overlapping it slightly, which is what
+        // lets the pointer travel diagonally into them without crossing a gap.
+        const position = autoPosition(trigger, element, {
+            placement: "right-start",
+            offset: -4,
+        });
+        const layer = dismissable({
+            element: () => element,
+            exclude: () => [trigger, panel],
+            onDismiss: () => closeSubmenusFrom(0),
+            escapeKey: false,
+        });
+        const inner = wireMenu(element, {
+            ...options,
+            onCloseSelf: () => {
+                closeSubmenusFrom(0);
+                focusSilently(trigger);
+            },
+        });
+        const firstItem = element.querySelector("[data-nebula-item]");
+        if (firstItem instanceof HTMLElement)
+            focusSilently(firstItem);
+        open.push({
+            close() {
+                inner();
+                layer.remove();
+                position.stop();
+                mount.close();
+                trigger.setAttribute("aria-expanded", "false");
+                trigger.removeAttribute("aria-controls");
+            },
+        });
+    }
+    function onKeyDown(event) {
+        const active = document.activeElement;
+        const inside = active instanceof Node && panel.contains(active);
+        if (event.key === "ArrowRight" && inside) {
+            if (!(active instanceof HTMLElement))
+                return;
+            if (active.getAttribute("data-submenu") === null)
+                return;
+            event.preventDefault();
+            event.stopPropagation();
+            openSubmenu(active);
+            return;
+        }
+        // One level per press for both keys: a submenu three deep takes three
+        // Escapes, not one. Closing a child we opened comes first; with none
+        // open, this panel is itself the child and asks its parent to close it.
+        // `dismissable` handles the last level, closing the root menu.
+        if (event.key === "ArrowLeft" || event.key === "Escape") {
+            if (open.length > 0) {
+                event.preventDefault();
+                event.stopPropagation();
+                closeSubmenusFrom(open.length - 1);
+                return;
+            }
+            if (options.onCloseSelf !== undefined) {
+                event.preventDefault();
+                event.stopPropagation();
+                options.onCloseSelf();
+                return;
+            }
+            // A root menu ignores ArrowLeft and lets `dismissable` see Escape.
+            if (event.key === "ArrowLeft")
+                return;
+        }
+        if (event.key === "Tab") {
+            // Tab out of a menu means "I am done here", not "next item".
+            options.onCloseAll();
+            return;
+        }
+        if (inside)
+            seek.handleKey(event);
+    }
+    function onPointerOver(event) {
+        const target = event.target;
+        if (!(target instanceof Element))
+            return;
+        const item = target.closest("[data-nebula-item]");
+        if (!(item instanceof HTMLElement))
+            return;
+        if (item.hasAttribute("data-disabled"))
+            return;
+        focusSilently(item);
+        // Hover focuses the row directly rather than going through rovingFocus,
+        // so its `onFocusChange` never runs — the close has to be explicit here
+        // or the pointer leaves a trail of open panels behind it.
+        if (item.getAttribute("data-submenu") !== null)
+            openSubmenu(item);
+        else
+            closeSubmenusFrom(0);
+    }
+    panel.addEventListener("keydown", onKeyDown);
+    panel.addEventListener("pointerover", onPointerOver);
+    if (options.autoFocusFirst === true) {
+        const first = group.items()[0];
+        if (first !== undefined)
+            focusSilently(first);
+    }
+    return () => {
+        closeSubmenusFrom(0);
+        panel.removeEventListener("keydown", onKeyDown);
+        panel.removeEventListener("pointerover", onPointerOver);
+        seek.reset();
+        group.destroy();
+    };
+}
+/** Move each submenu's entries from the build-time map onto its element. */
+function claimSubmenuEntries(panel) {
+    for (const node of panel.querySelectorAll("[data-submenu]")) {
+        const id = node.getAttribute("data-submenu");
+        if (id === null)
+            continue;
+        const entries = pendingSubmenus.get(id);
+        if (entries === undefined)
+            continue;
+        submenuEntries.set(node, entries);
+        pendingSubmenus.delete(id);
+    }
+}
+// ─── entry guards ────────────────────────────────────────────────────
+//
+// Discriminating on an optional `type` needs real guards: `entry.type ===
+// "item"` is false for a plain action, which leaves it undiscriminated. Each
+// guard names the shape it accepts so the renderer narrows without a cast.
+function isSeparator(entry) {
+    return entry.type === "separator";
+}
+function isLabel(entry) {
+    return entry.type === "label";
+}
+function isCheckbox(entry) {
+    return entry.type === "checkbox";
+}
+function isRadioGroup(entry) {
+    return entry.type === "radio-group";
+}
+function isSubmenu(entry) {
+    return entry.type === "submenu";
+}