@kritzel/engine 0.4.31

package/dist/types/classes/objects/path.class.d.ts

@@ -0,0 +1,220 @@
+import { KritzelBaseObject } from './base-object.class';
+import { KritzelPolygon } from '../../interfaces/polygon.interface';
+import { KritzelPoint } from '../../interfaces/point.interface';
+import { KritzelCore } from '../core/core.class';
+import { ThemeAwareColor } from '../../constants/color-palette.constants';
+import { KritzelObjectExportContext, KritzelObjectExportFormat } from '../../interfaces/object-export.interface';
+/**
+ * Configuration options for creating a KritzelPath instance.
+ */
+export interface KritzelPathConfig {
+    points?: number[][];
+    translateX?: number;
+    translateY?: number;
+    /** Rotation in degrees at initialization time. */
+    rotation?: number;
+    scale?: number;
+    stroke?: ThemeAwareColor;
+    strokeWidth?: number;
+    fill?: ThemeAwareColor;
+    opacity?: number;
+    lineSlack?: number;
+}
+export declare class KritzelPath extends KritzelBaseObject<SVGElement> {
+    __class__: string;
+    points: number[][];
+    d: string;
+    stroke: ThemeAwareColor;
+    strokeWidth: number;
+    lineSlack: number;
+    fill: ThemeAwareColor;
+    x: number;
+    y: number;
+    height: number;
+    width: number;
+    scale: number;
+    options: KritzelPathConfig | undefined;
+    isVisible: boolean;
+    isDebugInfoVisible: boolean;
+    isCompleted: boolean;
+    private _adjustedPoints;
+    /**
+     * Gets the SVG viewBox string for local (object-relative) rendering.
+     *
+     * The path's `d` string is generated in local coordinates (offset so the
+     * object's top-left origin is at 0,0), so the viewBox always starts at 0,0.
+     * Keeping the SVG's internal coordinates small — independent of the object's
+     * world position — avoids float32 precision loss in the browser's SVG
+     * rasterizer (Skia), which otherwise fails to paint paths whose absolute
+     * world coordinates exceed ~2^24 (e.g. far from the origin at extreme zoom).
+     * @returns The viewBox attribute value in the format "0 0 width height"
+     */
+    get viewBox(): string;
+    /**
+     * Creates a new KritzelPath instance.
+     * @param config - Optional configuration object for the path
+     * @param config.points - Array of [x, y] coordinate pairs defining the path
+     * @param config.translateX - Horizontal translation offset (default: 0)
+     * @param config.translateY - Vertical translation offset (default: 0)
+     * @param config.scale - Scale factor for the path (default: 1)
+     * @param config.strokeWidth - Width of the stroke in pixels (default: 8)
+     * @param config.fill - Theme-aware fill color with light and dark variants
+     * @param config.lineSlack - Additional padding for bounding box calculations (default: 0.5)
+     */
+    constructor(config?: KritzelPathConfig);
+    /**
+     * Factory method to create a new KritzelPath instance with a core reference.
+     * This is the preferred way to create paths that will be managed by the canvas.
+     * @param core - The KritzelCore instance that will manage this path
+     * @param options - Optional configuration options for the path
+     * @returns A new KritzelPath instance configured with the provided options
+     */
+    static create(core: KritzelCore, options?: KritzelPathConfig): KritzelPath;
+    /**
+     * Creates a deep copy of this path object.
+     * The points array is cloned to ensure the copy is independent.
+     * @returns A new KritzelPath instance with copied properties
+     */
+    copy(): KritzelPath;
+    /**
+     * Restores the path from a serialized object, then regenerates the SVG `d`
+     * string from the restored points.
+     *
+     * Regeneration is required because the `d` string is now emitted in local
+     * (object-relative) coordinates paired with a "0 0 width height" viewBox.
+     * Older persisted paths stored `d` in absolute world coordinates, which
+     * would be inconsistent with the local-coordinate viewBox and fail to
+     * rasterize far from the origin at extreme zoom. Recomputing `d` here makes
+     * both freshly created and previously persisted paths render identically.
+     * @param object - The serialized path data to restore from
+     * @returns This instance cast to type T
+     */
+    deserialize<T>(object: any): T;
+    /**
+     * Resizes the path to fit within the specified dimensions.
+     * Scales all points proportionally and updates the SVG path.
+     * @param x - New X position for the path, or null to keep current
+     * @param y - New Y position for the path, or null to keep current
+     * @param width - New width for the path (must be > 1)
+     * @param height - New height for the path (must be > 1)
+     */
+    resize(x: number | null, y: number | null, width: number, height: number): void;
+    /**
+     * Rotates the path by the specified angle.
+     * Invalidates cached adjusted points to force recalculation.
+     * @param value - Rotation angle in radians
+     */
+    rotate(value: number): void;
+    /**
+     * Moves the path by calculating the delta between start and end positions.
+     * The delta is adjusted for the current viewport scale.
+     * @param startX - Starting X coordinate in screen space
+     * @param startY - Starting Y coordinate in screen space
+     * @param endX - Ending X coordinate in screen space
+     * @param endY - Ending Y coordinate in screen space
+     */
+    move(startX: number, startY: number, endX: number, endY: number): void;
+    /**
+     * Tests whether a point intersects with the path's stroke.
+     * Uses distance-to-line-segment calculations for accurate hit detection.
+     * @param x - X coordinate to test in world space
+     * @param y - Y coordinate to test in world space
+     * @returns True if the point is within the stroke width of the path
+     */
+    hitTest(x: number, y: number): boolean;
+    /**
+     * Tests whether a polygon intersects with the path.
+     * Checks for point containment, edge intersections, and proximity to stroke.
+     * @param polygon - The polygon to test against, defined by its corner points
+     * @returns True if any part of the polygon overlaps with the path's stroke
+     */
+    hitTestPolygon(polygon: KritzelPolygon): boolean;
+    /**
+     * Updates the path's position to the specified coordinates.
+     * Invalidates cached adjusted points and triggers a store update.
+     * @param x - New X position in world space
+     * @param y - New Y position in world space
+     */
+    updatePosition(x: number, y: number): void;
+    /**
+     * Lifecycle hook called after properties have been updated.
+     * Regenerates the SVG path and bounding box when strokeWidth changes.
+     * @param changedProperties - Array of property names that were modified
+     */
+    onAfterUpdate(changedProperties: string[]): void;
+    /**
+     * Computes the world-space coordinates of all path points.
+     * Applies rotation around the path's center and adjusts for translation and scale.
+     * Results are cached in _adjustedPoints for performance.
+     * @returns Array of [x, y] coordinate pairs in world space
+     */
+    private computeAdjustedPoints;
+    /**
+     * Calculates the shortest distance from a point to a line segment.
+     * Uses projection to find the closest point on the segment.
+     * @param x - X coordinate of the test point
+     * @param y - Y coordinate of the test point
+     * @param x1 - X coordinate of the line segment start
+     * @param y1 - Y coordinate of the line segment start
+     * @param x2 - X coordinate of the line segment end
+     * @param y2 - Y coordinate of the line segment end
+     * @returns The shortest distance from the point to the line segment
+     */
+    private pointToLineSegmentDistance;
+    /**
+     * Updates width, height, x, y, translateX, and translateY based on current points.
+     * Uses the unrotated local points and stroke width for base dimensions.
+     * Called during initial setup to establish the path's dimensions and position.
+     */
+    private updateDimensions;
+    /**
+     * Updates width, height, x, y based on current points and strokeWidth.
+     * Does NOT modify translateX/translateY (use updateDimensions for initial setup).
+     */
+    private updateBoundingBox;
+    /**
+     * Generates the SVG path data string from the current points.
+     * Uses perfect-freehand to create a smooth, pressure-sensitive stroke.
+     * @returns SVG path data string (d attribute value)
+     */
+    private generateSvgPath;
+    /**
+     * Converts raw input points into a smooth stroke outline using perfect-freehand.
+     * Applies pressure simulation and smoothing for a natural pen-like appearance.
+     * @param points - Array of [x, y] coordinate pairs representing the input path
+     * @param strokeWidth - The desired stroke width in pixels
+     * @returns Array of [x, y] coordinate pairs forming the stroke outline polygon
+     */
+    private getStrokeFromPoints;
+    /**
+     * Converts stroke outline points into an SVG path data string.
+     * Uses quadratic bezier curves for smooth rendering.
+     * Coordinates are emitted relative to (offsetX, offsetY) so the resulting
+     * path lives in the object's local coordinate space (paired with a
+     * "0 0 width height" viewBox). This keeps SVG-internal coordinates small
+     * regardless of the object's world position, avoiding float32 rasterizer
+     * precision failures far from the origin.
+     * @param points - Array of [x, y] coordinate pairs forming the stroke outline
+     * @param offsetX - X origin to subtract from every coordinate (default 0)
+     * @param offsetY - Y origin to subtract from every coordinate (default 0)
+     * @param closed - Whether to close the path with 'Z' command (default: true)
+     * @returns SVG path data string with M, Q, and T commands
+     */
+    private getSvgPathFromStroke;
+    /**
+     * Determines if the path appears too small on screen for detailed rendering.
+     * Used for level-of-detail optimizations.
+     * @returns True if the path's screen area is less than 500 square pixels
+     */
+    isLowRes(): boolean;
+    /**
+     * Finds the point where a line from outsidePoint to the path's center
+     * intersects the stroke edge. Used for arrow clipping at the actual stroke edge.
+     * Uses binary search refinement for accurate intersection detection.
+     * @param outsidePoint - A point outside the path to trace from
+     * @returns The intersection point on the stroke edge, or null if no intersection found
+     */
+    getClipPoint(outsidePoint: KritzelPoint): KritzelPoint | null;
+    getSupportedExportFormats(): KritzelObjectExportFormat[];
+    exportAs(format: KritzelObjectExportFormat, context: KritzelObjectExportContext): Promise<string | null>;
+}

package/dist/types/classes/objects/selection-box.class.d.ts

@@ -0,0 +1,19 @@
+import { KritzelCore } from '../core/core.class';
+import { KritzelBaseObject } from './base-object.class';
+/**
+ * Represents a visual selection box used for multi-object selection on the canvas.
+ * The selection box is rendered as a semi-transparent rectangle with a border,
+ * typically shown when the user drags to select multiple objects.
+ */
+export declare class KritzelSelectionBox extends KritzelBaseObject<HTMLElement> {
+    __class__: string;
+    /**
+     * Factory method to create a new KritzelSelectionBox instance with default styling.
+     * Initializes the selection box with a blue semi-transparent background and border,
+     * positioned at the highest z-index to ensure visibility above all other objects.
+     *
+     * @param core - The KritzelCore instance providing access to the store and workspace state.
+     * @returns A fully initialized KritzelSelectionBox instance with default dimensions of 0x0.
+     */
+    static create(core: KritzelCore): KritzelSelectionBox;
+}

package/dist/types/classes/objects/selection-group.class.d.ts

@@ -0,0 +1,267 @@
+import { KritzelCore } from '../core/core.class';
+import { KritzelBaseObject } from './base-object.class';
+import { ThemeAwareColor } from '../../constants/color-palette.constants';
+/**
+ * Configuration options for creating a KritzelSelectionGroup instance.
+ */
+export interface KritzelSelectionGroupConfig {
+    rotation?: number;
+}
+/**
+ * Represents a snapshot of an object's transform state at a specific point in time.
+ * Used to preserve initial values during transform operations (rotate, resize)
+ * to avoid compounding errors from incremental updates.
+ */
+interface UnchangedObjectSnapshot {
+    /** The unique identifier of the object */
+    id: string;
+    /** The x-translation position of the object */
+    translateX: number;
+    /** The y-translation position of the object */
+    translateY: number;
+    /** The rotation angle of the object in radians */
+    rotation: number;
+    /** The content width of the object (excluding padding) */
+    width: number;
+    /** The content height of the object (excluding padding) */
+    height: number;
+    /** The total width of the object (including padding) */
+    totalWidth: number;
+    /** The total height of the object (including padding) */
+    totalHeight: number;
+    /** The scale factor applied to the object */
+    scale: number;
+}
+/**
+ * Represents a selection group that manages multiple selected objects on the canvas.
+ * The selection group allows batch operations like move, resize, and rotate on multiple objects simultaneously.
+ * It maintains its own bounding box that encompasses all selected objects.
+ */
+export declare class KritzelSelectionGroup extends KritzelBaseObject<HTMLElement> {
+    __class__: string;
+    constructor(config?: KritzelSelectionGroupConfig);
+    private _objectIds;
+    private _cachedObjects;
+    private _cachedObjectIdsHash;
+    unchangedObjectSnapshots: Map<string, UnchangedObjectSnapshot>;
+    snapshotRotation: number;
+    snapshotWidth: number;
+    snapshotHeight: number;
+    snapshotTranslateX: number;
+    snapshotTranslateY: number;
+    clientId?: number;
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+    handleColor?: ThemeAwareColor;
+    handleStrokeColor?: ThemeAwareColor;
+    handleSize: number;
+    /** Timestamp of the last Yjs persist for children during a drag */
+    private _lastChildPersistTime;
+    /** Minimum interval (ms) between child Yjs persists during drag */
+    private static readonly CHILD_PERSIST_THROTTLE_MS;
+    /** Ignore tiny floating-point diffs when comparing refreshed bounds */
+    private static readonly DIMENSION_EPSILON;
+    /**
+     * Gets the array of object IDs contained in this selection group.
+     * @returns Array of string IDs for the selected objects
+     */
+    get objectIds(): string[];
+    /**
+     * Sets the array of object IDs contained in this selection group.
+     * Invalidates the cached objects array when changed.
+     * @param value - Array of string IDs to set as the selected objects
+     */
+    set objectIds(value: string[]);
+    /**
+     * Invalidate the cached objects array. Call this when objects might have changed
+     * externally (e.g., after undo/redo operations).
+     */
+    invalidateObjectsCache(): void;
+    /**
+     * Retrieves the actual object instances from the store by their IDs.
+     * Uses caching to avoid redundant lookups - only recomputes when objectIds changes.
+     * Preserves the original insertion order of objects.
+     * @returns Array of KritzelBaseObject instances corresponding to the stored IDs
+     */
+    get objects(): KritzelBaseObject<any>[];
+    private syncChildSelectionState;
+    private shouldSyncChildSelectionState;
+    /**
+     * Gets the number of objects in the selection group.
+     * @returns The count of selected objects
+     */
+    get length(): number;
+    /**
+     * Factory method to create a new KritzelSelectionGroup instance.
+     * Initializes the selection group with default properties and associates it with the core instance.
+     * Default styling uses values from the theme system (selection section).
+     * @param core - The KritzelCore instance to associate with this selection group
+     * @returns A new KritzelSelectionGroup instance configured with default settings
+     */
+    static create(core: KritzelCore, config?: {
+        rotation?: number;
+    }): KritzelSelectionGroup;
+    /**
+     * Adds multiple objects to the selection group.
+     * Only adds objects that are not already in the selection.
+     * Updates the group's rotation based on the number of selected objects:
+     * - Single object: inherits the object's rotation
+     * - Multiple objects: resets rotation to 0
+     * Refreshes bounding box dimensions after adding objects.
+     * @param objects - Array of KritzelBaseObject instances to add to the selection
+     */
+    addObjects(objects: KritzelBaseObject<any>[]): void;
+    /**
+     * Toggles an object's presence in the selection group.
+     * If the object is already selected, it will be removed.
+     * If the object is not selected, it will be added.
+     * Updates group rotation and refreshes bounding box dimensions after the change.
+     * @param object - The KritzelBaseObject instance to toggle in the selection
+     */
+    addOrRemove(object: KritzelBaseObject<any>): void;
+    /**
+     * Prepares the selection group and its children for a transform interaction (rotate/resize).
+     * Ensures snapshot state is aligned with the current visual state.
+     */
+    beginTransform(): void;
+    /**
+     * Sets the isSelected flag to false for all objects in the selection group.
+     * Used when clearing or changing the selection state.
+     *
+     * For KritzelGroup members, also clears the isSelected flag on all nested
+     * descendants. A descendant can retain a lingering isSelected from the marquee
+     * preview before it was resolved to its parent group during selection, which
+     * would otherwise leave that object selected after the group is deselected and
+     * cause the whole group to be re-selected on the next interaction.
+     */
+    deselectAllChildren(): void;
+    /**
+     * Updates the workspace ID for the selection group and all its contained objects.
+     * Used when moving objects between workspaces or updating workspace associations.
+     * @param workspaceId - The new workspace ID to assign to the group and its children
+     */
+    updateWorkspaceId(workspaceId: string): void;
+    /**
+     * Updates the z-index values for all objects in the selection group.
+     * Assigns sequential z-indices starting from the provided value.
+     * @param startZIndex - The starting z-index value; subsequent objects get startZIndex + 1, startZIndex + 2, etc.
+     */
+    updateZIndices(startZIndex: number): void;
+    /**
+     * Updates the absolute position of the selection group and all its contained objects.
+     * Maintains the relative positions of child objects within the group.
+     * Also updates the unchangedObjectSnapshots to reflect the new positions.
+     * @param x - The new x-coordinate for the selection group's top-left corner
+     * @param y - The new y-coordinate for the selection group's top-left corner
+     */
+    updatePosition(x: number, y: number): void;
+    /**
+     * Capture snapshots of current object states for undo/redo operations
+     * @param cachedObjects Optional pre-fetched objects array to avoid redundant getter calls
+     */
+    captureUnchangedSnapshots(cachedObjects?: KritzelBaseObject<any>[]): void;
+    /**
+     * Serializes the selection group to a plain object for persistence or transmission.
+     * Excludes internal references like _core, element refs, and cached data.
+     * Converts the unchangedObjectSnapshots Map to a plain object for JSON compatibility.
+     * @returns A serializable object representation of the selection group
+     */
+    serialize(): any;
+    /**
+     * Deserializes a plain object back into a KritzelSelectionGroup instance.
+     * Restores objectIds through the setter and reconstructs the unchangedObjectSnapshots Map.
+     * @template T - The return type for the deserialized object
+     * @param object - The serialized object containing the selection group data
+     * @returns The deserialized selection group instance cast to type T
+     */
+    deserialize<T>(object: any): T;
+    /**
+     * Persists the selection group's current state to the store.
+     * Only updates the selection group itself, not child objects.
+     * Child objects are updated during their respective move/resize/rotate operations
+     * to avoid redundant Yjs updates.
+     */
+    update(): void;
+    /**
+     * Moves the selection group and all its contained objects by calculating the delta from drag coordinates.
+     * Updates anchor points for any lines connected to the moved objects.
+     *
+     * Child objects are moved locally without writing to Yjs during the drag to avoid
+     * N+1 full serializations per frame, which can overwhelm the WebSocket server.
+     * Children must be persisted at drag end via {@link persistChildren}.
+     *
+     * @param startX - The starting x-coordinate of the drag operation (in screen space)
+     * @param startY - The starting y-coordinate of the drag operation (in screen space)
+     * @param endX - The ending x-coordinate of the drag operation (in screen space)
+     * @param endY - The ending y-coordinate of the drag operation (in screen space)
+     */
+    move(startX: number, startY: number, endX: number, endY: number): void;
+    /**
+     * Persists all child objects to Yjs in a single transaction.
+     * Must be called after a drag operation completes to sync the final
+     * positions of children that were only updated locally during the drag.
+     */
+    persistChildren(): void;
+    /**
+     * Returns true when the selection contains a line anchored to an object
+     * that is not part of this selection group.
+     */
+    hasExternalAnchoredLineConnections(cachedObjects?: KritzelBaseObject<any>[]): boolean;
+    /**
+     * Resizes the selection group and scales all contained objects proportionally.
+     * Uses snapshot values to avoid compounding errors during continuous drag operations.
+     * Handles rotation by transforming coordinates into and out of the group's local space.
+     * Updates anchor points for any lines connected to resized objects.
+     * @param x - The new x-coordinate for the selection group's position
+     * @param y - The new y-coordinate for the selection group's position
+     * @param width - The new width for the selection group
+     * @param height - The new height for the selection group
+     */
+    resize(x: number, y: number, width: number, height: number): void;
+    /**
+     * Rotates the selection group and all contained objects around the group's center.
+     * Objects rotate around the group center while also adjusting their individual rotations.
+     * Uses snapshot values to calculate incremental rotation from the initial state.
+     * @param value - The new rotation angle in radians for the selection group
+     */
+    rotate(value: number): void;
+    /**
+     * Creates a deep copy of the selection group including copies of all contained objects.
+     * Preserves z-index ordering by sorting children before copying.
+     * Copies maintain their relative positions within the new selection group.
+     * @returns A new KritzelSelectionGroup with copies of all contained objects
+     */
+    copy(): KritzelBaseObject<HTMLElement>;
+    /**
+     * Refreshes the selection group's bounding box dimensions based on contained objects.
+     * @param cachedObjects Optional pre-fetched objects array to avoid redundant getter calls
+     * @param skipPersist If true, only updates local state without persisting to Yjs (used during undo/redo)
+     */
+    refreshObjectDimensions(cachedObjects?: KritzelBaseObject<any>[], skipPersist?: boolean): boolean;
+    /**
+     * Calculates the horizontal offset from the group's center to an object's center using snapshot data.
+     * Used during rotation to maintain relative positioning of objects.
+     * @param snapshot - The snapshot containing the object's recorded position and dimensions
+     * @returns The x-axis offset from the group center to the object center
+     */
+    private getOffsetXToCenterFromSnapshot;
+    /**
+     * Calculates the vertical offset from the group's center to an object's center using snapshot data.
+     * Used during rotation to maintain relative positioning of objects.
+     * @param snapshot - The snapshot containing the object's recorded position and dimensions
+     * @returns The y-axis offset from the group center to the object center
+     */
+    private getOffsetYToCenterFromSnapshot;
+    /**
+     * Tests whether a point intersects with the selection group or any of its contained objects.
+     * For a single line object, delegates hit testing to the line's own hit test (more precise).
+     * For other cases, first checks the group's rotated polygon bounding box, then individual objects.
+     * @param x - The x-coordinate of the point to test (in world space)
+     * @param y - The y-coordinate of the point to test (in world space)
+     * @returns True if the point is inside the selection group or any contained object, false otherwise
+     */
+    hitTest(x: number, y: number): boolean;
+}
+export {};