@grafloria/element 0.3.18 → 0.3.20

package/src/libs/engine/src/layout/port-aware-layout.interface.js

@@ -0,0 +1,413 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PortAwareLayoutManager = void 0;
+/**
+ * Port-aware layout computation utilities
+ */
+class PortAwareLayoutManager {
+    /**
+     * Assign ports to sides of their parent nodes
+     */
+    static assignPortSides(ports, nodePositions, options) {
+        const assignments = new Map();
+        // First, assign ports with explicit preferences
+        for (const port of ports) {
+            if (port.preferredSide) {
+                assignments.set(port.id, port.preferredSide);
+            }
+        }
+        // If auto-assign is enabled, assign remaining ports based on connections
+        if (options.autoAssignSides) {
+            const unassignedPorts = ports.filter((p) => !assignments.has(p.id));
+            for (const port of unassignedPorts) {
+                const side = this.determineOptimalSide(port, ports, nodePositions, options);
+                assignments.set(port.id, side);
+            }
+        }
+        return assignments;
+    }
+    /**
+     * Determine optimal side for a port based on connections
+     */
+    static determineOptimalSide(port, allPorts, nodePositions, options) {
+        var _a;
+        // Use direction-based defaults if specified
+        if (port.direction === 'input' && options.inputSide) {
+            return options.inputSide;
+        }
+        if (port.direction === 'output' && options.outputSide) {
+            return options.outputSide;
+        }
+        // Check node-specific preferences
+        const nodePrefs = (_a = options.nodeSidePreferences) === null || _a === void 0 ? void 0 : _a[port.nodeId];
+        if (nodePrefs) {
+            if (port.direction === 'input' && nodePrefs.inputs) {
+                return nodePrefs.inputs;
+            }
+            if (port.direction === 'output' && nodePrefs.outputs) {
+                return nodePrefs.outputs;
+            }
+        }
+        // Default assignments based on direction
+        if (port.direction === 'input') {
+            return 'left';
+        }
+        if (port.direction === 'output') {
+            return 'right';
+        }
+        // For bidirectional or unspecified, use top
+        return 'top';
+    }
+    /**
+     * Order ports on each node to minimize edge crossings
+     */
+    static orderPorts(ports, portAssignments, nodePositions, links, options) {
+        var _a;
+        const ordering = new Map();
+        // Group ports by node
+        const portsByNode = this.groupPortsByNode(ports);
+        for (const [nodeId, nodePorts] of portsByNode) {
+            // Check for manual ordering
+            if ((_a = options.portOrdering) === null || _a === void 0 ? void 0 : _a[nodeId]) {
+                ordering.set(nodeId, options.portOrdering[nodeId]);
+                continue;
+            }
+            // Auto-order if enabled
+            if (options.autoOrderPorts) {
+                const ordered = this.computeOptimalPortOrder(nodePorts, portAssignments, nodePositions, links, options, ports // the WHOLE port list: a partner port lives on another node
+                );
+                ordering.set(nodeId, ordered);
+            }
+            else {
+                // Default order: by offset, then by ID
+                const defaultOrder = nodePorts
+                    .sort((a, b) => {
+                    if (a.offset !== undefined && b.offset !== undefined) {
+                        return a.offset - b.offset;
+                    }
+                    return a.id.localeCompare(b.id);
+                })
+                    .map((p) => p.id);
+                ordering.set(nodeId, defaultOrder);
+            }
+        }
+        return ordering;
+    }
+    /**
+     * Compute optimal port order to minimize crossings
+     */
+    static computeOptimalPortOrder(nodePorts, portAssignments, nodePositions, links, options, allPorts) {
+        // Group ports by side
+        const portsBySide = new Map();
+        for (const port of nodePorts) {
+            const side = portAssignments.get(port.id) || 'top';
+            if (!portsBySide.has(side)) {
+                portsBySide.set(side, []);
+            }
+            portsBySide.get(side).push(port);
+        }
+        const orderedPorts = [];
+        // Order ports on each side
+        for (const [side, ports] of portsBySide) {
+            let sideOrder;
+            if (options.orderingStrategy === 'minimize-crossings') {
+                sideOrder = this.orderByMinimizingCrossings(ports, links, nodePositions, side, allPorts);
+            }
+            else if (options.orderingStrategy === 'connection-based') {
+                sideOrder = this.orderByConnections(ports, links, nodePositions, side, allPorts);
+            }
+            else if (options.orderingStrategy === 'group-based') {
+                sideOrder = this.orderByGroups(ports);
+            }
+            else {
+                // Manual or default
+                sideOrder = [...ports];
+            }
+            orderedPorts.push(...sideOrder.map((p) => p.id));
+        }
+        return orderedPorts;
+    }
+    /**
+     * 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.
+     */
+    static orderByMinimizingCrossings(ports, links, nodePositions, side, allPorts) {
+        const portsById = new Map(allPorts.map((p) => [p.id, p]));
+        const barycenters = new Map();
+        for (const port of ports) {
+            const connectedPorts = this.getConnectedPorts(port.id, links);
+            // A port that connects to nothing has no barycentre to speak of. Give it
+            // -Infinity's opposite: keep it stable at its declared position by scoring
+            // it 0 only when nothing else scored either — otherwise an unconnected port
+            // would jump to the top of the side.
+            let sum = 0;
+            let counted = 0;
+            for (const connectedPortId of connectedPorts) {
+                const partner = portsById.get(connectedPortId);
+                if (!partner)
+                    continue;
+                const nodePos = nodePositions.get(partner.nodeId);
+                if (!nodePos)
+                    continue;
+                // Ports on a vertical side are ordered by the partner's Y; on a horizontal
+                // side, by its X.
+                sum += side === 'left' || side === 'right' ? nodePos.y : nodePos.x;
+                counted++;
+            }
+            barycenters.set(port.id, counted > 0 ? sum / counted : 0);
+        }
+        // Sort by barycentre, breaking ties on id so the order is total and stable.
+        return [...ports].sort((a, b) => {
+            var _a, _b;
+            const bcA = (_a = barycenters.get(a.id)) !== null && _a !== void 0 ? _a : 0;
+            const bcB = (_b = barycenters.get(b.id)) !== null && _b !== void 0 ? _b : 0;
+            return bcA - bcB || a.id.localeCompare(b.id);
+        });
+    }
+    /**
+     * Order ports based on their connections
+     */
+    static orderByConnections(ports, links, nodePositions, side, allPorts) {
+        // Similar to crossing minimization but considers connectivity strength
+        return this.orderByMinimizingCrossings(ports, links, nodePositions, side, allPorts);
+    }
+    /**
+     * Order ports by their group membership
+     */
+    static orderByGroups(ports) {
+        return ports.sort((a, b) => {
+            // Group together, then by priority, then by ID
+            const groupCompare = (a.group || '').localeCompare(b.group || '');
+            if (groupCompare !== 0)
+                return groupCompare;
+            const priorityA = a.priority || 0;
+            const priorityB = b.priority || 0;
+            if (priorityA !== priorityB)
+                return priorityB - priorityA; // Higher priority first
+            return a.id.localeCompare(b.id);
+        });
+    }
+    /**
+     * Calculate physical port positions on nodes
+     */
+    static calculatePortPositions(ports, portAssignments, portOrdering, nodeSizes, options) {
+        const positions = new Map();
+        const spacing = options.portSpacing || this.DEFAULT_PORT_SPACING;
+        // Group ports by node
+        const portsByNode = this.groupPortsByNode(ports);
+        for (const [nodeId, nodePorts] of portsByNode) {
+            const nodeSize = nodeSizes.get(nodeId) || { width: 100, height: 100 };
+            const order = portOrdering.get(nodeId) || nodePorts.map((p) => p.id);
+            // Group by side
+            const portsBySide = new Map();
+            for (const portId of order) {
+                const side = portAssignments.get(portId) || 'top';
+                if (!portsBySide.has(side)) {
+                    portsBySide.set(side, []);
+                }
+                portsBySide.get(side).push(portId);
+            }
+            // Calculate positions for each side
+            for (const [side, portIds] of portsBySide) {
+                this.positionPortsOnSide(portIds, side, nodeSize, spacing, positions);
+            }
+        }
+        return positions;
+    }
+    /**
+     * Position ports evenly along a node side
+     */
+    static positionPortsOnSide(portIds, side, nodeSize, spacing, positions) {
+        const count = portIds.length;
+        if (count === 0)
+            return;
+        for (let i = 0; i < count; i++) {
+            const portId = portIds[i];
+            let x = 0;
+            let y = 0;
+            switch (side) {
+                case 'left':
+                    x = -nodeSize.width / 2;
+                    y = this.distributeAlongAxis(i, count, nodeSize.height, spacing);
+                    break;
+                case 'right':
+                    x = nodeSize.width / 2;
+                    y = this.distributeAlongAxis(i, count, nodeSize.height, spacing);
+                    break;
+                case 'top':
+                    x = this.distributeAlongAxis(i, count, nodeSize.width, spacing);
+                    y = -nodeSize.height / 2;
+                    break;
+                case 'bottom':
+                    x = this.distributeAlongAxis(i, count, nodeSize.width, spacing);
+                    y = nodeSize.height / 2;
+                    break;
+            }
+            positions.set(portId, { x, y, side });
+        }
+    }
+    /**
+     * Distribute ports evenly along an axis
+     */
+    static distributeAlongAxis(index, total, axisLength, spacing) {
+        if (total === 1) {
+            return 0; // Center single port
+        }
+        // Calculate even distribution
+        const segment = axisLength / (total + 1);
+        return -axisLength / 2 + segment * (index + 1);
+    }
+    /**
+     * Group ports by their parent node
+     */
+    static groupPortsByNode(ports) {
+        const grouped = new Map();
+        for (const port of ports) {
+            if (!grouped.has(port.nodeId)) {
+                grouped.set(port.nodeId, []);
+            }
+            grouped.get(port.nodeId).push(port);
+        }
+        return grouped;
+    }
+    /**
+     * Get ports connected to a given port
+     */
+    static getConnectedPorts(portId, links) {
+        const connected = [];
+        for (const link of links) {
+            if (link.sourcePortId === portId && link.targetPortId) {
+                connected.push(link.targetPortId);
+            }
+            if (link.targetPortId === portId && link.sourcePortId) {
+                connected.push(link.sourcePortId);
+            }
+        }
+        return connected;
+    }
+    /**
+     * 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, nodePositions, links, ports) {
+        const nodeIdByPort = new Map((ports !== null && ports !== void 0 ? ports : []).map((p) => [p.id, p.nodeId]));
+        let crossings = 0;
+        // Check each pair of links
+        for (let i = 0; i < links.length; i++) {
+            for (let j = i + 1; j < links.length; j++) {
+                if (this.linksIntersect(links[i], links[j], portPositions, nodePositions, nodeIdByPort)) {
+                    crossings++;
+                }
+            }
+        }
+        return crossings;
+    }
+    /**
+     * Check if two links intersect
+     */
+    static linksIntersect(link1, link2, portPositions, nodePositions, nodeIdByPort) {
+        const at = (link, end) => this.getLinkEndpoint(link, end, portPositions, nodePositions, nodeIdByPort);
+        const l1Start = at(link1, 'source');
+        const l1End = at(link1, 'target');
+        const l2Start = at(link2, 'source');
+        const l2End = at(link2, 'target');
+        if (!l1Start || !l1End || !l2Start || !l2End) {
+            return false;
+        }
+        return this.lineSegmentsIntersect(l1Start, l1End, l2Start, l2End);
+    }
+    /**
+     * 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.)
+     */
+    static getLinkEndpoint(link, end, portPositions, nodePositions, nodeIdByPort) {
+        const portId = end === 'source' ? link.sourcePortId : link.targetPortId;
+        if (!portId)
+            return null;
+        const portPos = portPositions.get(portId);
+        if (!portPos)
+            return null;
+        const nodeId = nodeIdByPort.get(portId);
+        const nodePos = nodeId ? nodePositions.get(nodeId) : undefined;
+        // Without the port->node mapping we cannot lift this into diagram space, so
+        // stay in the relative frame rather than pretending the node sits at (0,0).
+        if (!nodePos)
+            return { x: portPos.x, y: portPos.y };
+        return { x: nodePos.x + portPos.x, y: nodePos.y + portPos.y };
+    }
+    /**
+     * Check if two line segments intersect
+     */
+    static lineSegmentsIntersect(p1, p2, p3, p4) {
+        const ccw = (a, b, c) => {
+            return (c.y - a.y) * (b.x - a.x) > (b.y - a.y) * (c.x - a.x);
+        };
+        return ccw(p1, p3, p4) !== ccw(p2, p3, p4) && ccw(p1, p2, p3) !== ccw(p1, p2, p4);
+    }
+    /**
+     * Generate complete port-aware layout result
+     */
+    static computePortLayout(ports, nodePositions, nodeSizes, links, options) {
+        // Assign sides
+        const portAssignments = this.assignPortSides(ports, nodePositions, options);
+        // Order ports
+        const portOrdering = this.orderPorts(ports, portAssignments, nodePositions, links, options);
+        // Calculate positions
+        const portPositions = this.calculatePortPositions(ports, portAssignments, portOrdering, nodeSizes, options);
+        // Count crossings
+        const edgeCrossings = this.countEdgeCrossings(portPositions, nodePositions, links, ports);
+        // Track what was auto-assigned/ordered
+        const autoAssignedPorts = options.autoAssignSides
+            ? ports.filter((p) => !p.preferredSide).map((p) => p.id)
+            : [];
+        const autoOrderedPorts = options.autoOrderPorts
+            ? Array.from(portOrdering.keys()).filter((nodeId) => { var _a; return !((_a = options.portOrdering) === null || _a === void 0 ? void 0 : _a[nodeId]); })
+            : [];
+        return {
+            portAssignments,
+            portOrdering,
+            portPositions,
+            edgeCrossings,
+            wasOptimized: options.autoAssignSides || options.autoOrderPorts || false,
+            autoAssignedPorts,
+            autoOrderedPorts,
+        };
+    }
+}
+exports.PortAwareLayoutManager = PortAwareLayoutManager;
+PortAwareLayoutManager.DEFAULT_PORT_SPACING = 20;
+//# sourceMappingURL=port-aware-layout.interface.js.map

package/src/libs/engine/src/layout/port-label-bridge.d.ts

@@ -0,0 +1,77 @@
+import type { NodeModel } from '../models/NodeModel';
+import type { LinkModel } from '../models/LinkModel';
+import type { PortModel } from '../models/PortModel';
+import type { LinkLabel } from '../types/model.types';
+import type { PortInfo, PortSide } from './port-aware-layout.interface';
+/**
+ * Was this port invented by `NodeModel.initializeDefaultPorts()` rather than
+ * declared by the author?
+ *
+ * The model marks them (`setMetadata('default', true)`), which is the only
+ * trustworthy signal — `explicitSide` is TRUE even for the default ports (they
+ * are constructed with `side:`, and the PortModel constructor sets the flag), so
+ * `explicitSide` cannot be used to tell an authored port from an invented one.
+ * That trap is exactly why this helper exists instead of an inline check.
+ */
+export declare function isDefaultPort(port: PortModel): boolean;
+/** Ports the author actually declared — the ones that may constrain a layout. */
+export declare function declaredPorts(node: NodeModel): PortModel[];
+/**
+ * Does this node carry author-declared ports? If not, layout may place it freely
+ * and route through whichever of the four default sides suits the router.
+ */
+export declare function hasDeclaredPorts(node: NodeModel): boolean;
+/**
+ * Build the `PortInfo[]` that `PortAwareLayoutManager` and the ELK adapter have
+ * been waiting for, from the real wave-6 port model.
+ *
+ * Only DECLARED ports are emitted (see the file header). Ordering is canonical —
+ * sorted by (nodeId, side, index, id) — because layout determinism is a Card 0
+ * invariant and a Map-iteration-ordered port list would break it exactly the way
+ * an insertion-ordered node list did.
+ */
+export declare function derivePortInfos(nodes: NodeModel[]): PortInfo[];
+/** ELK's compass vocabulary for a port side. */
+export type ElkPortSide = 'NORTH' | 'EAST' | 'SOUTH' | 'WEST';
+export declare function toElkPortSide(side: PortSide): ElkPortSide;
+/**
+ * How much freedom does the layout engine have over this node's ports?
+ *
+ *   FREE        — no declared ports: put the edge wherever it routes best.
+ *   FIXED_SIDE  — the author said which side; the engine may still reorder
+ *                 within that side to reduce crossings.
+ *   FIXED_ORDER — side AND order are the author's.
+ *   FIXED_POS   — the exact coordinates are the author's.
+ *
+ * `'auto'` (the default) resolves per node: FIXED_SIDE when the node declares
+ * ports, FREE when it does not. That is what makes port-awareness safe to leave
+ * ON — it constrains only the nodes whose author asked for it.
+ */
+export type PortConstraintMode = 'auto' | 'free' | 'fixed-side' | 'fixed-order' | 'fixed-pos';
+export type ElkPortConstraint = 'FREE' | 'FIXED_SIDE' | 'FIXED_ORDER' | 'FIXED_POS';
+export declare function resolvePortConstraint(node: NodeModel, mode?: PortConstraintMode): ElkPortConstraint;
+/** The box an edge label needs. Layout's job is to reserve it; not to place it. */
+export interface LabelBox {
+    /** The label this box belongs to. */
+    id: string;
+    /** The link the label rides on. */
+    linkId: string;
+    text: string;
+    width: number;
+    height: number;
+}
+/** The estimated content box of a single edge label, including its padding. */
+export declare function estimateLabelBox(label: LinkLabel, linkId?: string): LabelBox;
+/** Every label on a link, sized. Empty for the common unlabelled link. */
+export declare function deriveLabelBoxes(link: LinkModel): LabelBox[];
+/** The single box that must fit on a link: the union of its labels' boxes. */
+export declare function linkLabelBox(link: LinkModel): LabelBox | undefined;
+/**
+ * The space every labelled edge needs, as one summary — what a layout engine that
+ * cannot take per-edge label boxes (force, spectral, …) uses to inflate its
+ * spacing so labels have somewhere to live.
+ */
+export declare function reservedLabelSpace(links: LinkModel[]): {
+    width: number;
+    height: number;
+};