@grafloria/element 0.3.18 → 0.3.20

package/src/libs/engine/src/layout/layout-presets.js

@@ -0,0 +1,333 @@
+"use strict";
+/**
+ * Layout Presets Library
+ *
+ * Pre-configured layout settings for common diagram scenarios.
+ * Includes both layout options and constraint configurations.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LayoutPresets = void 0;
+/**
+ * Predefined layout presets for common scenarios
+ */
+class LayoutPresets {
+    /**
+     * Get all preset categories
+     */
+    static getAllCategories() {
+        return [
+            this.HIERARCHICAL,
+            this.FLOW,
+            this.NETWORK,
+            this.ARCHITECTURE,
+            this.INTERACTIVE,
+        ];
+    }
+    /**
+     * Get all presets across all categories
+     */
+    static getAllPresets() {
+        const allPresets = [];
+        this.getAllCategories().forEach(category => {
+            allPresets.push(...category.presets);
+        });
+        return allPresets;
+    }
+    /**
+     * Find preset by ID
+     */
+    static findPreset(id) {
+        return this.getAllPresets().find(preset => preset.id === id);
+    }
+    /**
+     * Find presets by tag
+     */
+    static findPresetsByTag(tag) {
+        return this.getAllPresets().filter(preset => { var _a; return (_a = preset.tags) === null || _a === void 0 ? void 0 : _a.includes(tag); });
+    }
+    /**
+     * Find presets by adapter type
+     */
+    static findPresetsByAdapter(adapter) {
+        return this.getAllPresets().filter(preset => preset.adapter === adapter);
+    }
+    /**
+     * Search presets by name or description
+     */
+    static searchPresets(query) {
+        const lowerQuery = query.toLowerCase();
+        return this.getAllPresets().filter(preset => preset.name.toLowerCase().includes(lowerQuery) ||
+            preset.description.toLowerCase().includes(lowerQuery));
+    }
+}
+exports.LayoutPresets = LayoutPresets;
+/**
+ * Organizational/Hierarchical Layouts
+ */
+LayoutPresets.HIERARCHICAL = {
+    name: 'Hierarchical Layouts',
+    description: 'Top-down or left-right hierarchies, org charts, and tree structures',
+    presets: [
+        {
+            id: 'org-chart-compact',
+            name: 'Org Chart (Compact)',
+            description: 'Compact organizational chart with tight spacing',
+            adapter: 'dagre',
+            options: {
+                rankdir: 'TB',
+                nodesep: 40,
+                ranksep: 60,
+                ranker: 'tight-tree',
+            },
+            tags: ['hierarchy', 'org-chart', 'compact'],
+        },
+        {
+            id: 'org-chart-spacious',
+            name: 'Org Chart (Spacious)',
+            description: 'Organizational chart with generous spacing for readability',
+            adapter: 'dagre',
+            options: {
+                rankdir: 'TB',
+                nodesep: 100,
+                ranksep: 120,
+                ranker: 'network-simplex',
+            },
+            tags: ['hierarchy', 'org-chart', 'spacious'],
+        },
+        {
+            id: 'tree-left-to-right',
+            name: 'Tree (Left to Right)',
+            description: 'Decision tree or file system hierarchy flowing left to right',
+            adapter: 'elk',
+            options: {
+                algorithm: 'mrtree',
+                'elk.direction': 'RIGHT',
+                'elk.spacing.nodeNode': 60,
+            },
+            tags: ['tree', 'horizontal'],
+        },
+        {
+            id: 'tree-top-to-bottom',
+            name: 'Tree (Top to Bottom)',
+            description: 'Classic tree structure flowing from top to bottom',
+            adapter: 'elk',
+            options: {
+                algorithm: 'mrtree',
+                'elk.direction': 'DOWN',
+                'elk.spacing.nodeNode': 50,
+            },
+            tags: ['tree', 'vertical'],
+        },
+    ],
+};
+/**
+ * Process/Flow Layouts
+ */
+LayoutPresets.FLOW = {
+    name: 'Flow Layouts',
+    description: 'Sequential processes, workflows, and state machines',
+    presets: [
+        {
+            id: 'workflow-horizontal',
+            name: 'Workflow (Horizontal)',
+            description: 'Left-to-right workflow with clear step progression',
+            adapter: 'dagre',
+            options: {
+                rankdir: 'LR',
+                nodesep: 70,
+                ranksep: 150,
+                ranker: 'longest-path',
+            },
+            tags: ['workflow', 'process', 'horizontal'],
+        },
+        {
+            id: 'workflow-vertical',
+            name: 'Workflow (Vertical)',
+            description: 'Top-to-bottom workflow for vertical displays',
+            adapter: 'dagre',
+            options: {
+                rankdir: 'TB',
+                nodesep: 60,
+                ranksep: 100,
+                ranker: 'network-simplex',
+            },
+            tags: ['workflow', 'process', 'vertical'],
+        },
+        {
+            id: 'state-machine',
+            name: 'State Machine',
+            description: 'State machine diagram with optimized edge routing',
+            adapter: 'elk',
+            options: {
+                algorithm: 'layered',
+                'elk.direction': 'RIGHT',
+                'elk.layered.nodePlacement.strategy': 'BRANDES_KOEPF',
+                'elk.layered.crossingMinimization.strategy': 'LAYER_SWEEP',
+                'elk.spacing.nodeNode': 80,
+            },
+            tags: ['state-machine', 'fsm'],
+        },
+    ],
+};
+/**
+ * Network/Graph Layouts
+ */
+LayoutPresets.NETWORK = {
+    name: 'Network Layouts',
+    description: 'Network topologies, dependency graphs, and social networks',
+    presets: [
+        {
+            id: 'force-directed-balanced',
+            name: 'Force-Directed (Balanced)',
+            description: 'Balanced force-directed layout for general networks',
+            adapter: 'elk',
+            options: {
+                algorithm: 'force',
+                'elk.force.repulsion': 150,
+                'elk.force.temperature': 0.5,
+                'elk.force.iterations': 300,
+            },
+            tags: ['network', 'force', 'graph'],
+        },
+        {
+            id: 'force-directed-tight',
+            name: 'Force-Directed (Tight)',
+            description: 'Compact force-directed layout for dense networks',
+            adapter: 'elk',
+            options: {
+                algorithm: 'force',
+                'elk.force.repulsion': 80,
+                'elk.force.temperature': 0.3,
+                'elk.force.iterations': 400,
+            },
+            tags: ['network', 'force', 'compact'],
+        },
+        {
+            id: 'radial-center',
+            name: 'Radial (Center Focus)',
+            description: 'Radial layout with central hub and surrounding nodes',
+            adapter: 'elk',
+            options: {
+                algorithm: 'radial',
+                'elk.radial.radius': 200,
+                'elk.radial.compaction': true,
+            },
+            tags: ['radial', 'hub', 'network'],
+        },
+        {
+            id: 'stress-minimization',
+            name: 'Stress Minimization',
+            description: 'Optimized stress-based layout for complex networks',
+            adapter: 'elk',
+            options: {
+                algorithm: 'stress',
+                'elk.spacing.nodeNode': 100,
+            },
+            tags: ['stress', 'network', 'optimization'],
+        },
+    ],
+};
+/**
+ * Architecture/System Layouts
+ */
+LayoutPresets.ARCHITECTURE = {
+    name: 'Architecture Layouts',
+    description: 'System architectures, microservices, and component diagrams',
+    presets: [
+        {
+            id: 'microservices-layered',
+            name: 'Microservices (Layered)',
+            description: 'Layered microservices architecture with clear separation',
+            adapter: 'elk',
+            options: {
+                algorithm: 'layered',
+                'elk.direction': 'RIGHT',
+                'elk.spacing.nodeNode': 120,
+                'elk.layered.spacing.nodeNodeBetweenLayers': 150,
+                'elk.layered.nodePlacement.strategy': 'NETWORK_SIMPLEX',
+            },
+            tags: ['microservices', 'architecture', 'layered'],
+        },
+        {
+            id: 'component-diagram',
+            name: 'Component Diagram',
+            description: 'Component architecture with dependency flow',
+            adapter: 'dagre',
+            options: {
+                rankdir: 'TB',
+                nodesep: 90,
+                ranksep: 110,
+                ranker: 'network-simplex',
+            },
+            tags: ['components', 'architecture'],
+        },
+        {
+            id: 'data-flow',
+            name: 'Data Flow',
+            description: 'Data pipeline with clear flow direction',
+            adapter: 'dagre',
+            options: {
+                rankdir: 'LR',
+                nodesep: 80,
+                ranksep: 140,
+                ranker: 'longest-path',
+                edgesep: 20,
+            },
+            tags: ['data-flow', 'pipeline'],
+        },
+    ],
+};
+/**
+ * Interactive/Dashboard Layouts
+ */
+LayoutPresets.INTERACTIVE = {
+    name: 'Interactive Layouts',
+    description: 'Layouts optimized for interactive editing and dashboards',
+    presets: [
+        {
+            id: 'dashboard-pinned',
+            name: 'Dashboard (Pinned Header)',
+            description: 'Dashboard layout with pinned header and sidebar',
+            adapter: 'dagre',
+            options: {
+                rankdir: 'TB',
+                nodesep: 70,
+                ranksep: 90,
+            },
+            incrementalOptions: {
+                strategy: 'pin-existing',
+            },
+            tags: ['dashboard', 'interactive', 'pinned'],
+        },
+        {
+            id: 'incremental-minimal',
+            name: 'Incremental (Minimal Movement)',
+            description: 'Add nodes with minimal disruption to existing layout',
+            adapter: 'elk',
+            options: {
+                algorithm: 'layered',
+                'elk.direction': 'DOWN',
+            },
+            incrementalOptions: {
+                strategy: 'minimal-shift',
+                maxShift: 30,
+            },
+            tags: ['incremental', 'minimal-movement'],
+        },
+        {
+            id: 'incremental-proximity',
+            name: 'Incremental (Proximity-Aware)',
+            description: 'Adjust nearby nodes, pin distant ones',
+            adapter: 'dagre',
+            options: {
+                rankdir: 'TB',
+            },
+            incrementalOptions: {
+                strategy: 'proximity-aware',
+                proximityRadius: 250,
+            },
+            tags: ['incremental', 'proximity'],
+        },
+    ],
+};
+//# sourceMappingURL=layout-presets.js.map

package/src/libs/engine/src/layout/layout-quality-extended.d.ts

@@ -0,0 +1,66 @@
+import type { NodeModel } from '../models/NodeModel';
+import type { LinkModel } from '../models/LinkModel';
+import type { LayoutResult } from './layout-adapter.interface';
+import type { PortInfo } from './port-aware-layout.interface';
+export interface PortRespectResult {
+    /** Links whose endpoint travels AGAINST the side its port faces. */
+    violations: number;
+    /** Links that could be judged (both ends resolvable, both nodes placed). */
+    judged: number;
+    /** 100 = every port-constrained edge leaves in the direction its port faces. */
+    score: number;
+    /** Which links violated, for the report. */
+    violatingLinks: string[];
+}
+/**
+ * Does each edge actually leave (and enter) in the direction its port faces?
+ *
+ * This is requirement 1 of the card as a measurement: "an edge leaving a `right`
+ * port should not require the layout to place the target to the left". We check
+ * the sign of the displacement along the port's facing axis. A right port whose
+ * target sits to the left scores a violation.
+ *
+ * Only AUTHOR-DECLARED ports are judged — the four auto-created default ports
+ * carry no authorial intent, so an edge through them can go anywhere (see
+ * port-label-bridge.ts). A graph with no declared ports is vacuously perfect,
+ * which is the correct answer: there is nothing to respect.
+ */
+export declare function assessPortRespect(nodes: NodeModel[], links: LinkModel[], portInfos?: PortInfo[]): PortRespectResult;
+export interface LabelClearanceResult {
+    /** Label boxes that land on top of a node. */
+    overlaps: number;
+    /** Labelled links that could be judged. */
+    judged: number;
+    /** 100 = no label box collides with any node. */
+    score: number;
+    /** Which links' labels collided, for the report. */
+    collidingLinks: string[];
+}
+/**
+ * Would this layout's edge labels sit on top of a node?
+ *
+ * Requirement 2 as a measurement. We are NOT placing labels here — the renderer's
+ * edge optimizer does collision-aware placement at render time, and duplicating it
+ * would be the exact mistake the card warns against. We ask the cheaper question a
+ * LAYOUT can answer: if the label sat at its natural home (the midpoint of the
+ * route the engine computed), would it land on a node? If yes, layout has not left
+ * the optimizer enough room, and this layout is worse than one that did.
+ *
+ * A layout with no labels is vacuously perfect.
+ */
+export declare function assessLabelClearance(nodes: NodeModel[], links: LinkModel[], result: LayoutResult): LabelClearanceResult;
+/**
+ * Total bend count across the routes the layout engine computed.
+ *
+ * Bends are one of the four measures the card names, and they only became
+ * measurable once the adapters stopped discarding their routing output. A layout
+ * whose edges need fewer corners is easier to follow.
+ *
+ * Returns undefined when the engine reported no routes — an ABSENT measurement,
+ * not a zero. Scoring "0 bends" for an engine that simply never told us would
+ * hand it a perfect score for saying nothing, which is how a metric quietly
+ * becomes a lie.
+ */
+export declare function countBends(result: LayoutResult): number | undefined;
+/** The area of the layout's bounding box, in px². Smaller is tighter. */
+export declare function layoutArea(result: LayoutResult): number;

package/src/libs/engine/src/layout/layout-quality-extended.js

@@ -0,0 +1,246 @@
+"use strict";
+// Wave 7 (Auto-layout) — Card 7b: the quality metrics that make auto-selection
+// worth having.
+//
+// `layout-quality-metrics.ts` already scores the classics — crossings, overlap,
+// edge length, distribution, symmetry, aspect ratio — and they are REAL (the code
+// computes them; nothing consumed them, but they work). What it cannot see is the
+// two things this card is about:
+//
+//   • PORT RESPECT   — an edge leaving a node's RIGHT port and travelling LEFT is
+//                      a bad layout, and no generic metric notices. This one does.
+//   • LABEL CLEARANCE— a label box sitting on top of a node is a bad layout, and
+//                      again no generic metric notices.
+//
+// Those two are exactly requirements 1 and 2 of this card, restated as SCORES —
+// which is what lets the auto-selector prefer a port-aware engine on a graph that
+// has ports, instead of us hard-coding "use ELK if ports exist".
+//
+// Plus the two structural measures the card names that the old module lacked:
+// BENDS (from the routing hints the adapters no longer discard) and AREA.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assessPortRespect = assessPortRespect;
+exports.assessLabelClearance = assessLabelClearance;
+exports.countBends = countBends;
+exports.layoutArea = layoutArea;
+const port_label_bridge_1 = require("./port-label-bridge");
+/**
+ * The point half-way along a polyline, by ARC LENGTH.
+ *
+ * Not `points[floor(n/2)]` — that is an array index, not a midpoint, and on a
+ * two-point (straight) route it returns the END point.
+ */
+function midpointAlongPath(points) {
+    if (points.length === 0)
+        return { x: 0, y: 0 };
+    if (points.length === 1)
+        return points[0];
+    const segments = [];
+    let total = 0;
+    for (let i = 1; i < points.length; i++) {
+        const length = Math.hypot(points[i].x - points[i - 1].x, points[i].y - points[i - 1].y);
+        segments.push(length);
+        total += length;
+    }
+    // A degenerate zero-length path has no meaningful midpoint but a real position.
+    if (total === 0)
+        return points[0];
+    let travelled = 0;
+    const half = total / 2;
+    for (let i = 0; i < segments.length; i++) {
+        if (travelled + segments[i] >= half) {
+            const along = segments[i] === 0 ? 0 : (half - travelled) / segments[i];
+            return {
+                x: points[i].x + (points[i + 1].x - points[i].x) * along,
+                y: points[i].y + (points[i + 1].y - points[i].y) * along,
+            };
+        }
+        travelled += segments[i];
+    }
+    return points[points.length - 1];
+}
+/** The centre of a node — the honest anchor for any direction question. */
+function centre(node) {
+    return {
+        x: node.position.x + (node.size.width || 150) / 2,
+        y: node.position.y + (node.size.height || 50) / 2,
+    };
+}
+/**
+ * The direction a port's side FACES, as a unit vector. A `right` port faces +x.
+ * Screen coordinates: +y is down, so `top` faces -y.
+ */
+const SIDE_VECTOR = {
+    right: { x: 1, y: 0 },
+    left: { x: -1, y: 0 },
+    top: { x: 0, y: -1 },
+    bottom: { x: 0, y: 1 },
+};
+/**
+ * Does each edge actually leave (and enter) in the direction its port faces?
+ *
+ * This is requirement 1 of the card as a measurement: "an edge leaving a `right`
+ * port should not require the layout to place the target to the left". We check
+ * the sign of the displacement along the port's facing axis. A right port whose
+ * target sits to the left scores a violation.
+ *
+ * Only AUTHOR-DECLARED ports are judged — the four auto-created default ports
+ * carry no authorial intent, so an edge through them can go anywhere (see
+ * port-label-bridge.ts). A graph with no declared ports is vacuously perfect,
+ * which is the correct answer: there is nothing to respect.
+ */
+function assessPortRespect(nodes, links, portInfos) {
+    var _a, _b, _c, _d;
+    const ports = portInfos !== null && portInfos !== void 0 ? portInfos : (0, port_label_bridge_1.derivePortInfos)(nodes);
+    const portById = new Map(ports.map((p) => [p.id, p]));
+    const nodeById = new Map(nodes.map((n) => [n.id, n]));
+    let violations = 0;
+    let judged = 0;
+    const violatingLinks = [];
+    for (const link of links) {
+        const source = nodeById.get((_a = link.sourceNodeId) !== null && _a !== void 0 ? _a : '');
+        const target = nodeById.get((_b = link.targetNodeId) !== null && _b !== void 0 ? _b : '');
+        if (!source || !target || source === target)
+            continue;
+        const sc = centre(source);
+        const tc = centre(target);
+        // Judge each END against its own port: the source port faces the target, and
+        // the target port faces back at the source.
+        const ends = [
+            [portById.get((_c = link.sourcePortId) !== null && _c !== void 0 ? _c : ''), { x: tc.x - sc.x, y: tc.y - sc.y }],
+            [portById.get((_d = link.targetPortId) !== null && _d !== void 0 ? _d : ''), { x: sc.x - tc.x, y: sc.y - tc.y }],
+        ];
+        let violated = false;
+        for (const [port, toOther] of ends) {
+            if (!(port === null || port === void 0 ? void 0 : port.preferredSide))
+                continue;
+            judged++;
+            const facing = SIDE_VECTOR[port.preferredSide];
+            // Projection of "where the other end is" onto "where this port points".
+            // Negative => the edge has to double back around the node.
+            if (facing.x * toOther.x + facing.y * toOther.y < 0) {
+                violations++;
+                violated = true;
+            }
+        }
+        if (violated)
+            violatingLinks.push(link.id);
+    }
+    return {
+        violations,
+        judged,
+        score: judged === 0 ? 100 : Math.round(((judged - violations) / judged) * 100),
+        violatingLinks,
+    };
+}
+/**
+ * Would this layout's edge labels sit on top of a node?
+ *
+ * Requirement 2 as a measurement. We are NOT placing labels here — the renderer's
+ * edge optimizer does collision-aware placement at render time, and duplicating it
+ * would be the exact mistake the card warns against. We ask the cheaper question a
+ * LAYOUT can answer: if the label sat at its natural home (the midpoint of the
+ * route the engine computed), would it land on a node? If yes, layout has not left
+ * the optimizer enough room, and this layout is worse than one that did.
+ *
+ * A layout with no labels is vacuously perfect.
+ */
+function assessLabelClearance(nodes, links, result) {
+    var _a, _b, _c;
+    let overlaps = 0;
+    let judged = 0;
+    const collidingLinks = [];
+    const nodeById = new Map(nodes.map((n) => [n.id, n]));
+    for (const link of links) {
+        const box = (0, port_label_bridge_1.linkLabelBox)(link);
+        if (!box)
+            continue;
+        // Where would the label naturally sit? Mid-route if the engine gave us a
+        // route, else the midpoint between the two node centres.
+        const route = (_a = result.routing) === null || _a === void 0 ? void 0 : _a.edgeRoutes.get(link.id);
+        let mid;
+        if (route) {
+            // The label's natural home is the point HALFWAY ALONG THE PATH — measured by
+            // arc length, not by array index.
+            //
+            // Picking `pts[floor(n/2)]` (as this did) is wrong in the exact way that
+            // matters: a straight route has two points, so floor(2/2) = 1 selects the
+            // route's END — a point sitting on the target node's border. A label centred
+            // there ALWAYS overlaps that node, so every clean, bend-free edge was scored
+            // as a label collision. That systematically punished the engines that route
+            // best — ELK above all — and so biased auto-selection AGAINST the port-aware
+            // engine this card exists to favour. Found by driving a real graph through
+            // engine.layout(), not by any unit test.
+            mid = midpointAlongPath([route.start, ...route.bends, route.end]);
+        }
+        else {
+            const s = nodeById.get((_b = link.sourceNodeId) !== null && _b !== void 0 ? _b : '');
+            const t = nodeById.get((_c = link.targetNodeId) !== null && _c !== void 0 ? _c : '');
+            if (s && t) {
+                const sc = centre(s);
+                const tc = centre(t);
+                mid = { x: (sc.x + tc.x) / 2, y: (sc.y + tc.y) / 2 };
+            }
+        }
+        if (!mid)
+            continue;
+        judged++;
+        const labelRect = {
+            left: mid.x - box.width / 2,
+            right: mid.x + box.width / 2,
+            top: mid.y - box.height / 2,
+            bottom: mid.y + box.height / 2,
+        };
+        for (const node of nodes) {
+            const nodeRect = {
+                left: node.position.x,
+                right: node.position.x + (node.size.width || 150),
+                top: node.position.y,
+                bottom: node.position.y + (node.size.height || 50),
+            };
+            const hit = labelRect.left < nodeRect.right &&
+                labelRect.right > nodeRect.left &&
+                labelRect.top < nodeRect.bottom &&
+                labelRect.bottom > nodeRect.top;
+            if (hit) {
+                overlaps++;
+                collidingLinks.push(link.id);
+                break; // one collision per label is enough to condemn it
+            }
+        }
+    }
+    return {
+        overlaps,
+        judged,
+        score: judged === 0 ? 100 : Math.round(((judged - overlaps) / judged) * 100),
+        collidingLinks,
+    };
+}
+/**
+ * Total bend count across the routes the layout engine computed.
+ *
+ * Bends are one of the four measures the card names, and they only became
+ * measurable once the adapters stopped discarding their routing output. A layout
+ * whose edges need fewer corners is easier to follow.
+ *
+ * Returns undefined when the engine reported no routes — an ABSENT measurement,
+ * not a zero. Scoring "0 bends" for an engine that simply never told us would
+ * hand it a perfect score for saying nothing, which is how a metric quietly
+ * becomes a lie.
+ */
+function countBends(result) {
+    var _a;
+    const routes = (_a = result.routing) === null || _a === void 0 ? void 0 : _a.edgeRoutes;
+    if (!routes || routes.size === 0)
+        return undefined;
+    let bends = 0;
+    for (const route of routes.values())
+        bends += route.bends.length;
+    return bends;
+}
+/** The area of the layout's bounding box, in px². Smaller is tighter. */
+function layoutArea(result) {
+    const { width, height } = result.bounds;
+    return Math.max(0, width) * Math.max(0, height);
+}
+//# sourceMappingURL=layout-quality-extended.js.map