@yalehwang/plantuml-js 0.4.1 → 0.5.1

package/README.md

@@ -72,7 +72,7 @@ console.log(svg);
 |---|---|
 | `createRenderer({ layout })` | Build a renderer. `layout` is `'elk'` (default), `'viz'` (experimental), or a custom `LayoutEngine`. |
 | `renderer.render(puml)` | Parse + layout + emit SVG. Returns `{ svg, diagramType, warnings }`. Throws `RenderError` on structurally invalid puml. |
-| `renderDetailed(pumlOrModel, options?)` | Run the same pipeline as `renderer.render` and return every intermediate: `{ model, layout, svg, layoutMs, hiddenTransitive }`. Accepts a puml string (throws `RenderError` on invalid input) or an already-parsed `PlantUmlModel`. `DetailedRender.layout` carries the **stable** node/package/edge rectangles — see [Stable layout geometry](#stable-layout-geometry-renderdetailed) — so tooling never has to re-read bounding boxes from the SVG. Exported from both `.` and `./elk`. |
+| `renderDetailed(pumlOrModel, options?)` | Run the same pipeline as `renderer.render` and return every intermediate: `{ model, sourceModel, layout, svg, layoutMs, hiddenTransitive }`. Accepts a puml string (throws `RenderError` on invalid input) or an already-parsed `PlantUmlModel`. `model` is the post-detail model that was drawn — **not suitable for export** (detail truncation may have replaced member rows); `sourceModel` is the complete pre-detail model, so export with `toPlantUml(sourceModel)`. `DetailedRender.layout` carries the **stable** node/package/edge rectangles — see [Stable layout geometry](#stable-layout-geometry-renderdetailed) — so tooling never has to re-read bounding boxes from the SVG. Exported from both `.` and `./elk`. |
 | `parsePlantUml(puml)` | Parse a puml string into a `PlantUmlModel`. |
 | `checkSyntax(puml)` | Validate without throwing. Returns `{ ok, errors, warnings }` of line-accurate `SyntaxDiagnostic`s. |
 | `explain(puml)` | Explain each line. Returns `LineExplanation[]` (line, kind, explanation). |
@@ -98,6 +98,28 @@ without re-routing. `model` is the diagram actually drawn (after view,
 transforms and detail), and `hiddenTransitive` counts the edges dropped by
 transitive reduction.
 
+`model` is a **drawing** model: `detail`/`memberMaxRows` may have replaced rows
+with a synthetic `… +N more (M members)` marker, so serializing it is lossy.
+For a lossless export (copy/download the current diagram as PlantUML), serialize
+`sourceModel` — the same model after view/transforms but before detail:
+
+```ts
+const { sourceModel } = await renderDetailed(puml, { detail: 'compact' });
+const text = toPlantUml(sourceModel); // every authored member, no marker rows
+```
+
+`toPlantUml` skips synthetic members, so `toPlantUml(model)` never emits a
+`+ … +N more` line either — it is simply only as complete as what was drawn.
+
+The canvas is fitted to **the routes and labels that are drawn**, not only to
+the boxes the layout engine measures: `layout.width`/`height` (and therefore
+the SVG `viewBox`) contain every edge route point and every edge label box, with
+a margin of at least **16px** on all four sides. An edge label beside an outer
+detour route is therefore never clipped at the SVG border, and a host can rely
+on `0 0 width height` containing the whole drawing. Engine geometry that
+already fits is left untouched, so the canvas never shrinks and unchanged
+diagrams render identically.
+
 ### Error semantics
 
 `createRenderer` fails closed on an unknown layout name (`'elk'`, `'viz'`, or a

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
@@ -67,8 +79,8 @@ export interface RenderResult {
 }
 /**
  * Everything {@link renderDetailed} computed for one diagram: the model that was
- * actually laid out and drawn, the geometry the renderer used, the SVG it
- * emitted, and the reduction bookkeeping.
+ * actually laid out and drawn, the pre-detail model to export from, the geometry
+ * the renderer used, the SVG it emitted, and the reduction bookkeeping.
  *
  * This is a **public, stable API** (available from both the `.` and `./elk`
  * entries). Consumers such as an architecture tab should read geometry from
@@ -89,8 +101,20 @@ export interface RenderResult {
  * they can be translated into a thumbnail directly.
  */
 export interface DetailedRender {
-    /** The model actually laid out and drawn (after view, transforms and detail). */
+    /**
+     * The model actually laid out and drawn (after view, transforms **and**
+     * detail). Detail truncation has already dropped members here — row caps
+     * replace them with a `synthetic` `… +N more` marker — so this model is for
+     * drawing/inspection, **not for export**. Export from {@link sourceModel}.
+     */
     model: PlantUmlModel;
+    /**
+     * The complete model after view/transforms but **before** detail truncation:
+     * every authored member, with `raw` intact. Serialize this to export what was
+     * parsed — `toPlantUml(renderDetailed(input).sourceModel)` — instead of
+     * `model`, whose rows detail may have capped.
+     */
+    sourceModel: PlantUmlModel;
     /** Geometry actually used by the renderer; its node/package/edge rectangles are a stable contract (see above). */
     layout: LayoutResult;
     svg: string;
@@ -126,6 +150,8 @@ export declare function createRenderer(options?: RendererOptions): Renderer;
  * Render one diagram through the exact pipeline `createRenderer` uses
  * (view/transforms → detail → layout → svg) and return every intermediate, so
  * tooling can read real geometry instead of reverse-engineering the SVG.
+ * `model` is the post-detail model that was drawn; `sourceModel` is the
+ * pre-detail model to serialize for a lossless export.
  *
  * Accepts either a puml string (the counterpart of
  * `createRenderer(options).render(puml)`, with the same fail-closed

package/dist/core.js

@@ -7,7 +7,8 @@
  * engine + `renderDot`.
  */
 import { parsePlantUml, parseWithDiagnostics, ENTITY_LINE, ENTITY_KEYWORD, extractDeclaredName, stripComment } from './parse/parser.js';
-import { applyDetail } from './foundation/layout.js';
+import { applyDetail, fitLayoutToContent } from './foundation/layout.js';
+import { placeEdgeLabels } from './foundation/labels.js';
 import { ElkLayoutEngine } from './layout/elk.js';
 import { renderSvg, SvgRenderer, } from './render/svg.js';
 import { applyView, transformModel, transformModelDetailed, shouldAutoReduce, INTER_PACKAGE_AGGREGATE_ENTITY_THRESHOLD } from './transform/transform.js';
@@ -67,13 +68,22 @@ 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: sourceModel, hiddenTransitive } = transformForRender(parsed, options);
+    const model = applyDetail(sourceModel, options.detail, {
+        memberMaxRows: options.memberMaxRows,
+        memberMaxChars: options.memberMaxChars,
+    });
     const started = performance.now();
-    const layout = await engine.layout(model);
+    const raw = await engine.layout(model);
     const layoutMs = Math.round((performance.now() - started) * 100) / 100;
+    // The engines size the canvas from boxes and routes; edge labels are placed
+    // by the renderer and can hang outside that box (a plain label beside an
+    // outer detour route lands at a negative x). Fit the canvas to the routes and
+    // labels, so the returned layout and the SVG viewBox both contain them with
+    // a margin.
+    const layout = fitLayoutToContent(raw, placeEdgeLabels(model, raw).map((label) => label.rect));
     const svg = renderEngine.render(model, layout, { hiddenTransitive });
-    return { model, layout, svg, layoutMs, hiddenTransitive };
+    return { sourceModel, model, layout, svg, layoutMs, hiddenTransitive };
 }
 export async function renderDetailed(input, options = {}) {
     const parsed = typeof input === 'string' ? parseForDetailed(input) : input;

package/dist/foundation/layout.d.ts

@@ -40,6 +40,28 @@ export interface LayoutResult {
 export interface LayoutEngine {
     layout(model: PlantUmlModel): Promise<LayoutResult>;
 }
+/** Empty border the canvas keeps around every drawn mark (px). */
+export declare const CANVAS_CONTENT_MARGIN = 16;
+/** Axis-aligned rectangle, structurally compatible with `labels`/`edge-router` rects. */
+export interface ContentRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Grow and translate a layout so every edge route point and the supplied extra
+ * rectangles (edge labels) stays at least `margin` from the canvas side. Routes
+ * and labels are drawn from the layout coordinates but are not part of
+ * `layout.width`/`height` as produced by the engines, so a label hung beside an
+ * outer detour route can sit at a negative x and be clipped by a `0 0 w h`
+ * viewBox.
+ *
+ * Boxes are left alone — the engines already place them inside their own
+ * margin — so this never moves a diagram whose routes and labels already fit:
+ * the input is returned untouched and the canvas never shrinks.
+ */
+export declare function fitLayoutToContent(layout: LayoutResult, extraRects?: readonly ContentRect[], margin?: number): 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
@@ -105,11 +127,34 @@ 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.
+ *
+ * Row caps replace dropped members with one `… +N more (M members)` row marked
+ * `synthetic: true`: it is drawing scaffolding, not authored content, so the
+ * serializer skips it and a lossless export reads the pre-detail model
+ * (`renderDetailed().sourceModel`). Re-applying `applyDetail` to an already
+ * detailed model counts only the real members, so markers never stack.
  */
-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

@@ -5,6 +5,64 @@
  * engines (ELK, Graphviz, a custom tuner) is an injection, not a rewrite.
  */
 import { measureTextWidth, MONOSPACE_FONT_SIZE } from './text-measure.js';
+/** Empty border the canvas keeps around every drawn mark (px). */
+export const CANVAS_CONTENT_MARGIN = 16;
+/**
+ * Grow and translate a layout so every edge route point and the supplied extra
+ * rectangles (edge labels) stays at least `margin` from the canvas side. Routes
+ * and labels are drawn from the layout coordinates but are not part of
+ * `layout.width`/`height` as produced by the engines, so a label hung beside an
+ * outer detour route can sit at a negative x and be clipped by a `0 0 w h`
+ * viewBox.
+ *
+ * Boxes are left alone — the engines already place them inside their own
+ * margin — so this never moves a diagram whose routes and labels already fit:
+ * the input is returned untouched and the canvas never shrinks.
+ */
+export function fitLayoutToContent(layout, extraRects = [], margin = CANVAS_CONTENT_MARGIN) {
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    const take = (x, y) => {
+        if (x < minX)
+            minX = x;
+        if (x > maxX)
+            maxX = x;
+        if (y < minY)
+            minY = y;
+        if (y > maxY)
+            maxY = y;
+    };
+    for (const edge of layout.edges ?? []) {
+        for (const point of edge.points)
+            take(point.x, point.y);
+    }
+    for (const rect of extraRects) {
+        take(rect.x, rect.y);
+        take(rect.x + rect.width, rect.y + rect.height);
+    }
+    if (minX === Infinity)
+        return layout;
+    const dx = Math.max(0, margin - minX);
+    const dy = Math.max(0, margin - minY);
+    const width = Math.max(layout.width + dx, maxX + dx + margin);
+    const height = Math.max(layout.height + dy, maxY + dy + margin);
+    if (dx === 0 && dy === 0 && width === layout.width && height === layout.height) {
+        return layout;
+    }
+    return {
+        ...layout,
+        nodes: layout.nodes.map((n) => ({ ...n, x: n.x + dx, y: n.y + dy })),
+        edges: layout.edges.map((e) => ({
+            ...e,
+            points: e.points.map((p) => ({ x: p.x + dx, y: p.y + dy })),
+        })),
+        packages: layout.packages?.map((p) => ({ ...p, x: p.x + dx, y: p.y + dy })),
+        width,
+        height,
+    };
+}
 /**
  * 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
@@ -74,7 +132,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 +156,58 @@ 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.
+ *
+ * Row caps replace dropped members with one `… +N more (M members)` row marked
+ * `synthetic: true`: it is drawing scaffolding, not authored content, so the
+ * serializer skips it and a lossless export reads the pre-detail model
+ * (`renderDetailed().sourceModel`). Re-applying `applyDetail` to an already
+ * detailed model counts only the real members, so markers never stack.
  */
-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;
+            const authored = entity.members.filter((member) => member.synthetic !== true);
+            const total = authored.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);
+                return entity.members.length === 0 ? entity : { ...entity, members: [] };
+            const rowCap = memberMaxRows !== undefined
+                ? memberMaxRows
+                : level === 'compact'
+                    ? COMPACT_MEMBER_ROWS
+                    : total;
+            if (total <= rowCap) {
+                if (!hasLimits && authored.length === entity.members.length)
+                    return entity;
+                return { ...entity, members: authored.map(limitMember) };
+            }
+            const kept = authored.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)`,
+                synthetic: true,
             };
             return { ...entity, members: [...kept, more] };
         }),

package/dist/foundation/model.d.ts

@@ -20,6 +20,21 @@ 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;
+    /**
+     * True when the member never existed in the source: it is a drawn-only
+     * stand-in synthesized by `applyDetail` (the `… +N more (M members)` count
+     * row) to stand for the rows the detail level dropped. It is not part of the
+     * parsed model, so it must never be exported: [[toPlantUml]] skips it, and
+     * the lossless export path serializes `renderDetailed().sourceModel` instead.
+     */
+    synthetic?: true;
 }
 export interface PlantUmlEntity {
     /** Stable node identity inside the diagram (the alias when `as` is used). */

package/dist/parse/serialize.d.ts

@@ -1,13 +1,19 @@
 /**
  * PlantUmlModel → PlantUML class-diagram text.
  *
- * The inverse of [[parsePlantUml]]: `toPlantUml(renderDetailed(...).model)`
- * reproduces the diagram that was actually drawn (after view/transform/detail)
- * as source a user can copy and paste. Pure and synchronous — the model is the
- * only input, so the caller composes the scope by picking the model
+ * The inverse of [[parsePlantUml]]. The model is the only input, so the caller
+ * composes the scope by picking the model
  * (`toPlantUml(applyView(model, {kind: 'neighborhood', entity, hops}))`); this
  * function never chooses a range on its own.
  *
+ * For a **lossless export** of what `renderDetailed` parsed, pass its
+ * `sourceModel` (the post-view/transform, pre-detail model):
+ * `toPlantUml(renderDetailed(input).sourceModel)`. Passing `model` instead
+ * serializes the model that was drawn — detail truncation has already dropped
+ * rows there, so the text is only as complete as the drawing. Members marked
+ * `synthetic` (the `… +N more (M members)` count row `applyDetail` adds) are
+ * drawing scaffolding, not authored content, and are always skipped.
+ *
  * Shapes that only exist after parsing (stub/external/usageCount, aggregated
  * edge weights, cycle markers) are rendering semantics with no PlantUML
  * spelling; they serialize as their plain-text equivalent (stub → class,

package/dist/parse/serialize.js

@@ -1,13 +1,19 @@
 /**
  * PlantUmlModel → PlantUML class-diagram text.
  *
- * The inverse of [[parsePlantUml]]: `toPlantUml(renderDetailed(...).model)`
- * reproduces the diagram that was actually drawn (after view/transform/detail)
- * as source a user can copy and paste. Pure and synchronous — the model is the
- * only input, so the caller composes the scope by picking the model
+ * The inverse of [[parsePlantUml]]. The model is the only input, so the caller
+ * composes the scope by picking the model
  * (`toPlantUml(applyView(model, {kind: 'neighborhood', entity, hops}))`); this
  * function never chooses a range on its own.
  *
+ * For a **lossless export** of what `renderDetailed` parsed, pass its
+ * `sourceModel` (the post-view/transform, pre-detail model):
+ * `toPlantUml(renderDetailed(input).sourceModel)`. Passing `model` instead
+ * serializes the model that was drawn — detail truncation has already dropped
+ * rows there, so the text is only as complete as the drawing. Members marked
+ * `synthetic` (the `… +N more (M members)` count row `applyDetail` adds) are
+ * drawing scaffolding, not authored content, and are always skipped.
+ *
  * Shapes that only exist after parsing (stub/external/usageCount, aggregated
  * edge weights, cycle markers) are rendering semantics with no PlantUML
  * spelling; they serialize as their plain-text equivalent (stub → class,
@@ -131,10 +137,13 @@ function entityLines(entity, depth, aliases) {
     const indent = INDENT.repeat(depth);
     const alias = aliases.alias(entity.id, entity.name);
     const head = `${entityKeyword(entity)} ${quoteName(entity.name)}${genericSuffix(entity)} as ${alias}`;
-    if (entity.members.length === 0)
+    // Synthetic rows (applyDetail's `… +N more` marker) stand in for members the
+    // drawing dropped; they are not authored content, so they never serialize.
+    const members = entity.members.filter((member) => member.synthetic !== true);
+    if (members.length === 0)
         return [`${indent}${head}`];
     const lines = [`${indent}${head} {`];
-    for (const member of entity.members) {
+    for (const member of members) {
         lines.push(`${indent}${INDENT}${memberLine(member)}`);
     }
     lines.push(`${indent}}`);
@@ -146,10 +155,9 @@ function genericSuffix(entity) {
 }
 /**
  * One member row. The authored `raw` text is authoritative (it carries the
- * visibility symbol and the exact signature), except for synthesized rows —
- * the detail pipeline's `… +N more (M members)` truncation marker has no
- * visibility symbol, so it gets one prefixed to stay parseable as a member
- * row while keeping the marker text verbatim.
+ * visibility symbol and the exact signature); a declaration without a leading
+ * visibility symbol gets one prefixed so the row stays parseable. Synthetic
+ * detail markers never reach this function (see [[entityLines]]).
  */
 function memberLine(member) {
     const raw = (member.raw ?? '').trim();

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.1",
+  "version": "0.5.1",
   "description": "Pure-TypeScript PlantUML class diagram renderer (MIT)",
   "type": "module",
   "license": "MIT",