@grafloria/element 0.3.18 → 0.3.20

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/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/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;
+}