@ue-too/board 0.9.5 → 0.11.0

package/camera/utils/rotation.d.ts

@@ -1,5 +1,18 @@
 /**
- * @description The limits of the rotation.
+ * Constraints for camera rotation defining an angular range with direction.
+ *
+ * @property start - Starting angle of the allowed range in radians
+ * @property end - Ending angle of the allowed range in radians
+ * @property ccw - If true, the range is measured counter-clockwise from start to end. If false, clockwise
+ * @property startAsTieBreaker - When clamping and distance to start equals distance to end, clamp to start if true, end if false
+ *
+ * @remarks
+ * Rotation limits define an angular arc. The direction (ccw) determines which
+ * way around the circle the range extends from start to end.
+ *
+ * For example:
+ * - start=0, end=π/2, ccw=true: allows 0 to π/2 (0° to 90°)
+ * - start=0, end=π/2, ccw=false: allows 0 to -3π/2 going clockwise (0° to 270° the other way)
  *
  * @category Camera
  */
@@ -10,7 +23,15 @@ export type RotationLimits = {
     startAsTieBreaker: boolean;
 };
 /**
- * @description The boundary of the rotation. (experimental)
+ * Experimental rotation boundary type with positive/negative direction semantics.
+ *
+ * @property start - Starting angle of the boundary in radians
+ * @property end - Ending angle of the boundary in radians
+ * @property positiveDirection - If true, range extends in positive angle direction. If false, negative direction
+ * @property startAsTieBreaker - When equidistant from start and end, prefer start if true, end if false
+ *
+ * @remarks
+ * This is an experimental alternative to {@link RotationLimits} with different direction semantics.
  *
  * @category Camera
  */
@@ -21,43 +42,152 @@ export type RotationBoundary = {
     startAsTieBreaker: boolean;
 };
 /**
- * @description Clamps the rotation within the limits.
+ * Clamps a rotation angle to stay within specified angular limits.
+ *
+ * @param rotation - The rotation angle to clamp in radians
+ * @param rotationLimits - Optional rotation constraints with direction
+ * @returns The clamped rotation angle, or original if already within limits
+ *
+ * @remarks
+ * If the rotation is outside the allowed arc, it's clamped to the nearest
+ * boundary (start or end). When equidistant from both, the `startAsTieBreaker`
+ * flag determines which boundary to use.
+ *
+ * The rotation is normalized to [0, 2π] before clamping.
+ *
+ * @example
+ * ```typescript
+ * const limits = { start: 0, end: Math.PI/2, ccw: true, startAsTieBreaker: true };
+ *
+ * clampRotation(Math.PI/4, limits);  // π/4 (within range)
+ * clampRotation(Math.PI, limits);    // π/2 (clamped to end)
+ * clampRotation(-0.1, limits);       // 0 (clamped to start)
+ * ```
  *
  * @category Camera
  */
 export declare function clampRotation(rotation: number, rotationLimits?: RotationLimits): number;
 /**
- * @description Checks if the rotation is within the limits.
+ * Checks if a rotation angle is within specified angular limits.
+ *
+ * @param rotation - The rotation angle to check in radians
+ * @param rotationLimits - Optional rotation constraints with direction
+ * @returns True if rotation is within the allowed arc or no limits specified, false otherwise
+ *
+ * @remarks
+ * Returns true if:
+ * - No limits are specified (undefined)
+ * - Start and end angles are effectively equal (full circle allowed)
+ * - Rotation falls within the arc from start to end in the specified direction
+ *
+ * The rotation is normalized to [0, 2π] before checking.
+ *
+ * @example
+ * ```typescript
+ * const limits = { start: 0, end: Math.PI/2, ccw: true, startAsTieBreaker: true };
+ *
+ * rotationWithinLimits(Math.PI/4, limits);   // true (within range)
+ * rotationWithinLimits(Math.PI, limits);     // false (outside range)
+ * rotationWithinLimits(0, limits);           // true (at start)
+ * rotationWithinLimits(Math.PI/2, limits);   // true (at end)
+ * ```
  *
  * @category Camera
  */
 export declare function rotationWithinLimits(rotation: number, rotationLimits?: RotationLimits): boolean;
 /**
- * @description Checks if the rotation is within the boundary. (experimental)
+ * Checks if a rotation angle is within an experimental rotation boundary.
+ *
+ * @param rotation - The rotation angle to check in radians
+ * @param rotationBoundary - Rotation boundary with positive/negative direction
+ * @returns True if rotation is within the boundary range, false otherwise
+ *
+ * @remarks
+ * This is an experimental alternative to {@link rotationWithinLimits} using
+ * positive/negative direction semantics instead of ccw/cw.
  *
  * @category Camera
  */
 export declare function rotationWithinBoundary(rotation: number, rotationBoundary: RotationBoundary): boolean;
 /**
- * @description Normalizes the angle to be between 0 and 2π.
+ * Normalizes an angle to the range [0, 2π).
+ *
+ * @param angle - Angle in radians (can be any value)
+ * @returns Equivalent angle in the range [0, 2π)
+ *
+ * @remarks
+ * This function wraps angles to the standard [0, 2π) range. Useful for
+ * ensuring consistent angle representation when comparing or storing angles.
+ *
+ * @example
+ * ```typescript
+ * normalizeAngleZero2TwoPI(0);           // 0
+ * normalizeAngleZero2TwoPI(Math.PI);     // π
+ * normalizeAngleZero2TwoPI(3 * Math.PI); // π (wraps around)
+ * normalizeAngleZero2TwoPI(-Math.PI/2);  // 3π/2 (negative becomes positive)
+ * normalizeAngleZero2TwoPI(2 * Math.PI); // 0 (full rotation)
+ * ```
  *
  * @category Camera
  */
 export declare function normalizeAngleZero2TwoPI(angle: number): number;
 /**
- * @description Gets the smaller angle span between two angles. (in radians)
+ * Calculates the signed angular distance between two angles, taking the shorter path.
+ *
+ * @param from - Starting angle in radians
+ * @param to - Target angle in radians
+ * @returns Signed angular difference in radians, in the range (-π, π]
+ *
+ * @remarks
+ * Returns the shortest angular path from `from` to `to`:
+ * - Positive value: rotate counter-clockwise (positive direction)
+ * - Negative value: rotate clockwise (negative direction)
+ * - Always returns the smaller of the two possible paths
+ *
+ * @example
+ * ```typescript
+ * angleSpan(0, Math.PI/2);        // π/2 (90° ccw)
+ * angleSpan(Math.PI/2, 0);        // -π/2 (90° cw)
+ * angleSpan(0, 3*Math.PI/2);      // -π/2 (shorter to go cw)
+ * angleSpan(3*Math.PI/2, 0);      // π/2 (shorter to go ccw)
+ * angleSpan(0, Math.PI);          // π (180°, ambiguous)
+ * ```
  *
  * @category Camera
  */
 export declare function angleSpan(from: number, to: number): number;
 /**
- * @description Converts degrees to radians.
+ * Converts degrees to radians.
+ *
+ * @param deg - Angle in degrees
+ * @returns Equivalent angle in radians
+ *
+ * @example
+ * ```typescript
+ * deg2rad(0);     // 0
+ * deg2rad(90);    // π/2
+ * deg2rad(180);   // π
+ * deg2rad(360);   // 2π
+ * deg2rad(-45);   // -π/4
+ * ```
  *
  * @category Camera
  */
 export declare function deg2rad(deg: number): number;
 /**
- * @description Converts radians to degrees.
+ * Converts radians to degrees.
+ *
+ * @param rad - Angle in radians
+ * @returns Equivalent angle in degrees
+ *
+ * @example
+ * ```typescript
+ * rad2deg(0);             // 0
+ * rad2deg(Math.PI/2);     // 90
+ * rad2deg(Math.PI);       // 180
+ * rad2deg(2 * Math.PI);   // 360
+ * rad2deg(-Math.PI/4);    // -45
+ * ```
  *
  * @category Camera
  */

package/camera/utils/zoom.d.ts

@@ -1,5 +1,12 @@
 /**
- * @description The limits of the zoom level.
+ * Constraints for camera zoom level with optional minimum and maximum bounds.
+ *
+ * @property min - Minimum allowed zoom level (optional, e.g., 0.1 for 10% zoom)
+ * @property max - Maximum allowed zoom level (optional, e.g., 10 for 1000% zoom)
+ *
+ * @remarks
+ * Zoom level of 1.0 represents 100% (no zoom), values >1 zoom in, values <1 zoom out.
+ * If both min and max are undefined, no constraints are applied.
  *
  * @category Camera
  */
@@ -8,17 +15,78 @@ export type ZoomLevelLimits = {
     max?: number;
 };
 /**
- * @description Checks if the zoom level limits are valid.
+ * Validates that zoom level limits are logically consistent.
+ *
+ * @param zoomLevelLimits - The zoom limits to validate
+ * @returns True if limits are valid or undefined, false if min > max
+ *
+ * @remarks
+ * Returns true if:
+ * - Limits are undefined (no constraints)
+ * - Only min or max is defined
+ * - Both are defined and min ≤ max
+ *
+ * @example
+ * ```typescript
+ * isValidZoomLevelLimits({ min: 0.5, max: 5 });    // true
+ * isValidZoomLevelLimits({ min: 5, max: 0.5 });    // false
+ * isValidZoomLevelLimits({ min: 0.5 });            // true
+ * isValidZoomLevelLimits(undefined);               // true
+ * ```
+ *
+ * @category Camera
  */
 export declare function isValidZoomLevelLimits(zoomLevelLimits: ZoomLevelLimits | undefined): boolean;
 /**
- * @description Clamps the zoom level within the limits.
+ * Clamps a zoom level to stay within specified limits.
+ *
+ * @param zoomLevel - The zoom level to clamp
+ * @param zoomLevelLimits - Optional zoom constraints
+ * @returns The clamped zoom level, or original value if already within limits
+ *
+ * @remarks
+ * If the zoom level is already within limits, returns it unchanged.
+ * If no limits are specified, returns the original value.
+ *
+ * @example
+ * ```typescript
+ * const limits = { min: 0.5, max: 4 };
+ *
+ * clampZoomLevel(2.0, limits);  // 2.0 (within bounds)
+ * clampZoomLevel(0.1, limits);  // 0.5 (clamped to min)
+ * clampZoomLevel(10, limits);   // 4.0 (clamped to max)
+ * clampZoomLevel(2.0);          // 2.0 (no limits)
+ * ```
  *
  * @category Camera
  */
 export declare function clampZoomLevel(zoomLevel: number, zoomLevelLimits?: ZoomLevelLimits): number;
 /**
- * @description Checks if the zoom level is within the limits.
+ * Checks if a zoom level is within specified limits.
+ *
+ * @param zoomLevel - The zoom level to check
+ * @param zoomLevelLimits - Optional zoom constraints
+ * @returns True if zoom level is valid and within limits, false otherwise
+ *
+ * @remarks
+ * Returns false if:
+ * - Zoom level is ≤ 0 (invalid zoom)
+ * - Zoom level exceeds maximum limit (if defined)
+ * - Zoom level is below minimum limit (if defined)
+ *
+ * Returns true if no limits are defined or zoom is within bounds.
+ *
+ * @example
+ * ```typescript
+ * const limits = { min: 0.5, max: 4 };
+ *
+ * zoomLevelWithinLimits(2.0, limits);   // true
+ * zoomLevelWithinLimits(0.1, limits);   // false (below min)
+ * zoomLevelWithinLimits(10, limits);    // false (above max)
+ * zoomLevelWithinLimits(-1, limits);    // false (negative zoom)
+ * zoomLevelWithinLimits(0, limits);     // false (zero zoom)
+ * zoomLevelWithinLimits(2.0);           // true (no limits)
+ * ```
  *
  * @category Camera
  */

package/index.d.ts

@@ -1,3 +1,40 @@
+/**
+ * @packageDocumentation
+ * Main entry point for the @ue-too/board package.
+ *
+ * @remarks
+ * This package provides a high-performance infinite canvas with pan, zoom, and rotate capabilities.
+ * The {@link Board} class is the primary API that orchestrates camera management, input handling,
+ * and coordinate transformations for building interactive 2D canvas applications.
+ *
+ * ## Key Exports
+ *
+ * - **{@link Board}**: Main class for creating an infinite canvas with camera controls
+ * - **Camera System**: Camera classes, rigs, and multiplexers for viewport management
+ * - **Input System**: Input parsers, state machines, and orchestration for user interaction
+ * - **Utilities**: Helper functions for coordinate conversion, math operations, and more
+ *
+ * @example
+ * Basic usage
+ * ```typescript
+ * import { Board } from '@ue-too/board';
+ *
+ * const canvas = document.querySelector('canvas') as HTMLCanvasElement;
+ * const board = new Board(canvas);
+ *
+ * function draw(timestamp: number) {
+ *   board.step(timestamp);
+ *
+ *   if (board.context) {
+ *     board.context.fillRect(0, 0, 100, 100);
+ *   }
+ *
+ *   requestAnimationFrame(draw);
+ * }
+ *
+ * requestAnimationFrame(draw);
+ * ```
+ */
 export * from "./boardify";
 export * from "./camera";
 export * from "./input-interpretation";