@grafloria/element 0.3.18 → 0.3.20

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

@@ -0,0 +1,414 @@
+"use strict";
+// Wave 7 (Auto-layout) — Card 0: the unified layout API and engine registry.
+//
+// ---------------------------------------------------------------------------
+// WHAT THE AUDIT GOT RIGHT, AND THE ONE THING IT GOT WRONG
+// ---------------------------------------------------------------------------
+//
+// Right: full-graph layout was UNREACHABLE. `DiagramEngine.applyLayout()` throws
+// unless you first call `setLayoutService()` — and nothing in the entire codebase
+// ever called it (the only mention is a doc comment in layout/index.ts). So dagre,
+// ELK, force, spectral and community — thousands of lines, several of them
+// untested — could not be run from the engine at all. That is the whole "layout is
+// fragmented" finding, and this file is the fix: ONE entry point, `engine.layout()`,
+// with the built-ins already registered.
+//
+// Wrong: the audit called LayoutManager and LayoutService "two parallel layout
+// stacks" and asked for them to be collapsed. They are not parallel — they solve
+// DIFFERENT problems, and merging them would have been a category error (the same
+// one Wave 3 corrected about the two IRenderer interfaces):
+//
+//   • LayoutManager  → `calculatePlacement(node, viewport)`. Given ONE newly-added
+//                      node, where should it go so it doesn't overlap anything?
+//                      An incremental PLACEMENT strategy. Runs on node:added.
+//   • LayoutAdapter  → `apply(nodes, links)`. Given a WHOLE GRAPH, where does
+//                      everything go? A full-graph LAYOUT algorithm.
+//
+// Collapsing them would have forced a single-node placer to pretend it can lay out
+// a graph, or a graph layout engine to pretend a one-node call is meaningful. They
+// stay separate, and this file documents the boundary instead of erasing it.
+//
+// ---------------------------------------------------------------------------
+// THE CONTRACT
+// ---------------------------------------------------------------------------
+//
+//   engine.layout('dagre', { direction: 'LR' })   // named algorithm, one schema
+//   engine.layout()                                // zero-config default (Card 1)
+//
+// and it is DETERMINISTIC and IDEMPOTENT:
+//
+//   same graph + same seed  =>  byte-identical coordinates
+//   layout(g); layout(g)    =>  the second run changes nothing
+//
+// Determinism is not a nicety here. Without it: layouts cannot have golden tests,
+// a saved diagram moves every time you reopen it, and the mental-map card (#6) is
+// undefinable — you cannot minimise movement against a baseline that itself moves.
+// See rng.ts.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_LAYOUT_NAME = exports.LayoutRegistry = void 0;
+exports.fromAdapter = fromAdapter;
+exports.createLayout = createLayout;
+exports.translateOptions = translateOptions;
+exports.createBuiltInLayoutAdapters = createBuiltInLayoutAdapters;
+exports.createBuiltInLayoutFactories = createBuiltInLayoutFactories;
+exports.createAutoLayout = createAutoLayout;
+exports.packAdapter = packAdapter;
+exports.createPortfolioLayouts = createPortfolioLayouts;
+exports.createDefaultLayoutRegistry = createDefaultLayoutRegistry;
+exports.runLayout = runLayout;
+const tslib_1 = require("tslib");
+const rng_1 = require("./rng");
+const dagre_layout_adapter_1 = require("./dagre-layout-adapter");
+const elk_layout_adapter_1 = require("./elk-layout-adapter");
+const force_layout_adapter_1 = require("./force-layout-adapter");
+const spectral_layout_adapter_1 = require("./spectral-layout-adapter");
+const community_layout_adapter_1 = require("./community-layout-adapter");
+const layout_auto_select_1 = require("./layout-auto-select");
+// Wave 7 Card 2: the portfolio, and the packing wrapper every layout goes through.
+const component_packing_1 = require("./component-packing");
+const portfolio_layouts_1 = require("./portfolio-layouts");
+const tree_layout_1 = require("./tree-layout");
+// Wave 7 Cards 1 & 5: our own layered (Sugiyama) engine.
+const layered_layout_1 = require("./sugiyama/layered-layout");
+/**
+ * The named-algorithm registry.
+ *
+ * Registration is a plain map, deliberately: extension-registered layouts (via
+ * the wave-6 ExtensionHost) and the built-ins are the same kind of thing, and a
+ * host must be able to replace a built-in — `register()` returns a disposer that
+ * RESTORES what was there before rather than deleting the name, which is the
+ * convention wave 6 established for every other registry.
+ */
+class LayoutRegistry {
+    constructor() {
+        this.engines = new Map();
+    }
+    register(engine) {
+        const previous = this.engines.get(engine.name);
+        this.engines.set(engine.name, engine);
+        return () => {
+            if (previous)
+                this.engines.set(engine.name, previous);
+            else
+                this.engines.delete(engine.name);
+        };
+    }
+    get(name) {
+        return this.engines.get(name);
+    }
+    has(name) {
+        return this.engines.has(name);
+    }
+    /** Registered names, sorted — a stable list is part of being deterministic. */
+    names() {
+        return [...this.engines.keys()].sort();
+    }
+    /**
+     * Wave 7 Card 4: name → adapter, for every registered engine that exposes one.
+     *
+     * This is what nested (compound) layout resolves a container's algorithm
+     * against — so `group.subgraphLayout = { algorithm: 'force' }` works, and so
+     * does an algorithm an extension registered, rather than only the hard-coded
+     * dagre|elk pair.
+     */
+    adapters() {
+        var _a;
+        const out = {};
+        for (const name of this.names()) {
+            const adapter = (_a = this.engines.get(name)) === null || _a === void 0 ? void 0 : _a.adapter;
+            if (adapter)
+                out[name] = adapter;
+        }
+        return out;
+    }
+}
+exports.LayoutRegistry = LayoutRegistry;
+/**
+ * Wrap a legacy `LayoutAdapter` (dagre/elk/force/spectral/community) as a
+ * registry engine.
+ *
+ * This is the adaptor that finally makes the orphaned stack reachable. It also
+ * does the two things the old path never did:
+ *
+ *   1. CANONICAL INPUT ORDER — nodes and links are sorted by id before they
+ *      reach the algorithm. A seeded PRNG alone does not give reproducibility:
+ *      map iteration follows insertion order, so an authored diagram and the same
+ *      diagram loaded from JSON feed the algorithm in different orders and
+ *      diverge even with the same seed. (This is the subtle half of Card 0, and
+ *      the half that a naive "just seed the RNG" fix misses.)
+ *
+ *   2. OPTION NORMALISATION — `direction`/`nodeSpacing`/`rankSpacing` are
+ *      translated into whatever the adapter calls them.
+ */
+function fromAdapter(adapter) {
+    // Card 2's createLayout() routes every adapter through COMPONENT PACKING (a
+    // provable no-op for a connected graph, so it cannot regress anything) and does
+    // the canonical-ordering + option-translation Card 0 established. The `adapter`
+    // field is kept because Card 7's auto-selector reads it to tell whether a
+    // candidate engine is port-aware.
+    // The EXPOSED adapter is packing-wrapped too, and that is load-bearing.
+    //
+    // Two resolvers hand algorithms to the layout host: the engine's inline one reads
+    // `registry.get(name).adapter` (so a runtime-registered layout is honoured), and
+    // the worker's builds by name from the factories (functions cannot cross
+    // postMessage). If only one of them packs, the SAME layout behaves differently on
+    // the two paths — and it did: a disconnected graph laid its components on top of
+    // each other whenever the engine resolved through the registry. Card 2's forest
+    // tests caught it the moment these branches met.
+    //
+    // Object.create, not a spread: spreading a class instance copies only its OWN
+    // properties, so step()/snapshot() — prototype methods — vanish and a steppable
+    // algorithm silently stops being cancellable.
+    const packed = packAdapter(adapter);
+    return Object.assign(Object.assign({}, createLayout(adapter.name, (nodes, links, options) => adapter.apply(nodes, links, translateOptions(adapter.name, options)))), { adapter: packed });
+}
+/**
+ * Turn a raw graph-layout function into a registered layout.
+ *
+ * The two things EVERY layout in the engine gets here, whether it is a wrapped
+ * third-party adapter or one of Card 2's own:
+ *
+ *   1. CANONICAL INPUT ORDER (Card 0) — sorted by id, so the same graph laid out
+ *      after a save/load round-trip produces the same coordinates.
+ *   2. COMPONENT PACKING (Card 2) — a disconnected graph is split, laid out
+ *      component by component, and the boxes are packed. Implemented ONCE, here,
+ *      rather than five times in five algorithms. It is a no-op for a connected
+ *      graph, so it cannot regress an existing layout.
+ */
+function createLayout(name, fn) {
+    return {
+        name,
+        apply(diagram, options) {
+            return (0, component_packing_1.layoutWithComponentPacking)(name, fn, (0, rng_1.inStableOrder)(diagram.getNodes()), (0, rng_1.inStableOrder)(diagram.getLinks()), options);
+        },
+        // Every registered layout also exposes the adapter-shaped (nodes, links) form.
+        //
+        // MERGE NOTE (Cards 2 + 4): the nested/container path lays out SUBSETS — a
+        // container's members — not whole diagrams, so it needs `apply(nodes, links)`
+        // rather than `apply(diagram)`. It reached for `registry.adapters()`, which only
+        // knew about the five legacy LayoutAdapters; the moment Card 2 promoted `force`
+        // (and added tree/grid/circular/radial) to first-class layouts built from a raw
+        // graph function, they vanished from that map and a container could no longer be
+        // laid out with them. Exposing the graph function here makes Card 4's promise —
+        // "a container can use ANY registered engine" — actually true, including for
+        // anything an extension host registers.
+        adapter: {
+            name,
+            apply: (nodes, links, options) => (0, component_packing_1.layoutWithComponentPacking)(name, fn, nodes, links, (options !== null && options !== void 0 ? options : {})),
+            applyIncremental: () => {
+                throw new Error(`Layout '${name}' does not support applyIncremental.`);
+            },
+            validateOptions: () => true,
+        },
+    };
+}
+/**
+ * One vocabulary in, each engine's dialect out.
+ *
+ * The adapters disagree about names for the same concept — dagre says `rankdir`,
+ * `nodesep`, `ranksep`; ELK says `elk.direction` with words instead of letters.
+ * Making callers know which engine they are talking to is exactly the "you cannot
+ * be best-in-class with inconsistent options" problem Card 0 names.
+ *
+ * Exported for Card 4: nested layout runs a DIFFERENT engine per container
+ * (`group.subgraphLayout.algorithm`), so it has to translate the one vocabulary
+ * per level rather than once up front. Reusing this is what stops the nested
+ * path from quietly forking the options schema.
+ */
+function translateOptions(engine, options) {
+    var _a;
+    const out = Object.assign({}, options);
+    out['seed'] = (_a = options.seed) !== null && _a !== void 0 ? _a : rng_1.DEFAULT_LAYOUT_SEED;
+    // Card 3: the run controls are the HOST's business, not the algorithm's, and
+    // `signal`/`onProgress` are not structured-clone-safe — posting one to a real
+    // Worker throws DataCloneError. They must not reach the wire.
+    delete out['signal'];
+    delete out['onProgress'];
+    delete out['timeBudgetMs'];
+    delete out['sliceMs'];
+    delete out['stopAfterIteration'];
+    const { direction, nodeSpacing, rankSpacing } = options;
+    if (engine === 'dagre') {
+        if (direction)
+            out['rankdir'] = direction;
+        if (nodeSpacing !== undefined)
+            out['nodesep'] = nodeSpacing;
+        if (rankSpacing !== undefined)
+            out['ranksep'] = rankSpacing;
+    }
+    else if (engine === 'elk') {
+        if (direction) {
+            out['elk.direction'] = {
+                TB: 'DOWN',
+                BT: 'UP',
+                LR: 'RIGHT',
+                RL: 'LEFT',
+            }[direction];
+        }
+        if (nodeSpacing !== undefined)
+            out['elk.spacing.nodeNode'] = nodeSpacing;
+        if (rankSpacing !== undefined)
+            out['elk.layered.spacing.nodeNodeBetweenLayers'] = rankSpacing;
+    }
+    return out;
+}
+/**
+ * The layouts that ship in the box.
+ *
+ * Registered eagerly by `DiagramEngine.getLayoutRegistry()`, so `engine.layout()`
+ * works with no setup call — which is the entire point of Card 0. ELK is included
+ * even though it resolves asynchronously; the adapter already handles that.
+ */
+function createBuiltInLayoutAdapters() {
+    return [...createBuiltInLayoutFactories().values()].map((make) => make());
+}
+/**
+ * The same built-ins, as FACTORIES — construct one only when it is asked for.
+ *
+ * Wave 7 Card 3, and this is not a micro-optimisation: it is a crash fix that
+ * only a live run could have found. Constructing every adapter up-front means
+ * constructing ELK, and `new ELKLayoutAdapter()` calls `new ElkConstructor()`,
+ * which tries to spawn elkjs's OWN nested Worker. Inside a Web Worker that
+ * throws `_Worker is not a constructor` — so the layout worker died on the line
+ * that started it, before it had read a single message, and every request to it
+ * hung forever.
+ *
+ * Nothing caught it because in Node (where the unit tests live) elkjs constructs
+ * happily. It reproduced the instant a real Worker ran in a real browser.
+ *
+ * Laziness makes the worker pay only for the algorithm actually requested, so
+ * asking for `force` no longer detonates on ELK's behalf.
+ */
+function createBuiltInLayoutFactories() {
+    return new Map([
+        ['dagre', () => new dagre_layout_adapter_1.DagreLayoutAdapter()],
+        ['elk', () => new elk_layout_adapter_1.ELKLayoutAdapter()],
+        ['force', () => new force_layout_adapter_1.ForceLayoutAdapter()],
+        ['spectral', () => new spectral_layout_adapter_1.SpectralLayoutAdapter()],
+        ['community', () => new community_layout_adapter_1.CommunityLayoutAdapter()],
+    ]);
+}
+/**
+ * The layout `engine.layout()` runs when the caller names none.
+ *
+ * Wave 7 — Card 7b: this is `'auto'`, not a fixed algorithm. A zero-config caller
+ * gets a bake-off (see layout-auto-select.ts) rather than whichever algorithm
+ * happened to be hard-coded, and can read back WHY it chose what it chose. Naming
+ * it here rather than inline in DiagramEngine keeps the decision in one place —
+ * a card that wants a different default (a Sugiyama, say) changes this constant
+ * and nothing else.
+ */
+exports.DEFAULT_LAYOUT_NAME = layout_auto_select_1.AUTO_LAYOUT_NAME;
+/**
+ * The auto-selecting layout, as a registry engine.
+ *
+ * It is registered under a name like any other layout — deliberately. Card 0's
+ * contract is that `engine.layout(name)` is THE entry point, so auto-selection had
+ * to compose with the registry rather than fork a second one. It takes the registry
+ * it lives in so its candidate pool is whatever is actually registered, including
+ * layouts an extension host added after start-up.
+ */
+function createAutoLayout(registry) {
+    return {
+        name: layout_auto_select_1.AUTO_LAYOUT_NAME,
+        apply: (diagram, options) => (0, layout_auto_select_1.autoSelectLayout)(diagram, registry, options),
+    };
+}
+/**
+ * Card 2's portfolio: the diagram shapes a serious engine has to be able to draw.
+ *
+ * `force` is in here as well as in the adapter list, and it deliberately WINS —
+ * it is registered second. The adapter's physics is reused unchanged (see
+ * portfolio-layouts.ts); what the portfolio version adds is component packing and
+ * the shared options vocabulary, which is the difference between "we expose a
+ * force adapter" and "force is a first-class layout".
+ */
+/**
+ * Component-packing wrapper, preserving the algorithm underneath.
+ *
+ * Object.create, not a spread: spreading a class instance copies only its OWN
+ * properties, so `step()`/`snapshot()` — which live on the prototype — vanish,
+ * `isSteppable()` goes false, and a long-running algorithm silently stops being
+ * cancellable. Delegating through the prototype keeps it whole and overrides only
+ * `apply`, which is the one thing packing needs to intercept.
+ */
+function packAdapter(adapter) {
+    const packed = Object.create(adapter);
+    packed.apply = (nodes, links, options) => (0, component_packing_1.layoutWithComponentPacking)(adapter.name, (n, l, o) => adapter.apply(n, l, translateOptions(adapter.name, o)), nodes, links, (options !== null && options !== void 0 ? options : {}));
+    return packed;
+}
+function createPortfolioLayouts() {
+    // Card 2's `force` overrides the raw adapter — but it must keep the adapter's
+    // STEPPABLE physics reachable, or Card 3 loses progress, cancellation and partial
+    // results on the one algorithm that can actually be interrupted mid-run. (The
+    // portfolio version delegates to exactly this simulation; what it adds is packing
+    // and the shared options vocabulary.)
+    const steppableForce = packAdapter(new force_layout_adapter_1.ForceLayoutAdapter());
+    return [
+        createLayout('tree', (nodes, links, options) => (0, tree_layout_1.treeLayout)(nodes, links, options)),
+        createLayout('grid', (nodes, links, options) => (0, portfolio_layouts_1.gridLayout)(nodes, links, options)),
+        createLayout('circular', (nodes, links, options) => (0, portfolio_layouts_1.circularLayout)(nodes, links, options)),
+        createLayout('radial', (nodes, links, options) => (0, portfolio_layouts_1.radialLayout)(nodes, links, options)),
+        Object.assign(Object.assign({}, createLayout('force', (nodes, links, options) => (0, portfolio_layouts_1.forceLayout)(nodes, links, options))), { adapter: steppableForce }),
+    ];
+}
+/**
+ * The registry `engine.layout()` runs against.
+ *
+ * Registration order is the override order, and it is deliberate:
+ *
+ *   1. the five legacy ADAPTERS (dagre/elk/force/spectral/community) — Card 0 made
+ *      them reachable at all;
+ *   2. the PORTFOLIO (tree/grid/circular/radial/force) — Card 2. `force` appears in
+ *      both and the portfolio's wins, because it adds component packing and the
+ *      shared options vocabulary: the difference between "we expose a force adapter"
+ *      and "force is a first-class layout";
+ *   3. LAYERED (Cards 1 & 5) — our own Sugiyama. The only engine that honours
+ *      semantic constraints DURING ranking and ordering, which is why the
+ *      mental-map/incremental path (Card 6) names it explicitly;
+ *   4. AUTO (Card 7b) — the scored bake-off. Registered last because it takes the
+ *      registry, so its candidate pool is whatever is actually in it — including
+ *      `layered`, and including anything an extension host adds after start-up.
+ */
+function createDefaultLayoutRegistry() {
+    const registry = new LayoutRegistry();
+    for (const adapter of createBuiltInLayoutAdapters()) {
+        registry.register(fromAdapter(adapter));
+    }
+    for (const layout of createPortfolioLayouts()) {
+        registry.register(layout);
+    }
+    registry.register((0, layered_layout_1.createLayeredLayout)('layered'));
+    registry.register(createAutoLayout(registry));
+    return registry;
+}
+/**
+ * Run a named layout against a diagram and COMMIT the result.
+ *
+ * The single place positions are written back, shared by `DiagramEngine.layout()`
+ * and by the preset applicator. `setPosition()` — never a raw write to
+ * `node.position` — because the spatial index, the routing obstacle map and the
+ * renderer all hang off the change event it emits. (Wave 5 lost a day to the
+ * mirror image of this: the engine subscribed to `node.on('position')` while the
+ * model emits `change:position`, so the obstacle map never updated and routes were
+ * computed against stale geometry.)
+ */
+function runLayout(registry_1, diagram_1, name_1) {
+    return tslib_1.__awaiter(this, arguments, void 0, function* (registry, diagram, name, options = {}) {
+        var _a, _b;
+        const layout = registry.get(name);
+        if (!layout) {
+            throw new Error(`Unknown layout '${name}'. Registered layouts: ${registry.names().join(', ')}`);
+        }
+        const seed = (_a = options.seed) !== null && _a !== void 0 ? _a : rng_1.DEFAULT_LAYOUT_SEED;
+        const result = yield layout.apply(diagram, Object.assign(Object.assign({}, options), { seed }));
+        for (const [nodeId, position] of result.nodePositions) {
+            (_b = diagram.getNode(nodeId)) === null || _b === void 0 ? void 0 : _b.setPosition(position.x, position.y);
+        }
+        // Card 3's run-status fields. runLayout is the SYNCHRONOUS apply-and-commit path
+        // (the preset applicator's route); it runs an algorithm to completion on this
+        // thread, so it is never partial. The worker/host path reports the real numbers.
+        return Object.assign(Object.assign({}, result), { algorithm: name, seed, partial: false, iteration: 1, totalIterations: 1 });
+    });
+}
+//# sourceMappingURL=layout-registry.js.map

package/src/libs/engine/src/layout/layout.service.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Layout Service
+ *
+ * Central service for managing layout adapters and applying layouts to diagrams.
+ * Handles adapter registration, layout application, animation, and viewport fitting.
+ */
+import { DiagramModel } from '../models/DiagramModel';
+import { LayoutAdapter, LayoutOptions, LayoutResult } from './layout-adapter.interface';
+/**
+ * Configuration for applying a layout
+ */
+export interface ApplyLayoutConfig {
+    /** Layout adapter to use (name or instance) */
+    adapter: 'dagre' | 'elk' | LayoutAdapter;
+    /** Layout-specific options */
+    options?: Partial<LayoutOptions>;
+    /** Whether to animate to new positions */
+    animate?: boolean;
+    /** Animation duration in milliseconds */
+    animationDuration?: number;
+    /** Whether to fit viewport after layout */
+    fit?: boolean;
+    /** Canvas dimensions for viewport fitting */
+    canvasDimensions?: {
+        width: number;
+        height: number;
+    };
+    /** Progress callback for long-running layouts */
+    onProgress?: (progress: number) => void;
+}
+/**
+ * Layout Service
+ *
+ * Manages layout adapters and provides a unified API for applying layouts.
+ * Can be used as a singleton or instantiated per diagram.
+ */
+export declare class LayoutService {
+    private adapters;
+    constructor();
+    /**
+     * Register a custom layout adapter
+     *
+     * @param adapter - Layout adapter to register
+     */
+    registerAdapter(adapter: LayoutAdapter): void;
+    /**
+     * Get a registered adapter by name
+     *
+     * @param name - Name of the adapter
+     * @returns The adapter, or undefined if not found
+     */
+    getAdapter(name: string): LayoutAdapter | undefined;
+    /**
+     * Get all registered adapter names
+     *
+     * @returns Array of adapter names
+     */
+    getAdapterNames(): string[];
+    /**
+     * Apply layout to diagram
+     *
+     * @param diagram - Diagram to layout
+     * @param config - Layout configuration
+     * @returns Layout result with positions and metadata
+     */
+    applyLayout(diagram: DiagramModel, config: ApplyLayoutConfig): Promise<LayoutResult>;
+    /**
+     * Apply positions immediately without animation
+     *
+     * @param diagram - Diagram to update
+     * @param positions - Map of node IDs to positions
+     */
+    private applyPositions;
+    /**
+     * 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
+     */
+    private animateToPositions;
+    /**
+     * 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
+     */
+    private regenerateLinkPaths;
+}
+/**
+ * Singleton instance of LayoutService
+ *
+ * Can be used across the application for convenience.
+ */
+export declare const layoutService: LayoutService;