@yalehwang/plantuml-js 0.2.2 → 0.3.0

package/dist/layout/lane-spread.js

@@ -0,0 +1,302 @@
+/**
+ * Lane spreading. The grid router and ELK both let unrelated orthogonal edges
+ * share one channel centre, so several edges end up drawn on top of each other
+ * and read as one thicker line. This pass fans such coincident (or nearly
+ * coincident) interior segments out onto distinct, evenly spaced lanes around
+ * their common centre. Only interior segments move — the first and last
+ * segments stay attached to their ports — and a move is dropped when it would
+ * run through a node or fold an adjacent segment back on itself.
+ */
+/** Segments closer than this on the cross axis are one lane cluster (just above PARALLEL_PROXIMITY). */
+const CLUSTER_DISTANCE = 10;
+/** Distance between spread lanes; strictly above [[CLUSTER_DISTANCE]] so lanes stay distinct. */
+const LANE_STEP = 10;
+/** Tightest lane step used when a corridor is too narrow (still above PARALLEL_PROXIMITY = 8). */
+const MIN_LANE_STEP = 8.5;
+/** An adjacent segment may shrink to at most this length. */
+const MIN_STUB = 6;
+/** Clearance between a moved segment and an unrelated node box. */
+const NODE_CLEARANCE = 12;
+/** Clearance between a moved segment and a package frame border it runs along. */
+const FRAME_CLEARANCE = 10;
+/** Spreading is repeated because moved lanes can land beside a neighbouring channel. */
+const PASSES = 2;
+export function spreadParallelLanes(layout) {
+    const polylines = layout.edges.map((e) => dropRepeats(e.points));
+    const owners = layout.edges.map((e) => new Set([e.source, e.target]));
+    const ends = layout.edges.map((e) => [e.source, e.target]);
+    let changed = layout.edges.some((e, i) => e.points.length !== polylines[i].length);
+    for (let pass = 0; pass < PASSES; pass++) {
+        let moved = false;
+        for (const horizontal of [true, false]) {
+            const segs = withoutMergedTrunks(collectSegments(polylines, horizontal), ends);
+            for (const cluster of clusterSegments(segs)) {
+                if (spreadCluster(cluster, polylines, owners, layout, horizontal))
+                    moved = true;
+            }
+        }
+        if (!moved)
+            break;
+        changed = true;
+    }
+    if (!changed)
+        return layout;
+    return { ...layout, edges: layout.edges.map((e, i) => ({ ...e, points: polylines[i] })) };
+}
+/** Copy of `points` without consecutive duplicates (zero-length segments). */
+function dropRepeats(points) {
+    const out = [];
+    for (const p of points) {
+        const last = out[out.length - 1];
+        if (!last || Math.abs(last.x - p.x) > 1e-6 || Math.abs(last.y - p.y) > 1e-6)
+            out.push({ ...p });
+    }
+    return out.length >= 2 || points.length < 2 ? out : points.map((p) => ({ ...p }));
+}
+function collectSegments(polylines, horizontal) {
+    const segs = [];
+    const cross = (p) => (horizontal ? p.y : p.x);
+    const along = (p) => (horizontal ? p.x : p.y);
+    polylines.forEach((pts, edge) => {
+        // Interior segments only: both neighbours must exist.
+        for (let i = 1; i + 2 < pts.length; i++) {
+            const a = pts[i];
+            const b = pts[i + 1];
+            if (Math.abs(cross(a) - cross(b)) > 1e-6)
+                continue;
+            const prev = pts[i - 1];
+            const next = pts[i + 2];
+            // Neighbours must be perpendicular (they absorb the shift).
+            if (Math.abs(along(prev) - along(a)) > 1e-6 || Math.abs(along(next) - along(b)) > 1e-6)
+                continue;
+            const c = cross(a);
+            const side = (p) => Math.sign(cross(p) - c);
+            segs.push({
+                edge,
+                at: i,
+                c,
+                lo: Math.min(along(a), along(b)),
+                hi: Math.max(along(a), along(b)),
+                turn: side(prev) + side(next),
+            });
+        }
+    });
+    return segs;
+}
+/**
+ * Drops segments lying exactly on a segment of another edge with the same source
+ * (or target): that overlap is a deliberately shared trunk, not a clash to fan out.
+ */
+function withoutMergedTrunks(segs, ends) {
+    const merged = new Set();
+    const order = segs.slice().sort((a, b) => a.c - b.c);
+    for (let x = 0; x < order.length; x++) {
+        for (let y = x + 1; y < order.length && order[y].c - order[x].c < 0.5; y++) {
+            const s = order[x];
+            const t = order[y];
+            if (s.edge === t.edge || Math.min(s.hi, t.hi) - Math.max(s.lo, t.lo) <= 1)
+                continue;
+            const [sa, sb] = ends[s.edge];
+            const [ta, tb] = ends[t.edge];
+            if (sa === ta || sb === tb) {
+                merged.add(s);
+                merged.add(t);
+            }
+        }
+    }
+    return merged.size === 0 ? segs : segs.filter((s) => !merged.has(s));
+}
+/** Groups of segments (from at least two edges) that overlap within [[CLUSTER_DISTANCE]]. */
+function clusterSegments(segs) {
+    const order = segs.map((_, i) => i).sort((a, b) => segs[a].c - segs[b].c);
+    const parent = segs.map((_, i) => i);
+    const find = (i) => {
+        while (parent[i] !== i)
+            i = parent[i] = parent[parent[i]];
+        return i;
+    };
+    for (let x = 0; x < order.length; x++) {
+        const s = segs[order[x]];
+        for (let y = x + 1; y < order.length; y++) {
+            const t = segs[order[y]];
+            if (t.c - s.c >= CLUSTER_DISTANCE)
+                break;
+            if (s.edge === t.edge)
+                continue;
+            if (Math.min(s.hi, t.hi) - Math.max(s.lo, t.lo) > 1)
+                parent[find(order[x])] = find(order[y]);
+        }
+    }
+    const groups = new Map();
+    segs.forEach((s, i) => {
+        const root = find(i);
+        const list = groups.get(root);
+        if (list)
+            list.push(s);
+        else
+            groups.set(root, [s]);
+    });
+    return [...groups.values()].filter((g) => new Set(g.map((s) => s.edge)).size > 1);
+}
+function spreadCluster(cluster, polylines, owners, layout, horizontal) {
+    const lanes = cluster
+        .slice()
+        .sort((a, b) => a.c - b.c || a.turn - b.turn || a.edge - b.edge || a.at - b.at);
+    const targets = fitToCorridor(separate(lanes.map((s) => s.c), LANE_STEP), lanes, layout, horizontal);
+    let moved = false;
+    lanes.forEach((seg, k) => {
+        const target = targets[k];
+        if (Math.abs(target - seg.c) < 1e-6)
+            return;
+        if (shift(polylines[seg.edge], seg.at, target, owners[seg.edge], layout, horizontal))
+            moved = true;
+    });
+    return moved;
+}
+/**
+ * Least-squares positions for the sorted coordinates `c` such that neighbours
+ * are at least `step` apart (pool-adjacent-violators on `c − step·i`).
+ */
+function separate(c, step) {
+    const blocks = [];
+    c.forEach((v, i) => {
+        blocks.push({ sum: v - step * i, n: 1 });
+        while (blocks.length > 1) {
+            const b = blocks[blocks.length - 1];
+            const a = blocks[blocks.length - 2];
+            if (a.sum / a.n <= b.sum / b.n)
+                break;
+            a.sum += b.sum;
+            a.n += b.n;
+            blocks.pop();
+        }
+    });
+    const out = [];
+    for (const b of blocks)
+        for (let k = 0; k < b.n; k++)
+            out.push(b.sum / b.n + step * out.length);
+    return out;
+}
+/**
+ * Keep `targets` (sorted lanes) inside the free corridor around the cluster:
+ * the gap between the nearest unrelated boxes on either side. A corridor too
+ * narrow for [[LANE_STEP]] is shared at a tighter step down to [[MIN_LANE_STEP]];
+ * when even that does not fit the unconstrained targets are returned (the
+ * per-segment safety checks then decide what can move).
+ */
+function fitToCorridor(targets, lanes, layout, horizontal) {
+    const n = targets.length;
+    const lo = Math.min(...lanes.map((s) => s.lo));
+    const hi = Math.max(...lanes.map((s) => s.hi));
+    const centre = lanes.reduce((sum, s) => sum + s.c, 0) / n;
+    const blocked = [];
+    const add = (a0, a1, c0, c1, clearance) => {
+        if (a1 > lo && a0 < hi)
+            blocked.push([c0 - clearance, c1 + clearance]);
+    };
+    for (const b of layout.nodes) {
+        if (horizontal)
+            add(b.x, b.x + b.width, b.y, b.y + b.height, NODE_CLEARANCE);
+        else
+            add(b.y, b.y + b.height, b.x, b.x + b.width, NODE_CLEARANCE);
+    }
+    for (const f of layout.packages ?? []) {
+        if (horizontal) {
+            add(f.x, f.x + f.width, f.y, f.y, FRAME_CLEARANCE);
+            add(f.x, f.x + f.width, f.y + f.height, f.y + f.height, FRAME_CLEARANCE);
+        }
+        else {
+            add(f.y, f.y + f.height, f.x, f.x, FRAME_CLEARANCE);
+            add(f.y, f.y + f.height, f.x + f.width, f.x + f.width, FRAME_CLEARANCE);
+        }
+    }
+    let floor = -Infinity;
+    let ceil = Infinity;
+    for (const [a, b] of blocked) {
+        if (a <= centre && centre <= b)
+            return targets;
+        if (b < centre)
+            floor = Math.max(floor, b);
+        else
+            ceil = Math.min(ceil, a);
+    }
+    const room = ceil - floor;
+    const needed = (n - 1) * LANE_STEP;
+    if (room >= needed) {
+        const first = targets[0];
+        const last = targets[n - 1];
+        const shiftBy = first < floor ? floor - first : last > ceil ? ceil - last : 0;
+        return targets.map((t) => t + shiftBy);
+    }
+    if (n < 2 || room / (n - 1) < MIN_LANE_STEP)
+        return targets;
+    const step = room / (n - 1);
+    return targets.map((_, i) => floor + i * step);
+}
+/** Move segment `at` of `pts` to cross-axis `target`; false (and unchanged) if that is unsafe. */
+function shift(pts, at, target, owner, layout, horizontal) {
+    const key = horizontal ? 'y' : 'x';
+    const a = pts[at];
+    const b = pts[at + 1];
+    const prev = pts[at - 1];
+    const next = pts[at + 2];
+    // The segment may have moved already (shared with an earlier lane); read live coordinates.
+    const keepsDirection = (far, near) => {
+        const before = near[key] - far[key];
+        const after = target - far[key];
+        return Math.sign(before) === Math.sign(after) && Math.abs(after) >= MIN_STUB;
+    };
+    if (!keepsDirection(prev, a) || !keepsDirection(next, b))
+        return false;
+    const trial = [
+        { ...prev },
+        { ...a, [key]: target },
+        { ...b, [key]: target },
+        { ...next },
+    ];
+    for (const n of layout.nodes) {
+        if (owner.has(n.id))
+            continue;
+        const box = {
+            x0: n.x - NODE_CLEARANCE,
+            y0: n.y - NODE_CLEARANCE,
+            x1: n.x + n.width + NODE_CLEARANCE,
+            y1: n.y + n.height + NODE_CLEARANCE,
+        };
+        for (let i = 0; i + 1 < trial.length; i++)
+            if (segmentHitsBox(trial[i], trial[i + 1], box))
+                return false;
+    }
+    if (runsAlongFrame(trial[1], trial[2], layout, horizontal) ||
+        runsAlongFrame(trial[0], trial[1], layout, !horizontal) ||
+        runsAlongFrame(trial[2], trial[3], layout, !horizontal)) {
+        return false;
+    }
+    a[key] = target;
+    b[key] = target;
+    return true;
+}
+/** True when the moved segment would hug a package frame border it is parallel to. */
+function runsAlongFrame(p, q, layout, horizontal) {
+    for (const f of layout.packages ?? []) {
+        if (horizontal) {
+            if (Math.max(p.x, q.x) <= f.x || Math.min(p.x, q.x) >= f.x + f.width)
+                continue;
+            if (Math.abs(p.y - f.y) < FRAME_CLEARANCE || Math.abs(p.y - (f.y + f.height)) < FRAME_CLEARANCE)
+                return true;
+        }
+        else {
+            if (Math.max(p.y, q.y) <= f.y || Math.min(p.y, q.y) >= f.y + f.height)
+                continue;
+            if (Math.abs(p.x - f.x) < FRAME_CLEARANCE || Math.abs(p.x - (f.x + f.width)) < FRAME_CLEARANCE)
+                return true;
+        }
+    }
+    return false;
+}
+function segmentHitsBox(p, q, box) {
+    return (Math.max(p.x, q.x) > box.x0 &&
+        Math.min(p.x, q.x) < box.x1 &&
+        Math.max(p.y, q.y) > box.y0 &&
+        Math.min(p.y, q.y) < box.y1);
+}

package/dist/layout/layout-metrics.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Layout quality metrics. Pure functions from (model, layout) to numbers, so a
+ * layout strategy change can be judged by a diff in figures rather than by eye.
+ *
+ * Edge polylines are taken at face value: for the viz engine they are bezier
+ * control points, which is a coarse but consistent approximation. Every metric
+ * is deterministic — the same (model, layout) always yields the same numbers —
+ * so a run can be committed as `rendered/metrics.baseline.json` and diffed
+ * against a later run to prove an improvement or a regression.
+ */
+import { PlantUmlModel } from '../foundation/model.js';
+import { LayoutResult, EdgeLayout, Point } from '../foundation/layout.js';
+export interface LayoutMetrics {
+    /** Proper crossings between segments of two different edges. */
+    edgeCrossings: number;
+    /** Edge segments passing through the interior of an unrelated node. */
+    edgeNodeIntersections: number;
+    /**
+     * Edges drawn with at least one diagonal segment (or no usable polyline at
+     * all) — the straight-line fallback an engine takes when its router returns
+     * no route. Zero means every edge is an orthogonal polyline.
+     */
+    nonOrthogonalEdgeCount: number;
+    /** Summed polyline length of every edge, in canvas pixels. */
+    totalEdgeLength: number;
+    /** Sum of node areas divided by canvas area (0..1). */
+    areaUtilization: number;
+    /** Canvas width / height. */
+    aspectRatio: number;
+    /** Entity text lines wider than the box they are drawn in. */
+    textOverflowCount: number;
+    /** Package label tabs that overlap content or are narrower than their text. */
+    labelOverlapCount: number;
+    /**
+     * Summed overlap length of *nearly* parallel segments from different edges —
+     * segments within [[PARALLEL_PROXIMITY]] px of each other. The orthogonal
+     * router's "parallel-line wall" is invisible to [[edgeCrossings]] (segments
+     * that merely run alongside never *cross*), so this counts that hidden
+     * clutter in canvas pixels.
+     */
+    overlappingEdgeLength: number;
+    /** Hub badges whose circle covers any of the owning node's text. */
+    badgeLabelOverlap: number;
+    /**
+     * Edge labels (`×N` weights and plain labels) that overlap another edge label
+     * or sit on top of a node box.
+     */
+    edgeLabelOverlap: number;
+    /** Edge labels whose rectangle intersects any node rectangle (should be 0). */
+    labelNodeOverlap: number;
+    /** Edge labels whose rectangle is crossed by a segment of an edge other than their own. */
+    labelEdgeOverlap: number;
+    /** Pairs of edge-label rectangles that intersect each other. */
+    labelLabelOverlap: number;
+    /**
+     * Incoming arrowheads stacked beyond a threshold on the same side of the
+     * same node — the "everything points at this hub" pile-up that
+     * [[edgeCrossings]] cannot see either.
+     */
+    hubArrowStack: number;
+    /**
+     * Area of the largest axis-aligned rectangle on the canvas that holds neither
+     * a node nor a package frame, divided by the canvas area (0..1). A big value
+     * is the "empty quadrant" a row-packed root layer leaves behind.
+     */
+    maxEmptyBlockRatio: number;
+    /**
+     * Edge segments running parallel to, and within [[EDGE_FLUSH_DISTANCE]] px
+     * of, a side of a node they do not end at or of a package frame border they
+     * do not end at — the edge then reads as part of the box outline.
+     */
+    edgeFlushCount: number;
+    /**
+     * "Combs": groups of at least [[BUNDLE_MIN_EDGES]] edges that share a source
+     * (or a target), run the same way, and have segments laid side by side
+     * within [[BUNDLE_LATERAL_DISTANCE]] px for at least [[BUNDLE_MIN_RUN]] px.
+     * Edges drawn exactly on top of each other (a merged trunk) are one line and
+     * do not form a comb. [[overlappingEdgeLength]] cannot see these: the lines
+     * sit just outside its proximity.
+     */
+    parallelBundleCount: number;
+    /**
+     * Edges that pass through the interior of a package frame neither endpoint
+     * belongs to (counted once per edge and frame) — a corridor should run in the
+     * gutters between frames, not across unrelated packages.
+     */
+    edgeFrameCrossings: number;
+    /**
+     * Edges whose polyline is longer than [[TRUNK_DETOUR_FACTOR]] times the
+     * Manhattan distance between their end points — a trunk that wanders round a
+     * cluster instead of running the lane between the rows.
+     */
+    trunkDetourCount: number;
+    /**
+     * Nested rectangular loops inside one package frame (edges between two nodes of the same frame): U-turns (three segments,
+     * the outer two running in opposite directions) whose bounding box encloses a
+     * node the edge does not end at (the route wraps a cluster) and lies inside
+     * another such U-turn's — counted once per inner loop. The concentric "coil" a trunk makes when it keeps
+     * circling the nodes it avoids.
+     */
+    nestedLoopCount: number;
+    /**
+     * Edge segments at least [[EDGE_NODE_FLUSH_MIN_LENGTH]] px long running
+     * parallel to a side of the node they end at, within
+     * [[EDGE_NODE_FLUSH_DISTANCE]] px — the line hugs the box it belongs to and
+     * is hard to tell from its outline.
+     */
+    edgeNodeFlush: number;
+    /**
+     * Smallest node-area ÷ frame-area over the package frames holding at least
+     * [[FRAME_FILL_MIN_NODES]] nodes (1 when no frame qualifies): low means a
+     * stretched, mostly empty frame.
+     */
+    frameFillRatio: number;
+    /**
+     * Smallest distance from any edge point to a canvas side (the shorter canvas
+     * side when there are no edges): a line hugging the canvas edge is easily
+     * cropped.
+     */
+    edgeCanvasMargin: number;
+    /**
+     * Layout-engine wall time in milliseconds (layout only: no transforms, SVG
+     * or rasterisation). Present only when the caller passes the measured time.
+     */
+    layoutMs?: number;
+}
+/**
+ * A named, pure measurement over a layout. The metrics registry is the single
+ * source of truth for which measurements [[computeLayoutMetrics]] reports:
+ * adding a metric means registering a `Metric`, not editing the function's
+ * return literal.
+ */
+export interface Metric {
+    /** Key the value is exposed under on [[LayoutMetrics]]. */
+    readonly name: string;
+    compute(model: PlantUmlModel, layout: LayoutResult): number;
+}
+/** Register a metric; the next [[computeLayoutMetrics]] call reports it. */
+export declare function registerMetric(metric: Metric): void;
+/** Remove a registered metric by name; returns whether one was removed. */
+export declare function unregisterMetric(name: string): boolean;
+/** Names of the currently registered metrics, in evaluation order. */
+export declare function listMetrics(): readonly string[];
+/**
+ * Computes every registered metric. The registry drives the assembly, so a new
+ * measurement participates without touching this function; [[LayoutMetrics]]
+ * remains the strong, hand-written shape the registered names must cover.
+ * `layoutMs` is not a measurement of the layout — it is the caller's wall-time
+ * reading — so it is attached directly rather than registered.
+ */
+export declare function computeLayoutMetrics(model: PlantUmlModel, layout: LayoutResult, layoutMs?: number): LayoutMetrics;
+/** Polyline length ÷ Manhattan distance above which an edge counts as a detour. */
+export declare const TRUNK_DETOUR_FACTOR = 2;
+/** Distance (px) and run (px) for [[LayoutMetrics.edgeNodeFlush]]. */
+export declare const EDGE_NODE_FLUSH_DISTANCE = 4;
+export declare const EDGE_NODE_FLUSH_MIN_LENGTH = 40;
+/** Frames with at least this many nodes count for [[LayoutMetrics.frameFillRatio]]. */
+export declare const FRAME_FILL_MIN_NODES = 6;
+/** For each polyline, the number of crossings it takes part in (each crossing counts for both edges). */
+export declare function perEdgeCrossings(polylines: Point[][]): number[];
+/** Lateral distance (px) within which two parallel segments count as overlapping. */
+export declare const PARALLEL_PROXIMITY = 8;
+/** Edge-to-box distance (px) below which a parallel segment counts as flush. */
+export declare const EDGE_FLUSH_DISTANCE = 6;
+/**
+ * Rasterises nodes and package frames onto a coarse grid and returns the
+ * largest all-empty rectangle (maximal-rectangle-in-histogram) over the canvas.
+ */
+export declare function computeMaxEmptyBlockRatio(layout: LayoutResult): number;
+/** Edges per comb needed to count it. */
+export declare const BUNDLE_MIN_EDGES = 5;
+/** Lateral distance (px) within which two same-way segments sit "side by side". */
+export declare const BUNDLE_LATERAL_DISTANCE = 16;
+/** Shared run (px) two side-by-side segments need to count. */
+export declare const BUNDLE_MIN_RUN = 120;
+/** One comb: the shared end node and the ids of the edges laid side by side. */
+export interface ParallelBundle {
+    end: 'source' | 'target';
+    node: string;
+    edges: string[];
+}
+/** Lists source-sharing and target-sharing combs; see [[LayoutMetrics.parallelBundleCount]]. */
+export declare function findParallelBundles(edges: EdgeLayout[]): ParallelBundle[];