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

package/src/input/types.ts

@@ -1,331 +1,331 @@
-/**
- * The input system's public shapes (`hub.input`, docs/hub.md "Input system").
- * A game declares named inputs that each read as 0..1 and maps each to
- * keyboard, mouse, touch and gamepad sources.
- */
-
-/** The device the player is using right now. */
-export type InputSource = 'keyboard' | 'mouse' | 'gamepad' | 'touch';
-
-/** A direction or half of an axis. */
-export type AxisSide = '+' | '-';
-
-/** How the mouse drives an input. */
-export interface MouseMapping {
-  /** Held while this mouse button is down. */
-  button?: number;
-  /** 1 for one frame on a double-click. */
-  dblclick?: boolean;
-  /** The pointer's position from screen centre on this axis maps to 0..1 on one side. */
-  centerAxis?: 'x' | 'y';
-  /** Which side of centre fills 0..1 (default `+`). */
-  centerSide?: AxisSide;
-  /** Relative movement on this axis, scaled by `moveScale`. */
-  moveAxis?: 'x' | 'y';
-  /** Which direction of movement counts (default `+`). */
-  moveSign?: AxisSide;
-  /** Movement scale (default 0.1). */
-  moveScale?: number;
-  /** Wheel delta in this direction (decays). */
-  wheel?: AxisSide;
-}
-
-/** How a gamepad drives an input. */
-export interface GamepadMapping {
-  /** A standard-gamepad button index (0/1, or a 0..1 trigger). */
-  button?: number;
-  /** An axis index and which half: `+` positive, `-` negative, `±` absolute value. */
-  axis?: [number, AxisSide | '±'];
-}
-
-/** How touch and the on-screen controls drive an input. */
-export interface TouchMapping {
-  /** The id of a virtual button that drives this input. */
-  button?: string;
-  /** The id of a virtual joystick. */
-  stick?: string;
-  /** Which half or axis of that stick. */
-  axis?: 'x+' | 'x-' | 'y+' | 'y-' | 'x' | 'y';
-  /** 1 for one frame on a tap anywhere on a tap control. */
-  tap?: boolean;
-  /** The last touch's position from screen centre on this axis maps to 0..1 on one side. */
-  centerAxis?: 'x' | 'y';
-  /** Which side of centre fills 0..1 (default `+`). */
-  centerSide?: AxisSide;
-}
-
-/** One named input and its sources. */
-export interface InputDef {
-  /** `KeyboardEvent.key` values (case-insensitive). */
-  keys?: string[];
-  /** Mouse source (counts while the mouse is the active pointer). */
-  mouse?: MouseMapping;
-  /** Gamepad source (counts while a gamepad is the active pointer). */
-  gamepad?: GamepadMapping;
-  /** Touch and on-screen control source. */
-  touch?: TouchMapping;
-}
-
-/**
- * A named axis. Each of `x` and `y` is a `[negative, positive]` pair of input
- * names (read as -1..1), or one input name read directly.
- */
-export interface AxisDef {
-  /** The horizontal axis. */
-  x?: string | [string, string];
-  /** The vertical axis. */
-  y?: string | [string, string];
-}
-
-/** Where an on-screen control sits. */
-export type Anchor =
-  | 'top-left' | 'top' | 'top-right'
-  | 'left' | 'center' | 'right'
-  | 'bottom-left' | 'bottom' | 'bottom-right';
-
-/** The kinds of on-screen control. */
-export type VirtualControlType = 'button' | 'joystick' | 'dpad' | 'tap';
-
-/** Pixel distances from the viewport edges. */
-export interface EdgeOffsets {
-  /** From the left edge. */
-  left?: number;
-  /** From the right edge. */
-  right?: number;
-  /** From the top edge. */
-  top?: number;
-  /** From the bottom edge. */
-  bottom?: number;
-}
-
-/** The inputs a dpad or button drives. */
-export interface VirtualInputs {
-  /** Up. */
-  up?: string;
-  /** Down. */
-  down?: string;
-  /** Left. */
-  left?: string;
-  /** Right. */
-  right?: string;
-  /** A press. */
-  press?: string;
-}
-
-/** An on-screen touch control. */
-export interface VirtualDef {
-  /** Its id (inputs reference it from `touch.button` or `touch.stick`). */
-  id: string;
-  /** What it is. */
-  type: VirtualControlType;
-  /** Its anchor for the automatic layout. */
-  place: Anchor;
-  /**
-   * An explicit pixel position from the viewport edges; bypasses the automatic
-   * layout for this control (e.g. pin a pause button just above a stick).
-   */
-  pos?: EdgeOffsets;
-  /**
-   * Nudge an auto-placed control away from its anchor's edges, in px: `x`
-   * moves it inward from the left/right edge, `y` away from the top/bottom
-   * edge. For a band every control should avoid, use `hub.input.setInsets`.
-   */
-  offset?: { x?: number; y?: number };
-  /** Diameter in px (or the width when `width`/`height` are given). */
-  size?: number;
-  /** Width in px; overrides `size` for non-square controls. */
-  width?: number;
-  /** Height in px; overrides `size` for non-square controls. */
-  height?: number;
-  /** Default circle for sticks, round for buttons. */
-  shape?: 'round' | 'circle' | 'square' | 'pill';
-  /** A stick's travel: `both` (default), or single-axis `x` / `y`. */
-  axis?: 'x' | 'y' | 'both';
-  /** 0..1. */
-  opacity?: number;
-  /** Accent colour (border, knob, pressed fill). */
-  color?: string;
-  /** Resting background colour. */
-  bg?: string;
-  /** Label text colour. */
-  text?: string;
-  /** Text on a button. */
-  label?: string;
-  /** Raw HTML inside a button. */
-  html?: string;
-  /** For a dpad or button: the inputs it drives. Joysticks drive the inputs that reference them. */
-  inputs?: VirtualInputs;
-}
-
-/** A screen rectangle in px. */
-export interface Rect {
-  /** Left. */
-  x: number;
-  /** Top. */
-  y: number;
-  /** Width. */
-  width: number;
-  /** Height. */
-  height: number;
-}
-
-/** What a navigable element is, for `act`. */
-export type NavElementKind = 'button' | 'text' | 'range' | 'custom';
-
-/** A navigable element that isn't (only) a DOM node, e.g. a canvas-drawn button. */
-export interface NavElement {
-  /** Its id, echoed in focus/blur/act events. */
-  id?: string;
-  /** What it is (`text` opens the on-screen keyboard on act). */
-  kind?: NavElementKind;
-  /** A DOM element: bounds, click and focus come from it. */
-  el?: HTMLElement;
-  /** Its bounds, for elements without `el`. */
-  getBounds?: () => Rect;
-  /** Called when it gains the highlight. */
-  onFocus?: () => void;
-  /** Called when it loses the highlight. */
-  onBlur?: () => void;
-  /** Called when the player activates it. */
-  onAct?: () => void;
-}
-
-/** What a navigable group's element list may hold. */
-export type NavTarget = HTMLElement | NavElement;
-
-/** Makes a group's UI navigable by gamepad and keys. */
-export interface NavigableDef {
-  /** Input that steps to the previous element. */
-  prev?: string;
-  /** Input that steps to the next element. */
-  next?: string;
-  /** Input that moves up spatially. */
-  up?: string;
-  /** Input that moves down spatially. */
-  down?: string;
-  /** Input that activates the highlighted element. */
-  act: string;
-  /** The elements, re-queried after every interaction (the DOM can change). */
-  elements: () => NavTarget[];
-  /** Wrap around at the ends (default true). */
-  wrap?: boolean;
-}
-
-/** A named group of inputs, enabled and disabled together. */
-export interface GroupDef {
-  /** The inputs, by name. */
-  inputs: Record<string, InputDef>;
-  /** Named axes over the inputs. */
-  axes?: Record<string, AxisDef>;
-  /** On-screen controls shown while the group is enabled. */
-  virtual?: VirtualDef[];
-  /** Makes the group's UI navigable. */
-  navigable?: NavigableDef;
-  /** Start enabled (default false; call `enable()` yourself). */
-  enabled?: boolean;
-}
-
-/** What `hub.input.define` takes. */
-export interface InputConfig {
-  /** The groups, by name. */
-  groups: Record<string, GroupDef>;
-}
-
-/** One input's reading this frame. */
-export interface InputReading {
-  /** 0..1. */
-  value: number;
-  /** Same as `value`. */
-  raw: number;
-  /** It crossed 0.5 upward this frame. */
-  isDown: boolean;
-  /** It crossed 0.5 downward this frame. */
-  isUp: boolean;
-}
-
-/** A 2D reading, clamped to the unit circle. */
-export interface Vector {
-  /** -1..1. */
-  x: number;
-  /** -1..1. */
-  y: number;
-  /** 0..1. */
-  mag: number;
-}
-
-/** A player-dragged spot: the control's top-left corner as % of the viewport. */
-export interface DraggedSpot {
-  /** % of the viewport width. */
-  x?: number;
-  /** % of the viewport height. */
-  y?: number;
-}
-
-/** A player's changes to a virtual control. */
-export type VirtualOverride = Partial<VirtualDef> & DraggedSpot;
-
-/** The player's remaps and control customisations, persisted per game. */
-export interface InputOverrides {
-  /** Rebound inputs, by input name. */
-  bindings?: Record<string, Partial<InputDef>>;
-  /** Moved or restyled on-screen controls, by control id. */
-  virtual?: Record<string, VirtualOverride>;
-  /** The player's show/hide choice for the on-screen controls. */
-  showVirtual?: boolean;
-}
-
-/** The hub menu, as the input system drives it (toggle on Select, gamepad navigation inside). */
-export interface MenuBridge {
-  /** Open or close the menu; returns whether it is now open. */
-  toggle: () => boolean;
-  /** Whether the menu is open. */
-  isOpen: () => boolean;
-  /** Close the menu. */
-  close: () => void;
-  /** The menu's shadow root (its focusables are navigated). */
-  root: ShadowRoot | null;
-}
-
-/** A navigation focus or act event. */
-export interface NavFocusEvent {
-  /** The element's id, if it has one. */
-  id?: string | undefined;
-  /** The DOM element, if any. */
-  el?: HTMLElement | undefined;
-  /** What it is. */
-  kind?: NavElementKind | undefined;
-  /** Its index in the list. */
-  index: number;
-}
-
-/** A navigation blur event. */
-export interface NavBlurEvent {
-  /** The element's id, if it has one. */
-  id?: string | undefined;
-  /** Its index in the list. */
-  index: number;
-}
-
-/** Events `hub.input.on` delivers, name → payload. */
-export interface InputEvents {
-  /** An element gained the highlight. */
-  focus: NavFocusEvent;
-  /** An element lost the highlight. */
-  blur: NavBlurEvent;
-  /** The player activated an element. */
-  act: NavFocusEvent;
-  /** The active device changed. */
-  sourcechange: InputSource;
-  /** Reserved. */
-  navigate: NavFocusEvent;
-}
-
-/** Where the input system persists the player's remaps. */
-export interface InputHost {
-  /** This page's game slug. */
-  readonly slug: string | null;
-  /** The saved overrides, or `null`. */
-  loadOverrides(): InputOverrides | null;
-  /** Save overrides (locally, and to the cloud when signed in). */
-  saveOverrides(overrides: InputOverrides): void;
-}
+/**
+ * The input system's public shapes (`hub.input`, docs/hub.md "Input system").
+ * A game declares named inputs that each read as 0..1 and maps each to
+ * keyboard, mouse, touch and gamepad sources.
+ */
+
+/** The device the player is using right now. */
+export type InputSource = 'keyboard' | 'mouse' | 'gamepad' | 'touch';
+
+/** A direction or half of an axis. */
+export type AxisSide = '+' | '-';
+
+/** How the mouse drives an input. */
+export interface MouseMapping {
+  /** Held while this mouse button is down. */
+  button?: number;
+  /** 1 for one frame on a double-click. */
+  dblclick?: boolean;
+  /** The pointer's position from screen centre on this axis maps to 0..1 on one side. */
+  centerAxis?: 'x' | 'y';
+  /** Which side of centre fills 0..1 (default `+`). */
+  centerSide?: AxisSide;
+  /** Relative movement on this axis, scaled by `moveScale`. */
+  moveAxis?: 'x' | 'y';
+  /** Which direction of movement counts (default `+`). */
+  moveSign?: AxisSide;
+  /** Movement scale (default 0.1). */
+  moveScale?: number;
+  /** Wheel delta in this direction (decays). */
+  wheel?: AxisSide;
+}
+
+/** How a gamepad drives an input. */
+export interface GamepadMapping {
+  /** A standard-gamepad button index (0/1, or a 0..1 trigger). */
+  button?: number;
+  /** An axis index and which half: `+` positive, `-` negative, `±` absolute value. */
+  axis?: [number, AxisSide | '±'];
+}
+
+/** How touch and the on-screen controls drive an input. */
+export interface TouchMapping {
+  /** The id of a virtual button that drives this input. */
+  button?: string;
+  /** The id of a virtual joystick. */
+  stick?: string;
+  /** Which half or axis of that stick. */
+  axis?: 'x+' | 'x-' | 'y+' | 'y-' | 'x' | 'y';
+  /** 1 for one frame on a tap anywhere on a tap control. */
+  tap?: boolean;
+  /** The last touch's position from screen centre on this axis maps to 0..1 on one side. */
+  centerAxis?: 'x' | 'y';
+  /** Which side of centre fills 0..1 (default `+`). */
+  centerSide?: AxisSide;
+}
+
+/** One named input and its sources. */
+export interface InputDef {
+  /** `KeyboardEvent.key` values (case-insensitive). */
+  keys?: string[];
+  /** Mouse source (counts while the mouse is the active pointer). */
+  mouse?: MouseMapping;
+  /** Gamepad source (counts while a gamepad is the active pointer). */
+  gamepad?: GamepadMapping;
+  /** Touch and on-screen control source. */
+  touch?: TouchMapping;
+}
+
+/**
+ * A named axis. Each of `x` and `y` is a `[negative, positive]` pair of input
+ * names (read as -1..1), or one input name read directly.
+ */
+export interface AxisDef {
+  /** The horizontal axis. */
+  x?: string | [string, string];
+  /** The vertical axis. */
+  y?: string | [string, string];
+}
+
+/** Where an on-screen control sits. */
+export type Anchor =
+  | 'top-left' | 'top' | 'top-right'
+  | 'left' | 'center' | 'right'
+  | 'bottom-left' | 'bottom' | 'bottom-right';
+
+/** The kinds of on-screen control. */
+export type VirtualControlType = 'button' | 'joystick' | 'dpad' | 'tap';
+
+/** Pixel distances from the viewport edges. */
+export interface EdgeOffsets {
+  /** From the left edge. */
+  left?: number;
+  /** From the right edge. */
+  right?: number;
+  /** From the top edge. */
+  top?: number;
+  /** From the bottom edge. */
+  bottom?: number;
+}
+
+/** The inputs a dpad or button drives. */
+export interface VirtualInputs {
+  /** Up. */
+  up?: string;
+  /** Down. */
+  down?: string;
+  /** Left. */
+  left?: string;
+  /** Right. */
+  right?: string;
+  /** A press. */
+  press?: string;
+}
+
+/** An on-screen touch control. */
+export interface VirtualDef {
+  /** Its id (inputs reference it from `touch.button` or `touch.stick`). */
+  id: string;
+  /** What it is. */
+  type: VirtualControlType;
+  /** Its anchor for the automatic layout. */
+  place: Anchor;
+  /**
+   * An explicit pixel position from the viewport edges; bypasses the automatic
+   * layout for this control (e.g. pin a pause button just above a stick).
+   */
+  pos?: EdgeOffsets;
+  /**
+   * Nudge an auto-placed control away from its anchor's edges, in px: `x`
+   * moves it inward from the left/right edge, `y` away from the top/bottom
+   * edge. For a band every control should avoid, use `hub.input.setInsets`.
+   */
+  offset?: { x?: number; y?: number };
+  /** Diameter in px (or the width when `width`/`height` are given). */
+  size?: number;
+  /** Width in px; overrides `size` for non-square controls. */
+  width?: number;
+  /** Height in px; overrides `size` for non-square controls. */
+  height?: number;
+  /** Default circle for sticks, round for buttons. */
+  shape?: 'round' | 'circle' | 'square' | 'pill';
+  /** A stick's travel: `both` (default), or single-axis `x` / `y`. */
+  axis?: 'x' | 'y' | 'both';
+  /** 0..1. */
+  opacity?: number;
+  /** Accent colour (border, knob, pressed fill). */
+  color?: string;
+  /** Resting background colour. */
+  bg?: string;
+  /** Label text colour. */
+  text?: string;
+  /** Text on a button. */
+  label?: string;
+  /** Raw HTML inside a button. */
+  html?: string;
+  /** For a dpad or button: the inputs it drives. Joysticks drive the inputs that reference them. */
+  inputs?: VirtualInputs;
+}
+
+/** A screen rectangle in px. */
+export interface Rect {
+  /** Left. */
+  x: number;
+  /** Top. */
+  y: number;
+  /** Width. */
+  width: number;
+  /** Height. */
+  height: number;
+}
+
+/** What a navigable element is, for `act`. */
+export type NavElementKind = 'button' | 'text' | 'range' | 'custom';
+
+/** A navigable element that isn't (only) a DOM node, e.g. a canvas-drawn button. */
+export interface NavElement {
+  /** Its id, echoed in focus/blur/act events. */
+  id?: string;
+  /** What it is (`text` opens the on-screen keyboard on act). */
+  kind?: NavElementKind;
+  /** A DOM element: bounds, click and focus come from it. */
+  el?: HTMLElement;
+  /** Its bounds, for elements without `el`. */
+  getBounds?: () => Rect;
+  /** Called when it gains the highlight. */
+  onFocus?: () => void;
+  /** Called when it loses the highlight. */
+  onBlur?: () => void;
+  /** Called when the player activates it. */
+  onAct?: () => void;
+}
+
+/** What a navigable group's element list may hold. */
+export type NavTarget = HTMLElement | NavElement;
+
+/** Makes a group's UI navigable by gamepad and keys. */
+export interface NavigableDef {
+  /** Input that steps to the previous element. */
+  prev?: string;
+  /** Input that steps to the next element. */
+  next?: string;
+  /** Input that moves up spatially. */
+  up?: string;
+  /** Input that moves down spatially. */
+  down?: string;
+  /** Input that activates the highlighted element. */
+  act: string;
+  /** The elements, re-queried after every interaction (the DOM can change). */
+  elements: () => NavTarget[];
+  /** Wrap around at the ends (default true). */
+  wrap?: boolean;
+}
+
+/** A named group of inputs, enabled and disabled together. */
+export interface GroupDef {
+  /** The inputs, by name. */
+  inputs: Record<string, InputDef>;
+  /** Named axes over the inputs. */
+  axes?: Record<string, AxisDef>;
+  /** On-screen controls shown while the group is enabled. */
+  virtual?: VirtualDef[];
+  /** Makes the group's UI navigable. */
+  navigable?: NavigableDef;
+  /** Start enabled (default false; call `enable()` yourself). */
+  enabled?: boolean;
+}
+
+/** What `hub.input.define` takes. */
+export interface InputConfig {
+  /** The groups, by name. */
+  groups: Record<string, GroupDef>;
+}
+
+/** One input's reading this frame. */
+export interface InputReading {
+  /** 0..1. */
+  value: number;
+  /** Same as `value`. */
+  raw: number;
+  /** It crossed 0.5 upward this frame. */
+  isDown: boolean;
+  /** It crossed 0.5 downward this frame. */
+  isUp: boolean;
+}
+
+/** A 2D reading, clamped to the unit circle. */
+export interface Vector {
+  /** -1..1. */
+  x: number;
+  /** -1..1. */
+  y: number;
+  /** 0..1. */
+  mag: number;
+}
+
+/** A player-dragged spot: the control's top-left corner as % of the viewport. */
+export interface DraggedSpot {
+  /** % of the viewport width. */
+  x?: number;
+  /** % of the viewport height. */
+  y?: number;
+}
+
+/** A player's changes to a virtual control. */
+export type VirtualOverride = Partial<VirtualDef> & DraggedSpot;
+
+/** The player's remaps and control customisations, persisted per game. */
+export interface InputOverrides {
+  /** Rebound inputs, by input name. */
+  bindings?: Record<string, Partial<InputDef>>;
+  /** Moved or restyled on-screen controls, by control id. */
+  virtual?: Record<string, VirtualOverride>;
+  /** The player's show/hide choice for the on-screen controls. */
+  showVirtual?: boolean;
+}
+
+/** The hub menu, as the input system drives it (toggle on Select, gamepad navigation inside). */
+export interface MenuBridge {
+  /** Open or close the menu; returns whether it is now open. */
+  toggle: () => boolean;
+  /** Whether the menu is open. */
+  isOpen: () => boolean;
+  /** Close the menu. */
+  close: () => void;
+  /** The menu's shadow root (its focusables are navigated). */
+  root: ShadowRoot | null;
+}
+
+/** A navigation focus or act event. */
+export interface NavFocusEvent {
+  /** The element's id, if it has one. */
+  id?: string | undefined;
+  /** The DOM element, if any. */
+  el?: HTMLElement | undefined;
+  /** What it is. */
+  kind?: NavElementKind | undefined;
+  /** Its index in the list. */
+  index: number;
+}
+
+/** A navigation blur event. */
+export interface NavBlurEvent {
+  /** The element's id, if it has one. */
+  id?: string | undefined;
+  /** Its index in the list. */
+  index: number;
+}
+
+/** Events `hub.input.on` delivers, name → payload. */
+export interface InputEvents {
+  /** An element gained the highlight. */
+  focus: NavFocusEvent;
+  /** An element lost the highlight. */
+  blur: NavBlurEvent;
+  /** The player activated an element. */
+  act: NavFocusEvent;
+  /** The active device changed. */
+  sourcechange: InputSource;
+  /** Reserved. */
+  navigate: NavFocusEvent;
+}
+
+/** Where the input system persists the player's remaps. */
+export interface InputHost {
+  /** This page's game slug. */
+  readonly slug: string | null;
+  /** The saved overrides, or `null`. */
+  loadOverrides(): InputOverrides | null;
+  /** Save overrides (locally, and to the cloud when signed in). */
+  saveOverrides(overrides: InputOverrides): void;
+}