@grafloria/element 0.3.17 → 0.3.19

package/src/libs/engine/src/layout/layout-adapter.interface.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Layout Adapter Interface
+ *
+ * Defines the common interface for external layout library adapters.
+ * This allows seamless integration of different layout engines (Dagre, ELK, etc.)
+ * into the Grafloria diagram engine.
+ */
+import { NodeModel } from '../models/NodeModel';
+import { LinkModel } from '../models/LinkModel';
+import type { Point } from '../types/geometry.types';
+import { LayoutConstraints } from './layout-constraints.interface';
+import { IncrementalLayoutOptions, IncrementalLayoutResult } from './incremental-layout.interface';
+import { LayoutQualityResult } from './layout-quality-metrics';
+import { PortAwareLayoutOptions, PortAwareLayoutResult, PortSide } from './port-aware-layout.interface';
+import { SubgraphLayoutOptions, SubgraphLayoutResult } from './subgraph-layout.interface';
+import { EdgeBundlingOptions, EdgeBundlingResult } from './edge-bundling.interface';
+import { PortConstraintMode } from './port-label-bridge';
+/**
+ * Base options for all layout adapters
+ */
+export interface LayoutOptions {
+    /**
+     * Seed for any algorithm that uses randomness (force, spectral, community).
+     *
+     * Wave 7 Card 3: this was already load-bearing — Card 0 made three adapters
+     * read it — but it lived nowhere in the type, so `force-layout-adapter` had to
+     * launder it through `(options as { seed?: number }).seed`. A cast is not a
+     * contract: it meant `seed` could not survive a typed hop across the worker
+     * boundary, where the options bag really is `Partial<LayoutOptions>` and
+     * anything not named there is dropped. Named here, it crosses.
+     */
+    seed?: number;
+    /** Whether to animate to new positions */
+    animate?: boolean;
+    /** Animation duration in milliseconds */
+    animationDuration?: number;
+    /** Whether to fit viewport to content after layout */
+    fit?: boolean;
+    /** Padding around content when fitting */
+    padding?: number;
+    /** Layout constraints for pinning/fixing nodes */
+    constraints?: LayoutConstraints;
+    /** Whether to calculate quality metrics after layout */
+    calculateQuality?: boolean;
+    /** Canvas dimensions for quality assessment */
+    canvasDimensions?: {
+        width: number;
+        height: number;
+    };
+    /** Port-aware layout options (Phase 3) */
+    portAware?: PortAwareLayoutOptions;
+    /** Subgraph/group layout options (Phase 3) */
+    subgraph?: SubgraphLayoutOptions;
+    /** Edge bundling options (Phase 4) */
+    edgeBundling?: EdgeBundlingOptions;
+    /**
+     * How much freedom the layout engine has over declared ports.
+     * `'auto'` (default): FIXED_SIDE for nodes with author-declared ports, FREE
+     * for the rest. So an edge leaving a `right` port will not force the layout to
+     * put the target on the left.
+     */
+    portConstraints?: PortConstraintMode;
+    /**
+     * Reserve space for edge labels at LAYOUT time (default true).
+     *
+     * This is a reservation, NOT a placement: the renderer's edge optimizer (wave
+     * 4/5) does collision-aware label placement, but it cannot invent space that
+     * layout never left. This gives it room to work in.
+     */
+    labelAware?: boolean;
+    /**
+     * Ask the layout engine for orthogonal edge routes (default true for ELK).
+     * The routes come back as HINTS (see `LayoutResult.routing`) — the wave-5
+     * routing engine stays authoritative.
+     */
+    orthogonalRouting?: boolean;
+}
+/**
+ * Wave 7 — Card 7: what the layout engine worked out about EDGES and PORTS,
+ * which until now was computed and then thrown in the bin.
+ *
+ * ELK does genuine port-aware layered layout with orthogonal edge routing. The
+ * old adapter read back `child.x` / `child.y` and NOTHING else — every port
+ * position and every edge section ELK produced was discarded. These are those
+ * results.
+ *
+ * They are HINTS, deliberately. The boundary wave 5 established still holds: the
+ * renderer computes endpoints and hands them to the routing engine
+ * (ManhattanRouter / GlobalRouteSolver), which owns the final path. Layout's job
+ * is to place nodes so a good route EXISTS and to say where it thinks that route
+ * runs — not to draw it.
+ */
+export interface LayoutRoutingHints {
+    /** Absolute position of each declared port, as the layout engine placed it. */
+    portPositions: Map<string, {
+        x: number;
+        y: number;
+        side: PortSide;
+    }>;
+    /** The route the layout engine found for each link: endpoints + bend points. */
+    edgeRoutes: Map<string, {
+        start: Point;
+        end: Point;
+        bends: Point[];
+    }>;
+    /** The box reserved for each labelled link (keyed by link id). */
+    labelSpace: Map<string, {
+        width: number;
+        height: number;
+    }>;
+    /** Whether the engine routed orthogonally. */
+    orthogonal: boolean;
+}
+/**
+ * Result of applying a layout algorithm
+ */
+export interface LayoutResult {
+    /** Map of node IDs to their new positions */
+    nodePositions: Map<string, {
+        x: number;
+        y: number;
+    }>;
+    /** Bounding box of the laid-out graph */
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Additional metadata about the layout execution */
+    metadata?: {
+        algorithm: string;
+        executionTime: number;
+        [key: string]: any;
+    };
+    /** Quality assessment of the layout (if calculateQuality was true) */
+    quality?: LayoutQualityResult;
+    /** Port-aware layout result (if portAware was enabled) */
+    portAware?: PortAwareLayoutResult;
+    /** Subgraph layout result (if subgraph was enabled) */
+    subgraph?: SubgraphLayoutResult;
+    /** Edge bundling result (if edgeBundling was enabled) */
+    edgeBundling?: EdgeBundlingResult;
+    /**
+     * Wave 7 — Card 7: the port positions and edge routes the layout engine
+     * computed. Present when the engine produces them (ELK does); previously
+     * computed and discarded.
+     */
+    routing?: LayoutRoutingHints;
+}
+/**
+ * Interface that all layout adapters must implement
+ */
+export interface LayoutAdapter {
+    /** Name of the layout adapter (e.g., 'dagre', 'elk') */
+    readonly name: string;
+    /**
+     * Apply layout to nodes and links
+     *
+     * @param nodes - Array of nodes to layout
+     * @param links - Array of links connecting the nodes
+     * @param options - Layout-specific options
+     * @returns Layout result with new positions and metadata
+     */
+    apply(nodes: NodeModel[], links: LinkModel[], options?: Partial<LayoutOptions>): Promise<LayoutResult>;
+    /**
+     * 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 (merged with generated constraints)
+     * @returns Layout result with positions and incremental statistics
+     */
+    applyIncremental(nodes: NodeModel[], links: LinkModel[], incrementalOptions: IncrementalLayoutOptions, layoutOptions?: Partial<LayoutOptions>): Promise<LayoutResult & {
+        incremental: IncrementalLayoutResult;
+    }>;
+    /**
+     * Validate that options are valid for this adapter
+     *
+     * @param options - Options to validate
+     * @returns true if valid, false otherwise
+     */
+    validateOptions(options: Partial<LayoutOptions>): boolean;
+}

package/src/libs/engine/src/layout/layout-adapter.interface.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Layout Adapter Interface
+ *
+ * Defines the common interface for external layout library adapters.
+ * This allows seamless integration of different layout engines (Dagre, ELK, etc.)
+ * into the Grafloria diagram engine.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=layout-adapter.interface.js.map

package/src/libs/engine/src/layout/layout-adapter.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout-adapter.interface.js","sourceRoot":"","sources":["../../../../../../engine/src/layout/layout-adapter.interface.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG"}

package/src/libs/engine/src/layout/layout-auto-select.d.ts

@@ -0,0 +1,160 @@
+import type { DiagramModel } from '../models/DiagramModel';
+import type { NodeModel } from '../models/NodeModel';
+import type { LinkModel } from '../models/LinkModel';
+import type { LayoutResult } from './layout-adapter.interface';
+import type { LayoutRegistry, UnifiedLayoutOptions } from './layout-registry';
+import { LayoutQualityResult } from './layout-quality-metrics';
+/** The registered name of the auto-selecting layout. */
+export declare const AUTO_LAYOUT_NAME = "auto";
+/**
+ * What kind of graph is this? Used to pick which candidates are worth RUNNING
+ * (a bake-off over five algorithms on a 5,000-node graph is not free) — never to
+ * pick the winner. The winner is always decided by measurement.
+ */
+export interface GraphShape {
+    nodeCount: number;
+    linkCount: number;
+    /** links / max-possible-links. */
+    density: number;
+    /** No cycles, and every node has at most one parent. */
+    isTree: boolean;
+    /** Directed, acyclic. */
+    isDAG: boolean;
+    /** Number of connected components. */
+    components: number;
+    /** Any node carries author-declared ports. */
+    hasDeclaredPorts: boolean;
+    /** Any link carries a label. */
+    hasEdgeLabels: boolean;
+}
+export declare function analyseGraphShape(nodes: NodeModel[], links: LinkModel[]): GraphShape;
+/**
+ * Longest-path layering estimate for a DAG — the two numbers that predict which
+ * hierarchical engine will choke (measured, not guessed; see the perf spec):
+ *
+ *   • dagre's pathology is DEPTH: a 2,000-rank chain never returns, while a
+ *     2,000-node, ~1,000-wide tree takes ~700ms.
+ *   • our layered (Sugiyama) engine's pathology is WIDTH: crossing minimisation
+ *     over a ~1,000-node rank runs for tens of seconds, while a 45-wide,
+ *     90-deep mesh takes ~480ms and a width-1, 2,000-deep chain ~130ms.
+ *
+ * O(n + m) via Kahn's algorithm. Only meaningful when the graph is acyclic;
+ * nodes left unranked by a cycle default to rank 0.
+ */
+export interface LayeringEstimate {
+    /** Number of layers a longest-path layering would produce. */
+    depth: number;
+    /** Node count of the widest layer. */
+    maxWidth: number;
+}
+export declare function estimateLayering(nodes: NodeModel[], links: LinkModel[]): LayeringEstimate;
+export interface LayoutCandidate {
+    /** Registered layout name to run. */
+    name: string;
+    /** Options to run it with. */
+    options: UnifiedLayoutOptions;
+    /** A stable id for this candidate — name + tuning. Ties break on this. */
+    id: string;
+    /** Is this engine able to honour port sides? */
+    portAware: boolean;
+}
+/**
+ * The candidate pool, in a FIXED order.
+ *
+ * Auto-tuning lives here too: a candidate is an algorithm PLUS its knobs, so
+ * `dagre TB` and `dagre LR` compete as separate candidates and the better
+ * direction simply wins on score. That is the whole of "auto-tune" — no separate
+ * tuning pass, just more candidates in the bake-off.
+ */
+export declare function buildCandidates(shape: GraphShape, registry: LayoutRegistry): LayoutCandidate[];
+/**
+ * Above this many nodes the bake-off itself is the pathology: it runs EVERY
+ * candidate engine on the full graph, so its runtime is the SUM of the field —
+ * including whichever engine happens to hang at that scale (measured: 16s+ at
+ * 300 nodes, unbounded at 2,000). Past this limit the graph is classified
+ * structurally and ONE engine is picked directly; the choice is still
+ * deterministic and still explained in the selection report.
+ */
+export declare const BAKEOFF_NODE_LIMIT = 200;
+/** A structural engine choice made without running a bake-off. */
+export interface ScalePlan {
+    /** Candidates to try, best-first; the first that runs wins. */
+    candidates: LayoutCandidate[];
+    /** The structural fact the pick rests on — goes into the report verbatim. */
+    why: string;
+}
+/**
+ * Pick the engine(s) for a graph too large to bake off, from its STRUCTURE.
+ *
+ * Every branch below is backed by a measurement in layout-auto-select.perf.spec.ts
+ * (times on the dev machine, generous CI caps in the spec):
+ *
+ *   tree            → portfolio `tree`: 19ms at n=2000 (vs dagre 702ms, layered 5.3s)
+ *   DAG, narrow     → `layered`: 156ms at 900-mesh, 479ms at 2025-mesh,
+ *                     132ms at a 2,000-deep chain — width is what hurts it, and
+ *                     narrow ranks are exactly where dagre's depth pathology lives.
+ *   DAG, wide+shallow → `dagre`: 1.3s at a 2,000-node sparse DAG whose ~1,000-wide
+ *                     ranks are what kill layered.
+ *   DAG, wide+deep  → `elk` layered: the moderate-everywhere engine.
+ *   cyclic          → `force`: completes in well under a second at this scale;
+ *                     hierarchical engines would first have to break the cycles.
+ *
+ * Declared ports bump ELK (the only port-aware candidate) to the front for
+ * hierarchical graphs — at this scale we cannot afford to MEASURE port respect
+ * across a whole field, so we pick the engine built to honour it.
+ *
+ * Returns undefined when none of the preferred engines is registered; the caller
+ * then falls back to the (gated) bake-off rather than failing.
+ */
+export declare function pickEngineForScale(shape: GraphShape, nodes: NodeModel[], links: LinkModel[], registry: LayoutRegistry): ScalePlan | undefined;
+/** Every number behind one candidate's verdict. */
+export interface CandidateScore {
+    id: string;
+    name: string;
+    options: UnifiedLayoutOptions;
+    /** Final weighted score, 0-100. */
+    score: number;
+    /** The classic metrics (crossings, overlap, symmetry, …). */
+    quality: LayoutQualityResult;
+    /** Requirement 1: do edges leave in the direction their port faces? 0-100. */
+    portRespect: number;
+    /** Requirement 2: do edge labels stay off the nodes? 0-100. */
+    labelClearance: number;
+    /** Total bends across the engine's routes; undefined if it reported none. */
+    bends: number | undefined;
+    /** Bounding-box area in px². */
+    area: number;
+    /** Failed to run — kept in the report rather than hidden. */
+    error?: string;
+}
+/**
+ * What the auto-selector chose, and WHY. Returned on the layout result, so the
+ * reasoning is available to a UI, a log line or a test — never hidden.
+ */
+export interface LayoutSelectionReport {
+    /** The candidate that won (its id, e.g. 'elk:layered:RIGHT'). */
+    chosen: string;
+    /** The registered algorithm behind it. */
+    algorithm: string;
+    /** One sentence a human can read. */
+    reason: string;
+    /** What we worked out about the graph before choosing. */
+    shape: GraphShape;
+    /** Every candidate, scored, best first. Losers included on purpose. */
+    candidates: CandidateScore[];
+}
+export interface AutoLayoutResult extends LayoutResult {
+    /** Why this layout, and what the alternatives scored. */
+    selection: LayoutSelectionReport;
+}
+/**
+ * Run the bake-off and keep the best layout.
+ *
+ * IMPORTANT — this MUTATES node positions while it works: each candidate has to be
+ * applied to the model before its quality can be measured (crossings are a
+ * property of a drawn graph, not of a plan). The winner's positions are re-applied
+ * at the end, so the model always lands on the layout we chose, never on the last
+ * one we happened to try. `DiagramEngine.layout()` then commits them through
+ * `setPosition()` as usual.
+ */
+export declare function autoSelectLayout(diagram: DiagramModel, registry: LayoutRegistry, options?: UnifiedLayoutOptions): Promise<AutoLayoutResult>;