@grafloria/element 0.3.17 → 0.3.19

package/src/libs/engine/src/layout/component-packing.js

@@ -0,0 +1,307 @@
+"use strict";
+// Wave 7 (Auto-layout) — Card 2: disconnected-component packing.
+//
+// ---------------------------------------------------------------------------
+// THE BUG THIS CLOSES
+// ---------------------------------------------------------------------------
+//
+// Hand dagre a FOREST — three org charts with no edge between them — and it
+// ranks all three roots into rank 0 and interleaves their children. The trees
+// land on top of each other. Every naive layout integration has this bug, and it
+// is the single most visible way an auto-layout feature looks broken: the user
+// presses "arrange" and gets a pile.
+//
+// The fix is not per-algorithm. It is a WRAPPER that sits in front of EVERY
+// registered layout (Card 0's `fromAdapter` and Card 2's portfolio alike):
+//
+//   1. split the graph into connected components,
+//   2. lay each one out INDEPENDENTLY (the algorithm never sees the others, so
+//      it cannot interleave them),
+//   3. normalise each component's coordinates to its own origin,
+//   4. pack the component bounding boxes.
+//
+// ---------------------------------------------------------------------------
+// WHY SHELF PACKING
+// ---------------------------------------------------------------------------
+//
+// The candidates were guillotine/binary-tree packing (the classic
+// texture-atlas algorithm), MAXRECTS, and shelf (a.k.a. strip) packing.
+//
+// Shelf, first-fit-decreasing-height, is what ships here:
+//
+//   • Density. Binary-tree packing wins on paper, but only for boxes with wildly
+//     varying aspect ratios. Graph components are roughly convex blobs with
+//     similar aspects, and FFDH is provably within ~1.7x of optimal strip height
+//     for those — the gap to a jigsaw packer is small.
+//   • READABILITY, which is the real reason. Shelf packing produces ROWS. A
+//     forest of five org charts reads as five charts on two tidy rows. A
+//     binary-tree packer produces a jigsaw: a tall tree wedged into the gap
+//     beside a short one, with no visual logic a human can follow. Denser, and
+//     worse. Layout is a communication medium, not a bin-packing benchmark.
+//   • Determinism is trivial to guarantee (sort by height desc, tie-break on id).
+//
+// The shelf width targets an ASPECT RATIO rather than a fixed width, so the
+// packed result is roughly screen-shaped instead of one endless row.
+//
+// ---------------------------------------------------------------------------
+// THE NO-OP GUARANTEE
+// ---------------------------------------------------------------------------
+//
+// A connected graph has exactly ONE component, and a single component's own
+// layout IS its packing. So the wrapper detects that case and delegates straight
+// through, byte-for-byte untouched. Packing can therefore never regress an
+// existing layout — it only ever fires where the old behaviour was a pile.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_NODE_HEIGHT = exports.DEFAULT_NODE_WIDTH = void 0;
+exports.nodeSize = nodeSize;
+exports.separateOverlappingNodes = separateOverlappingNodes;
+exports.findConnectedComponents = findConnectedComponents;
+exports.packBoxes = packBoxes;
+exports.layoutWithComponentPacking = layoutWithComponentPacking;
+const tslib_1 = require("tslib");
+const rng_1 = require("./rng");
+const overlap_removal_1 = require("./overlap-removal");
+/** Dagre's fallbacks, reused so every layout agrees on what an unsized node is. */
+exports.DEFAULT_NODE_WIDTH = 150;
+exports.DEFAULT_NODE_HEIGHT = 50;
+/** A node's box, with the same defaults every layout in the portfolio uses. */
+function nodeSize(node) {
+    var _a, _b;
+    return {
+        width: ((_a = node.size) === null || _a === void 0 ? void 0 : _a.width) || exports.DEFAULT_NODE_WIDTH,
+        height: ((_b = node.size) === null || _b === void 0 ? void 0 : _b.height) || exports.DEFAULT_NODE_HEIGHT,
+    };
+}
+const DEFAULT_COMPONENT_SPACING = 60;
+const DEFAULT_ASPECT_RATIO = 1.6;
+/**
+ * THE OVERLAP PASS — one rule, one place, for every path that produces positions.
+ *
+ * It lives outside the five algorithms for the same reason packing does: force and
+ * community lay out DIMENSIONLESS POINTS and happily return boxes that intersect
+ * (see overlap-removal.ts). For every layout that does not overlap — dagre, ELK,
+ * tree, grid, circular, radial — it is a no-op, so it costs them one comparison
+ * pass and nothing else.
+ *
+ * wave10/gallery — WHY IT IS EXPORTED, which is the bug.
+ *
+ * It used to be a closure inside `layoutWithComponentPacking`, reachable only from
+ * `adapter.apply()`. But the layout HOST — the path `engine.layout()` actually
+ * takes — does not call `apply()` for a steppable algorithm: it drives
+ * `createRun()`/`step()`/`snapshot()` so the run can report progress and be
+ * cancelled. `snapshot()` was returned RAW.
+ *
+ * Force is the only steppable built-in. So the one algorithm that genuinely needs
+ * overlap removal was the one algorithm that never got it, and
+ * `engine.layout('force')` handed back overlapping node boxes — while every unit
+ * test stayed green, because they all go through `apply()`.
+ *
+ * A demo caught it in the first thirty seconds of being pointed at a real browser.
+ */
+function separateOverlappingNodes(nodes, positions, options = {}) {
+    var _a;
+    if (options.removeOverlaps === false)
+        return positions;
+    return (0, overlap_removal_1.removeOverlaps)(nodes, positions, {
+        spacing: (_a = options.nodeSpacing) !== null && _a !== void 0 ? _a : DEFAULT_COMPONENT_SPACING / 3,
+    });
+}
+/**
+ * Split a graph into connected components.
+ *
+ * Connectivity is UNDIRECTED — an edge joins its endpoints regardless of which
+ * way it points. (A tree whose edges all point away from the root is still one
+ * component; treating edges as directed would shatter it into leaves.)
+ *
+ * Deterministic: nodes are visited in id order and each node's neighbours are
+ * visited in id order, so the components — and the order they come back in —
+ * depend only on the graph, never on insertion order.
+ */
+function findConnectedComponents(nodes, links) {
+    var _a;
+    const ordered = (0, rng_1.inStableOrder)(nodes);
+    const nodeIds = new Set(ordered.map((n) => n.id));
+    // Only links whose BOTH endpoints are present can join anything. A dangling
+    // link (endpoint deleted, or an id that never existed) is dropped here — which
+    // incidentally fixes a live bug in the dagre adapter: `g.setEdge(a, b)` with an
+    // unknown `b` makes dagre INVENT a node `b`, and the phantom's coordinates then
+    // pollute the reported bounds.
+    const realLinks = (0, rng_1.inStableOrder)(links).filter((l) => l.sourceNodeId && l.targetNodeId && nodeIds.has(l.sourceNodeId) && nodeIds.has(l.targetNodeId));
+    const adjacency = new Map();
+    for (const id of nodeIds)
+        adjacency.set(id, []);
+    for (const link of realLinks) {
+        adjacency.get(link.sourceNodeId).push(link.targetNodeId);
+        adjacency.get(link.targetNodeId).push(link.sourceNodeId);
+    }
+    for (const neighbours of adjacency.values())
+        neighbours.sort();
+    const componentOf = new Map();
+    const groups = [];
+    for (const node of ordered) {
+        if (componentOf.has(node.id))
+            continue;
+        const index = groups.length;
+        const members = [];
+        const queue = [node.id];
+        componentOf.set(node.id, index);
+        while (queue.length > 0) {
+            const current = queue.shift();
+            members.push(current);
+            for (const neighbour of (_a = adjacency.get(current)) !== null && _a !== void 0 ? _a : []) {
+                if (!componentOf.has(neighbour)) {
+                    componentOf.set(neighbour, index);
+                    queue.push(neighbour);
+                }
+            }
+        }
+        members.sort();
+        groups.push(members);
+    }
+    const byId = new Map(ordered.map((n) => [n.id, n]));
+    const components = groups.map((members) => ({
+        nodes: members.map((id) => byId.get(id)),
+        links: [],
+    }));
+    for (const link of realLinks) {
+        components[componentOf.get(link.sourceNodeId)].links.push(link);
+    }
+    return components;
+}
+/**
+ * Shelf packing, first-fit-decreasing-height.
+ *
+ * Returns the top-left OFFSET for every box. Boxes are laid left-to-right into
+ * a shelf; when the next box would overflow the target width a new shelf opens
+ * below the tallest box on the current one.
+ */
+function packBoxes(boxes, options = {}) {
+    var _a, _b;
+    const spacing = (_a = options.spacing) !== null && _a !== void 0 ? _a : DEFAULT_COMPONENT_SPACING;
+    const aspectRatio = (_b = options.aspectRatio) !== null && _b !== void 0 ? _b : DEFAULT_ASPECT_RATIO;
+    const offsets = new Map();
+    if (boxes.length === 0)
+        return offsets;
+    // Target width from the total area, so the packed result is roughly the
+    // requested aspect instead of one endless row. Never narrower than the widest
+    // box, or that box could not be placed at all.
+    const totalArea = boxes.reduce((sum, b) => sum + (b.width + spacing) * (b.height + spacing), 0);
+    const widest = Math.max(...boxes.map((b) => b.width));
+    const targetWidth = Math.max(widest, Math.sqrt(totalArea * aspectRatio));
+    // Tallest first — that is what makes shelves tight. Ties break on id, so the
+    // packing is a pure function of the graph.
+    const sorted = [...boxes].sort((a, b) => b.height - a.height || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    let shelfX = 0;
+    let shelfY = 0;
+    let shelfHeight = 0;
+    for (const box of sorted) {
+        if (shelfX > 0 && shelfX + box.width > targetWidth) {
+            shelfY += shelfHeight + spacing;
+            shelfX = 0;
+            shelfHeight = 0;
+        }
+        offsets.set(box.id, { x: shelfX, y: shelfY });
+        shelfX += box.width + spacing;
+        shelfHeight = Math.max(shelfHeight, box.height);
+    }
+    return offsets;
+}
+/** The bounding box of a set of positioned nodes (positions are top-left). */
+function boundsOf(nodes, positions) {
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (const node of nodes) {
+        const p = positions.get(node.id);
+        if (!p)
+            continue;
+        const { width, height } = nodeSize(node);
+        minX = Math.min(minX, p.x);
+        minY = Math.min(minY, p.y);
+        maxX = Math.max(maxX, p.x + width);
+        maxY = Math.max(maxY, p.y + height);
+    }
+    if (!Number.isFinite(minX))
+        return { minX: 0, minY: 0, width: 0, height: 0 };
+    return { minX, minY, width: maxX - minX, height: maxY - minY };
+}
+/**
+ * Run a layout with component packing.
+ *
+ * The wrapper every registered layout goes through. See the header: for a
+ * CONNECTED graph this is a straight delegation (packing a single component is
+ * the identity), so it cannot regress anything; for a disconnected one it is the
+ * difference between a tidy row of trees and a pile.
+ */
+function layoutWithComponentPacking(name_1, fn_1, nodes_1, links_1) {
+    return tslib_1.__awaiter(this, arguments, void 0, function* (name, fn, nodes, links, options = {}) {
+        var _a, _b, _c;
+        const started = Date.now();
+        const components = findConnectedComponents(nodes, links);
+        if (components.length === 0) {
+            return {
+                nodePositions: new Map(),
+                bounds: { x: 0, y: 0, width: 0, height: 0 },
+                metadata: { algorithm: name, executionTime: 0, components: 0 },
+            };
+        }
+        /** Lay one component out, then separate any nodes the algorithm left stacked. */
+        const solve = (component) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+            const result = yield fn(component.nodes, component.links, options);
+            separateOverlappingNodes(component.nodes, result.nodePositions, options);
+            return result;
+        });
+        // THE NO-OP GUARANTEE. One component ⇒ the layout's own output IS the packing.
+        // Delegate untouched (note this passes the FILTERED link list, so a dangling
+        // link can no longer conjure a phantom dagre node).
+        if (components.length === 1) {
+            const result = yield solve(components[0]);
+            return Object.assign(Object.assign({}, result), { metadata: Object.assign(Object.assign({}, ((_a = result.metadata) !== null && _a !== void 0 ? _a : { algorithm: name, executionTime: 0 })), { components: 1 }) });
+        }
+        const spacing = (_c = (_b = options.componentSpacing) !== null && _b !== void 0 ? _b : options.nodeSpacing) !== null && _c !== void 0 ? _c : DEFAULT_COMPONENT_SPACING;
+        // 1. Lay each component out on its own, then normalise it to its own origin.
+        const laidOut = [];
+        for (const component of components) {
+            const result = yield solve(component);
+            // The component's extent is measured from the POSITIONS, not from
+            // `result.bounds` — adapters disagree about bounds (force adds 50px of
+            // padding, dagre does not), and packing against inconsistent boxes leaves
+            // ragged gutters.
+            const b = boundsOf(component.nodes, result.nodePositions);
+            const normalised = new Map();
+            for (const node of component.nodes) {
+                const p = result.nodePositions.get(node.id);
+                if (p)
+                    normalised.set(node.id, { x: p.x - b.minX, y: p.y - b.minY });
+            }
+            laidOut.push({
+                // The component's id is its lowest node id — stable, and it is what makes
+                // the packing order reproducible when two components are the same height.
+                box: { id: component.nodes[0].id, width: b.width, height: b.height },
+                positions: normalised,
+            });
+        }
+        // 2. Pack the boxes and apply the offsets.
+        const offsets = packBoxes(laidOut.map((c) => c.box), { spacing, aspectRatio: options.aspectRatio });
+        const nodePositions = new Map();
+        for (const { box, positions } of laidOut) {
+            const offset = offsets.get(box.id);
+            for (const [id, p] of positions) {
+                nodePositions.set(id, { x: p.x + offset.x, y: p.y + offset.y });
+            }
+        }
+        const all = boundsOf(nodes, nodePositions);
+        return {
+            nodePositions,
+            bounds: { x: all.minX, y: all.minY, width: all.width, height: all.height },
+            metadata: {
+                algorithm: name,
+                executionTime: Date.now() - started,
+                components: components.length,
+                packing: 'shelf',
+            },
+        };
+    });
+}
+//# sourceMappingURL=component-packing.js.map

package/src/libs/engine/src/layout/component-packing.js.map

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

package/src/libs/engine/src/layout/dagre-layout-adapter.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Dagre Layout Adapter
+ *
+ * Integrates the Dagre library for hierarchical graph layouts.
+ * Supports multiple directions, ranking algorithms, and fine-tuned spacing controls.
+ *
+ * @see https://github.com/dagrejs/dagre
+ */
+import { NodeModel } from '../models/NodeModel';
+import { LinkModel } from '../models/LinkModel';
+import { LayoutAdapter, LayoutOptions, LayoutResult } from './layout-adapter.interface';
+import { IncrementalLayoutOptions, IncrementalLayoutResult } from './incremental-layout.interface';
+/**
+ * Dagre-specific layout options
+ */
+export interface DagreLayoutOptions extends LayoutOptions {
+    /** Layout direction */
+    rankdir: 'TB' | 'BT' | 'LR' | 'RL';
+    /** Alignment for rank nodes */
+    align?: 'UL' | 'UR' | 'DL' | 'DR';
+    /** Separation between adjacent nodes on the same rank (pixels) */
+    nodesep: number;
+    /** Separation between adjacent edges (pixels) */
+    edgesep: number;
+    /** Separation between ranks (pixels) */
+    ranksep: number;
+    /** Horizontal margin (pixels) */
+    marginx: number;
+    /** Vertical margin (pixels) */
+    marginy: number;
+    /** Acyclic strategy for breaking cycles */
+    acyclicer?: 'greedy' | undefined;
+    /** Algorithm for assigning ranks to nodes */
+    ranker: 'network-simplex' | 'tight-tree' | 'longest-path';
+    /**
+     * DEEP-GRAPH FAST PATH — rank-count threshold (default 300).
+     *
+     * MEASURED pathology (2026-07): dagre 0.8.5's crossing-minimization phase
+     * builds one layer graph PER RANK, and `buildLayerGraph` scans ALL of
+     * `g.nodes()` each time — O(ranks × V), quadratic in depth (and dagre doubles
+     * the rank count internally to make room for edge labels). A 1000-node chain
+     * spends 865ms of its 955ms total inside `build-layer-graph`; a 2000-node
+     * chain either hangs for >25s or dies outright with a stack overflow in
+     * dagre's RECURSIVE `acyclic.js` dfs (recursion depth = chain length).
+     * Switching `ranker` does NOT help: the rank phase is 31ms of the 955.
+     *
+     * So above this many ranks (estimated by an O(V+E) iterative, cycle-safe
+     * longest-path pass) the adapter bypasses `dagre.layout` entirely and runs
+     * its own linear hierarchical placement: longest-path ranks, barycenter
+     * ordering sweeps, centered coordinates. Deep graphs have few nodes per rank,
+     * which is exactly where that simple scheme matches dagre's quality — and
+     * where dagre itself is unusable. Below the threshold nothing changes:
+     * dagre runs with the configured `ranker` and produces identical output.
+     *
+     * Set to `Infinity` to force full dagre regardless of depth.
+     */
+    deepRankThreshold?: number;
+}
+/**
+ * Dagre Layout Adapter
+ *
+ * Provides hierarchical layout using the Dagre library.
+ * Converts between Grafloria's node/link model and Dagre's graph structure.
+ */
+export declare class DagreLayoutAdapter implements LayoutAdapter {
+    readonly name = "dagre";
+    /**
+     * Apply Dagre layout to nodes and links
+     *
+     * @param nodes - Nodes to layout
+     * @param links - Links connecting the nodes
+     * @param options - Dagre layout options
+     * @returns Layout result with positions and metadata
+     */
+    apply(nodes: NodeModel[], links: LinkModel[], options?: Partial<DagreLayoutOptions>): Promise<LayoutResult>;
+    /**
+     * The classic path: hand the graph to `dagre.layout` and read positions,
+     * ranks and edge polylines back. Behavior-identical to the pre-fast-path
+     * adapter — shallow graphs must lay out byte-for-byte the same.
+     */
+    private runDagre;
+    /**
+     * DEEP-GRAPH FAST PATH — O(V + E) hierarchical placement for graphs whose
+     * rank count exceeds `deepRankThreshold`, where `dagre.layout` goes quadratic
+     * (or stack-overflows — see the option's doc comment for the measurements).
+     *
+     * Longest-path ranks (already computed for the depth estimate), a few
+     * deterministic barycenter ordering sweeps, then centered coordinates:
+     * each rank is centered on the cross axis, ranks advance by
+     * max-node-extent + ranksep (+ reserved label space when labelAware).
+     * A deep chain comes out as dagre would draw it: one straight centered
+     * column, `ranksep` apart.
+     */
+    private runDeepFastPath;
+    /**
+     * Validate Dagre layout options
+     *
+     * @param options - Options to validate
+     * @returns true if valid, false otherwise
+     */
+    validateOptions(options: Partial<DagreLayoutOptions>): boolean;
+    /**
+     * Calculate bounding box for all laid-out nodes
+     *
+     * @param positions - Map of node positions
+     * @param nodes - Array of nodes
+     * @returns Bounding box
+     */
+    private calculateBounds;
+    /**
+     * Apply incremental layout - layout new nodes while preserving existing positions
+     *
+     * @param nodes - Array of all nodes (existing + new)
+     * @param links - Array of all links
+     * @param incrementalOptions - Options for incremental layout
+     * @param layoutOptions - Base layout options
+     * @returns Layout result with positions and incremental statistics
+     */
+    applyIncremental(nodes: NodeModel[], links: LinkModel[], incrementalOptions: IncrementalLayoutOptions, layoutOptions?: Partial<DagreLayoutOptions>): Promise<LayoutResult & {
+        incremental: IncrementalLayoutResult;
+    }>;
+}