@grafloria/element 0.3.18 → 0.3.20

package/src/libs/engine/src/layout/incremental/mental-map.d.ts

@@ -0,0 +1,98 @@
+import type { DiagramModel } from '../../models/DiagramModel';
+import type { SemanticConstraints } from '../sugiyama/sugiyama';
+export type IncrementalStrategy = 
+/** Only the changed region may move; everything else is an anchor. */
+'region'
+/** Nothing existing moves at all; new nodes are placed in the gaps. */
+ | 'pin-existing'
+/** Everything may move, but the result is re-aligned and movement is capped. */
+ | 'minimal-shift';
+export interface MovementBudget {
+    /** No single node may move further than this. */
+    maxPerNode?: number;
+    /** The mean movement across all nodes that existed before. */
+    averagePerNode?: number;
+}
+export interface IncrementalOptions {
+    strategy?: IncrementalStrategy;
+    /** Node ids the user just added/edited. Everything else is "existing". */
+    changed?: string[];
+    /** How far the disturbance is allowed to spread, in graph hops. Default 1. */
+    radius?: number;
+    budget?: MovementBudget;
+}
+export interface MovementReport {
+    /** Sum of the distances every pre-existing node travelled. */
+    total: number;
+    average: number;
+    max: number;
+    /** How many pre-existing nodes moved at all (beyond a 0.5px epsilon). */
+    moved: number;
+    /** Of the pre-existing nodes, how many stayed exactly put. */
+    unmoved: number;
+    /** Did we stay inside the caller's budget? */
+    withinBudget: boolean;
+    /** How much of the movement the centroid re-alignment removed. */
+    savedByAlignment: number;
+}
+export type Positions = Map<string, {
+    x: number;
+    y: number;
+}>;
+/**
+ * The translation that minimises total squared displacement between two layouts.
+ *
+ * For a pure translation the optimum is exactly the difference of the centroids of
+ * the shared nodes — no search, no iteration. This is the single highest-value
+ * function in the file: a layered layout is defined only up to translation, so a
+ * new node widening rank 0 can shift the ENTIRE drawing sideways. Every node then
+ * "moves" although the picture is unchanged, the movement budget blows, and a
+ * naive implementation starts fighting its own layout with constraints. Align
+ * first; constrain only what is left.
+ */
+export declare function alignToPrevious(next: Positions, previous: Positions): {
+    positions: Positions;
+    shift: {
+        x: number;
+        y: number;
+    };
+};
+/**
+ * Measure how much the mental map was disturbed.
+ *
+ * Only nodes that existed BEFORE count: a new node cannot "move", and including it
+ * would flatter the numbers exactly when the layout is at its most disruptive.
+ */
+export declare function measureMovement(before: Positions, after: Positions, budget: MovementBudget | undefined, savedByAlignment?: number): MovementReport;
+/**
+ * The nodes allowed to move: the changed set grown by `radius` hops.
+ *
+ * Everything outside becomes a Card-5 anchor. This is what "re-run layout only in
+ * the affected region" means concretely — and it is only possible because anchors
+ * are now real: the layout works AROUND the frozen nodes instead of laying out over
+ * them and being corrected afterwards.
+ */
+export declare function affectedRegion(diagram: DiagramModel, changed: string[], radius: number): Set<string>;
+/**
+ * Turn a strategy into Card-5 semantic constraints.
+ *
+ * Note what this does NOT do: it does not emit positions to be clamped afterwards.
+ * It emits ANCHORS, which the layered engine honours during coordinate assignment —
+ * the whole reason the four scaffolded strategies never worked.
+ */
+export declare function constraintsForStrategy(diagram: DiagramModel, before: Positions, options: IncrementalOptions): SemanticConstraints;
+/**
+ * A tween plan: pure data, so the engine stays free of rAF/DOM/time.
+ *
+ * The card asks for "an animated tweened transition from old to new positions
+ * instead of snapping". The engine's job is to say WHERE things go at time t; the
+ * host's job is to drive t. Keeping it that way is what lets the same code run in
+ * a worker, in SSR, and in a test.
+ */
+export interface TweenPlan {
+    /** Positions at normalised time t ∈ [0, 1]. Eased. */
+    at(t: number): Positions;
+    /** Nodes that actually move — a host can skip the rest entirely. */
+    movingIds: string[];
+}
+export declare function planTween(before: Positions, after: Positions): TweenPlan;

package/src/libs/engine/src/layout/incremental/mental-map.js

@@ -0,0 +1,221 @@
+"use strict";
+// Wave 7 (Auto-layout) — Card 6: mental-map-preserving incremental layout.
+//
+// THE DIFFERENTIATOR. Mermaid re-renders the whole diagram from scratch on every
+// edit, so adding one node can rearrange everything and destroy the user's spatial
+// memory of their own diagram. Nobody does this well. Doing it well is defensible.
+//
+// ---------------------------------------------------------------------------
+// WHY THE EXISTING SCAFFOLDING COULD NOT WORK
+// ---------------------------------------------------------------------------
+//
+// `IncrementalLayoutManager.generateConstraints()` ships four named strategies —
+// pin-existing, fix-anchors, proximity-aware, minimal-shift. All four do the same
+// thing: they emit `NodeConstraint[]` for the OLD constraint system, which applied
+// them by taking an already-computed position and clamping it (see Card 5). So
+// `pin-existing` — "pin every existing node, lay out only the new ones" — actually:
+//
+//     1. pinned nothing during the layout,
+//     2. let the layout place NEW nodes wherever it liked, including on top of
+//        existing ones, because it had no idea they were there,
+//     3. then snapped the existing nodes back on top of the new ones.
+//
+// It was scaffolding on a foundation that could not hold it. Card 5 replaced the
+// foundation: anchors are now honoured DURING coordinate assignment, and everything
+// else is laid out AROUND them. This module is what that makes possible.
+//
+// ---------------------------------------------------------------------------
+// THE THREE IDEAS
+// ---------------------------------------------------------------------------
+//
+// 1. REGION-LIMITED RELAYOUT. An edit touches a few nodes. Re-laying-out the whole
+//    graph to accommodate them is what destroys the mental map. So: take the
+//    changed nodes, grow a k-hop neighbourhood around them, and let ONLY that
+//    region move. Everything outside is a Card-5 anchor — an immovable obstacle the
+//    layout must work around, not a position to be corrected afterwards.
+//
+// 2. OPTIMAL RE-ALIGNMENT — the cheapest large win, and the one most implementations
+//    miss. A layered layout is only defined up to a translation: dagre will happily
+//    hand you back the same picture shifted 300px right because one new node widened
+//    rank 0. Every node then "moves" even though the DRAWING is identical. The fix
+//    is exact and costs nothing: translate the new layout so the CENTROIDS of the
+//    nodes present in both layouts coincide. That is provably the translation that
+//    minimises total squared displacement, and it recovers most of the mental map
+//    before a single constraint is applied.
+//
+// 3. MEASURED, NOT ASSERTED. The card says "real and measured". Movement is reported
+//    against an explicit budget (total / average / max), and the caller can see
+//    exactly what moved and by how much. A mental-map feature that cannot show its
+//    own numbers is a claim, not a capability.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.alignToPrevious = alignToPrevious;
+exports.measureMovement = measureMovement;
+exports.affectedRegion = affectedRegion;
+exports.constraintsForStrategy = constraintsForStrategy;
+exports.planTween = planTween;
+/**
+ * The translation that minimises total squared displacement between two layouts.
+ *
+ * For a pure translation the optimum is exactly the difference of the centroids of
+ * the shared nodes — no search, no iteration. This is the single highest-value
+ * function in the file: a layered layout is defined only up to translation, so a
+ * new node widening rank 0 can shift the ENTIRE drawing sideways. Every node then
+ * "moves" although the picture is unchanged, the movement budget blows, and a
+ * naive implementation starts fighting its own layout with constraints. Align
+ * first; constrain only what is left.
+ */
+function alignToPrevious(next, previous) {
+    const shared = [...next.keys()].filter((id) => previous.has(id));
+    if (shared.length === 0)
+        return { positions: next, shift: { x: 0, y: 0 } };
+    let dx = 0;
+    let dy = 0;
+    for (const id of shared) {
+        dx += previous.get(id).x - next.get(id).x;
+        dy += previous.get(id).y - next.get(id).y;
+    }
+    dx /= shared.length;
+    dy /= shared.length;
+    const positions = new Map();
+    for (const [id, p] of next)
+        positions.set(id, { x: p.x + dx, y: p.y + dy });
+    return { positions, shift: { x: dx, y: dy } };
+}
+/** Straight-line distance between two positions. */
+const dist = (a, b) => Math.hypot(a.x - b.x, a.y - b.y);
+/**
+ * Measure how much the mental map was disturbed.
+ *
+ * Only nodes that existed BEFORE count: a new node cannot "move", and including it
+ * would flatter the numbers exactly when the layout is at its most disruptive.
+ */
+function measureMovement(before, after, budget, savedByAlignment = 0) {
+    const existing = [...before.keys()].filter((id) => after.has(id));
+    const distances = existing.map((id) => dist(before.get(id), after.get(id)));
+    const total = distances.reduce((s, d) => s + d, 0);
+    const average = distances.length ? total / distances.length : 0;
+    const max = distances.length ? Math.max(...distances) : 0;
+    const moved = distances.filter((d) => d > 0.5).length;
+    const withinBudget = ((budget === null || budget === void 0 ? void 0 : budget.maxPerNode) === undefined || max <= budget.maxPerNode) &&
+        ((budget === null || budget === void 0 ? void 0 : budget.averagePerNode) === undefined || average <= budget.averagePerNode);
+    return {
+        total,
+        average,
+        max,
+        moved,
+        unmoved: distances.length - moved,
+        withinBudget,
+        savedByAlignment,
+    };
+}
+/**
+ * The nodes allowed to move: the changed set grown by `radius` hops.
+ *
+ * Everything outside becomes a Card-5 anchor. This is what "re-run layout only in
+ * the affected region" means concretely — and it is only possible because anchors
+ * are now real: the layout works AROUND the frozen nodes instead of laying out over
+ * them and being corrected afterwards.
+ */
+function affectedRegion(diagram, changed, radius) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const region = new Set(changed);
+    if (radius <= 0)
+        return region;
+    // adjacency over the whole graph
+    const adj = new Map();
+    for (const link of diagram.getLinks()) {
+        const s = (_a = link.sourceNodeId) !== null && _a !== void 0 ? _a : (_c = (_b = diagram.getNodeByPortId) === null || _b === void 0 ? void 0 : _b.call(diagram, link.sourcePortId)) === null || _c === void 0 ? void 0 : _c.id;
+        const t = (_d = link.targetNodeId) !== null && _d !== void 0 ? _d : (_f = (_e = diagram.getNodeByPortId) === null || _e === void 0 ? void 0 : _e.call(diagram, link.targetPortId)) === null || _f === void 0 ? void 0 : _f.id;
+        if (!s || !t)
+            continue;
+        if (!adj.has(s))
+            adj.set(s, []);
+        if (!adj.has(t))
+            adj.set(t, []);
+        adj.get(s).push(t);
+        adj.get(t).push(s);
+    }
+    let frontier = [...changed];
+    for (let hop = 0; hop < radius; hop++) {
+        const next = [];
+        for (const id of frontier) {
+            for (const n of (_g = adj.get(id)) !== null && _g !== void 0 ? _g : []) {
+                if (!region.has(n)) {
+                    region.add(n);
+                    next.push(n);
+                }
+            }
+        }
+        frontier = next;
+        if (frontier.length === 0)
+            break;
+    }
+    return region;
+}
+/**
+ * Turn a strategy into Card-5 semantic constraints.
+ *
+ * Note what this does NOT do: it does not emit positions to be clamped afterwards.
+ * It emits ANCHORS, which the layered engine honours during coordinate assignment —
+ * the whole reason the four scaffolded strategies never worked.
+ */
+function constraintsForStrategy(diagram, before, options) {
+    var _a, _b, _c;
+    const strategy = (_a = options.strategy) !== null && _a !== void 0 ? _a : 'region';
+    const changed = (_b = options.changed) !== null && _b !== void 0 ? _b : [];
+    const anchors = {};
+    if (strategy === 'minimal-shift') {
+        // Nothing is anchored: the layout is free, and the mental map is preserved by
+        // re-alignment plus the movement budget instead. (Anchoring everything and
+        // ALSO asking for a good layout is how you get a bad layout that also moved.)
+        return { anchors };
+    }
+    const mayMove = strategy === 'pin-existing'
+        ? new Set(changed) // only the new/changed nodes may move
+        : affectedRegion(diagram, changed, (_c = options.radius) !== null && _c !== void 0 ? _c : 1);
+    for (const node of diagram.getNodes()) {
+        if (mayMove.has(node.id))
+            continue;
+        const p = before.get(node.id);
+        if (!p)
+            continue; // a node with no previous position is new by definition
+        // anchor at the node's CENTRE — sugiyama's anchors are centres, positions are
+        // top-left (the model's convention). Getting this wrong shifts every frozen
+        // node by half its size, which looks like "the anchors don't work".
+        anchors[node.id] = { x: p.x + node.size.width / 2, y: p.y + node.size.height / 2 };
+    }
+    return { anchors };
+}
+/** ease-in-out cubic: slow, fast, slow — the standard "this moved on purpose" curve. */
+const easeInOutCubic = (t) => t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+function planTween(before, after) {
+    const movingIds = [...after.keys()].filter((id) => {
+        const b = before.get(id);
+        return b !== undefined && dist(b, after.get(id)) > 0.5;
+    });
+    return {
+        movingIds,
+        at(t) {
+            const clamped = Math.max(0, Math.min(1, t));
+            const e = easeInOutCubic(clamped);
+            const out = new Map();
+            for (const [id, target] of after) {
+                const start = before.get(id);
+                if (!start) {
+                    // A NEW node does not slide in from a position it never had. It appears
+                    // where it belongs; the host can fade it in. Interpolating from (0,0)
+                    // would fly it across the diagram, which is precisely the disorientation
+                    // this card exists to prevent.
+                    out.set(id, Object.assign({}, target));
+                    continue;
+                }
+                out.set(id, {
+                    x: start.x + (target.x - start.x) * e,
+                    y: start.y + (target.y - start.y) * e,
+                });
+            }
+            return out;
+        },
+    };
+}
+//# sourceMappingURL=mental-map.js.map

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

@@ -0,0 +1,145 @@
+/**
+ * Incremental Layout System
+ *
+ * Enables adding nodes to an existing diagram without re-laying out the entire graph.
+ * This is essential for interactive editing where users progressively build diagrams.
+ */
+import { NodeModel } from '../models/NodeModel';
+import { LayoutConstraints } from './layout-constraints.interface';
+/**
+ * Strategy for incremental layout
+ */
+export type IncrementalLayoutStrategy = 'pin-existing' | 'fix-anchors' | 'proximity-aware' | 'minimal-shift';
+/**
+ * Options for incremental layout
+ */
+export interface IncrementalLayoutOptions {
+    /**
+     * Strategy to use for incremental layout
+     * @default 'pin-existing'
+     */
+    strategy?: IncrementalLayoutStrategy;
+    /**
+     * Nodes that are new (to be laid out)
+     * If not provided, nodes without valid positions are considered new
+     */
+    newNodeIds?: string[];
+    /**
+     * Anchor nodes that should never move (in addition to strategy constraints)
+     * These have highest priority
+     */
+    anchorNodeIds?: string[];
+    /**
+     * Maximum distance a non-anchor node can move (pixels)
+     * Only applies to 'minimal-shift' strategy
+     */
+    maxShift?: number;
+    /**
+     * Radius around new nodes where existing nodes can be adjusted (pixels)
+     * Only applies to 'proximity-aware' strategy
+     * @default 200
+     */
+    proximityRadius?: number;
+    /**
+     * Whether to allow slight adjustments to improve layout quality
+     * @default false
+     */
+    allowMinorAdjustments?: boolean;
+    /**
+     * Custom constraints to apply in addition to incremental constraints
+     */
+    customConstraints?: LayoutConstraints;
+}
+/**
+ * Result of incremental layout operation
+ */
+export interface IncrementalLayoutResult {
+    /**
+     * IDs of nodes that were moved during layout
+     */
+    movedNodeIds: string[];
+    /**
+     * IDs of nodes that were pinned/fixed
+     */
+    pinnedNodeIds: string[];
+    /**
+     * IDs of nodes that were newly laid out
+     */
+    newlyLaidOutNodeIds: string[];
+    /**
+     * Maximum distance any node moved (pixels)
+     */
+    maxMovement: number;
+    /**
+     * Average distance nodes moved (pixels)
+     */
+    avgMovement: number;
+    /**
+     * Strategy that was used
+     */
+    strategy: IncrementalLayoutStrategy;
+    /**
+     * Number of constraints that were auto-generated
+     */
+    autoConstraintCount: number;
+}
+/**
+ * Helper class for managing incremental layouts
+ */
+export declare class IncrementalLayoutManager {
+    /**
+     * Identify new nodes that need to be laid out
+     *
+     * @param nodes - All nodes in the diagram
+     * @param options - Incremental layout options
+     * @returns Array of node IDs that are considered new
+     */
+    static identifyNewNodes(nodes: NodeModel[], options: IncrementalLayoutOptions): string[];
+    /**
+     * Identify existing nodes that should be constrained
+     *
+     * @param nodes - All nodes in the diagram
+     * @param newNodeIds - IDs of new nodes
+     * @returns Array of node IDs that should be constrained
+     */
+    static identifyExistingNodes(nodes: NodeModel[], newNodeIds: string[]): string[];
+    /**
+     * Generate constraints for incremental layout based on strategy
+     *
+     * @param nodes - All nodes in the diagram
+     * @param options - Incremental layout options
+     * @returns Generated layout constraints
+     */
+    static generateConstraints(nodes: NodeModel[], options: IncrementalLayoutOptions): LayoutConstraints;
+    /**
+     * Pin all existing nodes to their current positions
+     */
+    private static generatePinExistingConstraints;
+    /**
+     * Fix anchor nodes (nodes with many connections) strongly,
+     * allow other existing nodes to move slightly
+     */
+    private static generateFixAnchorsConstraints;
+    /**
+     * Pin nodes far from new nodes, allow nodes near new nodes to adjust
+     */
+    private static generateProximityAwareConstraints;
+    /**
+     * Allow all existing nodes to move, but constrain within maxShift
+     */
+    private static generateMinimalShiftConstraints;
+    /**
+     * Calculate movement statistics after incremental layout
+     *
+     * @param nodes - All nodes
+     * @param oldPositions - Map of node IDs to their positions before layout
+     * @param newNodeIds - IDs of newly laid out nodes
+     * @param constraints - Constraints that were applied
+     * @param strategy - Strategy that was used
+     * @returns Incremental layout result with statistics
+     */
+    static calculateResult(nodes: NodeModel[], oldPositions: Map<string, {
+        x: number;
+        y: number;
+    }>, newNodeIds: string[], constraints: LayoutConstraints, strategy: IncrementalLayoutStrategy): IncrementalLayoutResult;
+}