@ue-too/board 0.9.5 → 0.10.0

package/utils/ruler.d.ts

@@ -1 +1,37 @@
+/**
+ * Calculates the order of magnitude (power of 10) of a number.
+ *
+ * @param value - The number to analyze
+ * @returns The power of 10 that best represents this value's magnitude
+ *
+ * @remarks
+ * The order of magnitude helps determine appropriate tick spacing for rulers
+ * and grids. For example:
+ * - Value 1234 has order 3 (10^3 = 1000)
+ * - Value 0.056 has order -2 (10^-2 = 0.01)
+ *
+ * The calculation finds the largest power of 10 that is less than or equal
+ * to the absolute value.
+ *
+ * Edge cases:
+ * - Returns 0 for values <= 0
+ * - For values >= 1: Counts powers of 10 until reaching the value
+ * - For values < 1: Counts negative powers of 10 until reaching the value
+ *
+ * This is used by drawing utilities to automatically scale tick marks and
+ * grid lines appropriately for different zoom levels.
+ *
+ * @example
+ * ```typescript
+ * calculateOrderOfMagnitude(1500);   // 3 (between 10^3=1000 and 10^4=10000)
+ * calculateOrderOfMagnitude(85);     // 1 (between 10^1=10 and 10^2=100)
+ * calculateOrderOfMagnitude(7);      // 0 (between 10^0=1 and 10^1=10)
+ * calculateOrderOfMagnitude(0.05);   // -2 (between 10^-2=0.01 and 10^-1=0.1)
+ * calculateOrderOfMagnitude(0);      // 0 (edge case)
+ * calculateOrderOfMagnitude(-100);   // 0 (negative edge case)
+ * ```
+ *
+ * @category Drawing Utilities
+ * @see {@link drawRuler} for usage in ruler drawing
+ */
 export declare function calculateOrderOfMagnitude(value: number): number;

package/utils/zoomlevel-adjustment.d.ts

@@ -1,28 +1,164 @@
 import { Boundaries } from "../camera/utils/position";
 import { ZoomLevelLimits } from "../camera/utils/zoom";
 /**
- * @description Calculates the minimum zoom level based on the dimensions of the boundaries.
- * Used when the canvas on the html is resized.
+ * Calculates minimum zoom level to fit boundaries within canvas at any rotation.
+ *
+ * @param boundaries - The world-space boundaries to fit
+ * @param canvasWidth - Canvas width in pixels
+ * @param canvasHeight - Canvas height in pixels
+ * @param cameraRotation - Camera rotation angle in radians
+ * @returns Minimum zoom level, or undefined if boundaries are incomplete
+ *
+ * @remarks
+ * This function ensures the entire boundary region remains visible regardless
+ * of camera rotation. It considers both width and height projections of the
+ * rotated boundaries.
+ *
+ * When boundaries are rotated, they occupy a larger axis-aligned bounding box.
+ * This function calculates the minimum zoom needed to fit that box:
+ *
+ * For each dimension (width/height):
+ * 1. Project boundary width onto canvas width axis: `width * cos(rotation)`
+ * 2. Project boundary height onto canvas width axis: `height * cos(rotation)`
+ * 3. Calculate zoom needed for each projection
+ * 4. Take the maximum of all zoom levels
+ *
+ * Returns undefined if boundaries don't have both width and height defined.
+ *
+ * Used when canvas is resized to automatically adjust zoom to keep content visible.
+ *
+ * @example
+ * ```typescript
+ * const boundaries = {
+ *   min: { x: 0, y: 0 },
+ *   max: { x: 1000, y: 500 }
+ * };
+ *
+ * // No rotation, 800x600 canvas
+ * const zoom1 = minZoomLevelBaseOnDimensions(boundaries, 800, 600, 0);
+ * // Result: 1.2 (600/500, height is limiting)
+ *
+ * // 45 degree rotation
+ * const zoom2 = minZoomLevelBaseOnDimensions(
+ *   boundaries, 800, 600, Math.PI / 4
+ * );
+ * // Result: higher zoom (rotated bounds need more space)
+ * ```
  *
  * @category Camera
+ * @see {@link minZoomLevelBaseOnWidth} for width-only calculation
+ * @see {@link minZoomLevelBaseOnHeight} for height-only calculation
  */
 export declare function minZoomLevelBaseOnDimensions(boundaries: Boundaries | undefined, canvasWidth: number, canvasHeight: number, cameraRotation: number): number | undefined;
 /**
- * @description Determines if the zoom level boundaries should be updated when the canvas is resized.
- * Zoom level boundaries adjustment only tightens the zoom level boundaries; it does not relax them.
+ * Determines if zoom level boundaries should be updated.
+ *
+ * @param zoomLevelBoundaries - Current zoom level limits
+ * @param targetMinZoomLevel - Proposed new minimum zoom level
+ * @returns True if boundaries should be updated (type guard for targetMinZoomLevel)
+ *
+ * @remarks
+ * Zoom level boundary updates only tighten (increase minimum zoom), never relax.
+ * This prevents the camera from zooming out too far when boundaries shrink.
+ *
+ * Returns true (update needed) when:
+ * - No current boundaries exist (first-time setup)
+ * - Target minimum is higher than current minimum (tightening)
+ *
+ * Returns false (no update) when:
+ * - Target is undefined (invalid/incomplete)
+ * - Target is Infinity (invalid state)
+ * - Target is lower than current minimum (would relax, not allowed)
+ *
+ * This function is a type guard: when it returns true, TypeScript knows
+ * targetMinZoomLevel is a number (not undefined).
+ *
+ * @example
+ * ```typescript
+ * const currentLimits = { min: 0.5, max: 10 };
+ * const newMin = 0.8;
+ *
+ * if (zoomLevelBoundariesShouldUpdate(currentLimits, newMin)) {
+ *   // Safe to use newMin as number here
+ *   currentLimits.min = newMin;  // Tighten the limit
+ * }
+ *
+ * // No update for lower values
+ * zoomLevelBoundariesShouldUpdate(currentLimits, 0.3);  // false
+ * ```
  *
  * @category Camera
  */
 export declare function zoomLevelBoundariesShouldUpdate(zoomLevelBoundaries: ZoomLevelLimits | undefined, targetMinZoomLevel: number | undefined): targetMinZoomLevel is number;
 /**
- * @description Calculates the minimum zoom level based on the width of the boundaries.
- * Used when the canvas on the html is resized.
+ * Calculates minimum zoom level based only on boundary width.
+ *
+ * @param boundaries - The world-space boundaries
+ * @param canvasWidth - Canvas width in pixels
+ * @param canvasHeight - Canvas height in pixels
+ * @param cameraRotation - Camera rotation angle in radians
+ * @returns Minimum zoom level, or undefined if width is not defined
+ *
+ * @remarks
+ * Similar to {@link minZoomLevelBaseOnDimensions} but only considers the
+ * width constraint. Useful when height is unbounded or not relevant.
+ *
+ * Calculates zoom needed to fit the boundary width within the canvas,
+ * accounting for rotation:
+ * - Width projection on canvas X-axis: `width * cos(rotation)`
+ * - Width projection on canvas Y-axis: `width * sin(rotation)`
+ *
+ * Takes the maximum of these to ensure the width fits regardless of
+ * how rotation distributes it across canvas axes.
+ *
+ * @example
+ * ```typescript
+ * const boundaries = {
+ *   min: { x: 0 },
+ *   max: { x: 1000 }
+ * };
+ *
+ * const zoom = minZoomLevelBaseOnWidth(boundaries, 800, 600, 0);
+ * // Result: 0.8 (800/1000)
+ * ```
+ *
  * @category Camera
+ * @see {@link minZoomLevelBaseOnDimensions} for full calculation
  */
 export declare function minZoomLevelBaseOnWidth(boundaries: Boundaries | undefined, canvasWidth: number, canvasHeight: number, cameraRotation: number): number | undefined;
 /**
- * @description Calculates the minimum zoom level based on the height of the boundaries.
- * Used when the canvas on the html is resized.
+ * Calculates minimum zoom level based only on boundary height.
+ *
+ * @param boundaries - The world-space boundaries
+ * @param canvasWidth - Canvas width in pixels
+ * @param canvasHeight - Canvas height in pixels
+ * @param cameraRotation - Camera rotation angle in radians
+ * @returns Minimum zoom level, or undefined if height is not defined
+ *
+ * @remarks
+ * Similar to {@link minZoomLevelBaseOnDimensions} but only considers the
+ * height constraint. Useful when width is unbounded or not relevant.
+ *
+ * Calculates zoom needed to fit the boundary height within the canvas,
+ * accounting for rotation:
+ * - Height projection on canvas X-axis: `height * cos(rotation)`
+ * - Height projection on canvas Y-axis: `height * sin(rotation)`
+ *
+ * Takes the maximum of these to ensure the height fits regardless of
+ * how rotation distributes it across canvas axes.
+ *
+ * @example
+ * ```typescript
+ * const boundaries = {
+ *   min: { y: 0 },
+ *   max: { y: 500 }
+ * };
+ *
+ * const zoom = minZoomLevelBaseOnHeight(boundaries, 800, 600, 0);
+ * // Result: 1.2 (600/500)
+ * ```
+ *
  * @category Camera
+ * @see {@link minZoomLevelBaseOnDimensions} for full calculation
  */
 export declare function minZoomLevelBaseOnHeight(boundaries: Boundaries | undefined, canvasWidth: number, canvasHeight: number, cameraRotation: number): number | undefined;

package/camera/camera-rig/update-batcher/index.d.ts

@@ -1,3 +0,0 @@
-export * from "./position-update-batcher";
-export * from "./rotation-update-batcher";
-export * from "./zoom-udpate-batcher";

package/camera/camera-rig/update-batcher/position-update-batcher.d.ts

@@ -1,58 +0,0 @@
-import { Observer, SubscriptionOptions } from "../../../utils/observable";
-export type Position = {
-    x: number;
-    y: number;
-};
-export type Velocity = {
-    vx: number;
-    vy: number;
-};
-export type DestinationUpdate = Position & {
-    type: 'destination';
-};
-export type DeltaUpdate = Position & {
-    type: 'delta';
-};
-export type PositionUpdate = DestinationUpdate | DeltaUpdate;
-export declare class CameraPositionUpdateBatcher {
-    private nextPosition;
-    private delta;
-    private observable;
-    private queuePositionUpdateCount;
-    private queuePositionUpdateToCount;
-    private queuePositionUpdateByCount;
-    private lastUpdateCount;
-    constructor();
-    /**
-     * Queue an absolute position update to be processed in the next animation frame
-     */
-    queuePositionUpdate(x: number, y: number): void;
-    /**
-     * Queue a position update to a specific destination to be processed in the next animation frame
-     * This will override any pending delta updates
-     */
-    queuePositionUpdateTo(destination: Position): void;
-    /**
-     * Queue a position update by delta to be processed in the next animation frame
-     * This will be ignored if there's a pending destination update
-     */
-    queuePositionUpdateBy(delta: Position): void;
-    /**
-     * Process and clear all queued position updates
-     * @returns the update to apply to the position, with type information
-     */
-    processQueuedUpdates(): PositionUpdate | null;
-    /**
-     * Subscribe to position updates
-     */
-    subscribe(observer: Observer<[PositionUpdate]>, options?: SubscriptionOptions): () => void;
-    /**
-     * Get debug information about queue method calls since last update
-     */
-    getDebugInfo(): {
-        lastUpdateTotalCalls: number;
-        queuePositionUpdateCalls: number;
-        queuePositionUpdateToCalls: number;
-        queuePositionUpdateByCalls: number;
-    };
-}

package/camera/camera-rig/update-batcher/rotation-update-batcher.d.ts

@@ -1,54 +0,0 @@
-import { Observer, SubscriptionOptions } from "../../../utils/observable";
-export type Rotation = number;
-export type RotationVelocity = number;
-export type RotationDestinationUpdate = {
-    type: 'destination';
-    destination: Rotation;
-};
-export type RotationDeltaUpdate = {
-    type: 'delta';
-    delta: Rotation;
-};
-export type RotationUpdate = RotationDestinationUpdate | RotationDeltaUpdate;
-export declare class CameraRotationUpdateBatcher {
-    private nextRotation;
-    private delta;
-    private observable;
-    private queueRotationUpdateCount;
-    private queueRotationUpdateToCount;
-    private queueRotationUpdateByCount;
-    private lastUpdateCount;
-    constructor();
-    /**
-     * Queue an absolute rotation update to be processed in the next animation frame
-     */
-    queueRotationUpdate(rotation: Rotation): void;
-    /**
-     * Queue a rotation update to a specific destination to be processed in the next animation frame
-     * This will override any pending delta updates
-     */
-    queueRotationUpdateTo(destination: Rotation): void;
-    /**
-     * Queue a rotation update by delta to be processed in the next animation frame
-     * This will be ignored if there's a pending destination update
-     */
-    queueRotationUpdateBy(delta: Rotation): void;
-    /**
-     * Process and clear all queued rotation updates
-     * @returns the update to apply to the rotation, with type information
-     */
-    processQueuedUpdates(): RotationUpdate | null;
-    /**
-     * Subscribe to rotation updates
-     */
-    subscribe(observer: Observer<[RotationUpdate]>, options?: SubscriptionOptions): () => void;
-    /**
-     * Get debug information about queue method calls since last update
-     */
-    getDebugInfo(): {
-        lastUpdateTotalCalls: number;
-        queueRotationUpdateCalls: number;
-        queueRotationUpdateToCalls: number;
-        queueRotationUpdateByCalls: number;
-    };
-}

package/camera/camera-rig/update-batcher/zoom-udpate-batcher.d.ts

@@ -1,60 +0,0 @@
-import { Observer, SubscriptionOptions } from "../../../utils/observable";
-import { Point } from "@ue-too/math";
-export type DestinationZoomUpdate = {
-    type: 'destination';
-    destination: number;
-    anchor?: Point;
-};
-export type DeltaZoomUpdate = {
-    type: 'delta';
-    delta: number;
-    anchor?: Point;
-};
-export type ZoomUpdate = {
-    anchorCoordinateSystem: 'world' | 'viewport';
-    update: DestinationZoomUpdate | DeltaZoomUpdate;
-};
-export declare class CameraZoomUpdateBatcher {
-    private nextZoom;
-    private observable;
-    private anchor;
-    private delta;
-    private anchorCoordinateSystem;
-    private queueZoomUpdateCount;
-    private queueZoomUpdateToCount;
-    private lastUpdateCount;
-    constructor();
-    /**
-     * Queue a zoom update to a specific destination to be processed in the next animation frame
-     */
-    queueZoomUpdateTo(destination: number, anchor?: Point): void;
-    /**
-     * Queue a zoom update by delta to be processed in the next animation frame
-     */
-    queueZoomUpdateBy(delta: number, anchor?: Point): void;
-    /**
-     * Queue a zoom update by delta at a world anchor to be processed in the next animation frame
-     */
-    queueZoomByAtWorld(delta: number, worldAnchor: Point): void;
-    /**
-     * Queue a zoom update to a specific destination at a world anchor to be processed in the next animation frame
-     */
-    queueZoomToAtWorld(destination: number, worldAnchor: Point): void;
-    /**
-     * Process and clear all queued zoom updates
-     * @returns the update to apply to the zoom level, with type information
-     */
-    processQueuedUpdates(): ZoomUpdate | null;
-    /**
-     * Subscribe to zoom updates
-     */
-    subscribe(observer: Observer<[ZoomUpdate]>, options?: SubscriptionOptions): () => void;
-    /**
-     * Get debug information about queue method calls since last update
-     */
-    getDebugInfo(): {
-        lastUpdateTotalCalls: number;
-        queueZoomUpdateCalls: number;
-        queueZoomUpdateToCalls: number;
-    };
-}