@kritzel/engine 0.4.31

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

@@ -0,0 +1,112 @@
+import { ObjectHelper } from "../../helpers/object.helper";
+/** Current version of the workspace export format */
+export const WORKSPACE_EXPORT_VERSION = '1.3.0';
+/**
+ * Represents a workspace in the Kritzel canvas.
+ * A workspace is an isolated canvas area with its own set of objects and viewport state.
+ * It can be serialized and deserialized for persistence and collaborative editing.
+ */
+export class KritzelWorkspace {
+    __class__ = 'KritzelWorkspace';
+    /** Unique identifier for the workspace */
+    id;
+    /** Display name of the workspace */
+    name;
+    /** Timestamp when the workspace was created */
+    createdAt;
+    /** Timestamp when the workspace was last updated */
+    updatedAt;
+    /** Viewport state containing the world-space center point and zoom level */
+    viewport;
+    /**
+     * Desired canvas objects. Seeded when the workspace is first initialized and applied as the
+     * full desired set by `updateWorkspace()`: `undefined` leaves objects untouched, `[]` removes all.
+     */
+    objects;
+    /** Whether the workspace is publicly accessible via a share link */
+    isPublic;
+    /** Reference to the KritzelCore instance managing this workspace */
+    _core;
+    /**
+     * Creates a new KritzelWorkspace instance.
+     * @param config - Configuration options object for the workspace
+     */
+    constructor(config) {
+        this.id = config?.id ?? ObjectHelper.generateUUID();
+        this.name = config?.name ?? 'New Workspace';
+        this.createdAt = new Date();
+        this.updatedAt = new Date();
+        this.viewport = {
+            centerWorldX: config?.viewport?.centerWorldX ?? 0,
+            centerWorldY: config?.viewport?.centerWorldY ?? 0,
+            scale: config?.viewport?.scale ?? 1,
+        };
+        this.objects = config?.objects;
+        this.isPublic = false;
+    }
+    /**
+     * Factory method to create a workspace with a core reference.
+     * @param core - The KritzelCore instance to associate with this workspace
+     * @param obj - Object containing workspace properties (id, name, viewport)
+     * @returns A new KritzelWorkspace instance with the core reference set
+     */
+    static create(core, obj) {
+        const workspace = new KritzelWorkspace({
+            id: obj.id,
+            name: obj.name,
+            viewport: obj.viewport,
+        });
+        workspace._core = core;
+        return workspace;
+    }
+    /**
+     * Adds an object to this workspace via the core engine.
+     * @param obj - The object to add to the workspace
+     */
+    addObject(obj) {
+        this._core.engine.addObject(obj);
+    }
+    /**
+     * Serializes the workspace to a plain object for storage or transmission.
+     * Converts dates to ISO strings and includes the class identifier.
+     * @param options - Optional settings for serialization
+     * @param options.includeObjects - If true, includes all canvas objects in the serialized output
+     * @returns A plain object representation of the workspace
+     */
+    serialize(options) {
+        const serialized = {
+            __class__: this.__class__,
+            version: WORKSPACE_EXPORT_VERSION,
+            id: this.id,
+            name: this.name,
+            createdAt: this.createdAt.toISOString(),
+            updatedAt: this.updatedAt.toISOString(),
+            viewport: this.viewport,
+            isPublic: this.isPublic,
+        };
+        if (options?.includeObjects && this._core) {
+            const allObjects = this._core.store.allNonSelectionObjects;
+            serialized.objects = allObjects.map(obj => obj.serialize());
+        }
+        return serialized;
+    }
+    /**
+     * Creates a shallow clone of this workspace, preserving the prototype chain.
+     * Useful when Stencil needs a new object reference to detect property changes.
+     */
+    clone() {
+        return Object.assign(Object.create(Object.getPrototypeOf(this)), this);
+    }
+    /**
+     * Deserializes a plain object into this workspace instance.
+     * Converts ISO string dates back to Date objects.
+     * @param object - The plain object to deserialize from
+     * @returns This workspace instance with updated properties
+     */
+    deserialize(object) {
+        Object.assign(this, object);
+        this.createdAt = new Date(object.createdAt);
+        this.updatedAt = new Date(object.updatedAt);
+        return this;
+    }
+}

package/dist/collection/classes/handlers/base.handler.js

@@ -0,0 +1,20 @@
+/**
+ * Abstract base class for all Kritzel event handlers.
+ * Provides a common foundation with access to the core instance for derived handler classes
+ * such as key handlers, hover handlers, and context menu handlers.
+ */
+export class KritzelBaseHandler {
+    /**
+     * Reference to the KritzelCore instance.
+     * Provides access to canvas state, store, and operations for derived handlers.
+     */
+    _core;
+    /**
+     * Creates a new instance of the base handler.
+     * @param core - The KritzelCore instance that provides access to canvas state and operations.
+     */
+    constructor(core) {
+        this._core = core;
+        void this._core; // Avoid unused variable warning
+    }
+}

package/dist/collection/classes/handlers/context-menu.handler.js

@@ -0,0 +1,170 @@
+import { KritzelSelectionGroup } from "../objects/selection-group.class";
+import { KritzelBaseHandler } from "./base.handler";
+import { KritzelSelectionBox } from "../objects/selection-box.class";
+/**
+ * Handles context menu interactions on the Kritzel canvas.
+ * Manages the display and positioning of context menus, selecting appropriate menu items
+ * based on whether an object is targeted or the canvas background is right-clicked.
+ */
+export class KritzelContextMenuHandler extends KritzelBaseHandler {
+    /**
+     * Menu items to display when the context menu is opened on the canvas background
+     * (i.e., when no object is selected).
+     */
+    globalContextMenuItems = [];
+    /**
+     * Menu items to display when the context menu is opened on a selected object.
+     */
+    objectContextMenuItems = [];
+    /**
+     * Creates a new instance of the context menu handler.
+     * @param core - The KritzelCore instance that provides access to canvas state and operations.
+     * @param globalContextMenuItems - Array of menu items to show for canvas-level context menus.
+     * @param objectContextMenuItems - Array of menu items to show when right-clicking on objects.
+     */
+    constructor(core, globalContextMenuItems, objectContextMenuItems) {
+        super(core);
+        this.globalContextMenuItems = globalContextMenuItems;
+        this.objectContextMenuItems = objectContextMenuItems;
+    }
+    /**
+     * Resolves the active context menu items for display, translating each item's
+     * `label` through the current locale. When the label is a known
+     * {@link KritzelTermKey} the translation is used; any other string is passed
+     * through unchanged. Runs at menu-open time so the labels reflect the locale
+     * active at that moment.
+     * @returns A new array of items with resolved labels.
+     */
+    resolveLabels(items) {
+        return items.map(item => ({
+            ...item,
+            label: this._core.localizationManager.translate(item.label),
+            children: item.children ? this.resolveLabels(item.children) : undefined,
+        }));
+    }
+    /**
+     * Gets the active context menu items (object or global) with localized labels.
+     */
+    getResolvedContextMenuItems() {
+        const items = this._core.store.selectionGroup ? this.objectContextMenuItems : this.globalContextMenuItems;
+        return this.resolveLabels(items);
+    }
+    /**
+     * Handles the context menu event (typically triggered by right-click).
+     * This method performs the following operations:
+     * 1. Validates that the selection tool is active; exits early otherwise.
+     * 2. Checks and resets the `skipContextMenu` flag if set.
+     * 3. Cancels any pending drag operation on the selection tool.
+     * 4. Clears any active selection box if present.
+     * 5. If an object is clicked, creates a new selection group containing that object.
+     * 6. Determines which menu items to display (object or global context menu).
+     * 7. Calculates the menu position, ensuring it stays within viewport bounds.
+     * 8. Updates the store state to show the context menu and disables canvas interactions.
+     * @param event - The pointer event containing the click coordinates and target information.
+     * @returns void - This method does not return a value; it updates state and triggers a rerender.
+     */
+    handleContextMenu(event) {
+        if (this._core.store.state.activeTool?.toolType !== 'selection') {
+            return;
+        }
+        if (this._core.store.state.skipContextMenu) {
+            this._core.store.state.skipContextMenu = false;
+            return;
+        }
+        const selectionTool = this._core.store.state.activeTool;
+        selectionTool?.moveHandler?.cancelPendingDrag();
+        if (this._core.store.selectionBox) {
+            this._core.store.objects.remove(object => object instanceof KritzelSelectionBox);
+            this._core.store.setSelectionBox(null);
+            this._core.store.state.isSelecting = false;
+        }
+        const selectedObject = this._core.getObjectFromPointerEvent(event, '.object');
+        if (selectedObject && !(selectedObject instanceof KritzelSelectionGroup) && !(selectedObject instanceof KritzelSelectionBox)) {
+            const selectionGroup = KritzelSelectionGroup.create(this._core);
+            selectionGroup.addOrRemove(selectedObject);
+            selectionGroup.isSelected = true;
+            selectionGroup.rotation = selectedObject.rotation;
+            this._core.store.state.isSelecting = false;
+            const currentSelectionGroup = this._core.store.selectionGroup;
+            if (currentSelectionGroup) {
+                this._core.removeSelectionGroup();
+            }
+            this._core.addSelectionGroup(selectionGroup);
+            this._core.rerender();
+        }
+        this._core.store.state.contextMenuItems = this.getResolvedContextMenuItems();
+        const clickX = event.clientX - this._core.store.offsetX;
+        const clickY = event.clientY - this._core.store.offsetY;
+        const { translateX, translateY, scale } = this._core.store.state;
+        this._core.store.state.contextMenuWorldX = (clickX - translateX) / scale;
+        this._core.store.state.contextMenuWorldY = (clickY - translateY) / scale;
+        let x = clickX;
+        let y = clickY;
+        const menuWidthEstimate = 150;
+        const margin = 10;
+        if (x + menuWidthEstimate > this._core.store.state.viewportWidth - margin) {
+            x = this._core.store.state.viewportWidth - menuWidthEstimate - margin;
+        }
+        x = Math.max(margin, x);
+        y = Math.max(margin, y);
+        this._core.store.state.contextMenuX = x;
+        this._core.store.state.contextMenuY = y;
+        this._core.store.state.isContextMenuVisible = true;
+        this._core.store.state.isEnabled = false;
+        this._core.rerender();
+    }
+    /**
+     * Programmatically opens the context menu at a specified world-coordinate position.
+     * If an objectId is provided and found, the object context menu is shown for that object.
+     * If no objectId is provided but a selection group exists, the object context menu is shown.
+     * Otherwise, the global context menu is shown.
+     * @param options.x - The X position in world (canvas) coordinates.
+     * @param options.y - The Y position in world (canvas) coordinates.
+     * @param options.objectId - Optional ID of an object to select and show the object context menu for.
+     */
+    open(options) {
+        const { x, y, objectId } = options;
+        if (this._core.store.state.activeTool?.toolType === 'selection') {
+            const selectionTool = this._core.store.state.activeTool;
+            selectionTool?.moveHandler?.cancelPendingDrag();
+        }
+        if (this._core.store.selectionBox) {
+            this._core.store.objects.remove(object => object instanceof KritzelSelectionBox);
+            this._core.store.setSelectionBox(null);
+            this._core.store.state.isSelecting = false;
+        }
+        if (objectId) {
+            const targetObject = this._core.store.allObjects.find(obj => obj.id === objectId);
+            if (targetObject && !(targetObject instanceof KritzelSelectionGroup) && !(targetObject instanceof KritzelSelectionBox)) {
+                const selectionGroup = KritzelSelectionGroup.create(this._core);
+                selectionGroup.addOrRemove(targetObject);
+                selectionGroup.isSelected = true;
+                selectionGroup.rotation = targetObject.rotation;
+                this._core.store.state.isSelecting = false;
+                const currentSelectionGroup = this._core.store.selectionGroup;
+                if (currentSelectionGroup) {
+                    this._core.removeSelectionGroup();
+                }
+                this._core.addSelectionGroup(selectionGroup);
+            }
+        }
+        this._core.store.state.contextMenuItems = this.getResolvedContextMenuItems();
+        this._core.store.state.contextMenuWorldX = x;
+        this._core.store.state.contextMenuWorldY = y;
+        const { translateX, translateY, scale } = this._core.store.state;
+        let screenX = x * scale + translateX;
+        let screenY = y * scale + translateY;
+        const menuWidthEstimate = 150;
+        const margin = 10;
+        if (screenX + menuWidthEstimate > this._core.store.state.viewportWidth - margin) {
+            screenX = this._core.store.state.viewportWidth - menuWidthEstimate - margin;
+        }
+        screenX = Math.max(margin, screenX);
+        screenY = Math.max(margin, screenY);
+        this._core.store.state.contextMenuX = screenX;
+        this._core.store.state.contextMenuY = screenY;
+        this._core.store.state.isContextMenuVisible = true;
+        this._core.store.state.isEnabled = false;
+        this._core.rerender();
+    }
+}

package/dist/collection/classes/handlers/hover.handler.js

@@ -0,0 +1,35 @@
+import { KritzelBaseHandler } from "./base.handler";
+/**
+ * Handles hover interactions on the Kritzel canvas.
+ * Detects when the pointer moves over canvas objects and updates their hover state accordingly.
+ * Currently only processes mouse input, with placeholder support for touch and pen devices.
+ */
+export class KritzelHoverHandler extends KritzelBaseHandler {
+    /**
+     * Creates a new instance of the hover handler.
+     * @param core - The KritzelCore instance that provides access to canvas state and object detection.
+     */
+    constructor(core) {
+        super(core);
+    }
+    /**
+     * Handles pointer move events to detect and update object hover states.
+     * For mouse input, performs a hit test on the object under the pointer and updates
+     * its `isHovered` property based on whether the pointer coordinates intersect with the object.
+     * Touch and pen input types are recognized but not yet implemented.
+     * @param event - The pointer event containing information about the pointer type and position.
+     * @returns void - This method does not return a value; it updates object state as a side effect.
+     */
+    handlePointerMove(event) {
+        if (event.pointerType === 'mouse') {
+            const hoveredObject = this._core.getObjectFromPointerEvent(event, '.object');
+            if (!hoveredObject)
+                return;
+            const x = this._core.store.state.pointerX;
+            const y = this._core.store.state.pointerY;
+            hoveredObject.isHovered = hoveredObject.hitTest(x, y);
+        }
+        if (event.pointerType === 'touch' || event.pointerType === 'pen') {
+        }
+    }
+}

package/dist/collection/classes/handlers/key.handler.js

@@ -0,0 +1,162 @@
+import { KritzelBaseHandler } from "./base.handler";
+/** The amount of pixels to move an object when using arrow key nudging. */
+const NUDGE_AMOUNT = 10;
+/**
+ * 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 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.
+     */
+    shortcuts = [
+        // General
+        {
+            key: 'Escape',
+            label: 'Clear Selection',
+            category: 'General',
+            condition: c => !!c.store.activeText || !!c.store.activeShape || !!c.store.selectionGroup,
+            action: c => {
+                if (c.store.activeText) {
+                    c.store.activeText.handleEscape();
+                    return;
+                }
+                if (c.store.activeShape) {
+                    c.store.activeShape.handleEscape();
+                    return;
+                }
+                c.clearSelection();
+            },
+        },
+        { key: 'Delete', label: 'Delete Selected', category: 'General', condition: c => !!c.store.selectionGroup, action: c => c.delete() },
+        { key: 'a', ctrl: true, label: 'Select All in Viewport', category: 'General', action: c => c.selectAllObjectsInViewport() },
+        { key: 'A', ctrl: true, shift: true, label: 'Select All Objects', category: 'General', action: c => c.selectAllObjects() },
+        // Undo/Redo
+        { key: 'z', ctrl: true, label: 'Undo', category: 'Undo/Redo', action: c => c.undo() },
+        { key: 'y', ctrl: true, label: 'Redo', category: 'Undo/Redo', action: c => c.redo() },
+        // Tool selection (Ctrl+1-9)
+        { key: '1', ctrl: true, label: 'Tool 1', category: 'Tool Selection', action: () => this.switchToolByIndex(0) },
+        { key: '2', ctrl: true, label: 'Tool 2', category: 'Tool Selection', action: () => this.switchToolByIndex(1) },
+        { key: '3', ctrl: true, label: 'Tool 3', category: 'Tool Selection', action: () => this.switchToolByIndex(2) },
+        { key: '4', ctrl: true, label: 'Tool 4', category: 'Tool Selection', action: () => this.switchToolByIndex(3) },
+        { key: '5', ctrl: true, label: 'Tool 5', category: 'Tool Selection', action: () => this.switchToolByIndex(4) },
+        { key: '6', ctrl: true, label: 'Tool 6', category: 'Tool Selection', action: () => this.switchToolByIndex(5) },
+        { key: '7', ctrl: true, label: 'Tool 7', category: 'Tool Selection', action: () => this.switchToolByIndex(6) },
+        { key: '8', ctrl: true, label: 'Tool 8', category: 'Tool Selection', action: () => this.switchToolByIndex(7) },
+        { key: '9', ctrl: true, label: 'Tool 9', category: 'Tool Selection', action: () => this.switchToolByIndex(8) },
+        // Object layering
+        { key: '+', ctrl: true, label: 'Bring Forward', category: 'Object Layering', condition: c => !!c.store.selectionGroup, action: c => c.bringForward() },
+        { key: '-', ctrl: true, label: 'Send Backward', category: 'Object Layering', condition: c => !!c.store.selectionGroup, action: c => c.sendBackward() },
+        { key: '*', shift: true, label: 'Bring to Front', category: 'Object Layering', condition: c => !!c.store.selectionGroup, action: c => c.bringToFront() },
+        { key: '_', shift: true, label: 'Send to Back', category: 'Object Layering', condition: c => !!c.store.selectionGroup, action: c => c.sendToBack() },
+        // Grouping
+        { key: 'g', ctrl: true, label: 'Group', category: 'Grouping', condition: c => !!c.store.selectionGroup && c.store.selectionGroup.objects.length >= 2, action: c => c.group() },
+        { key: 'G', ctrl: true, shift: true, label: 'Ungroup', category: 'Grouping', condition: c => !!c.store.selectionGroup, action: c => c.ungroup() },
+        // Movement
+        {
+            key: 'ArrowUp',
+            label: 'Move Object Up',
+            category: 'Movement',
+            condition: c => !!c.store.selectionGroup,
+            action: c => {
+                c.store.selectionGroup.move(0, 0, 0, NUDGE_AMOUNT);
+                c.rerender();
+            },
+        },
+        {
+            key: 'ArrowDown',
+            label: 'Move Object Down',
+            category: 'Movement',
+            condition: c => !!c.store.selectionGroup,
+            action: c => {
+                c.store.selectionGroup.move(0, NUDGE_AMOUNT, 0, 0);
+                c.rerender();
+            },
+        },
+        {
+            key: 'ArrowLeft',
+            label: 'Move Object Left',
+            category: 'Movement',
+            condition: c => !!c.store.selectionGroup,
+            action: c => {
+                c.store.selectionGroup.move(0, 0, NUDGE_AMOUNT, 0);
+                c.rerender();
+            },
+        },
+        {
+            key: 'ArrowRight',
+            label: 'Move Object Right',
+            category: 'Movement',
+            condition: c => !!c.store.selectionGroup,
+            action: c => {
+                c.store.selectionGroup.move(NUDGE_AMOUNT, 0, 0, 0);
+                c.rerender();
+            },
+        },
+    ];
+    /**
+     * Creates a new instance of the key handler.
+     * @param core - The KritzelCore instance that provides access to the canvas state and operations.
+     */
+    constructor(core) {
+        super(core);
+    }
+    /**
+     * 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.
+     */
+    switchToolByIndex(index) {
+        const toolInstance = this._core.toolRegistry.getToolByIndex(index);
+        if (toolInstance) {
+            this._core.store.setState('activeTool', toolInstance);
+            this._core.deselectAllObjects();
+            toolInstance.onActivate();
+        }
+    }
+    /**
+     * 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) {
+        this._core.store.state.isCtrlKeyPressed = event.ctrlKey;
+        // While a text or shape's text editor is being edited, let ProseMirror /
+        // the browser handle keys natively (Ctrl+A, Ctrl+C, arrows, etc.) instead
+        // of running global canvas shortcuts. Escape is the one exception — it
+        // still runs through the shortcut system so it can collapse the text
+        // selection (handled inside the shortcut's action).
+        if ((this._core.store.activeText || this._core.store.activeShape || this._core.store.activeInteractiveDynamicObject) && event.key !== 'Escape') {
+            return;
+        }
+        const shortcut = this.shortcuts.find(s => s.key === event.key && !!s.ctrl === event.ctrlKey && !!s.shift === event.shiftKey && (!s.condition || s.condition(this._core)));
+        if (shortcut) {
+            event.preventDefault();
+            shortcut.action(this._core);
+        }
+    }
+    /**
+     * Handles keyup events and updates the Ctrl key state.
+     * @param event - The keyboard event triggered by the user releasing a key.
+     */
+    handleKeyUp(event) {
+        this._core.store.state.isCtrlKeyPressed = event.ctrlKey;
+    }
+    /**
+     * 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() {
+        return this.shortcuts.map(({ key, ctrl, shift, label, category }) => ({
+            key,
+            ctrl,
+            shift,
+            label,
+            category,
+        }));
+    }
+}