@ue-too/board 0.12.0 → 0.13.0

package/README.md

@@ -229,20 +229,9 @@ flowchart TB
 ```
 
 **Key concepts:**
-- **Event Parsers**: Register listeners on canvas (works with vanilla, pixi.js, fabric.js, konva)
+- **Event Parsers**: Register listeners on canvas (should work with vanilla out of the box, pixi.js, fabric.js, konva with some modifications)
 - **Input State Machine**: Interprets raw events into camera intents (pan/zoom/rotate)
-- **Input Orchestrator**: Routes outputs in parallel — always publishes raw input, and asks CameraMux for permission
+- **Input Orchestrator**: Routes outputs in parallel — always publishes raw input, and asks CameraMux for permission to pass through the input to the camera rig.
 - **Camera Mux**: Controls input priority (e.g., user input can cancel animations). Returns `{allowPassThrough: true/false}`
 - **Camera Rig**: Applies movement restrictions and clamping before updating camera
 - **Observable Camera**: Final camera state with change observers
-
-## TODO
-- [x] Add a canvas position dimension publisher that can be used to get the position and dimension of the canvas.
-- [ ] Add a `boardify-pixi` package that contains utility functions for the board to work with pixi.js.
-- [ ] Add a `boardify-fabric` package that contains utility functions for the board to work with fabric.js.
-- [ ] Add a `boardify-konva` package that contains utility functions for the board to work with konva.js.
-- [ ] Add an example of the board being used with react.
-- [ ] Add an example of the board being used with svelte. (I'm learning svelte right now so I can make a example for that)
-- [ ] Add an example of the board being used with vue. (Currently I don't have any plans on learning vue so probably not going to make one very soon)
-- [ ] A documentation site. There is a lot of util stuff that I don't think will fit in here in the readme. So stay tuned! (I am experimenting with docusaurus right now so it might be a docusaurus site)
-

package/boardify/index.d.ts

@@ -6,6 +6,8 @@ import { CameraEventMap, CameraState, UnSubscribe } from '../camera/update-publi
 import { UnsubscribeToUserRawInput, RawUserInputEventMap } from '../input-interpretation/raw-input-publisher';
 import { CameraMux } from '../camera/camera-mux';
 import { CameraRig } from '../camera/camera-rig';
+import { CanvasDimensions } from '../input-interpretation/input-state-machine';
+import { InputOrchestrator } from '../input-interpretation/input-orchestrator';
 /**
  * Main user-facing API class that provides an infinite canvas with pan, zoom, and rotate capabilities.
  *
@@ -171,7 +173,11 @@ export default class Board {
     private _observableInputTracker;
     private _touchInputTracker;
     private _inputOrchestrator;
+    private _cachedCanvasWidth;
+    private _cachedCanvasHeight;
+    private _cachedCanvasPixelRatio;
     private lastUpdateTime;
+    private _canvasElement;
     /**
      * Creates a new Board instance with an optional canvas element.
      *
@@ -322,6 +328,9 @@ export default class Board {
      * @see {@link context} for accessing the rendering context
      */
     attach(canvas: HTMLCanvasElement, debug?: boolean): void;
+    disableEventListeners(): void;
+    enableEventListeners(): void;
+    get inputOrchestrator(): InputOrchestrator;
     /**
      * @group LifeCycle
      * @description This function is used to clean up the board. It removes all the event listeners and disconnects the resize observer and the attribute observer.
@@ -442,4 +451,6 @@ export default class Board {
     set clampRotation(value: boolean);
     getCameraRig(): CameraRig;
     setInputMode(mode: 'kmt' | 'trackpad'): void;
+    onCanvasDimensionChange(callback: (dimensions: CanvasDimensions) => void): () => void;
+    get canvasDimensions(): CanvasDimensions;
 }

package/camera/base.d.ts

@@ -47,6 +47,7 @@ export default class BaseCamera implements BoardCamera {
     private _rotation;
     private _zoomLevel;
     private currentCachedTransform;
+    private currentCachedTRS;
     private _viewPortWidth;
     private _viewPortHeight;
     private _boundaries?;
@@ -271,7 +272,7 @@ export default class BaseCamera implements BoardCamera {
      *
      * @see {@link getTRS} for decomposed transformation components
      */
-    getTransform(devicePixelRatio: number, alignCoorindate: boolean): {
+    getTransform(devicePixelRatio?: number, alignCoorindate?: boolean): {
         cached: boolean;
         a: number;
         b: number;
@@ -291,16 +292,17 @@ export default class BaseCamera implements BoardCamera {
      * This is useful when you need individual transformation components rather than
      * the combined matrix. Internally calls {@link getTransform} and decomposes the result.
      */
-    getTRS(devicePixelRatio: number, alignCoorindate: boolean): {
-        translation: {
+    getTRS(devicePixelRatio?: number, alignCoorindate?: boolean): {
+        scale: {
             x: number;
             y: number;
         };
         rotation: number;
-        scale: {
+        translation: {
             x: number;
             y: number;
         };
+        cached: boolean;
     };
     /**
      * Sets camera state by decomposing a transformation matrix.
@@ -321,7 +323,7 @@ export default class BaseCamera implements BoardCamera {
      * camera.setUsingTransformationMatrix(matrix);
      * ```
      */
-    setUsingTransformationMatrix(transformationMatrix: TransformationMatrix): void;
+    setUsingTransformationMatrix(transformationMatrix: TransformationMatrix, devicePixelRatio?: number): void;
     /**
      * Sets the camera rotation with boundary validation and normalization.
      *

package/camera/camera-mux/animation-and-lock/animation-and-lock.d.ts

@@ -1,10 +1,8 @@
 import { CameraMux, CameraMuxPanOutput, CameraMuxZoomOutput, CameraMuxRotationOutput } from "../interface";
 import { Point } from "@ue-too/math";
-import { ObservableBoardCamera } from "../../interface";
 import { PanControlStateMachine } from "./pan-control-state-machine";
 import { ZoomControlStateMachine } from "./zoom-control-state-machine";
 import { RotateControlStateMachine, RotateControlOutputEvent } from "./rotation-control-state-machine";
-import { CameraRig } from "../../camera-rig";
 /**
  * Advanced camera input multiplexer with animation support and input locking via state machines.
  *
@@ -95,7 +93,7 @@ export declare class CameraMuxWithAnimationAndLock implements CameraMux {
      */
     notifyPanToAnimationInput(target: Point): CameraMuxPanOutput;
     /**
-     * Processes user pan input (implements {@link CameraMux.notifyPanInput}).
+     * Processes user pan input (implements {@link CameraMux}).
      *
      * @param delta - Pan delta in viewport coordinates
      * @returns Output indicating whether pan is allowed
@@ -118,7 +116,7 @@ export declare class CameraMuxWithAnimationAndLock implements CameraMux {
      */
     notifyPanInput(delta: Point): CameraMuxPanOutput;
     /**
-     * Processes user zoom input (implements {@link CameraMux.notifyZoomInput}).
+     * Processes user zoom input (implements {@link CameraMux}).
      *
      * @param delta - Zoom delta (change in zoom level)
      * @param at - Anchor point in viewport coordinates
@@ -187,7 +185,7 @@ export declare class CameraMuxWithAnimationAndLock implements CameraMux {
      */
     notifyZoomInputAnimationWorld(targetZoom: number, at?: Point): void;
     /**
-     * Processes user rotation input (implements {@link CameraMux.notifyRotationInput}).
+     * Processes user rotation input (implements {@link CameraMux}).
      *
      * @param delta - Rotation delta in radians
      * @returns Output indicating whether rotation is allowed
@@ -303,50 +301,4 @@ export declare class CameraMuxWithAnimationAndLock implements CameraMux {
  * @see {@link CameraMuxWithAnimationAndLock} for the implementation
  * @see {@link createCameraMuxWithAnimationAndLockWithCameraRig} for custom rig version
  */
-export declare function createCameraMuxWithAnimationAndLock(camera: ObservableBoardCamera): CameraMux;
-/**
- * Creates a camera mux with animation and locking capabilities from a camera rig.
- *
- * @param cameraRig - Pre-configured camera rig to use
- * @returns Configured camera mux with animation support
- *
- * @remarks
- * Similar to {@link createCameraMuxWithAnimationAndLock} but accepts an existing
- * camera rig instead of creating a default one. Use this when you need:
- * - Custom camera rig configuration
- * - Specific pan/zoom/rotation constraints
- * - Non-default handler pipelines
- * - To share a camera rig between multiple systems
- *
- * **Advantages over camera-only variant:**
- * - Full control over camera rig settings
- * - Ability to configure boundaries, restrictions, clamping
- * - Use custom handler functions
- * - Reuse existing rig instance
- *
- * @example
- * ```typescript
- * // Create custom camera rig with specific config
- * const camera = new DefaultBoardCamera(1920, 1080);
- * const rig = new DefaultCameraRig({
- *   limitEntireViewPort: true,
- *   clampTranslation: true,
- *   boundaries: {
- *     min: { x: 0, y: 0 },
- *     max: { x: 2000, y: 1000 }
- *   }
- * }, camera);
- *
- * // Create mux with custom rig
- * const mux = createCameraMuxWithAnimationAndLockWithCameraRig(rig);
- *
- * // Animations respect rig's boundaries and constraints
- * mux.notifyPanToAnimationInput({ x: 3000, y: 1500 });
- * // Camera will be clamped to boundaries during animation
- * ```
- *
- * @category Input Flow Control
- * @see {@link CameraMuxWithAnimationAndLock} for the implementation
- * @see {@link createCameraMuxWithAnimationAndLock} for simpler camera-only version
- */
-export declare function createCameraMuxWithAnimationAndLockWithCameraRig(cameraRig: CameraRig): CameraMux;
+export declare function createCameraMuxWithAnimationAndLock(): CameraMux;

package/camera/camera-mux/animation-and-lock/pan-control-state-machine.d.ts

@@ -151,7 +151,7 @@ export declare class PanControlStateMachine extends TemplateStateMachine<PanEven
      * Forces state change to begin animation or transition sequence.
      * Called when starting programmatic camera movements.
      */
-    initateTransition(): void;
+    initateTransition(): import("@ue-too/being").EventResult<PanControlStates, void>;
 }
 /**
  * State implementation for accepting user pan input (idle/normal state).
@@ -160,7 +160,7 @@ export declare class PanControlStateMachine extends TemplateStateMachine<PanEven
  */
 export declare class AcceptingUserInputState extends TemplateState<PanEventPayloadMapping, BaseContext, PanControlStates, PanControlOutputMapping> {
     constructor();
-    eventReactions: EventReactions<PanEventPayloadMapping, BaseContext, PanControlStates, PanControlOutputMapping>;
+    protected _eventReactions: EventReactions<PanEventPayloadMapping, BaseContext, PanControlStates, PanControlOutputMapping>;
     userPanByInputHandler(context: BaseContext, payload: PanByInputEventPayload): PanControlOutputEvent;
     userPanToInputHandler(context: BaseContext, payload: PanToInputEventPayload): PanControlOutputEvent;
     lockedOnObjectPanByInputHandler(context: BaseContext, payload: PanByInputEventPayload): PanControlOutputEvent;
@@ -173,7 +173,7 @@ export declare class AcceptingUserInputState extends TemplateState<PanEventPaylo
  */
 export declare class TransitionState extends TemplateState<PanEventPayloadMapping, BaseContext, PanControlStates, PanControlOutputMapping> {
     constructor();
-    eventReactions: EventReactions<PanEventPayloadMapping, BaseContext, PanControlStates, PanControlOutputMapping>;
+    protected _eventReactions: EventReactions<PanEventPayloadMapping, BaseContext, PanControlStates, PanControlOutputMapping>;
     userPanByInputHandler(context: BaseContext, payload: PanByInputEventPayload): PanControlOutputEvent;
     userPanToInputHandler(context: BaseContext, payload: PanToInputEventPayload): PanControlOutputEvent;
     transitionPanByInputHandler(context: BaseContext, payload: PanByInputEventPayload): PanControlOutputEvent;
@@ -188,7 +188,7 @@ export declare class TransitionState extends TemplateState<PanEventPayloadMappin
  */
 export declare class LockedOnObjectState extends TemplateState<PanEventPayloadMapping, BaseContext, PanControlStates, PanControlOutputMapping> {
     constructor();
-    eventReactions: EventReactions<PanEventPayloadMapping, BaseContext, PanControlStates, PanControlOutputMapping>;
+    protected _eventReactions: EventReactions<PanEventPayloadMapping, BaseContext, PanControlStates, PanControlOutputMapping>;
     lockedOnObjectPanByInputHandler(context: BaseContext, payload: PanByInputEventPayload): PanControlOutputEvent;
     lockedOnObjectPanToInputHandler(context: BaseContext, payload: PanToInputEventPayload): PanControlOutputEvent;
 }
@@ -216,5 +216,5 @@ export declare function createDefaultPanControlStates(): Record<PanControlStates
  *
  * @category Input Flow Control
  */
-export declare function createDefaultPanControlStateMachine(context: BaseContext): PanControlStateMachine;
+export declare function createDefaultPanControlStateMachine(context?: BaseContext): PanControlStateMachine;
 export {};

package/camera/camera-mux/animation-and-lock/rotation-control-state-machine.d.ts

@@ -159,7 +159,7 @@ export declare class RotateControlStateMachine extends TemplateStateMachine<Rota
  */
 export declare class RotationAcceptingUserInputState extends TemplateState<RotateEventPayloadMapping, BaseContext, RotateControlStates, RotateControlOutputMapping> {
     constructor();
-    eventReactions: EventReactions<RotateEventPayloadMapping, BaseContext, RotateControlStates, RotateControlOutputMapping>;
+    protected _eventReactions: EventReactions<RotateEventPayloadMapping, BaseContext, RotateControlStates, RotateControlOutputMapping>;
     userRotateByInputHandler(context: BaseContext, payload: RotateByInputEventPayload): RotateControlOutputEvent;
     userRotateToInputHandler(context: BaseContext, payload: RotateToInputEventPayload): RotateControlOutputEvent;
     lockedOnObjectRotateByInputHandler(context: BaseContext, payload: RotateByInputEventPayload): RotateControlOutputEvent;
@@ -172,7 +172,7 @@ export declare class RotationAcceptingUserInputState extends TemplateState<Rotat
  */
 export declare class RotationTransitionState extends TemplateState<RotateEventPayloadMapping, BaseContext, RotateControlStates, RotateControlOutputMapping> {
     constructor();
-    eventReactions: EventReactions<RotateEventPayloadMapping, BaseContext, RotateControlStates, RotateControlOutputMapping>;
+    protected _eventReactions: EventReactions<RotateEventPayloadMapping, BaseContext, RotateControlStates, RotateControlOutputMapping>;
     userRotateByInputHandler(context: BaseContext, payload: RotateByInputEventPayload): RotateControlOutputEvent;
     userRotateToInputHandler(context: BaseContext, payload: RotateToInputEventPayload): RotateControlOutputEvent;
     transitionRotateByInputHandler(context: BaseContext, payload: RotateByInputEventPayload): RotateControlOutputEvent;
@@ -187,7 +187,7 @@ export declare class RotationTransitionState extends TemplateState<RotateEventPa
  */
 export declare class RotationLockedOnObjectState extends TemplateState<RotateEventPayloadMapping, BaseContext, RotateControlStates, RotateControlOutputMapping> {
     constructor();
-    eventReactions: EventReactions<RotateEventPayloadMapping, BaseContext, RotateControlStates, RotateControlOutputMapping>;
+    protected _eventReactions: EventReactions<RotateEventPayloadMapping, BaseContext, RotateControlStates, RotateControlOutputMapping>;
     lockedOnObjectRotateByInputHandler(context: BaseContext, payload: RotateByInputEventPayload): RotateControlOutputEvent;
     lockedOnObjectRotateToInputHandler(context: BaseContext, payload: RotateToInputEventPayload): RotateControlOutputEvent;
 }
@@ -215,5 +215,5 @@ export declare function createDefaultRotateControlStates(): Record<RotateControl
  *
  * @category Input Flow Control
  */
-export declare function createDefaultRotateControlStateMachine(context: BaseContext): RotateControlStateMachine;
+export declare function createDefaultRotateControlStateMachine(context?: BaseContext): RotateControlStateMachine;
 export {};

package/camera/camera-mux/animation-and-lock/zoom-control-state-machine.d.ts

@@ -137,8 +137,7 @@ export type ZoomControlOutputMapping = {
  * @category Input Flow Control
  */
 export declare class ZoomAcceptingUserInputState extends TemplateState<ZoomEventPayloadMapping, BaseContext, ZoomControlStates, ZoomControlOutputMapping> {
-    private _eventReactions;
-    get eventReactions(): EventReactions<ZoomEventPayloadMapping, BaseContext, ZoomControlStates, ZoomControlOutputMapping>;
+    protected _eventReactions: EventReactions<ZoomEventPayloadMapping, BaseContext, ZoomControlStates, ZoomControlOutputMapping>;
     userZoomByAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["userZoomByAtInput"]): ZoomControlOutputEvent;
     userZoomToAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["userZoomToAtInput"]): ZoomControlOutputEvent;
 }
@@ -149,8 +148,7 @@ export declare class ZoomAcceptingUserInputState extends TemplateState<ZoomEvent
  */
 export declare class ZoomTransitionState extends TemplateState<ZoomEventPayloadMapping, BaseContext, ZoomControlStates, ZoomControlOutputMapping> {
     constructor();
-    private _eventReactions;
-    get eventReactions(): EventReactions<ZoomEventPayloadMapping, BaseContext, ZoomControlStates, ZoomControlOutputMapping>;
+    protected _eventReactions: EventReactions<ZoomEventPayloadMapping, BaseContext, ZoomControlStates, ZoomControlOutputMapping>;
     lockedOnObjectZoomByAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["lockedOnObjectZoomByAtInput"]): ZoomControlOutputEvent;
     lockedOnObjectZoomToAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["lockedOnObjectZoomToAtInput"]): ZoomControlOutputEvent;
     userZoomByAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["userZoomByAtInput"]): ZoomControlOutputEvent;
@@ -168,8 +166,7 @@ export declare class ZoomTransitionState extends TemplateState<ZoomEventPayloadM
  */
 export declare class ZoomLockedOnObjectState extends TemplateState<ZoomEventPayloadMapping, BaseContext, ZoomControlStates, ZoomControlOutputMapping> {
     constructor();
-    private _eventReactions;
-    get eventReactions(): EventReactions<ZoomEventPayloadMapping, BaseContext, ZoomControlStates, ZoomControlOutputMapping>;
+    protected _eventReactions: EventReactions<ZoomEventPayloadMapping, BaseContext, ZoomControlStates, ZoomControlOutputMapping>;
     lockedOnObjectZoomByAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["lockedOnObjectZoomByAtInput"]): ZoomControlOutputEvent;
     lockedOnObjectZoomToAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["lockedOnObjectZoomToAtInput"]): ZoomControlOutputEvent;
     userZoomByAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["userZoomByAtInput"]): ZoomControlOutputEvent;
@@ -287,4 +284,4 @@ export declare function createDefaultZoomControlStates(): Record<ZoomControlStat
  *
  * @category Input Flow Control
  */
-export declare function createDefaultZoomControlStateMachine(context: BaseContext): ZoomControlStateMachine;
+export declare function createDefaultZoomControlStateMachine(context?: BaseContext): ZoomControlStateMachine;

package/camera/camera-rig/camera-rig.d.ts

@@ -507,7 +507,7 @@ export declare class DefaultCameraRig implements CameraRig {
      * When true, pan boundaries ensure the entire viewport stays within configured limits.
      * When false, only the camera center point is constrained.
      *
-     * This is a convenience setter for {@link CameraRigConfig.limitEntireViewPort}.
+     * This is a convenience setter for {@link CameraRigConfig}.limitEntireViewPort.
      */
     set limitEntireViewPort(limit: boolean);
     /**

package/camera/default-camera.d.ts

@@ -199,7 +199,7 @@ export default class DefaultBoardCamera implements ObservableBoardCamera {
      * @param alignCoorindate Whether to align the coordinate system to the camera's position
      * @returns The transformation matrix
      */
-    getTransform(devicePixelRatio: number, alignCoorindate?: boolean): TransformationMatrix;
+    getTransform(devicePixelRatio?: number, alignCoorindate?: boolean): TransformationMatrix;
     /**
      * Sets the camera rotation and notifies observers if successful.
      *
@@ -303,7 +303,7 @@ export default class DefaultBoardCamera implements ObservableBoardCamera {
      * ```
      */
     on<K extends keyof CameraEventMap>(eventName: K, callback: (event: CameraEventMap[K], cameraState: CameraState) => void, options?: SubscriptionOptions): UnSubscribe;
-    getTRS(devicePixelRatio: number, alignCoordinateSystem: boolean): {
+    getTRS(devicePixelRatio?: number, alignCoordinateSystem?: boolean): {
         scale: {
             x: number;
             y: number;
@@ -313,7 +313,9 @@ export default class DefaultBoardCamera implements ObservableBoardCamera {
             x: number;
             y: number;
         };
+        cached: boolean;
     };
+    setUsingTransformationMatrix(transformationMatrix: TransformationMatrix, devicePixelRatio?: number): void;
     viewPortInWorldSpace(alignCoordinate?: boolean): {
         top: {
             left: Point;