@ue-too/board 0.5.1

package/camera/interface.d.ts

@@ -0,0 +1,59 @@
+import { Point } from "@ue-too/math";
+import { UnSubscribe } from "./update-publisher";
+import { RotationLimits } from "./utils/rotation";
+import { ZoomLevelLimits } from "./utils/zoom";
+import { Boundaries } from "./utils/position";
+import { CameraEventMap, CameraState } from "./update-publisher";
+import { SubscriptionOptions } from "../utils/observable";
+/**
+ * @description The interface for the observable board camera.
+ *
+ * @category Camera
+ */
+export interface ObservableBoardCamera extends BoardCamera {
+    on<K extends keyof CameraEventMap>(eventName: K, callback: (event: CameraEventMap[K], cameraState: CameraState) => void, options?: SubscriptionOptions): UnSubscribe;
+}
+/**
+ * @description The interface for the board camera.
+ *
+ * @category Camera
+ */
+export interface BoardCamera {
+    position: Point;
+    rotation: number;
+    zoomLevel: number;
+    viewPortWidth: number;
+    viewPortHeight: number;
+    boundaries?: Boundaries;
+    zoomBoundaries?: ZoomLevelLimits;
+    rotationBoundaries?: RotationLimits;
+    setPosition(destination: Point): boolean;
+    setZoomLevel(zoomLevel: number): boolean;
+    setRotation(rotation: number): boolean;
+    setMinZoomLevel(minZoomLevel: number): void;
+    setMaxZoomLevel(maxZoomLevel: number): void;
+    setHorizontalBoundaries(min: number, max: number): void;
+    setVerticalBoundaries(min: number, max: number): void;
+    getCameraOriginInWindow(centerInWindow: Point): Point;
+    convertFromViewPort2WorldSpace(point: Point): Point;
+    convertFromWorld2ViewPort(point: Point): Point;
+    getTRS(devicePixelRatio: number, alignCoordinateSystem: boolean): {
+        scale: {
+            x: number;
+            y: number;
+        };
+        rotation: number;
+        translation: {
+            x: number;
+            y: number;
+        };
+    };
+    getTransform(devicePixelRatio: number, alignCoordinateSystem: boolean): {
+        a: number;
+        b: number;
+        c: number;
+        d: number;
+        e: number;
+        f: number;
+    };
+}

package/camera/update-publisher.d.ts

@@ -0,0 +1,172 @@
+import { Point } from "@ue-too/math";
+import { SubscriptionOptions } from "../utils/observable";
+/**
+ * @description The payload for the pan event.
+ *
+ * @category Camera
+ */
+export type CameraPanEventPayload = {
+    diff: Point;
+};
+/**
+ * @description The payload for the zoom event.
+ *
+ * @category Camera
+ */
+export type CameraZoomEventPayload = {
+    deltaZoomAmount: number;
+};
+/**
+ * @description The payload for the rotate event.
+ *
+ * @category Camera
+ */
+export type CameraRotateEventPayload = {
+    deltaRotation: number;
+};
+/**
+ * @description The mapping of the camera events.
+ * This is primarily used for type inference.
+ *
+ * @category Camera
+ */
+export type CameraEventMap = {
+    "pan": CameraPanEventPayload;
+    "zoom": CameraZoomEventPayload;
+    "rotate": CameraRotateEventPayload;
+    "all": AllCameraEventPayload;
+};
+/**
+ * @description The type of the camera rotate event.
+ * The type is for discriminating the event type when the all event is triggered.
+ *
+ * @category Camera
+ */
+export type CameraRotateEvent = {
+    type: "rotate";
+} & CameraRotateEventPayload;
+/**
+ * @description The type of the camera pan event.
+ * The type is for discriminating the event type when the all event is triggered.
+ *
+ * @category Camera
+ */
+export type CameraPanEvent = {
+    type: "pan";
+} & CameraPanEventPayload;
+/**
+ * @description The type of the camera zoom event.
+ * The type is for discriminating the event type when the all event is triggered.
+ *
+ * @category Camera
+ */
+export type CameraZoomEvent = {
+    type: "zoom";
+} & CameraZoomEventPayload;
+/**
+ * @description The type of the camera state.
+ *
+ * @category Camera
+ */
+export type CameraState = {
+    position: Point;
+    zoomLevel: number;
+    rotation: number;
+};
+/**
+ * @description The payload type of the "all" camera event payload.
+ *
+ * @category Camera
+ */
+export type AllCameraEventPayload = CameraRotateEvent | CameraPanEvent | CameraZoomEvent;
+/**
+ * @description The callback function type for the camera event.
+ *
+ * @category Camera
+ */
+export type Callback<K extends keyof CameraEventMap> = (event: CameraEventMap[K], cameraState: CameraState) => void;
+/**
+ * @description The callback function type for the "all" camera event.
+ *
+ * @category Camera
+ */
+export type ConslidateCallback = (payload: AllCameraEventPayload, cameraState: CameraState) => void;
+/**
+ * @description The type of the unsubscribe function.
+ *
+ * @category Camera
+ */
+export type UnSubscribe = () => void;
+/**
+ * @description The observer type for the pan event.
+ *
+ * @category Camera
+ */
+export type PanObserver = Callback<"pan">;
+/**
+ * @description The observer type for the zoom event.
+ *
+ * @category Camera
+ */
+export type ZoomObserver = Callback<"zoom">;
+/**
+ * @description The observer type for the rotate event.
+ *
+ * @category Camera
+ */
+export type RotateObserver = Callback<"rotate">;
+/**
+ * @description The observer type for the "all" camera event.
+ *
+ * @category Camera
+ */
+export type AllObserver = Callback<"all">;
+/**
+ * @description The camera update publisher.
+ *
+ * @category Camera
+ */
+export declare class CameraUpdatePublisher {
+    private pan;
+    private zoom;
+    private rotate;
+    private all;
+    constructor();
+    /**
+     * @description Notify the pan event.
+     * Will also notify the "all" event.
+     *
+     * @category Camera
+     */
+    notifyPan(event: CameraEventMap["pan"], cameraState: CameraState): void;
+    /**
+     * @description Notify the zoom event.
+     * Will also notify the "all" event.
+     *
+     * @category Camera
+     */
+    notifyZoom(event: CameraEventMap["zoom"], cameraState: CameraState): void;
+    /**
+     * @description Notify the rotate event.
+     * Will also notify the "all" event.
+     *
+     * @category Camera
+     */
+    notifyRotate(event: CameraEventMap["rotate"], cameraState: CameraState): void;
+    /**
+     * @description Subscribe to the camera event.
+     * You can also pass in the abort controller signal within the options to cancel the subscription. Like this:
+     * ```ts
+     * const controller = new AbortController();
+     * const unSubscribe = on("pan", (event, cameraState)=>{}, {signal: controller.signal});
+     *
+     * // later in other place where you want to unsubscribe
+     * controller.abort();
+     *
+     * ```
+     * This means you can cancel multiple subscriptions by aborting the same controller. Just like regular event listeners.
+     *
+     * @category Camera
+     */
+    on<K extends keyof CameraEventMap>(eventName: K, callback: (event: CameraEventMap[K], cameraState: CameraState) => void, options?: SubscriptionOptions): UnSubscribe;
+}

package/camera/utils/coordinate-conversion.d.ts

@@ -0,0 +1,75 @@
+import { Point } from "@ue-too/math";
+import { TransformationMatrix } from "./matrix";
+/**
+ * @description Finds the world space coordinate of the interest point if the camera is at target position.
+ * The target position is the "would be" position of the camera in world space.
+ * The interest point is the point in view port space where the "bottom left" corner is the origin.
+ *
+ * @category Camera
+ */
+export declare function convert2WorldSpaceWRT(targetPosition: Point, interestPoint: Point, viewPortWidth: number, viewPortHeight: number, cameraZoomLevel: number, cameraRotation: number): Point;
+/**
+ * @description Converts the point to world space.
+ * The point is in the viewport space where the "bottom left" corner is the origin.
+ * Camera position is the position of the camera in world space.
+ *
+ * @category Camera
+ */
+export declare function convert2WorldSpace(point: Point, viewPortWidth: number, viewPortHeight: number, cameraPosition: Point, cameraZoomLevel: number, cameraRotation: number): Point;
+/**
+ * @description Converts the point to world space.
+ * The point is in the viewport space where the origin is at the center of the viewport.
+ * Camera position is the position of the camera in world space.
+ *
+ * @category Camera
+ */
+export declare function convert2WorldSpaceAnchorAtCenter(point: Point, cameraPosition: Point, cameraZoomLevel: number, cameraRotation: number): Point;
+/**
+ * @description Converts a point in "stage/context/world" space to view port space.
+ * The origin of the viewport is at the center of the viewport.
+ * The point is in world space.
+ * The camera position is the position of the camera in world space.
+ *
+ * @category Camera
+ */
+export declare function convert2ViewPortSpaceAnchorAtCenter(point: Point, cameraPosition: Point, cameraZoomLevel: number, cameraRotation: number): Point;
+/**
+ * @description Converts a point in "stage/context/world" space to view port space.
+ * The origin of the view port is at the bottom left corner.
+ * The point is in world space.
+ * The camera position is the position of the camera in world space.
+ *
+ * @category Camera
+ */
+export declare function invertFromWorldSpace(point: Point, viewPortWidth: number, viewPortHeight: number, cameraPosition: Point, cameraZoomLevel: number, cameraRotation: number): Point;
+/**
+ * @description Checks if a point is in the view port.
+ * The point is in world space.
+ * The camera position is the position of the camera in world space.
+ *
+ * @category Camera
+ */
+export declare function pointIsInViewPort(point: Point, viewPortWidth: number, viewPortHeight: number, cameraPosition: Point, cameraZoomLevel: number, cameraRotation: number): boolean;
+/**
+ * @description Converts a delta in view port space to world space.
+ * The delta is in view port space.
+ *
+ * @category Camera
+ */
+export declare function convertDeltaInViewPortToWorldSpace(delta: Point, cameraZoomLevel: number, cameraRotation: number): Point;
+/**
+ * @description Converts a delta in world space to view port space.
+ * The delta is in world space.
+ *
+ * @category Camera
+ */
+export declare function convertDeltaInWorldToViewPortSpace(delta: Point, cameraZoomLevel: number, cameraRotation: number): Point;
+/**
+ * @description Calculates the camera position to get a point in "stage/context/world" space to be at a certain point in view port space.
+ * This is useful to coordinate camera pan and zoom at the same time.
+ *
+ * @category Camera
+ */
+export declare function cameraPositionToGet(pointInWorld: Point, toPointInViewPort: Point, cameraZoomLevel: number, cameraRotation: number): Point;
+export declare function transformationMatrixFromCamera(cameraPosition: Point, cameraZoomLevel: number, cameraRotation: number): TransformationMatrix;
+export declare function convert2WorldSpaceWithTransformationMatrix(point: Point, transformationMatrix: TransformationMatrix): Point;

package/camera/utils/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./coordinate-conversion";
+export * from "./matrix";
+export * from "./position";
+export * from "./rotation";
+export * from "./zoom";

package/camera/utils/matrix.d.ts

@@ -0,0 +1,114 @@
+/**
+ * @description The transform matrix for the camera.
+ * It's in the format like this:
+ * ```
+ * | a    c    e |
+ * | b    d    f |
+ * | 0    0    1 |
+ * ```
+ *
+ * @category Camera
+ */
+export type TransformationMatrix = {
+    a: number;
+    b: number;
+    c: number;
+    d: number;
+    e: number;
+    f: number;
+};
+/**
+ * Decomposes a camera transformation matrix back to camera parameters
+ *
+ * Transformation order:
+ * 1. Scale by device pixel ratio
+ * 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
+ */
+export declare function decomposeCameraMatrix(transformMatrix: TransformationMatrix, devicePixelRatio: number, canvasWidth: number, canvasHeight: number): {
+    position: {
+        x: number;
+        y: number;
+    };
+    zoom: number;
+    rotation: number;
+};
+export declare function createCameraMatrix(cameraPos: {
+    x: number;
+    y: number;
+}, zoom: number, rotation: number, devicePixelRatio: number, canvasWidth: number, canvasHeight: number): {
+    a: number;
+    b: number;
+    c: number;
+    d: number;
+    e: number;
+    f: number;
+};
+export declare function multiplyMatrix(m1: TransformationMatrix, m2: TransformationMatrix): {
+    a: number;
+    b: number;
+    c: number;
+    d: number;
+    e: number;
+    f: number;
+};
+/**
+ * Decomposes a 2D transformation matrix into Translation, Rotation, and Scale (TRS)
+ *
+ * @param matrix - The transformation matrix to decompose
+ * @returns Object containing translation, rotation (in radians), and scale components
+ *
+ * @category Matrix
+ */
+export declare function decomposeTRS(matrix: TransformationMatrix): {
+    translation: {
+        x: number;
+        y: number;
+    };
+    rotation: number;
+    scale: {
+        x: number;
+        y: number;
+    };
+};
+/**
+ * Creates a transformation matrix from TRS components
+ *
+ * @param translation - Translation vector
+ * @param rotation - Rotation in radians
+ * @param scale - Scale vector
+ * @returns Transformation matrix
+ *
+ * @category Matrix
+ */
+export declare function createTRSMatrix(translation: {
+    x: number;
+    y: number;
+}, rotation: number, scale: {
+    x: number;
+    y: number;
+}): TransformationMatrix;
+/**
+ * Decomposes a matrix using SVD (Singular Value Decomposition) approach
+ * This is an alternative method that can handle more complex transformations
+ *
+ * @param matrix - The transformation matrix to decompose
+ * @returns Object containing translation, rotation, and scale components
+ *
+ * @category Matrix
+ */
+export declare function decomposeTRSSVD(matrix: TransformationMatrix): {
+    translation: {
+        x: number;
+        y: number;
+    };
+    rotation: number;
+    scale: {
+        x: number;
+        y: number;
+    };
+};

package/camera/utils/position.d.ts

@@ -0,0 +1,71 @@
+import { Point } from "@ue-too/math";
+/**
+ * @description The boundaries of a camera.
+ * The x and y are in world space.
+ *
+ * @category Camera
+ */
+export type Boundaries = {
+    min?: {
+        x?: number;
+        y?: number;
+    };
+    max?: {
+        x?: number;
+        y?: number;
+    };
+};
+/**
+ * @description Checks if a point is within the boundaries.
+ *
+ * @category Camera
+ */
+export declare function withinBoundaries(point: Point, boundaries: Boundaries | undefined): boolean;
+/**
+ * @description Checks if the boundaries are valid.
+ *
+ * @category Camera
+ */
+export declare function isValidBoundaries(boundaries: Boundaries | undefined): boolean;
+/**
+ * @description Checks if the boundaries are fully defined.
+ *
+ * @category Camera
+ */
+export declare function boundariesFullyDefined(boundaries: Boundaries | undefined): boolean;
+/**
+ * @description Clamps a point to the boundaries.
+ *
+ * @category Camera
+ */
+export declare function clampPoint(point: Point, boundaries: Boundaries | undefined): Point;
+/**
+ * @description Gets the translation width of the boundaries.
+ *
+ * @category Camera
+ */
+export declare function translationWidthOf(boundaries: Boundaries | undefined): number | undefined;
+/**
+ * @description Gets the half translation width of the boundaries.
+ *
+ * @category Camera
+ */
+export declare function halfTranslationWidthOf(boundaries: Boundaries): number | undefined;
+/**
+ * @description Gets the translation height of the boundaries.
+ *
+ * @category Camera
+ */
+export declare function translationHeightOf(boundaries: Boundaries | undefined): number | undefined;
+/**
+ * @description Gets the half translation height of the boundaries.
+ *
+ * @category Camera
+ */
+export declare function halfTranslationHeightOf(boundaries: Boundaries): number | undefined;
+/**
+ * @description Clamps the entire viewport within the boundaries
+ *
+ * @category Camera
+ */
+export declare function clampPointEntireViewPort(point: Point, viewPortWidth: number, viewPortHeight: number, boundaries: Boundaries | undefined, cameraZoomLevel: number, cameraRotation: number): Point;

package/camera/utils/rotation.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @description The limits of the rotation.
+ *
+ * @category Camera
+ */
+export type RotationLimits = {
+    start: number;
+    end: number;
+    ccw: boolean;
+    startAsTieBreaker: boolean;
+};
+/**
+ * @description The boundary of the rotation. (experimental)
+ *
+ * @category Camera
+ */
+export type RotationBoundary = {
+    start: number;
+    end: number;
+    positiveDirection: boolean;
+    startAsTieBreaker: boolean;
+};
+/**
+ * @description Clamps the rotation within the limits.
+ *
+ * @category Camera
+ */
+export declare function clampRotation(rotation: number, rotationLimits?: RotationLimits): number;
+/**
+ * @description Checks if the rotation is within the limits.
+ *
+ * @category Camera
+ */
+export declare function rotationWithinLimits(rotation: number, rotationLimits?: RotationLimits): boolean;
+/**
+ * @description Checks if the rotation is within the boundary. (experimental)
+ *
+ * @category Camera
+ */
+export declare function rotationWithinBoundary(rotation: number, rotationBoundary: RotationBoundary): boolean;
+/**
+ * @description Normalizes the angle to be between 0 and 2π.
+ *
+ * @category Camera
+ */
+export declare function normalizeAngleZero2TwoPI(angle: number): number;
+/**
+ * @description Gets the smaller angle span between two angles. (in radians)
+ *
+ * @category Camera
+ */
+export declare function angleSpan(from: number, to: number): number;
+/**
+ * @description Converts degrees to radians.
+ *
+ * @category Camera
+ */
+export declare function deg2rad(deg: number): number;
+/**
+ * @description Converts radians to degrees.
+ *
+ * @category Camera
+ */
+export declare function rad2deg(rad: number): number;

package/camera/utils/zoom.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @description The limits of the zoom level.
+ *
+ * @category Camera
+ */
+export type ZoomLevelLimits = {
+    min?: number;
+    max?: number;
+};
+/**
+ * @description Checks if the zoom level limits are valid.
+ */
+export declare function isValidZoomLevelLimits(zoomLevelLimits: ZoomLevelLimits | undefined): boolean;
+/**
+ * @description Clamps the zoom level within the limits.
+ *
+ * @category Camera
+ */
+export declare function clampZoomLevel(zoomLevel: number, zoomLevelLimits?: ZoomLevelLimits): number;
+/**
+ * @description Checks if the zoom level is within the limits.
+ *
+ * @category Camera
+ */
+export declare function zoomLevelWithinLimits(zoomLevel: number, zoomLevelLimits?: ZoomLevelLimits): boolean;

package/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./boardify";
+export * from "./camera";
+export * from "./input-interpretation";
+export * from "./utils";
+export { default as Board } from "./boardify";