@grafloria/element 0.3.20 → 0.3.22

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

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

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

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