@grafloria/element 0.3.20 → 0.3.22

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

@@ -1,414 +0,0 @@
-"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

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