@grafloria/element 0.3.17 → 0.3.19

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

@@ -0,0 +1,216 @@
+"use strict";
+/**
+ * Layout Service
+ *
+ * Central service for managing layout adapters and applying layouts to diagrams.
+ * Handles adapter registration, layout application, animation, and viewport fitting.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.layoutService = exports.LayoutService = void 0;
+const tslib_1 = require("tslib");
+const dagre_layout_adapter_1 = require("./dagre-layout-adapter");
+const elk_layout_adapter_1 = require("./elk-layout-adapter");
+/**
+ * Layout Service
+ *
+ * Manages layout adapters and provides a unified API for applying layouts.
+ * Can be used as a singleton or instantiated per diagram.
+ */
+class LayoutService {
+    constructor() {
+        this.adapters = new Map();
+        // Register built-in adapters
+        this.registerAdapter(new dagre_layout_adapter_1.DagreLayoutAdapter());
+        this.registerAdapter(new elk_layout_adapter_1.ELKLayoutAdapter());
+    }
+    /**
+     * Register a custom layout adapter
+     *
+     * @param adapter - Layout adapter to register
+     */
+    registerAdapter(adapter) {
+        this.adapters.set(adapter.name, adapter);
+    }
+    /**
+     * Get a registered adapter by name
+     *
+     * @param name - Name of the adapter
+     * @returns The adapter, or undefined if not found
+     */
+    getAdapter(name) {
+        return this.adapters.get(name);
+    }
+    /**
+     * Get all registered adapter names
+     *
+     * @returns Array of adapter names
+     */
+    getAdapterNames() {
+        return Array.from(this.adapters.keys());
+    }
+    /**
+     * Apply layout to diagram
+     *
+     * @param diagram - Diagram to layout
+     * @param config - Layout configuration
+     * @returns Layout result with positions and metadata
+     */
+    applyLayout(diagram, config) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            var _a;
+            // Get adapter
+            const adapter = typeof config.adapter === 'string' ? this.adapters.get(config.adapter) : config.adapter;
+            if (!adapter) {
+                throw new Error(`Layout adapter not found: ${config.adapter}`);
+            }
+            // Validate options
+            if (config.options && !adapter.validateOptions(config.options)) {
+                throw new Error(`Invalid layout options for adapter: ${adapter.name}`);
+            }
+            // Get nodes and links from diagram
+            const nodes = Array.from(diagram.getNodes().values());
+            const links = Array.from(diagram.getLinks().values());
+            if (nodes.length === 0) {
+                // Empty diagram, return empty result
+                return {
+                    nodePositions: new Map(),
+                    bounds: { x: 0, y: 0, width: 0, height: 0 },
+                    metadata: {
+                        algorithm: adapter.name,
+                        executionTime: 0,
+                    },
+                };
+            }
+            // Apply layout algorithm
+            const result = yield adapter.apply(nodes, links, config.options);
+            // Update node positions (with or without animation)
+            if (config.animate) {
+                yield this.animateToPositions(diagram, result.nodePositions, config.animationDuration || 300);
+            }
+            else {
+                this.applyPositions(diagram, result.nodePositions);
+            }
+            // CRITICAL: Regenerate all link paths after nodes have been repositioned
+            // This ensures links connect properly to nodes at their new positions
+            this.regenerateLinkPaths(diagram);
+            // Fit viewport if requested and canvas dimensions provided
+            if (config.fit && config.canvasDimensions && diagram.zoomToFit) {
+                const padding = ((_a = config.options) === null || _a === void 0 ? void 0 : _a.padding) || 50;
+                diagram.zoomToFit(config.canvasDimensions.width, config.canvasDimensions.height, padding);
+            }
+            return result;
+        });
+    }
+    /**
+     * Apply positions immediately without animation
+     *
+     * @param diagram - Diagram to update
+     * @param positions - Map of node IDs to positions
+     */
+    applyPositions(diagram, positions) {
+        positions.forEach((pos, nodeId) => {
+            const node = diagram.getNode(nodeId);
+            if (node) {
+                node.setPosition(pos.x, pos.y);
+            }
+        });
+    }
+    /**
+     * Animate nodes to new positions
+     *
+     * Uses requestAnimationFrame for smooth 60fps animation.
+     * Applies ease-out-cubic easing for natural motion.
+     *
+     * @param diagram - Diagram to update
+     * @param positions - Map of node IDs to target positions
+     * @param duration - Animation duration in milliseconds
+     */
+    animateToPositions(diagram, positions, duration) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            // Store start positions
+            const startPositions = new Map();
+            positions.forEach((_, nodeId) => {
+                const node = diagram.getNode(nodeId);
+                if (node) {
+                    startPositions.set(nodeId, {
+                        x: node.position.x,
+                        y: node.position.y,
+                    });
+                }
+            });
+            // Animate
+            return new Promise((resolve) => {
+                const startTime = performance.now();
+                const animate = () => {
+                    const now = performance.now();
+                    const elapsed = now - startTime;
+                    const progress = Math.min(elapsed / duration, 1);
+                    // Ease-out-cubic easing function
+                    const eased = 1 - Math.pow(1 - progress, 3);
+                    // Update positions
+                    positions.forEach((endPos, nodeId) => {
+                        const startPos = startPositions.get(nodeId);
+                        const node = diagram.getNode(nodeId);
+                        if (startPos && node) {
+                            const x = startPos.x + (endPos.x - startPos.x) * eased;
+                            const y = startPos.y + (endPos.y - startPos.y) * eased;
+                            node.setPosition(x, y);
+                        }
+                    });
+                    // Continue animation or resolve
+                    if (progress < 1) {
+                        requestAnimationFrame(animate);
+                    }
+                    else {
+                        resolve();
+                    }
+                };
+                requestAnimationFrame(animate);
+            });
+        });
+    }
+    /**
+     * Regenerate paths for all links in the diagram
+     *
+     * This is called after layout to ensure links connect properly to nodes
+     * at their new positions. Without this, links appear disconnected.
+     *
+     * @param diagram - Diagram containing the links to update
+     */
+    regenerateLinkPaths(diagram) {
+        const links = Array.from(diagram.getLinks().values());
+        links.forEach((link) => {
+            var _a, _b;
+            // Get source and target nodes
+            const sourceNode = link.sourceNodeId ? diagram.getNode(link.sourceNodeId) : null;
+            const targetNode = link.targetNodeId ? diagram.getNode(link.targetNodeId) : null;
+            if (!sourceNode || !targetNode) {
+                return; // Skip links without valid nodes
+            }
+            // Get source and target ports
+            const sourcePort = link.sourcePortId ? sourceNode.getPort(link.sourcePortId) : null;
+            const targetPort = link.targetPortId ? targetNode.getPort(link.targetPortId) : null;
+            if (!sourcePort || !targetPort) {
+                return; // Skip links without valid ports
+            }
+            // Calculate absolute positions of ports
+            const sourceBounds = sourceNode.getBoundingBox();
+            const targetBounds = targetNode.getBoundingBox();
+            const sourcePoint = sourcePort.getAbsolutePosition(sourceBounds);
+            const targetPoint = targetPort.getAbsolutePosition(targetBounds);
+            // Get port directions
+            const sourceDirection = (_a = sourcePort.alignment) === null || _a === void 0 ? void 0 : _a.side;
+            const targetDirection = (_b = targetPort.alignment) === null || _b === void 0 ? void 0 : _b.side;
+            // Regenerate the link path
+            link.generatePath(sourcePoint, targetPoint, sourceDirection, targetDirection);
+        });
+    }
+}
+exports.LayoutService = LayoutService;
+/**
+ * Singleton instance of LayoutService
+ *
+ * Can be used across the application for convenience.
+ */
+exports.layoutService = new LayoutService();
+//# sourceMappingURL=layout.service.js.map

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

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

package/src/libs/engine/src/layout/overlap-removal.d.ts

@@ -0,0 +1,20 @@
+import type { NodeModel } from '../models/NodeModel';
+export interface OverlapRemovalOptions {
+    /** Gap to open up between two boxes that were overlapping. */
+    spacing?: number;
+}
+/**
+ * Separate overlapping nodes, in place, and return the corrected positions.
+ *
+ * Deterministic: boxes are swept in (x, id) order, so the result is a pure
+ * function of the input positions — never of a map's iteration order.
+ *
+ * Returns the same Map instance for convenience.
+ */
+export declare function removeOverlaps(nodes: readonly NodeModel[], positions: Map<string, {
+    x: number;
+    y: number;
+}>, options?: OverlapRemovalOptions): Map<string, {
+    x: number;
+    y: number;
+}>;

package/src/libs/engine/src/layout/overlap-removal.js

@@ -0,0 +1,117 @@
+"use strict";
+// Wave 7 (Auto-layout) — Card 2: overlap removal.
+//
+// ---------------------------------------------------------------------------
+// THE BUG THIS CLOSES (found by Card 2's own packing test)
+// ---------------------------------------------------------------------------
+//
+// The force and community adapters lay out nodes as DIMENSIONLESS POINTS. Every
+// force in `force-layout-adapter.ts` — repulsion, attraction, gravity — is
+// computed from centre-to-centre distance with `mass: 1`, and nothing anywhere
+// consults `node.size`. So a four-node star with the default `linkDistance: 100`
+// puts four 150x50 boxes 100px apart centre-to-centre and they SIT ON TOP OF EACH
+// OTHER. The layout is "correct" as physics and useless as a diagram.
+//
+// It is the same class of failure as the forest-becomes-a-pile bug that packing
+// fixes, one level down: packing stops COMPONENTS colliding, this stops NODES
+// colliding. Neither is optional, and neither belongs in five separate algorithms.
+//
+// The proper fix inside the simulation is size-aware repulsion (repel by box
+// distance, not centre distance). That would change force's coordinates for every
+// existing caller and is a card of its own. This is the standard alternative — a
+// post-pass — and it has the property that matters here: for a layout that does
+// NOT overlap (dagre, ELK, tree, grid, circular, radial) it is a provable NO-OP,
+// so it can sit in front of every layout in the engine without moving a single
+// well-behaved pixel.
+//
+// ---------------------------------------------------------------------------
+// WHY THIS IS A SWEEP, AND NOT THE OBVIOUS PAIRWISE RELAXATION
+// ---------------------------------------------------------------------------
+//
+// The obvious implementation — and the one this shipped with for an hour — is:
+// repeat N times { for every overlapping pair, push both apart along the minimum
+// translation vector }. It passes a four-node unit test beautifully and it DOES
+// NOT WORK.
+//
+// Measured, on 200 nodes:
+//
+//     200-node pile,   20 iterations -> 2352 overlaps remaining
+//     200-node pile,  100 iterations -> 1012 overlaps remaining
+//     200-node pile, 2000 iterations ->  161 overlaps remaining  (16.6 SECONDS)
+//     realistic 200-node soup, default -> 140 overlaps remaining
+//
+// It does not converge. Every push into free space shoves a node into a
+// neighbour, and the whole field diffuses instead of separating. Worse, it is
+// O(n² · iterations), so the "just raise the cap" reflex buys 16 seconds of CPU
+// and still leaves overlaps. A guarantee that silently fails on the second-
+// simplest input is worse than no guarantee at all.
+//
+// What ships instead is an EXACT one-pass horizontal separation, and it rests on
+// one observation: two boxes overlap only if they overlap on BOTH axes. So it is
+// enough to make every y-overlapping pair disjoint in x — then nothing overlaps,
+// by definition, and no second pass is needed.
+//
+// Sweep the boxes left to right; push each one right until it clears everything
+// already placed. Each push moves a box strictly past some already-placed box's
+// right edge, so it terminates; and a box that overlaps nothing never moves, so a
+// well-behaved layout (dagre, ELK, tree, grid, circular, radial) is untouched.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.removeOverlaps = removeOverlaps;
+const component_packing_1 = require("./component-packing");
+/** True overlap — not "within spacing of". Keeps the pass a no-op for tidy layouts. */
+const intersects = (a, b) => a.x < b.x + b.width && b.x < a.x + a.width && a.y < b.y + b.height && b.y < a.y + a.height;
+/**
+ * Separate overlapping nodes, in place, and return the corrected positions.
+ *
+ * Deterministic: boxes are swept in (x, id) order, so the result is a pure
+ * function of the input positions — never of a map's iteration order.
+ *
+ * Returns the same Map instance for convenience.
+ */
+function removeOverlaps(nodes, positions, options = {}) {
+    var _a;
+    const spacing = (_a = options.spacing) !== null && _a !== void 0 ? _a : 20;
+    const boxes = [];
+    for (const node of nodes) {
+        const p = positions.get(node.id);
+        if (!p)
+            continue;
+        const size = (0, component_packing_1.nodeSize)(node);
+        boxes.push({ id: node.id, x: p.x, y: p.y, width: size.width, height: size.height });
+    }
+    if (boxes.length < 2)
+        return positions;
+    boxes.sort((a, b) => a.x - b.x || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    // `active` holds the boxes a future box could still run into. Without it this is
+    // O(n²) even when NOTHING overlaps — every box would scan every earlier box —
+    // and a 60,000-node diagram would spend billions of comparisons proving there
+    // was nothing to do.
+    const active = [];
+    for (const box of boxes) {
+        // The frontier is the box's ORIGINAL left edge, which is monotonic in sort
+        // order. Pruning against the box's PUSHED position would be wrong: the next
+        // box may sit further left than this one ended up, and would then be compared
+        // against an active list that had already discarded its real neighbours.
+        const frontier = box.x;
+        for (let i = active.length - 1; i >= 0; i--) {
+            if (active[i].x + active[i].width + spacing <= frontier) {
+                active.splice(i, 1);
+            }
+        }
+        // Push right until it clears everything still active. Each push clears at
+        // least one box's right edge and x only ever increases, so this terminates in
+        // at most `active.length` steps.
+        for (let guard = 0; guard <= active.length; guard++) {
+            const hit = active.find((other) => intersects(box, other));
+            if (!hit)
+                break; // THE NO-OP: a box that overlaps nothing never moves
+            box.x = hit.x + hit.width + spacing;
+        }
+        active.push(box);
+    }
+    for (const box of boxes) {
+        positions.set(box.id, { x: box.x, y: box.y });
+    }
+    return positions;
+}
+//# sourceMappingURL=overlap-removal.js.map

package/src/libs/engine/src/layout/overlap-removal.js.map

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

package/src/libs/engine/src/layout/port-aware-layout.interface.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Port-Aware Layout System
+ *
+ * Enables layout algorithms to consider port positions when arranging nodes,
+ * minimizing edge crossings and creating cleaner diagrams.
+ *
+ * Key features:
+ * - Port side preferences (left, right, top, bottom)
+ * - Port ordering constraints
+ * - Connection-aware positioning
+ * - Crossing minimization
+ *
+ * @module layout/port-aware-layout
+ */
+/**
+ * Port side relative to node
+ */
+export type PortSide = 'left' | 'right' | 'top' | 'bottom';
+/**
+ * Port direction (input or output)
+ */
+export type PortFlowDirection = 'input' | 'output' | 'bidirectional';
+/**
+ * Information about a port for layout purposes
+ */
+export interface PortInfo {
+    /** Port unique identifier */
+    id: string;
+    /** Node this port belongs to */
+    nodeId: string;
+    /** Preferred side of the node */
+    preferredSide?: PortSide;
+    /** Port direction */
+    direction?: PortFlowDirection;
+    /** Position along the side (0-1, where 0 is top/left, 1 is bottom/right) */
+    offset?: number;
+    /** Fixed position (prevents automatic ordering) */
+    fixed?: boolean;
+    /** Priority for ordering (higher = more important) */
+    priority?: number;
+    /** Group identifier for related ports */
+    group?: string;
+}
+/**
+ * Configuration for port-aware layout
+ */
+export interface PortAwareLayoutOptions {
+    /** Enable port-aware layout */
+    enabled: boolean;
+    /** Port information for all ports in the diagram */
+    ports?: PortInfo[];
+    /** Automatic port side assignment based on node connections */
+    autoAssignSides?: boolean;
+    /** Automatic port ordering to minimize crossings */
+    autoOrderPorts?: boolean;
+    /** Prefer inputs on specific side */
+    inputSide?: PortSide;
+    /** Prefer outputs on specific side */
+    outputSide?: PortSide;
+    /** Minimum spacing between ports (in pixels) */
+    portSpacing?: number;
+    /** Whether to consider port positions in edge routing */
+    usePortPositions?: boolean;
+    /** Strategy for port ordering */
+    orderingStrategy?: 'minimize-crossings' | 'connection-based' | 'group-based' | 'manual';
+    /** Node-specific port side preferences */
+    nodeSidePreferences?: {
+        [nodeId: string]: {
+            inputs?: PortSide;
+            outputs?: PortSide;
+        };
+    };
+    /** Per-port ordering constraints */
+    portOrdering?: {
+        [nodeId: string]: string[];
+    };
+}
+/**
+ * Result of port-aware layout computation
+ */
+export interface PortAwareLayoutResult {
+    /** Final port assignments (port ID -> side) */
+    portAssignments: Map<string, PortSide>;
+    /** Final port ordering (node ID -> ordered port IDs) */
+    portOrdering: Map<string, string[]>;
+    /** Calculated port positions (port ID -> {x, y} relative to node) */
+    portPositions: Map<string, {
+        x: number;
+        y: number;
+        side: PortSide;
+    }>;
+    /** Number of edge crossings */
+    edgeCrossings: number;
+    /** Whether port positions were optimized */
+    wasOptimized: boolean;
+    /** Ports that were automatically assigned sides */
+    autoAssignedPorts: string[];
+    /** Ports that were automatically ordered */
+    autoOrderedPorts: string[];
+}
+/**
+ * Port-aware layout computation utilities
+ */
+export declare class PortAwareLayoutManager {
+    private static readonly DEFAULT_PORT_SPACING;
+    /**
+     * Assign ports to sides of their parent nodes
+     */
+    static assignPortSides(ports: PortInfo[], nodePositions: Map<string, {
+        x: number;
+        y: number;
+    }>, options: PortAwareLayoutOptions): Map<string, PortSide>;
+    /**
+     * Determine optimal side for a port based on connections
+     */
+    private static determineOptimalSide;
+    /**
+     * Order ports on each node to minimize edge crossings
+     */
+    static orderPorts(ports: PortInfo[], portAssignments: Map<string, PortSide>, nodePositions: Map<string, {
+        x: number;
+        y: number;
+    }>, links: Array<{
+        sourcePortId?: string;
+        targetPortId?: string;
+    }>, options: PortAwareLayoutOptions): Map<string, string[]>;
+    /**
+     * Compute optimal port order to minimize crossings
+     */
+    private static computeOptimalPortOrder;
+    /**
+     * Order ports to minimize edge crossings (barycentre method).
+     *
+     * BUG FIXED (Wave 7, Card 7): the connected port was looked up in `ports` — the
+     * ports on ONE SIDE of ONE node, i.e. the very list being sorted. But a port is
+     * connected to ports on OTHER nodes, which are never in that list, so the lookup
+     * missed every time, every barycentre came out 0, and the sort was a no-op.
+     * `minimize-crossings` ordering had never reordered anything in its life.
+     *
+     * The fix needs the WHOLE port list (`allPorts`) to resolve a partner port back
+     * to its node.
+     */
+    private static orderByMinimizingCrossings;
+    /**
+     * Order ports based on their connections
+     */
+    private static orderByConnections;
+    /**
+     * Order ports by their group membership
+     */
+    private static orderByGroups;
+    /**
+     * Calculate physical port positions on nodes
+     */
+    static calculatePortPositions(ports: PortInfo[], portAssignments: Map<string, PortSide>, portOrdering: Map<string, string[]>, nodeSizes: Map<string, {
+        width: number;
+        height: number;
+    }>, options: PortAwareLayoutOptions): Map<string, {
+        x: number;
+        y: number;
+        side: PortSide;
+    }>;
+    /**
+     * Position ports evenly along a node side
+     */
+    private static positionPortsOnSide;
+    /**
+     * Distribute ports evenly along an axis
+     */
+    private static distributeAlongAxis;
+    /**
+     * Group ports by their parent node
+     */
+    private static groupPortsByNode;
+    /**
+     * Get ports connected to a given port
+     */
+    private static getConnectedPorts;
+    /**
+     * Count edge crossings for a given port configuration.
+     *
+     * BUG FIXED (Wave 7, Card 7): this took `nodePositions` and never used it. Port
+     * coordinates are RELATIVE to their own node, so every node's ports were being
+     * compared around a shared origin — two edges on opposite ends of a large canvas
+     * could be counted as crossing, and two that genuinely crossed could be missed.
+     * The old `getLinkEndpoint` even said so in a comment ("In real implementation,
+     * this should be absolute") and returned the relative point anyway. Every
+     * `edgeCrossings` number this module has ever reported was therefore noise.
+     *
+     * `ports` is what makes the fix possible: it maps a port back to its node, so
+     * the port's offset can be added to the node's origin. It is optional only for
+     * source compatibility — without it we cannot resolve the frame, so we fall back
+     * to the relative comparison rather than silently inventing a node position.
+     */
+    static countEdgeCrossings(portPositions: Map<string, {
+        x: number;
+        y: number;
+        side: PortSide;
+    }>, nodePositions: Map<string, {
+        x: number;
+        y: number;
+    }>, links: Array<{
+        sourcePortId?: string;
+        targetPortId?: string;
+    }>, ports?: PortInfo[]): number;
+    /**
+     * Check if two links intersect
+     */
+    private static linksIntersect;
+    /**
+     * The ABSOLUTE position of a link endpoint: the port's offset within its node,
+     * plus that node's origin. (It used to return the raw relative offset.)
+     */
+    private static getLinkEndpoint;
+    /**
+     * Check if two line segments intersect
+     */
+    private static lineSegmentsIntersect;
+    /**
+     * Generate complete port-aware layout result
+     */
+    static computePortLayout(ports: PortInfo[], nodePositions: Map<string, {
+        x: number;
+        y: number;
+    }>, nodeSizes: Map<string, {
+        width: number;
+        height: number;
+    }>, links: Array<{
+        sourcePortId?: string;
+        targetPortId?: string;
+    }>, options: PortAwareLayoutOptions): PortAwareLayoutResult;
+}