@grafloria/element 0.3.20 → 0.3.21

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

@@ -1,309 +0,0 @@
-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>;