@ue-too/board 0.9.5 → 0.10.0

package/camera/default-camera.d.ts

@@ -7,29 +7,88 @@ import { RotationLimits } from './utils/rotation';
 import { CameraEventMap, CameraState } from './update-publisher';
 import { ObservableBoardCamera } from './interface';
 import { SubscriptionOptions } from '../utils/observable';
+/** Default viewport width in CSS pixels */
 export declare const DEFAULT_BOARD_CAMERA_VIEWPORT_WIDTH = 1000;
+/** Default viewport height in CSS pixels */
 export declare const DEFAULT_BOARD_CAMERA_VIEWPORT_HEIGHT = 1000;
+/** Default zoom level constraints (0.1x to 10x) */
 export declare const DEFAULT_BOARD_CAMERA_ZOOM_BOUNDARIES: ZoomLevelLimits;
+/** Default position boundaries (±10000 on both axes) */
 export declare const DEFAULT_BOARD_CAMERA_BOUNDARIES: Boundaries;
+/** Default rotation boundaries (unrestricted) */
 export declare const DEFAULT_BOARD_CAMERA_ROTATION_BOUNDARIES: RotationLimits | undefined;
 /**
- * @description The default board camera. This is basically the same as the {@link BaseCamera} class.
- * But it's observable.
+ * Observable camera implementation that extends {@link BaseCamera} with event notification.
+ * This is the recommended camera class for most applications.
+ *
+ * @remarks
+ * DefaultBoardCamera wraps {@link BaseCamera} and adds an event system via {@link CameraUpdatePublisher}.
+ * All camera state changes (pan, zoom, rotate) trigger corresponding events that observers can subscribe to.
+ *
+ * Use this class when you need to:
+ * - React to camera changes in your UI or game logic
+ * - Synchronize multiple systems with camera state
+ * - Implement camera-dependent features (minimap, LOD, culling)
+ *
+ * For a non-observable camera without event overhead, use {@link BaseCamera} directly.
+ *
+ * @example
+ * ```typescript
+ * const camera = new DefaultBoardCamera(1920, 1080);
+ *
+ * // Subscribe to camera events
+ * camera.on('zoom', (event, state) => {
+ *   console.log(`Zoomed by ${event.deltaZoomAmount}`);
+ *   console.log(`New zoom level: ${state.zoomLevel}`);
+ * });
+ *
+ * camera.on('pan', (event, state) => {
+ *   console.log(`Panned by (${event.diff.x}, ${event.diff.y})`);
+ * });
+ *
+ * // Camera updates trigger events
+ * camera.setZoomLevel(2.0);
+ * camera.setPosition({ x: 100, y: 200 });
+ * ```
  *
  * @category Camera
+ * @see {@link BaseCamera} for non-observable camera
+ * @see {@link ObservableBoardCamera} for the interface definition
  */
 export default class DefaultBoardCamera implements ObservableBoardCamera {
     private _baseCamera;
     private _observer;
     /**
-     * @param position The position of the camera in the world coordinate system
-     * @param rotation The rotation of the camera in the world coordinate system
-     * @param zoomLevel The zoom level of the camera
-     * @param viewPortWidth The width of the viewport. (The width of the canvas in css pixels)
-     * @param viewPortHeight The height of the viewport. (The height of the canvas in css pixels)
-     * @param boundaries The boundaries of the camera in the world coordinate system
-     * @param zoomLevelBoundaries The boundaries of the zoom level of the camera
-     * @param rotationBoundaries The boundaries of the rotation of the camera
+     * Creates a new observable camera with event notification capabilities.
+     *
+     * @param viewPortWidth - Width of the viewport in CSS pixels (default: 1000)
+     * @param viewPortHeight - Height of the viewport in CSS pixels (default: 1000)
+     * @param position - Initial camera position in world coordinates (default: {x: 0, y: 0})
+     * @param rotation - Initial rotation in radians (default: 0)
+     * @param zoomLevel - Initial zoom level (default: 1.0)
+     * @param boundaries - Position constraints (default: ±10000 on both axes)
+     * @param zoomLevelBoundaries - Zoom constraints (default: 0.1 to 10)
+     * @param rotationBoundaries - Optional rotation constraints (default: unrestricted)
+     *
+     * @example
+     * ```typescript
+     * // Camera with default settings
+     * const camera1 = new DefaultBoardCamera();
+     *
+     * // Camera with custom viewport
+     * const camera2 = new DefaultBoardCamera(1920, 1080);
+     *
+     * // Camera with all options
+     * const camera3 = new DefaultBoardCamera(
+     *   1920, 1080,
+     *   { x: 0, y: 0 },
+     *   0,
+     *   1.0,
+     *   { min: { x: -5000, y: -5000 }, max: { x: 5000, y: 5000 } },
+     *   { min: 0.5, max: 4 },
+     *   { start: 0, end: Math.PI * 2 }
+     * );
+     * ```
      */
     constructor(viewPortWidth?: number, viewPortHeight?: number, position?: Point, rotation?: number, zoomLevel?: number, boundaries?: Boundaries, zoomLevelBoundaries?: ZoomLevelLimits, rotationBoundaries?: RotationLimits | undefined);
     /**
@@ -60,13 +119,23 @@ export default class DefaultBoardCamera implements ObservableBoardCamera {
      */
     get position(): Point;
     /**
-     * @description This function is used to set the position of the camera.
-     * @param destination The destination point of the camera.
-     * @returns Whether the position is set successfully.
+     * Sets the camera position and notifies observers if successful.
+     *
+     * @param destination - Target position in world coordinates
+     * @returns True if position was updated, false if rejected by boundaries or negligible change
+     *
+     * @remarks
+     * If the position changes, a 'pan' event is triggered with the position delta and new camera state.
+     * All 'pan' and 'all' event subscribers will be notified.
      *
-     * @description This function has a guard that checks if the destination point is within the boundaries of the camera.
-     * If the destination point is not within the boundaries, the function will return false and the position will not be updated.
-     * If the destination point is within the boundaries, the function will return true and the position will be updated.
+     * @example
+     * ```typescript
+     * camera.on('pan', (event, state) => {
+     *   console.log(`Camera moved by (${event.diff.x}, ${event.diff.y})`);
+     * });
+     *
+     * camera.setPosition({ x: 100, y: 200 }); // Triggers pan event
+     * ```
      */
     setPosition(destination: Point): boolean;
     /**
@@ -84,11 +153,31 @@ export default class DefaultBoardCamera implements ObservableBoardCamera {
     set zoomBoundaries(zoomBoundaries: ZoomLevelLimits | undefined);
     setMaxZoomLevel(maxZoomLevel: number): boolean;
     setMinZoomLevel(minZoomLevel: number): boolean;
+    /**
+     * Sets the camera zoom level and notifies observers if successful.
+     *
+     * @param zoomLevel - Target zoom level (1.0 = 100%, 2.0 = 200%, etc.)
+     * @returns True if zoom was updated, false if outside boundaries or already at limit
+     *
+     * @remarks
+     * If the zoom changes, a 'zoom' event is triggered with the zoom delta and new camera state.
+     * All 'zoom' and 'all' event subscribers will be notified.
+     *
+     * @example
+     * ```typescript
+     * camera.on('zoom', (event, state) => {
+     *   console.log(`Zoom changed by ${event.deltaZoomAmount}`);
+     *   console.log(`New zoom: ${state.zoomLevel}`);
+     * });
+     *
+     * camera.setZoomLevel(2.0); // Triggers zoom event
+     * ```
+     */
     setZoomLevel(zoomLevel: number): boolean;
     /**
-     * @description The rotation of the camera in the world coordinate system.
+     * Gets the current camera rotation in radians.
      *
-     * @category Camera
+     * @returns Current rotation angle (0 to 2π)
      */
     get rotation(): number;
     /**
@@ -112,9 +201,24 @@ export default class DefaultBoardCamera implements ObservableBoardCamera {
      */
     getTransform(devicePixelRatio: number, alignCoorindate?: boolean): TransformationMatrix;
     /**
-     * @description This function is used to set the rotation of the camera.
-     * @param rotation The rotation of the camera in the world coordinate system.
-     * @returns Whether the rotation is set successfully.
+     * Sets the camera rotation and notifies observers if successful.
+     *
+     * @param rotation - Target rotation in radians
+     * @returns True if rotation was updated, false if outside boundaries or already at limit
+     *
+     * @remarks
+     * If the rotation changes, a 'rotate' event is triggered with the rotation delta and new camera state.
+     * All 'rotate' and 'all' event subscribers will be notified.
+     * Rotation is automatically normalized to 0-2π range.
+     *
+     * @example
+     * ```typescript
+     * camera.on('rotate', (event, state) => {
+     *   console.log(`Camera rotated by ${event.deltaRotation} radians`);
+     * });
+     *
+     * camera.setRotation(Math.PI / 4); // Triggers rotate event
+     * ```
      */
     setRotation(rotation: number): boolean;
     /**
@@ -149,11 +253,54 @@ export default class DefaultBoardCamera implements ObservableBoardCamera {
     setHorizontalBoundaries(min: number, max: number): void;
     setVerticalBoundaries(min: number, max: number): void;
     /**
-     * @description This function is used to subscribe to the camera events.
-     * @param eventName The name of the event to subscribe to.
-     * @param callback The callback function to be called when the event is triggered.
-     * @param options The options for the subscription.
-     * @returns The unsubscribe function.
+     * Subscribes to camera events with optional AbortController for cancellation.
+     *
+     * @typeParam K - The event type key from CameraEventMap
+     * @param eventName - Event type to listen for: 'pan', 'zoom', 'rotate', or 'all'
+     * @param callback - Function called when event occurs, receives event data and camera state
+     * @param options - Optional subscription configuration including AbortController signal
+     * @returns Function to unsubscribe from this event
+     *
+     * @remarks
+     * Available events:
+     * - 'pan': Triggered when camera position changes
+     * - 'zoom': Triggered when zoom level changes
+     * - 'rotate': Triggered when rotation changes
+     * - 'all': Triggered for any camera change (pan, zoom, or rotate)
+     *
+     * Use the AbortController pattern to manage multiple subscriptions:
+     *
+     * @example
+     * ```typescript
+     * // Basic subscription
+     * const unsubscribe = camera.on('pan', (event, state) => {
+     *   console.log(`Panned by (${event.diff.x}, ${event.diff.y})`);
+     *   console.log(`New position: (${state.position.x}, ${state.position.y})`);
+     * });
+     *
+     * // Later: unsubscribe
+     * unsubscribe();
+     *
+     * // Subscribe to all events
+     * camera.on('all', (event, state) => {
+     *   if (event.type === 'pan') {
+     *     console.log('Pan event:', event.diff);
+     *   } else if (event.type === 'zoom') {
+     *     console.log('Zoom event:', event.deltaZoomAmount);
+     *   } else if (event.type === 'rotate') {
+     *     console.log('Rotate event:', event.deltaRotation);
+     *   }
+     * });
+     *
+     * // Using AbortController for batch unsubscribe
+     * const controller = new AbortController();
+     * camera.on('pan', handlePan, { signal: controller.signal });
+     * camera.on('zoom', handleZoom, { signal: controller.signal });
+     * camera.on('rotate', handleRotate, { signal: controller.signal });
+     *
+     * // Unsubscribe all at once
+     * controller.abort();
+     * ```
      */
     on<K extends keyof CameraEventMap>(eventName: K, callback: (event: CameraEventMap[K], cameraState: CameraState) => void, options?: SubscriptionOptions): UnSubscribe;
     getTRS(devicePixelRatio: number, alignCoordinateSystem: boolean): {

package/camera/index.d.ts

@@ -1,3 +1,23 @@
+/**
+ * Camera system module exports.
+ *
+ * @remarks
+ * This module provides the complete camera system for viewport management in the board package.
+ * It includes camera implementations, constraint systems (rigs), input multiplexing, and utilities.
+ *
+ * ## Key Components
+ *
+ * - **Camera Classes**: {@link DefaultBoardCamera} for viewport transformations (pan/zoom/rotate)
+ * - **Camera Rigs**: {@link CameraRig} for enforcing boundaries and movement constraints
+ * - **Camera Multiplexers**: {@link CameraMux} for coordinating user input, animations, and programmatic control
+ * - **Utilities**: Helper functions for coordinate conversion, position calculations, and more
+ *
+ * @see {@link DefaultBoardCamera} for the main camera implementation
+ * @see {@link CameraRig} for camera constraint configuration
+ * @see {@link CameraMux} for input coordination and animation support
+ *
+ * @module
+ */
 export * from "./base";
 export * from './utils';
 export * from './default-camera';

package/camera/interface.d.ts

@@ -6,31 +6,114 @@ import { Boundaries } from "./utils/position";
 import { CameraEventMap, CameraState } from "./update-publisher";
 import { SubscriptionOptions } from "../utils/observable";
 /**
- * @description The interface for the observable board camera.
+ * Observable camera interface that extends {@link BoardCamera} with event subscription capabilities.
+ * Allows observers to subscribe to camera state changes such as pan, zoom, and rotation events.
+ *
+ * @example
+ * ```typescript
+ * const camera: ObservableBoardCamera = new DefaultBoardCamera();
+ *
+ * // Subscribe to pan events
+ * const unsubscribe = camera.on('pan', (event, state) => {
+ *   console.log('Camera panned by:', event.diff);
+ * });
+ *
+ * // Later, unsubscribe
+ * unsubscribe();
+ * ```
  *
  * @category Camera
  */
 export interface ObservableBoardCamera extends BoardCamera {
+    /**
+     * Subscribes to camera events with an optional AbortController for cancellation.
+     *
+     * @typeParam K - The event type key from CameraEventMap
+     * @param eventName - The type of camera event to listen for ('pan', 'zoom', 'rotate', or 'all')
+     * @param callback - Function called when the event occurs, receives event data and current camera state
+     * @param options - Optional subscription configuration including AbortController signal
+     * @returns Function to unsubscribe from the event
+     *
+     * @example
+     * ```typescript
+     * // Basic subscription
+     * camera.on('zoom', (event, state) => {
+     *   console.log(`Zoom changed by ${event.deltaZoomAmount}`);
+     * });
+     *
+     * // With AbortController for batch unsubscribing
+     * const controller = new AbortController();
+     * camera.on('pan', handlePan, { signal: controller.signal });
+     * camera.on('zoom', handleZoom, { signal: controller.signal });
+     *
+     * // Unsubscribe all at once
+     * controller.abort();
+     * ```
+     */
     on<K extends keyof CameraEventMap>(eventName: K, callback: (event: CameraEventMap[K], cameraState: CameraState) => void, options?: SubscriptionOptions): UnSubscribe;
 }
 /**
- * @description The interface for the board camera.
+ * Core camera interface for the infinite canvas board system.
+ * Manages camera position, rotation, zoom, and coordinate transformations between viewport and world space.
+ *
+ * The camera uses a center-anchored coordinate system where the camera position represents
+ * the center of the viewport in world coordinates.
+ *
+ * @remarks
+ * Transformation order: Scale (devicePixelRatio) → Translation (viewport center) → Rotation → Zoom → Translation (camera position)
+ *
+ * @example
+ * ```typescript
+ * const camera: BoardCamera = new BaseCamera(1920, 1080);
+ * camera.setPosition({ x: 100, y: 100 });
+ * camera.setZoomLevel(2.0);
+ * camera.setRotation(Math.PI / 4); // 45 degrees
+ *
+ * // Convert mouse position to world coordinates
+ * const worldPos = camera.convertFromViewPort2WorldSpace(mousePos);
+ * ```
  *
  * @category Camera
  */
 export interface BoardCamera {
+    /** Current camera position in world coordinates (center of viewport) */
     position: Point;
+    /** Current rotation in radians (0 to 2π), normalized */
     rotation: number;
+    /** Current zoom level (1.0 = 100%, 2.0 = 200%, etc.) */
     zoomLevel: number;
+    /** Width of the viewport in CSS pixels */
     viewPortWidth: number;
+    /** Height of the viewport in CSS pixels */
     viewPortHeight: number;
+    /** Optional position boundaries for the camera in world coordinates */
     boundaries?: Boundaries;
+    /** Optional zoom level constraints (min and max zoom) */
     zoomBoundaries?: ZoomLevelLimits;
+    /** Optional rotation constraints (start and end angles) */
     rotationBoundaries?: RotationLimits;
+    /**
+     * Calculates the axis-aligned bounding box (AABB) of the viewport in world space.
+     *
+     * @param alignCoordinate - If true, uses standard coordinate system (y-up). If false, uses inverted y-axis
+     * @returns Object with min and max points defining the bounding box
+     *
+     * @remarks
+     * Useful for culling and determining which objects are visible in the current viewport.
+     */
     viewPortAABB(alignCoordinate?: boolean): {
         min: Point;
         max: Point;
     };
+    /**
+     * Calculates the four corners of the viewport in world space, accounting for rotation.
+     *
+     * @param alignCoordinate - If true, uses standard coordinate system (y-up). If false, uses inverted y-axis
+     * @returns Object containing the four corner points (top-left, top-right, bottom-left, bottom-right)
+     *
+     * @remarks
+     * Returns the actual rotated viewport corners, not an AABB. Use this for precise viewport bounds.
+     */
     viewPortInWorldSpace(alignCoordinate?: boolean): {
         top: {
             left: Point;
@@ -41,16 +124,114 @@ export interface BoardCamera {
             right: Point;
         };
     };
+    /**
+     * Sets the camera position in world coordinates.
+     *
+     * @param destination - Target position for the camera center
+     * @returns True if position was updated, false if rejected by boundaries or no significant change
+     *
+     * @remarks
+     * Position changes smaller than 10E-10 or 1/zoomLevel are ignored to prevent floating-point jitter.
+     * Position is clamped to boundaries if set.
+     */
     setPosition(destination: Point): boolean;
+    /**
+     * Sets the camera zoom level.
+     *
+     * @param zoomLevel - Target zoom level (1.0 = 100%)
+     * @returns True if zoom was updated, false if outside boundaries or already at limit
+     *
+     * @remarks
+     * Zoom is clamped to zoomBoundaries if set. Values are clamped, not rejected.
+     */
     setZoomLevel(zoomLevel: number): boolean;
+    /**
+     * Sets the camera rotation in radians.
+     *
+     * @param rotation - Target rotation angle in radians
+     * @returns True if rotation was updated, false if outside boundaries or already at limit
+     *
+     * @remarks
+     * Rotation is automatically normalized to 0-2π range. Clamped to rotationBoundaries if set.
+     */
     setRotation(rotation: number): boolean;
+    /**
+     * Updates the minimum allowed zoom level.
+     *
+     * @param minZoomLevel - Minimum zoom level constraint
+     *
+     * @remarks
+     * If current zoom is below the new minimum, camera will zoom in to match the minimum.
+     */
     setMinZoomLevel(minZoomLevel: number): void;
+    /**
+     * Updates the maximum allowed zoom level.
+     *
+     * @param maxZoomLevel - Maximum zoom level constraint
+     */
     setMaxZoomLevel(maxZoomLevel: number): void;
+    /**
+     * Sets horizontal (x-axis) movement boundaries for the camera.
+     *
+     * @param min - Minimum x coordinate in world space
+     * @param max - Maximum x coordinate in world space
+     *
+     * @remarks
+     * If min > max, values are automatically swapped.
+     */
     setHorizontalBoundaries(min: number, max: number): void;
+    /**
+     * Sets vertical (y-axis) movement boundaries for the camera.
+     *
+     * @param min - Minimum y coordinate in world space
+     * @param max - Maximum y coordinate in world space
+     *
+     * @remarks
+     * If min > max, values are automatically swapped.
+     */
     setVerticalBoundaries(min: number, max: number): void;
+    /**
+     * Gets the camera origin position in window coordinates.
+     *
+     * @deprecated This method is deprecated and will be removed in a future version
+     * @param centerInWindow - Center point in window coordinates
+     * @returns The camera origin point (currently just returns the input)
+     */
     getCameraOriginInWindow(centerInWindow: Point): Point;
+    /**
+     * Converts a point from viewport coordinates to world coordinates.
+     *
+     * @param point - Point in viewport space (pixels from viewport center)
+     * @returns Corresponding point in world coordinates
+     *
+     * @example
+     * ```typescript
+     * // Convert mouse position (relative to viewport center) to world position
+     * const mouseViewport = { x: mouseX - canvas.width/2, y: mouseY - canvas.height/2 };
+     * const worldPos = camera.convertFromViewPort2WorldSpace(mouseViewport);
+     * ```
+     */
     convertFromViewPort2WorldSpace(point: Point): Point;
+    /**
+     * Converts a point from world coordinates to viewport coordinates.
+     *
+     * @param point - Point in world coordinates
+     * @returns Corresponding point in viewport space (pixels from viewport center)
+     *
+     * @example
+     * ```typescript
+     * // Find viewport position of a world object
+     * const viewportPos = camera.convertFromWorld2ViewPort(objectWorldPos);
+     * ```
+     */
     convertFromWorld2ViewPort(point: Point): Point;
+    /**
+     * Decomposes the camera transformation into Translation, Rotation, and Scale components.
+     *
+     * @param devicePixelRatio - Device pixel ratio for high-DPI displays
+     * @param alignCoordinateSystem - If true, uses standard coordinate system (y-up). If false, uses inverted y-axis
+     * @returns Object containing separate scale, rotation, and translation values
+     */
     getTRS(devicePixelRatio: number, alignCoordinateSystem: boolean): {
         scale: {
             x: number;
@@ -62,6 +243,25 @@ export interface BoardCamera {
             y: number;
         };
     };
+    /**
+     * Calculates the complete transformation matrix for rendering.
+     * This matrix transforms from world space to canvas pixel space.
+     *
+     * @param devicePixelRatio - Device pixel ratio for high-DPI displays (typically window.devicePixelRatio)
+     * @param alignCoordinateSystem - If true, uses standard coordinate system (y-up). If false, uses inverted y-axis
+     * @returns 2D transformation matrix in standard form {a, b, c, d, e, f}
+     *
+     * @remarks
+     * Apply this matrix to canvas context: `ctx.setTransform(a, b, c, d, e, f)`
+     * The transformation includes devicePixelRatio scaling, viewport centering, rotation, zoom, and camera position.
+     *
+     * @example
+     * ```typescript
+     * const transform = camera.getTransform(window.devicePixelRatio, true);
+     * ctx.setTransform(transform.a, transform.b, transform.c, transform.d, transform.e, transform.f);
+     * // Now draw in world coordinates
+     * ```
+     */
     getTransform(devicePixelRatio: number, alignCoordinateSystem: boolean): {
         a: number;
         b: number;