kritzel-react 0.1.30 → 0.1.32

package/dist/types/kritzel-stencil/src/classes/handlers/selection.handler.d.ts

@@ -0,0 +1,27 @@
+import { KritzelBaseHandler } from './base.handler';
+import { KritzelCore } from '../core/core.class';
+export declare class KritzelSelectionHandler extends KritzelBaseHandler {
+    startX: number;
+    startY: number;
+    touchStartX: number;
+    touchStartY: number;
+    touchStartTimeout: any;
+    private _previouslySelectedObjects;
+    get isSelectionClick(): boolean | null;
+    get isSelectionDrag(): boolean | null;
+    constructor(core: KritzelCore);
+    handlePointerDown(event: PointerEvent): void;
+    handlePointerMove(event: PointerEvent): void;
+    handlePointerUp(event: PointerEvent): void;
+    private removeSelectionBox;
+    private startMouseSelection;
+    private startTouchSelection;
+    private updateMouseSelection;
+    private updateTouchSelection;
+    private updateSelectedObjects;
+    private handleSelectionClick;
+    private getTopmostHitObject;
+    private clearSelectionPreview;
+    private addObjectToSelectionGroup;
+    private addSelectedObjectsToSelectionGroup;
+}

package/dist/types/kritzel-stencil/src/classes/managers/anchor.manager.d.ts

@@ -0,0 +1,180 @@
+import { AnchorIndexEntry, AnchorLinesRenderData, AnchorVisualization, LineAnchor, SnapCandidate, SnapIndicatorRenderData, SnapTarget } from '../../interfaces/anchor.interface';
+import { KritzelCore } from '../core/core.class';
+import { KritzelLine } from '../objects/line.class';
+import { KritzelBaseObject } from '../objects/base-object.class';
+type AnchorClipInfo = {
+    localX: number;
+    localY: number;
+    worldX: number;
+    worldY: number;
+    t?: number;
+};
+/**
+ * Manages anchor connections between line endpoints and other objects.
+ * Maintains a runtime index for efficient reverse lookups and handles
+ * snap detection during line endpoint dragging.
+ */
+export declare class KritzelAnchorManager {
+    private readonly _core;
+    /**
+     * Runtime index mapping objectId to the lines anchored to it.
+     * This is derived from the anchor properties on lines and rebuilt as needed.
+     */
+    private readonly _anchorIndex;
+    constructor(core: KritzelCore);
+    /**
+     * Sets an anchor from a line endpoint to a target object's center.
+     * Updates both the line's anchor property and the internal index.
+     */
+    setAnchor(lineId: string, endpoint: 'start' | 'end', targetObjectId: string): void;
+    /**
+     * Removes an anchor from a line endpoint.
+     * Updates both the line's anchor property and the internal index.
+     */
+    removeAnchor(lineId: string, endpoint: 'start' | 'end'): void;
+    /**
+     * Gets the anchor for a specific line endpoint.
+     */
+    getAnchor(lineId: string, endpoint: 'start' | 'end'): LineAnchor | null;
+    /**
+     * Gets all lines that have an endpoint anchored to the specified object.
+     */
+    getLinesAnchoredTo(objectId: string): AnchorIndexEntry[];
+    /**
+     * Updates all line endpoints that are anchored to the specified object.
+     * Should be called when an object moves.
+     */
+    updateAnchorsForObject(objectId: string): void;
+    /**
+     * Snaps a line endpoint to an object's center.
+     */
+    private snapEndpointToObject;
+    /**
+     * Converts world coordinates to a line's local coordinate system.
+     */
+    private worldToLineLocal;
+    /**
+     * Finds the nearest object that can be snapped to within the snap threshold.
+     * Returns null if no suitable snap target is found.
+     *
+     * @param worldX - X coordinate in world space
+     * @param worldY - Y coordinate in world space
+     * @param excludeLineId - ID of the line being edited (to exclude from snap targets)
+     * @param otherEndpointAnchorId - ID of object anchored to the other endpoint (to prevent same-object anchoring)
+     */
+    findSnapTarget(worldX: number, worldY: number, excludeLineId: string, otherEndpointAnchorId?: string): SnapTarget | null;
+    /**
+     * Sets the current snap candidate for visual feedback.
+     */
+    setSnapCandidate(candidate: SnapCandidate | null): void;
+    /**
+     * Gets the current snap candidate.
+     */
+    getSnapCandidate(): SnapCandidate | null;
+    /**
+     * Clears the snap candidate.
+     */
+    clearSnapCandidate(): void;
+    /**
+     * Gets render data for anchor lines visualization.
+     * Returns null if there's no selected line with anchors or if snap is in progress.
+     */
+    getAnchorLinesRenderData(): AnchorLinesRenderData | null;
+    /**
+     * Gets render data for snap indicator visualization.
+     * Returns null if there's no snap candidate.
+     */
+    getSnapIndicatorRenderData(): SnapIndicatorRenderData | null;
+    /**
+     * Handles cleanup when an object is deleted.
+     * Detaches all lines that were anchored to the deleted object.
+     */
+    handleObjectDeleted(objectId: string): void;
+    /**
+     * Handles cleanup when a line is deleted.
+     * Removes all anchor index entries for the line.
+     */
+    handleLineDeleted(lineId: string): void;
+    /**
+     * Rebuilds the anchor index from all lines in the object map.
+     * Should be called after loading/deserializing objects.
+     */
+    rebuildIndex(): void;
+    /**
+     * Adds an entry to the anchor index.
+     */
+    private addToIndex;
+    /**
+     * Removes an entry from the anchor index.
+     */
+    private removeFromIndex;
+    /**
+     * Gets a line by its ID.
+     */
+    private getLineById;
+    /**
+     * Gets an object by its ID.
+     */
+    private getObjectById;
+    findAnchorTarget(line: KritzelLine, endpoint: 'start' | 'end'): KritzelBaseObject<Element> | null;
+    /**
+     * Computes anchor visualization data for a line with anchors.
+     * Returns edge intersection points for rendering dashed lines from edge to center.
+     */
+    computeAnchorVisualization(line: KritzelLine, endpoint: 'start' | 'end'): AnchorVisualization | null;
+    /**
+     * Computes a clipped line path that stops at anchor edges instead of going to anchor centers.
+     * When arrows are present on anchored ends, the line is shortened so the arrow tip appears at the edge.
+     * Returns the SVG path 'd' attribute string, or the original path if no clipping is needed.
+     * @param line The line object
+     * @param offsetByViewBox If true, subtracts line.x and line.y from coordinates (for selection UI)
+     */
+    computeClippedLinePath(line: KritzelLine, offsetByViewBox?: boolean): string;
+    computeAnchorClipInfo(line: KritzelLine, endpoint: 'start' | 'end', targetObject: KritzelBaseObject<Element>): AnchorClipInfo | null;
+    private computeStraightClipInfo;
+    private computeCurvedClipInfo;
+    private findCurveExitPoint;
+    /**
+     * Finds the exit point for a curved line going to a Path object.
+     * Uses distance-to-stroke sampling instead of polygon containment.
+     */
+    private findCurveExitPointForPath;
+    private refineCurveExitParameterForPath;
+    private getPathAdjustedPoints;
+    private computePathAdjustedPoints;
+    private isPointInPathStroke;
+    private pointToSegmentDistance;
+    private refineCurveExitParameter;
+    private approximateParameterForWorldPoint;
+    private evaluateLineAtT;
+    private evaluateDerivativeSpeedAtT;
+    private extractQuadraticSegment;
+    private splitQuadraticSegment;
+    private lerpPoint;
+    private buildAnchorPath;
+    private buildWorldQuadraticPath;
+    private getPolygonPoints;
+    /**
+     * Gets the custom clip polygon for an object if it has one.
+     * Returns null for objects that should use the default rotatedPolygon.
+     */
+    private getClipPolygonForObject;
+    /**
+     * Gets the clip point for a Path object (stroke edge intersection).
+     * Returns null if the object is not a Path or no intersection found.
+     */
+    private getPathClipPoint;
+    /**
+     * Converts local line coordinates to world coordinates.
+     */
+    private lineLocalToWorld;
+    /**
+     * Converts world coordinates to line's local SVG coordinates.
+     */
+    private lineWorldToLocal;
+    /**
+     * Checks if an object can be used as an anchor target.
+     */
+    private isAnchorable;
+}
+export {};

package/dist/types/kritzel-stencil/src/classes/managers/cursor.manager.d.ts

@@ -0,0 +1,43 @@
+import { KritzelCore } from '../core/core.class';
+/**
+ * Manages cursor state and updates across the application.
+ * Handles cursor changes based on handle hovers, tool states, and interactions.
+ */
+export declare class KritzelCursorManager {
+    private readonly _core;
+    private _targetElement;
+    private _shadowRoot;
+    constructor(core: KritzelCore);
+    /**
+     * Sets the target element where cursor styles will be applied.
+     * Also sets the pointer cursor CSS variable for child components.
+     */
+    setTargetElement(element: HTMLElement | null): void;
+    /**
+     * Gets the current cursor target element.
+     */
+    getTargetElement(): HTMLElement | null;
+    /**
+     * Sets the shadow root for element detection.
+     */
+    setShadowRoot(shadowRoot: ShadowRoot): void;
+    /**
+     * Resets cursor to default state.
+     * Should be called when all pointers are released.
+     */
+    resetToDefault(): void;
+    /**
+     * Detects handle hover states using elementsFromPoint() to work with overlapped elements.
+     * This approach finds all elements at the pointer position instead of relying on pointerenter/pointerleave.
+     */
+    updateHoverState(ev: PointerEvent): void;
+    /**
+     * Applies the current cursor state to the target element.
+     * Should be called in the render loop.
+     */
+    applyCursor(): void;
+    /**
+     * Cleans up cursor state when the component is disconnected.
+     */
+    cleanup(): void;
+}

package/dist/types/kritzel-stencil/src/classes/managers/theme.manager.d.ts

@@ -0,0 +1,56 @@
+import { KritzelTheme, ThemeName } from '../../interfaces/theme.interface';
+import { KritzelCore } from '../core/core.class';
+/**
+ * Manages theme state and application across the Kritzel editor.
+ * Handles theme persistence, retrieval, and CSS variable application.
+ */
+export declare class KritzelThemeManager {
+    private readonly _core;
+    private _currentTheme;
+    private _targetElement;
+    constructor(core: KritzelCore);
+    /**
+     * Gets the current active theme name.
+     */
+    get currentTheme(): ThemeName;
+    /**
+     * Sets the target element where theme CSS variables will be applied.
+     */
+    setTargetElement(element: HTMLElement | null): void;
+    /**
+     * Gets the current target element.
+     */
+    getTargetElement(): HTMLElement | null;
+    /**
+     * Gets the theme object by name.
+     */
+    getThemeByName(themeName: ThemeName): KritzelTheme;
+    /**
+     * Gets the stored theme name from localStorage.
+     * Can be called statically without a manager instance.
+     * @returns The stored theme name, or 'light' as default
+     */
+    static getStoredTheme(): ThemeName;
+    /**
+     * Saves the theme name to localStorage.
+     */
+    saveTheme(themeName: ThemeName): void;
+    /**
+     * Sets the current theme, saves it to storage, and applies it to the target element.
+     */
+    setTheme(themeName: ThemeName): void;
+    /**
+     * Checks if the current theme is dark.
+     */
+    isDarkTheme(): boolean;
+    /**
+     * Applies a theme to the target element by setting CSS custom properties.
+     * Uses the generic theme utility to automatically derive CSS variable names
+     * from the theme interface structure.
+     */
+    applyTheme(themeName: ThemeName): void;
+    /**
+     * Cleans up theme manager state.
+     */
+    cleanup(): void;
+}

package/dist/types/kritzel-stencil/src/classes/objects/base-object.class.d.ts

@@ -0,0 +1,76 @@
+import { KritzelBoundingBox } from '../../interfaces/bounding-box.interface';
+import { KritzelObject } from '../../interfaces/object.interface';
+import { KritzelPolygon } from '../../interfaces/polygon.interface';
+import { KritzelSerializable } from '../../interfaces/serializable.interface';
+import { KritzelCore } from '../core/core.class';
+import { KritzelClonable } from '../../interfaces/clonable.interface';
+import { ThemeAwareColor } from '../../constants/color-palette.constants';
+export declare class KritzelBaseObject<T extends Element = HTMLElement | SVGElement> implements KritzelObject<T>, KritzelSerializable, KritzelClonable<KritzelBaseObject<T>> {
+    __class__: string;
+    _core: KritzelCore;
+    _elementRef: T;
+    id: string;
+    workspaceId: string;
+    x: number;
+    y: number;
+    translateX: number;
+    translateY: number;
+    height: number;
+    width: number;
+    backgroundColor?: ThemeAwareColor;
+    borderColor?: ThemeAwareColor;
+    borderWidth: number;
+    opacity: number;
+    padding: number;
+    scale: number;
+    resizing: boolean;
+    rotation: number;
+    markedForRemoval: boolean;
+    zIndex: number;
+    isVisible: boolean;
+    isSelected: boolean;
+    isHovered: boolean;
+    isMounted: boolean;
+    isEditable: boolean;
+    isInteractive: boolean;
+    isDebugInfoVisible: boolean;
+    get totalWidth(): number;
+    get totalHeight(): number;
+    set elementRef(element: T);
+    get elementRef(): T;
+    get boundingBox(): KritzelBoundingBox;
+    get rotatedBoundingBox(): KritzelBoundingBox;
+    get rotatedPolygon(): KritzelPolygon;
+    get minXRotated(): number;
+    get minYRotated(): number;
+    get maxXRotated(): number;
+    get maxYRotated(): number;
+    get transformationMatrix(): string;
+    get rotationDegrees(): number;
+    get centerX(): number;
+    get centerY(): number;
+    constructor();
+    static create(core: KritzelCore): KritzelBaseObject<Element>;
+    mount(element: T): void;
+    generateId(): string;
+    isInViewport(): boolean;
+    centerInViewport(): void;
+    update(): void;
+    move(startX: number, startY: number, endX: number, endY: number): void;
+    resize(x: number, y: number, width: number, height: number): void;
+    rotate(value: number): void;
+    clone(): KritzelBaseObject<T>;
+    copy(): KritzelBaseObject<T>;
+    serialize(): any;
+    deserialize<T>(object: any): T;
+    isClass<T extends KritzelBaseObject>(this: T, className: string): this is T;
+    edit(_event?: PointerEvent): void;
+    /**
+     * Called after properties are updated via updateObject.
+     * Override in subclasses to perform custom logic when specific properties change.
+     */
+    onAfterUpdate(_changedProperties: string[]): void;
+    hitTest(_x: number, _y: number): boolean;
+    hitTestPolygon(polygon: KritzelPolygon): boolean;
+    updatePosition(x: number, y: number): void;
+}

package/dist/types/kritzel-stencil/src/classes/objects/custom-element.class.d.ts

@@ -0,0 +1,26 @@
+import { KritzelCore } from '../core/core.class';
+import { KritzelBaseObject } from './base-object.class';
+export declare class KritzelCustomElement extends KritzelBaseObject<HTMLElement> {
+    __class__: string;
+    element: HTMLElement;
+    isInteractive: boolean;
+    constructor(config?: {
+        element: HTMLElement;
+        translateX?: number;
+        translateY?: number;
+        scale?: number;
+        height?: number;
+        width?: number;
+    });
+    static create(core: KritzelCore, config?: {
+        element: HTMLElement;
+        translateX?: number;
+        translateY?: number;
+        scale?: number;
+        height?: number;
+        width?: number;
+    }): KritzelBaseObject<Element>;
+    mount(element: HTMLElement): void;
+    resize(x: number, y: number, width: number, height: number): void;
+    copy(): KritzelCustomElement;
+}

package/dist/types/kritzel-stencil/src/classes/objects/group.class.d.ts

@@ -0,0 +1,97 @@
+import { KritzelCore } from '../core/core.class';
+import { KritzelBaseObject } from './base-object.class';
+import { KritzelPolygon } from '../../interfaces/polygon.interface';
+/**
+ * KritzelGroup represents a permanent grouping of objects that act as a single unit.
+ *
+ * Unlike KritzelSelectionGroup (which is ephemeral and used for temporary multi-selection),
+ * KritzelGroup is persisted and saved with the workspace. Grouped objects move, resize,
+ * rotate, copy, and delete together as one unit.
+ *
+ * Key features:
+ * - Supports nested groups (groups can contain other groups)
+ * - Clicking any child selects the entire group
+ * - Can be ungrouped to restore children to top-level objects
+ */
+export declare class KritzelGroup extends KritzelBaseObject<HTMLElement> {
+    __class__: string;
+    /**
+     * IDs of child objects within this group.
+     * Children can be any KritzelBaseObject, including other KritzelGroups for nesting.
+     */
+    childIds: string[];
+    /**
+     * Snapshots of child states for transformation operations (resize, rotate).
+     * Similar pattern to KritzelSelectionGroup.
+     */
+    private unchangedChildSnapshots;
+    private snapshotRotation;
+    private snapshotTranslateX;
+    private snapshotTranslateY;
+    private snapshotTotalWidth;
+    private snapshotTotalHeight;
+    private snapshotScale;
+    /**
+     * Retrieves the actual child objects from the store by their IDs.
+     */
+    get children(): KritzelBaseObject<any>[];
+    /**
+     * Returns the number of children in this group.
+     */
+    get length(): number;
+    /**
+     * Creates a new empty KritzelGroup.
+     */
+    static create(core: KritzelCore): KritzelGroup;
+    /**
+     * Creates a KritzelGroup from an array of objects.
+     * The objects are added as children and their bounding box is calculated.
+     */
+    static createFromObjects(core: KritzelCore, objects: KritzelBaseObject<any>[]): KritzelGroup;
+    /**
+     * Finds the parent KritzelGroup that contains the given object as a child.
+     * Returns null if the object is not a child of any group.
+     */
+    static findParentGroup(core: KritzelCore, objectId: string): KritzelGroup | null;
+    /**
+     * Adds a child object to this group.
+     */
+    addChild(object: KritzelBaseObject<any>): void;
+    /**
+     * Removes a child object from this group.
+     */
+    removeChild(objectId: string): void;
+    /**
+     * Ungroups this group, returning all children to top-level objects.
+     * The group itself should be removed after calling this.
+     */
+    ungroup(): KritzelBaseObject<any>[];
+    /**
+     * Finalizes the group after children have been positioned (e.g., after paste).
+     * Refreshes the bounding box and captures child snapshots.
+     */
+    finalize(): void;
+    /**
+     * Recalculates the group's bounding box based on its children.
+     */
+    refreshBoundingBox(): void;
+    /**
+     * Captures snapshots of child states for transformation operations.
+     */
+    private captureChildSnapshots;
+    move(startX: number, startY: number, endX: number, endY: number): void;
+    resize(x: number, y: number, width: number, height: number): void;
+    rotate(value: number): void;
+    private getOffsetXToCenterFromSnapshot;
+    private getOffsetYToCenterFromSnapshot;
+    hitTest(x: number, y: number): boolean;
+    hitTestPolygon(polygon: KritzelPolygon): boolean;
+    copy(): KritzelGroup;
+    serialize(): any;
+    deserialize<T>(object: any): T;
+    update(): void;
+    /**
+     * Updates the workspace ID for this group and all its children.
+     */
+    updateWorkspaceId(workspaceId: string): void;
+}

package/dist/types/kritzel-stencil/src/classes/objects/image.class.d.ts

@@ -0,0 +1,17 @@
+import { KritzelCore } from '../core/core.class';
+import { KritzelBaseObject } from './base-object.class';
+export declare class KritzelImage extends KritzelBaseObject<HTMLImageElement> {
+    __class__: string;
+    src: string;
+    maxWidth: number;
+    maxHeight: number;
+    maxCompressionSize: number;
+    isDebugInfoVisible: boolean;
+    constructor(config?: Partial<KritzelImage>);
+    static create(core: KritzelCore): KritzelImage;
+    resize(x: number, y: number, width: number, height: number): void;
+    calculateScaledDimensions(img: HTMLImageElement): {
+        scaledWidth: number;
+        scaledHeight: number;
+    };
+}

package/dist/types/kritzel-stencil/src/classes/objects/line.class.d.ts

@@ -0,0 +1,101 @@
+import { KritzelLineOptions } from '../../interfaces/line-options.interface';
+import { KritzelBaseObject } from './base-object.class';
+import { KritzelPolygon } from '../../interfaces/polygon.interface';
+import { KritzelCore } from '../core/core.class';
+import { LineAnchor } from '../../interfaces/anchor.interface';
+import { ArrowHeadStyle, LineArrowConfig } from '../../interfaces/arrow-head.interface';
+import { ThemeAwareColor } from '../../constants/color-palette.constants';
+export declare class KritzelLine extends KritzelBaseObject<SVGElement> {
+    __class__: string;
+    startX: number;
+    startY: number;
+    endX: number;
+    endY: number;
+    controlX?: number;
+    controlY?: number;
+    stroke: ThemeAwareColor;
+    strokeWidth: number;
+    scale: number;
+    options: KritzelLineOptions | undefined;
+    /** Anchor connection for the start point of the line */
+    startAnchor?: LineAnchor;
+    /** Anchor connection for the end point of the line */
+    endAnchor?: LineAnchor;
+    /** Arrow head configuration for start and end of line */
+    arrows?: LineArrowConfig;
+    isVisible: boolean;
+    isDebugInfoVisible: boolean;
+    isCompleted: boolean;
+    private _adjustedPoints?;
+    private _clipInfo;
+    get d(): string;
+    get viewBox(): string;
+    constructor(config?: KritzelLineOptions);
+    static create(core: KritzelCore, options?: KritzelLineOptions): KritzelLine;
+    resize(x: number | null, y: number | null, width: number, height: number): void;
+    rotate(value: number): void;
+    move(startX: number, startY: number, endX: number, endY: number): void;
+    hitTest(x: number, y: number): boolean;
+    hitTestPolygon(polygon: KritzelPolygon): boolean;
+    updatePosition(x: number, y: number): void;
+    /**
+     * Updates a specific endpoint of the line (start or end).
+     * The coordinates are in viewBox-local space (relative to x, y origin).
+     * This method recalculates the bounding box dimensions.
+     *
+     * @param handleType - Which endpoint to update: 'start' or 'end'
+     * @param newX - New X coordinate in viewBox-local space
+     * @param newY - New Y coordinate in viewBox-local space
+     */
+    updateEndpoint(handleType: 'start' | 'end', newX: number, newY: number): void;
+    updateControlPoint(newX: number | undefined, newY: number | undefined): void;
+    private computeAdjustedPoints;
+    private pointToLineSegmentDistance;
+    /**
+     * Calculates the minimum distance from a point to a quadratic Bezier curve.
+     * Uses sampling along the curve to find the closest point.
+     */
+    private pointToBezierDistance;
+    private getClipInfo;
+    /**
+     * Computes the adjusted control point in world coordinates, accounting for rotation and translation.
+     */
+    private computeAdjustedControlPoint;
+    get rotatedPolygon(): KritzelPolygon;
+    /**
+     * Calculates the tight bounding box for a quadratic Bezier curve or straight line.
+     * For curves, it finds the extrema points where the derivative equals zero.
+     */
+    static calculateBoundingBox(startX: number, startY: number, endX: number, endY: number, controlX: number | undefined, controlY: number | undefined, strokeWidth: number): {
+        minX: number;
+        minY: number;
+        maxX: number;
+        maxY: number;
+    };
+    calculateBoundingBox(): {
+        minX: number;
+        minY: number;
+        maxX: number;
+        maxY: number;
+    };
+    private updateDimensions;
+    /** Get unique marker ID for SVG defs at the start of the line */
+    get startMarkerId(): string;
+    /** Get unique marker ID for SVG defs at the end of the line */
+    get endMarkerId(): string;
+    /** Get the arrow size for start or end, defaulting to strokeWidth * 3 */
+    getArrowSize(end: 'start' | 'end'): number;
+    /** Get the arrow fill color for start or end, defaulting to stroke color */
+    getArrowFill(end: 'start' | 'end'): string;
+    /**
+     * Generate SVG path data for an arrow head based on the given style.
+     * The path is designed to fit in a 10x10 viewBox with the tip at (10, 5).
+     * @param style The arrow head style
+     * @returns SVG path data string
+     */
+    getArrowPath(style?: ArrowHeadStyle): string;
+    /** Check if start arrow is enabled */
+    get hasStartArrow(): boolean;
+    /** Check if end arrow is enabled */
+    get hasEndArrow(): boolean;
+}