@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 +61 -0
- package/README.md +21 -2
- package/index.mjs +5 -0
- package/package.json +4 -1
- package/src/layout/elk_layout.mjs +82 -12
- package/src/layout/sequence_layout.mjs +430 -8
- package/src/layout/sizing.mjs +62 -3
- package/src/model/diagram.mjs +237 -3
- package/src/parser/plantuml.mjs +27 -4
- package/src/parser/plugins/component/preamble.mjs +21 -0
- package/src/parser/plugins/sequence/advanced.mjs +143 -0
- package/src/parser/plugins/sequence/fragments.mjs +40 -0
- package/src/parser/plugins/sequence/messages.mjs +18 -4
- package/src/parser/plugins/sequence/participants.mjs +3 -3
- package/src/parser/plugins/sequence/preamble.mjs +47 -0
- package/src/parser/sequence_context.mjs +248 -5
- package/src/parser/utils.mjs +1 -12
- package/src/render/excalidraw.mjs +214 -45
- package/src/render/sequence_render.mjs +542 -79
- package/src/render/svg.mjs +168 -21
- package/src/style/style.mjs +10 -0
- package/src/style/text.mjs +92 -0
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
|
[](https://nodejs.org)
|
|
8
8
|
[](./LICENSE)
|
|
9
9
|
|
|
10
|
-
> PlantUML → ELK layout → Excalidraw renderer with a plugin-based parser. · **v0.
|
|
10
|
+
> PlantUML → ELK layout → Excalidraw renderer with a plugin-based parser. · **v0.6.0** · 136 tests · 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 **
|
|
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
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@grethel-labs/excaliplant",
|
|
3
|
-
"version": "0.
|
|
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": "
|
|
61
|
-
"elk.spacing.nodeNode": "
|
|
62
|
-
"elk.
|
|
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": "
|
|
74
|
-
"elk.spacing.nodeNode": "
|
|
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": "
|
|
82
|
-
"elk.spacing.nodeNode": "
|
|
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).
|