@jgengine/react 0.26.0 → 0.28.0

package/dist/loadingScreen.js

@@ -0,0 +1,108 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useState } from "react";
+import { createTipRotation } from "@jgengine/core/ui/loadingTips";
+import { menuIntentForKey } from "@jgengine/core/ui/menuNav";
+import { hudSpace, hudType } from "./hudTokens.js";
+import { useMenuNav } from "./menuNav.js";
+import { MenuScreen } from "./menuScreen.js";
+const column = {
+    display: "flex",
+    flexDirection: "column",
+    gap: hudSpace("md"),
+    width: "min(92vw, 520px)",
+};
+function useTip(rotation, intervalMs, active) {
+    const [, bump] = useState(0);
+    useEffect(() => {
+        if (!active || intervalMs <= 0)
+            return;
+        const timer = setInterval(() => {
+            rotation.next();
+            bump((value) => value + 1);
+        }, intervalMs);
+        return () => clearInterval(timer);
+    }, [rotation, intervalMs, active]);
+    return rotation.current();
+}
+/**
+ * A loading screen with a progress bar and a rotating tip. Progress is a real 0–1 value from the
+ * game's loader (or indeterminate), tips come from the game and cycle deterministically, and a
+ * `ready` screen accepts any key, a gamepad A/Cross or a click. It reads HudTheme tokens and keeps a
+ * live scene visible behind a blur, so loading a level looks like the game rather than a blank page.
+ *
+ * @capability loading-screen loading block with progress, rotating tips, a ready gate, and a scene backdrop
+ */
+export function LoadingScreen({ progress, title = "Loading", tips, tipIntervalMs = 6000, ready = false, onReady, onSkip, backdrop, scrim = "blur", children, open = true, reducedMotion, onClosed, className, style, contentClassName, contentStyle, }) {
+    const rotation = useMemo(() => {
+        if (tips === undefined)
+            return createTipRotation({ tips: [] });
+        return Array.isArray(tips) ? createTipRotation({ tips }) : tips;
+    }, [tips]);
+    const tip = useTip(rotation, tipIntervalMs, open && !ready);
+    const nav = useMenuNav({
+        ids: ready ? ["continue"] : [],
+        enabled: ready,
+        onConfirm: () => onReady?.(),
+        ...(onSkip === undefined ? {} : { onBack: onSkip }),
+    });
+    useEffect(() => {
+        if (!ready || onReady === undefined)
+            return;
+        const onKey = (event) => {
+            if (event.defaultPrevented || event.metaKey || event.ctrlKey || event.altKey)
+                return;
+            if (event.code === "Tab" || menuIntentForKey(event.code) !== null)
+                return;
+            onReady();
+        };
+        window.addEventListener("keydown", onKey);
+        return () => window.removeEventListener("keydown", onKey);
+    }, [ready, onReady]);
+    const clamped = progress === undefined ? undefined : Math.max(0, Math.min(1, progress));
+    const percent = clamped === undefined ? null : `${Math.round(clamped * 100)}%`;
+    return (_jsx(MenuScreen, { open: open, transition: "fade", scrim: scrim, label: typeof title === "string" ? title : "Loading", ...(backdrop === undefined ? {} : { backdrop }), ...(reducedMotion === undefined ? {} : { reducedMotion }), ...(onClosed === undefined ? {} : { onClosed }), className: className, style: style, contentClassName: contentClassName, contentStyle: contentStyle, children: _jsxs("div", { "data-loading-screen": "", style: column, ...nav.containerProps, children: [_jsx("div", { "data-loading-title": "", style: {
+                        fontFamily: "var(--jg-font-display, inherit)",
+                        fontSize: hudType("xl"),
+                        fontWeight: 700,
+                        letterSpacing: "0.08em",
+                        textTransform: "uppercase",
+                        color: "var(--jg-text, #f5f7fa)",
+                    }, children: title }), _jsx("div", { "data-loading-bar": "", role: "progressbar", "aria-valuemin": 0, "aria-valuemax": 100, ...(clamped === undefined ? {} : { "aria-valuenow": Math.round(clamped * 100) }), "aria-label": "Loading progress", style: {
+                        position: "relative",
+                        height: 6,
+                        borderRadius: 999,
+                        overflow: "hidden",
+                        background: "var(--jg-surface-deep, rgba(255,255,255,0.12))",
+                        border: "1px solid var(--jg-edge, rgba(255,255,255,0.14))",
+                    }, children: _jsx("div", { "data-loading-fill": "", style: {
+                            height: "100%",
+                            transformOrigin: "left center",
+                            transform: `scaleX(${clamped ?? 0.18})`,
+                            background: "linear-gradient(90deg, var(--jg-accent-deep, #2f9e6b), var(--jg-accent, #6ee7a8))",
+                            transition: "transform var(--jg-motion-slow, 320ms) var(--jg-ease-out, cubic-bezier(0.16, 1, 0.3, 1))",
+                            ...(clamped === undefined
+                                ? {
+                                    animation: "jg-sheen 1.1s linear infinite",
+                                    backgroundImage: "linear-gradient(90deg, var(--jg-accent-deep, #2f9e6b), var(--jg-accent, #6ee7a8), var(--jg-accent-deep, #2f9e6b))",
+                                    backgroundSize: "260px 100%",
+                                }
+                                : {}),
+                        } }) }), percent === null ? null : (_jsx("span", { "data-loading-percent": "", style: { fontSize: hudType("xs"), color: "var(--jg-text-dim, #94a3a0)", fontVariantNumeric: "tabular-nums" }, children: percent })), tip === null ? null : (_jsxs("p", { "data-loading-tip": "", "aria-live": "polite", style: {
+                        margin: 0,
+                        minHeight: "2.6em",
+                        fontSize: hudType("sm"),
+                        lineHeight: 1.4,
+                        color: "var(--jg-text-dim, #94a3a0)",
+                    }, children: [_jsx("span", { style: { color: "var(--jg-accent, #6ee7a8)", fontWeight: 700, letterSpacing: "0.14em", marginRight: 8 }, children: "TIP" }), tip] })), children, ready ? (_jsx("button", { type: "button", "data-loading-continue": "", ...nav.itemProps("continue"), onClick: () => onReady?.(), style: {
+                        alignSelf: "flex-start",
+                        marginTop: hudSpace("sm"),
+                        padding: "8px 14px",
+                        borderRadius: 8,
+                        border: "1px solid var(--jg-edge-bright, rgba(255,255,255,0.22))",
+                        background: "var(--jg-surface, rgba(20,24,32,0.8))",
+                        color: "var(--jg-text, #f5f7fa)",
+                        fontSize: hudType("sm"),
+                        fontWeight: 600,
+                        cursor: "pointer",
+                    }, children: "Press any key to continue" })) : null] }) }));
+}

package/dist/menuNav.d.ts

@@ -0,0 +1,63 @@
+import { type KeyboardEvent as ReactKeyboardEvent, type ReactNode, type RefCallback } from "react";
+import { type MenuNavDirection, type MenuNavRepeat } from "@jgengine/core/ui/menuNav";
+/** Props a menu item needs so {@link useMenuNav} can focus it and track pointer/focus. */
+export interface MenuNavItemProps {
+    "data-jg-menu-item": string;
+    tabIndex: number;
+    "aria-current"?: "true";
+    ref: RefCallback<HTMLElement>;
+    onPointerEnter: () => void;
+    onFocus: () => void;
+}
+/** The container props that make a menu navigable. */
+export interface MenuNavContainerProps {
+    "data-jg-menu-nav": "";
+    onKeyDown: (event: ReactKeyboardEvent<HTMLElement>) => void;
+}
+/** The live navigation controller returned by {@link useMenuNav}. */
+export interface MenuNavController {
+    /** Id of the focused item, or `null` when the menu has no items. */
+    activeId: string | null;
+    /** Focus an item by id (pointer hover or a game call). Does not steal DOM focus. */
+    setActive: (id: string | null) => void;
+    /** Move focus by one direction. */
+    move: (direction: MenuNavDirection) => void;
+    /** Props for one item — spread them onto the item's focusable element. */
+    itemProps: (id: string) => MenuNavItemProps;
+    /** Props for the container that wraps the items. */
+    containerProps: MenuNavContainerProps;
+}
+/** How {@link useMenuNav} is wired. */
+export interface UseMenuNavOptions {
+    /** Item ids in focus order. Changing the list keeps focus on the same id when it still exists. */
+    ids: readonly string[];
+    /** Items per row (see {@link MenuNavLayout}). Default 1 — a vertical list. */
+    columns?: number;
+    /** Wrap at the ends. Default true. */
+    wrap?: boolean;
+    /** Ids that are skipped by navigation (disabled rows). */
+    disabled?: readonly string[];
+    /** Item focused on mount. Default the first enabled item. */
+    initialId?: string;
+    /** Turn keyboard/gamepad handling off (for example while a rebind capture is armed). */
+    enabled?: boolean;
+    /** Confirm (Enter/Space/A). Called with the focused id. */
+    onConfirm?: (id: string) => void;
+    /** Back (Escape/Backspace/B/Start). */
+    onBack?: () => void;
+    /** Poll a connected gamepad for menu intents. Default true. */
+    gamepad?: boolean;
+    /** Hold-to-repeat timing for d-pad/stick navigation. */
+    repeat?: MenuNavRepeat;
+}
+/**
+ * Bind a menu's focus order to the DOM: arrow keys, WASD, Home/End and a standard gamepad move a
+ * roving focus, Enter/Space/A confirm, Escape/Backspace/B/Start go back. Tab is left to the browser,
+ * so a menu never traps focus, and typing in a text field is never intercepted. The menu is pure
+ * state + listeners — it unmounts with the screen, so it costs nothing during play.
+ *
+ * @capability use-menu-nav keyboard and gamepad focus navigation for a menu — roving focus order, confirm/back, disabled-item skipping, no focus trap
+ */
+export declare function useMenuNav({ ids, columns, wrap, disabled, initialId, enabled, onConfirm, onBack, gamepad, repeat, }: UseMenuNavOptions): MenuNavController;
+/** Render prop for a menu whose items come from {@link useMenuNav}. */
+export type MenuNavRender = (nav: MenuNavController) => ReactNode;

package/dist/menuNav.js

@@ -0,0 +1,257 @@
+import { useCallback, useEffect, useMemo, useRef, useState, } from "react";
+import { menuIntentForPadAxis, menuIntentForPadButton, menuIntentForKey, menuNavIdAt, menuNavIndex, menuNavMove, shouldRepeatMenuNav, } from "@jgengine/core/ui/menuNav";
+function isTextEntry(target) {
+    const element = target;
+    if (element === null || typeof element.closest !== "function")
+        return false;
+    return element.closest("input, textarea, select, [contenteditable]:not([contenteditable=false])") !== null;
+}
+/**
+ * Bind a menu's focus order to the DOM: arrow keys, WASD, Home/End and a standard gamepad move a
+ * roving focus, Enter/Space/A confirm, Escape/Backspace/B/Start go back. Tab is left to the browser,
+ * so a menu never traps focus, and typing in a text field is never intercepted. The menu is pure
+ * state + listeners — it unmounts with the screen, so it costs nothing during play.
+ *
+ * @capability use-menu-nav keyboard and gamepad focus navigation for a menu — roving focus order, confirm/back, disabled-item skipping, no focus trap
+ */
+export function useMenuNav({ ids, columns = 1, wrap = true, disabled, initialId, enabled = true, onConfirm, onBack, gamepad = true, repeat, }) {
+    const disabledIndices = useMemo(() => {
+        if (disabled === undefined || disabled.length === 0)
+            return undefined;
+        return disabled.map((id) => ids.indexOf(id)).filter((index) => index >= 0);
+    }, [disabled, ids]);
+    const firstEnabled = useMemo(() => {
+        for (let index = 0; index < ids.length; index += 1) {
+            if (disabledIndices === undefined || !disabledIndices.includes(index))
+                return index;
+        }
+        return -1;
+    }, [ids, disabledIndices]);
+    const [activeIndex, setActiveIndex] = useState(() => {
+        const initial = initialId === undefined ? -1 : ids.indexOf(initialId);
+        return initial >= 0 ? initial : firstEnabled;
+    });
+    const activeId = menuNavIdAt(ids, activeIndex);
+    const idsRef = useRef(ids);
+    idsRef.current = ids;
+    const activeIndexRef = useRef(activeIndex);
+    activeIndexRef.current = activeIndex;
+    const callbacks = useRef({ onConfirm, onBack });
+    callbacks.current = { onConfirm, onBack };
+    const elements = useRef(new Map());
+    const pendingFocus = useRef(true);
+    const focusActive = useCallback(() => {
+        const id = menuNavIdAt(idsRef.current, activeIndexRef.current);
+        if (id === null)
+            return;
+        elements.current.get(id)?.focus({ preventScroll: true });
+    }, []);
+    const move = useCallback((direction) => {
+        const layout = {
+            count: idsRef.current.length,
+            columns,
+            wrap,
+            ...(disabledIndices === undefined ? {} : { disabled: disabledIndices }),
+        };
+        const next = menuNavMove(activeIndexRef.current, direction, layout);
+        if (next < 0 || next === activeIndexRef.current)
+            return;
+        pendingFocus.current = true;
+        setActiveIndex(next);
+    }, [columns, disabledIndices, wrap]);
+    const setActive = useCallback((id) => {
+        const index = menuNavIndex(idsRef.current, id);
+        if (index < 0)
+            return;
+        pendingFocus.current = false;
+        setActiveIndex(index);
+    }, []);
+    const activate = useCallback((id) => {
+        if (id !== null)
+            callbacks.current.onConfirm?.(id);
+    }, []);
+    const runIntent = useCallback((intent) => {
+        if (intent === "confirm")
+            activate(menuNavIdAt(idsRef.current, activeIndexRef.current));
+        else if (intent === "back")
+            callbacks.current.onBack?.();
+        else
+            move(intent);
+    }, [activate, move]);
+    const moveRef = useRef(move);
+    moveRef.current = move;
+    const runIntentRef = useRef(runIntent);
+    runIntentRef.current = runIntent;
+    const repeatRef = useRef(repeat);
+    repeatRef.current = repeat;
+    useEffect(() => {
+        if (!pendingFocus.current)
+            return;
+        pendingFocus.current = false;
+        focusActive();
+    }, [activeIndex, focusActive]);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        pendingFocus.current = true;
+        focusActive();
+    }, [enabled, focusActive]);
+    useEffect(() => {
+        const index = ids.indexOf(activeId ?? "");
+        if (activeId !== null && index >= 0)
+            return;
+        setActiveIndex(firstEnabled);
+    }, [ids, activeId, firstEnabled]);
+    const onKeyDown = useCallback((event) => {
+        if (!enabled || event.defaultPrevented || isTextEntry(event.target))
+            return;
+        const intent = menuIntentForKey(event.code);
+        if (intent === null)
+            return;
+        const target = event.target;
+        const nativeActivate = intent === "confirm" &&
+            typeof target.closest === "function" &&
+            target.closest("button, a[href], [role='button'], summary") !== null;
+        if (intent === "back") {
+            if (callbacks.current.onBack === undefined)
+                return;
+            event.preventDefault();
+            callbacks.current.onBack();
+            return;
+        }
+        if (nativeActivate)
+            return;
+        event.preventDefault();
+        runIntent(intent);
+    }, [enabled, runIntent]);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        if (typeof window === "undefined")
+            return;
+        const onWindowKeyDown = (event) => {
+            if (event.defaultPrevented || isTextEntry(event.target))
+                return;
+            const target = event.target;
+            if (target !== null && typeof target.closest === "function" && target.closest("[data-jg-menu-nav]") !== null)
+                return;
+            const intent = menuIntentForKey(event.code);
+            if (intent === null)
+                return;
+            if (intent === "back") {
+                if (callbacks.current.onBack === undefined)
+                    return;
+                event.preventDefault();
+                callbacks.current.onBack();
+                return;
+            }
+            event.preventDefault();
+            runIntent(intent);
+        };
+        window.addEventListener("keydown", onWindowKeyDown);
+        return () => window.removeEventListener("keydown", onWindowKeyDown);
+    }, [enabled, runIntent]);
+    useEffect(() => {
+        if (!enabled || !gamepad)
+            return;
+        if (typeof navigator === "undefined" || typeof navigator.getGamepads !== "function")
+            return;
+        if (typeof requestAnimationFrame !== "function")
+            return;
+        const held = new Map();
+        let stick = null;
+        let previousPressed = new Set();
+        let frame = 0;
+        const poll = () => {
+            frame = requestAnimationFrame(poll);
+            if (typeof document !== "undefined" && document.visibilityState === "hidden")
+                return;
+            if (isTextEntry(document.activeElement))
+                return;
+            const pads = navigator.getGamepads();
+            const now = typeof performance !== "undefined" ? performance.now() : Date.now();
+            let pad = null;
+            for (const candidate of pads) {
+                if (candidate !== null && candidate.connected) {
+                    pad = candidate;
+                    break;
+                }
+            }
+            if (pad === null) {
+                held.clear();
+                previousPressed = new Set();
+                stick = null;
+                return;
+            }
+            const pressed = new Set();
+            for (let button = 0; button < pad.buttons.length; button += 1) {
+                if (pad.buttons[button]?.pressed === true)
+                    pressed.add(button);
+            }
+            for (const button of pressed) {
+                const intent = menuIntentForPadButton(button);
+                if (intent === null)
+                    continue;
+                const isNew = !previousPressed.has(button);
+                const record = held.get(button);
+                if (intent === "confirm" || intent === "back") {
+                    if (isNew)
+                        runIntent(intent);
+                    continue;
+                }
+                if (isNew) {
+                    held.set(button, { pressedAt: now, lastFiredAt: now });
+                    moveRef.current(intent);
+                    continue;
+                }
+                if (record !== undefined && shouldRepeatMenuNav(now, record, repeatRef.current)) {
+                    record.lastFiredAt = now;
+                    moveRef.current(intent);
+                }
+            }
+            for (const button of [...held.keys()])
+                if (!pressed.has(button))
+                    held.delete(button);
+            previousPressed = pressed;
+            const horizontal = menuIntentForPadAxis(0, pad.axes[0] ?? 0);
+            const vertical = menuIntentForPadAxis(1, pad.axes[1] ?? 0);
+            const axisIntent = horizontal ?? vertical;
+            if (axisIntent === null) {
+                stick = null;
+                return;
+            }
+            if (stick === null || stick.intent !== axisIntent) {
+                stick = { intent: axisIntent, pressedAt: now, lastFiredAt: now };
+                moveRef.current(axisIntent);
+                return;
+            }
+            if (shouldRepeatMenuNav(now, stick, repeatRef.current)) {
+                stick.lastFiredAt = now;
+                moveRef.current(axisIntent);
+            }
+        };
+        frame = requestAnimationFrame(poll);
+        return () => cancelAnimationFrame(frame);
+    }, [enabled, gamepad]);
+    const itemProps = useCallback((id) => {
+        const active = id === activeId;
+        return {
+            "data-jg-menu-item": id,
+            tabIndex: active ? 0 : -1,
+            ...(active ? { "aria-current": "true" } : {}),
+            ref: (node) => {
+                if (node === null)
+                    elements.current.delete(id);
+                else
+                    elements.current.set(id, node);
+            },
+            onPointerEnter: () => setActive(id),
+            onFocus: () => setActive(id),
+        };
+    }, [activeId, setActive]);
+    const containerProps = useMemo(() => ({
+        "data-jg-menu-nav": "",
+        onKeyDown,
+    }), [onKeyDown]);
+    return { activeId, setActive, move, itemProps, containerProps };
+}

package/dist/menuScreen.d.ts

@@ -0,0 +1,43 @@
+import { type CSSProperties, type ReactNode } from "react";
+/** Which motion a {@link MenuScreen} uses when it enters and leaves. */
+export type MenuScreenTransition = "fade" | "slide" | "scale" | "none";
+/** How much a {@link MenuScreen} dims the scene behind it. `none` keeps a live 3D scene fully visible. */
+export type MenuScreenScrim = "none" | "dim" | "blur";
+/** Props for {@link MenuScreen}. */
+export interface MenuScreenProps {
+    /** Open state the game owns. Closing runs the exit animation, then unmounts. Default true. */
+    open?: boolean;
+    /** Enter/exit motion. Default `"fade"`. */
+    transition?: MenuScreenTransition;
+    /** Dim/blur treatment over the scene behind. Default `"dim"`. */
+    scrim?: MenuScreenScrim;
+    /** Enter duration in ms. Default 220. */
+    enterMs?: number;
+    /** Exit duration in ms. Default 160. */
+    exitMs?: number;
+    /** Force motion off (reduced motion is also read from the accessibility preference and the OS). */
+    reducedMotion?: boolean;
+    /** Accessible name of the screen. */
+    label?: string;
+    /** `role` for the screen element. Default `"dialog"`. */
+    role?: string;
+    /** Full-bleed layer painted behind the menu content — a live canvas, a poster, or a preview. */
+    backdrop?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    contentClassName?: string;
+    contentStyle?: CSSProperties;
+    children?: ReactNode;
+    /** Called once the exit animation finished and the screen unmounted. */
+    onClosed?: () => void;
+}
+/**
+ * One animated screen of a game front-end: full-bleed, laid out by the game, with an enter/exit
+ * animation that runs on transform/opacity only (no layout, no frame hitch) and unmounts when the
+ * exit finishes. The scrim is translucent and the optional `backdrop` slot paints behind the content,
+ * so a live 3D scene stays visible behind a title, pause or settings screen. Durations come from the
+ * caller or collapse to zero under reduced motion.
+ *
+ * @capability menu-screen animated enter/exit menu screen over a live scene, with translucent scrim, backdrop slot, reduced-motion support and exit unmount
+ */
+export declare function MenuScreen({ open, transition, scrim, enterMs, exitMs, reducedMotion, label, role, backdrop, className, style, contentClassName, contentStyle, children, onClosed, }: MenuScreenProps): ReactNode;

package/dist/menuScreen.js

@@ -0,0 +1,98 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useSyncExternalStore } from "react";
+import { createMenuTransition, menuTransitionDurations } from "@jgengine/core/ui/menuTransition";
+import { useReducedMotion } from "./accessibility.js";
+const KEYFRAMES = {
+    fade: { enter: "jg-fade-in", exit: "jg-fade-out" },
+    slide: { enter: "jg-slide-up", exit: "jg-fade-out" },
+    scale: { enter: "jg-panel-in", exit: "jg-panel-out" },
+};
+const SCRIMS = {
+    none: {},
+    dim: { background: "radial-gradient(140% 130% at 50% 45%, rgba(0,0,0,0.34), rgba(0,0,0,0.78))" },
+    blur: {
+        background: "radial-gradient(140% 130% at 50% 45%, rgba(0,0,0,0.38), rgba(0,0,0,0.8))",
+        backdropFilter: "blur(4px)",
+        WebkitBackdropFilter: "blur(4px)",
+    },
+};
+function now() {
+    return typeof performance === "undefined" ? Date.now() : performance.now();
+}
+/**
+ * One animated screen of a game front-end: full-bleed, laid out by the game, with an enter/exit
+ * animation that runs on transform/opacity only (no layout, no frame hitch) and unmounts when the
+ * exit finishes. The scrim is translucent and the optional `backdrop` slot paints behind the content,
+ * so a live 3D scene stays visible behind a title, pause or settings screen. Durations come from the
+ * caller or collapse to zero under reduced motion.
+ *
+ * @capability menu-screen animated enter/exit menu screen over a live scene, with translucent scrim, backdrop slot, reduced-motion support and exit unmount
+ */
+export function MenuScreen({ open = true, transition = "fade", scrim = "dim", enterMs = 220, exitMs = 160, reducedMotion, label, role = "dialog", backdrop, className, style, contentClassName, contentStyle, children, onClosed, }) {
+    const prefersReduced = useReducedMotion();
+    const motion = reducedMotion === undefined ? prefersReduced : reducedMotion || prefersReduced;
+    const machine = useMemo(() => {
+        const config = { enterMs, exitMs, reducedMotion: motion };
+        const initial = open
+            ? { phase: menuTransitionDurations(config).enter === 0 ? "open" : "enter", since: now() }
+            : undefined;
+        return createMenuTransition(config, initial);
+        // `open` is read once for the initial phase; later changes are driven by the effect below.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [enterMs, exitMs, motion]);
+    const phase = useSyncExternalStore(machine.subscribe, () => machine.state().phase, () => machine.state().phase);
+    useEffect(() => {
+        if (open)
+            machine.open(now());
+        else
+            machine.close(now());
+    }, [open, machine]);
+    useEffect(() => {
+        if (phase !== "enter" && phase !== "exit")
+            return;
+        if (typeof requestAnimationFrame !== "function") {
+            machine.tick(now());
+            return;
+        }
+        let frame = requestAnimationFrame(function tick() {
+            machine.tick(now());
+            frame = requestAnimationFrame(tick);
+        });
+        return () => cancelAnimationFrame(frame);
+    }, [phase, machine]);
+    useEffect(() => {
+        if (phase === "closed" && !open)
+            onClosed?.();
+    }, [phase, open, onClosed]);
+    if (phase === "closed")
+        return null;
+    const durations = menuTransitionDurations({ enterMs, exitMs, reducedMotion: motion });
+    const frames = transition === "none" ? null : KEYFRAMES[transition];
+    const contentAnimation = frames === null || phase === "open"
+        ? {}
+        : {
+            animationName: phase === "enter" ? frames.enter : frames.exit,
+            animationDuration: `${phase === "enter" ? durations.enter : durations.exit}ms`,
+            animationTimingFunction: "var(--jg-ease-out, cubic-bezier(0.16, 1, 0.3, 1))",
+            animationFillMode: "both",
+        };
+    const scrimAnimation = phase === "open"
+        ? {}
+        : {
+            animationName: phase === "enter" ? "jg-fade-in" : "jg-fade-out",
+            animationDuration: `${phase === "enter" ? durations.enter : durations.exit}ms`,
+            animationTimingFunction: "var(--jg-ease-out, cubic-bezier(0.16, 1, 0.3, 1))",
+            animationFillMode: "both",
+        };
+    return (_jsxs("div", { "data-jg-menu-screen": "", "data-phase": phase, "data-transition": transition, "data-scrim": scrim, role: role, "aria-label": label, "aria-modal": scrim === "none" ? undefined : true, className: className, style: {
+            position: "absolute",
+            inset: 0,
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            overflow: "hidden",
+            color: "var(--jg-text, #f5f7fa)",
+            fontFamily: "var(--jg-font-body, inherit)",
+            ...style,
+        }, children: [backdrop === undefined ? null : (_jsx("div", { "data-jg-menu-backdrop": "", "aria-hidden": "true", style: { position: "absolute", inset: 0, pointerEvents: "none" }, children: backdrop })), _jsx("div", { "data-jg-menu-scrim": "", "aria-hidden": "true", style: { position: "absolute", inset: 0, pointerEvents: "none", ...SCRIMS[scrim], ...scrimAnimation } }), _jsx("div", { "data-jg-menu-content": "", className: contentClassName, style: { position: "relative", pointerEvents: "auto", ...contentAnimation, ...contentStyle }, children: children })] }));
+}

package/dist/modals.js

@@ -8,6 +8,7 @@ import { HudButton } from "./hudButton.js";
 import { useHudInteract } from "./hudInteract.js";
 import { HudSurface } from "./hudSurface.js";
 import { hudType } from "./hudTokens.js";
+import { useMenuNav } from "./menuNav.js";
 import { usePresence } from "./presence.js";
 /**
  * Subscribe to a modal stack and re-render on every change, returning the active modal and depth.
@@ -110,5 +111,16 @@ const PAUSE_DANGER_ITEM = { ...PAUSE_ITEM, color: "var(--jg-danger, #e5484d)", b
  * @capability pause-menu reskinnable pause-menu building block — Resume plus a game-filled Settings/Quit slot list, HudTheme-driven
  */
 export function PauseMenu({ title = "Paused", onResume, resumeLabel = "Resume", items = [], width = 300, className, style, }) {
-    return (_jsxs(HudSurface, { elevation: "modal", width: width, padding: 20, className: className, style: style, children: [_jsx("div", { "data-pause-title": "", style: PAUSE_TITLE, children: title }), _jsx(HudButton, { "data-pause-resume": "", cue: "resume", variant: "primary", size: "lg", block: true, onClick: onResume, children: resumeLabel }), items.map((item) => (_jsx(HudButton, { "data-pause-item": item.id, cue: `pause:${item.id}`, size: "lg", block: true, onClick: item.onSelect, disabled: item.disabled, style: item.danger ? PAUSE_DANGER_ITEM : PAUSE_ITEM, children: item.label }, item.id)))] }));
+    const nav = useMenuNav({
+        ids: ["resume", ...items.map((item) => item.id)],
+        disabled: items.filter((item) => item.disabled === true).map((item) => item.id),
+        onBack: onResume,
+        onConfirm: (id) => {
+            if (id === "resume")
+                onResume();
+            else
+                items.find((item) => item.id === id)?.onSelect();
+        },
+    });
+    return (_jsxs(HudSurface, { elevation: "modal", width: width, padding: 20, className: className, style: style, ...nav.containerProps, children: [_jsx("div", { "data-pause-title": "", style: PAUSE_TITLE, children: title }), _jsx(HudButton, { ...nav.itemProps("resume"), "data-pause-resume": "", cue: "resume", variant: "primary", size: "lg", block: true, onClick: onResume, children: resumeLabel }), items.map((item) => (_jsx(HudButton, { ...nav.itemProps(item.id), "data-pause-item": item.id, cue: `pause:${item.id}`, size: "lg", block: true, onClick: item.onSelect, disabled: item.disabled, style: item.danger ? PAUSE_DANGER_ITEM : PAUSE_ITEM, children: item.label }, item.id)))] }));
 }