@ue-too/board 0.9.4 → 0.10.0

package/camera/utils/matrix.d.ts

@@ -1,10 +1,52 @@
 /**
- * @description The transform matrix for the camera.
- * It's in the format like this:
+ * 2D affine transformation matrix in standard CSS/Canvas format.
+ *
+ * Represents a 3x3 matrix in homogeneous coordinates, stored in the compact 6-parameter form:
  * ```
- * | a    c    e |
- * | b    d    f |
- * | 0    0    1 |
+ * | a  c  e |
+ * | b  d  f |
+ * | 0  0  1 |
+ * ```
+ *
+ * @property a - Horizontal scaling / rotation component (m11)
+ * @property b - Vertical skewing / rotation component (m12)
+ * @property c - Horizontal skewing / rotation component (m21)
+ * @property d - Vertical scaling / rotation component (m22)
+ * @property e - Horizontal translation (tx)
+ * @property f - Vertical translation (ty)
+ *
+ * @remarks
+ * This format is compatible with:
+ * - Canvas 2D context: `ctx.setTransform(a, b, c, d, e, f)`
+ * - CSS transforms: `matrix(a, b, c, d, e, f)`
+ * - SVG transforms: `matrix(a b c d e f)`
+ *
+ * Common transformation types:
+ * - **Translation**: `{a: 1, b: 0, c: 0, d: 1, e: tx, f: ty}`
+ * - **Scaling**: `{a: sx, b: 0, c: 0, d: sy, e: 0, f: 0}`
+ * - **Rotation**: `{a: cos(θ), b: sin(θ), c: -sin(θ), d: cos(θ), e: 0, f: 0}`
+ *
+ * @example
+ * ```typescript
+ * // Identity matrix (no transformation)
+ * const identity: TransformationMatrix = {
+ *   a: 1, b: 0, c: 0, d: 1, e: 0, f: 0
+ * };
+ *
+ * // Translation by (100, 50)
+ * const translate: TransformationMatrix = {
+ *   a: 1, b: 0, c: 0, d: 1, e: 100, f: 50
+ * };
+ *
+ * // 2x scale
+ * const scale: TransformationMatrix = {
+ *   a: 2, b: 0, c: 0, d: 2, e: 0, f: 0
+ * };
+ *
+ * // 45° rotation
+ * const rotate: TransformationMatrix = {
+ *   a: 0.707, b: 0.707, c: -0.707, d: 0.707, e: 0, f: 0
+ * };
  * ```
  *
  * @category Camera
@@ -18,16 +60,51 @@ export type TransformationMatrix = {
     f: number;
 };
 /**
- * Decomposes a camera transformation matrix back to camera parameters
+ * Decomposes a camera transformation matrix back to camera parameters.
+ * Inverse operation of {@link createCameraMatrix}.
  *
- * Transformation order:
- * 1. Scale by device pixel ratio
+ * @param transformMatrix - The combined transformation matrix to decompose
+ * @param devicePixelRatio - Device pixel ratio used when creating the matrix
+ * @param canvasWidth - Canvas width in CSS pixels
+ * @param canvasHeight - Canvas height in CSS pixels
+ * @returns Camera parameters: position, zoom, and rotation
+ *
+ * @remarks
+ * This function reverses the transformation chain applied by {@link createCameraMatrix}:
+ * 1. Scale by devicePixelRatio
  * 2. Translate to canvas center
  * 3. Rotate by -camera.rotation
  * 4. Scale by zoom level
  * 5. Translate by -camera.position
  *
- * Final matrix: M = S1 * T1 * R * S2 * T2
+ * Final matrix: M = Scale(DPR) * Translate(center) * Rotate * Scale(zoom) * Translate(-position)
+ *
+ * The decomposition extracts:
+ * - **Rotation**: From the orientation of the transformation (atan2)
+ * - **Zoom**: From the total scale after removing devicePixelRatio
+ * - **Position**: By reversing the translation chain
+ *
+ * @example
+ * ```typescript
+ * // Create and then decompose a matrix
+ * const matrix = createCameraMatrix(
+ *   { x: 100, y: 200 },
+ *   2.0,
+ *   Math.PI / 4,
+ *   window.devicePixelRatio,
+ *   1920, 1080
+ * );
+ *
+ * const params = decomposeCameraMatrix(
+ *   matrix,
+ *   window.devicePixelRatio,
+ *   1920, 1080
+ * );
+ * // params ≈ { position: {x: 100, y: 200}, zoom: 2.0, rotation: π/4 }
+ * ```
+ *
+ * @category Camera
+ * @see {@link createCameraMatrix} for the inverse operation
  */
 export declare function decomposeCameraMatrix(transformMatrix: TransformationMatrix, devicePixelRatio: number, canvasWidth: number, canvasHeight: number): {
     position: {
@@ -37,6 +114,55 @@ export declare function decomposeCameraMatrix(transformMatrix: TransformationMat
     zoom: number;
     rotation: number;
 };
+/**
+ * Creates a camera transformation matrix from camera parameters.
+ * This matrix transforms world coordinates to canvas pixel coordinates.
+ *
+ * @param cameraPos - Camera position in world coordinates
+ * @param zoom - Zoom level (1.0 = 100%, 2.0 = 200%, etc.)
+ * @param rotation - Camera rotation in radians
+ * @param devicePixelRatio - Device pixel ratio (typically window.devicePixelRatio)
+ * @param canvasWidth - Canvas width in CSS pixels (not canvas.width!)
+ * @param canvasHeight - Canvas height in CSS pixels (not canvas.height!)
+ * @returns Transformation matrix for world→canvas conversion
+ *
+ * @remarks
+ * **Important**: canvasWidth and canvasHeight are CSS pixel dimensions,
+ * not the internal canvas buffer size (canvas.width/canvas.height).
+ * Use element.clientWidth/clientHeight or the CSS dimensions.
+ *
+ * Transformation order:
+ * 1. Scale by devicePixelRatio (for high-DPI displays)
+ * 2. Translate to canvas center
+ * 3. Rotate by -camera.rotation (negated for correct direction)
+ * 4. Scale by zoom
+ * 5. Translate by -camera.position (world offset)
+ *
+ * The resulting matrix can be applied to a canvas context:
+ * ```typescript
+ * const {a, b, c, d, e, f} = createCameraMatrix(...);
+ * ctx.setTransform(a, b, c, d, e, f);
+ * // Now draw at world coordinates
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const matrix = createCameraMatrix(
+ *   { x: 100, y: 200 },          // camera position
+ *   2.0,                          // 2x zoom
+ *   Math.PI / 6,                  // 30° rotation
+ *   window.devicePixelRatio,
+ *   canvas.clientWidth,           // CSS width, not canvas.width!
+ *   canvas.clientHeight
+ * );
+ *
+ * ctx.setTransform(matrix.a, matrix.b, matrix.c, matrix.d, matrix.e, matrix.f);
+ * ctx.fillRect(100, 200, 50, 50);  // Draws at world coordinates (100, 200)
+ * ```
+ *
+ * @category Camera
+ * @see {@link decomposeCameraMatrix} for extracting camera parameters from a matrix
+ */
 export declare function createCameraMatrix(cameraPos: {
     x: number;
     y: number;
@@ -48,6 +174,55 @@ export declare function createCameraMatrix(cameraPos: {
     e: number;
     f: number;
 };
+/**
+ * Multiplies two 2D transformation matrices.
+ * Order matters: M = m1 × m2 applies m2 first, then m1.
+ *
+ * @param m1 - First transformation matrix (applied second)
+ * @param m2 - Second transformation matrix (applied first)
+ * @returns Combined transformation matrix
+ *
+ * @remarks
+ * Matrix multiplication is not commutative: m1 × m2 ≠ m2 × m1
+ *
+ * The result applies transformations in right-to-left order:
+ * - Result = m1 × m2
+ * - Applying result to point P: (m1 × m2) × P = m1 × (m2 × P)
+ * - m2 is applied first, then m1
+ *
+ * Common use: Building composite transformations
+ * ```typescript
+ * // Translate then rotate (rotate happens first!)
+ * const translate = { a: 1, b: 0, c: 0, d: 1, e: 100, f: 0 };
+ * const rotate = { a: 0, b: 1, c: -1, d: 0, e: 0, f: 0 }; // 90° ccw
+ * const combined = multiplyMatrix(translate, rotate);
+ * // Points are rotated, then translated
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Combine scale and translation
+ * const scale2x: TransformationMatrix = {
+ *   a: 2, b: 0, c: 0, d: 2, e: 0, f: 0
+ * };
+ * const translate: TransformationMatrix = {
+ *   a: 1, b: 0, c: 0, d: 1, e: 100, f: 50
+ * };
+ *
+ * // Scale then translate
+ * const combined = multiplyMatrix(translate, scale2x);
+ * // Points are scaled by 2, then translated by (100, 50)
+ *
+ * // Chain multiple transformations
+ * const m = multiplyMatrix(
+ *   multiplyMatrix(translate, rotate),
+ *   scale
+ * );
+ * // Equivalent to: scale → rotate → translate
+ * ```
+ *
+ * @category Matrix
+ */
 export declare function multiplyMatrix(m1: TransformationMatrix, m2: TransformationMatrix): {
     a: number;
     b: number;
@@ -76,14 +251,42 @@ export declare function decomposeTRS(matrix: TransformationMatrix): {
     };
 };
 /**
- * Creates a transformation matrix from TRS components
+ * Creates a transformation matrix from Translation, Rotation, and Scale components.
+ * Inverse of {@link decomposeTRS}.
  *
- * @param translation - Translation vector
- * @param rotation - Rotation in radians
- * @param scale - Scale vector
- * @returns Transformation matrix
+ * @param translation - Translation vector (tx, ty)
+ * @param rotation - Rotation angle in radians (counter-clockwise)
+ * @param scale - Scale vector (sx, sy)
+ * @returns Transformation matrix combining TRS
+ *
+ * @remarks
+ * Transformation order: Scale → Rotate → Translate
+ *
+ * The resulting matrix is in standard form compatible with Canvas/CSS/SVG.
+ * Applying this matrix transforms points as:
+ * 1. Scale by (sx, sy)
+ * 2. Rotate by θ radians
+ * 3. Translate by (tx, ty)
+ *
+ * @example
+ * ```typescript
+ * // Create a transform that scales 2x, rotates 45°, then moves to (100, 50)
+ * const matrix = createTRSMatrix(
+ *   { x: 100, y: 50 },            // translation
+ *   Math.PI / 4,                   // 45° rotation
+ *   { x: 2, y: 2 }                 // 2x scale
+ * );
+ *
+ * ctx.setTransform(matrix.a, matrix.b, matrix.c, matrix.d, matrix.e, matrix.f);
+ * // Now drawing happens with scale→rotate→translate applied
+ *
+ * // Round-trip test
+ * const decomposed = decomposeTRS(matrix);
+ * // decomposed ≈ { translation: {x:100, y:50}, rotation: π/4, scale: {x:2, y:2} }
+ * ```
  *
  * @category Matrix
+ * @see {@link decomposeTRS} for extracting TRS from a matrix
  */
 export declare function createTRSMatrix(translation: {
     x: number;

package/camera/utils/position.d.ts

@@ -1,7 +1,41 @@
 import { Point } from "@ue-too/math";
 /**
- * @description The boundaries of a camera.
- * The x and y are in world space.
+ * Position boundaries for camera movement in world space.
+ * Allows optional constraints on x and y axes independently.
+ *
+ * @property min - Minimum position constraints (both x and y are optional)
+ * @property max - Maximum position constraints (both x and y are optional)
+ *
+ * @remarks
+ * All coordinates are in world space. Each axis (x, y) can be:
+ * - Fully constrained: both min and max defined
+ * - Partially constrained: only min or max defined
+ * - Unconstrained: neither min nor max defined
+ *
+ * This allows for flexible boundary configurations like:
+ * - Horizontal-only boundaries (x constrained, y free)
+ * - Vertical-only boundaries (y constrained, x free)
+ * - One-sided boundaries (e.g., minimum x but no maximum)
+ *
+ * @example
+ * ```typescript
+ * // Fully constrained rectangular boundary
+ * const rect: Boundaries = {
+ *   min: { x: -1000, y: -1000 },
+ *   max: { x: 1000, y: 1000 }
+ * };
+ *
+ * // Horizontal constraints only
+ * const horizontal: Boundaries = {
+ *   min: { x: -500 },
+ *   max: { x: 500 }
+ * };
+ *
+ * // One-sided constraint (can't go below y=0)
+ * const floor: Boundaries = {
+ *   min: { y: 0 }
+ * };
+ * ```
  *
  * @category Camera
  */
@@ -16,56 +50,260 @@ export type Boundaries = {
     };
 };
 /**
- * @description Checks if a point is within the boundaries.
+ * Checks if a point is within the specified boundaries.
+ *
+ * @param point - Point to check in world coordinates
+ * @param boundaries - Optional boundary constraints
+ * @returns True if point is within boundaries or no boundaries specified, false otherwise
+ *
+ * @remarks
+ * Returns true if:
+ * - No boundaries are defined (undefined)
+ * - Point satisfies all defined constraints
+ *
+ * Each axis is checked independently. A missing constraint on an axis means
+ * that axis is unbounded.
+ *
+ * @example
+ * ```typescript
+ * const bounds: Boundaries = {
+ *   min: { x: -100, y: -50 },
+ *   max: { x: 100, y: 50 }
+ * };
+ *
+ * withinBoundaries({ x: 0, y: 0 }, bounds);      // true (inside)
+ * withinBoundaries({ x: 150, y: 0 }, bounds);    // false (x too large)
+ * withinBoundaries({ x: 0, y: -100 }, bounds);   // false (y too small)
+ * withinBoundaries({ x: 100, y: 50 }, bounds);   // true (on boundary)
+ * withinBoundaries({ x: 0, y: 0 }, undefined);   // true (no bounds)
+ * ```
  *
  * @category Camera
  */
 export declare function withinBoundaries(point: Point, boundaries: Boundaries | undefined): boolean;
 /**
- * @description Checks if the boundaries are valid.
+ * Validates that boundaries are logically consistent.
+ *
+ * @param boundaries - The boundaries to validate
+ * @returns True if boundaries are valid or undefined, false if min >= max on any axis
+ *
+ * @remarks
+ * Returns false if:
+ * - On any axis, both min and max are defined AND min >= max
+ *
+ * Returns true if:
+ * - Boundaries are undefined
+ * - Only min or max is defined on an axis
+ * - Both are defined and min < max on all axes
+ *
+ * @example
+ * ```typescript
+ * isValidBoundaries({ min: { x: 0, y: 0 }, max: { x: 100, y: 100 } }); // true
+ * isValidBoundaries({ min: { x: 100 }, max: { x: 0 } });               // false (min > max)
+ * isValidBoundaries({ min: { x: 50, y: 50 }, max: { x: 50, y: 60 } }); // false (x min == max)
+ * isValidBoundaries({ min: { x: 0 } });                                // true (partial)
+ * isValidBoundaries(undefined);                                         // true
+ * ```
  *
  * @category Camera
  */
 export declare function isValidBoundaries(boundaries: Boundaries | undefined): boolean;
 /**
- * @description Checks if the boundaries are fully defined.
+ * Checks if boundaries have all four constraints (min/max for both x and y) defined.
+ *
+ * @param boundaries - The boundaries to check
+ * @returns True if all four constraints are defined, false otherwise
+ *
+ * @remarks
+ * Returns true only if boundaries define a complete rectangular region:
+ * - min.x, min.y, max.x, and max.y are all defined
+ *
+ * @example
+ * ```typescript
+ * boundariesFullyDefined({
+ *   min: { x: 0, y: 0 },
+ *   max: { x: 100, y: 100 }
+ * }); // true
+ *
+ * boundariesFullyDefined({
+ *   min: { x: 0, y: 0 },
+ *   max: { x: 100 }  // missing max.y
+ * }); // false
+ *
+ * boundariesFullyDefined({ min: { x: 0 } }); // false
+ * boundariesFullyDefined(undefined);          // false
+ * ```
  *
  * @category Camera
  */
 export declare function boundariesFullyDefined(boundaries: Boundaries | undefined): boolean;
 /**
- * @description Clamps a point to the boundaries.
+ * Clamps a point to stay within specified boundaries.
+ *
+ * @param point - Point to clamp in world coordinates
+ * @param boundaries - Optional boundary constraints
+ * @returns Clamped point, or original if already within bounds or no boundaries
+ *
+ * @remarks
+ * Each axis is clamped independently:
+ * - If a min constraint exists on an axis, ensures point >= min
+ * - If a max constraint exists on an axis, ensures point <= max
+ * - If no constraint exists on an axis, that axis is unchanged
+ *
+ * @example
+ * ```typescript
+ * const bounds: Boundaries = {
+ *   min: { x: -100, y: -50 },
+ *   max: { x: 100, y: 50 }
+ * };
+ *
+ * clampPoint({ x: 0, y: 0 }, bounds);       // { x: 0, y: 0 } (inside)
+ * clampPoint({ x: 150, y: 0 }, bounds);     // { x: 100, y: 0 } (clamped x)
+ * clampPoint({ x: 0, y: -100 }, bounds);    // { x: 0, y: -50 } (clamped y)
+ * clampPoint({ x: 200, y: -200 }, bounds);  // { x: 100, y: -50 } (both clamped)
+ * clampPoint({ x: 0, y: 0 }, undefined);    // { x: 0, y: 0 } (no bounds)
+ * ```
  *
  * @category Camera
  */
 export declare function clampPoint(point: Point, boundaries: Boundaries | undefined): Point;
 /**
- * @description Gets the translation width of the boundaries.
+ * Calculates the width (x-axis span) of the boundaries.
+ *
+ * @param boundaries - The boundaries to measure
+ * @returns Width in world units, or undefined if x boundaries are not fully defined
+ *
+ * @remarks
+ * Returns undefined if boundaries don't have both min.x and max.x defined.
+ * Result is always non-negative for valid boundaries (max.x - min.x).
+ *
+ * @example
+ * ```typescript
+ * translationWidthOf({
+ *   min: { x: -100, y: -50 },
+ *   max: { x: 100, y: 50 }
+ * }); // 200
+ *
+ * translationWidthOf({ min: { x: 0 } }); // undefined (no max.x)
+ * translationWidthOf(undefined);          // undefined
+ * ```
  *
  * @category Camera
  */
 export declare function translationWidthOf(boundaries: Boundaries | undefined): number | undefined;
 /**
- * @description Gets the half translation width of the boundaries.
+ * Calculates half the width (x-axis half-span) of the boundaries.
+ *
+ * @param boundaries - The boundaries to measure
+ * @returns Half-width in world units, or undefined if x boundaries are not fully defined
+ *
+ * @remarks
+ * Useful for calculating radius or offset from center for x-axis.
+ * Equivalent to `translationWidthOf(boundaries) / 2`.
+ *
+ * @example
+ * ```typescript
+ * halfTranslationWidthOf({
+ *   min: { x: -100, y: -50 },
+ *   max: { x: 100, y: 50 }
+ * }); // 100
+ * ```
  *
  * @category Camera
  */
 export declare function halfTranslationWidthOf(boundaries: Boundaries | undefined): number | undefined;
 /**
- * @description Gets the translation height of the boundaries.
+ * Calculates the height (y-axis span) of the boundaries.
+ *
+ * @param boundaries - The boundaries to measure
+ * @returns Height in world units, or undefined if y boundaries are not fully defined
+ *
+ * @remarks
+ * Returns undefined if boundaries don't have both min.y and max.y defined.
+ * Result is always non-negative for valid boundaries (max.y - min.y).
+ *
+ * @example
+ * ```typescript
+ * translationHeightOf({
+ *   min: { x: -100, y: -50 },
+ *   max: { x: 100, y: 50 }
+ * }); // 100
+ *
+ * translationHeightOf({ min: { y: 0 } }); // undefined (no max.y)
+ * translationHeightOf(undefined);          // undefined
+ * ```
  *
  * @category Camera
  */
 export declare function translationHeightOf(boundaries: Boundaries | undefined): number | undefined;
 /**
- * @description Gets the half translation height of the boundaries.
+ * Calculates half the height (y-axis half-span) of the boundaries.
+ *
+ * @param boundaries - The boundaries to measure
+ * @returns Half-height in world units, or undefined if y boundaries are not fully defined
+ *
+ * @remarks
+ * Useful for calculating radius or offset from center for y-axis.
+ * Equivalent to `translationHeightOf(boundaries) / 2`.
+ *
+ * @example
+ * ```typescript
+ * halfTranslationHeightOf({
+ *   min: { x: -100, y: -50 },
+ *   max: { x: 100, y: 50 }
+ * }); // 50
+ * ```
  *
  * @category Camera
  */
 export declare function halfTranslationHeightOf(boundaries: Boundaries | undefined): number | undefined;
 /**
- * @description Clamps the entire viewport within the boundaries
+ * Clamps camera position to ensure the entire viewport stays within boundaries.
+ * More restrictive than {@link clampPoint} as it considers viewport size and rotation.
+ *
+ * @param point - Proposed camera position in world coordinates
+ * @param viewPortWidth - Width of the viewport in CSS pixels
+ * @param viewPortHeight - Height of the viewport in CSS pixels
+ * @param boundaries - Optional boundary constraints in world space
+ * @param cameraZoomLevel - Current camera zoom level
+ * @param cameraRotation - Current camera rotation in radians
+ * @returns Adjusted camera position that keeps entire viewport within boundaries
+ *
+ * @remarks
+ * This function ensures no part of the viewport extends outside the boundaries.
+ * It accounts for:
+ * - Viewport dimensions (width/height)
+ * - Camera rotation (viewport corners rotate around camera center)
+ * - Zoom level (affects world-space size of viewport)
+ *
+ * The algorithm:
+ * 1. Calculates all four viewport corners in world space
+ * 2. Clamps each corner to boundaries
+ * 3. Finds the maximum displacement needed across all corners
+ * 4. Adjusts camera position by that displacement
+ *
+ * Use this for "edge-stop" behavior where viewport cannot scroll past boundaries.
+ * For "center-stop" behavior, use {@link clampPoint} instead.
+ *
+ * @example
+ * ```typescript
+ * const bounds: Boundaries = {
+ *   min: { x: 0, y: 0 },
+ *   max: { x: 1000, y: 1000 }
+ * };
+ *
+ * // Camera at center of bounds, viewport extends outside
+ * const adjusted = clampPointEntireViewPort(
+ *   { x: 100, y: 100 },  // camera position
+ *   800, 600,             // viewport size
+ *   bounds,
+ *   1.0,                  // zoom
+ *   0                     // rotation
+ * );
+ * // Returns position that prevents viewport from exceeding bounds
+ * ```
  *
  * @category Camera
+ * @see {@link clampPoint} for clamping camera center only
  */
 export declare function clampPointEntireViewPort(point: Point, viewPortWidth: number, viewPortHeight: number, boundaries: Boundaries | undefined, cameraZoomLevel: number, cameraRotation: number): Point;