@grafloria/element 0.3.17 → 0.3.19

package/src/libs/engine/src/layout/types.d.ts

@@ -0,0 +1,263 @@
+/**
+ * Layout algorithm types and interfaces
+ */
+import { Point, Size, Rectangle } from '../types';
+import { NodeModel } from '../models/NodeModel';
+/**
+ * Layout algorithm types
+ */
+export type LayoutAlgorithmType = 'grid' | 'force-directed' | 'hierarchical' | 'hybrid';
+/**
+ * Layout mode for automatic vs manual positioning
+ */
+export type LayoutMode = 'auto' | 'manual';
+/**
+ * Options for calculating node placement
+ */
+export interface PlacementOptions {
+    /**
+     * The node to place
+     */
+    node: NodeModel;
+    /**
+     * Current viewport dimensions
+     */
+    viewport: Rectangle;
+    /**
+     * Existing nodes in the diagram
+     */
+    existingNodes: NodeModel[];
+    /**
+     * Preferred position (optional hint)
+     */
+    preferredPosition?: Point;
+    /**
+     * Whether to respect manual positions of existing nodes
+     */
+    respectManualPositions?: boolean;
+    /**
+     * Spacing between nodes
+     */
+    spacing?: number;
+    /**
+     * Padding from viewport edges
+     */
+    padding?: number;
+}
+/**
+ * Result of placement calculation
+ */
+export interface PlacementResult {
+    /**
+     * Calculated position for the node
+     */
+    position: Point;
+    /**
+     * Whether placement was successful
+     */
+    success: boolean;
+    /**
+     * Metadata about the placement decision
+     */
+    metadata?: {
+        /**
+         * Grid position (for grid layouts)
+         */
+        gridPosition?: {
+            row: number;
+            column: number;
+        };
+        /**
+         * Pattern detected (for hybrid layouts)
+         */
+        detectedPattern?: 'grid' | 'tree' | 'freeform';
+        /**
+         * Reason for placement choice
+         */
+        reason?: string;
+        /**
+         * Number of attempts made (for iterative placement)
+         */
+        attempt?: number;
+        /**
+         * Allow additional metadata properties
+         */
+        [key: string]: any;
+    };
+}
+/**
+ * Configuration for layout algorithms
+ */
+export interface LayoutConfiguration {
+    /**
+     * Algorithm type (optional when passed to reLayout, as it uses current algorithm)
+     */
+    type?: LayoutAlgorithmType;
+    /**
+     * Algorithm-specific options
+     */
+    options?: GridLayoutOptions | ForceDirectedOptions | HierarchicalOptions | HybridOptions;
+    /**
+     * Whether to animate layout changes
+     */
+    animate?: boolean;
+    /**
+     * Animation duration in ms
+     */
+    animationDuration?: number;
+    /**
+     * Viewport for viewport-aware layout (Phase 0.5)
+     */
+    viewport?: Rectangle;
+    /**
+     * Margins around content (Phase 0.5)
+     */
+    margins?: number;
+    /**
+     * Shorthand for hierarchical direction (Phase 0.5)
+     */
+    direction?: 'TB' | 'BT' | 'LR' | 'RL';
+}
+/**
+ * Grid layout options
+ */
+export interface GridLayoutOptions {
+    /**
+     * Number of columns (auto-calculated if not specified)
+     */
+    columns?: number | 'auto';
+    /**
+     * Starting position
+     */
+    startPosition?: Point;
+    /**
+     * Horizontal spacing between nodes
+     */
+    horizontalSpacing?: number;
+    /**
+     * Vertical spacing between nodes
+     */
+    verticalSpacing?: number;
+    /**
+     * Node size for calculations (uses actual size if not specified)
+     */
+    nodeSize?: Size;
+    /**
+     * Alignment within grid cells
+     */
+    alignment?: 'start' | 'center' | 'end';
+    /**
+     * Direction of grid filling
+     */
+    direction?: 'row' | 'column';
+}
+/**
+ * Force-directed layout options (for future implementation)
+ */
+export interface ForceDirectedOptions {
+    /**
+     * Number of simulation iterations (default: 100)
+     */
+    iterations?: number;
+    /**
+     * Strength of repulsive force between nodes (default: 5000)
+     */
+    repulsionStrength?: number;
+    /**
+     * Strength of attraction between connected nodes (default: 0.01)
+     */
+    attractionStrength?: number;
+    /**
+     * Velocity damping factor (0-1, default: 0.9)
+     */
+    damping?: number;
+    /**
+     * Initial temperature for simulation (default: 100)
+     */
+    temperature?: number;
+    /**
+     * Cooling factor per iteration (default: 0.95)
+     */
+    coolingFactor?: number;
+    /**
+     * Minimum distance between nodes (default: 50)
+     */
+    minDistance?: number;
+    /**
+     * Maximum distance for force calculation (default: 500)
+     */
+    maxDistance?: number;
+    /**
+     * Center gravity strength (pulls towards center, default: 0.1)
+     */
+    centerGravity?: number;
+    /**
+     * Pin existing nodes (don't move them)
+     */
+    pinExistingNodes?: boolean;
+}
+/**
+ * Hierarchical layout options (for future implementation)
+ */
+export interface HierarchicalOptions {
+    /**
+     * Direction of hierarchy
+     */
+    direction?: 'TB' | 'BT' | 'LR' | 'RL';
+    /**
+     * Spacing between nodes in same rank
+     */
+    nodeSpacing?: number;
+    /**
+     * Spacing between ranks/levels
+     */
+    rankSpacing?: number;
+    /**
+     * Algorithm for rank assignment
+     */
+    rankAlgorithm?: 'longest-path' | 'coffman-graham';
+    /**
+     * Whether to minimize edge crossings
+     */
+    minimizeCrossings?: boolean;
+    /**
+     * Preserve mental map when re-layouting
+     */
+    preserveMentalMap?: boolean;
+}
+/**
+ * Hybrid layout options
+ */
+export interface HybridOptions {
+    /**
+     * Fallback algorithm if pattern detection fails or confidence is low
+     */
+    fallbackAlgorithm?: 'grid' | 'force-directed' | 'hierarchical';
+    /**
+     * Enable automatic algorithm switching based on pattern detection (default: true)
+     */
+    enableAutoSwitch?: boolean;
+    /**
+     * Confidence threshold for pattern detection (0-1, default: 0.7)
+     * If confidence is below this, fallback algorithm is used
+     */
+    analysisThreshold?: number;
+    /**
+     * Options for each sub-algorithm
+     */
+    gridOptions?: GridLayoutOptions;
+    forceDirectedOptions?: ForceDirectedOptions;
+    hierarchicalOptions?: HierarchicalOptions;
+}
+/**
+ * Layout event types
+ */
+export type LayoutEventType = 'layout:started' | 'layout:completed' | 'layout:failed' | 'layout:algorithm-changed' | 'layout:node-placed';
+/**
+ * Layout event data
+ */
+export interface DiagramLayoutEvent {
+    type: LayoutEventType;
+    algorithmType: LayoutAlgorithmType;
+    data?: any;
+}

package/src/libs/engine/src/layout/types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Layout algorithm types and interfaces
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/src/libs/engine/src/layout/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../../engine/src/layout/types.ts"],"names":[],"mappings":";AAAA;;GAEG"}

package/src/libs/engine/src/lib/performance/mobile-performance.service.d.ts

@@ -0,0 +1,43 @@
+export interface MobilePerformanceConfig {
+    enableThrottling: boolean;
+    touchMoveThrottle: number;
+    reducedRendering: boolean;
+    maxVisibleNodes: number;
+    lowPowerMode: boolean;
+}
+export declare class MobilePerformanceService {
+    private config;
+    private throttleTimers;
+    /**
+     * Detect if running on mobile device
+     */
+    static isMobileDevice(): boolean;
+    /**
+     * Detect if low-power device
+     */
+    static isLowPowerDevice(): boolean;
+    /**
+     * Initialize with auto-detection
+     */
+    initialize(customConfig?: Partial<MobilePerformanceConfig>): void;
+    /**
+     * Throttle function execution
+     */
+    throttle<T extends (...args: any[]) => any>(key: string, fn: T, wait?: number): (...args: Parameters<T>) => void;
+    /**
+     * Get recommended render quality based on device
+     */
+    getRenderQuality(): 'high' | 'medium' | 'low';
+    /**
+     * Should skip rendering based on performance config
+     */
+    shouldSkipRender(nodeCount: number): boolean;
+    /**
+     * Get configuration
+     */
+    getConfig(): MobilePerformanceConfig;
+    /**
+     * Update configuration
+     */
+    updateConfig(config: Partial<MobilePerformanceConfig>): void;
+}

package/src/libs/engine/src/lib/performance/mobile-performance.service.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MobilePerformanceService = void 0;
+class MobilePerformanceService {
+    constructor() {
+        this.config = {
+            enableThrottling: true,
+            touchMoveThrottle: 16, // ~60 FPS
+            reducedRendering: false,
+            maxVisibleNodes: 500,
+            lowPowerMode: false,
+        };
+        this.throttleTimers = new Map();
+    }
+    /**
+     * Detect if running on mobile device
+     */
+    static isMobileDevice() {
+        return /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent) || ('ontouchstart' in window) || (navigator.maxTouchPoints > 0);
+    }
+    /**
+     * Detect if low-power device
+     */
+    static isLowPowerDevice() {
+        // Check hardware concurrency (CPU cores)
+        const cores = navigator.hardwareConcurrency || 4;
+        // Check device memory (if available)
+        const memory = navigator.deviceMemory || 4;
+        return cores <= 2 || memory <= 2;
+    }
+    /**
+     * Initialize with auto-detection
+     */
+    initialize(customConfig) {
+        if (MobilePerformanceService.isMobileDevice()) {
+            this.config.enableThrottling = true;
+            if (MobilePerformanceService.isLowPowerDevice()) {
+                this.config.lowPowerMode = true;
+                this.config.reducedRendering = true;
+                this.config.maxVisibleNodes = 200;
+            }
+        }
+        if (customConfig) {
+            this.config = Object.assign(Object.assign({}, this.config), customConfig);
+        }
+    }
+    /**
+     * Throttle function execution
+     */
+    throttle(key, fn, wait = this.config.touchMoveThrottle) {
+        return (...args) => {
+            const now = Date.now();
+            const lastRun = this.throttleTimers.get(key) || 0;
+            if (now - lastRun >= wait) {
+                fn(...args);
+                this.throttleTimers.set(key, now);
+            }
+        };
+    }
+    /**
+     * Get recommended render quality based on device
+     */
+    getRenderQuality() {
+        if (this.config.lowPowerMode) {
+            return 'low';
+        }
+        if (this.config.reducedRendering) {
+            return 'medium';
+        }
+        return 'high';
+    }
+    /**
+     * Should skip rendering based on performance config
+     */
+    shouldSkipRender(nodeCount) {
+        if (!this.config.reducedRendering) {
+            return false;
+        }
+        return nodeCount > this.config.maxVisibleNodes;
+    }
+    /**
+     * Get configuration
+     */
+    getConfig() {
+        return Object.assign({}, this.config);
+    }
+    /**
+     * Update configuration
+     */
+    updateConfig(config) {
+        this.config = Object.assign(Object.assign({}, this.config), config);
+    }
+}
+exports.MobilePerformanceService = MobilePerformanceService;
+//# sourceMappingURL=mobile-performance.service.js.map

package/src/libs/engine/src/lib/performance/mobile-performance.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mobile-performance.service.js","sourceRoot":"","sources":["../../../../../../../engine/src/lib/performance/mobile-performance.service.ts"],"names":[],"mappings":"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"}

package/src/libs/engine/src/models/DiagramEntity.d.ts

@@ -0,0 +1,174 @@
+import { EventEmitter } from 'eventemitter3';
+import { SerializedEntity } from '../types';
+export interface ChangeEntry {
+    timestamp: number;
+    property: string;
+    oldValue: any;
+    newValue: any;
+}
+/** Read the current mutation epoch. Cheap enough to call every frame. */
+export declare function getMutationEpoch(): number;
+/**
+ * Bump the epoch by hand, for a mutation that legitimately bypasses
+ * `markDirty()` (in-place `points` rewrites, say). Prefer `markDirty()`.
+ */
+export declare function bumpMutationEpoch(): number;
+export declare abstract class DiagramEntity {
+    readonly id: string;
+    readonly uuid: string;
+    version: number;
+    metadata: Map<string, any>;
+    protected emitter: EventEmitter;
+    protected changeLog: ChangeEntry[];
+    protected maxChangeLogSize: number;
+    private _isDirty;
+    private _dirtyTimestamp;
+    private _dirtyReasons;
+    private _batchDepth;
+    private _batchHadChanges;
+    private _disposed;
+    constructor(id?: string, uuid?: string);
+    /**
+     * Check if entity has been modified since last render (Phase 5.2)
+     */
+    get isDirty(): boolean;
+    /**
+     * Mark entity as dirty (needs re-render) (Phase 5.2)
+     */
+    markDirty(reason?: string): void;
+    /**
+     * Mark entity as clean (rendered) (Phase 5.2)
+     */
+    markClean(): void;
+    /**
+     * Get reasons why entity is dirty (Phase 5.2)
+     */
+    getDirtyReasons(): string[];
+    /**
+     * Get timestamp when entity was marked dirty (Phase 5.2)
+     */
+    getDirtyTimestamp(): number | null;
+    /**
+     * Begin batch update (Phase 5.2)
+     * Delays dirty marking until batch ends
+     */
+    beginBatch(): void;
+    /**
+     * End batch update (Phase 5.2)
+     * Marks dirty once if any changes occurred
+     */
+    endBatch(): void;
+    /**
+     * Check if currently in batch mode
+     */
+    isBatching(): boolean;
+    /**
+     * Restore persisted identity onto a freshly-constructed entity during
+     * deserialization. A load must reproduce the SAVED identity (uuid) and
+     * mutation counter (version) rather than mint new ones — otherwise
+     * save/load is lossy and anything anchored to uuids (ops, comments,
+     * collaboration) breaks across a round-trip. `uuid` is readonly at the
+     * type level; this is the one sanctioned place it is written after
+     * construction.
+     */
+    protected restoreIdentity(data: {
+        uuid?: string;
+        version?: number;
+    }): void;
+    /**
+     * Track property changes for undo/redo and events
+     */
+    protected trackChange(property: string, oldValue: any, newValue: any): void;
+    /**
+     * REPORT A REGISTER WRITE THE COLLAB REDUCER JUST PERFORMED.
+     *
+     * `trackChange()` is `protected`, and `applyOp` lives outside the class — so every
+     * register the reducer wrote by plain field assignment (anything with no dedicated
+     * mutator: a link's `style`, `flexConfig`, a group's `isCollapsed`, `layoutConfig`,
+     * `bounds`, `parentId`, …) mutated the model WITHOUT passing the funnel.
+     *
+     * That is not a cosmetic gap. `UndoStack.undo()` applies the inverse THROUGH THE MODEL
+     * WITH CAPTURE LIVE and then reads back whatever capture minted. No trackChange means
+     * no op, which means THE UNDO REACHES NOBODY. Measured before this existed:
+     *
+     *     link style   execute → 1 op   undo → 0 ops
+     *     flexConfig   execute → 1 op   undo → 0 ops
+     *     isCollapsed  execute → 1 op   undo → 0 ops
+     *     position     execute → 1 op   undo → 1 op   ← a real mutator: always worked
+     *
+     * The author's own document was correct every time — which is exactly why this
+     * survived. It is the `UpdateLinkStyleCommand` defect (see style-undo.spec.ts) living
+     * one layer down, in the reducer, and hitting every mutator-less register at once.
+     *
+     * So the reducer gets a seam onto the funnel rather than a copy of it. There is still
+     * ONE funnel; this is a door onto it, not a second source of truth.
+     */
+    reportRegisterWrite(property: string, oldValue: unknown, newValue: unknown): void;
+    /**
+     * Subscribe to changes
+     */
+    on(event: string, handler: Function): () => void;
+    /**
+     * Subscribe to property changes
+     */
+    onPropertyChange(property: string, handler: (data: any) => void): () => void;
+    /**
+     * Get change history
+     */
+    getChangeLog(): ReadonlyArray<ChangeEntry>;
+    /**
+     * Clear change history
+     */
+    clearChangeLog(): void;
+    /**
+     * CANONICAL label read. `metadata.label` wins; legacy `data['label']` (on
+     * subclasses that carry a data bag) is honoured as a fallback so pre-canon
+     * documents and third-party writers still surface their labels everywhere —
+     * rendering, a11y names, and Mermaid export alike.
+     */
+    getLabel(): string | undefined;
+    /**
+     * CANONICAL label write. Writes `metadata.label` (tracked → dirty → repaint)
+     * and mirrors into the legacy `data['label']` slot when the entity has a
+     * data bag, so any reader still on the old field sees the same value. The
+     * mirror is a shadow: metadata is authoritative on every read path.
+     */
+    setLabel(label: string): void;
+    /**
+     * Set metadata value
+     */
+    setMetadata(key: string, value: any): void;
+    /**
+     * Get metadata value
+     */
+    getMetadata(key: string): any;
+    /**
+     * Remove metadata
+     */
+    deleteMetadata(key: string): void;
+    /**
+     * Clone a value for change tracking
+     */
+    protected cloneValue(value: any): any;
+    /**
+     * Serialize entity to JSON
+     */
+    abstract serialize(): SerializedEntity;
+    /**
+     * Check if entity has been disposed (Phase 5.4)
+     */
+    isDisposed(): boolean;
+    /**
+     * Check if entity is not disposed and throw if it is (Phase 5.4)
+     */
+    protected assertNotDisposed(): void;
+    /**
+     * Dispose entity and clean up resources (Phase 5.4)
+     * Prevents memory leaks by:
+     * - Removing all event listeners
+     * - Clearing change log
+     * - Clearing metadata
+     * - Marking as disposed
+     */
+    dispose(): void;
+}