@diffenderfer-games/hub 0.0.0-stage → 2.0.0-next.1

package/src/input/nav-state.ts

@@ -0,0 +1,191 @@
+/**
+ * One navigable list: the highlighted element, stepping and spatial moves,
+ * and activating it. The list is re-queried on every interaction because the
+ * DOM can change under it.
+ */
+import type { Direction } from './gamepad';
+import { findNearestInDirection, rectOf } from './spatial';
+import type { NavBlurEvent, NavElement, NavElementKind, NavFocusEvent, NavTarget, Rect } from './types';
+
+/** What a navigable list draws with (the overlay). */
+export interface NavHighlighter {
+  /** Ring the highlighted element. */
+  showHighlight(bounds: Rect): void;
+  /** Remove the ring. */
+  hideHighlight(): void;
+  /** Open the on-screen keyboard for a text field. */
+  openKeyboard(target: HTMLInputElement | HTMLTextAreaElement | null): void;
+}
+
+/** Where a list reports focus changes and activations. */
+export interface NavListeners {
+  /** An element gained the highlight. */
+  onFocus(event: NavFocusEvent): void;
+  /** An element lost the highlight. */
+  onBlur(event: NavBlurEvent): void;
+  /** The player activated an element. */
+  onAct(event: NavFocusEvent): void;
+}
+
+const TEXT_INPUT_TYPES = new Set(['text', 'search', 'email', 'password', 'number']);
+
+/** What kind of element a DOM node is, for `act`. */
+function kindOf(element: HTMLElement): NavElementKind {
+  if (element instanceof HTMLInputElement) {
+    if (element.type === 'range') {
+      return 'range';
+    }
+    if (TEXT_INPUT_TYPES.has(element.type)) {
+      return 'text';
+    }
+  }
+  return element instanceof HTMLTextAreaElement ? 'text' : 'button';
+}
+
+/** A navigable element's bounds. */
+function boundsOf(element: NavElement): Rect {
+  if (element.getBounds !== undefined) {
+    return element.getBounds();
+  }
+  return element.el === undefined ? { x: 0, y: 0, width: 0, height: 0 } : rectOf(element.el);
+}
+
+/** The text field a navigable element edits, if it is one. */
+function textFieldOf(element: NavElement): HTMLInputElement | HTMLTextAreaElement | null {
+  return element.el instanceof HTMLInputElement || element.el instanceof HTMLTextAreaElement ? element.el : null;
+}
+
+/** The highlight state of one navigable list. */
+export class NavState {
+  private elements: NavElement[] = [];
+  private index = -1;
+  private readonly queryElements: () => NavTarget[];
+  private readonly shouldWrap: boolean;
+
+  constructor(queryElements: () => NavTarget[], shouldWrap = true) {
+    this.queryElements = queryElements;
+    this.shouldWrap = shouldWrap;
+  }
+
+  /** Re-read the list, highlighting the first element if nothing is. */
+  requery(highlighter: NavHighlighter | null, listeners: NavListeners): void {
+    this.elements = this.resolve();
+    if (this.index >= this.elements.length) {
+      this.index = this.elements.length - 1;
+    }
+    if (this.index < 0 && this.elements.length > 0) {
+      this.index = 0;
+      this.focusCurrent(listeners);
+    }
+    this.position(highlighter);
+  }
+
+  /** Drop the highlight. */
+  blur(highlighter: NavHighlighter | null): void {
+    this.elements[this.index]?.onBlur?.();
+    this.index = -1;
+    highlighter?.hideHighlight();
+  }
+
+  /** Step to the next (+1) or previous (-1) element. */
+  step(delta: number, highlighter: NavHighlighter | null, listeners: NavListeners): void {
+    this.elements = this.resolve();
+    const count = this.elements.length;
+    if (count === 0) {
+      return;
+    }
+    this.blurCurrent(listeners);
+    let next = this.index + delta;
+    if (next < 0) {
+      next = this.shouldWrap ? count - 1 : 0;
+    }
+    if (next >= count) {
+      next = this.shouldWrap ? 0 : count - 1;
+    }
+    this.moveTo(next, highlighter, listeners);
+  }
+
+  /** Move to the nearest element in `direction`; up and down spill over to the previous and next column. */
+  moveInDirection(direction: Direction, highlighter: NavHighlighter | null, listeners: NavListeners): void {
+    this.elements = this.resolve();
+    if (this.elements.length === 0) {
+      return;
+    }
+    if (this.index < 0) {
+      this.moveTo(0, highlighter, listeners);
+      return;
+    }
+    const rects = this.elements.map(boundsOf);
+    let target = findNearestInDirection(rects, this.index, direction);
+    // Nothing directly that way: up falls through to the left, down to the right, so columns never dead-end.
+    const spillover = { up: 'left', down: 'right', left: null, right: null } as const;
+    const fallback = spillover[direction];
+    if (target < 0 && fallback !== null) {
+      target = findNearestInDirection(rects, this.index, fallback);
+    }
+    if (target >= 0) {
+      this.blurCurrent(listeners);
+      this.moveTo(target, highlighter, listeners);
+    }
+  }
+
+  /** Activate the highlighted element: open the keyboard for text, click anything else. */
+  act(highlighter: NavHighlighter | null, listeners: NavListeners): void {
+    this.elements = this.resolve();
+    const current = this.elements[this.index];
+    if (current === undefined) {
+      return;
+    }
+    if (current.kind === 'text') {
+      highlighter?.openKeyboard(textFieldOf(current));
+    } else {
+      current.el?.click();
+    }
+    current.onAct?.();
+    listeners.onAct({ id: current.id, el: current.el, kind: current.kind, index: this.index });
+    // Acting can change the elements.
+    this.elements = this.resolve();
+    this.position(highlighter);
+  }
+
+  /** Move the ring to the highlighted element (or hide it). */
+  position(highlighter: NavHighlighter | null): void {
+    if (highlighter === null) {
+      return;
+    }
+    const current = this.elements[this.index];
+    if (current === undefined) {
+      highlighter.hideHighlight();
+    } else {
+      highlighter.showHighlight(boundsOf(current));
+    }
+  }
+
+  private resolve(): NavElement[] {
+    return this.queryElements().map((target) => (target instanceof HTMLElement ? { el: target, kind: kindOf(target) } : target));
+  }
+
+  private moveTo(index: number, highlighter: NavHighlighter | null, listeners: NavListeners): void {
+    this.index = index;
+    this.focusCurrent(listeners);
+    this.position(highlighter);
+  }
+
+  private focusCurrent(listeners: NavListeners): void {
+    const current = this.elements[this.index];
+    if (current === undefined) {
+      return;
+    }
+    current.el?.focus({ preventScroll: false });
+    current.onFocus?.();
+    listeners.onFocus({ id: current.id, el: current.el, kind: current.kind, index: this.index });
+  }
+
+  private blurCurrent(listeners: NavListeners): void {
+    const current = this.elements[this.index];
+    if (current?.onBlur !== undefined) {
+      current.onBlur();
+      listeners.onBlur({ id: current.id, index: this.index });
+    }
+  }
+}

package/src/input/navigator.ts

@@ -0,0 +1,171 @@
+/**
+ * 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);
+  }
+}

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

@@ -0,0 +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());
+    }
+  }
+}

package/src/input/page-control.ts

@@ -0,0 +1,43 @@
+/**
+ * The small, stable slice of the input system that other bundles on the page
+ * use (plan §4.4): the host menu (attach itself, `game.controls`, the
+ * Controls button), the social runtime's dialogs (navigate them), the
+ * overlay stack (suspend `play`), and a handover between two client copies.
+ * Every client version keeps these methods.
+ */
+import { hasMethods } from '../realtime/cross-bundle';
+import type { MenuBridge, NavTarget } from './types';
+
+/** The cross-bundle input surface. */
+export interface PageInputControl {
+  /** Whether the game declared its inputs. */
+  readonly isDefined: boolean;
+  /** The host menu attaches itself. */
+  attachMenu(bridge: MenuBridge | null): void;
+  /** The host menu passes `game.controls`. */
+  // eslint-disable-next-line no-restricted-syntax -- trust boundary: game.controls from the page, parsed by the implementation
+  setLegacyControls(controls: unknown): void;
+  /** The menu's Controls button. */
+  openControls(): void;
+  /** Whether a group is on. */
+  isEnabled(group: string): boolean;
+  /** Turn a group on. */
+  enable(group: string): void;
+  /** Turn a group off. */
+  disable(group: string): void;
+  /** Make elements gamepad-navigable (the runtime's dialogs). */
+  autoNavigate(selector: string | (() => NavTarget[]), options?: { back?: () => void }): void;
+  /** Stop navigating them. */
+  clearAutoNavigate(): void;
+  /** Stop driving the page and hand over to `owner`. Absent on v1 copies. */
+  yieldPageTo?(owner: PageInputControl): void;
+}
+
+/** The methods every input system on the page has, v1 copies included. */
+const PAGE_INPUT_METHODS = ['attachMenu', 'setLegacyControls', 'openControls', 'isEnabled', 'enable', 'disable', 'autoNavigate', 'clearAutoNavigate', 'define', 'value'] as const;
+
+/** Whether `candidate` is some bundle's input system. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: the instance may come from another bundle
+export function isPageInputControl(candidate: unknown): candidate is PageInputControl {
+  return hasMethods(candidate, PAGE_INPUT_METHODS);
+}