@ue-too/board 0.9.5 → 0.11.0

package/input-interpretation/index.d.ts

@@ -1,3 +1,32 @@
+/**
+ * Input interpretation system module exports.
+ *
+ * @remarks
+ * This module handles all user input processing for the board package, converting raw DOM events
+ * into camera operations through a pipeline of parsers, state machines, and orchestration.
+ *
+ * ## Architecture
+ *
+ * The input system follows this flow:
+ * 1. **Raw Input Parsers**: Listen to DOM events (mouse, keyboard, touch)
+ * 2. **Input State Machines**: Interpret event sequences (e.g., drag vs click, pinch vs pan)
+ * 3. **Input Orchestrator**: Translates gestures into camera operations
+ * 4. **Raw Input Publisher**: Publishes input events for application-level handling
+ *
+ * ## Key Components
+ *
+ * - **Parsers**: {@link VanillaKMTEventParser}, {@link VanillaTouchEventParser} for DOM event handling
+ * - **State Machines**: {@link createKmtInputStateMachine}, {@link createTouchInputStateMachine} for gesture recognition
+ * - **Orchestrator**: {@link InputOrchestrator} for coordinating camera operations
+ * - **Publisher**: {@link RawUserInputPublisher} for input event subscriptions
+ *
+ * @see {@link InputOrchestrator} for camera control coordination
+ * @see {@link VanillaKMTEventParser} for keyboard/mouse/trackpad input
+ * @see {@link VanillaTouchEventParser} for touch input
+ *
+ * @module
+ */
 export * from "./input-state-machine";
 export * from "./raw-input-publisher";
 export * from "./raw-input-parser";
+export * from "./input-orchestrator";

package/input-interpretation/input-orchestrator.d.ts

@@ -0,0 +1,197 @@
+import { KmtOutputEvent } from "./input-state-machine/kmt-input-state-machine";
+import { TouchOutputEvent } from "./input-state-machine/touch-input-state-machine";
+import { UserInputPublisher } from "./raw-input-publisher/raw-input-publisher";
+import { CameraMux } from "../camera/camera-mux";
+import { CameraRig } from "../camera/camera-rig";
+/**
+ * Union type of all output events from state machines.
+ *
+ * @remarks
+ * This type represents the unified output from both KMT (Keyboard/Mouse/Trackpad) and Touch state machines.
+ * By unifying these outputs, the orchestrator can handle events from different input modalities uniformly.
+ *
+ * @category Input Interpretation
+ */
+export type OutputEvent = KmtOutputEvent | TouchOutputEvent;
+/**
+ * Central orchestrator that coordinates input interpretation and camera control for the infinite canvas.
+ *
+ * @remarks
+ * The InputOrchestrator serves as the mediator between input state machines and camera control systems.
+ * It implements a permission-based architecture where:
+ *
+ * 1. **Event Flow**: State machines produce high-level gesture events (pan, zoom, rotate)
+ * 2. **Permission Check**: Events are sent to CameraMux for permission validation
+ * 3. **Execution**: If allowed, gestures are executed on CameraRig
+ * 4. **Broadcasting**: Raw events are simultaneously broadcast to observers via UserInputPublisher
+ *
+ * **Architecture Pattern**:
+ * ```
+ * State Machines → Orchestrator → CameraMux (permission) → CameraRig (execution)
+ *                       ↓
+ *                 UserInputPublisher (observers)
+ * ```
+ *
+ * This design decouples state machines from camera control, allowing state machines to focus solely
+ * on gesture recognition while the orchestrator handles the complexities of camera coordination,
+ * permission management, and event distribution.
+ *
+ * **Key Benefits**:
+ * - Single point of control for all camera operations
+ * - State machines remain unaware of camera implementation
+ * - Parallel path for observers to react to raw input events
+ * - Consistent handling of KMT and Touch input modalities
+ *
+ * @category Input Interpretation
+ *
+ * @example
+ * ```typescript
+ * // Create the orchestrator
+ * const cameraMux = new CameraMux();
+ * const cameraRig = new CameraRig(camera, viewport);
+ * const publisher = new RawUserInputPublisher();
+ * const orchestrator = new InputOrchestrator(cameraMux, cameraRig, publisher);
+ *
+ * // State machines send their output to the orchestrator
+ * const kmtStateMachine = createKmtInputStateMachine(kmtContext);
+ * const result = kmtStateMachine.happens("leftPointerMove", {x: 100, y: 200});
+ * orchestrator.processInputEventOutput(result.output);
+ *
+ * // Observers can subscribe to raw input events
+ * publisher.on("pan", (event) => {
+ *   console.log("Pan gesture detected:", event.diff);
+ * });
+ * ```
+ */
+export declare class InputOrchestrator {
+    private _cameraMux;
+    private _cameraRig;
+    private _publisher?;
+    /**
+     * Creates a new InputOrchestrator instance.
+     *
+     * @param cameraMux - The camera multiplexer that validates and controls camera operation permissions
+     * @param cameraRig - The camera rig that executes camera transformations
+     * @param publisher - Optional publisher for broadcasting raw input events to observers
+     *
+     * @remarks
+     * The publisher parameter is optional to support scenarios where event broadcasting is not needed.
+     * When provided, all input events are broadcast in parallel to camera control execution.
+     */
+    constructor(cameraMux: CameraMux, cameraRig: CameraRig, publisher?: UserInputPublisher);
+    /**
+     * Processes output events from state machines and routes them to camera control and observers.
+     *
+     * @param output - The output from a state machine, can be a single event, array of events, or any value
+     *
+     * @remarks
+     * This method serves as the main entry point for state machine outputs. It:
+     * 1. Validates whether the output is a valid OutputEvent
+     * 2. Handles both single events and arrays of events
+     * 3. Routes each valid event through the camera control pipeline
+     * 4. Broadcasts events to observers via the publisher
+     *
+     * Called by event parsers after the state machine processes an input and produces output.
+     * The method uses type guards to ensure type safety when handling dynamic output types.
+     *
+     * @example
+     * ```typescript
+     * const result = stateMachine.happens("scroll", {deltaX: 0, deltaY: 10, x: 100, y: 200});
+     * orchestrator.processInputEventOutput(result.output);
+     * ```
+     */
+    processInputEventOutput(output: any): void;
+    /**
+     * Type guard to check if an output value is a valid OutputEvent.
+     *
+     * @param output - The value to check
+     * @returns True if the output is a valid OutputEvent with a type property
+     *
+     * @remarks
+     * This type guard ensures type safety when processing state machine outputs.
+     * It checks for the presence of a 'type' property which is common to all OutputEvent variants.
+     */
+    private isOutputEvent;
+    /**
+     * Handles individual output events from state machines by routing to camera control and observers.
+     *
+     * @param event - The output event from a state machine (pan, zoom, rotate, cursor, or none)
+     *
+     * @remarks
+     * This method implements a dual-path architecture:
+     *
+     * **Parallel Path 1 - Observer Notification**:
+     * - Immediately broadcasts the event to all subscribers via UserInputPublisher
+     * - This allows external systems to react to user input in real-time
+     * - Independent of camera permission/execution
+     *
+     * **Parallel Path 2 - Camera Control**:
+     * - Requests permission from CameraMux for the operation
+     * - CameraMux may modify the event (e.g., clamp values, deny operation)
+     * - If permitted, executes the transformation on CameraRig
+     *
+     * Event types:
+     * - **pan**: Translates the camera viewport
+     * - **zoom**: Scales the camera around an anchor point
+     * - **rotate**: Rotates the camera view
+     * - **cursor**: Changes cursor appearance (handled by state machine)
+     * - **none**: No operation needed
+     */
+    private handleStateMachineOutput;
+    /**
+     * Processes pan output from CameraMux and executes the pan operation if permitted.
+     *
+     * @param output - The pan output from CameraMux containing permission and potentially modified delta
+     *
+     * @remarks
+     * CameraMux may deny the operation (allowPassThrough = false) or modify the delta value
+     * to enforce constraints like viewport bounds or animation states.
+     * Only when permission is granted does the pan execute on CameraRig.
+     */
+    private processPanMuxOutput;
+    /**
+     * Processes zoom output from CameraMux and executes the zoom operation if permitted.
+     *
+     * @param output - The zoom output from CameraMux containing permission and potentially modified parameters
+     *
+     * @remarks
+     * CameraMux may deny the operation or modify zoom parameters to enforce constraints
+     * like minimum/maximum zoom levels or animation states. The anchor point determines
+     * the center of the zoom transformation in viewport coordinates.
+     */
+    private processZoomMuxOutput;
+    /**
+     * Processes rotation output from CameraMux and executes the rotation operation if permitted.
+     *
+     * @param output - The rotation output from CameraMux containing permission and potentially modified delta
+     *
+     * @remarks
+     * CameraMux may deny the operation or modify the rotation delta to enforce constraints
+     * like rotation limits or animation states.
+     */
+    private processRotateMuxOutput;
+    /**
+     * Gets the UserInputPublisher for direct access to event subscription.
+     *
+     * @returns The publisher instance, or undefined if not configured
+     *
+     * @remarks
+     * Allows external code to subscribe to raw input events without going through the orchestrator.
+     */
+    get publisher(): UserInputPublisher | undefined;
+    /**
+     * Gets the CameraMux instance for direct access to permission control.
+     *
+     * @returns The camera multiplexer instance
+     */
+    get cameraMux(): CameraMux;
+    /**
+     * Sets a new CameraMux instance.
+     *
+     * @param cameraMux - The new camera multiplexer to use for permission control
+     *
+     * @remarks
+     * Allows dynamic reconfiguration of camera permission logic at runtime.
+     */
+    set cameraMux(cameraMux: CameraMux);
+}

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

@@ -1,3 +1,21 @@
+/**
+ * Input state machine module exports.
+ *
+ * @remarks
+ * This module provides state machines for interpreting raw input events into high-level gestures.
+ * Separate state machines handle keyboard/mouse/trackpad (KMT) and touch input.
+ *
+ * ## Components
+ *
+ * - **KMT State Machine**: {@link createKmtInputStateMachine} for keyboard/mouse/trackpad gestures
+ * - **Touch State Machine**: {@link createTouchInputStateMachine} for touch gestures (pan, pinch, rotate)
+ * - **Input Contexts**: {@link ObservableInputTracker}, {@link TouchInputTracker} for tracking input state
+ *
+ * @see {@link createKmtInputStateMachine} for KMT gesture recognition
+ * @see {@link createTouchInputStateMachine} for touch gesture recognition
+ *
+ * @module
+ */
 export * from "./kmt-input-context";
 export * from "./touch-input-context";
 export * from "./touch-input-state-machine";

package/input-interpretation/input-state-machine/kmt-input-context.d.ts

@@ -1,36 +1,86 @@
 import { Point } from "@ue-too/math";
 import { BaseContext } from "@ue-too/being";
-import { UserInputPublisher } from "../raw-input-publisher";
 import { CanvasPositionDimensionPublisher, Observable, Observer, SubscriptionOptions } from "../../utils";
-import { EdgeAutoCameraInput } from "src/camera";
+/**
+ * Cursor styles used to provide visual feedback for different input states.
+ *
+ * @remarks
+ * These cursor styles indicate the current interaction mode to users:
+ * - **GRAB**: Indicates the canvas is ready to be panned (spacebar pressed, no drag yet)
+ * - **GRABBING**: Indicates active panning is in progress
+ * - **DEFAULT**: Normal cursor state when no special interaction is active
+ *
+ * @category Input State Machine
+ */
 export declare enum CursorStyle {
     GRAB = "grab",
     DEFAULT = "default",
     GRABBING = "grabbing"
 }
 /**
- * @description A proxy for the canvas so that client code that needs to access
- * the canvas dimensions and position does not need to access the DOM directly.
+ * Canvas dimension and position information.
+ *
+ * @property width - The canvas width in CSS pixels
+ * @property height - The canvas height in CSS pixels
+ * @property position - The top-left position of the canvas in window coordinates
+ *
+ * @category Input State Machine
+ */
+export type CanvasDimensions = {
+    width: number;
+    height: number;
+    position: Point;
+};
+/**
+ * Abstraction interface for canvas element access and manipulation.
+ *
+ * @remarks
+ * This interface provides a decoupled way to access canvas properties without direct DOM access.
+ * Multiple implementations exist to support different use cases:
+ * - **CanvasProxy**: Full implementation for HTML canvas elements with dimension tracking
+ * - **SvgProxy**: Implementation for SVG elements
+ * - **DummyCanvas**: No-op implementation for web worker contexts
+ * - **WorkerRelayCanvas**: Relays canvas dimension updates to web workers
+ * - **CanvasCacheInWebWorker**: Caches canvas dimensions within a web worker
+ *
+ * The abstraction enables:
+ * - Coordinate system transformations (window → canvas → viewport)
+ * - Canvas dimension tracking without repeated DOM queries
+ * - Cursor style management
+ * - Support for both canvas and SVG rendering contexts
+ *
+ * @category Input State Machine
  */
 export interface Canvas {
+    /** The canvas width in CSS pixels */
     width: number;
+    /** The canvas height in CSS pixels */
     height: number;
+    /** The top-left position of the canvas in window coordinates */
     position: Point;
+    /** Sets the CSS cursor style for visual feedback */
     setCursor: (style: CursorStyle) => void;
+    /** Combined dimensions and position information */
     dimensions: CanvasDimensions;
+    /** Whether the canvas is currently detached from the DOM */
     detached: boolean;
+    /** Cleanup method to dispose of resources and event listeners */
     tearDown: () => void;
 }
-export type CanvasDimensions = {
-    width: number;
-    height: number;
-    position: Point;
-};
 /**
- * @description A dummy implementation of the CanvasOperator interface.
- * This is specifically for the case where a input state machine that is for the relay of the input events to the web worker.
- * The input state machine needs a canvas operator in its context, but this context does not have any functionality.
- * @see DummyKmtInputContext
+ * No-op implementation of Canvas interface for web worker relay contexts.
+ *
+ * @remarks
+ * This class is used when an input state machine is configured to relay events to a web worker
+ * rather than perform actual canvas operations. The state machine requires a Canvas in its context,
+ * but in the relay scenario, no actual canvas operations are needed - events are simply forwarded
+ * to the worker thread.
+ *
+ * All properties return default/empty values and all methods are no-ops.
+ *
+ * @category Input State Machine
+ *
+ * @see {@link DummyKmtInputContext}
  */
 export declare class DummyCanvas implements Canvas {
     width: number;
@@ -100,6 +150,40 @@ export declare class CanvasProxy implements Canvas, Observable<[CanvasDimensions
     attach(canvas: HTMLCanvasElement): void;
     logCanvasTrueSize(): void;
 }
+export declare class SvgProxy implements Canvas, Observable<[CanvasDimensions]> {
+    private _width;
+    private _height;
+    private _position;
+    private _svgPositionDimensionPublisher;
+    private _svg;
+    private _internalSizeUpdateObservable;
+    constructor(svg?: SVGSVGElement);
+    subscribe(observer: Observer<[CanvasDimensions]>, options?: SubscriptionOptions): () => void;
+    notify(...data: [CanvasDimensions]): void;
+    get detached(): boolean;
+    get dimensions(): {
+        width: number;
+        height: number;
+        position: Point;
+    };
+    get width(): number;
+    /**
+     * set the width of the canvas
+     * the width is synonymous with the canvas style width not the canvas width
+     */
+    setWidth(width: number): void;
+    /**
+     * set the height of the canvas
+     * the height is synonymous with the canvas style height not the canvas height
+     */
+    setHeight(height: number): void;
+    get height(): number;
+    get position(): Point;
+    setCursor(style: "grab" | "default" | "grabbing"): void;
+    tearDown(): void;
+    attach(svg: SVGSVGElement): void;
+    logCanvasTrueSize(): void;
+}
 /**
  * @description A proxy for the canvas that is used to communicate with the web worker.
  * The primary purpose of this class is to cache the canvas dimensions and position in the DOM to reduce the calling of the getBoundingClientRect method.
@@ -127,27 +211,66 @@ export declare class WorkerRelayCanvas implements Canvas {
     setCursor(style: "grab" | "default" | "grabbing"): void;
 }
 /**
- * @description The context for the keyboard mouse and trackpad input state machine.
+ * Context interface for the Keyboard/Mouse/Trackpad (KMT) input state machine.
+ *
+ * @remarks
+ * This context provides the state and behavior needed by the KMT state machine to:
+ * 1. Track cursor positions for calculating pan deltas
+ * 2. Distinguish between mouse and trackpad input modalities
+ * 3. Access canvas dimensions for coordinate transformations
+ * 4. Manage coordinate system alignment (inverted Y-axis handling)
+ *
+ * **Input Modality Detection**:
+ * The context uses a scoring system (`kmtTrackpadTrackScore`) to differentiate between
+ * mouse and trackpad input, which have different zoom behaviors:
+ * - Mouse: Ctrl+Scroll = zoom, Scroll = pan
+ * - Trackpad: Scroll = zoom (no Ctrl needed), Two-finger gesture = pan
+ *
+ * **Coordinate System**:
+ * The `alignCoordinateSystem` flag determines Y-axis orientation:
+ * - `true`: Standard screen coordinates (Y increases downward)
+ * - `false`: Inverted coordinates (Y increases upward)
+ *
+ * This interface extends BaseContext from the @ue-too/being state machine library,
+ * inheriting setup() and cleanup() lifecycle methods.
  *
  * @category Input State Machine
  */
 export interface KmtInputContext extends BaseContext {
+    /** Whether to use standard screen coordinate system (vs inverted Y-axis) */
     alignCoordinateSystem: boolean;
+    /** Canvas accessor for dimensions and cursor control */
     canvas: Canvas;
-    notifyOnPan: (delta: Point) => void;
-    notifyOnZoom: (zoomAmount: number, anchorPoint: Point) => void;
-    notifyOnRotate: (deltaRotation: number) => void;
+    /** Sets the initial cursor position when starting a pan gesture */
     setInitialCursorPosition: (position: Point) => void;
+    /** Cancels the current action and resets cursor position */
     cancelCurrentAction: () => void;
+    /** The cursor position when a pan gesture started */
     initialCursorPosition: Point;
-    setCursorPosition: (position: Point) => void;
-    toggleOnEdgeAutoCameraInput: () => void;
-    toggleOffEdgeAutoCameraInput: () => void;
+    /** Score tracking input modality: >0 for mouse, <0 for trackpad, 0 for undetermined */
+    kmtTrackpadTrackScore: number;
+    /** Decreases the score toward trackpad */
+    subtractKmtTrackpadTrackScore: () => void;
+    /** Increases the score toward mouse */
+    addKmtTrackpadTrackScore: () => void;
+    /** Sets the determined input modality */
+    setMode: (mode: 'kmt' | 'trackpad' | 'TBD') => void;
+    /** The current input modality: 'kmt' (mouse), 'trackpad', or 'TBD' (to be determined) */
+    mode: 'kmt' | 'trackpad' | 'TBD';
 }
 /**
- * @description A dummy implementation of the KmtInputContext interface.
- * This is specifically for the case where a input state machine that is for the relay of the input events to the web worker.
- * The input state machine needs a context, but this context does not have any functionality.
+ * No-op implementation of KmtInputContext for web worker relay scenarios.
+ *
+ * @remarks
+ * Used when the input state machine is configured to relay events to a web worker
+ * rather than process them locally. The state machine requires a context, but in
+ * the relay scenario, no actual state tracking is needed - events are simply forwarded.
+ *
+ * All methods are no-ops and all properties return default values.
+ *
+ * @category Input State Machine
+ *
+ * @see {@link DummyCanvas}
  */
 export declare class DummyKmtInputContext implements KmtInputContext {
     alignCoordinateSystem: boolean;
@@ -157,40 +280,70 @@ export declare class DummyKmtInputContext implements KmtInputContext {
     toggleOnEdgeAutoCameraInput: () => void;
     toggleOffEdgeAutoCameraInput: () => void;
     setCursorPosition: (position: Point) => void;
-    notifyOnPan(delta: Point): void;
-    notifyOnZoom(zoomAmount: number, anchorPoint: Point): void;
-    notifyOnRotate(deltaRotation: number): void;
     setInitialCursorPosition(position: Point): void;
     cleanup(): void;
     setup(): void;
+    get kmtTrackpadTrackScore(): number;
+    subtractKmtTrackpadTrackScore(): void;
+    addKmtTrackpadTrackScore(): void;
+    setMode(mode: 'kmt' | 'trackpad' | 'TBD'): void;
+    get mode(): 'kmt' | 'trackpad' | 'TBD';
     cancelCurrentAction(): void;
 }
 /**
- * @description The observable input tracker.
- * This is used as the context for the keyboard mouse and trackpad input state machine.
+ * Production implementation of KmtInputContext that tracks input state for the state machine.
+ *
+ * @remarks
+ * This class provides the concrete implementation of the KMT input context, maintaining
+ * all state required by the state machine to recognize and track gestures:
+ *
+ * **State Tracking**:
+ * - Initial cursor position for calculating pan deltas
+ * - Input modality score to distinguish mouse vs trackpad
+ * - Determined input mode (kmt/trackpad/TBD)
+ * - Coordinate system alignment preference
+ *
+ * **Input Modality Detection**:
+ * The `kmtTrackpadTrackScore` accumulates evidence about the input device:
+ * - Positive values indicate mouse behavior (middle-click, no horizontal scroll)
+ * - Negative values indicate trackpad behavior (horizontal scroll, two-finger gestures)
+ * - Score is used to determine zoom behavior (Ctrl+Scroll for mouse vs Scroll for trackpad)
+ *
+ * **Design Pattern**:
+ * This class follows the Context pattern from the @ue-too/being state machine library,
+ * providing stateful data and operations that states can access and modify during transitions.
  *
  * @category Input State Machine
+ *
+ * @example
+ * ```typescript
+ * const canvasProxy = new CanvasProxy(canvasElement);
+ * const context = new ObservableInputTracker(canvasProxy);
+ * const stateMachine = createKmtInputStateMachine(context);
+ *
+ * // Context tracks state as the state machine processes events
+ * stateMachine.happens("leftPointerDown", {x: 100, y: 200});
+ * console.log(context.initialCursorPosition); // {x: 100, y: 200}
+ * ```
  */
 export declare class ObservableInputTracker implements KmtInputContext {
     private _alignCoordinateSystem;
     private _canvasOperator;
-    private _inputPublisher;
     private _initialCursorPosition;
-    private _edgeAutoCameraInput;
-    private _padding;
-    constructor(canvasOperator: Canvas, inputPublisher: UserInputPublisher, edgeAutoCameraInput: EdgeAutoCameraInput);
+    private _kmtTrackpadTrackScore;
+    private _mode;
+    constructor(canvasOperator: Canvas);
+    get mode(): 'kmt' | 'trackpad' | 'TBD';
+    setMode(mode: 'kmt' | 'trackpad' | 'TBD'): void;
+    get kmtTrackpadTrackScore(): number;
+    subtractKmtTrackpadTrackScore(): void;
+    addKmtTrackpadTrackScore(): void;
     get alignCoordinateSystem(): boolean;
     get canvas(): Canvas;
     get initialCursorPosition(): Point;
     set alignCoordinateSystem(value: boolean);
-    notifyOnPan(delta: Point): void;
-    notifyOnZoom(zoomAmount: number, anchorPoint: Point): void;
-    notifyOnRotate(deltaRotation: number): void;
     cancelCurrentAction(): void;
     setInitialCursorPosition(position: Point): void;
-    toggleOnEdgeAutoCameraInput(): void;
-    toggleOffEdgeAutoCameraInput(): void;
-    setCursorPosition(position: Point): void;
     cleanup(): void;
     setup(): void;
 }