@kritzel/engine 0.4.31

package/dist/collection/classes/core/reviver.class.js

@@ -0,0 +1,124 @@
+import { KritzelImage } from "../objects/image.class";
+import { KritzelLine } from "../objects/line.class";
+import { KritzelPath } from "../objects/path.class";
+import { KritzelShape } from "../objects/shape.class";
+import { KritzelSelectionGroup } from "../objects/selection-group.class";
+import { KritzelGroup } from "../objects/group.class";
+import { KritzelText } from "../objects/text.class";
+import { KritzelBrushTool } from "../tools/brush-tool.class";
+import { KritzelEraserTool } from "../tools/eraser-tool.class";
+import { KritzelImageTool } from "../tools/image-tool.class";
+import { KritzelLineTool } from "../tools/line-tool.class";
+import { KritzelSelectionTool } from "../tools/selection-tool.class";
+import { KritzelTextTool } from "../tools/text-tool.class";
+import { KritzelShapeTool } from "../tools/shape-tool.class";
+import { KritzelDynamicObject } from "../objects/dynamic-object.class";
+import { KritzelWorkspace } from "./workspace.class";
+/**
+ * Handles deserialization/revival of Kritzel objects from plain JavaScript objects.
+ * This class uses a pattern similar to JSON.parse reviver to reconstruct class instances
+ * from their serialized representations, preserving the object's prototype chain and methods.
+ */
+export class KritzelReviver {
+    /** Reference to the KritzelCore instance for creating objects */
+    _core;
+    /**
+     * Creates a new KritzelReviver instance.
+     * @param core - The KritzelCore instance used to create revived objects
+     */
+    constructor(core) {
+        this._core = core;
+    }
+    /**
+     * Recursively revives a plain JavaScript object (or array) into typed Kritzel instances.
+     * Uses the `__class__` property to determine the correct class to instantiate.
+     * Objects without `__class__` are recursively processed to revive nested objects.
+     *
+     * Supported classes:
+     * - Objects: KritzelPath, KritzelLine, KritzelText, KritzelShape, KritzelImage,
+     *            KritzelDynamicObject, KritzelSelectionGroup, KritzelGroup
+     * - Workspace: KritzelWorkspace
+     * - Tools: KritzelBrushTool, KritzelEraserTool, KritzelImageTool, KritzelSelectionTool,
+     *          KritzelTextTool, KritzelLineTool, KritzelShapeTool
+     *
+     * @typeParam T - The expected return type after revival
+     * @param obj - The plain object to revive, typically from JSON deserialization
+     * @returns The revived object with proper class instances, or the original value if not an object
+     */
+    revive(obj) {
+        if (obj && typeof obj === 'object') {
+            if (obj.__class__) {
+                let revivedObj;
+                switch (obj.__class__) {
+                    case 'KritzelPath':
+                        revivedObj = KritzelPath.create(this._core).deserialize(obj);
+                        break;
+                    case 'KritzelLine':
+                        revivedObj = KritzelLine.create(this._core).deserialize(obj);
+                        break;
+                    case 'KritzelText':
+                        revivedObj = KritzelText.create(this._core, obj.fontSize, obj.fontFamily).deserialize(obj);
+                        break;
+                    case 'KritzelShape':
+                        revivedObj = KritzelShape.create(this._core, {
+                            shapeType: obj.shapeType,
+                            fillColor: obj.fillColor,
+                            strokeColor: obj.strokeColor,
+                            strokeWidth: obj.strokeWidth,
+                            fontSize: obj.fontSize,
+                            fontFamily: obj.fontFamily,
+                            fontColor: obj.fontColor,
+                        }).deserialize(obj);
+                        break;
+                    case 'KritzelImage':
+                        revivedObj = KritzelImage.create(this._core).deserialize(obj);
+                        break;
+                    case 'KritzelDynamicObject':
+                        revivedObj = KritzelDynamicObject.create(this._core).deserialize(obj);
+                        break;
+                    case 'KritzelSelectionGroup':
+                        revivedObj = KritzelSelectionGroup.create(this._core).deserialize(obj);
+                        break;
+                    case 'KritzelGroup':
+                        revivedObj = KritzelGroup.create(this._core).deserialize(obj);
+                        break;
+                    case 'KritzelWorkspace':
+                        revivedObj = KritzelWorkspace.create(this._core, obj).deserialize(obj);
+                        break;
+                    case 'KritzelBrushTool':
+                        revivedObj = new KritzelBrushTool(this._core);
+                        break;
+                    case 'KritzelEraserTool':
+                        revivedObj = new KritzelEraserTool(this._core);
+                        break;
+                    case 'KritzelImageTool':
+                        revivedObj = new KritzelImageTool(this._core);
+                        break;
+                    case 'KritzelSelectionTool':
+                        revivedObj = new KritzelSelectionTool(this._core);
+                        break;
+                    case 'KritzelTextTool':
+                        revivedObj = new KritzelTextTool(this._core);
+                        break;
+                    case 'KritzelLineTool':
+                        revivedObj = new KritzelLineTool(this._core);
+                        break;
+                    case 'KritzelShapeTool':
+                        revivedObj = new KritzelShapeTool(this._core);
+                        break;
+                    default:
+                        revivedObj = obj;
+                }
+                return revivedObj;
+            }
+            const newObj = Array.isArray(obj) ? [] : {};
+            for (const key in obj) {
+                if (Object.prototype.hasOwnProperty.call(obj, key)) {
+                    newObj[key] = this.revive(obj[key]);
+                }
+            }
+            return newObj;
+        }
+        return obj;
+    }
+}

package/dist/collection/classes/core/store.class.js

@@ -0,0 +1,337 @@
+import { KritzelSelectionGroup } from "../objects/selection-group.class";
+import { KritzelSelectionBox } from "../objects/selection-box.class";
+import { KritzelText } from "../objects/text.class";
+import { KritzelShape } from "../objects/shape.class";
+import { KritzelPath } from "../objects/path.class";
+import { KritzelLine } from "../objects/line.class";
+import { KritzelClassHelper } from "../../helpers/class.helper";
+import { KritzelObjectMap } from "../structures/object-map.structure";
+/**
+ * Central state management store for the Kritzel engine.
+ * Provides reactive state management with change listeners, caching for frequently
+ * accessed objects, and computed properties for viewport and selection state.
+ */
+export class KritzelStore {
+    /** Internal state object containing all engine state properties */
+    _state;
+    /** Map of property keys to their registered change listeners */
+    _listeners = new Map();
+    // Cached references for O(1) access to frequently accessed special objects
+    _cachedSelectionBox = null;
+    _cachedSelectionGroup = null;
+    _selectionBoxCacheValid = false;
+    _selectionGroupCacheValid = false;
+    _localUserId = null;
+    /**
+     * Gets the current engine state.
+     * @returns The mutable engine state object
+     */
+    get state() {
+        return this._state;
+    }
+    /**
+     *  Gets the map of all objects in the workspace.
+     *  Throws an error if the objects map is not initialized, as it is required for all object management.
+     *  @returns The KritzelObjectMap containing all objects
+     *  @throws Error if the objects map is not initialized in the state
+     */
+    get objects() {
+        if (!this._state.objects) {
+            throw new Error('Objects map is not initialized.');
+        }
+        return this._state.objects;
+    }
+    /**
+     * Gets the host element for the Kritzel editor.
+     * Throws an error if the host is not set, as it is required for many operations.
+     * @returns The host HTMLElement
+     * @throws Error if the host element is not set in the state
+     */
+    get host() {
+        if (!this._state.host) {
+            throw new Error('Host element is not set.');
+        }
+        return this._state.host;
+    }
+    /**
+     * Gets the next available z-index for new objects.
+     * Calculates the maximum z-index among all non-selection objects and adds 1.
+     * @returns The next z-index value to use for new objects
+     */
+    get currentZIndex() {
+        return Math.max(0, ...this.objects.filter(o => !(o instanceof KritzelSelectionGroup) && !(o instanceof KritzelSelectionBox)).map(o => o.zIndex)) + 1;
+    }
+    /**
+     * Returns true if viewport boundaries are set to finite values (not Infinity).
+     */
+    get hasViewportBoundaries() {
+        return (Number.isFinite(this._state.viewportBoundaryLeft) ||
+            Number.isFinite(this._state.viewportBoundaryRight) ||
+            Number.isFinite(this._state.viewportBoundaryTop) ||
+            Number.isFinite(this._state.viewportBoundaryBottom));
+    }
+    /**
+     * Returns the viewport boundary bounds for querying objects.
+     * Uses the configured boundaries, defaulting to Infinity for unset values.
+     */
+    get viewportBoundaryBounds() {
+        const left = this._state.viewportBoundaryLeft;
+        const right = this._state.viewportBoundaryRight;
+        const top = this._state.viewportBoundaryTop;
+        const bottom = this._state.viewportBoundaryBottom;
+        return {
+            x: Number.isFinite(left) ? left : -Infinity,
+            y: Number.isFinite(top) ? top : -Infinity,
+            z: 0,
+            width: Number.isFinite(left) && Number.isFinite(right) ? right - left : Infinity,
+            height: Number.isFinite(top) && Number.isFinite(bottom) ? bottom - top : Infinity,
+        };
+    }
+    /**
+     * Gets the total count of objects in the workspace.
+     * When viewport boundaries are set, returns only objects within those boundaries.
+     * @returns The total number of objects
+     */
+    get totalObjectCount() {
+        if (this.hasViewportBoundaries) {
+            return this.allObjects.length;
+        }
+        return this.objects.totalCount;
+    }
+    /**
+     * Gets all objects in the workspace.
+     * When viewport boundaries are set, returns only objects within those boundaries.
+     * @returns Array of all canvas objects
+     */
+    get allObjects() {
+        if (this.hasViewportBoundaries) {
+            return this.objects.query(this.viewportBoundaryBounds);
+        }
+        return this.objects.allObjects();
+    }
+    /**
+     * Gets all objects currently visible in the viewport.
+     * Uses spatial querying for efficient retrieval and sorts by z-index.
+     * @returns Array of objects within the current viewport, sorted by z-index ascending
+     */
+    get objectsInViewport() {
+        const viewportBounds = {
+            x: -this._state.translateX / this._state.scale,
+            y: -this._state.translateY / this._state.scale,
+            z: this._state.scale,
+            width: this._state.viewportWidth / this._state.scale,
+            height: this._state.viewportHeight / this._state.scale,
+            depth: 100,
+        };
+        return this.objects.query(viewportBounds).sort((a, b) => a.zIndex - b.zIndex);
+    }
+    /**
+     * Gets all objects excluding selection-related objects (selection group and selection box).
+     * @returns Array of all regular canvas objects
+     */
+    get allNonSelectionObjects() {
+        return this.allObjects.filter(o => !(o instanceof KritzelSelectionGroup) && !(o instanceof KritzelSelectionBox));
+    }
+    /**
+     * Gets all currently selected objects (excluding the selection group itself).
+     * @returns Array of selected objects
+     */
+    get selectedObjects() {
+        return this.allObjects.filter(o => !(o instanceof KritzelSelectionGroup) && !(o instanceof KritzelSelectionBox)).filter(o => o.isSelected);
+    }
+    /**
+     * Gets the current selection box if one exists.
+     * Uses caching for O(1) access after initial lookup.
+     * @returns The selection box or null if none exists
+     */
+    get selectionBox() {
+        if (this._selectionBoxCacheValid) {
+            return this._cachedSelectionBox;
+        }
+        const selectionBoxes = this.objects.filter(o => o instanceof KritzelSelectionBox);
+        this._cachedSelectionBox = selectionBoxes.length > 0 ? selectionBoxes[0] : null;
+        this._selectionBoxCacheValid = true;
+        return this._cachedSelectionBox;
+    }
+    /**
+     * Gets the current local user's selection group if one exists.
+     * When a local user ID is set, returns only the selection group belonging to that user.
+     * Uses caching for O(1) access after initial lookup.
+     * @returns The local user's selection group or null if none exists
+     */
+    get selectionGroup() {
+        if (this._selectionGroupCacheValid) {
+            return this._cachedSelectionGroup;
+        }
+        const selectionGroups = this.objects.filter(o => o instanceof KritzelSelectionGroup);
+        if (this._localUserId) {
+            this._cachedSelectionGroup = selectionGroups.find(sg => sg.userId === this._localUserId) ?? null;
+        }
+        else {
+            this._cachedSelectionGroup = selectionGroups.length > 0 ? selectionGroups[0] : null;
+        }
+        this._selectionGroupCacheValid = true;
+        return this._cachedSelectionGroup;
+    }
+    /**
+     * Invalidate cached selection objects. Call this when selection objects are inserted or removed.
+     */
+    invalidateSelectionCache() {
+        this._selectionBoxCacheValid = false;
+        this._selectionGroupCacheValid = false;
+    }
+    /**
+     * Directly set the cached selection box reference for O(1) access.
+     * Use this when creating the selection box to avoid a filter lookup.
+     * @param box - The selection box to cache, or null to clear the cache
+     */
+    setSelectionBox(box) {
+        this._cachedSelectionBox = box;
+        this._selectionBoxCacheValid = true;
+    }
+    /**
+     * Directly set the cached selection group reference for O(1) access.
+     * Use this when creating the selection group to avoid a filter lookup.
+     * @param group - The selection group to cache, or null to clear the cache
+     */
+    setSelectionGroup(group) {
+        this._cachedSelectionGroup = group;
+        this._selectionGroupCacheValid = true;
+    }
+    /**
+     * Sets the local user ID for scoping selection group lookups.
+     * When set, the selectionGroup getter returns only the group owned by this user.
+     * @param userId - The local user's ID, or null for non-collaborative mode
+     */
+    setLocalUserId(userId) {
+        this._localUserId = userId;
+        this.invalidateSelectionCache();
+    }
+    /**
+     * Gets the currently active text object being edited.
+     * @returns The text object in editing mode, or null if none
+     */
+    get activeText() {
+        const activeTexts = this.objects.filter(o => o instanceof KritzelText && o.isEditing);
+        return activeTexts.length > 0 ? activeTexts[0] : null;
+    }
+    /**
+     * Gets the currently active shape object being edited.
+     * @returns The shape object in editing mode, or null if none
+     */
+    get activeShape() {
+        const activeShapes = this.objects.filter(o => o instanceof KritzelShape && o.isEditing);
+        return activeShapes.length > 0 ? activeShapes[0] : null;
+    }
+    /**
+     * Gets the currently selected dynamic object whose focused descendant is an input-like element.
+     * @returns The interactive dynamic object with focused input-like content, or null if none matches
+     */
+    get activeInteractiveDynamicObject() {
+        const interactiveDynamicObject = this.selectedObjects.find(object => KritzelClassHelper.isInstanceOf(object, 'KritzelDynamicObject') && object.hasFocusedInputElement());
+        return interactiveDynamicObject ?? null;
+    }
+    /**
+     * Gets the path currently being drawn (not yet completed).
+     * @returns The incomplete path object, or null if no path is being drawn
+     */
+    get currentPath() {
+        const drawingPaths = this.objects.filter(o => o instanceof KritzelPath && o.isCompleted === false);
+        return drawingPaths.length > 0 ? drawingPaths[0] : null;
+    }
+    /**
+     * Gets the line currently being drawn (not yet completed).
+     * @returns The incomplete line object, or null if no line is being drawn
+     */
+    get currentLine() {
+        const drawingLines = this.objects.filter(o => o instanceof KritzelLine && o.isCompleted === false);
+        return drawingLines.length > 0 ? drawingLines[0] : null;
+    }
+    /**
+     * Gets the horizontal offset of the host element from the viewport.
+     * @returns The left position of the host element in client coordinates
+     */
+    get offsetX() {
+        return this.host.getBoundingClientRect().left;
+    }
+    /**
+     * Gets the vertical offset of the host element from the viewport.
+     * @returns The top position of the host element in client coordinates
+     */
+    get offsetY() {
+        return this.host.getBoundingClientRect().top;
+    }
+    /**
+     * Checks if the engine is currently disabled.
+     * The engine is disabled when not enabled, not ready, or no active workspace exists.
+     * @returns True if the engine is disabled and should not process interactions
+     */
+    get isDisabled() {
+        return this._state.isEnabled === false || this._state.isReady === false || this._state.activeWorkspace === null;
+    }
+    /**
+     * Checks if any pointer is currently down (active).
+     * @returns True if at least one pointer is currently active
+     */
+    get isPointerDown() {
+        return this._state.pointers.size > 0;
+    }
+    /**
+     * Creates a new KritzelStore instance.
+     * @param state - The initial engine state configuration
+     */
+    constructor(state) {
+        this._state = {
+            ...state,
+            contextMenuItems: [...state.contextMenuItems],
+            debugInfo: { ...state.debugInfo },
+            pointers: new Map(state.pointers),
+            workspaces: [...state.workspaces],
+            cursor: { ...state.cursor },
+        };
+        this._state.objects = new KritzelObjectMap();
+    }
+    /**
+     * Registers a listener for changes to a specific state property.
+     * The listener will be called whenever the property value changes.
+     * @typeParam K - The state property key type
+     * @param property - The property key to listen for changes on
+     * @param listener - The callback function to invoke on changes
+     */
+    onStateChange(property, listener) {
+        if (!this._listeners.has(property)) {
+            this._listeners.set(property, new Set());
+        }
+        const listenersForProperty = this._listeners.get(property);
+        if (!listenersForProperty) {
+            throw new Error(`Listeners set for property ${String(property)} was not initialized.`);
+        }
+        listenersForProperty.add(listener);
+    }
+    /**
+     * Gets the current value of a state property as readonly.
+     * @typeParam K - The state property key type
+     * @param property - The property key to retrieve
+     * @returns The current value of the property
+     */
+    getState(property) {
+        return this._state[property];
+    }
+    /**
+     * Sets a state property value and notifies registered listeners.
+     * Only triggers listeners if the value actually changed.
+     * @typeParam K - The state property key type
+     * @param property - The property key to set
+     * @param value - The new value to assign
+     */
+    setState(property, value) {
+        const oldValue = this._state[property];
+        if (oldValue !== value) {
+            this._state[property] = value;
+            const listenersForProperty = this._listeners.get(property);
+            if (listenersForProperty) {
+                listenersForProperty.forEach(listener => listener(value, oldValue, String(property)));
+            }
+        }
+    }
+}