@yalehwang/plantuml-js 0.2.2 → 0.3.1

package/dist/layout-metrics.js

@@ -1,241 +0,0 @@
-/**
- * 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 { METRICS, displayName } from './layout.js';
-import { countEdgeBoxIntersections, nodeRect } from './edge-router.js';
-import { measureTextWidth } from './text-measure.js';
-/** Package label tab geometry, kept in step with [[../render/svg]]. */
-const PACKAGE_TAB_HEIGHT = 18;
-const PACKAGE_LABEL_FONT_SIZE = 12;
-const PACKAGE_TAB_PADDING = 12;
-export function computeLayoutMetrics(model, layout) {
-    const edges = layout.edges ?? [];
-    const nodeArea = layout.nodes.reduce((sum, n) => sum + n.width * n.height, 0);
-    const canvasArea = layout.width * layout.height;
-    return {
-        edgeCrossings: countEdgeCrossings(edges.map((e) => e.points)),
-        edgeNodeIntersections: countEdgeBoxIntersections(edges, layout.nodes),
-        totalEdgeLength: edges.reduce((sum, e) => sum + polylineLength(e.points), 0),
-        areaUtilization: canvasArea > 0 ? nodeArea / canvasArea : 0,
-        aspectRatio: layout.height > 0 ? layout.width / layout.height : 0,
-        textOverflowCount: countTextOverflow(model, layout),
-        labelOverlapCount: countLabelOverlap(model, layout),
-        overlappingEdgeLength: countOverlappingEdgeLength(edges.map((e) => e.points)),
-        hubArrowStack: countHubArrowStack(edges),
-    };
-}
-function polylineLength(points) {
-    let len = 0;
-    for (let i = 0; i + 1 < points.length; i++) {
-        len += Math.hypot(points[i + 1].x - points[i].x, points[i + 1].y - points[i].y);
-    }
-    return len;
-}
-function orient(a, b, c) {
-    const v = (b.x - a.x) * (c.y - a.y) - (b.y - a.y) * (c.x - a.x);
-    return Math.abs(v) < 1e-9 ? 0 : v > 0 ? 1 : -1;
-}
-/** True when segments ab and cd cross at a point interior to both. */
-function segmentsCross(a, b, c, d) {
-    const o1 = orient(a, b, c);
-    const o2 = orient(a, b, d);
-    const o3 = orient(c, d, a);
-    const o4 = orient(c, d, b);
-    return o1 * o2 < 0 && o3 * o4 < 0;
-}
-function countEdgeCrossings(polylines) {
-    const segs = [];
-    polylines.forEach((pts, edge) => {
-        for (let i = 0; i + 1 < pts.length; i++) {
-            const a = pts[i];
-            const b = pts[i + 1];
-            segs.push({
-                a,
-                b,
-                edge,
-                minX: Math.min(a.x, b.x),
-                maxX: Math.max(a.x, b.x),
-                minY: Math.min(a.y, b.y),
-                maxY: Math.max(a.y, b.y),
-            });
-        }
-    });
-    segs.sort((p, q) => p.minX - q.minX);
-    let count = 0;
-    for (let i = 0; i < segs.length; i++) {
-        const s = segs[i];
-        for (let j = i + 1; j < segs.length; j++) {
-            const t = segs[j];
-            if (t.minX > s.maxX)
-                break;
-            if (t.edge === s.edge)
-                continue;
-            if (t.maxY < s.minY || t.minY > s.maxY)
-                continue;
-            if (segmentsCross(s.a, s.b, t.a, t.b))
-                count++;
-        }
-    }
-    return count;
-}
-function countTextOverflow(model, layout) {
-    const nodes = new Map(layout.nodes.map((n) => [n.id, n]));
-    let count = 0;
-    for (const entity of model.entities) {
-        const node = nodes.get(entity.id);
-        if (!node)
-            continue;
-        const lines = [displayName(entity), ...entity.members.map((m) => m.raw)];
-        for (const line of lines) {
-            const needed = measureTextWidth(line, METRICS.fontSize) + METRICS.paddingX * 2;
-            if (needed > node.width + 0.01)
-                count++;
-        }
-    }
-    return count;
-}
-function rectsOverlap(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);
-}
-/**
- * A package's label tab is drawn at its top-left corner. It is counted when it
- * overlaps an entity or sub-package frame inside the package, or when the tab
- * is narrower than the label text it has to hold.
- */
-function countLabelOverlap(model, layout) {
-    const frames = new Map((layout.packages ?? []).map((p) => [p.id, p]));
-    const nodes = new Map(layout.nodes.map((n) => [n.id, n]));
-    let count = 0;
-    for (const pkg of model.packages) {
-        const frame = frames.get(pkg.id);
-        if (!frame)
-            continue;
-        const textWidth = measureTextWidth(pkg.name, PACKAGE_LABEL_FONT_SIZE);
-        const wanted = textWidth + PACKAGE_TAB_PADDING;
-        const tab = {
-            x: frame.x,
-            y: frame.y,
-            width: Math.min(frame.width, Math.max(24, wanted)),
-            height: PACKAGE_TAB_HEIGHT,
-        };
-        let bad = textWidth + 6 > tab.width + 0.01;
-        for (const entity of model.entities) {
-            if (bad)
-                break;
-            if (entity.packageId !== pkg.id)
-                continue;
-            const node = nodes.get(entity.id);
-            if (node && rectsOverlap(tab, nodeRect(node)))
-                bad = true;
-        }
-        for (const child of model.packages) {
-            if (bad)
-                break;
-            if (child.parentId !== pkg.id)
-                continue;
-            const childFrame = frames.get(child.id);
-            if (childFrame && rectsOverlap(tab, childFrame))
-                bad = true;
-        }
-        if (bad)
-            count++;
-    }
-    return count;
-}
-/**
- * Summed length of collinear, overlapping segments from different edges. Two
- * axis-aligned segments that lie on the same line and overlap are a
- * "parallel-line wall": they never produce a proper crossing (so
- * [[countEdgeCrossings]] misses them) yet still read as clutter. Each
- * (segment, segment) overlap is counted once, in canvas pixels.
- */
-function countOverlappingEdgeLength(polylines) {
-    const segs = [];
-    polylines.forEach((pts, edge) => {
-        for (let i = 0; i + 1 < pts.length; i++) {
-            segs.push({ a: pts[i], b: pts[i + 1], edge });
-        }
-    });
-    let total = 0;
-    for (let i = 0; i < segs.length; i++) {
-        for (let j = i + 1; j < segs.length; j++) {
-            if (segs[i].edge === segs[j].edge)
-                continue;
-            total += collinearOverlapLength(segs[i].a, segs[i].b, segs[j].a, segs[j].b);
-        }
-    }
-    return total;
-}
-/** Overlap length of two segments when collinear, else 0 (in canvas pixels). */
-function collinearOverlapLength(a, b, c, d) {
-    const ux = b.x - a.x;
-    const uy = b.y - a.y;
-    const vx = d.x - c.x;
-    const vy = d.y - c.y;
-    const lenU = Math.hypot(ux, uy);
-    const lenV = Math.hypot(vx, vy);
-    if (lenU < 1e-9 || lenV < 1e-9)
-        return 0;
-    // Parallel: the two direction vectors must be colinear.
-    if (Math.abs(ux * vy - uy * vx) > 1e-9 * lenU * lenV)
-        return 0;
-    // Colinear: `c` must lie on the line through `a`/`b` (perpendicular distance).
-    const distC = Math.abs(ux * (c.y - a.y) - uy * (c.x - a.x)) / lenU;
-    if (distC > 0.01)
-        return 0;
-    const uxN = ux / lenU;
-    const uyN = uy / lenU;
-    const proj = (p) => (p.x - a.x) * uxN + (p.y - a.y) * uyN;
-    const t0 = Math.min(proj(a), proj(b));
-    const t1 = Math.max(proj(a), proj(b));
-    const s0 = Math.min(proj(c), proj(d));
-    const s1 = Math.max(proj(c), proj(d));
-    const overlap = Math.min(t1, s1) - Math.max(t0, s0);
-    return overlap > 0 ? overlap : 0;
-}
-/**
- * Incoming arrowheads are grouped by (target node, entry side). A side that
- * receives more than [[HUB_ARROW_STACK_THRESHOLD]] arrowheads contributes its
- * excess to the total — the "everyone points at this hub from the same side"
- * pile-up, invisible to [[countEdgeCrossings]].
- */
-const HUB_ARROW_STACK_THRESHOLD = 3;
-function countHubArrowStack(edges) {
-    const groups = new Map();
-    for (const edge of edges) {
-        const pts = edge.points;
-        if (pts.length < 2)
-            continue;
-        const side = approachSide(pts[pts.length - 2], pts[pts.length - 1]);
-        if (side === undefined)
-            continue;
-        const key = `${edge.target}\u0000${side}`;
-        groups.set(key, (groups.get(key) ?? 0) + 1);
-    }
-    let total = 0;
-    for (const count of groups.values()) {
-        if (count > HUB_ARROW_STACK_THRESHOLD)
-            total += count - HUB_ARROW_STACK_THRESHOLD;
-    }
-    return total;
-}
-/** Side of the target the arrowhead enters from, derived from the last segment. */
-function approachSide(from, to) {
-    const dx = to.x - from.x;
-    const dy = to.y - from.y;
-    if (Math.abs(dx) < 1e-9 && Math.abs(dy) < 1e-9)
-        return undefined;
-    if (Math.abs(dx) >= Math.abs(dy))
-        return dx > 0 ? 'left' : 'right';
-    return dy > 0 ? 'top' : 'bottom';
-}

package/dist/layout.d.ts

@@ -1,75 +0,0 @@
-/**
- * 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 (elkjs, @viz-js/viz, 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: 18;
-    readonly fontSize: 12;
-    readonly tabPadding: 12;
-};
-/** 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;
-};

package/dist/layout.js

@@ -1,51 +0,0 @@
-/**
- * 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 (elkjs, @viz-js/viz, a custom tuner) is an injection, not a rewrite.
- */
-import { measureTextWidth, MONOSPACE_FONT_SIZE } from './text-measure.js';
-/**
- * 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 const METRICS = {
-    fontFamily: 'monospace',
-    fontSize: MONOSPACE_FONT_SIZE,
-    lineHeight: 18,
-    paddingX: 10,
-    paddingY: 8,
-    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 const PACKAGE_LABEL = {
-    tabHeight: 18,
-    fontSize: 12,
-    tabPadding: 12,
-};
-/** Reconstruct the name drawn in the title compartment, generics expanded. */
-export function displayName(entity) {
-    const generics = entity.generics;
-    if (!generics || generics.length === 0)
-        return entity.name;
-    return `${entity.name}<${generics.join(', ')}>`;
-}
-/**
- * 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 function estimateEntitySize(entity) {
-    const lines = [
-        displayName(entity),
-        ...entity.members.map((m) => m.raw),
-    ];
-    const longest = lines.reduce((max, line) => Math.max(max, measureTextWidth(line, METRICS.fontSize)), 0);
-    const width = Math.max(METRICS.minWidth, longest + METRICS.paddingX * 2);
-    const height = lines.length * METRICS.lineHeight + METRICS.paddingY * 2;
-    return { width, height };
-}

package/dist/parser.d.ts

@@ -1,17 +0,0 @@
-/**
- * Hand-written recursive-descent parser for the PlantUML class-diagram subset.
- *
- * M2 scope adds members (visibility `-`/`+`/`#`/`~`, fields, method
- * signatures), relations (inheritance / implementation / dependency /
- * association / aggregation / composition with cardinality and labels),
- * generics (`List~Item~`, `BaseEntity<T>`), package/namespace grouping,
- * aliases, and tolerant skipping of skinparam/hide/note directives.
- */
-import { PlantUmlModel } from './model.js';
-/**
- * Parse a PlantUML source string into a PlantUmlModel.
- *
- * The parser is total: unrecognised lines (skinparam, hide, note, title,
- * legend, …) are tolerated and skipped rather than failing the parse.
- */
-export declare function parsePlantUml(source: string): PlantUmlModel;