@flowscape-ui/core-sdk 1.0.5 → 1.0.7

package/dist/index.d.cts

@@ -346,6 +346,7 @@ interface BaseNodeOptions {
     y?: number;
     width?: number;
     height?: number;
+    rotation?: number;
 }
 declare abstract class BaseNode<T extends Konva.Node = Konva.Node> implements NodeHandle<T> {
     protected konvaNode: T;
@@ -445,6 +446,12 @@ interface CoreEvents {
     'plugin:added': [pluginName: string];
     /** Plugin was removed */
     'plugin:removed': [pluginName: string];
+    /** Persistence restore failed */
+    'persistence:restore:error': [{
+        error: string;
+    }];
+    /** Persistence restore completed */
+    'persistence:restore:done': [];
     /** Stage was resized */
     'stage:resized': [{
         width: number;
@@ -526,6 +533,36 @@ interface EllipseNodeOptions extends BaseNodeOptions {
     strokeWidth?: number;
 }
 
+interface FrameOptions {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    background?: string;
+    label?: string;
+    labelColor?: string;
+    labelHoverColor?: string;
+    template?: string;
+    draggable?: boolean;
+    id?: string;
+    name?: string;
+}
+
+type FrameNodeOptions = FrameOptions & BaseNodeOptions;
+declare class FrameNode extends BaseNode<Konva.Group> {
+    private _rect;
+    private _contentGroup;
+    private _container;
+    constructor(options: FrameNodeOptions);
+    getRect(): Konva.Rect;
+    getContentGroup(): Konva.Group;
+    /**
+     * Resize visual frame area without affecting child nodes.
+     * Updates rect size and clipping container.
+     */
+    resize(width: number, height: number): void;
+}
+
 interface MediaPlaceholderOptions {
     text: string;
     textColor: string;
@@ -895,9 +932,12 @@ declare class NodeManager {
     private _nodes;
     private _stage;
     private _eventBus;
+    private _frameLabels;
+    private _selectedFrame;
     private _batchDrawScheduled;
     private _listCache;
     private _listCacheInvalidated;
+    private _hadFrameInLastMultiSelection;
     constructor(stage: Konva.Stage, eventBus: EventBus<CoreEvents>);
     get layer(): Konva.Layer;
     get world(): Konva.Group;
@@ -917,6 +957,7 @@ declare class NodeManager {
     addSvg(options: SvgNodeOptions): SvgNodeHandle;
     addVideo(options: VideoNodeOptions): VideoNodeHandle;
     addGif(options: GifNodeOptions): GifNodeHandle;
+    addFrame(options: FrameNodeOptions): FrameNode;
     remove(node: BaseNode): void;
     findById(id: string): BaseNode | undefined;
     list(): BaseNode[];
@@ -925,6 +966,14 @@ declare class NodeManager {
      * CRITICAL OPTIMIZATION: group multiple node additions
      */
     private _scheduleBatchDraw;
+    private _listFrames;
+    private _attachFrameAutogroupHandlers;
+    /**
+     * Обновить позицию overlay label над соответствующими фреймами
+     * (используется при создании и drag фреймов)
+     */
+    private _updateFrameLabelsPosition;
+    private _enforceFrameDraggableInvariant;
 }
 
 interface LODLevel {
@@ -1265,6 +1314,10 @@ declare class CoreEngine {
      * Enable or disable auto-resize
      */
     setAutoResize(enabled: boolean): void;
+    /**
+     * Show the canvas container after persistence restore completes
+     */
+    showContainer(): void;
 }
 
 /**
@@ -1397,6 +1450,8 @@ declare class AreaSelectionPlugin extends Plugin {
     constructor(options?: AreaSelectionPluginOptions);
     protected onAttach(core: CoreEngine): void;
     protected onDetach(core: CoreEngine): void;
+    /** Проверить, что прямоугольник `inner` полностью содержится внутри `outer`. */
+    private _rectContains;
     private _startAutoPanLoop;
     private _stopAutoPanLoop;
     private _finalizeArea;
@@ -1737,6 +1792,198 @@ declare class NodeHotkeysPlugin extends Plugin {
     private _syncGroupZIndex;
 }
 
+/**
+ * IndexedDB storage service for canvas persistence.
+ * Handles storage of canvas state and blob files (images, videos, etc.)
+ */
+interface StoredCanvasState {
+    id: string;
+    state: string;
+    updatedAt: number;
+}
+interface StoredBlob {
+    id: string;
+    blob: Blob;
+    mimeType: string;
+    originalUrl?: string | undefined;
+}
+declare class PersistenceStorage {
+    private _dbName;
+    private _db;
+    private _dbPromise;
+    constructor(_dbName?: string);
+    /**
+     * Initialize IndexedDB connection
+     */
+    init(): Promise<void>;
+    private _openDatabase;
+    private _getDb;
+    /**
+     * Save canvas state to IndexedDB
+     */
+    saveCanvasState(id: string, state: string): Promise<void>;
+    /**
+     * Load canvas state from IndexedDB
+     */
+    loadCanvasState(id: string): Promise<StoredCanvasState | null>;
+    /**
+     * Delete canvas state from IndexedDB
+     */
+    deleteCanvasState(id: string): Promise<void>;
+    /**
+     * List all canvas states
+     */
+    listCanvasStates(): Promise<StoredCanvasState[]>;
+    /**
+     * Save blob to IndexedDB
+     */
+    saveBlob(id: string, blob: Blob, originalUrl?: string): Promise<void>;
+    /**
+     * Load blob from IndexedDB
+     */
+    loadBlob(id: string): Promise<StoredBlob | null>;
+    /**
+     * Delete blob from IndexedDB
+     */
+    deleteBlob(id: string): Promise<void>;
+    /**
+     * Load multiple blobs by IDs
+     */
+    loadBlobs(ids: string[]): Promise<Map<string, StoredBlob>>;
+    /**
+     * Save multiple blobs
+     */
+    saveBlobs(blobs: Map<string, {
+        blob: Blob;
+        originalUrl?: string;
+    }>): Promise<void>;
+    /**
+     * List all blob IDs
+     */
+    listBlobIds(): Promise<string[]>;
+    /**
+     * Clear all blobs not referenced in the given set
+     */
+    cleanupUnusedBlobs(usedBlobIds: Set<string>): Promise<number>;
+    /**
+     * Clear all data (canvas states and blobs)
+     */
+    clearAll(): Promise<void>;
+    /**
+     * Close database connection
+     */
+    close(): void;
+    /**
+     * Delete the entire database
+     */
+    deleteDatabase(): Promise<void>;
+}
+
+/**
+ * PersistencePlugin - Auto-saves canvas state to IndexedDB on any change.
+ * Restores state on page reload. Supports export/import to JSON with embedded blobs.
+ */
+
+interface PersistencePluginOptions {
+    /** Unique ID for this canvas (default: 'default') */
+    canvasId?: string;
+    /** Debounce delay in ms before saving (default: 300) */
+    debounceMs?: number;
+    /** Auto-restore on attach (default: true) */
+    autoRestore?: boolean;
+    /** Custom IndexedDB database name */
+    dbName?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+declare class PersistencePlugin extends Plugin {
+    private _core;
+    private _storage;
+    private _canvasId;
+    private _debounceMs;
+    private _autoRestore;
+    private _debug;
+    private _saveTimer;
+    private _isRestoring;
+    private _blobUrls;
+    private _initialized;
+    /** Maps original blob URLs to stored blob IDs */
+    private _blobUrlToId;
+    constructor(options?: PersistencePluginOptions);
+    protected onAttach(core: CoreEngine): void;
+    protected onDetach(core: CoreEngine): void;
+    private _initialize;
+    private _subscribeToEvents;
+    private _unsubscribeFromEvents;
+    private _onNodeCreated;
+    private _onNodeChange;
+    private _onClipboardPaste;
+    /**
+     * Capture blob data from a media node if it has a blob URL
+     */
+    private _captureBlobFromNode;
+    private _onNodeTransformed;
+    private _onCameraChange;
+    private _onKonvaDragEnd;
+    private _onKonvaTransformEnd;
+    private _onTextChange;
+    /**
+     * Subscribe to textChange events for all existing TextNodes
+     */
+    private _subscribeToTextNodes;
+    private _scheduleSave;
+    private _cancelPendingSave;
+    /**
+     * Save current canvas state to IndexedDB
+     */
+    save(): Promise<void>;
+    /**
+     * Restore canvas state from IndexedDB
+     */
+    restore(): Promise<boolean>;
+    /**
+     * Clear saved state from IndexedDB
+     */
+    clear(): Promise<void>;
+    /**
+     * Export canvas to JSON string with embedded blobs
+     */
+    exportToJSON(): Promise<string>;
+    /**
+     * Import canvas from JSON string with embedded blobs
+     */
+    importFromJSON(json: string): void;
+    /**
+     * Download canvas as JSON file
+     */
+    downloadJSON(filename?: string): Promise<void>;
+    /**
+     * Upload and import canvas from JSON file
+     */
+    uploadJSON(): Promise<void>;
+    /**
+     * Check if there is saved state
+     */
+    hasSavedState(): Promise<boolean>;
+    /**
+     * Get storage instance for advanced usage
+     */
+    getStorage(): PersistenceStorage;
+    /**
+     * Get canvas ID
+     */
+    getCanvasId(): string;
+    /**
+     * Set canvas ID (will trigger restore if autoRestore is enabled)
+     */
+    setCanvasId(id: string): Promise<void>;
+    private _log;
+    /**
+     * Capture blob URLs from all nodes that haven't been captured yet
+     */
+    private _captureAllBlobUrls;
+}
+
 interface RulerGuidesPluginOptions {
     guideColor?: string;
     activeColor?: string;
@@ -2155,6 +2402,10 @@ declare class SelectionPlugin extends Plugin {
     private _prevStageDraggableBeforeRotate;
     private _worldSyncRafId;
     private _onCameraZoomEvent;
+    private _onFrameChildrenChangedBound;
+    private _onFrameLabelClickedBound;
+    private _onFrameLabelDragStartBound;
+    private _onFrameLabelDragEndBound;
     private _hoverTr;
     private _isPointerDown;
     private _autoPanRafId;
@@ -2171,6 +2422,13 @@ declare class SelectionPlugin extends Plugin {
     private _tempMultiInitialTransforms;
     private _tempMultiGroup;
     private _tempOverlay;
+    /**
+     * Public readonly access to the currently selected BaseNode
+     * (or null if there is no selection). Mutable selection logic
+     * still lives inside SelectionPlugin; this method is used only
+     * for safe inspection from other plugins.
+     */
+    getSelected(): BaseNode | null;
     getMultiGroupController(): MultiGroupController;
     private _multiCtrl;
     private _startAutoPanLoop;
@@ -2188,6 +2446,18 @@ declare class SelectionPlugin extends Plugin {
     private _uiUpdateDebounce;
     constructor(options?: SelectionPluginOptions);
     setOptions(patch: Partial<SelectionPluginOptions>): void;
+    /**
+     * Select a single node from area (lasso) selection, without creating temp-multi.
+     * Used by AreaSelectionPlugin so that single-node selection (including FrameNode)
+     * reuses the same transformer and resize logic as обычный клик.
+     */
+    selectSingleFromArea(node: BaseNode): void;
+    /**
+     * Clear current selection (single + temp-multi) when starting lasso
+     * in special cases (e.g. inside FrameNode background) to mirror
+     * behavior of clicking on empty space in world.
+     */
+    clearSelectionFromAreaLasso(): void;
     protected onAttach(core: CoreEngine): void;
     protected onDetach(core: CoreEngine): void;
     private _onMouseDown;
@@ -2213,10 +2483,26 @@ declare class SelectionPlugin extends Plugin {
     private _ensureTempMulti;
     private _destroyTempMultiOverlayOnly;
     private _destroyTempMulti;
+    /**
+     * FRAME-SPECIFIC: автогруппировка для временной multi-группы.
+     * Для каждой ноды из tempMultiSet повторяет логику
+     * NodeManager._attachFrameAutogroupHandlers:
+     * - если нода была внутри FrameNode и вышла за его пределы, возвращаем её в world;
+     * - если нода была в world и её центр оказался внутри фрейма, переносим в contentGroup.
+     * Поведение вне FrameNode остаётся без изменений.
+     */
+    private _autogroupTempMultiInFrames;
     private _commitTempMultiToGroup;
     private _tryUngroupSelectedGroup;
     private _ensureHoverTr;
     private _destroyHoverTr;
+    /**
+     * Frame-specific selectability rules for direct clicks/hover:
+     * - If the owning BaseNode is a FrameNode and it has at least one child inside contentGroup,
+     *   the frame is not directly selectable/hoverable (selection only via lasso).
+     * - Empty frames and all other nodes remain selectable.
+     */
+    private _isSelectableByFrameRules;
     private _onHoverMoveThrottled;
     private _onHoverMove;
     private _onHoverDown;
@@ -2382,6 +2668,53 @@ declare class TextAutoTrimAddon extends NodeAddon<TextNode> {
     private normalize;
 }
 
+/**
+ * Canvas serialization/deserialization utility.
+ * Handles conversion of canvas state to/from JSON format with blob extraction.
+ */
+
+interface SerializedNode {
+    id: string;
+    type: string;
+    attrs: Record<string, unknown>;
+    zIndex: number;
+    blobId?: string;
+    children?: SerializedNode[];
+    parentFrameId?: string;
+}
+interface SerializedCamera {
+    x: number;
+    y: number;
+    scale: number;
+}
+interface SerializedCanvas {
+    version: number;
+    timestamp: number;
+    nodes: SerializedNode[];
+    camera: SerializedCamera;
+    blobIds: string[];
+}
+interface ExtractedBlob {
+    id: string;
+    blob: Blob;
+    originalUrl: string;
+}
+interface DeserializeOptions {
+    blobUrls?: Map<string, string>;
+    clearExisting?: boolean;
+}
+interface SerializeOptions {
+    /** Pre-existing mapping of blob URLs to blob IDs (from captured blobs) */
+    blobUrlToId?: Map<string, string>;
+}
+declare function serializeCanvas(core: CoreEngine, options?: SerializeOptions): SerializedCanvas;
+declare function extractBlobs(core: CoreEngine): Promise<Map<string, ExtractedBlob>>;
+declare function deserializeCanvas(core: CoreEngine, state: SerializedCanvas, options?: DeserializeOptions): void;
+declare function exportCanvasToJSON(core: CoreEngine): Promise<string>;
+declare function importCanvasFromJSON(core: CoreEngine, json: string, options?: Omit<DeserializeOptions, 'blobUrls'>): void;
+declare function createBlobUrlMap(state: SerializedCanvas, storedBlobs: Map<string, Blob>): Map<string, string>;
+declare function revokeBlobUrls(blobUrls: Map<string, string>): void;
+
 /**
  * DebounceHelper - utility for debouncing (delayed execution)
  *
@@ -2463,4 +2796,13 @@ declare class ThrottleHelper {
     getThrottle(): number;
 }
 
-export { type ArcNodeHandle, type ArcNodeOptions, AreaSelectionPlugin, type AreaSelectionPluginOptions, type ArrowNodeHandle, type ArrowNodeOptions, type BaseNodeOptions, type CameraHotkeysOptions, CameraHotkeysPlugin, CameraManager, type CircleNodeHandle, type CircleNodeOptions, ContentFromClipboardPlugin, type ContentFromClipboardPluginOptions, CoreEngine, type CoreEngineOptions, type CoreEvents, DebounceHelper, type EllipseNodeHandle, type EllipseNodeOptions, EventBus, type GifNodeHandle, type GifNodeOptions, GridPlugin, type GridPluginOptions, type GroupNodeHandle, type GroupNodeOptions, type HistoryAction, HistoryManager, HistoryPlugin, type HistoryPluginOptions, ImageHoverFilterAddon, type ImageNodeHandle, type ImageNodeOptions, type ImageSource, type KonvaArc, type KonvaArrow, type KonvaCircle, type KonvaEllipse, type KonvaGroup, type KonvaGroupConfig, type KonvaImage, type KonvaLayer, type KonvaNode, type KonvaNodeConfig, type KonvaRegularPolygon, type KonvaRing, type KonvaShape, type KonvaStage, type KonvaStar, type KonvaText, type LogoOptions, LogoPlugin, MediaPlaceholder, type MediaPlaceholderOptions, NodeAddon, NodeAddons, type NodeAddonsHandle, type NodeHandle, type NodeHotkeysOptions, NodeHotkeysPlugin, NodeManager, PluginAddon, Plugins, type RegularPolygonNodeHandle, type RegularPolygonNodeOptions, type RingNodeHandle, type RingNodeOptions, RulerGuidesAddon, RulerGuidesPlugin, type RulerGuidesPluginOptions, RulerHighlightAddon, RulerHighlightPlugin, type RulerHighlightPluginOptions, RulerManagerAddon, RulerManagerPlugin, type RulerManagerPluginOptions, RulerPlugin, type RulerPluginOptions, SelectionPlugin, type SelectionPluginOptions, ShapeHoverHighlightAddon, type ShapeNodeHandle, type ShapeNodeOptions, type StarNodeHandle, type StarNodeOptions, type SvgNodeHandle, type SvgNodeOptions, TextAutoTrimAddon, type TextNodeHandle, type TextNodeOptions, ThrottleHelper, type VideoNodeHandle, type VideoNodeOptions, VideoOverlayAddon, type VideoOverlayAddonOptions, VisualGuidesPlugin, type VisualGuidesPluginOptions };
+declare const frameTemplates: {
+    readonly desktopFrame: {
+        width: number;
+        height: number;
+        template: string;
+        label: string;
+    };
+};
+
+export { type ArcNodeHandle, type ArcNodeOptions, AreaSelectionPlugin, type AreaSelectionPluginOptions, type ArrowNodeHandle, type ArrowNodeOptions, type BaseNodeOptions, type CameraHotkeysOptions, CameraHotkeysPlugin, CameraManager, type CircleNodeHandle, type CircleNodeOptions, ContentFromClipboardPlugin, type ContentFromClipboardPluginOptions, CoreEngine, type CoreEngineOptions, type CoreEvents, DebounceHelper, type DeserializeOptions, type EllipseNodeHandle, type EllipseNodeOptions, EventBus, type ExtractedBlob, FrameNode, type FrameNodeOptions, type FrameOptions, type GifNodeHandle, type GifNodeOptions, GridPlugin, type GridPluginOptions, type GroupNodeHandle, type GroupNodeOptions, type HistoryAction, HistoryManager, HistoryPlugin, type HistoryPluginOptions, ImageHoverFilterAddon, type ImageNodeHandle, type ImageNodeOptions, type ImageSource, type KonvaArc, type KonvaArrow, type KonvaCircle, type KonvaEllipse, type KonvaGroup, type KonvaGroupConfig, type KonvaImage, type KonvaLayer, type KonvaNode, type KonvaNodeConfig, type KonvaRegularPolygon, type KonvaRing, type KonvaShape, type KonvaStage, type KonvaStar, type KonvaText, type LogoOptions, LogoPlugin, MediaPlaceholder, type MediaPlaceholderOptions, NodeAddon, NodeAddons, type NodeAddonsHandle, type NodeHandle, type NodeHotkeysOptions, NodeHotkeysPlugin, NodeManager, PersistencePlugin, type PersistencePluginOptions, PersistenceStorage, PluginAddon, Plugins, type RegularPolygonNodeHandle, type RegularPolygonNodeOptions, type RingNodeHandle, type RingNodeOptions, RulerGuidesAddon, RulerGuidesPlugin, type RulerGuidesPluginOptions, RulerHighlightAddon, RulerHighlightPlugin, type RulerHighlightPluginOptions, RulerManagerAddon, RulerManagerPlugin, type RulerManagerPluginOptions, RulerPlugin, type RulerPluginOptions, SelectionPlugin, type SelectionPluginOptions, type SerializeOptions, type SerializedCamera, type SerializedCanvas, type SerializedNode, ShapeHoverHighlightAddon, type ShapeNodeHandle, type ShapeNodeOptions, type StarNodeHandle, type StarNodeOptions, type StoredBlob, type StoredCanvasState, type SvgNodeHandle, type SvgNodeOptions, TextAutoTrimAddon, type TextNodeHandle, type TextNodeOptions, ThrottleHelper, type VideoNodeHandle, type VideoNodeOptions, VideoOverlayAddon, type VideoOverlayAddonOptions, VisualGuidesPlugin, type VisualGuidesPluginOptions, createBlobUrlMap, deserializeCanvas, exportCanvasToJSON, extractBlobs, frameTemplates, importCanvasFromJSON, revokeBlobUrls, serializeCanvas };