@grafloria/element 0.3.17 → 0.3.19

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

@@ -0,0 +1,120 @@
+/**
+ * Interface for layout algorithms
+ *
+ * All layout algorithms must implement this interface to be used by the LayoutManager.
+ * This provides a consistent API for different layout strategies.
+ */
+import { DiagramModel } from '../models/DiagramModel';
+import { NodeModel } from '../models/NodeModel';
+import { Point } from '../types';
+import { PlacementOptions, PlacementResult, LayoutConfiguration } from './types';
+export interface ILayoutAlgorithm {
+    /**
+     * Get the name of the layout algorithm
+     */
+    getName(): string;
+    /**
+     * Get the type of the layout algorithm
+     */
+    getType(): 'grid' | 'force-directed' | 'hierarchical' | 'hybrid';
+    /**
+     * Calculate position for a single new node
+     *
+     * This is called when a node is added to the diagram.
+     * The algorithm should return a position that:
+     * - Doesn't overlap with existing nodes
+     * - Follows the layout strategy
+     * - Fits within the viewport (or is close to existing content)
+     *
+     * @param options - Placement options
+     * @returns Placement result with position and metadata
+     */
+    calculatePlacement(options: PlacementOptions): PlacementResult;
+    /**
+     * Re-layout all nodes in the diagram
+     *
+     * This is called when the user explicitly requests a re-layout (e.g., clicks "Re-Arrange" button).
+     * The algorithm should calculate new positions for ALL nodes.
+     *
+     * @param diagram - The diagram to layout
+     * @param config - Layout configuration
+     * @returns Map of node IDs to new positions
+     */
+    reLayout(diagram: DiagramModel, config?: LayoutConfiguration): Map<string, Point>;
+    /**
+     * Configure the layout algorithm
+     *
+     * @param config - Configuration options
+     */
+    configure(config: LayoutConfiguration): void;
+    /**
+     * Get current configuration
+     *
+     * @returns Current configuration
+     */
+    getConfiguration(): LayoutConfiguration;
+    /**
+     * Validate if this algorithm can be applied to the given diagram
+     *
+     * For example:
+     * - Hierarchical layout requires a DAG (no cycles)
+     * - Force-directed works better with connected nodes
+     *
+     * @param diagram - The diagram to validate
+     * @returns true if algorithm can be applied, false with reason if not
+     */
+    canApply(diagram: DiagramModel): {
+        valid: boolean;
+        reason?: string;
+    };
+    /**
+     * Called when the algorithm is activated
+     * Use this to initialize any state or caches
+     */
+    onActivate?(): void;
+    /**
+     * Called when the algorithm is deactivated
+     * Use this to clean up state or caches
+     */
+    onDeactivate?(): void;
+}
+/**
+ * Base abstract class for layout algorithms
+ *
+ * Provides common functionality that all layout algorithms can use.
+ * Extend this class when implementing a new layout algorithm.
+ */
+export declare abstract class BaseLayoutAlgorithm implements ILayoutAlgorithm {
+    protected config: LayoutConfiguration;
+    constructor(config?: LayoutConfiguration);
+    abstract getName(): string;
+    abstract getType(): 'grid' | 'force-directed' | 'hierarchical' | 'hybrid';
+    abstract calculatePlacement(options: PlacementOptions): PlacementResult;
+    abstract reLayout(diagram: DiagramModel, config?: LayoutConfiguration): Map<string, Point>;
+    configure(config: LayoutConfiguration): void;
+    getConfiguration(): LayoutConfiguration;
+    canApply(diagram: DiagramModel): {
+        valid: boolean;
+        reason?: string;
+    };
+    /**
+     * Utility: Check if a position would collide with existing nodes
+     */
+    protected hasCollision(position: Point, size: {
+        width: number;
+        height: number;
+    }, existingNodes: NodeModel[], spacing?: number): boolean;
+    /**
+     * Utility: Check if two bounding boxes intersect
+     */
+    protected boundsIntersect(box1: any, box2: any): boolean;
+    /**
+     * Utility: Calculate bounding box of all nodes
+     */
+    protected calculateBounds(nodes: NodeModel[]): {
+        minX: number;
+        minY: number;
+        maxX: number;
+        maxY: number;
+    } | null;
+}

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

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * Interface for layout algorithms
+ *
+ * All layout algorithms must implement this interface to be used by the LayoutManager.
+ * This provides a consistent API for different layout strategies.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseLayoutAlgorithm = void 0;
+/**
+ * Base abstract class for layout algorithms
+ *
+ * Provides common functionality that all layout algorithms can use.
+ * Extend this class when implementing a new layout algorithm.
+ */
+class BaseLayoutAlgorithm {
+    constructor(config) {
+        this.config = config || {
+            type: this.getType(),
+            animate: false,
+        };
+    }
+    configure(config) {
+        this.config = Object.assign(Object.assign({}, this.config), config);
+    }
+    getConfiguration() {
+        return Object.assign({}, this.config);
+    }
+    canApply(diagram) {
+        // Default implementation: always valid
+        return { valid: true };
+    }
+    /**
+     * Utility: Check if a position would collide with existing nodes
+     */
+    hasCollision(position, size, existingNodes, spacing = 20) {
+        const testBounds = {
+            left: position.x,
+            top: position.y,
+            right: position.x + size.width,
+            bottom: position.y + size.height,
+        };
+        for (const node of existingNodes) {
+            const bounds = node.getBoundingBox();
+            const expandedBounds = {
+                left: bounds.left - spacing,
+                top: bounds.top - spacing,
+                right: bounds.right + spacing,
+                bottom: bounds.bottom + spacing,
+            };
+            if (this.boundsIntersect(testBounds, expandedBounds)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Utility: Check if two bounding boxes intersect
+     */
+    boundsIntersect(box1, box2) {
+        return !(box1.right < box2.left ||
+            box1.left > box2.right ||
+            box1.bottom < box2.top ||
+            box1.top > box2.bottom);
+    }
+    /**
+     * Utility: Calculate bounding box of all nodes
+     */
+    calculateBounds(nodes) {
+        if (nodes.length === 0) {
+            return null;
+        }
+        let minX = Infinity;
+        let minY = Infinity;
+        let maxX = -Infinity;
+        let maxY = -Infinity;
+        for (const node of nodes) {
+            const bounds = node.getBoundingBox();
+            minX = Math.min(minX, bounds.left);
+            minY = Math.min(minY, bounds.top);
+            maxX = Math.max(maxX, bounds.right);
+            maxY = Math.max(maxY, bounds.bottom);
+        }
+        return { minX, minY, maxX, maxY };
+    }
+}
+exports.BaseLayoutAlgorithm = BaseLayoutAlgorithm;
+//# sourceMappingURL=ILayoutAlgorithm.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ILayoutAlgorithm.js","sourceRoot":"","sources":["../../../../../../engine/src/layout/ILayoutAlgorithm.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAmFH;;;;;GAKG;AACH,MAAsB,mBAAmB;IAGvC,YAAY,MAA4B;QACtC,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI;YACtB,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE;YACpB,OAAO,EAAE,KAAK;SACf,CAAC;IACJ,CAAC;IAOD,SAAS,CAAC,MAA2B;QACnC,IAAI,CAAC,MAAM,mCAAQ,IAAI,CAAC,MAAM,GAAK,MAAM,CAAE,CAAC;IAC9C,CAAC;IAED,gBAAgB;QACd,yBAAY,IAAI,CAAC,MAAM,EAAG;IAC5B,CAAC;IAED,QAAQ,CAAC,OAAqB;QAC5B,uCAAuC;QACvC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACzB,CAAC;IAED;;OAEG;IACO,YAAY,CACpB,QAAe,EACf,IAAuC,EACvC,aAA0B,EAC1B,UAAkB,EAAE;QAEpB,MAAM,UAAU,GAAG;YACjB,IAAI,EAAE,QAAQ,CAAC,CAAC;YAChB,GAAG,EAAE,QAAQ,CAAC,CAAC;YACf,KAAK,EAAE,QAAQ,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK;YAC9B,MAAM,EAAE,QAAQ,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM;SACjC,CAAC;QAEF,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;YACjC,MAAM,MAAM,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;YACrC,MAAM,cAAc,GAAG;gBACrB,IAAI,EAAE,MAAM,CAAC,IAAI,GAAG,OAAO;gBAC3B,GAAG,EAAE,MAAM,CAAC,GAAG,GAAG,OAAO;gBACzB,KAAK,EAAE,MAAM,CAAC,KAAK,GAAG,OAAO;gBAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,GAAG,OAAO;aAChC,CAAC;YAEF,IAAI,IAAI,CAAC,eAAe,CAAC,UAAU,EAAE,cAAc,CAAC,EAAE,CAAC;gBACrD,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACO,eAAe,CAAC,IAAS,EAAE,IAAS;QAC5C,OAAO,CAAC,CACN,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,IAAI;YACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK;YACtB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG;YACtB,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,CACvB,CAAC;IACJ,CAAC;IAED;;OAEG;IACO,eAAe,CAAC,KAAkB;QAM1C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,IAAI,GAAG,QAAQ,CAAC;QACpB,IAAI,IAAI,GAAG,QAAQ,CAAC;QACpB,IAAI,IAAI,GAAG,CAAC,QAAQ,CAAC;QACrB,IAAI,IAAI,GAAG,CAAC,QAAQ,CAAC;QAErB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,MAAM,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;YACrC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;YACnC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;YAClC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;YACpC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QACvC,CAAC;QAED,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACpC,CAAC;CACF;AArGD,kDAqGC"}

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

@@ -0,0 +1,155 @@
+/**
+ * Layout Manager
+ *
+ * Manages layout algorithms and provides a unified API for layout operations.
+ * Responsibilities:
+ * - Register and switch between layout algorithms
+ * - Calculate placement for new nodes
+ * - Re-layout existing diagrams
+ * - Emit layout events
+ */
+import { DiagramModel } from '../models/DiagramModel';
+import { NodeModel } from '../models/NodeModel';
+import { Rectangle } from '../types';
+import { ILayoutAlgorithm } from './ILayoutAlgorithm';
+import { LayoutAlgorithmType, LayoutConfiguration, PlacementOptions, PlacementResult, DiagramLayoutEvent } from './types';
+/**
+ * Layout Manager
+ */
+export declare class LayoutManager {
+    private algorithms;
+    private currentAlgorithm;
+    private diagram;
+    private eventListeners;
+    constructor(diagram: DiagramModel, initialAlgorithm?: LayoutAlgorithmType);
+    /**
+     * Register a layout algorithm
+     */
+    registerAlgorithm(type: LayoutAlgorithmType, algorithm: ILayoutAlgorithm): void;
+    /**
+     * Get registered algorithm
+     */
+    getAlgorithm(type: LayoutAlgorithmType): ILayoutAlgorithm | undefined;
+    /**
+     * Get all registered algorithm types
+     */
+    getAvailableAlgorithms(): LayoutAlgorithmType[];
+    /**
+     * Switch to a different layout algorithm
+     */
+    setAlgorithm(type: LayoutAlgorithmType, config?: LayoutConfiguration): void;
+    /**
+     * Get current layout algorithm
+     */
+    getCurrentAlgorithm(): ILayoutAlgorithm;
+    /**
+     * Get current algorithm type
+     */
+    getCurrentAlgorithmType(): LayoutAlgorithmType;
+    /**
+     * Calculate placement for a new node
+     */
+    calculatePlacement(node: NodeModel, viewport: Rectangle, options?: Partial<PlacementOptions>): PlacementResult;
+    /**
+     * Re-layout all nodes using current algorithm (Phase 0.5 - Viewport-aware)
+     * Option 3: Supports animation and locked node constraints
+     */
+    reLayout(config?: LayoutConfiguration): Promise<void>;
+    /**
+     * Option 3: Animate layout transitions
+     *
+     * Smoothly transitions nodes from old positions to new positions over the specified duration.
+     * Uses requestAnimationFrame for smooth 60fps animation.
+     */
+    private animateLayout;
+    /**
+     * Invalidate the routed polyline of every link whose endpoint nodes moved.
+     *
+     * Layout moves NODES; each link keeps the polyline it was routed on before.
+     * Edge labels are placed by walking that polyline (renderer LabelRenderer via
+     * link.getPointAtPosition), so a stale route strands labels at PRE-layout
+     * midpoints — observed live with labels sitting off-canvas at the old world
+     * coordinates. `setPoints([])` is the proven trigger for a re-route on the
+     * next paint (and it marks the link dirty, busting the VNode cache).
+     *
+     * Manual waypoints are cleared with the route — they were authored against
+     * the pre-layout coordinates (same rule as setPathType / setRouter).
+     */
+    private invalidateRoutesForMovedNodes;
+    /**
+     * Recalculate all link paths based on current node/port positions
+     *
+     * CRITICAL: This must be called after moving nodes programmatically (e.g., layout algorithms)
+     * because links don't automatically update their paths when nodes move.
+     *
+     * How it works:
+     * 1. Get all links in the diagram
+     * 2. For each link, find its source and target ports
+     * 3. Calculate port absolute positions based on current node positions
+     * 4. Call link.generatePath() to recalculate the path points
+     */
+    private recalculateLinkPaths;
+    /**
+     * Phase 0.5.2 Enhanced: Select optimal ports based on layout-aware algorithm
+     *
+     * Uses layout-aware analysis based on academic research:
+     * - Considers layout direction (TB/LR/RL/BT)
+     * - Classifies edges as forward/backward/cross relative to layout flow
+     * - Uses hierarchical rank information when available
+     * - Falls back to geometric analysis for non-hierarchical layouts
+     *
+     * Algorithm based on "Drawing Layered Graphs with Port Constraints" (Spönemann et al., 2013)
+     *
+     * @param sourceNode - The source node
+     * @param targetNode - The target node
+     * @param layoutContext - Optional layout context with direction and rank information
+     * @returns Object containing optimal source and target ports, or undefined if not found
+     */
+    selectOptimalPorts(sourceNode: NodeModel, targetNode: NodeModel, layoutContext?: {
+        direction?: 'TB' | 'LR' | 'RL' | 'BT';
+        ranks?: Map<string, number>;
+    }): {
+        sourcePort: any;
+        targetPort: any;
+    } | undefined;
+    /**
+     * Phase 0.5.2 Enhanced: Optimize all connections after layout
+     *
+     * Reassigns ports for all links based on current node positions and layout context.
+     * This ensures connections look natural after layout algorithms reposition nodes.
+     *
+     * Now public and layout-aware - uses hierarchical rank information when available
+     * to apply academic research-based port assignment (Spönemann et al., 2013).
+     *
+     * @param layoutContext - Optional layout context with direction and rank information
+     * @returns Number of connections optimized
+     */
+    optimizeConnections(layoutContext?: {
+        direction?: 'TB' | 'LR' | 'RL' | 'BT';
+        ranks?: Map<string, number>;
+    }): number;
+    /**
+     * Configure current layout algorithm
+     */
+    configure(config: LayoutConfiguration): void;
+    /**
+     * Get current configuration
+     */
+    getConfiguration(): LayoutConfiguration;
+    /**
+     * Subscribe to layout events
+     */
+    on(eventType: string, callback: (event: DiagramLayoutEvent) => void): void;
+    /**
+     * Unsubscribe from layout events
+     */
+    off(eventType: string, callback: (event: DiagramLayoutEvent) => void): void;
+    /**
+     * Emit layout event
+     */
+    private emitEvent;
+    /**
+     * Clean up resources
+     */
+    dispose(): void;
+}