@grethel-labs/excaliplant 0.5.2 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -24,6 +24,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
24
24
  - Edge-label chips now carry `customData.role` markers
25
25
  (`edgeLabelChip` / `edgeLabelText`) so renderers, tests, and
26
26
  third-party tools can identify them reliably.
27
+ - Class-diagram styling can now colour UML class-like boxes by type
28
+ with `classDiagram.colorByType` and `classDiagram.typeColors`
29
+ (`class`, `abstract`, `interface`, `enum`).
30
+ - Sequence diagrams now parse, lay out, and render combined fragments
31
+ for `opt`, `loop`, `alt` / `else`, `par`, `break`, `critical`, and
32
+ `group` blocks. Fragment frames are included in Excalidraw JSON,
33
+ SVG, and PNG output.
34
+ - Sequence diagrams now support PlantUML lifecycle and timeline
35
+ constructs: `autonumber`, `create`, `activate`, `deactivate`,
36
+ `destroy`, inline message suffixes (`++`, `--`, `**`, `!!`),
37
+ participant `box ... end box` groups, `ref over` references,
38
+ dividers, delays, spacers, `par` / `and`, and `critical` / `group`
39
+ `option` operands, plus block and compact sequence colour skinparams
40
+ for arrows, participants, and lifelines.
27
41
  - Auto-generated single-page API reference at
28
42
  [`docs/API.md`](docs/API.md). It replaces the previous TypeDoc HTML
29
43
  site under `docs/api/` and is rendered from JSDoc by
@@ -39,6 +53,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
39
53
  `edgeLabel.textColor`, `edgeLabel.maxWidth`, …). The chip itself is
40
54
  emitted with `roughness: 0` and no rounded corners so it reads as a
41
55
  clean badge sitting on the line; default font size dropped to 10 px.
56
+ - UML class boxes now draw a thin compartment separator between
57
+ attribute-like members and operation/function members when both are
58
+ present.
59
+ - Sequence-diagram rendering now gives combined fragments typed
60
+ background/stroke colours with solid header labels, reserves vertical
61
+ margins around fragment frames, expands nested parent fragments
62
+ recursively, prevents adjacent fragment overlap, and colours
63
+ participant heads with deterministic hash-based pastel fills.
64
+ - Sequence-diagram message labels now wrap to their available arrow
65
+ length and reserve enough vertical space so long labels do not
66
+ overlap neighbouring timeline entries.
42
67
  - The `svg.mjs` renderer now honours the per-element `roughness`
43
68
  field, so connection arrows / lines and edge-label chips appear
44
69
  perfectly straight in the exported SVG / PNG (matching the existing
@@ -48,6 +73,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
48
73
  …) keep working; calls to `setStyle()` / `loadStyleFromFile()`
49
74
  immediately propagate to sizing and rendering.
50
75
 
76
+ ### Fixed
77
+
78
+ - Connection arrows now always inherit the **outline colour of their
79
+ source box** (not the owning plane's colour), and arrowheads
80
+ (`arrow`, `triangle`, `triangle_outline`, `diamond`,
81
+ `diamond_outline`) are rendered in the matching colour in both the
82
+ Excalidraw JSON output and the SVG / PNG export. The SVG renderer
83
+ emits one `<marker>` definition per (arrowhead-type, colour)
84
+ combination actually in use and references it via a
85
+ colour-suffixed marker id, so renderers without
86
+ `context-stroke` support (resvg-js, some Markdown sanitisers) still
87
+ produce coloured arrowheads. Box-stroke resolution is shared with
88
+ the box renderer through the new `boxStrokeColor()` helper, so
89
+ arrows always agree with the box outline including the
90
+ per-id colours used for `__floating__`-plane children.
91
+ - Class-diagram visual regressions on large tplant-style sources:
92
+ - Composition (`*--`) and aggregation (`o--`) arrows now keep
93
+ their intentional `endArrowhead: null`. The renderer used to
94
+ coerce `null` to `"arrow"`, which produced a spurious target
95
+ arrow alongside the source diamond.
96
+ - The synthetic `__floating__` collector plane (used for
97
+ declarations that live outside any explicit
98
+ `package` / `namespace`) is no longer drawn as a visible
99
+ bounding rectangle or labelled tab. Its child boxes each
100
+ receive their own deterministic per-id colour
101
+ (`planeColor(box.id)`) so individual top-level types stay
102
+ visually distinguishable, and outgoing arrows pick up the
103
+ matching source-box stroke colour rather than the (invisible)
104
+ floating-plane colour.
105
+ - Long class / interface / enum member signatures now wrap at
106
+ semantically meaningful break points (after `,` `(` `:`,
107
+ before `|` `&` `)`) via the new `wrapMemberSignature` helper
108
+ in `src/style/text.mjs`, with continuation indent. Sizing
109
+ grows the box height accordingly so members no longer bleed
110
+ past the right edge.
111
+
51
112
  ## [0.3.7] - 2026-05-04
52
113
 
53
114
  ### Added
package/README.md CHANGED
@@ -7,7 +7,7 @@
7
7
  [![node](https://img.shields.io/node/v/@grethel-labs/excaliplant.svg)](https://nodejs.org)
8
8
  [![license](https://img.shields.io/npm/l/@grethel-labs/excaliplant.svg)](./LICENSE)
9
9
 
10
- > PlantUML → ELK layout → Excalidraw renderer with a plugin-based parser. &nbsp;·&nbsp; **v0.5.2** &nbsp;·&nbsp; 116 tests &nbsp;·&nbsp; MIT
10
+ > PlantUML → ELK layout → Excalidraw renderer with a plugin-based parser. &nbsp;·&nbsp; **v0.6.0** &nbsp;·&nbsp; 136 tests &nbsp;·&nbsp; MIT
11
11
 
12
12
  `@grethel-labs/excaliplant` takes PlantUML source, runs it through a plugin-based
13
13
  parser, lays it out with [ELK](https://github.com/kieler/elkjs), and
@@ -107,13 +107,29 @@ The complete list of exported symbols, with parameter tables and
107
107
  return types, lives in [`docs/API.md`](./docs/API.md). It is
108
108
  regenerated from JSDoc on every `npm run build:docs` run.
109
109
 
110
+ ### Sequence diagram coverage
111
+
112
+ Sequence diagrams support participants (`participant`, `actor`,
113
+ `boundary`, `control`, `entity`, `database`, `collections`, `queue`),
114
+ message arrows including async/reply/reverse/bidirectional variants,
115
+ notes, participant `box ... end box` groups, `ref over` references,
116
+ dividers (`== label ==`), delays (`... label ...`), spacers (`|||` /
117
+ `||45||`), `autonumber`, lifecycle controls (`create`, `activate`,
118
+ `deactivate`, `destroy`) and inline message lifecycle suffixes
119
+ (`++`, `--`, `**`, `!!`). Combined fragments render for `opt`,
120
+ `loop`, `alt`/`else`, `par`/`and`, `break`, `critical`/`option`, and
121
+ `group`/`option` blocks. A small sequence `skinparam` subset maps
122
+ directly to output colours in block or compact form: `ArrowColor`,
123
+ `ParticipantBackgroundColor`, `ParticipantBorderColor`, and
124
+ `LifeLineBorderColor`.
125
+
110
126
  ### Run the tests
111
127
 
112
128
  ```sh
113
129
  npm test
114
130
  ```
115
131
 
116
- Ships with **116 tests** across functional, edge-case,
132
+ Ships with **136 tests** across functional, edge-case,
117
133
  security (XSS / ReDoS / prototype-pollution), and self-introspection
118
134
  suites.
119
135
 
@@ -215,6 +231,7 @@ excaliplant
215
231
  ├── scripts
216
232
  │ ├── auto-patch-deps.mjs
217
233
  │ ├── bump-release-version.mjs
234
+ │ ├── clean-test-output.mjs
218
235
  │ ├── merge-driver-prefer-higher-version.mjs
219
236
  │ ├── prepublish-guard.mjs
220
237
  │ ├── setup-merge-drivers.mjs
@@ -249,6 +266,8 @@ excaliplant
249
266
  │ ├── style.mjs
250
267
  │ └── text.mjs
251
268
  ├── tests
269
+ │ ├── helpers
270
+ │ │ └── output.mjs
252
271
  │ ├── edge_cases.test.mjs
253
272
  │ ├── functional_more.test.mjs
254
273
  │ ├── merge_driver.test.mjs
package/index.mjs CHANGED
@@ -84,7 +84,12 @@ export {
84
84
  Participant,
85
85
  Message,
86
86
  SequenceDiagram,
87
+ SequenceActivation,
88
+ SequenceFragment,
89
+ SequenceMarker,
87
90
  SequenceNote,
91
+ SequenceParticipantGroup,
92
+ SequenceReference,
88
93
  SHAPES,
89
94
  } from "./src/model/diagram.mjs";
90
95
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@grethel-labs/excaliplant",
3
- "version": "0.5.2",
3
+ "version": "0.6.0",
4
4
  "description": "PlantUML → ELK layout → Excalidraw renderer with a plugin-based parser.",
5
5
  "type": "module",
6
6
  "main": "index.mjs",
@@ -34,6 +34,7 @@
34
34
  "./style": "./src/style/style.mjs"
35
35
  },
36
36
  "scripts": {
37
+ "pretest": "node scripts/clean-test-output.mjs",
37
38
  "test": "node --test tests/edge_cases.test.mjs tests/functional_more.test.mjs tests/merge_driver.test.mjs tests/plantuml.test.mjs tests/security.test.mjs tests/self_introspection.test.mjs tests/style.test.mjs",
38
39
  "typecheck": "tsc -p tsconfig.json",
39
40
  "build:docs": "node docs/scripts/build-docs.mjs",
@@ -62,6 +63,8 @@
62
63
  "svg",
63
64
  "png",
64
65
  "uml",
66
+ "javascript",
67
+ "js",
65
68
  "sequence-diagram"
66
69
  ],
67
70
  "publishConfig": {
@@ -45,6 +45,36 @@ import { layoutSequenceDiagram } from "./sequence_layout.mjs";
45
45
 
46
46
  const elk = new ELK();
47
47
 
48
+ // ELK distributes ports evenly along each side using the formula
49
+ // port_y = (side_height / (n + 1)) * i
50
+ // so the per-port gap equals `side_height / (n + 1)`. To guarantee a
51
+ // minimum visual gap between the arrowheads of parallel edges, we
52
+ // enforce a minimum box height of `(max_edges_per_side + 1) * MIN_PORT_GAP`
53
+ // before handing the graph to ELK.
54
+ //
55
+ // Corridor spacing options must be applied to the parent that owns the
56
+ // edges. Since most edges live inside Plane/Subplane compound nodes,
57
+ // root-only layoutOptions do not reach them. We pass corridor spacing
58
+ // through elk.layout(..., { layoutOptions }) so every hierarchical node
59
+ // receives the same values unless it explicitly overrides them.
60
+ const MIN_PORT_GAP = 26;
61
+
62
+ // A single-line edge-label chip is roughly 17 px tall. 26 px centreline
63
+ // spacing leaves several pixels between two labels on adjacent parallel
64
+ // edges without making corridors feel oversized.
65
+ const EDGE_CORRIDOR_GAP = 26;
66
+ // ELK measures edge-node spacing from a node border to the edge centreline.
67
+ // Keep this comfortably larger than corridor spacing so routed edge bundles
68
+ // read as separate corridors instead of hugging class boxes.
69
+ const EDGE_NODE_GAP = 96;
70
+
71
+ const GLOBAL_LAYOUT_OPTIONS = {
72
+ "elk.spacing.edgeEdge": `${EDGE_CORRIDOR_GAP}`,
73
+ "elk.layered.spacing.edgeEdgeBetweenLayers": `${EDGE_CORRIDOR_GAP}`,
74
+ "elk.spacing.edgeNode": `${EDGE_NODE_GAP}`,
75
+ "elk.layered.spacing.edgeNodeBetweenLayers": `${EDGE_NODE_GAP}`,
76
+ };
77
+
48
78
  // ELK layout options. These are tuned for many-node, many-edge,
49
79
  // hierarchical compound layouts with orthogonal edge routing — i.e.
50
80
  // what we have. See https://eclipse.dev/elk/reference/options.html
@@ -57,29 +87,25 @@ const ROOT_OPTIONS = {
57
87
  "elk.layered.crossingMinimization.semiInteractive": "true",
58
88
  "elk.layered.nodePlacement.strategy": "NETWORK_SIMPLEX",
59
89
  "elk.layered.nodePlacement.bk.fixedAlignment": "BALANCED",
60
- "elk.layered.spacing.nodeNodeBetweenLayers": "60",
61
- "elk.spacing.nodeNode": "30",
62
- "elk.spacing.edgeNode": "20",
63
- "elk.spacing.edgeEdge": "12",
64
- "elk.spacing.edgeNodeBetweenLayers": "20",
65
- "elk.spacing.edgeEdgeBetweenLayers": "12",
66
- "elk.padding": "[top=24,left=24,bottom=24,right=24]",
90
+ "elk.layered.spacing.nodeNodeBetweenLayers": "90",
91
+ "elk.spacing.nodeNode": "45",
92
+ "elk.padding": "[top=36,left=36,bottom=36,right=36]",
67
93
  };
68
94
 
69
95
  const PLANE_OPTIONS = {
70
96
  "elk.algorithm": "layered",
71
97
  "elk.direction": "RIGHT",
72
98
  "elk.padding": `[top=${SIZING.planeTitleHeight + SIZING.planePaddingY},left=${SIZING.planePaddingX},bottom=${SIZING.planePaddingY},right=${SIZING.planePaddingX}]`,
73
- "elk.layered.spacing.nodeNodeBetweenLayers": "50",
74
- "elk.spacing.nodeNode": "24",
99
+ "elk.layered.spacing.nodeNodeBetweenLayers": "75",
100
+ "elk.spacing.nodeNode": "36",
75
101
  };
76
102
 
77
103
  const SUBPLANE_OPTIONS = {
78
104
  "elk.algorithm": "layered",
79
105
  "elk.direction": "RIGHT",
80
106
  "elk.padding": `[top=${SIZING.subplaneTitleHeight + SIZING.subplanePaddingY},left=${SIZING.subplanePaddingX},bottom=${SIZING.subplanePaddingY},right=${SIZING.subplanePaddingX}]`,
81
- "elk.layered.spacing.nodeNodeBetweenLayers": "40",
82
- "elk.spacing.nodeNode": "16",
107
+ "elk.layered.spacing.nodeNodeBetweenLayers": "60",
108
+ "elk.spacing.nodeNode": "24",
83
109
  };
84
110
 
85
111
  /**
@@ -105,11 +131,15 @@ export async function layoutDiagram(diagram) {
105
131
  // Step 1: text-based box sizing.
106
132
  sizeDiagram(diagram);
107
133
 
134
+ // Step 1b: widen boxes that receive or emit many parallel edges so
135
+ // ELK's DISTRIBUTED port alignment keeps arrowheads apart.
136
+ ensureBoxHeightForEdges(diagram);
137
+
108
138
  // Step 2: build the ELK graph.
109
139
  const graph = buildElkGraph(diagram);
110
140
 
111
141
  // Step 3: run ELK.
112
- const result = await elk.layout(graph);
142
+ const result = await elk.layout(graph, { layoutOptions: GLOBAL_LAYOUT_OPTIONS });
113
143
 
114
144
  // Step 4: write geometry back.
115
145
  applyElkResult(diagram, result);
@@ -204,6 +234,46 @@ function buildElkGraph(diagram) {
204
234
  return root;
205
235
  }
206
236
 
237
+ /**
238
+ * Expand box heights so ELK's distributed port allocation places
239
+ * arrowheads at least MIN_PORT_GAP px apart.
240
+ *
241
+ * ELK uses `height / (n + 1)` for the gap between n ports on one
242
+ * side. Required height = `(n + 1) * MIN_PORT_GAP`. We only ever
243
+ * increase heights (never shrink), so box labels and members still
244
+ * fit.
245
+ *
246
+ * @param {import("../model/diagram.mjs").Diagram} diagram
247
+ * @returns {void}
248
+ */
249
+ function ensureBoxHeightForEdges(diagram) {
250
+ // Count incoming and outgoing connections per box.
251
+ /** @type {Map<string, {in: number, out: number}>} */
252
+ const counts = new Map();
253
+ const get = (/** @type {string} */ id) => {
254
+ if (!counts.has(id)) counts.set(id, { in: 0, out: 0 });
255
+ return /** @type {{in:number,out:number}} */ (counts.get(id));
256
+ };
257
+ for (const conn of diagram.connections) {
258
+ get(conn.from.id).out += 1;
259
+ get(conn.to.id).in += 1;
260
+ }
261
+ // Raise each box's height if needed.
262
+ for (const plane of diagram.planes) {
263
+ for (const child of plane.children) {
264
+ const boxes = child instanceof Subplane ? child.boxes : [child];
265
+ for (const box of boxes) {
266
+ if (!(box instanceof Box)) continue;
267
+ const c = counts.get(box.id);
268
+ if (!c) continue;
269
+ const maxEdgesPerSide = Math.max(c.in, c.out);
270
+ const minH = (maxEdgesPerSide + 1) * MIN_PORT_GAP;
271
+ if (box.height < minH) box.height = minH;
272
+ }
273
+ }
274
+ }
275
+ }
276
+
207
277
  /**
208
278
  * Convert a {@link Box} to its ELK node representation.
209
279
  * @param {import("../model/diagram.mjs").Box} box The model box (must already have width/height).