@grafloria/element 0.3.18 → 0.3.20

package/src/libs/engine/src/layout/layout-registry.d.ts

@@ -0,0 +1,309 @@
+import type { DiagramModel } from '../models/DiagramModel';
+import type { LayoutAdapter, LayoutOptions, LayoutResult } from './layout-adapter.interface';
+import type { LayoutRunOptions, LayoutStopReason } from './layout-host';
+import { type LayoutSelectionReport } from './layout-auto-select';
+import { type GraphLayoutFn } from './component-packing';
+import { type FlowDirection } from './tree-layout';
+/**
+ * The one options schema. Adapter-specific knobs still ride in `options`, but
+ * everything that is common to all layouts is named here so callers do not have
+ * to learn five different vocabularies.
+ */
+export interface UnifiedLayoutOptions extends Partial<LayoutOptions>, LayoutRunOptions {
+    /**
+     * Adapter-specific knobs (`iterations`, `repulsion`, `align`, …) ride along here.
+     *
+     * Card 0's comment PROMISED this — "adapter-specific knobs still ride in
+     * `options`" — but the type did not allow it, so `engine.layout('force',
+     * { iterations: 500 })` was a compile error and the only way to reach half of
+     * force's own options was a cast. A vocabulary that cannot say what its
+     * engines can do is not a unified vocabulary; this is the promise made good.
+     */
+    [key: string]: unknown;
+    /**
+     * Seed for any algorithm that uses randomness (force, spectral, community).
+     * Defaults to a FIXED constant — so an author who never thinks about seeds
+     * still gets the same picture every time. Randomness is opt-in.
+     */
+    seed?: number;
+    /**
+     * Primary flow direction, normalised across engines: dagre calls it `rankdir`,
+     * ELK calls it `elk.direction`, and the two disagree about spelling. Callers
+     * say `direction` and the registry translates.
+     */
+    direction?: FlowDirection;
+    /** Space between nodes in the same rank/row. */
+    nodeSpacing?: number;
+    /** Space between ranks/layers. */
+    rankSpacing?: number;
+    /**
+     * Lay groups out as CONTAINERS: each group's contents are arranged
+     * recursively (deepest first), the container is auto-sized to fit them, and
+     * the parent level then arranges containers as COMPOUND NODES — with edges
+     * that cross a container boundary induced onto the compound nodes so the
+     * containers land next to the things they actually connect to.
+     *
+     * Defaults to TRUE whenever the diagram has groups, because the flat path is
+     * not merely less good on a grouped diagram — it is WRONG: it interleaves
+     * members of different groups and never updates a single group frame, so the
+     * containers stay behind, pointing at where their members used to be.
+     * Pass `nested: false` for the old flat behaviour.
+     */
+    nested?: boolean;
+    /** Fallback inner padding for containers that carry no `padding` of their own. */
+    containerPadding?: number;
+    /** Gap between compound units when a level falls back to the built-in grid. */
+    groupSpacing?: number;
+    /**
+     * Gap between packed disconnected components. Defaults to `nodeSpacing`.
+     * See component-packing.ts — this applies to EVERY layout, not just the new
+     * ones, because "lay out a forest and the trees land on top of each other" is
+     * an adapter-agnostic bug.
+     */
+    componentSpacing?: number;
+    /** Target width/height of the packed result. 1.6 ≈ a landscape screen. */
+    aspectRatio?: number;
+    /**
+     * Push nodes apart if the algorithm left them overlapping. Default true.
+     *
+     * A no-op for every layout that does not overlap (dagre, ELK, tree, grid,
+     * circular, radial) — but force and community lay out DIMENSIONLESS POINTS and
+     * genuinely do return intersecting boxes. See overlap-removal.ts. Opt out only
+     * if you want the algorithm's raw output.
+     */
+    removeOverlaps?: boolean;
+    /** grid: number of columns. Defaults to ceil(sqrt(n)). */
+    columns?: number;
+    /** tree/radial: the node to root the tree / centre the rings on. */
+    rootId?: string;
+    /**
+     * tree: per-branch direction. The subtree rooted at each listed node flows its
+     * own way instead of the tree's `direction` — a mind map is
+     * `{ 'left-branch': 'RL', 'right-branch': 'LR' }`.
+     */
+    branchDirections?: Record<string, FlowDirection>;
+}
+/** What a registered layout engine must be able to do. */
+export interface RegisteredLayout {
+    readonly name: string;
+    apply(diagram: DiagramModel, options: UnifiedLayoutOptions): Promise<LayoutResult>;
+    /**
+     * The underlying node/link algorithm, when the engine has one.
+     *
+     * TWO cards landed on this one field, for two reasons that turn out to be the
+     * same reason — a `LayoutAdapter` is a pure function of (nodes, links), and a
+     * `RegisteredLayout` is an opaque closure over a whole DiagramModel:
+     *
+     *   • Card 4 (nested) arranges the contents of ONE container at a time, so it
+     *     needs an engine it can hand a node/link SUBSET to. `apply(diagram)` cannot
+     *     express "just these nodes". Exposing the adapter is what lets a container
+     *     be laid out by ANY registered engine — including an extension's — instead
+     *     of the closed dagre|elk pair the wave-5 service hard-coded.
+     *
+     *   • Card 3 (worker) needs an algorithm it can SHIP ACROSS A THREAD BOUNDARY.
+     *     A closure cannot be posted anywhere, so layouts registered that way run
+     *     inline — by physics, not by policy. Exposing the adapter is what lets the
+     *     host tell the two apart instead of guessing.
+     */
+    readonly adapter?: LayoutAdapter;
+}
+/** How a layout engine reports back. */
+export interface UnifiedLayoutResult extends LayoutResult {
+    /** The algorithm that actually ran (useful once auto-selection lands, Card 7). */
+    algorithm: string;
+    /** The seed used — so a pleasing random layout can be reproduced on demand. */
+    seed: number;
+    /**
+     * Wave 7 — Card 7b. Present when the AUTO layout ran: which algorithm it chose,
+     * why, and what every other candidate scored. An auto-selector that cannot show
+     * its working is a support ticket.
+     */
+    selection?: LayoutSelectionReport;
+    /**
+     * True when the run was cut short (cancelled, or out of time budget) and this
+     * is the BEST-SO-FAR answer rather than a finished one.
+     *
+     * Flagged rather than thrown away: a force layout stopped at 200 of 300
+     * iterations is a perfectly usable picture, and discarding it is the
+     * difference between a tool that feels alive and one that feels broken. But
+     * the caller has to be able to TELL — silently returning a partial layout as
+     * if it were final is how a "finished" diagram ends up half-settled.
+     */
+    partial: boolean;
+    /** Why it stopped early, when it did. */
+    reason?: LayoutStopReason;
+    /** Iterations actually completed. */
+    iteration: number;
+    /** Iterations the algorithm would have run, left alone. */
+    totalIterations: number;
+}
+/**
+ * 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.
+ */
+export declare class LayoutRegistry {
+    private readonly engines;
+    register(engine: RegisteredLayout): () => void;
+    get(name: string): RegisteredLayout | undefined;
+    has(name: string): boolean;
+    /** Registered names, sorted — a stable list is part of being deterministic. */
+    names(): string[];
+    /**
+     * 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(): Record<string, LayoutAdapter>;
+}
+/**
+ * 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.
+ */
+export declare function fromAdapter(adapter: LayoutAdapter): RegisteredLayout;
+/**
+ * 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.
+ */
+export declare function createLayout(name: string, fn: GraphLayoutFn): RegisteredLayout;
+/**
+ * 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.
+ */
+export declare function translateOptions(engine: string, options: UnifiedLayoutOptions): Partial<LayoutOptions>;
+/**
+ * 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.
+ */
+export declare function createBuiltInLayoutAdapters(): LayoutAdapter[];
+/**
+ * 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.
+ */
+export declare function createBuiltInLayoutFactories(): Map<string, () => LayoutAdapter>;
+/**
+ * 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.
+ */
+export declare const DEFAULT_LAYOUT_NAME = "auto";
+/**
+ * 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.
+ */
+export declare function createAutoLayout(registry: LayoutRegistry): RegisteredLayout;
+/**
+ * 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.
+ */
+export declare function packAdapter(adapter: LayoutAdapter): LayoutAdapter;
+export declare function createPortfolioLayouts(): RegisteredLayout[];
+/**
+ * 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.
+ */
+export declare function createDefaultLayoutRegistry(): LayoutRegistry;
+/**
+ * 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.)
+ */
+export declare function runLayout(registry: LayoutRegistry, diagram: DiagramModel, name: string, options?: UnifiedLayoutOptions): Promise<UnifiedLayoutResult>;