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

package/src/input/legacy-controls.ts

@@ -1,64 +1,64 @@
-/**
- * `game.controls` (`window.__HUB__.controls`): the gamepad-to-keyboard map a
- * zero-config game declares. It comes from the page, so it is read field by
- * field; anything malformed falls back to the defaults.
- */
-import { isObject, readField } from '../realtime/cross-bundle';
-
-/** One player's resolved map: a `KeyboardEvent.code` per direction and per button index. */
-export interface ResolvedControlMap {
-  up: string;
-  down: string;
-  left: string;
-  right: string;
-  buttons: Map<number, string>;
-}
-
-/** The parsed `game.controls`: one map per player (pads past the end use the first). */
-export type LegacyControls = readonly ResolvedControlMap[];
-
-/** The defaults: arrows, A=Space, B=Enter, X=Z, Y=X, Select=Escape, Start=Enter. */
-const DEFAULT_BUTTONS: ReadonlyArray<readonly [number, string]> = [[0, 'Space'], [1, 'Enter'], [2, 'KeyZ'], [3, 'KeyX'], [9, 'Enter'], [8, 'Escape']];
-
-/** A text field of the map, or the default. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: game.controls from the page
-function textOr(map: unknown, key: string, fallback: string): string {
-  const field = readField(map, key);
-  return typeof field === 'string' && field !== '' ? field : fallback;
-}
-
-/** One player's map over the defaults. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: game.controls from the page
-function resolveMap(map: unknown): ResolvedControlMap {
-  const buttons = new Map<number, string>(DEFAULT_BUTTONS);
-  const declared = readField(map, 'buttons');
-  if (isObject(declared)) {
-    for (const [index, code] of Object.entries(declared)) {
-      if (typeof code === 'string' && code !== '' && /^\d+$/.test(index)) {
-        buttons.set(Number(index), code);
-      }
-    }
-  }
-  return {
-    up: textOr(map, 'up', 'ArrowUp'),
-    down: textOr(map, 'down', 'ArrowDown'),
-    left: textOr(map, 'left', 'ArrowLeft'),
-    right: textOr(map, 'right', 'ArrowRight'),
-    buttons,
-  };
-}
-
-/** Parse `game.controls` (a shared map, or per-player maps in `players`). */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: game.controls from the page
-export function parseLegacyControls(raw: unknown): LegacyControls {
-  const players = readField(raw, 'players');
-  if (Array.isArray(players) && players.length > 0) {
-    return players.map(resolveMap);
-  }
-  return [resolveMap(raw)];
-}
-
-/** The map for the pad at `padIndex`. */
-export function controlMapFor(controls: LegacyControls, padIndex: number): ResolvedControlMap {
-  return controls[padIndex] ?? controls[0] ?? resolveMap(null);
-}
+/**
+ * `game.controls` (`window.__HUB__.controls`): the gamepad-to-keyboard map a
+ * zero-config game declares. It comes from the page, so it is read field by
+ * field; anything malformed falls back to the defaults.
+ */
+import { isObject, readField } from '../realtime/cross-bundle';
+
+/** One player's resolved map: a `KeyboardEvent.code` per direction and per button index. */
+export interface ResolvedControlMap {
+  up: string;
+  down: string;
+  left: string;
+  right: string;
+  buttons: Map<number, string>;
+}
+
+/** The parsed `game.controls`: one map per player (pads past the end use the first). */
+export type LegacyControls = readonly ResolvedControlMap[];
+
+/** The defaults: arrows, A=Space, B=Enter, X=Z, Y=X, Select=Escape, Start=Enter. */
+const DEFAULT_BUTTONS: ReadonlyArray<readonly [number, string]> = [[0, 'Space'], [1, 'Enter'], [2, 'KeyZ'], [3, 'KeyX'], [9, 'Enter'], [8, 'Escape']];
+
+/** A text field of the map, or the default. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: game.controls from the page
+function textOr(map: unknown, key: string, fallback: string): string {
+  const field = readField(map, key);
+  return typeof field === 'string' && field !== '' ? field : fallback;
+}
+
+/** One player's map over the defaults. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: game.controls from the page
+function resolveMap(map: unknown): ResolvedControlMap {
+  const buttons = new Map<number, string>(DEFAULT_BUTTONS);
+  const declared = readField(map, 'buttons');
+  if (isObject(declared)) {
+    for (const [index, code] of Object.entries(declared)) {
+      if (typeof code === 'string' && code !== '' && /^\d+$/.test(index)) {
+        buttons.set(Number(index), code);
+      }
+    }
+  }
+  return {
+    up: textOr(map, 'up', 'ArrowUp'),
+    down: textOr(map, 'down', 'ArrowDown'),
+    left: textOr(map, 'left', 'ArrowLeft'),
+    right: textOr(map, 'right', 'ArrowRight'),
+    buttons,
+  };
+}
+
+/** Parse `game.controls` (a shared map, or per-player maps in `players`). */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: game.controls from the page
+export function parseLegacyControls(raw: unknown): LegacyControls {
+  const players = readField(raw, 'players');
+  if (Array.isArray(players) && players.length > 0) {
+    return players.map(resolveMap);
+  }
+  return [resolveMap(raw)];
+}
+
+/** The map for the pad at `padIndex`. */
+export function controlMapFor(controls: LegacyControls, padIndex: number): ResolvedControlMap {
+  return controls[padIndex] ?? controls[0] ?? resolveMap(null);
+}

package/src/input/nav-state.ts

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