@diffenderfer-games/hub 2.0.0-next.0 → 2.0.0-next.10

package/src/input/navigator.ts

@@ -1,171 +1,182 @@
-/**
- * Gamepad navigation the input system drives each frame: the hub menu while
- * it is open, a game's own menus opted in with `autoNavigate`, and the
- * navigable groups a game declares.
- */
-import type { RepeatingEdges, RisingEdges } from './edges';
-import { anyPadDirections, AXIS_DEADZONE, isAnyPadButtonPressed, PAD_BUTTON } from './gamepad';
-import type { Direction } from './gamepad';
-import { NavState } from './nav-state';
-import type { NavHighlighter, NavListeners } from './nav-state';
-import type { MenuBridge, NavigableDef, NavTarget } from './types';
-
-/** What the navigator reads from the input system. */
-export interface NavigatorContext {
-  readonly gamepads: readonly Gamepad[];
-  readonly repeats: RepeatingEdges;
-  readonly presses: RisingEdges;
-  readonly listeners: NavListeners;
-  /** The overlay, created on demand. */
-  highlighter(): NavHighlighter;
-  /** Whether an input is held (≥ 0.5). */
-  isPressed(inputName: string): boolean;
-  /** Whether an input went down this frame. */
-  wentDown(inputName: string): boolean;
-}
-
-const DIRECTIONS: readonly Direction[] = ['up', 'down', 'left', 'right'];
-
-/** The visible focusables of the hub menu. */
-function menuFocusables(root: ShadowRoot | null): HTMLElement[] {
-  if (root === null) {
-    return [];
-  }
-  return [...root.querySelectorAll<HTMLElement>('a[href], button:not([disabled]), input, [tabindex]')]
-    .filter((element) => element.getClientRects().length > 0);
-}
-
-/** Visible elements matching a CSS selector. */
-function visibleMatches(selector: string): HTMLElement[] {
-  return [...document.querySelectorAll<HTMLElement>(selector)].filter((element) => element.getClientRects().length > 0);
-}
-
-/** A navigable group with its highlight state. */
-interface GroupNavigation {
-  readonly definition: NavigableDef;
-  readonly state: NavState;
-}
-
-/** The menu, auto-navigate and group navigation of one input system. */
-export class Navigator {
-  private menuState: NavState | null = null;
-  private autoNavigateQuery: (() => NavTarget[]) | null = null;
-  private autoNavigateState: NavState | null = null;
-  private autoNavigateBack: (() => void) | null = null;
-  private readonly groups = new Map<string, GroupNavigation>();
-
-  /** Forget the declared groups (a new `define`). */
-  clearGroups(): void {
-    this.groups.clear();
-  }
-
-  /** Declare a navigable group. */
-  addGroup(group: string, definition: NavigableDef): void {
-    this.groups.set(group, { definition, state: new NavState(definition.elements, definition.wrap !== false) });
-  }
-
-  /** A group was enabled: highlight its first element. */
-  refreshGroup(group: string, context: NavigatorContext): void {
-    this.groups.get(group)?.state.requery(context.highlighter(), context.listeners);
-  }
-
-  /** A group was disabled: drop its highlight. */
-  blurGroup(group: string, highlighter: NavHighlighter | null): void {
-    this.groups.get(group)?.state.blur(highlighter);
-  }
-
-  /** Opt a game's own menus into gamepad navigation. */
-  setAutoNavigate(query: () => NavTarget[], back: (() => void) | null): void {
-    this.autoNavigateQuery = query;
-    this.autoNavigateBack = back;
-    this.autoNavigateState = null;
-  }
-
-  /** Make a CSS selector's visible matches the auto-navigate targets. */
-  static queryFor(selector: string | (() => NavTarget[])): () => NavTarget[] {
-    return typeof selector === 'string' ? () => visibleMatches(selector) : selector;
-  }
-
-  /** Stop auto-navigating. */
-  clearAutoNavigate(highlighter: NavHighlighter | null): void {
-    this.autoNavigateQuery = null;
-    this.autoNavigateState?.blur(highlighter);
-    this.autoNavigateState = null;
-  }
-
-  /** The hub menu is open: drive it with the highlight ring (gamepad only). */
-  driveMenu(menu: MenuBridge, isGamepadActive: boolean, context: NavigatorContext, highlighter: NavHighlighter | null): void {
-    if (!isGamepadActive) {
-      highlighter?.hideHighlight();
-      return;
-    }
-    this.menuState ??= new NavState(() => menuFocusables(menu.root));
-    this.driveList(this.menuState, 'm', context, () => {
-      menu.close();
-    });
-  }
-
-  /** The hub menu closed: drop its highlight. */
-  leaveMenu(highlighter: NavHighlighter | null): void {
-    this.menuState?.blur(highlighter);
-    this.menuState = null;
-  }
-
-  /** A game's own menus, when opted in, visible, and a gamepad is in use. */
-  driveAutoNavigate(isGamepadActive: boolean, context: NavigatorContext, highlighter: NavHighlighter | null): void {
-    const query = this.autoNavigateQuery;
-    if (query === null || !isGamepadActive || query().length === 0) {
-      this.autoNavigateState?.blur(highlighter);
-      this.autoNavigateState = null;
-      return;
-    }
-    this.autoNavigateState ??= new NavState(query);
-    this.driveList(this.autoNavigateState, 'an', context, this.autoNavigateBack);
-  }
-
-  /** The declared navigable groups that are enabled. */
-  driveGroups(isGroupEnabled: (group: string) => boolean, context: NavigatorContext): void {
-    for (const [group, { definition, state }] of this.groups) {
-      if (!isGroupEnabled(group)) {
-        continue;
-      }
-      const highlighter = context.highlighter();
-      const fires = (prefix: string, inputName: string | undefined): boolean => inputName !== undefined && context.repeats.fires(prefix + group, context.isPressed(inputName));
-      const shouldStepPrevious = fires('np:', definition.prev);
-      const shouldStepNext = fires('nn:', definition.next);
-      const shouldMoveUp = fires('nu:', definition.up);
-      const shouldMoveDown = fires('nd:', definition.down);
-      if (shouldStepNext) {
-        state.step(1, highlighter, context.listeners);
-      } else if (shouldStepPrevious) {
-        state.step(-1, highlighter, context.listeners);
-      } else if (shouldMoveUp) {
-        state.moveInDirection('up', highlighter, context.listeners);
-      } else if (shouldMoveDown) {
-        state.moveInDirection('down', highlighter, context.listeners);
-      }
-      if (definition.act !== '' && context.wentDown(definition.act)) {
-        state.act(highlighter, context.listeners);
-      }
-      state.position(highlighter);
-    }
-  }
-
-  /** Move with the stick or d-pad, A acts, B goes back. */
-  private driveList(state: NavState, keyPrefix: string, context: NavigatorContext, back: (() => void) | null): void {
-    const highlighter = context.highlighter();
-    state.requery(highlighter, context.listeners);
-    const held = anyPadDirections(context.gamepads, AXIS_DEADZONE);
-    const direction = DIRECTIONS.find((candidate) => context.repeats.fires(`${keyPrefix}:${candidate[0] ?? ''}`, held[candidate]));
-    if (direction !== undefined) {
-      state.moveInDirection(direction, highlighter, context.listeners);
-    }
-    if (context.presses.rose('act', isAnyPadButtonPressed(context.gamepads, PAD_BUTTON.A))) {
-      state.act(highlighter, context.listeners);
-    }
-    if (context.presses.rose('back', isAnyPadButtonPressed(context.gamepads, PAD_BUTTON.B))) {
-      back?.();
-    }
-    state.position(highlighter);
-  }
-}
+/**
+ * Gamepad navigation the input system drives each frame: the hub menu while
+ * it is open, a game's own menus opted in with `autoNavigate`, and the
+ * navigable groups a game declares.
+ */
+import type { RepeatingEdges, RisingEdges } from './edges';
+import { anyPadDirections, AXIS_DEADZONE, isAnyPadButtonPressed, PAD_BUTTON } from './gamepad';
+import type { Direction } from './gamepad';
+import { NavState } from './nav-state';
+import type { NavHighlighter, NavListeners } from './nav-state';
+import type { MenuBridge, NavigableDef, NavTarget } from './types';
+
+/** What the navigator reads from the input system. */
+export interface NavigatorContext {
+  readonly gamepads: readonly Gamepad[];
+  readonly repeats: RepeatingEdges;
+  readonly presses: RisingEdges;
+  readonly listeners: NavListeners;
+  /** The overlay, created on demand. */
+  highlighter(): NavHighlighter;
+  /** Whether an input is held (≥ 0.5). */
+  isPressed(inputName: string): boolean;
+  /** Whether an input went down this frame. */
+  wentDown(inputName: string): boolean;
+}
+
+const DIRECTIONS: readonly Direction[] = ['up', 'down', 'left', 'right'];
+
+/** The visible focusables of the hub menu. */
+function menuFocusables(root: ShadowRoot | null): HTMLElement[] {
+  if (root === null) {
+    return [];
+  }
+  return [...root.querySelectorAll<HTMLElement>('a[href], button:not([disabled]), input, [tabindex]')]
+    .filter((element) => element.getClientRects().length > 0);
+}
+
+/** Visible elements matching a CSS selector. */
+function visibleMatches(selector: string): HTMLElement[] {
+  return [...document.querySelectorAll<HTMLElement>(selector)].filter((element) => element.getClientRects().length > 0);
+}
+
+/** What `autoNavigate` was last given: the targets' query and the back action. */
+export interface AutoNavigateTarget {
+  readonly query: () => NavTarget[];
+  readonly back: (() => void) | null;
+}
+
+/** A navigable group with its highlight state. */
+interface GroupNavigation {
+  readonly definition: NavigableDef;
+  readonly state: NavState;
+}
+
+/** The menu, auto-navigate and group navigation of one input system. */
+export class Navigator {
+  private menuState: NavState | null = null;
+  private autoNavigateQuery: (() => NavTarget[]) | null = null;
+  private autoNavigateState: NavState | null = null;
+  private autoNavigateBack: (() => void) | null = null;
+  private readonly groups = new Map<string, GroupNavigation>();
+
+  /** Forget the declared groups (a new `define`). */
+  clearGroups(): void {
+    this.groups.clear();
+  }
+
+  /** Declare a navigable group. */
+  addGroup(group: string, definition: NavigableDef): void {
+    this.groups.set(group, { definition, state: new NavState(definition.elements, definition.wrap !== false) });
+  }
+
+  /** A group was enabled: highlight its first element. */
+  refreshGroup(group: string, context: NavigatorContext): void {
+    this.groups.get(group)?.state.requery(context.highlighter(), context.listeners);
+  }
+
+  /** A group was disabled: drop its highlight. */
+  blurGroup(group: string, highlighter: NavHighlighter | null): void {
+    this.groups.get(group)?.state.blur(highlighter);
+  }
+
+  /** Opt a game's own menus into gamepad navigation. */
+  setAutoNavigate(query: () => NavTarget[], back: (() => void) | null): void {
+    this.autoNavigateQuery = query;
+    this.autoNavigateBack = back;
+    this.autoNavigateState = null;
+  }
+
+  /** The current auto-navigate target and back action, or `null` when none is set. */
+  autoNavigateTarget(): AutoNavigateTarget | null {
+    return this.autoNavigateQuery === null ? null : { query: this.autoNavigateQuery, back: this.autoNavigateBack };
+  }
+
+  /** Make a CSS selector's visible matches the auto-navigate targets. */
+  static queryFor(selector: string | (() => NavTarget[])): () => NavTarget[] {
+    return typeof selector === 'string' ? () => visibleMatches(selector) : selector;
+  }
+
+  /** Stop auto-navigating. */
+  clearAutoNavigate(highlighter: NavHighlighter | null): void {
+    this.autoNavigateQuery = null;
+    this.autoNavigateState?.blur(highlighter);
+    this.autoNavigateState = null;
+  }
+
+  /** The hub menu is open: drive it with the highlight ring (gamepad only). */
+  driveMenu(menu: MenuBridge, isGamepadActive: boolean, context: NavigatorContext, highlighter: NavHighlighter | null): void {
+    if (!isGamepadActive) {
+      highlighter?.hideHighlight();
+      return;
+    }
+    this.menuState ??= new NavState(() => menuFocusables(menu.root));
+    this.driveList(this.menuState, 'm', context, () => {
+      menu.close();
+    });
+  }
+
+  /** The hub menu closed: drop its highlight. */
+  leaveMenu(highlighter: NavHighlighter | null): void {
+    this.menuState?.blur(highlighter);
+    this.menuState = null;
+  }
+
+  /** A game's own menus, when opted in, visible, and a gamepad is in use. */
+  driveAutoNavigate(isGamepadActive: boolean, context: NavigatorContext, highlighter: NavHighlighter | null): void {
+    const query = this.autoNavigateQuery;
+    if (query === null || !isGamepadActive || query().length === 0) {
+      this.autoNavigateState?.blur(highlighter);
+      this.autoNavigateState = null;
+      return;
+    }
+    this.autoNavigateState ??= new NavState(query);
+    this.driveList(this.autoNavigateState, 'an', context, this.autoNavigateBack);
+  }
+
+  /** The declared navigable groups that are enabled. */
+  driveGroups(isGroupEnabled: (group: string) => boolean, context: NavigatorContext): void {
+    for (const [group, { definition, state }] of this.groups) {
+      if (!isGroupEnabled(group)) {
+        continue;
+      }
+      const highlighter = context.highlighter();
+      const fires = (prefix: string, inputName: string | undefined): boolean => inputName !== undefined && context.repeats.fires(prefix + group, context.isPressed(inputName));
+      const shouldStepPrevious = fires('np:', definition.prev);
+      const shouldStepNext = fires('nn:', definition.next);
+      const shouldMoveUp = fires('nu:', definition.up);
+      const shouldMoveDown = fires('nd:', definition.down);
+      if (shouldStepNext) {
+        state.step(1, highlighter, context.listeners);
+      } else if (shouldStepPrevious) {
+        state.step(-1, highlighter, context.listeners);
+      } else if (shouldMoveUp) {
+        state.moveInDirection('up', highlighter, context.listeners);
+      } else if (shouldMoveDown) {
+        state.moveInDirection('down', highlighter, context.listeners);
+      }
+      if (definition.act !== '' && context.wentDown(definition.act)) {
+        state.act(highlighter, context.listeners);
+      }
+      state.position(highlighter);
+    }
+  }
+
+  /** Move with the stick or d-pad, A acts, B goes back. */
+  private driveList(state: NavState, keyPrefix: string, context: NavigatorContext, back: (() => void) | null): void {
+    const highlighter = context.highlighter();
+    state.requery(highlighter, context.listeners);
+    const held = anyPadDirections(context.gamepads, AXIS_DEADZONE);
+    const direction = DIRECTIONS.find((candidate) => context.repeats.fires(`${keyPrefix}:${candidate[0] ?? ''}`, held[candidate]));
+    if (direction !== undefined) {
+      state.moveInDirection(direction, highlighter, context.listeners);
+    }
+    if (context.presses.rose('act', isAnyPadButtonPressed(context.gamepads, PAD_BUTTON.A))) {
+      state.act(highlighter, context.listeners);
+    }
+    if (context.presses.rose('back', isAnyPadButtonPressed(context.gamepads, PAD_BUTTON.B))) {
+      back?.();
+    }
+    state.position(highlighter);
+  }
+}

package/src/input/on-screen-controls.ts

@@ -1,101 +1,101 @@
-/**
- * The input system's side of the overlay: creating it on demand, building
- * the on-screen controls, and deciding when they show (the player's choice,
- * else the game's default, else on touch devices without a gamepad; editing
- * the layout shows them all).
- */
-import { Overlay } from '../overlay/overlay';
-import type { VirtualControlCallbacks } from '../overlay/virtual-controls';
-import type { DeviceState } from './device-state';
-import type { InputConfig, InputOverrides } from './types';
-
-/** Whether this page counts as a touch device. */
-export function detectTouchDevice(): boolean {
-  return typeof navigator !== 'undefined' && (navigator.maxTouchPoints > 0 || 'ontouchstart' in window);
-}
-
-/** On-screen controls write into the device state; touching one makes touch the active source. */
-export function feedDeviceState(devices: DeviceState, reactions: { onTouch(): void; onDragged: VirtualControlCallbacks['onDragged'] }): VirtualControlCallbacks {
-  return {
-    onButtonDown: (id) => {
-      devices.pressedVirtualButtons.add(id);
-      reactions.onTouch();
-    },
-    onButtonUp: (id) => {
-      devices.pressedVirtualButtons.delete(id);
-    },
-    onStick: (id, outX, outY) => {
-      devices.sticks.set(id, { outX, outY });
-      reactions.onTouch();
-    },
-    onTap: () => {
-      devices.pulse('tap');
-      reactions.onTouch();
-    },
-    onDragged: reactions.onDragged,
-  };
-}
-
-/** The overlay and the on-screen controls' visibility. */
-export class OnScreenControls {
-  /** Whether this page counts as a touch device. */
-  readonly isTouchDevice: boolean = detectTouchDevice();
-  /** Whether a gamepad is connected (controls hide by default then). */
-  isGamepadConnected = false;
-  /** The player's explicit show/hide choice, or `null`. */
-  playerChoice: boolean | null = null;
-  private overlayInstance: Overlay | null = null;
-  private gameDefault: boolean | null = null;
-  private isEditing = false;
-  private readonly enabledGroups: () => ReadonlySet<string>;
-
-  constructor(enabledGroups: () => ReadonlySet<string>) {
-    this.enabledGroups = enabledGroups;
-  }
-
-  /** The overlay if it exists yet. */
-  get existingOverlay(): Overlay | null {
-    return this.overlayInstance;
-  }
-
-  /** The overlay, created on first use. */
-  overlay(): Overlay {
-    this.overlayInstance ??= new Overlay();
-    return this.overlayInstance;
-  }
-
-  /** What the "Show on-screen controls" toggle reflects (excludes the editing force). */
-  get isShowing(): boolean {
-    return this.playerChoice ?? this.gameDefault ?? (this.isTouchDevice && !this.isGamepadConnected);
-  }
-
-  /** Set the game's default visibility (`null` = automatic). */
-  setGameDefault(isVisible: boolean | null): void {
-    this.gameDefault = isVisible;
-    this.sync();
-  }
-
-  /** Force every control visible while the player edits the layout. */
-  setEditing(isEditing: boolean): void {
-    this.isEditing = isEditing;
-    this.sync();
-  }
-
-  /** (Re)build the controls from the config and overrides. */
-  build(config: InputConfig, overrides: InputOverrides, callbacks: VirtualControlCallbacks): void {
-    this.overlay().build(config, overrides, callbacks);
-    this.sync();
-  }
-
-  /** Apply the visibility rules to the built controls. */
-  sync(): void {
-    if (this.overlayInstance === null) {
-      return;
-    }
-    if (this.isEditing) {
-      this.overlayInstance.setVirtualVisible(true, null);
-    } else {
-      this.overlayInstance.setVirtualVisible(this.isShowing, this.enabledGroups());
-    }
-  }
-}
+/**
+ * The input system's side of the overlay: creating it on demand, building
+ * the on-screen controls, and deciding when they show (the player's choice,
+ * else the game's default, else on touch devices without a gamepad; editing
+ * the layout shows them all).
+ */
+import { Overlay } from '../overlay/overlay';
+import type { VirtualControlCallbacks } from '../overlay/virtual-controls';
+import type { DeviceState } from './device-state';
+import type { InputConfig, InputOverrides } from './types';
+
+/** Whether this page counts as a touch device. */
+export function detectTouchDevice(): boolean {
+  return typeof navigator !== 'undefined' && (navigator.maxTouchPoints > 0 || 'ontouchstart' in window);
+}
+
+/** On-screen controls write into the device state; touching one makes touch the active source. */
+export function feedDeviceState(devices: DeviceState, reactions: { onTouch(): void; onDragged: VirtualControlCallbacks['onDragged'] }): VirtualControlCallbacks {
+  return {
+    onButtonDown: (id) => {
+      devices.pressedVirtualButtons.add(id);
+      reactions.onTouch();
+    },
+    onButtonUp: (id) => {
+      devices.pressedVirtualButtons.delete(id);
+    },
+    onStick: (id, outX, outY) => {
+      devices.sticks.set(id, { outX, outY });
+      reactions.onTouch();
+    },
+    onTap: () => {
+      devices.pulse('tap');
+      reactions.onTouch();
+    },
+    onDragged: reactions.onDragged,
+  };
+}
+
+/** The overlay and the on-screen controls' visibility. */
+export class OnScreenControls {
+  /** Whether this page counts as a touch device. */
+  readonly isTouchDevice: boolean = detectTouchDevice();
+  /** Whether a gamepad is connected (controls hide by default then). */
+  isGamepadConnected = false;
+  /** The player's explicit show/hide choice, or `null`. */
+  playerChoice: boolean | null = null;
+  private overlayInstance: Overlay | null = null;
+  private gameDefault: boolean | null = null;
+  private isEditing = false;
+  private readonly enabledGroups: () => ReadonlySet<string>;
+
+  constructor(enabledGroups: () => ReadonlySet<string>) {
+    this.enabledGroups = enabledGroups;
+  }
+
+  /** The overlay if it exists yet. */
+  get existingOverlay(): Overlay | null {
+    return this.overlayInstance;
+  }
+
+  /** The overlay, created on first use. */
+  overlay(): Overlay {
+    this.overlayInstance ??= new Overlay();
+    return this.overlayInstance;
+  }
+
+  /** What the "Show on-screen controls" toggle reflects (excludes the editing force). */
+  get isShowing(): boolean {
+    return this.playerChoice ?? this.gameDefault ?? (this.isTouchDevice && !this.isGamepadConnected);
+  }
+
+  /** Set the game's default visibility (`null` = automatic). */
+  setGameDefault(isVisible: boolean | null): void {
+    this.gameDefault = isVisible;
+    this.sync();
+  }
+
+  /** Force every control visible while the player edits the layout. */
+  setEditing(isEditing: boolean): void {
+    this.isEditing = isEditing;
+    this.sync();
+  }
+
+  /** (Re)build the controls from the config and overrides. */
+  build(config: InputConfig, overrides: InputOverrides, callbacks: VirtualControlCallbacks): void {
+    this.overlay().build(config, overrides, callbacks);
+    this.sync();
+  }
+
+  /** Apply the visibility rules to the built controls. */
+  sync(): void {
+    if (this.overlayInstance === null) {
+      return;
+    }
+    if (this.isEditing) {
+      this.overlayInstance.setVirtualVisible(true, null);
+    } else {
+      this.overlayInstance.setVirtualVisible(this.isShowing, this.enabledGroups());
+    }
+  }
+}