@yalehwang/plantuml-js 0.4.0 → 0.5.0

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/core.d.ts

@@ -46,6 +46,18 @@ export interface RendererOptions {
      * Default: chosen by entity count (≤40 full, ≤150 compact, else names).
      */
     detail?: DetailLevel;
+    /**
+     * Maximum member rows drawn per entity; surplus members collapse into the
+     * existing `… +N more (M members)` row. Applied before layout, so the box is
+     * sized for what is drawn. Default: unlimited for `full`, 4 for `compact`.
+     */
+    memberMaxRows?: number;
+    /**
+     * Cut each drawn member line to this many characters (ending with `…`).
+     * Only the drawn text changes: `PlantUmlMember.raw` keeps the full
+     * declaration. Default: unlimited.
+     */
+    memberMaxChars?: number;
     /**
      * `'aggregate'` folds the relations between two packages into one weighted
      * box-to-box corridor edge (originals kept in its `<title>`); `'raw'` draws

package/dist/core.js

@@ -68,7 +68,10 @@ export function createRenderer(options = {}) {
 }
 async function renderParsed(parsed, options, engine, renderEngine) {
     const { model: transformed, hiddenTransitive } = transformForRender(parsed, options);
-    const model = applyDetail(transformed, options.detail);
+    const model = applyDetail(transformed, options.detail, {
+        memberMaxRows: options.memberMaxRows,
+        memberMaxChars: options.memberMaxChars,
+    });
     const started = performance.now();
     const layout = await engine.layout(model);
     const layoutMs = Math.round((performance.now() - started) * 100) / 100;

package/dist/foundation/layout.d.ts

@@ -105,11 +105,28 @@ 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;
+/**
+ * Optional caps on the member text a diagram draws. Both are applied by
+ * [[applyDetail]] before layout, so an entity is sized for exactly what the
+ * renderer emits; neither mutates `PlantUmlMember.raw`.
+ */
+export interface MemberDisplayLimits {
+    /** Maximum member rows drawn per entity; the rest collapse into the count row. */
+    memberMaxRows?: number;
+    /** Cut each drawn member line to this many characters, ending with `…`. */
+    memberMaxChars?: number;
+}
 /**
  * Reduce member rows to the requested detail level *before* layout, so boxes
  * are sized for what is actually drawn. `undefined` picks by entity count.
+ *
+ * `limits` caps the drawn rows per entity (`memberMaxRows`, replacing
+ * [[COMPACT_MEMBER_ROWS]] for `compact` and also capping `full`) and the width
+ * of each drawn line (`memberMaxChars`). Truncation only sets
+ * `PlantUmlMember.display`; `raw` keeps the full declaration. Without limits
+ * the result is byte-for-byte what it always was.
  */
-export declare function applyDetail(model: PlantUmlModel, detail?: DetailLevel): PlantUmlModel;
+export declare function applyDetail(model: PlantUmlModel, detail?: DetailLevel, limits?: MemberDisplayLimits): 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

package/dist/foundation/layout.js

@@ -74,7 +74,7 @@ export function compartmentHeights(entity) {
 export function estimateEntitySize(entity) {
     const lines = [
         displayName(entity),
-        ...entity.members.map((m) => m.raw),
+        ...entity.members.map((m) => m.display ?? m.raw),
     ];
     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));
@@ -98,26 +98,48 @@ export function autoDetail(entityCount) {
 /**
  * Reduce member rows to the requested detail level *before* layout, so boxes
  * are sized for what is actually drawn. `undefined` picks by entity count.
+ *
+ * `limits` caps the drawn rows per entity (`memberMaxRows`, replacing
+ * [[COMPACT_MEMBER_ROWS]] for `compact` and also capping `full`) and the width
+ * of each drawn line (`memberMaxChars`). Truncation only sets
+ * `PlantUmlMember.display`; `raw` keeps the full declaration. Without limits
+ * the result is byte-for-byte what it always was.
  */
-export function applyDetail(model, detail) {
+export function applyDetail(model, detail, limits = {}) {
     const level = detail ?? autoDetail(model.entities.length);
-    if (level === 'full')
+    const { memberMaxRows, memberMaxChars } = limits;
+    const hasLimits = memberMaxRows !== undefined || memberMaxChars !== undefined;
+    if (level === 'full' && !hasLimits)
         return model;
+    const limitMember = (member) => {
+        if (memberMaxChars === undefined || member.raw.length <= memberMaxChars)
+            return member;
+        return {
+            ...member,
+            display: `${member.raw.slice(0, Math.max(0, memberMaxChars - 1))}…`,
+        };
+    };
     return {
         ...model,
         entities: model.entities.map((entity) => {
             const total = entity.members.length;
             if (level === 'names')
                 return total === 0 ? entity : { ...entity, members: [] };
-            if (total <= COMPACT_MEMBER_ROWS)
-                return entity;
-            const kept = entity.members.slice(0, COMPACT_MEMBER_ROWS);
+            const rowCap = memberMaxRows !== undefined
+                ? memberMaxRows
+                : level === 'compact'
+                    ? COMPACT_MEMBER_ROWS
+                    : total;
+            if (total <= rowCap) {
+                return hasLimits ? { ...entity, members: entity.members.map(limitMember) } : entity;
+            }
+            const kept = entity.members.slice(0, rowCap).map(limitMember);
             const more = {
                 visibility: 'public',
                 name: '…',
                 kind: 'field',
                 modifiers: [],
-                raw: `… +${total - COMPACT_MEMBER_ROWS} more (${total} members)`,
+                raw: `… +${total - rowCap} more (${total} members)`,
             };
             return { ...entity, members: [...kept, more] };
         }),

package/dist/foundation/model.d.ts

@@ -20,6 +20,13 @@ export interface PlantUmlMember {
     optional?: boolean;
     /** Full authored declaration incl. visibility symbol, for faithful display. */
     raw: string;
+    /**
+     * Text actually drawn for this member, when it differs from `raw` (e.g. cut
+     * to a display width by `applyDetail`). Layout and rendering read
+     * `display ?? raw`; `raw` itself is never modified, so serialization and
+     * inspector views keep the full declaration.
+     */
+    display?: string;
 }
 export interface PlantUmlEntity {
     /** Stable node identity inside the diagram (the alias when `as` is used). */

package/dist/render/svg.js

@@ -166,7 +166,7 @@ function renderEntity(entity, node, theme) {
         parts.push(rule(opsTop, 'ops'));
     const titleBaseline = node.y + METRICS.paddingY + METRICS.fontSize + 1;
     parts.push(textEl(displayName(entity), node.x + node.width / 2, titleBaseline, 'middle', font.size.title, font.weight.title, color.textTitle, theme, fontStyle));
-    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}"`);
+    const memberText = (member, idx, top, cls) => textEl(member.display ?? 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'));
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yalehwang/plantuml-js",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "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"
   },