@grafloria/element 0.3.20 → 0.3.22

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

@@ -1,307 +0,0 @@
-"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/dagre-layout-adapter.d.ts

@@ -1,122 +0,0 @@
-/**
- * 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;
-    }>;
-}