@dloizides/game-input 1.4.0 → 1.5.1

package/CHANGELOG.md

@@ -1,36 +1,45 @@
-# Changelog
-
-All notable changes to `@dloizides/game-input` are documented here.
-
-## 1.4.0
-
-GI-HAPTICS-1 "Haptics vibrate only after a user activation".
-
-- `createHaptics` no longer calls `navigator.vibrate` before a user gesture (Chrome blocks it and logs an
-  intervention). Gate: `navigator.userActivation.hasBeenActive` where present, else a capture-phase latch on
-  the first `pointerdown` / `keydown` / `touchstart` of `activationTarget` (new option, default `globalThis`).
-- The enable-confirmation tick follows the same gate. Disabled and unsupported stay silent no-ops.
-- New exports: `ActivationTarget` type, `USER_ACTIVATION_EVENTS`.
-
-## 1.3.0
-
-Standard Gamepad action poller (first consumer: NextGame console-dashboard UI).
-
-- `stepPad(prev, next, repeat, now)` — pure per-frame reducer: face/shoulder buttons fire on the
-  rising edge by W3C Standard POSITION; D-pad or left stick (0.5 dead-zone, dominant axis) fires
-  once, repeats after 380 ms, then every 110 ms; release resets the repeat.
-- `createGamepadPoller({ getPads, requestFrame, cancelFrame, onAction })` — injectable rAF loop over
-  the first connected pad; a disappearing pad resets state; `stop()` is safe from inside `onAction`.
-- `PAD_ACTIONS`, `STANDARD_BUTTON`, `IDLE_REPEAT` + types `PadAction`, `PadSnapshot`, `RepeatState`,
-  `PadLike`, `GamepadPollerOptions`.
-
-## 1.0.0
-
-Initial release — the haptics primitive of the C4 games shared kit.
-
-- `createHaptics(options)` — player-toggleable, always-safe Web Vibration API wrapper
-  (localStorage-gated, structural/injectable `navigator` + `storage`, never throws into the game loop).
-- `HAPTIC_PATTERNS` — shared semantic vibration vocabulary (tap/select/lock/bump/navigate/success/error/loss/reveal).
-- Zero runtime dependencies; isomorphic; dual CJS/ESM; 100% test coverage.
-
-Extracted from Aurora's `src/input/haptics.ts`. First consumers: Aurora (re-export shim) and Morphe (new adoption).
+# Changelog
+
+All notable changes to `@dloizides/game-input` are documented here.
+
+## 1.5.1
+
+- Pad back dispatches Escape at the focused element so a dialog host that handles Escape and stops propagation still closes (NAV-1).
+
+## 1.5.0
+
+- `createMenuNav`: one menu focus engine for arrow keys (capture phase) and pad actions; top-most dialog owns focus, focus restored on close, sliders/selects step on Left/Right, text fields keep arrows until Escape/B, `data-nav-input` on <html> (NAV-1 "Every game menu works with arrow keys and controller").
+- `MENU_FOCUSABLE_SELECTOR`, `menuRoot`, `focusables`, `pickTarget` exported (pickTarget moved from Surge).
+
+## 1.4.0
+
+GI-HAPTICS-1 "Haptics vibrate only after a user activation".
+
+- `createHaptics` no longer calls `navigator.vibrate` before a user gesture (Chrome blocks it and logs an
+  intervention). Gate: `navigator.userActivation.hasBeenActive` where present, else a capture-phase latch on
+  the first `pointerdown` / `keydown` / `touchstart` of `activationTarget` (new option, default `globalThis`).
+- The enable-confirmation tick follows the same gate. Disabled and unsupported stay silent no-ops.
+- New exports: `ActivationTarget` type, `USER_ACTIVATION_EVENTS`.
+
+## 1.3.0
+
+Standard Gamepad action poller (first consumer: NextGame console-dashboard UI).
+
+- `stepPad(prev, next, repeat, now)` — pure per-frame reducer: face/shoulder buttons fire on the
+  rising edge by W3C Standard POSITION; D-pad or left stick (0.5 dead-zone, dominant axis) fires
+  once, repeats after 380 ms, then every 110 ms; release resets the repeat.
+- `createGamepadPoller({ getPads, requestFrame, cancelFrame, onAction })` — injectable rAF loop over
+  the first connected pad; a disappearing pad resets state; `stop()` is safe from inside `onAction`.
+- `PAD_ACTIONS`, `STANDARD_BUTTON`, `IDLE_REPEAT` + types `PadAction`, `PadSnapshot`, `RepeatState`,
+  `PadLike`, `GamepadPollerOptions`.
+
+## 1.0.0
+
+Initial release — the haptics primitive of the C4 games shared kit.
+
+- `createHaptics(options)` — player-toggleable, always-safe Web Vibration API wrapper
+  (localStorage-gated, structural/injectable `navigator` + `storage`, never throws into the game loop).
+- `HAPTIC_PATTERNS` — shared semantic vibration vocabulary (tap/select/lock/bump/navigate/success/error/loss/reveal).
+- Zero runtime dependencies; isomorphic; dual CJS/ESM; 100% test coverage.
+
+Extracted from Aurora's `src/input/haptics.ts`. First consumers: Aurora (re-export shim) and Morphe (new adoption).

package/dist/index.d.mts

@@ -70,6 +70,63 @@ declare function stepPad(prev: PadSnapshot | null, next: PadSnapshot, repeat: Re
     repeat: RepeatState;
 };
 
+interface MenuNavOptions {
+    /** The game's base menu root when no dialog is open; null = no menu (e.g. during play). */
+    baseRoot: () => HTMLElement | null;
+    /** True while input must not move focus (e.g. a remap capture). Default: never. */
+    suspended?: () => boolean;
+    /** Where focus goes when a root opens. Default: [data-menu-default], else the first control. */
+    initialFocus?: (root: HTMLElement) => HTMLElement | null;
+}
+interface MenuNav {
+    /** Feed one pad action from stepPad (the game keeps its own poller). */
+    pad(action: PadAction): void;
+    /** Re-evaluate the root and place focus (call after the game opens a screen). */
+    refresh(): void;
+    dispose(): void;
+}
+/** One focus engine for every game menu: arrow keys (capture phase), pad actions, dialogs on top, sliders and text fields. */
+declare function createMenuNav(options: MenuNavOptions): MenuNav;
+
+/** Every control a menu walker must be able to reach (shared with @dloizides/game-e2e). */
+declare const MENU_FOCUSABLE_SELECTOR: string;
+declare const DIALOG_SELECTOR = "[role=\"dialog\"]";
+declare const MENU_DEFAULT_ATTR = "data-menu-default";
+declare const NAV_INPUT_ATTR = "data-nav-input";
+declare const NAV_INPUT: {
+    readonly key: "key";
+    readonly pad: "pad";
+};
+type NavInput = (typeof NAV_INPUT)[keyof typeof NAV_INPUT];
+
+/** True when the element has a layout box and no hidden, inert or aria-hidden ancestor. */
+declare function isShown(el: Element): boolean;
+/** The visible, enabled controls inside root, in DOM order. */
+declare function focusables(root: HTMLElement): HTMLElement[];
+/** The [data-menu-default] control, else the first control, else null. */
+declare function defaultInitialFocus(root: HTMLElement): HTMLElement | null;
+
+/** Top-most visible dialog (aria-modal preferred, last in DOM wins), else the visible base root, else null. */
+declare function menuRoot(baseRoot: () => HTMLElement | null): HTMLElement | null;
+
+interface Box {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+declare const NAV_DIRS: {
+    readonly up: "arrowup";
+    readonly down: "arrowdown";
+    readonly left: "arrowleft";
+    readonly right: "arrowright";
+};
+type NavDir = (typeof NAV_DIRS)[keyof typeof NAV_DIRS];
+/** The direction an arrow key names (case-insensitive), or null for any other key. */
+declare const navDir: (key: string) => NavDir | null;
+/** Index of the nearest box from `from` in `dir`; wraps in list order when none lies that way; -1 for no boxes. */
+declare function pickTarget(boxes: readonly Box[], from: number, dir: NavDir): number;
+
 /**
  * A vibration pattern: a single duration in ms, or an on/off pattern
  * (`[wait, on, off, on, ...]`) exactly as the Web Vibration API expects.
@@ -151,4 +208,4 @@ type HapticIntent = 'tap' | 'select' | 'lock' | 'bump' | 'navigate' | 'success'
  */
 declare const HAPTIC_PATTERNS: Record<HapticIntent, VibrationPattern>;
 
-export { type ActivationTarget, DEFAULT_ENABLE_CONFIRMATION, DEFAULT_HAPTICS_STORAGE_KEY, type GamepadPollerOptions, HAPTIC_PATTERNS, type HapticIntent, type Haptics, type HapticsOptions, type HapticsStorage, IDLE_REPEAT, PAD_ACTIONS, type PadAction, type PadLike, type PadSnapshot, type RepeatState, STANDARD_BUTTON, USER_ACTIVATION_EVENTS, type VibrationCapable, type VibrationPattern, createGamepadPoller, createHaptics, stepPad };
+export { type ActivationTarget, DEFAULT_ENABLE_CONFIRMATION, DEFAULT_HAPTICS_STORAGE_KEY, DIALOG_SELECTOR, type GamepadPollerOptions, HAPTIC_PATTERNS, type HapticIntent, type Haptics, type HapticsOptions, type HapticsStorage, IDLE_REPEAT, MENU_DEFAULT_ATTR, MENU_FOCUSABLE_SELECTOR, type MenuNav, type MenuNavOptions, NAV_DIRS, NAV_INPUT, NAV_INPUT_ATTR, type Box as NavBox, type NavDir, type NavInput, PAD_ACTIONS, type PadAction, type PadLike, type PadSnapshot, type RepeatState, STANDARD_BUTTON, USER_ACTIVATION_EVENTS, type VibrationCapable, type VibrationPattern, createGamepadPoller, createHaptics, createMenuNav, defaultInitialFocus, focusables, isShown, menuRoot, navDir, pickTarget, stepPad };

package/dist/index.d.ts

@@ -70,6 +70,63 @@ declare function stepPad(prev: PadSnapshot | null, next: PadSnapshot, repeat: Re
     repeat: RepeatState;
 };
 
+interface MenuNavOptions {
+    /** The game's base menu root when no dialog is open; null = no menu (e.g. during play). */
+    baseRoot: () => HTMLElement | null;
+    /** True while input must not move focus (e.g. a remap capture). Default: never. */
+    suspended?: () => boolean;
+    /** Where focus goes when a root opens. Default: [data-menu-default], else the first control. */
+    initialFocus?: (root: HTMLElement) => HTMLElement | null;
+}
+interface MenuNav {
+    /** Feed one pad action from stepPad (the game keeps its own poller). */
+    pad(action: PadAction): void;
+    /** Re-evaluate the root and place focus (call after the game opens a screen). */
+    refresh(): void;
+    dispose(): void;
+}
+/** One focus engine for every game menu: arrow keys (capture phase), pad actions, dialogs on top, sliders and text fields. */
+declare function createMenuNav(options: MenuNavOptions): MenuNav;
+
+/** Every control a menu walker must be able to reach (shared with @dloizides/game-e2e). */
+declare const MENU_FOCUSABLE_SELECTOR: string;
+declare const DIALOG_SELECTOR = "[role=\"dialog\"]";
+declare const MENU_DEFAULT_ATTR = "data-menu-default";
+declare const NAV_INPUT_ATTR = "data-nav-input";
+declare const NAV_INPUT: {
+    readonly key: "key";
+    readonly pad: "pad";
+};
+type NavInput = (typeof NAV_INPUT)[keyof typeof NAV_INPUT];
+
+/** True when the element has a layout box and no hidden, inert or aria-hidden ancestor. */
+declare function isShown(el: Element): boolean;
+/** The visible, enabled controls inside root, in DOM order. */
+declare function focusables(root: HTMLElement): HTMLElement[];
+/** The [data-menu-default] control, else the first control, else null. */
+declare function defaultInitialFocus(root: HTMLElement): HTMLElement | null;
+
+/** Top-most visible dialog (aria-modal preferred, last in DOM wins), else the visible base root, else null. */
+declare function menuRoot(baseRoot: () => HTMLElement | null): HTMLElement | null;
+
+interface Box {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+declare const NAV_DIRS: {
+    readonly up: "arrowup";
+    readonly down: "arrowdown";
+    readonly left: "arrowleft";
+    readonly right: "arrowright";
+};
+type NavDir = (typeof NAV_DIRS)[keyof typeof NAV_DIRS];
+/** The direction an arrow key names (case-insensitive), or null for any other key. */
+declare const navDir: (key: string) => NavDir | null;
+/** Index of the nearest box from `from` in `dir`; wraps in list order when none lies that way; -1 for no boxes. */
+declare function pickTarget(boxes: readonly Box[], from: number, dir: NavDir): number;
+
 /**
  * A vibration pattern: a single duration in ms, or an on/off pattern
  * (`[wait, on, off, on, ...]`) exactly as the Web Vibration API expects.
@@ -151,4 +208,4 @@ type HapticIntent = 'tap' | 'select' | 'lock' | 'bump' | 'navigate' | 'success'
  */
 declare const HAPTIC_PATTERNS: Record<HapticIntent, VibrationPattern>;
 
-export { type ActivationTarget, DEFAULT_ENABLE_CONFIRMATION, DEFAULT_HAPTICS_STORAGE_KEY, type GamepadPollerOptions, HAPTIC_PATTERNS, type HapticIntent, type Haptics, type HapticsOptions, type HapticsStorage, IDLE_REPEAT, PAD_ACTIONS, type PadAction, type PadLike, type PadSnapshot, type RepeatState, STANDARD_BUTTON, USER_ACTIVATION_EVENTS, type VibrationCapable, type VibrationPattern, createGamepadPoller, createHaptics, stepPad };
+export { type ActivationTarget, DEFAULT_ENABLE_CONFIRMATION, DEFAULT_HAPTICS_STORAGE_KEY, DIALOG_SELECTOR, type GamepadPollerOptions, HAPTIC_PATTERNS, type HapticIntent, type Haptics, type HapticsOptions, type HapticsStorage, IDLE_REPEAT, MENU_DEFAULT_ATTR, MENU_FOCUSABLE_SELECTOR, type MenuNav, type MenuNavOptions, NAV_DIRS, NAV_INPUT, NAV_INPUT_ATTR, type Box as NavBox, type NavDir, type NavInput, PAD_ACTIONS, type PadAction, type PadLike, type PadSnapshot, type RepeatState, STANDARD_BUTTON, USER_ACTIVATION_EVENTS, type VibrationCapable, type VibrationPattern, createGamepadPoller, createHaptics, createMenuNav, defaultInitialFocus, focusables, isShown, menuRoot, navDir, pickTarget, stepPad };

package/dist/index.js

@@ -122,6 +122,369 @@ function createGamepadPoller(opts) {
   };
 }
 
+// src/menu/constants.ts
+var MENU_FOCUSABLE_SELECTOR = [
+  "button",
+  "a[href]",
+  "input",
+  "select",
+  "textarea",
+  '[role="button"]',
+  '[role="tab"]',
+  '[role="option"]',
+  '[role="slider"]',
+  '[role="switch"]',
+  '[role="checkbox"]',
+  '[role="radio"]',
+  '[tabindex="0"]'
+].join(", ");
+var NATIVE_FOCUSABLE_SELECTOR = "button, input, select, textarea, a[href]";
+var DIALOG_SELECTOR = '[role="dialog"]';
+var HIDDEN_ANCESTOR_SELECTOR = '[hidden], [inert], [aria-hidden="true"]';
+var MENU_DEFAULT_ATTR = "data-menu-default";
+var NAV_INPUT_ATTR = "data-nav-input";
+var NAV_INPUT = { key: "key", pad: "pad" };
+var OBSERVED_ATTRIBUTES = ["hidden", "class", "style", "aria-hidden", "aria-modal", "inert", "open"];
+var ESCAPE_KEY = "Escape";
+var ENTER_KEY = "Enter";
+
+// src/menu/controlKind.ts
+var NON_TEXT_INPUTS = ["button", "submit", "reset", "color", "file", "image"];
+var TOGGLE_ROLES = ["checkbox", "switch", "radio"];
+function inputKind(el) {
+  const type = el.type;
+  if (type === "range") {
+    return "slider" /* Slider */;
+  }
+  if (type === "checkbox" || type === "radio") {
+    return "toggle" /* Toggle */;
+  }
+  return NON_TEXT_INPUTS.includes(type) ? "button" /* Button */ : "textField" /* TextField */;
+}
+function controlKind(el) {
+  if (el instanceof HTMLInputElement) {
+    return inputKind(el);
+  }
+  if (el instanceof HTMLTextAreaElement) {
+    return "textField" /* TextField */;
+  }
+  if (el instanceof HTMLSelectElement) {
+    return "select" /* Select */;
+  }
+  const role = el.getAttribute("role") ?? "";
+  if (role === "slider") {
+    return "slider" /* Slider */;
+  }
+  return TOGGLE_ROLES.includes(role) ? "toggle" /* Toggle */ : "button" /* Button */;
+}
+var isTextField = (el) => controlKind(el) === "textField" /* TextField */;
+function isStepper(el) {
+  const kind = controlKind(el);
+  return kind === "slider" /* Slider */ || kind === "select" /* Select */;
+}
+function needsSyntheticClick(el) {
+  const kind = controlKind(el);
+  const clickable = kind === "button" /* Button */ || kind === "toggle" /* Toggle */;
+  return clickable && !el.matches(NATIVE_FOCUSABLE_SELECTOR);
+}
+
+// src/menu/focusables.ts
+function isShown(el) {
+  return el.getClientRects().length > 0 && el.closest(HIDDEN_ANCESTOR_SELECTOR) === null;
+}
+var isDisabled = (el) => el.disabled === true;
+function focusables(root) {
+  return Array.from(root.querySelectorAll(MENU_FOCUSABLE_SELECTOR)).filter((el) => isShown(el) && !isDisabled(el));
+}
+function defaultInitialFocus(root) {
+  const list = focusables(root);
+  return list.find((el) => el.hasAttribute(MENU_DEFAULT_ATTR)) ?? list[0] ?? null;
+}
+
+// src/menu/menuRoot.ts
+function menuRoot(baseRoot) {
+  const dialogs = Array.from(document.querySelectorAll(DIALOG_SELECTOR)).filter(isShown);
+  const modal = dialogs.filter((d) => d.getAttribute("aria-modal") === "true");
+  const top = (modal.length > 0 ? modal : dialogs).pop();
+  if (top !== void 0) {
+    return top;
+  }
+  const base = baseRoot();
+  return base !== null && isShown(base) ? base : null;
+}
+
+// src/menu/pickTarget.ts
+var NAV_DIRS = { up: "arrowup", down: "arrowdown", left: "arrowleft", right: "arrowright" };
+var NAV_KEYS = Object.values(NAV_DIRS);
+var CROSS_WEIGHT = 2;
+var SLACK = 1;
+var navDir = (key) => NAV_KEYS.includes(key.toLowerCase()) ? key.toLowerCase() : null;
+var centre = (b) => ({ cx: b.x + b.w / 2, cy: b.y + b.h / 2 });
+function cost(a, b, dir) {
+  const p = centre(a);
+  const q = centre(b);
+  const dx = q.cx - p.cx;
+  const dy = q.cy - p.cy;
+  const vertical = dir === NAV_DIRS.up || dir === NAV_DIRS.down;
+  const along = vertical ? dir === NAV_DIRS.down ? dy : -dy : dir === NAV_DIRS.right ? dx : -dx;
+  if (along <= SLACK) {
+    return null;
+  }
+  return along + CROSS_WEIGHT * Math.abs(vertical ? dx : dy);
+}
+function pickTarget(boxes, from, dir) {
+  if (boxes.length === 0) {
+    return -1;
+  }
+  if (from < 0 || from >= boxes.length) {
+    return 0;
+  }
+  const origin = boxes[from];
+  let best = -1;
+  let bestCost = Infinity;
+  boxes.forEach((b, i) => {
+    const c = i === from ? null : cost(origin, b, dir);
+    if (c !== null && c < bestCost) {
+      best = i;
+      bestCost = c;
+    }
+  });
+  if (best >= 0) {
+    return best;
+  }
+  const step = dir === NAV_DIRS.down || dir === NAV_DIRS.right ? 1 : -1;
+  return (from + step + boxes.length) % boxes.length;
+}
+
+// src/menu/stepControl.ts
+var DEFAULT_MAX = 100;
+var num = (raw, fallback) => {
+  const n = parseFloat(raw ?? "");
+  return Number.isFinite(n) ? n : fallback;
+};
+function clampStep(value, delta, min, max, step) {
+  const decimals = (String(step).split(".")[1] ?? "").length;
+  return Math.min(max, Math.max(min, Number((value + delta * step).toFixed(decimals))));
+}
+function apply(el, current, next, write) {
+  if (next === current) {
+    return;
+  }
+  write(next);
+  el.dispatchEvent(new Event("input", { bubbles: true }));
+  el.dispatchEvent(new Event("change", { bubbles: true }));
+}
+function stepControl(el, delta) {
+  if (el instanceof HTMLInputElement) {
+    const value = num(el.value, 0);
+    const next = clampStep(value, delta, num(el.min, 0), num(el.max, DEFAULT_MAX), num(el.step, 1));
+    apply(el, value, next, (v) => {
+      el.value = String(v);
+    });
+  } else if (el instanceof HTMLSelectElement) {
+    const next = Math.min(el.options.length - 1, Math.max(0, el.selectedIndex + delta));
+    apply(el, el.selectedIndex, next, (v) => {
+      el.selectedIndex = v;
+    });
+  } else {
+    const value = num(el.getAttribute("aria-valuenow"), 0);
+    const next = clampStep(value, delta, num(el.getAttribute("aria-valuemin"), 0), num(el.getAttribute("aria-valuemax"), DEFAULT_MAX), num(el.getAttribute("data-step"), 1));
+    apply(el, value, next, (v) => el.setAttribute("aria-valuenow", String(v)));
+  }
+}
+
+// src/menu/navActions.ts
+var boxOf = (el) => {
+  const r = el.getBoundingClientRect();
+  return { x: r.left, y: r.top, w: r.width, h: r.height };
+};
+function focusControl(el) {
+  if (!el.matches(NATIVE_FOCUSABLE_SELECTOR) && !el.hasAttribute("tabindex")) {
+    el.setAttribute("tabindex", "-1");
+  }
+  el.focus({ preventScroll: true });
+  if (typeof el.scrollIntoView === "function") {
+    el.scrollIntoView({ block: "nearest" });
+  }
+}
+function activeIn(root) {
+  const a = document.activeElement;
+  return a instanceof HTMLElement && a !== root && root.contains(a) ? a : null;
+}
+function focusInitial(root, initial) {
+  const target = initial(root);
+  if (target === null) {
+    return false;
+  }
+  focusControl(target);
+  return true;
+}
+function moveFocus(root, active, dir, initial) {
+  const list = focusables(root);
+  const from = active === null ? -1 : list.indexOf(active);
+  if (from < 0) {
+    return focusInitial(root, initial);
+  }
+  focusControl(list[pickTarget(list.map(boxOf), from, dir)]);
+  return true;
+}
+function direct(root, active, dir, initial) {
+  const horizontal = dir === NAV_DIRS.left || dir === NAV_DIRS.right;
+  if (active !== null && horizontal && isStepper(active)) {
+    stepControl(active, dir === NAV_DIRS.right ? 1 : -1);
+    return true;
+  }
+  return moveFocus(root, active, dir, initial);
+}
+function leaveField(root, field) {
+  const list = focusables(root);
+  const next = list[pickTarget(list.map(boxOf), list.indexOf(field), NAV_DIRS.down)];
+  if (next === field || next === void 0) {
+    field.blur();
+    return;
+  }
+  focusControl(next);
+}
+
+// src/menu/createMenuNav.ts
+var PAD_DIRS = { up: NAV_DIRS.up, down: NAV_DIRS.down, left: NAV_DIRS.left, right: NAV_DIRS.right };
+var isOpen = (el) => el.isConnected && isShown(el);
+var markInput = (kind) => document.documentElement.setAttribute(NAV_INPUT_ATTR, kind);
+var clearInput = () => document.documentElement.removeAttribute(NAV_INPUT_ATTR);
+var sendEscape = () => [document.activeElement, window].find((t) => t !== null).dispatchEvent(new KeyboardEvent("keydown", { key: ESCAPE_KEY, bubbles: true, cancelable: true }));
+function popClosed(stack) {
+  let restore = null;
+  while (stack.length > 0 && !isOpen(stack[stack.length - 1].dialog)) {
+    restore = stack.pop().restore;
+  }
+  return restore;
+}
+function canRestore(restore, root) {
+  return restore !== null && restore.isConnected && root.contains(restore) && isShown(restore);
+}
+function onKey(e, root, initial) {
+  const active = activeIn(root);
+  const dir = navDir(e.key);
+  if (e.key === ESCAPE_KEY) {
+    if (active === null || !isTextField(active)) {
+      return;
+    }
+    e.preventDefault();
+    e.stopImmediatePropagation();
+    leaveField(root, active);
+  } else if (e.key === ENTER_KEY) {
+    if (active === null || !needsSyntheticClick(active)) {
+      return;
+    }
+    e.preventDefault();
+    active.click();
+  } else if (dir !== null) {
+    markInput(NAV_INPUT.key);
+    if (active !== null && isTextField(active)) {
+      return;
+    }
+    if (direct(root, active, dir, initial)) {
+      e.preventDefault();
+    }
+  }
+}
+function onPad(action, root, initial) {
+  const active = root === null ? null : activeIn(root);
+  const dir = PAD_DIRS[action];
+  if (action === PAD_ACTIONS.back) {
+    if (root !== null && active !== null && isTextField(active)) {
+      leaveField(root, active);
+    } else {
+      sendEscape();
+    }
+  } else if (root === null) {
+    return;
+  } else if (dir !== void 0) {
+    direct(root, active, dir, initial);
+  } else if (action === PAD_ACTIONS.confirm) {
+    if (active === null) {
+      focusInitial(root, initial);
+    } else if (isTextField(active)) {
+      focusControl(active);
+    } else {
+      active.click();
+    }
+  }
+}
+function createMenuNav(options) {
+  const suspended = options.suspended ?? (() => false);
+  const initial = options.initialFocus ?? defaultInitialFocus;
+  const stack = [];
+  let root = menuRoot(options.baseRoot);
+  let lastInRoot = null;
+  const settle = (next) => {
+    const restore = popClosed(stack);
+    if (next.matches(DIALOG_SELECTOR) && !stack.some((s) => s.dialog === next)) {
+      stack.push({ dialog: next, restore: lastInRoot });
+    }
+    if (activeIn(next) !== null) {
+      return;
+    }
+    if (canRestore(restore, next)) {
+      focusControl(restore);
+    } else {
+      focusInitial(next, initial);
+    }
+  };
+  const refresh = () => {
+    const next = menuRoot(options.baseRoot);
+    if (next === root) {
+      return next;
+    }
+    root = next;
+    if (next !== null) {
+      settle(next);
+    }
+    return next;
+  };
+  const keydown = (e) => {
+    if (e.altKey || e.ctrlKey || e.metaKey || suspended()) {
+      return;
+    }
+    const r = refresh();
+    if (r !== null) {
+      onKey(e, r, initial);
+    }
+  };
+  const focusin = (e) => {
+    const t = e.target;
+    if (root !== null && root.contains(t) && t.closest(DIALOG_SELECTOR) === root.closest(DIALOG_SELECTOR)) {
+      lastInRoot = t;
+    }
+  };
+  const observer = new MutationObserver(() => {
+    refresh();
+  });
+  observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: [...OBSERVED_ATTRIBUTES] });
+  window.addEventListener("keydown", keydown, true);
+  window.addEventListener("pointerdown", clearInput, true);
+  document.addEventListener("focusin", focusin, true);
+  return {
+    pad: (action) => {
+      if (suspended()) {
+        return;
+      }
+      markInput(NAV_INPUT.pad);
+      onPad(action, refresh(), initial);
+    },
+    refresh: () => {
+      refresh();
+    },
+    dispose: () => {
+      observer.disconnect();
+      window.removeEventListener("keydown", keydown, true);
+      window.removeEventListener("pointerdown", clearInput, true);
+      document.removeEventListener("focusin", focusin, true);
+      clearInput();
+    }
+  };
+}
+
 // src/constants.ts
 var DEFAULT_HAPTICS_STORAGE_KEY = "game.haptics";
 var DEFAULT_ENABLE_CONFIRMATION = 15;
@@ -234,13 +597,26 @@ function createHaptics(options = {}) {
 
 exports.DEFAULT_ENABLE_CONFIRMATION = DEFAULT_ENABLE_CONFIRMATION;
 exports.DEFAULT_HAPTICS_STORAGE_KEY = DEFAULT_HAPTICS_STORAGE_KEY;
+exports.DIALOG_SELECTOR = DIALOG_SELECTOR;
 exports.HAPTIC_PATTERNS = HAPTIC_PATTERNS;
 exports.IDLE_REPEAT = IDLE_REPEAT;
+exports.MENU_DEFAULT_ATTR = MENU_DEFAULT_ATTR;
+exports.MENU_FOCUSABLE_SELECTOR = MENU_FOCUSABLE_SELECTOR;
+exports.NAV_DIRS = NAV_DIRS;
+exports.NAV_INPUT = NAV_INPUT;
+exports.NAV_INPUT_ATTR = NAV_INPUT_ATTR;
 exports.PAD_ACTIONS = PAD_ACTIONS;
 exports.STANDARD_BUTTON = STANDARD_BUTTON;
 exports.USER_ACTIVATION_EVENTS = USER_ACTIVATION_EVENTS;
 exports.createGamepadPoller = createGamepadPoller;
 exports.createHaptics = createHaptics;
+exports.createMenuNav = createMenuNav;
+exports.defaultInitialFocus = defaultInitialFocus;
+exports.focusables = focusables;
+exports.isShown = isShown;
+exports.menuRoot = menuRoot;
+exports.navDir = navDir;
+exports.pickTarget = pickTarget;
 exports.stepPad = stepPad;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map