@yalehwang/plantuml-js 0.3.1 → 0.4.1

package/README.md

@@ -6,9 +6,28 @@ default, `@viz-js/viz` (WASM Graphviz) as an option.
 
 > **Engine status** — `'viz'` is **experimental**. It reaches only a fraction
 > of `'elk'`'s area utilization and still routes a few edges through unrelated
-> nodes on large package diagrams. See [`docs/viz-decision.md`](docs/viz-decision.md)
+> nodes on large package diagrams. See
+> [`docs/viz-decision.md`](https://github.com/yaleh/plantuml-js/blob/author/docs/viz-decision.md)
 > for the measured comparison. Use `'elk'` (the default) for production diagrams.
 
+## What it renders
+
+`@yalehwang/plantuml-js` turns a PlantUML class diagram into a styled SVG. Here
+is a minimal diagram through the default `'elk'` engine — three-compartment
+class/interface boxes, a package, and implementation / composition / dependency
+edges:
+
+![Minimal class diagram — package, class boxes, and three edge kinds](https://raw.githubusercontent.com/yaleh/plantuml-js/author/docs/img/quickstart.elk.png)
+
+The same pipeline on a real medium-size architecture graph (package grouping,
+orthogonal edge routing, bundled arrowheads):
+
+![Medium architecture diagram](https://raw.githubusercontent.com/yaleh/plantuml-js/author/docs/img/m-architecture.elk.png)
+
+See the [gallery](https://github.com/yaleh/plantuml-js/blob/author/docs/gallery.md)
+for every figure's source `.puml`, its SVG output, and the `elk` vs `viz`
+comparison.
+
 ## Install
 
 ```bash

package/dist/foundation/layout.d.ts

@@ -68,9 +68,26 @@ 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.
+ * Heights of the three UML compartments inside an entity box: the title band,
+ * the attribute (field) band, and the operations (method) band. Each band is a
+ * whole number of text rows; the compartment separator rules are zero-thickness
+ * boundaries drawn *between* bands and so consume no additional height.
+ *
+ * The renderer and {@link estimateEntitySize} both read this, so the drawn
+ * boxes and the emitted `data-title-h` / `data-attrs-h` / `data-ops-h`
+ * metadata can never drift apart.
+ */
+export declare function compartmentHeights(entity: PlantUmlEntity): {
+    title: number;
+    attrs: number;
+    ops: number;
+};
+/**
+ * Approximate the on-canvas size of an entity box. Height is the sum of the
+ * three compartments (title rows + attribute rows + operation rows) plus the
+ * top/bottom padding, snapped up to the spacing grid; 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;

package/dist/foundation/layout.js

@@ -40,9 +40,36 @@ export function displayName(entity) {
     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.
+ * Heights of the three UML compartments inside an entity box: the title band,
+ * the attribute (field) band, and the operations (method) band. Each band is a
+ * whole number of text rows; the compartment separator rules are zero-thickness
+ * boundaries drawn *between* bands and so consume no additional height.
+ *
+ * The renderer and {@link estimateEntitySize} both read this, so the drawn
+ * boxes and the emitted `data-title-h` / `data-attrs-h` / `data-ops-h`
+ * metadata can never drift apart.
+ */
+export function compartmentHeights(entity) {
+    let attrs = 0;
+    let ops = 0;
+    for (const member of entity.members) {
+        if (member.kind === 'method')
+            ops++;
+        else
+            attrs++;
+    }
+    return {
+        title: METRICS.lineHeight,
+        attrs: attrs * METRICS.lineHeight,
+        ops: ops * METRICS.lineHeight,
+    };
+}
+/**
+ * Approximate the on-canvas size of an entity box. Height is the sum of the
+ * three compartments (title rows + attribute rows + operation rows) plus the
+ * top/bottom padding, snapped up to the spacing grid; width is the longest
+ * rendered line measured through the text table plus padding, never below
+ * MIN_WIDTH.
  */
 export function estimateEntitySize(entity) {
     const lines = [
@@ -51,7 +78,8 @@ export function estimateEntitySize(entity) {
     ];
     const longest = lines.reduce((max, line) => Math.max(max, measureTextWidth(line, METRICS.fontSize)), 0);
     const width = snapUp(Math.max(METRICS.minWidth, longest + METRICS.paddingX * 2));
-    const height = snapUp(lines.length * METRICS.lineHeight + METRICS.paddingY * 2);
+    const bands = compartmentHeights(entity);
+    const height = snapUp(bands.title + bands.attrs + bands.ops + METRICS.paddingY * 2);
     return { width, height };
 }
 /** Entity count up to which `full` is chosen automatically. */

package/dist/render/svg.js

@@ -3,7 +3,7 @@
  * The renderer consumes only the LayoutResult (positions/sizes) plus the
  * model's display fields; it never reaches back into the parser.
  */
-import { METRICS, PACKAGE_LABEL, displayName, } from '../foundation/layout.js';
+import { METRICS, PACKAGE_LABEL, displayName, compartmentHeights, } from '../foundation/layout.js';
 import { measureTextWidth } from '../foundation/text-measure.js';
 import { hubBadgeCircle, placeEdgeLabels, EDGE_LABEL_FONT_SIZE } from '../foundation/labels.js';
 import { renderLegend, LEGEND_DEFAULT_NODE_THRESHOLD } from './legend.js';
@@ -134,6 +134,14 @@ function renderEntity(entity, node, theme) {
     const fontStyle = italic ? ' font-style="italic"' : '';
     const stub = entity.stub === true;
     const { color, font } = theme;
+    // UML compartments, top to bottom: title / attributes (fields) / operations
+    // (methods). Members are regrouped by kind, so an authored interleaving of
+    // fields and methods still lands in the two canonical member bands.
+    const attrs = entity.members.filter((m) => m.kind !== 'method');
+    const ops = entity.members.filter((m) => m.kind === 'method');
+    const bands = compartmentHeights(entity);
+    const titleBottom = node.y + METRICS.paddingY + bands.title;
+    const opsTop = titleBottom + bands.attrs;
     const parts = [];
     if (entity.groupMembers)
         parts.push(`<title>${entity.groupMembers.map(escapeXml).join('\n')}</title>`);
@@ -145,17 +153,25 @@ function renderEntity(entity, node, theme) {
         ` height="${fmt(node.height)}" rx="${theme.shape.nodeRadius}" ry="${theme.shape.nodeRadius}"` +
         ` fill="${weak ? color.stubFill : color.nodeFill}"` +
         `${stubAttrs} stroke="${weak ? color.strokeStub : color.stroke}" stroke-width="${theme.stroke.node}"/>`);
-    const headerBottom = node.y + METRICS.paddingY + METRICS.lineHeight;
+    const rule = (y, kind) => `<line class="uml-compartment-rule" data-rule="${kind}"` +
+        ` x1="${fmt(node.x)}" y1="${fmt(y)}"` +
+        ` x2="${fmt(node.x + node.width)}" y2="${fmt(y)}"` +
+        ` stroke="${color.stroke}" stroke-width="${theme.stroke.node}"/>`;
+    // Title/attrs boundary: present whenever any member row is drawn.
+    if (attrs.length + ops.length > 0)
+        parts.push(rule(titleBottom, 'title'));
+    // Attrs/ops boundary: only when both member compartments carry rows. An
+    // interface (methods only) therefore has exactly one rule, `data-rule="title"`.
+    if (attrs.length > 0 && ops.length > 0)
+        parts.push(rule(opsTop, 'ops'));
     const titleBaseline = node.y + METRICS.paddingY + METRICS.fontSize + 1;
-    if (entity.members.length > 0) {
-        parts.push(`<line x1="${fmt(node.x)}" y1="${fmt(headerBottom)}"` +
-            ` x2="${fmt(node.x + node.width)}" y2="${fmt(headerBottom)}"` +
-            ` stroke="${color.stroke}" stroke-width="${theme.stroke.node}"/>`);
-    }
     parts.push(textEl(displayName(entity), node.x + node.width / 2, titleBaseline, 'middle', font.size.title, font.weight.title, color.textTitle, theme, fontStyle));
-    entity.members.forEach((member, i) => {
-        const baseline = node.y + METRICS.paddingY + METRICS.lineHeight * (i + 1) + METRICS.fontSize + 1;
-        parts.push(textEl(member.raw, node.x + METRICS.paddingX, baseline, 'start', font.size.member, font.weight.member, color.textMember, theme));
+    const memberText = (member, idx, top, cls) => textEl(member.raw, node.x + METRICS.paddingX, top + METRICS.lineHeight * idx + METRICS.fontSize + 1, 'start', font.size.member, font.weight.member, color.textMember, theme, ` class="${cls}"`);
+    attrs.forEach((member, i) => {
+        parts.push(memberText(member, i, titleBottom, 'uml-attr'));
+    });
+    ops.forEach((member, i) => {
+        parts.push(memberText(member, i, opsTop, 'uml-op'));
     });
     if (entity.usageCount && entity.usageCount > 0) {
         parts.push(renderHubBadge(node, entity.usageCount, theme));
@@ -163,10 +179,17 @@ function renderEntity(entity, node, theme) {
     // Each entity is a single DOM group carrying its stable id and its innermost
     // package, so a browser host can bind hover/click handlers, cross-panel
     // linkage, and package-containment queries without geometric hit-testing.
+    // The data-* geometry lets a level-of-detail host map zoom to compartments
+    // from metadata instead of re-measuring the drawn rect/lines.
     const packageAttr = entity.packageId !== undefined
         ? ` data-package-id="${escapeXml(entity.packageId)}"`
         : '';
-    return (`<g data-entity-id="${escapeXml(entity.id)}"${packageAttr} class="uml-node${entity.external ? ' uml-external' : ''}">` +
+    return (`<g data-entity-id="${escapeXml(entity.id)}"${packageAttr}` +
+        ` data-x="${fmt(node.x)}" data-y="${fmt(node.y)}"` +
+        ` data-w="${fmt(node.width)}" data-h="${fmt(node.height)}"` +
+        ` data-title-h="${fmt(bands.title)}" data-attrs-h="${fmt(bands.attrs)}"` +
+        ` data-ops-h="${fmt(bands.ops)}"` +
+        ` class="uml-node${entity.external ? ' uml-external' : ''}">` +
         parts.join('') +
         `</g>`);
 }
@@ -193,11 +216,22 @@ function renderPackage(pkg, box, theme, tone) {
     parts.push(`<rect x="${fmt(box.x)}" y="${fmt(box.y)}" width="${fmt(box.width)}"` +
         ` height="${fmt(box.height)}" rx="${theme.shape.packageRadius}" ry="${theme.shape.packageRadius}"` +
         ` fill="${fill}" stroke="${color.packageStroke}" stroke-width="${theme.stroke.package}"/>`);
-    parts.push(`<line class="uml-package-tab" x1="${fmt(box.x)}" y1="${fmt(box.y + PACKAGE_LABEL.tabHeight)}"` +
-        ` x2="${fmt(box.x + tabWidth)}" y2="${fmt(box.y + PACKAGE_LABEL.tabHeight)}"` +
-        ` stroke="${color.packageStroke}" stroke-width="${theme.stroke.package}"/>`);
+    // Closed UML label tab: top edge → right vertical down → bottom edge → close
+    // back up the left side. The opaque fill hides the package frame underneath,
+    // so the tab reads as a solid tab with a sealed right side and bottom edge.
+    const tabHeight = PACKAGE_LABEL.tabHeight;
+    const tabRight = box.x + tabWidth;
+    const tabBottom = box.y + tabHeight;
+    parts.push(`<path class="uml-package-tab"` +
+        ` d="M ${fmt(box.x)},${fmt(box.y)} H ${fmt(tabRight)} V ${fmt(tabBottom)}` +
+        ` H ${fmt(box.x)} Z"` +
+        ` fill="${fill}" stroke="${color.packageStroke}" stroke-width="${theme.stroke.package}"` +
+        ` stroke-linejoin="round"/>`);
     parts.push(textEl(pkg.name, box.x + 8, box.y + PACKAGE_LABEL.tabHeight - 8, 'start', theme.font.size.packageLabel, theme.font.weight.packageLabel, color.textPackage, theme));
-    return (`<g data-package-id="${escapeXml(pkg.id)}" class="uml-package">` +
+    return (`<g data-package-id="${escapeXml(pkg.id)}" class="uml-package"` +
+        ` data-x="${fmt(box.x)}" data-y="${fmt(box.y)}"` +
+        ` data-w="${fmt(box.width)}" data-h="${fmt(box.height)}"` +
+        ` data-tab-w="${fmt(tabWidth)}" data-tab-h="${fmt(tabHeight)}">` +
         parts.join('') +
         `</g>`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yalehwang/plantuml-js",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Pure-TypeScript PlantUML class diagram renderer (MIT)",
   "type": "module",
   "license": "MIT",
@@ -39,6 +39,8 @@
     "typecheck": "tsc -p tsconfig.test.json",
     "test": "vitest run",
     "demo:build": "node scripts/build-demo.mjs",
+    "docs": "node scripts/render-docs.mjs",
+    "docs:check": "node scripts/render-docs.mjs --check",
     "release": "node scripts/release.mjs",
     "prepublishOnly": "npm run typecheck && npm run build && node scripts/check-dist-clean.mjs"
   },