@yalehwang/plantuml-js 0.2.2 → 0.3.1

package/dist/foundation/labels.js

@@ -0,0 +1,231 @@
+/**
+ * Edge-label and hub-badge geometry shared by the SVG renderer and the layout
+ * metrics, so a drawn label and a measured label are the same rectangle.
+ *
+ * Weight labels (`×N`) are placed on the edge itself over a white backing box.
+ * Candidate anchors run along the edge's segments, longest first; the first
+ * candidate that collides with no node and no previously placed label wins, so
+ * labels of neighbouring edges do not pile onto each other.
+ */
+import { METRICS, displayName } from './layout.js';
+import { nodeRect } from './edge-router.js';
+import { measureTextWidth } from './text-measure.js';
+export const EDGE_LABEL_FONT_SIZE = 11;
+const EDGE_LABEL_PAD_X = 3;
+const EDGE_LABEL_HEIGHT = 14;
+/** Fractions along a segment tried, in order, for a label anchor. */
+const ANCHOR_FRACTIONS = [0.5, 0.3, 0.7, 0.15, 0.85];
+export const HUB_BADGE_RADIUS = 9;
+/** Hub badge circle: centred on the node's top-right corner, half outside the box. */
+export function hubBadgeCircle(node) {
+    return { cx: node.x + node.width, cy: node.y, r: HUB_BADGE_RADIUS };
+}
+export function hubBadgeRect(node) {
+    const { cx, cy, r } = hubBadgeCircle(node);
+    return { x: cx - r, y: cy - r, width: 2 * r, height: 2 * r };
+}
+/** Bounding boxes of the text lines drawn inside a node (title + members). */
+export function entityTextRects(entity, node) {
+    const rects = [];
+    const title = measureTextWidth(displayName(entity), METRICS.fontSize);
+    rects.push({
+        x: node.x + (node.width - title) / 2,
+        y: node.y + METRICS.paddingY,
+        width: title,
+        height: METRICS.lineHeight,
+    });
+    entity.members.forEach((member, i) => {
+        rects.push({
+            x: node.x + METRICS.paddingX,
+            y: node.y + METRICS.paddingY + METRICS.lineHeight * (i + 1),
+            width: measureTextWidth(member.raw, METRICS.fontSize),
+            height: METRICS.lineHeight,
+        });
+    });
+    return rects;
+}
+export function rectsIntersect(a, b) {
+    return (a.x < b.x + b.width &&
+        b.x < a.x + a.width &&
+        a.y < b.y + b.height &&
+        b.y < a.y + a.height);
+}
+/** Same-text labels sharing a source (or target) and the other end's package collapse to one. */
+export const LABEL_DEDUPE_MIN = 3;
+/** A collapsed label standing for at least this many edges carries a `×N` count. */
+export const LABEL_COUNT_BADGE_MIN = 4;
+const PLAIN_LABEL_FONT_SIZE = 12;
+const PLAIN_LABEL_HEIGHT = 14;
+/** Gap between a beside-the-line label and the line. */
+const LABEL_SIDE_GAP = 2;
+/** True when the segment ab touches the rectangle (Liang–Barsky clip). */
+export function segmentIntersectsRect(a, b, r) {
+    let t0 = 0;
+    let t1 = 1;
+    const dx = b.x - a.x;
+    const dy = b.y - a.y;
+    const clip = (p, q) => {
+        if (p === 0)
+            return q >= 0;
+        const t = q / p;
+        if (p < 0) {
+            if (t > t1)
+                return false;
+            if (t > t0)
+                t0 = t;
+        }
+        else {
+            if (t < t0)
+                return false;
+            if (t < t1)
+                t1 = t;
+        }
+        return true;
+    };
+    return (clip(-dx, a.x - r.x) &&
+        clip(dx, r.x + r.width - a.x) &&
+        clip(-dy, a.y - r.y) &&
+        clip(dy, r.y + r.height - a.y));
+}
+/** Edge ids (`rel-<i>`) of every segment of every edge other than `ownId` that crosses `rect`. */
+export function rectHitsOtherEdge(rect, edges, ownId) {
+    for (const e of edges) {
+        if (e.id === ownId)
+            continue;
+        for (let i = 0; i + 1 < e.points.length; i++) {
+            if (segmentIntersectsRect(e.points[i], e.points[i + 1], rect))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Plain labels that repeat along one bundle (same text, same source — or same
+ * target — and the same package at the other end) show on a single
+ * representative edge; the rest keep a `<title>` tooltip. Returns the
+ * representative index → group size, and the set of suppressed indexes.
+ */
+function dedupePlainLabels(model) {
+    const pkgOf = new Map(model.entities.map((e) => [e.id, e.packageId ?? e.id]));
+    const reps = new Map();
+    const suppressed = new Set();
+    for (const end of ['source', 'target']) {
+        const other = end === 'source' ? 'target' : 'source';
+        const groups = new Map();
+        model.relations.forEach((rel, i) => {
+            if (!rel.label || suppressed.has(i))
+                return;
+            const key = `${rel[end]}\u0000${rel.label}\u0000${pkgOf.get(rel[other]) ?? rel[other]}`;
+            const list = groups.get(key);
+            if (list)
+                list.push(i);
+            else
+                groups.set(key, [i]);
+        });
+        for (const g of groups.values()) {
+            if (g.length < LABEL_DEDUPE_MIN)
+                continue;
+            const total = g.reduce((n, i) => n + (reps.get(i) ?? 1), 0);
+            reps.set(g[0], total);
+            for (const i of g.slice(1)) {
+                suppressed.add(i);
+                reps.delete(i);
+            }
+        }
+    }
+    return { reps, suppressed };
+}
+/**
+ * Candidate rectangles for a plain label: beside each segment (longest first),
+ * offset to either side so the text never sits on its own line.
+ */
+function plainLabelCandidates(points, width, height) {
+    const segs = [];
+    for (let i = 0; i + 1 < points.length; i++) {
+        const len = Math.hypot(points[i + 1].x - points[i].x, points[i + 1].y - points[i].y);
+        if (len > 0)
+            segs.push({ a: points[i], b: points[i + 1], len });
+    }
+    segs.sort((p, q) => q.len - p.len);
+    const rects = [];
+    for (const { a, b } of segs) {
+        const horizontal = Math.abs(b.x - a.x) >= Math.abs(b.y - a.y);
+        for (const t of ANCHOR_FRACTIONS) {
+            const cx = a.x + (b.x - a.x) * t;
+            const cy = a.y + (b.y - a.y) * t;
+            for (const side of [-1, 1]) {
+                rects.push(horizontal
+                    ? { x: cx - width / 2, y: side < 0 ? cy - LABEL_SIDE_GAP - height : cy + LABEL_SIDE_GAP, width, height }
+                    : { x: side < 0 ? cx - LABEL_SIDE_GAP - width : cx + LABEL_SIDE_GAP, y: cy - height / 2, width, height });
+            }
+        }
+    }
+    return rects;
+}
+/** Place every weight label and collect every plain edge label, deterministically. */
+export function placeEdgeLabels(model, layout) {
+    const edges = layout.edges ?? [];
+    const edgesById = new Map(edges.map((e) => [e.id, e]));
+    const nodeRects = layout.nodes.map(nodeRect);
+    const out = [];
+    const placed = [];
+    const { reps, suppressed } = dedupePlainLabels(model);
+    // A plain label sits beside its own edge, clear of every node, every other
+    // edge and every earlier label. A label that fits nowhere is left out (the
+    // renderer keeps it as a `<title>` tooltip).
+    model.relations.forEach((rel, edge) => {
+        const points = edgesById.get(`rel-${edge}`)?.points;
+        if (!points || points.length < 2 || !rel.label || suppressed.has(edge))
+            return;
+        const count = reps.get(edge) ?? 1;
+        const text = count >= LABEL_COUNT_BADGE_MIN ? `${rel.label} ×${count}` : rel.label;
+        const width = measureTextWidth(text, PLAIN_LABEL_FONT_SIZE);
+        const free = plainLabelCandidates(points, width, PLAIN_LABEL_HEIGHT).find((rect) => !nodeRects.some((n) => rectsIntersect(rect, n)) &&
+            !placed.some((p) => rectsIntersect(rect, p)) &&
+            !rectHitsOtherEdge(rect, edges, `rel-${edge}`) &&
+            !ownEdgeTouches(rect, points));
+        if (!free)
+            return;
+        placed.push(free);
+        out.push({ edge, kind: 'label', text, rect: free });
+    });
+    model.relations.forEach((rel, edge) => {
+        const points = edgesById.get(`rel-${edge}`)?.points;
+        if (!points || points.length < 2 || !rel.weight || rel.weight <= 1)
+            return;
+        const text = `×${rel.weight}`;
+        const width = measureTextWidth(text, EDGE_LABEL_FONT_SIZE) + EDGE_LABEL_PAD_X * 2;
+        const candidates = labelCandidates(points, width, EDGE_LABEL_HEIGHT);
+        const clear = (rect) => !nodeRects.some((n) => rectsIntersect(rect, n)) && !placed.some((p) => rectsIntersect(rect, p));
+        const free = candidates.find((rect) => clear(rect) && !rectHitsOtherEdge(rect, edges, `rel-${edge}`)) ??
+            candidates.find(clear);
+        const rect = free ?? candidates[0];
+        placed.push(rect);
+        out.push({ edge, kind: 'weight', text, rect });
+    });
+    return out;
+}
+function ownEdgeTouches(rect, points) {
+    for (let i = 0; i + 1 < points.length; i++) {
+        if (segmentIntersectsRect(points[i], points[i + 1], rect))
+            return true;
+    }
+    return false;
+}
+function labelCandidates(points, width, height) {
+    const segs = [];
+    for (let i = 0; i + 1 < points.length; i++) {
+        const len = Math.hypot(points[i + 1].x - points[i].x, points[i + 1].y - points[i].y);
+        segs.push({ a: points[i], b: points[i + 1], len });
+    }
+    segs.sort((p, q) => q.len - p.len);
+    const rects = [];
+    for (const { a, b } of segs) {
+        for (const t of ANCHOR_FRACTIONS) {
+            const cx = a.x + (b.x - a.x) * t;
+            const cy = a.y + (b.y - a.y) * t;
+            rects.push({ x: cx - width / 2, y: cy - height / 2, width, height });
+        }
+    }
+    return rects;
+}

package/dist/foundation/layers.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Semantic layer resolution for the ELK engine: which layer a package belongs
+ * to, how layers are ordered, and which ELK partition each package lands in.
+ * Pure functions over the model; no ELK types involved.
+ */
+import { PlantUmlModel, PlantUmlPackage } from './model.js';
+/** Resolve a package's semantic layer from its explicit field or its name. */
+export declare function packageLayer(pkg: PlantUmlPackage): string | undefined;
+/**
+ * Order semantic layers by dependency topology instead of puml declaration
+ * order: a layer that depends on another (`A ..> B` across layers) sits *above*
+ * its dependency, so entry layers (Tests, Examples) stack over the base they
+ * consume (Src) and independent layers (Templates) fall out of the sandwich.
+ *
+ * A Kahn topological sort places in-degree-zero layers (nothing depends on
+ * them) first, breaking ties in declaration order for determinism. Layers left
+ * over because of a dependency cycle are appended in declaration order, so a
+ * cyclic graph still yields a stable (if not strictly topological) order; the
+ * renderer marks the offending back-edges as feedback arcs.
+ */
+export declare function topologicalLayerOrder(model: PlantUmlModel): string[];
+/** Ordered, de-duplicated list of semantic layers (dependency topology by default). */
+export declare function resolveLayerOrder(model: PlantUmlModel, layerOrder?: string[]): string[];
+/** Map each package to its partition index (layers first, unlayered last). */
+export declare function assignPartitions(model: PlantUmlModel, layers: string[]): Map<string, number>;

package/dist/foundation/layers.js

@@ -0,0 +1,101 @@
+/**
+ * Semantic layer resolution for the ELK engine: which layer a package belongs
+ * to, how layers are ordered, and which ELK partition each package lands in.
+ * Pure functions over the model; no ELK types involved.
+ */
+/** Name convention: `"X Layer"` declares a semantic layer `X`. */
+const LAYER_SUFFIX = /^(.*)\s+Layer$/i;
+/** Resolve a package's semantic layer from its explicit field or its name. */
+export function packageLayer(pkg) {
+    if (pkg.layer !== undefined)
+        return pkg.layer;
+    const m = LAYER_SUFFIX.exec(pkg.name);
+    if (!m)
+        return undefined;
+    const core = m[1].trim();
+    return core === '' ? undefined : core;
+}
+/**
+ * Order semantic layers by dependency topology instead of puml declaration
+ * order: a layer that depends on another (`A ..> B` across layers) sits *above*
+ * its dependency, so entry layers (Tests, Examples) stack over the base they
+ * consume (Src) and independent layers (Templates) fall out of the sandwich.
+ *
+ * A Kahn topological sort places in-degree-zero layers (nothing depends on
+ * them) first, breaking ties in declaration order for determinism. Layers left
+ * over because of a dependency cycle are appended in declaration order, so a
+ * cyclic graph still yields a stable (if not strictly topological) order; the
+ * renderer marks the offending back-edges as feedback arcs.
+ */
+export function topologicalLayerOrder(model) {
+    const declared = [];
+    for (const pkg of model.packages) {
+        const layer = packageLayer(pkg);
+        if (layer !== undefined && !declared.includes(layer))
+            declared.push(layer);
+    }
+    if (declared.length <= 1)
+        return declared;
+    const pkgById = new Map(model.packages.map((p) => [p.id, p]));
+    const layerOf = new Map();
+    for (const entity of model.entities) {
+        const pkg = entity.packageId ? pkgById.get(entity.packageId) : undefined;
+        layerOf.set(entity.id, pkg ? packageLayer(pkg) : undefined);
+    }
+    const dependsOn = new Map();
+    const dependents = new Map();
+    for (const layer of declared) {
+        dependsOn.set(layer, new Set());
+        dependents.set(layer, 0);
+    }
+    for (const relation of model.relations) {
+        const source = layerOf.get(relation.source);
+        const target = layerOf.get(relation.target);
+        if (source === undefined || target === undefined || source === target)
+            continue;
+        const set = dependsOn.get(source);
+        if (!set.has(target)) {
+            set.add(target);
+            dependents.set(target, (dependents.get(target) ?? 0) + 1);
+        }
+    }
+    const order = [];
+    const done = new Set();
+    const queue = declared.filter((layer) => (dependents.get(layer) ?? 0) === 0);
+    for (let i = 0; i < queue.length; i++) {
+        const layer = queue[i];
+        order.push(layer);
+        done.add(layer);
+        for (const dep of dependsOn.get(layer) ?? []) {
+            const remaining = (dependents.get(dep) ?? 0) - 1;
+            dependents.set(dep, remaining);
+            if (remaining === 0 && !done.has(dep))
+                queue.push(dep);
+        }
+    }
+    // Cyclic remainder: keep declaration order so the output is stable.
+    for (const layer of declared) {
+        if (!done.has(layer))
+            order.push(layer);
+    }
+    return order;
+}
+/** Ordered, de-duplicated list of semantic layers (dependency topology by default). */
+export function resolveLayerOrder(model, layerOrder) {
+    if (layerOrder) {
+        return layerOrder.filter((layer, i, all) => all.indexOf(layer) === i);
+    }
+    return topologicalLayerOrder(model);
+}
+/** Map each package to its partition index (layers first, unlayered last). */
+export function assignPartitions(model, layers) {
+    const partitions = new Map();
+    if (layers.length === 0)
+        return partitions;
+    for (const pkg of model.packages) {
+        const layer = packageLayer(pkg);
+        const index = layer !== undefined ? layers.indexOf(layer) : -1;
+        partitions.set(pkg.id, index >= 0 ? index : layers.length);
+    }
+    return partitions;
+}

package/dist/foundation/layout.d.ts

@@ -0,0 +1,116 @@
+/**
+ * LayoutEngine — the pluggable layout contract. A LayoutEngine is a pure
+ * function from PlantUmlModel to concrete positions; the parser never talks
+ * to a layout engine and the renderer never talks to the parser, so swapping
+ * engines (ELK, Graphviz, a custom tuner) is an injection, not a rewrite.
+ */
+import { PlantUmlModel, PlantUmlEntity } from './model.js';
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface NodeLayout {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface EdgeLayout {
+    id: string;
+    source: string;
+    target: string;
+    points: Point[];
+}
+export interface PackageLayout {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface LayoutResult {
+    nodes: NodeLayout[];
+    edges: EdgeLayout[];
+    /** Package frames; engines without container support may omit this. */
+    packages?: PackageLayout[];
+    width: number;
+    height: number;
+}
+export interface LayoutEngine {
+    layout(model: PlantUmlModel): Promise<LayoutResult>;
+}
+/**
+ * Shared drawing metrics. The renderer reads these so entity sizing and the
+ * emitted SVG stay in lockstep: the font family and size are bound to the same
+ * monospace advance [[../text-measure]] measures with.
+ */
+export declare const METRICS: {
+    readonly fontFamily: "monospace";
+    readonly fontSize: 13;
+    readonly lineHeight: 18;
+    readonly paddingX: 10;
+    readonly paddingY: 8;
+    readonly minWidth: 60;
+};
+/**
+ * Package label-tab geometry, shared by the renderer and the layout-metrics
+ * overlap counter so a drawn tab and a measured tab are the same rectangle.
+ */
+export declare const PACKAGE_LABEL: {
+    readonly tabHeight: 20;
+    readonly fontSize: 12;
+    readonly tabPadding: 8;
+};
+/** Spacing grid (px). Entity box sizes snap up to a multiple of it. */
+export declare const GRID = 8;
+export declare function snapUp(n: number, grid?: number): number;
+/** Reconstruct the name drawn in the title compartment, generics expanded. */
+export declare function displayName(entity: PlantUmlEntity): string;
+/**
+ * Approximate the on-canvas size of an entity box. The title plus every member
+ * line contributes one row; the width is the longest rendered line measured
+ * through the text table plus padding, never below MIN_WIDTH.
+ */
+export declare function estimateEntitySize(entity: PlantUmlEntity): {
+    width: number;
+    height: number;
+};
+/**
+ * Level of member detail drawn per entity: every member (`full`), the first
+ * few plus a count (`compact`), or just the class name (`names`).
+ */
+export type DetailLevel = 'full' | 'compact' | 'names';
+/** Entity count up to which `full` is chosen automatically. */
+export declare const DETAIL_FULL_MAX_ENTITIES = 40;
+/** Entity count up to which `compact` is chosen automatically (beyond: `names`). */
+export declare const DETAIL_COMPACT_MAX_ENTITIES = 150;
+/** Member rows kept per entity in `compact` mode. */
+export declare const COMPACT_MEMBER_ROWS = 4;
+export declare function autoDetail(entityCount: number): DetailLevel;
+/**
+ * Reduce member rows to the requested detail level *before* layout, so boxes
+ * are sized for what is actually drawn. `undefined` picks by entity count.
+ */
+export declare function applyDetail(model: PlantUmlModel, detail?: DetailLevel): PlantUmlModel;
+/**
+ * Group nodes into rows: within one package (or the top level), nodes whose
+ * vertical extents overlap belong to the same layered-layout rank. Returns
+ * arrays of node ids, each sorted top-to-bottom.
+ */
+export declare function layoutRows(model: PlantUmlModel, layout: LayoutResult): NodeLayout[][];
+/**
+ * Top-align the nodes of every row (never moving a node down or out of its
+ * package) and keep edges attached: an endpoint on a moved node shifts with it,
+ * dragging along the next bend when the first segment is horizontal, so
+ * orthogonal routes stay orthogonal. Mutates and returns `layout`.
+ */
+export declare function alignRows(model: PlantUmlModel, layout: LayoutResult): LayoutResult;
+/**
+ * Top-align an isolated package frame (no edge touches any entity inside it)
+ * with the topmost side-by-side neighbour frame, so a lone package sits level
+ * with its neighbour instead of floating at its own offset. Only moves up, and
+ * only when the frame (with its contents) stays clear of everything else.
+ * Mutates and returns `layout`.
+ */
+export declare function alignIsolatedFrames(model: PlantUmlModel, layout: LayoutResult): LayoutResult;