@ue-too/board 0.9.5 → 0.11.0

package/input-interpretation/input-state-machine/touch-input-state-machine.d.ts

@@ -1,18 +1,72 @@
 import { EventReactions, EventGuards, Guard, TemplateState, TemplateStateMachine } from "@ue-too/being";
 import { TouchContext, TouchPoints } from "./touch-input-context";
+import type { Point } from "@ue-too/math";
+/**
+ * Possible states of the touch input state machine.
+ *
+ * @remarks
+ * State transitions:
+ * - **IDLE**: No touches active, or single touch (reserved for UI)
+ * - **PENDING**: Exactly two touches active, waiting for movement to determine gesture type
+ * - **IN_PROGRESS**: Two-finger gesture in progress (pan or zoom)
+ *
+ * The state machine only handles two-finger gestures. Single-finger touches are ignored
+ * to avoid interfering with UI interactions (button clicks, text selection, etc.).
+ *
+ * @category Input State Machine - Touch
+ */
 export type TouchStates = "IDLE" | "PENDING" | "IN_PROGRESS";
 /**
- * @description The touch event payload.
+ * Payload for touch events containing active touch points.
  *
- * @category Input State Machine
+ * @property points - Array of touch points involved in this event
+ *
+ * @category Input State Machine - Touch
  */
 export type TouchEventPayload = {
     points: TouchPoints[];
 };
 /**
- * @description The touch event mapping.
+ * Output events produced by the touch state machine for the orchestrator.
  *
- * @category Input State Machine
+ * @remarks
+ * Touch gestures are recognized from two-finger interactions:
+ *
+ * **Pan Gesture**:
+ * - Two fingers move in the same direction
+ * - Delta is calculated from the midpoint movement
+ * - Triggers when midpoint delta > distance delta
+ *
+ * **Zoom Gesture**:
+ * - Two fingers move toward/away from each other (pinch)
+ * - Delta is calculated from distance change between fingers
+ * - Anchor point is the midpoint between fingers
+ * - Triggers when distance delta > midpoint delta
+ *
+ * **Coordinate Spaces**:
+ * - Pan delta is in window pixels
+ * - Zoom anchor point is in viewport coordinates
+ *
+ * @category Input State Machine - Touch
+ */
+export type TouchOutputEvent = {
+    type: "pan";
+    delta: Point;
+} | {
+    type: "zoom";
+    delta: number;
+    anchorPointInViewPort: Point;
+} | {
+    type: "none";
+};
+/**
+ * Event mapping for the touch input state machine.
+ *
+ * @remarks
+ * Maps touch event names to their payload types. The state machine handles
+ * the three core touch events: touchstart, touchmove, and touchend.
+ *
+ * @category Input State Machine - Touch
  */
 export type TouchEventMapping = {
     touchstart: TouchEventPayload;
@@ -20,15 +74,35 @@ export type TouchEventMapping = {
     touchend: TouchEventPayload;
 };
 /**
- * @description The idle state of the touch input state machine.
+ * Mapping of events to their output types.
  *
- * @category Input State Machine
+ * @remarks
+ * Only touchmove produces outputs (pan or zoom gestures).
+ * touchstart and touchend only manage state transitions.
+ *
+ * @category Input State Machine - Touch
  */
-export declare class IdleState extends TemplateState<TouchEventMapping, TouchContext, TouchStates> {
+export type TouchInputEventOutputMapping = {
+    touchmove: TouchOutputEvent;
+};
+/**
+ * IDLE state - waiting for two-finger touch.
+ *
+ * @remarks
+ * This state handles touch lifecycle but only transitions to PENDING when exactly
+ * two touches are active. Single touches and three+ touches are ignored.
+ *
+ * **Guard Condition**:
+ * Transitions to PENDING only when `getCurrentTouchPointsCount() === 2`.
+ * This ensures the state machine only handles two-finger gestures.
+ *
+ * @category Input State Machine - Touch
+ */
+export declare class IdleState extends TemplateState<TouchEventMapping, TouchContext, TouchStates, TouchInputEventOutputMapping> {
     private _eventReactions;
     protected _guards: Guard<TouchContext, "touchPointsCount">;
     protected _eventGuards: Partial<EventGuards<TouchEventMapping, TouchStates, TouchContext, typeof this._guards>>;
-    get eventReactions(): EventReactions<TouchEventMapping, TouchContext, TouchStates>;
+    get eventReactions(): EventReactions<TouchEventMapping, TouchContext, TouchStates, TouchInputEventOutputMapping>;
     touchstart(context: TouchContext, payload: TouchEventPayload): void;
     touchend(context: TouchContext, payload: TouchEventPayload): void;
 }
@@ -37,28 +111,75 @@ export declare class IdleState extends TemplateState<TouchEventMapping, TouchCon
  *
  * @category Input State Machine
  */
-export declare class PendingState extends TemplateState<TouchEventMapping, TouchContext, TouchStates> {
+export declare class PendingState extends TemplateState<TouchEventMapping, TouchContext, TouchStates, TouchInputEventOutputMapping> {
     private _eventReactions;
-    get eventReactions(): EventReactions<TouchEventMapping, TouchContext, TouchStates>;
+    get eventReactions(): EventReactions<TouchEventMapping, TouchContext, TouchStates, TouchInputEventOutputMapping>;
     touchstart(context: TouchContext, payload: TouchEventPayload): void;
     touchend(context: TouchContext, payload: TouchEventPayload): void;
-    touchmove(context: TouchContext, payload: TouchEventPayload): void;
+    touchmove(context: TouchContext, payload: TouchEventPayload): TouchOutputEvent;
 }
 /**
  * @description The in progress state of the touch input state machine.
  *
  * @category Input State Machine
  */
-export declare class InProgressState extends TemplateState<TouchEventMapping, TouchContext, TouchStates> {
+export declare class InProgressState extends TemplateState<TouchEventMapping, TouchContext, TouchStates, TouchInputEventOutputMapping> {
     private _eventReactions;
-    get eventReactions(): EventReactions<TouchEventMapping, TouchContext, TouchStates>;
-    touchmove(context: TouchContext, payload: TouchEventPayload): void;
+    get eventReactions(): EventReactions<TouchEventMapping, TouchContext, TouchStates, TouchInputEventOutputMapping>;
+    touchmove(context: TouchContext, payload: TouchEventPayload): TouchOutputEvent;
     touchend(context: TouchContext, payload: TouchEventPayload): void;
 }
 /**
- * @description The touch input state machine.
+ * Type alias for the touch input state machine.
  *
- * @category Input State Machine
+ * @category Input State Machine - Touch
+ */
+export type TouchInputStateMachine = TemplateStateMachine<TouchEventMapping, TouchContext, TouchStates, TouchInputEventOutputMapping>;
+/**
+ * Creates a new touch input state machine for multi-touch gesture recognition.
+ *
+ * @param context - The context providing touch point tracking and canvas access
+ * @returns A configured state machine ready to process touch events
+ *
+ * @remarks
+ * This factory creates a state machine that recognizes two-finger pan and pinch-to-zoom gestures.
+ *
+ * **State Flow**:
+ * ```
+ * IDLE → (2 touches start) → PENDING → (touch move) → IN_PROGRESS
+ * IN_PROGRESS → (touch end) → IDLE
+ * ```
+ *
+ * **Gesture Recognition Algorithm**:
+ * 1. Wait for exactly 2 touches (IDLE → PENDING)
+ * 2. On first move, determine gesture type:
+ *    - If distance change > midpoint change: ZOOM
+ *    - If midpoint change > distance change: PAN
+ * 3. Continue producing pan/zoom outputs until touches end
+ *
+ * **Pan Gesture**:
+ * Delta = current midpoint - initial midpoint
+ *
+ * **Zoom Gesture**:
+ * Delta = (current distance - initial distance) * 0.005
+ * Anchor = midpoint in viewport coordinates
+ *
+ * @category Input State Machine - Touch
+ *
+ * @example
+ * ```typescript
+ * const canvasProxy = new CanvasProxy(canvasElement);
+ * const context = new TouchInputTracker(canvasProxy);
+ * const stateMachine = createTouchInputStateMachine(context);
+ *
+ * // Process a touch start event with 2 fingers
+ * const result = stateMachine.happens("touchstart", {
+ *   points: [
+ *     {ident: 0, x: 100, y: 200},
+ *     {ident: 1, x: 300, y: 200}
+ *   ]
+ * });
+ * console.log(result.nextState); // "PENDING"
+ * ```
  */
-export type TouchInputStateMachine = TemplateStateMachine<TouchEventMapping, TouchContext, TouchStates>;
 export declare function createTouchInputStateMachine(context: TouchContext): TouchInputStateMachine;

package/input-interpretation/raw-input-parser/index.d.ts

@@ -1,2 +1,21 @@
+/**
+ * Raw input parser module exports.
+ *
+ * @remarks
+ * This module provides DOM event parsers that listen to browser events and convert them
+ * into input events for the state machines. Separate parsers handle KMT and touch input.
+ *
+ * ## Components
+ *
+ * - **{@link VanillaKMTEventParser}**: Parses keyboard, mouse, and trackpad DOM events
+ * - **{@link VanillaTouchEventParser}**: Parses touch DOM events
+ *
+ * Parsers attach to canvas elements and forward events to their respective state machines.
+ *
+ * @see {@link VanillaKMTEventParser} for KMT event parsing
+ * @see {@link VanillaTouchEventParser} for touch event parsing
+ *
+ * @module
+ */
 export * from "./vanilla-kmt-event-parser";
 export * from "./vanilla-touch-event-parser";

package/input-interpretation/raw-input-parser/vanilla-kmt-event-parser.d.ts

@@ -1,56 +1,96 @@
 import type { KmtInputStateMachine } from "../../input-interpretation/input-state-machine";
+import type { InputOrchestrator } from "../input-orchestrator";
 /**
- * @category Event Parser
+ * Interface for KMT (Keyboard/Mouse/Trackpad) event parsers.
+ *
+ * @remarks
+ * Event parsers bridge the gap between DOM events and the state machine.
+ * They listen for raw DOM events, convert them to state machine events,
+ * and coordinate with the orchestrator for output processing.
+ *
+ * @category Raw Input Parser
  */
 export interface KMTEventParser {
+    /** Whether the parser is currently disabled */
     disabled: boolean;
+    /** Initializes event listeners */
     setUp(): void;
+    /** Removes event listeners and cleans up */
     tearDown(): void;
+    /** Attaches to a new canvas element */
     attach(canvas: HTMLCanvasElement): void;
+    /** The state machine that processes parsed events */
     stateMachine: KmtInputStateMachine;
+    /** The orchestrator that handles state machine outputs */
+    orchestrator: InputOrchestrator;
 }
 /**
- * @description The minimum pointer event.
- * This is for the interoperability between the vanilla javascript and the pixijs event system.
+ * Minimal pointer event interface for framework interoperability.
  *
- * @category Event Parser
+ * @remarks
+ * This subset of the DOM PointerEvent interface allows the parser to work with
+ * both vanilla JavaScript PointerEvents and framework-wrapped events (e.g., PixiJS).
+ *
+ * @category Raw Input Parser
  */
 export type MinimumPointerEvent = {
+    /** Mouse button number (0=left, 1=middle, 2=right) */
     button: number;
+    /** Pointer type ("mouse", "pen", "touch") */
     pointerType: string;
+    /** X coordinate in window space */
     clientX: number;
+    /** Y coordinate in window space */
     clientY: number;
+    /** Bitmask of currently pressed buttons */
     buttons: number;
 };
 /**
- * @description The minimum wheel event.
- * This is for the interoperability between the vanilla javascript and the pixijs event system.
+ * Minimal wheel event interface for framework interoperability.
+ *
+ * @remarks
+ * This subset of the DOM WheelEvent interface allows the parser to work with
+ * both vanilla JavaScript WheelEvents and framework-wrapped events.
  *
- * @category Event Parser
+ * @category Raw Input Parser
  */
 export type MinimumWheelEvent = {
+    /** Prevents default scroll behavior */
     preventDefault: () => void;
+    /** Horizontal scroll delta */
     deltaX: number;
+    /** Vertical scroll delta */
     deltaY: number;
+    /** Whether Ctrl key is pressed (for zoom) */
     ctrlKey: boolean;
+    /** X coordinate in window space */
     clientX: number;
+    /** Y coordinate in window space */
     clientY: number;
 };
 /**
- * @description The minimum keyboard event.
- * This is for the interoperability between the vanilla javascript and the pixijs event system.
+ * Minimal keyboard event interface for framework interoperability.
  *
- * @category Event Parser
+ * @remarks
+ * This subset of the DOM KeyboardEvent interface allows the parser to work with
+ * both vanilla JavaScript KeyboardEvents and framework-wrapped events.
+ *
+ * @category Raw Input Parser
  */
 export type MinimumKeyboardEvent = {
+    /** Prevents default keyboard behavior */
     preventDefault: () => void;
+    /** The key that was pressed */
     key: string;
 };
 /**
- * @description The event target with pointer events.
- * This is for the interoperability between the vanilla javascript and the pixijs event system.
+ * Minimal event target interface for framework interoperability.
+ *
+ * @remarks
+ * This interface allows the parser to attach event listeners to different
+ * types of event targets (HTMLElement, Canvas, PixiJS Container, etc.).
  *
- * @category Event Parser
+ * @category Raw Input Parser
  */
 export type EventTargetWithPointerEvents = {
     addEventListener: (type: string, listener: (event: any) => void, options?: {
@@ -59,29 +99,75 @@ export type EventTargetWithPointerEvents = {
     removeEventListener: (type: string, listener: (event: any) => void) => void;
 };
 /**
- * @description The vanilla keyboard mouse and trackpad(KMT) event parser.
- * This parser converts the raw events to events that can be used by the input state machine.
+ * DOM event parser for Keyboard/Mouse/Trackpad input.
+ *
+ * @remarks
+ * This parser converts raw DOM events into state machine events and coordinates with
+ * the orchestrator to process outputs. It serves as the entry point for all KMT input
+ * in the input interpretation pipeline.
+ *
+ * **Event Flow**:
+ * ```
+ * DOM Events → Parser → State Machine → Parser → Orchestrator → Camera/Observers
+ * ```
+ *
+ * **Responsibilities**:
+ * 1. Listen for DOM pointer, wheel, and keyboard events
+ * 2. Convert DOM events to state machine event format
+ * 3. Send events to the state machine
+ * 4. Forward state machine outputs to the orchestrator
+ *
+ * **Handled DOM Events**:
+ * - pointerdown/up/move (canvas-scoped)
+ * - wheel (canvas-scoped)
+ * - keydown/up (window-scoped for spacebar)
+ *
+ * **Keyboard Handling**:
+ * Keyboard events are only processed when `document.body` is the target,
+ * preventing interference with text inputs and other UI elements.
+ *
+ * The parser can be disabled to temporarily stop input processing (e.g., during
+ * modal dialogs or animations).
+ *
+ * @category Raw Input Parser
+ *
+ * @example
+ * ```typescript
+ * const canvasElement = document.getElementById("canvas");
+ * const stateMachine = createKmtInputStateMachine(context);
+ * const orchestrator = new InputOrchestrator(cameraMux, cameraRig, publisher);
+ * const parser = new VanillaKMTEventParser(stateMachine, orchestrator, canvasElement);
+ *
+ * parser.setUp(); // Starts listening for events
+ *
+ * // Later, to disable input temporarily
+ * parser.disabled = true;
  *
- * @category Event Parser
+ * // Cleanup when done
+ * parser.tearDown();
+ * ```
  */
 export declare class VanillaKMTEventParser implements KMTEventParser {
     private _disabled;
     private _stateMachine;
+    private _orchestrator;
     private _keyfirstPressed;
     private _abortController;
     private _canvas?;
-    constructor(kmtInputStateMachine: KmtInputStateMachine, canvas?: HTMLCanvasElement);
+    constructor(kmtInputStateMachine: KmtInputStateMachine, orchestrator: InputOrchestrator, canvas?: HTMLCanvasElement | SVGSVGElement);
     get disabled(): boolean;
     set disabled(value: boolean);
     get stateMachine(): KmtInputStateMachine;
+    get orchestrator(): InputOrchestrator;
     addEventListeners(signal: AbortSignal): void;
     setUp(): void;
     tearDown(): void;
     bindFunctions(): void;
-    pointerDownHandler(e: MinimumPointerEvent): void;
-    pointerUpHandler(e: MinimumPointerEvent): void;
-    pointerMoveHandler(e: MinimumPointerEvent): void;
-    scrollHandler(e: MinimumWheelEvent): void;
+    private processEvent;
+    pointerDownHandler(e: PointerEvent): void;
+    pointerUpHandler(e: PointerEvent): void;
+    pointerMoveHandler(e: PointerEvent): void;
+    scrollHandler(e: WheelEvent): void;
     keypressHandler(e: KeyboardEvent): void;
     keyupHandler(e: KeyboardEvent): void;
     attach(canvas: HTMLCanvasElement): void;

package/input-interpretation/raw-input-parser/vanilla-touch-event-parser.d.ts

@@ -1,24 +1,83 @@
 import { TouchInputStateMachine } from "../../input-interpretation/input-state-machine/touch-input-state-machine";
+import type { InputOrchestrator } from "../input-orchestrator";
 /**
- * @description The touch event parser.
- * This is for the interoperability between the vanilla javascript and the pixijs event system.
+ * Interface for touch event parsers.
  *
- * @category Event Parser
+ * @remarks
+ * Touch event parsers bridge DOM TouchEvents and the touch state machine.
+ * They provide granular control over which gesture types are enabled.
+ *
+ * @category Raw Input Parser
  */
 export interface TouchEventParser {
+    /** Whether all touch input is disabled */
     disabled: boolean;
+    /** Whether pan gestures are disabled */
     panDisabled: boolean;
+    /** Whether zoom gestures are disabled */
     zoomDisabled: boolean;
+    /** Whether rotation gestures are disabled (currently unused) */
     rotateDisabled: boolean;
+    /** Initializes event listeners */
     setUp(): void;
+    /** Removes event listeners and cleans up */
     tearDown(): void;
+    /** Attaches to a new canvas element */
     attach(canvas: HTMLCanvasElement): void;
+    /** The state machine that processes parsed events */
+    stateMachine: TouchInputStateMachine;
+    /** The orchestrator that handles state machine outputs */
+    orchestrator: InputOrchestrator;
 }
 /**
- * @description The vanilla touch event parser.
- * This parser converts the raw events to events that can be used by the input state machine.
+ * DOM event parser for touch input.
+ *
+ * @remarks
+ * This parser converts raw DOM TouchEvents into state machine events and coordinates
+ * with the orchestrator to process outputs. It serves as the entry point for all touch
+ * input in the input interpretation pipeline.
+ *
+ * **Event Flow**:
+ * ```
+ * DOM TouchEvents → Parser → State Machine → Parser → Orchestrator → Camera/Observers
+ * ```
+ *
+ * **Responsibilities**:
+ * 1. Listen for DOM touch events (touchstart/move/end/cancel)
+ * 2. Extract touch point data (identifier, x, y)
+ * 3. Convert to state machine event format
+ * 4. Send events to the state machine
+ * 5. Forward state machine outputs to the orchestrator
+ *
+ * **Touch Point Extraction**:
+ * - touchstart/touchend: Uses `changedTouches` (only new/removed touches)
+ * - touchmove: Uses `targetTouches` (all touches on the canvas)
+ *
+ * **Gesture Control**:
+ * Individual gesture types (pan, zoom, rotate) can be disabled independently,
+ * though currently the state machine outputs are filtered by the orchestrator
+ * rather than the parser.
+ *
+ * The parser prevents default touch behavior to avoid browser scroll/zoom
+ * interfering with canvas gestures.
+ *
+ * @category Raw Input Parser
+ *
+ * @example
+ * ```typescript
+ * const canvasElement = document.getElementById("canvas");
+ * const stateMachine = createTouchInputStateMachine(context);
+ * const orchestrator = new InputOrchestrator(cameraMux, cameraRig, publisher);
+ * const parser = new VanillaTouchEventParser(stateMachine, orchestrator, canvasElement);
+ *
+ * parser.setUp(); // Starts listening for touch events
+ *
+ * // Disable zoom gestures temporarily
+ * parser.zoomDisabled = true;
  *
- * @category Event Parser
+ * // Cleanup when done
+ * parser.tearDown();
+ * ```
  */
 export declare class VanillaTouchEventParser implements TouchEventParser {
     private _canvas?;
@@ -26,9 +85,12 @@ export declare class VanillaTouchEventParser implements TouchEventParser {
     private _panDisabled;
     private _zoomDisabled;
     private _rotateDisabled;
-    private touchSM;
+    private _stateMachine;
+    private _orchestrator;
     private _abortController;
-    constructor(touchInputStateMachine: TouchInputStateMachine, canvas?: HTMLCanvasElement);
+    constructor(touchInputStateMachine: TouchInputStateMachine, orchestrator: InputOrchestrator, canvas?: HTMLCanvasElement);
+    get stateMachine(): TouchInputStateMachine;
+    get orchestrator(): InputOrchestrator;
     get touchStateMachine(): TouchInputStateMachine;
     bindListeners(): void;
     enableStrategy(): void;
@@ -42,6 +104,7 @@ export declare class VanillaTouchEventParser implements TouchEventParser {
     set zoomDisabled(zoomDisabled: boolean);
     get rotateDisabled(): boolean;
     set rotateDisabled(rotateDisabled: boolean);
+    private processEvent;
     touchstartHandler(e: TouchEvent): void;
     touchcancelHandler(e: TouchEvent): void;
     touchendHandler(e: TouchEvent): void;

package/input-interpretation/raw-input-publisher/index.d.ts

@@ -1 +1,19 @@
+/**
+ * Raw input publisher module exports.
+ *
+ * @remarks
+ * This module provides the event publishing system for raw user input events.
+ * The {@link RawUserInputPublisher} allows subscribing to input events (pan, zoom, rotate)
+ * at the application level, before they are processed into camera operations.
+ *
+ * ## Components
+ *
+ * - **{@link RawUserInputPublisher}**: Event publisher for raw input subscriptions
+ *
+ * Use this to listen to user input gestures without directly handling camera control.
+ *
+ * @see {@link RawUserInputPublisher} for the publisher implementation
+ *
+ * @module
+ */
 export * from "./raw-input-publisher";