@kritzel/engine 0.4.31

package/dist/types/classes/handlers/key.handler.d.ts

@@ -0,0 +1,44 @@
+import { KritzelBaseHandler } from './base.handler';
+import { KritzelCore } from '../core/core.class';
+import { KritzelShortcut } from '../../interfaces/shortcut.interface';
+/**
+ * Handles keyboard events and manages keyboard shortcuts for the Kritzel canvas.
+ * Provides functionality for tool switching, object manipulation,
+ * undo/redo, and navigation via keyboard input.
+ */
+export declare class KritzelKeyHandler extends KritzelBaseHandler {
+    /**
+     * Array of registered keyboard shortcuts with their associated actions.
+     * Each shortcut defines the key combination, display label, category, optional condition, and action to execute.
+     */
+    private shortcuts;
+    /**
+     * Creates a new instance of the key handler.
+     * @param core - The KritzelCore instance that provides access to the canvas state and operations.
+     */
+    constructor(core: KritzelCore);
+    /**
+     * Switches the active tool to the tool at the specified index in the tool registry.
+     * Deselects all objects and activates the new tool if found.
+     * @param index - The zero-based index of the tool to activate from the tool registry.
+     */
+    private switchToolByIndex;
+    /**
+     * Handles keydown events and executes matching keyboard shortcuts.
+     * Updates the Ctrl key state in the store and finds matching shortcuts based on
+     * the pressed key combination and any defined conditions.
+     * @param event - The keyboard event triggered by the user pressing a key.
+     */
+    handleKeyDown(event: KeyboardEvent): void;
+    /**
+     * Handles keyup events and updates the Ctrl key state.
+     * @param event - The keyboard event triggered by the user releasing a key.
+     */
+    handleKeyUp(event: KeyboardEvent): void;
+    /**
+     * Returns a list of all registered shortcuts suitable for display in a UI help dialog.
+     * Excludes the action and condition properties to provide only the display-relevant information.
+     * @returns An array of shortcut objects containing key, modifiers, label, and category.
+     */
+    getDisplayableShortcuts(): Omit<KritzelShortcut, 'action' | 'condition'>[];
+}

package/dist/types/classes/handlers/line-handle.handler.d.ts

@@ -0,0 +1,115 @@
+import { KritzelCore } from '../core/core.class';
+import { KritzelBaseHandler } from './base.handler';
+/** The type of line handle being manipulated: start point, end point, or center control point. */
+export type LineHandleType = 'start' | 'end' | 'center';
+/**
+ * Handler for manipulating line object handles (endpoints and control points).
+ * Manages dragging of line start/end points and curve control points,
+ * including snap-to-object functionality for creating anchored connections.
+ */
+export declare class KritzelLineHandleHandler extends KritzelBaseHandler {
+    initialMouseX: number;
+    initialMouseY: number;
+    initialStartX: number;
+    initialStartY: number;
+    initialEndX: number;
+    initialEndY: number;
+    initialControlX: number | undefined;
+    initialControlY: number | undefined;
+    initialTranslateX: number;
+    initialTranslateY: number;
+    hasMoved: boolean;
+    /** Current snap target during drag, if any */
+    private currentSnapTarget;
+    /**
+     * Creates a new instance of the line handle handler.
+     * @param core - The KritzelCore instance providing access to the drawing engine and state management.
+     */
+    constructor(core: KritzelCore);
+    /**
+     * Resets the handler's internal state to its initial values.
+     * Called after a drag operation completes to prepare for the next interaction.
+     * Clears all stored initial positions, movement flags, and snap candidates.
+     */
+    private reset;
+    /**
+     * Handles pointer down events to initiate line handle dragging.
+     * For mouse input, responds only to left clicks.
+     * For touch/pen input, responds only when there's exactly one active pointer.
+     * @param event - The pointer event containing position and input type information.
+     */
+    handlePointerDown(event: PointerEvent): void;
+    /**
+     * Initializes the drag operation for a line handle.
+     * Stores the initial mouse position and line state (endpoints, control point, translation)
+     * to enable delta calculations during movement. Also removes any existing anchor
+     * for the endpoint being dragged to allow repositioning.
+     * @param event - The pointer event that initiated the drag.
+     */
+    private startHandleDrag;
+    /**
+     * Handles pointer move events during a line handle drag operation.
+     * Updates the appropriate line property based on the handle type being dragged:
+     * - 'start': Updates the line's start point, checking for snap targets.
+     * - 'end': Updates the line's end point, checking for snap targets.
+     * - 'center': Updates the quadratic curve control point, with snap-to-straight behavior.
+     *
+     * Applies coordinate transformations to convert screen delta to the line's local coordinate system,
+     * accounting for viewport scale, object scale, and rotation.
+     *
+     * @param event - The pointer event containing the current cursor position.
+     */
+    handlePointerMove(event: PointerEvent): void;
+    /**
+     * Converts world coordinates to a line's local coordinate system.
+     * Accounts for the line's translation, scale, and rotation to transform
+     * absolute canvas positions into the line's internal coordinate space.
+     *
+     * @param line - The line object whose coordinate system to transform into.
+     * @param worldX - The X coordinate in world/canvas space.
+     * @param worldY - The Y coordinate in world/canvas space.
+     * @returns An object containing the transformed local X and Y coordinates.
+     */
+    private worldToLineLocal;
+    /**
+     * Converts a line's local coordinate system to world coordinates.
+     * Reverses the transformations applied by worldToLineLocal to convert
+     * the line's internal coordinates back to absolute canvas positions.
+     *
+     * @param line - The line object whose coordinate system to transform from.
+     * @param localX - The X coordinate in the line's local space.
+     * @param localY - The Y coordinate in the line's local space.
+     * @returns An object containing the transformed world X and Y coordinates.
+     */
+    private lineLocalToWorld;
+    /**
+     * Updates a line's endpoint positions and recalculates all dependent properties.
+     * Computes new bounding boxes for both the old and new line configurations,
+     * adjusts the line's position (x, y), dimensions (width, height), and translation
+     * to maintain visual consistency while moving endpoints.
+     *
+     * @param line - The line object to update.
+     * @param startX - The new X coordinate for the line's start point in local space.
+     * @param startY - The new Y coordinate for the line's start point in local space.
+     * @param endX - The new X coordinate for the line's end point in local space.
+     * @param endY - The new Y coordinate for the line's end point in local space.
+     */
+    private updateLineEndpoint;
+    /**
+     * Handles pointer up events to complete a line handle drag operation.
+     * If the line was moved and snapped to a target object, creates an anchor connection.
+     * Refreshes the selection group dimensions and triggers change events.
+     * Finally resets the handler state and triggers a rerender.
+     *
+     * @param _event - The pointer event (unused, but required by the handler interface).
+     */
+    handlePointerUp(_event: PointerEvent): void;
+    /**
+     * Retrieves the currently selected line object, if any.
+     * Returns the line only when exactly one object is selected and it is a KritzelLine instance.
+     *
+     * @returns The selected KritzelLine object, or null if no single line is selected.
+     */
+    private getSelectedLine;
+    private createIndicatorCandidate;
+}

package/dist/types/classes/handlers/move.handler.d.ts

@@ -0,0 +1,94 @@
+import { KritzelBaseHandler } from './base.handler';
+import { KritzelCore } from '../core/core.class';
+/**
+ * Handler class responsible for managing move/drag operations on selected objects.
+ * Handles pointer events for mouse, touch, and pen inputs to enable dragging
+ * of selected objects on the canvas. Also manages anchor disconnection when
+ * lines are dragged beyond a threshold distance.
+ */
+export declare class KritzelMoveHandler extends KritzelBaseHandler {
+    /** X coordinate where the drag started (updates during drag for incremental movement) */
+    dragStartX: number;
+    /** Y coordinate where the drag started (updates during drag for incremental movement) */
+    dragStartY: number;
+    /** Initial X coordinate when starting interaction (remains constant during drag) */
+    startX: number;
+    /** Initial Y coordinate when starting interaction (remains constant during drag) */
+    startY: number;
+    /** Current X coordinate during move operation */
+    endX: number;
+    /** Current Y coordinate during move operation */
+    endY: number;
+    /** Initial position when drag started (for calculating total accumulated distance) */
+    private initialDragX;
+    private initialDragY;
+    /** Set of line IDs that have been disconnected from anchors during this drag */
+    private disconnectedLineIds;
+    /** Flag indicating whether objects have been moved during the current drag operation */
+    hasMoved: boolean;
+    /** The pointer ID being tracked for the current drag operation (null if not dragging) */
+    private trackedPointerId;
+    /**
+     * Creates a new instance of KritzelMoveHandler.
+     * @param core - The KritzelCore instance providing access to store, engine, and other core services
+     */
+    constructor(core: KritzelCore);
+    /**
+     * Resets all internal state variables to their initial values.
+     * Called after a drag operation completes or is cancelled to prepare
+     * the handler for the next interaction.
+     * @returns void
+     */
+    private reset;
+    /**
+     * Cancels any pending drag operation without completing it.
+     * Sets the dragging state to false and resets internal state.
+     * Useful for aborting a drag when another interaction takes precedence.
+     * @returns void
+     */
+    cancelPendingDrag(): void;
+    /**
+     * Handles the pointer down event to initiate a drag operation.
+     * Validates that the event is appropriate for starting a drag (e.g., left mouse click,
+     * single touch, correct state) and initializes drag tracking variables.
+     * Supports mouse, touch, and pen input types.
+     * @param event - The PointerEvent from the browser containing pointer information
+     *                including clientX, clientY, pointerId, pointerType, and modifier keys
+     * @returns void
+     */
+    handlePointerDown(event: PointerEvent): void;
+    /**
+     * Handles pointer move events during a drag operation.
+     * Calculates movement delta, applies a movement threshold to filter micro-movements,
+     * checks for anchor disconnection on lines, and updates the position of selected objects.
+     * Supports mouse, touch, and pen input types.
+     * @param event - The PointerEvent from the browser containing current pointer position
+     *                and pointer identification (pointerId, pointerType, clientX, clientY)
+     * @returns void
+     */
+    handlePointerMove(event: PointerEvent): void;
+    /**
+     * Handles the pointer up event to complete a drag operation.
+     * Finalizes the move by updating the selection group, emitting change events
+     * if objects were moved, and resetting internal state for the next operation.
+     * Supports mouse, touch, and pen input types.
+     * @param event - The PointerEvent from the browser containing pointer identification
+     *                (pointerId, pointerType) to verify this is the tracked pointer
+     * @returns void
+     */
+    handlePointerUp(event: PointerEvent): void;
+    /**
+     * Checks if the total accumulated drag distance exceeds the anchor disconnect threshold.
+     * If so, disconnects all anchors from any KritzelLine objects in the selection group.
+     * This allows anchored lines to be freely moved after dragging beyond the threshold.
+     *
+     * Only disconnects anchors when the selection contains exclusively line objects.
+     * If the selection includes other object types (e.g., shapes that lines might be
+     * anchored to), no disconnection occurs to preserve intended relationships.
+     *
+     * @param currentX - The current X coordinate of the pointer in screen pixels
+     * @param currentY - The current Y coordinate of the pointer in screen pixels
+     * @returns void
+     */
+    private checkAndDisconnectAnchors;
+}

package/dist/types/classes/handlers/resize.handler.d.ts

@@ -0,0 +1,95 @@
+import { KritzelCore } from '../core/core.class';
+import { KritzelBaseHandler } from './base.handler';
+/**
+ * Handler class responsible for managing resize operations on selected objects.
+ * Supports mouse, touch, and pen input types, with rotation-aware resizing
+ * and optional aspect ratio locking via Shift key (mouse only).
+ */
+export declare class KritzelResizeHandler extends KritzelBaseHandler {
+    /** Initial mouse/pointer X coordinate when resize started */
+    initialMouseX: number;
+    /** Initial mouse/pointer Y coordinate when resize started */
+    initialMouseY: number;
+    /** Initial position and dimensions of the selection group before resize */
+    initialSize: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** New position and dimensions being calculated during resize */
+    newSize: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Flag indicating whether the user has moved past the resize threshold */
+    hasResized: boolean;
+    /**
+     * Creates a new KritzelResizeHandler instance.
+     * @param core - The KritzelCore instance providing access to store, engine, and other core functionalities
+     */
+    constructor(core: KritzelCore);
+    /**
+     * Resets all internal state variables to their default values.
+     * Called after a resize operation completes to prepare for the next resize.
+     * @private
+     */
+    private reset;
+    /**
+     * Rebase pointer and size baselines to the latest live selection bounds.
+     * This prevents drift when anchored lines to external objects expand/shrink
+     * the selection box while a resize gesture is in progress.
+     */
+    private rebaseResizeBaseline;
+    private shouldRebaseResizeBaseline;
+    /**
+     * Handles the pointer down event to initiate a resize operation.
+     * Captures the initial mouse position and selection group dimensions when
+     * the user clicks/touches a resize handle. Supports both mouse and touch/pen inputs.
+     *
+     * For mouse: Requires left click on an active resize handle.
+     * For touch/pen: Requires single finger touch on an active resize handle.
+     *
+     * @param event - The PointerEvent containing pointer type, position, and button information
+     */
+    handlePointerDown(event: PointerEvent): void;
+    /**
+     * Handles the pointer move event during an active resize operation.
+     * Calculates the new dimensions based on pointer movement, taking into account:
+     * - The rotation of the selection group (transforms screen delta to local space)
+     * - The current canvas scale/zoom level
+     * - The type of resize handle being dragged (TopLeft, TopRight, BottomLeft, BottomRight)
+     * - Aspect ratio locking when Shift key is pressed (mouse only)
+     *
+     * Uses a movement threshold to prevent accidental micro-resizes.
+     * The resize is applied symmetrically around the center point.
+     *
+     * @param event - The PointerEvent containing current pointer position and modifier keys
+     */
+    handlePointerMove(event: PointerEvent): void;
+    /**
+     * Constrains the new size to maintain the original aspect ratio.
+     * Uses the dominant scale factor (the axis with larger relative change)
+     * to determine the final size, ensuring natural resize behavior.
+     *
+     * If width changed more proportionally, height is adjusted to match the aspect ratio.
+     * If height changed more proportionally, width is adjusted to match the aspect ratio.
+     *
+     * @private
+     * @remarks Does nothing if initial width or height is zero to prevent division errors
+     */
+    private constrainToAspectRatio;
+    /**
+     * Handles the pointer up event to finalize a resize operation.
+     * If resizing occurred (movement exceeded threshold), updates the selection group
+     * and emits change events. Resets all internal state regardless of whether
+     * actual resizing took place.
+     *
+     * For touch/pen inputs, also clears any pending long touch timeout.
+     *
+     * @param event - The PointerEvent containing pointer type information
+     */
+    handlePointerUp(event: PointerEvent): void;
+}

package/dist/types/classes/handlers/rotation.handler.d.ts

@@ -0,0 +1,50 @@
+import { KritzelBaseHandler } from './base.handler';
+import { KritzelCore } from '../core/core.class';
+/**
+ * Handles rotation interactions for selected objects on the canvas.
+ * Supports both mouse and touch/pen input for rotating the selection group
+ * around its center point.
+ */
+export declare class KritzelRotationHandler extends KritzelBaseHandler {
+    /** The initial angle (in radians) between the cursor and the selection group center when rotation starts. */
+    initialRotation: number;
+    /** The current rotation angle (in radians) applied to the selection group. */
+    rotation: number;
+    /** The rotation value of the selection group before the current rotation operation began. */
+    initialSelectionGroupRotation: number;
+    /** The X coordinate of the rotation pivot (group center) captured when rotation starts, in world space. */
+    initialCenterX: number;
+    /** The Y coordinate of the rotation pivot (group center) captured when rotation starts, in world space. */
+    initialCenterY: number;
+    /**
+     * Creates an instance of KritzelRotationHandler.
+     * @param core - The KritzelCore instance that provides access to the store, engine, and other core functionalities.
+     */
+    constructor(core: KritzelCore);
+    /**
+     * Resets the rotation state to initial values.
+     * Called after a rotation operation is completed.
+     */
+    private reset;
+    /**
+     * Handles the pointer down event to initiate a rotation operation.
+     * Calculates the initial angle between the cursor position and the selection group center.
+     * Supports both mouse (left-click) and touch/pen input.
+     * @param event - The PointerEvent containing information about the pointer interaction.
+     */
+    handlePointerDown(event: PointerEvent): void;
+    /**
+     * Handles the pointer move event during an active rotation operation.
+     * Calculates the current rotation angle based on the cursor position relative
+     * to the selection group center and applies the rotation to the selection group.
+     * @param event - The PointerEvent containing the current pointer position.
+     */
+    handlePointerMove(event: PointerEvent): void;
+    /**
+     * Handles the pointer up event to finalize the rotation operation.
+     * Updates the selection group state, emits the objects change event,
+     * resets the rotation state, and marks objects as changed.
+     * @param event - The PointerEvent indicating the end of the pointer interaction.
+     */
+    handlePointerUp(event: PointerEvent): void;
+}

package/dist/types/classes/handlers/selection.handler.d.ts

@@ -0,0 +1,153 @@
+import { KritzelBaseHandler } from './base.handler';
+import { KritzelCore } from '../core/core.class';
+/**
+ * Handles object selection interactions on the canvas.
+ * Supports both click-to-select and drag-to-select (marquee) selection modes
+ * for mouse, touch, and pen input types. Also handles additive selection
+ * via shift/ctrl modifiers.
+ */
+export declare class KritzelSelectionHandler extends KritzelBaseHandler {
+    startX: number;
+    startY: number;
+    touchStartX: number;
+    touchStartY: number;
+    touchStartTimeout: any;
+    /**
+     * Tracks previously selected objects for efficient deselection.
+     * Uses a Set for O(1) lookup when determining which objects need to be deselected.
+     */
+    private _previouslySelectedObjects;
+    /**
+     * Indicates whether the current selection action is a single click (no drag).
+     * @returns `true` if a selection box exists with zero width and height
+     */
+    get isSelectionClick(): boolean;
+    /**
+     * Indicates whether the current selection action is a drag selection (marquee).
+     * @returns `true` if a selection box exists with non-zero width or height
+     */
+    get isSelectionDrag(): boolean;
+    /**
+     * Creates a new selection handler instance.
+     * @param core - The KritzelCore instance providing access to store, engine, and other core services
+     */
+    constructor(core: KritzelCore);
+    /**
+     * Handles the pointer down event to initiate selection.
+     * For mouse input, starts selection on left-click when no selection group exists or in additive mode.
+     * For touch/pen input, initiates selection after a brief delay (80ms) to distinguish from other gestures.
+     * @param event - The pointer event containing input type, coordinates, and modifier keys
+     */
+    handlePointerDown(event: PointerEvent): void;
+    /**
+     * Handles the pointer move event to update the selection box during drag selection.
+     * For mouse input, updates selection when actively selecting.
+     * For touch/pen input, updates selection and cancels long-touch timeout if movement exceeds threshold.
+     * @param event - The pointer event containing current pointer position and input type
+     */
+    handlePointerMove(event: PointerEvent): void;
+    /**
+     * Handles the pointer up event to complete the selection action.
+     * Determines whether the action was a click or drag selection and processes accordingly.
+     * Triggers object edit mode when a single object is selected without movement.
+     * Emits objects change event after selection completes.
+     * @param event - The pointer event containing input type, coordinates, and modifier keys
+     */
+    handlePointerUp(event: PointerEvent): void;
+    /**
+     * Removes the selection box from the canvas and resets selection state.
+     * Clears the selecting flag and removes the selection box object from the store.
+     */
+    private removeSelectionBox;
+    /**
+     * Initiates a mouse-based selection by creating a selection box at the click position.
+     * Calculates canvas coordinates accounting for offset, translation, and scale.
+     * In non-additive mode, clears any existing selection group.
+     * @param event - The mouse event containing click coordinates
+     * @param isAdditive - When `true`, preserves existing selection group for adding objects
+     */
+    private startMouseSelection;
+    /**
+     * Initiates a touch/pen-based selection by creating a selection box at the touch position.
+     * Uses the first active pointer from the pointers map to determine coordinates.
+     * In non-additive mode, clears any existing selection group.
+     * @param _event - The pointer event (unused, coordinates from active pointers)
+     * @param isAdditive - When `true`, preserves existing selection group for adding objects
+     */
+    private startTouchSelection;
+    /**
+     * Updates the selection box dimensions during mouse drag.
+     * Calculates the new width, height, and position based on current mouse position
+     * relative to the start position. Supports selection in any direction.
+     * @param event - The mouse event containing current cursor position
+     */
+    private updateMouseSelection;
+    /**
+     * Updates the selection box dimensions during touch/pen drag.
+     * Uses the first active pointer to calculate new dimensions.
+     * Supports selection in any direction by using absolute width/height
+     * and positioning at the minimum coordinates.
+     */
+    private updateTouchSelection;
+    /**
+     * Updates the selection state of objects intersecting with the selection box.
+     * Uses quadtree spatial indexing for efficient O(log n + k) candidate lookup.
+     * Performs polygon-based hit testing for accurate rotated selection support.
+     * Efficiently deselects only previously selected objects that no longer intersect.
+     */
+    private updateSelectedObjects;
+    /**
+     * Handles a single-click selection action.
+     * Finds the topmost object at the click position and adds it to the selection group.
+     * Supports additive selection mode via shift/ctrl modifier keys.
+     * @param event - The pointer event containing click coordinates and modifier keys
+     */
+    private handleSelectionClick;
+    /**
+     * Finds the topmost (highest z-order) object at the pointer position.
+     * Iterates through overlapping objects from top to bottom and performs hit testing.
+     * Excludes selection-related objects (selection box and selection group).
+     * @param event - The pointer event used to query overlapping DOM elements
+     * @returns The topmost object that passes hit testing, or `null` if none found
+     */
+    private getTopmostHitObject;
+    /**
+     * Clears the visual selection preview by deselecting all previously selected objects.
+     * Operates in O(k) time where k is the number of previously selected objects,
+     * rather than O(n) by iterating only tracked objects.
+     */
+    private clearSelectionPreview;
+    /**
+     * Adds a single object to the selection group.
+     * Resolves child objects to their parent groups before adding.
+     * In additive mode (shift), toggles object presence in existing group.
+     * In non-additive mode, creates a new selection group with the object.
+     * @param object - The object to add to selection (may be a child of a group)
+     * @param shiftKey - When `true`, adds to/removes from existing selection group
+     */
+    private addObjectToSelectionGroup;
+    /**
+     * Adds all currently selected objects to a selection group.
+     * Builds a parent group lookup map for efficient O(n) resolution of child objects.
+     * Deduplicates objects by ID to prevent duplicate entries from group resolution.
+     * In additive mode, adds to existing group; otherwise creates a new selection group.
+     * Captures unchanged snapshots and refreshes dimensions once at the end for O(n) performance.
+     * @param shiftKey - When `true`, adds objects to existing selection group
+     */
+    private addSelectedObjectsToSelectionGroup;
+    /**
+     * Removes objects that are descendants of any KritzelGroup also present in the list.
+     * Prevents an ancestor group and one of its descendants from coexisting in a selection,
+     * which would otherwise cause the descendant to be transformed twice (once via the
+     * ancestor group, and once directly).
+     * @param objects - The candidate objects for the selection.
+     * @returns A new array with descendants of selected groups removed.
+     */
+    private filterDescendantsOfSelectedGroups;
+    /**
+     * Mutates an existing selection group to remove any descendants of groups
+     * already present in it. See {@link filterDescendantsOfSelectedGroups}.
+     * @param selectionGroup - The selection group to clean up in place.
+     */
+    private removeDescendantsOfSelectedGroups;
+}