@grethel-labs/excaliplant 0.5.3 → 0.7.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 +85 -0
- package/README.md +59 -4
- package/assets/arrowheads/arrowheads.svg +46 -0
- package/assets/arrowheads/manifest.json +17 -0
- package/index.mjs +31 -0
- package/package.json +7 -3
- package/src/layout/elk_layout.mjs +82 -12
- package/src/layout/sequence_layout.mjs +925 -21
- package/src/layout/sequence_spacing.mjs +106 -0
- package/src/layout/sizing.mjs +62 -3
- package/src/model/diagram.mjs +621 -10
- package/src/parser/plantuml.mjs +33 -4
- package/src/parser/plugins/component/preamble.mjs +21 -0
- package/src/parser/plugins/sequence/advanced.mjs +241 -0
- package/src/parser/plugins/sequence/fragments.mjs +67 -0
- package/src/parser/plugins/sequence/messages.mjs +407 -24
- package/src/parser/plugins/sequence/notes.mjs +127 -20
- package/src/parser/plugins/sequence/participants.mjs +52 -5
- package/src/parser/plugins/sequence/preamble.mjs +104 -0
- package/src/parser/sequence_context.mjs +424 -6
- package/src/parser/utils.mjs +1 -5
- package/src/render/excalidraw.mjs +254 -45
- package/src/render/sequence_render.mjs +1198 -148
- package/src/render/svg.mjs +231 -21
- package/src/style/style.mjs +10 -0
- package/src/style/text.mjs +195 -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
|
|
@@ -31,6 +45,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
31
45
|
[`docs/API.template.md.njk`](docs/API.template.md.njk) on every
|
|
32
46
|
`npm run build:docs` run, so it can never drift from the README.
|
|
33
47
|
The TypeDoc devDependency was removed.
|
|
48
|
+
- Reusable arrow model classes (`DiagramArrow`, `ArrowEndpoint`,
|
|
49
|
+
`ArrowLine`, `ArrowLabel`) are now exported from the package root
|
|
50
|
+
and used by both sequence messages and component/class connections.
|
|
51
|
+
- Sequence diagrams now support endpoint labels, long label wrapping
|
|
52
|
+
against arrowhead-safe budgets, `hide unlinked`, `header`,
|
|
53
|
+
`footer`, `mainframe`, single-canvas `newpage`, solid lifelines,
|
|
54
|
+
and simplified `&` parallel-message parsing.
|
|
55
|
+
- Sequence diagrams now support multiline participant block titles,
|
|
56
|
+
message alignment / response-below-arrow skinparams, actor style
|
|
57
|
+
modes, group secondary labels and colours, safe formatted
|
|
58
|
+
autonumber output, Teoz pragmas / partition wrappers, and expanded
|
|
59
|
+
sequence skinparams for messages, notes, groups, dividers, and
|
|
60
|
+
activation bars.
|
|
61
|
+
- SVG marker assets for all produced arrowhead forms are stored under
|
|
62
|
+
[`assets/arrowheads/`](assets/arrowheads/), and the docs build now
|
|
63
|
+
emits a self-updating model class diagram in the README architecture
|
|
64
|
+
section.
|
|
34
65
|
|
|
35
66
|
### Changed
|
|
36
67
|
|
|
@@ -39,6 +70,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
39
70
|
`edgeLabel.textColor`, `edgeLabel.maxWidth`, …). The chip itself is
|
|
40
71
|
emitted with `roughness: 0` and no rounded corners so it reads as a
|
|
41
72
|
clean badge sitting on the line; default font size dropped to 10 px.
|
|
73
|
+
- UML class boxes now draw a thin compartment separator between
|
|
74
|
+
attribute-like members and operation/function members when both are
|
|
75
|
+
present.
|
|
76
|
+
- Sequence-diagram rendering now gives combined fragments typed
|
|
77
|
+
background/stroke colours with solid header labels, reserves vertical
|
|
78
|
+
margins around fragment frames, expands nested parent fragments
|
|
79
|
+
recursively, prevents adjacent fragment overlap, and colours
|
|
80
|
+
participant heads with deterministic hash-based pastel fills.
|
|
81
|
+
- Sequence-diagram message labels now wrap to their available arrow
|
|
82
|
+
length and reserve enough vertical space so long labels do not
|
|
83
|
+
overlap neighbouring timeline entries.
|
|
42
84
|
- The `svg.mjs` renderer now honours the per-element `roughness`
|
|
43
85
|
field, so connection arrows / lines and edge-label chips appear
|
|
44
86
|
perfectly straight in the exported SVG / PNG (matching the existing
|
|
@@ -47,6 +89,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
47
89
|
style document. Existing reads (`FONT.sizeTitle`, `FONT.family`,
|
|
48
90
|
…) keep working; calls to `setStyle()` / `loadStyleFromFile()`
|
|
49
91
|
immediately propagate to sizing and rendering.
|
|
92
|
+
- Sequence-diagram timeline spacing is centralized in one spacing
|
|
93
|
+
contract so messages, notes, refs, markers, fragments, and wrapped
|
|
94
|
+
endpoint labels reserve symmetric top/bottom gaps consistently.
|
|
95
|
+
|
|
96
|
+
### Fixed
|
|
97
|
+
|
|
98
|
+
- Connection arrows now always inherit the **outline colour of their
|
|
99
|
+
source box** (not the owning plane's colour), and arrowheads
|
|
100
|
+
(`arrow`, `triangle`, `triangle_outline`, `diamond`,
|
|
101
|
+
`diamond_outline`) are rendered in the matching colour in both the
|
|
102
|
+
Excalidraw JSON output and the SVG / PNG export. The SVG renderer
|
|
103
|
+
emits one `<marker>` definition per (arrowhead-type, colour)
|
|
104
|
+
combination actually in use and references it via a
|
|
105
|
+
colour-suffixed marker id, so renderers without
|
|
106
|
+
`context-stroke` support (resvg-js, some Markdown sanitisers) still
|
|
107
|
+
produce coloured arrowheads. Box-stroke resolution is shared with
|
|
108
|
+
the box renderer through the new `boxStrokeColor()` helper, so
|
|
109
|
+
arrows always agree with the box outline including the
|
|
110
|
+
per-id colours used for `__floating__`-plane children.
|
|
111
|
+
- Class-diagram visual regressions on large tplant-style sources:
|
|
112
|
+
- Composition (`*--`) and aggregation (`o--`) arrows now keep
|
|
113
|
+
their intentional `endArrowhead: null`. The renderer used to
|
|
114
|
+
coerce `null` to `"arrow"`, which produced a spurious target
|
|
115
|
+
arrow alongside the source diamond.
|
|
116
|
+
- The synthetic `__floating__` collector plane (used for
|
|
117
|
+
declarations that live outside any explicit
|
|
118
|
+
`package` / `namespace`) is no longer drawn as a visible
|
|
119
|
+
bounding rectangle or labelled tab. Its child boxes each
|
|
120
|
+
receive their own deterministic per-id colour
|
|
121
|
+
(`planeColor(box.id)`) so individual top-level types stay
|
|
122
|
+
visually distinguishable, and outgoing arrows pick up the
|
|
123
|
+
matching source-box stroke colour rather than the (invisible)
|
|
124
|
+
floating-plane colour.
|
|
125
|
+
- Long class / interface / enum member signatures now wrap at
|
|
126
|
+
semantically meaningful break points (after `,` `(` `:`,
|
|
127
|
+
before `|` `&` `)`) via the new `wrapMemberSignature` helper
|
|
128
|
+
in `src/style/text.mjs`, with continuation indent. Sizing
|
|
129
|
+
grows the box height accordingly so members no longer bleed
|
|
130
|
+
past the right edge.
|
|
131
|
+
- SVG start markers are now anchored at the visual tip, so backward
|
|
132
|
+
and start-side arrowheads point at their endpoint instead of starting
|
|
133
|
+
there. Additional rendered heads include circles, dots, bars, and
|
|
134
|
+
partial top/bottom heads.
|
|
50
135
|
|
|
51
136
|
## [0.3.7] - 2026-05-04
|
|
52
137
|
|
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.7.0** · 162 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,31 @@ 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
|
+
|
|
126
|
+
See the full [Sequence Diagram Component Coverage](./docs/sequence-components.md) for detailed examples and support matrix.
|
|
127
|
+
|
|
110
128
|
### Run the tests
|
|
111
129
|
|
|
112
130
|
```sh
|
|
113
131
|
npm test
|
|
114
132
|
```
|
|
115
133
|
|
|
116
|
-
Ships with **
|
|
134
|
+
Ships with **162 tests** across functional, edge-case,
|
|
117
135
|
security (XSS / ReDoS / prototype-pollution), and self-introspection
|
|
118
136
|
suites.
|
|
119
137
|
|
|
@@ -170,6 +188,18 @@ To add support for a new PlantUML keyword, drop a new file in
|
|
|
170
188
|
`src/parser/plugins/` and append it to the default array in
|
|
171
189
|
[`plantuml.mjs`](./src/parser/plantuml.mjs). No engine change required.
|
|
172
190
|
|
|
191
|
+
### Model classes
|
|
192
|
+
|
|
193
|
+

|
|
194
|
+
|
|
195
|
+
_Sources: [PlantUML](docs/ressources/generated/puml/model.puml) · [SVG](docs/ressources/generated/svg/model.svg)_
|
|
196
|
+
|
|
197
|
+
The model diagram is generated dynamically from exported classes in
|
|
198
|
+
[`src/model/diagram.mjs`](./src/model/diagram.mjs). It shows how the
|
|
199
|
+
reusable arrow classes sit underneath both component connections and
|
|
200
|
+
sequence messages, so future model classes appear in the README without
|
|
201
|
+
hand-maintained PlantUML.
|
|
202
|
+
|
|
173
203
|
## Pipeline
|
|
174
204
|
|
|
175
205
|
```text
|
|
@@ -193,6 +223,9 @@ PlantUML text
|
|
|
193
223
|
```text
|
|
194
224
|
excaliplant
|
|
195
225
|
├── assets
|
|
226
|
+
│ ├── arrowheads
|
|
227
|
+
│ │ ├── arrowheads.svg
|
|
228
|
+
│ │ └── manifest.json
|
|
196
229
|
│ └── fonts
|
|
197
230
|
│ ├── Excalifont-Regular.ttf
|
|
198
231
|
│ ├── Excalifont-Regular.woff2
|
|
@@ -201,20 +234,28 @@ excaliplant
|
|
|
201
234
|
│ └── excaliplant.mjs
|
|
202
235
|
├── docs
|
|
203
236
|
│ ├── ressources
|
|
237
|
+
│ │ └── sequence
|
|
238
|
+
│ │ ├── puml
|
|
239
|
+
│ │ └── svg
|
|
204
240
|
│ ├── scripts
|
|
205
241
|
│ │ ├── build-docs.mjs
|
|
242
|
+
│ │ ├── build-sequence-coverage.mjs
|
|
206
243
|
│ │ ├── check-build-manifest.mjs
|
|
207
244
|
│ │ ├── config.mjs
|
|
208
245
|
│ │ ├── extract-api.mjs
|
|
209
246
|
│ │ ├── extract-docs.mjs
|
|
210
247
|
│ │ ├── file-tree.mjs
|
|
211
|
-
│ │
|
|
248
|
+
│ │ ├── self-diagrams.mjs
|
|
249
|
+
│ │ └── sequence-coverage-examples.mjs
|
|
212
250
|
│ ├── API.md
|
|
213
251
|
│ ├── API.template.md.njk
|
|
214
|
-
│
|
|
252
|
+
│ ├── README.template.md.njk
|
|
253
|
+
│ ├── sequence-components.md
|
|
254
|
+
│ └── sequence-components.template.md.njk
|
|
215
255
|
├── scripts
|
|
216
256
|
│ ├── auto-patch-deps.mjs
|
|
217
257
|
│ ├── bump-release-version.mjs
|
|
258
|
+
│ ├── clean-test-output.mjs
|
|
218
259
|
│ ├── merge-driver-prefer-higher-version.mjs
|
|
219
260
|
│ ├── prepublish-guard.mjs
|
|
220
261
|
│ ├── setup-merge-drivers.mjs
|
|
@@ -223,6 +264,7 @@ excaliplant
|
|
|
223
264
|
│ ├── layout
|
|
224
265
|
│ │ ├── elk_layout.mjs
|
|
225
266
|
│ │ ├── sequence_layout.mjs
|
|
267
|
+
│ │ ├── sequence_spacing.mjs
|
|
226
268
|
│ │ └── sizing.mjs
|
|
227
269
|
│ ├── model
|
|
228
270
|
│ │ └── diagram.mjs
|
|
@@ -249,12 +291,15 @@ excaliplant
|
|
|
249
291
|
│ ├── style.mjs
|
|
250
292
|
│ └── text.mjs
|
|
251
293
|
├── tests
|
|
294
|
+
│ ├── helpers
|
|
295
|
+
│ │ └── output.mjs
|
|
252
296
|
│ ├── edge_cases.test.mjs
|
|
253
297
|
│ ├── functional_more.test.mjs
|
|
254
298
|
│ ├── merge_driver.test.mjs
|
|
255
299
|
│ ├── plantuml.test.mjs
|
|
256
300
|
│ ├── security.test.mjs
|
|
257
301
|
│ ├── self_introspection.test.mjs
|
|
302
|
+
│ ├── sequence_components.test.mjs
|
|
258
303
|
│ └── style.test.mjs
|
|
259
304
|
├── AGENTS.md
|
|
260
305
|
├── CHANGELOG.md
|
|
@@ -266,6 +311,7 @@ excaliplant
|
|
|
266
311
|
├── SECURITY.md
|
|
267
312
|
├── THIRD_PARTY_NOTICES.md
|
|
268
313
|
├── index.mjs
|
|
314
|
+
├── lifecycle-test.svg
|
|
269
315
|
├── package.json
|
|
270
316
|
├── style.example.json
|
|
271
317
|
├── style.example.yaml
|
|
@@ -323,6 +369,15 @@ that any Excalidraw front-end can open. The companion module
|
|
|
323
369
|
`src/render/svg.mjs` converts the same JSON to SVG for the
|
|
324
370
|
build-time documentation pipeline.
|
|
325
371
|
|
|
372
|
+
### sequence-spacing
|
|
373
|
+
|
|
374
|
+
Central spacing contract for sequence diagrams.
|
|
375
|
+
|
|
376
|
+
Sequence layout has many visual item types (messages, notes, refs,
|
|
377
|
+
dividers, fragments, lifecycle bars). They all reserve vertical space
|
|
378
|
+
through this module so adding a new timeline item does not introduce a
|
|
379
|
+
one-off top/bottom rhythm.
|
|
380
|
+
|
|
326
381
|
## License
|
|
327
382
|
|
|
328
383
|
MIT © grethel-labs
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 120 80" aria-label="Arrowhead marker shapes">
|
|
2
|
+
<defs>
|
|
3
|
+
<symbol id="arrow" viewBox="0 0 10 10">
|
|
4
|
+
<path d="M0,0 L10,5 L0,10" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" />
|
|
5
|
+
</symbol>
|
|
6
|
+
<symbol id="triangle" viewBox="0 0 10 10">
|
|
7
|
+
<path d="M0,0 L10,5 L0,10 z" fill="currentColor" />
|
|
8
|
+
</symbol>
|
|
9
|
+
<symbol id="triangle_outline" viewBox="0 0 10 10">
|
|
10
|
+
<path d="M0,0 L10,5 L0,10 z" fill="#fff" stroke="currentColor" />
|
|
11
|
+
</symbol>
|
|
12
|
+
<symbol id="diamond" viewBox="0 0 12 10">
|
|
13
|
+
<path d="M0,5 L6,0 L12,5 L6,10 z" fill="currentColor" />
|
|
14
|
+
</symbol>
|
|
15
|
+
<symbol id="diamond_outline" viewBox="0 0 12 10">
|
|
16
|
+
<path d="M0,5 L6,0 L12,5 L6,10 z" fill="#fff" stroke="currentColor" />
|
|
17
|
+
</symbol>
|
|
18
|
+
<symbol id="circle_outline" viewBox="0 0 10 10">
|
|
19
|
+
<path d="M5,5 m-4,0 a4,4 0 1,0 8,0 a4,4 0 1,0 -8,0" fill="#fff" stroke="currentColor" />
|
|
20
|
+
</symbol>
|
|
21
|
+
<symbol id="dot" viewBox="0 0 10 10">
|
|
22
|
+
<path d="M5,5 m-3,0 a3,3 0 1,0 6,0 a3,3 0 1,0 -6,0" fill="currentColor" />
|
|
23
|
+
</symbol>
|
|
24
|
+
<symbol id="bar" viewBox="0 0 10 10">
|
|
25
|
+
<path d="M5,0 L5,10" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" />
|
|
26
|
+
</symbol>
|
|
27
|
+
<symbol id="partial_top" viewBox="0 0 10 10">
|
|
28
|
+
<path d="M0,0 L10,5" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" />
|
|
29
|
+
</symbol>
|
|
30
|
+
<symbol id="partial_bottom" viewBox="0 0 10 10">
|
|
31
|
+
<path d="M0,10 L10,5" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" />
|
|
32
|
+
</symbol>
|
|
33
|
+
</defs>
|
|
34
|
+
<g color="#1f2933" transform="translate(8 8)">
|
|
35
|
+
<use href="#arrow" x="0" y="0" width="16" height="16" />
|
|
36
|
+
<use href="#triangle" x="22" y="0" width="16" height="16" />
|
|
37
|
+
<use href="#triangle_outline" x="44" y="0" width="16" height="16" />
|
|
38
|
+
<use href="#diamond" x="66" y="0" width="19" height="16" />
|
|
39
|
+
<use href="#diamond_outline" x="91" y="0" width="19" height="16" />
|
|
40
|
+
<use href="#circle_outline" x="0" y="34" width="16" height="16" />
|
|
41
|
+
<use href="#dot" x="22" y="34" width="16" height="16" />
|
|
42
|
+
<use href="#bar" x="44" y="34" width="16" height="16" />
|
|
43
|
+
<use href="#partial_top" x="66" y="34" width="16" height="16" />
|
|
44
|
+
<use href="#partial_bottom" x="88" y="34" width="16" height="16" />
|
|
45
|
+
</g>
|
|
46
|
+
</svg>
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
{
|
|
2
|
+
"source": "assets/arrowheads/arrowheads.svg",
|
|
3
|
+
"generatedBy": "src/render/svg.mjs marker geometry",
|
|
4
|
+
"arrowheads": [
|
|
5
|
+
"arrow",
|
|
6
|
+
"triangle",
|
|
7
|
+
"triangle_outline",
|
|
8
|
+
"diamond",
|
|
9
|
+
"diamond_outline",
|
|
10
|
+
"circle",
|
|
11
|
+
"circle_outline",
|
|
12
|
+
"dot",
|
|
13
|
+
"bar",
|
|
14
|
+
"partial_top",
|
|
15
|
+
"partial_bottom"
|
|
16
|
+
]
|
|
17
|
+
}
|
package/index.mjs
CHANGED
|
@@ -46,6 +46,16 @@
|
|
|
46
46
|
* each plugin handling one PlantUML construct.
|
|
47
47
|
*/
|
|
48
48
|
|
|
49
|
+
/**
|
|
50
|
+
* @diagram model
|
|
51
|
+
*
|
|
52
|
+
* The model diagram is generated dynamically from exported classes in
|
|
53
|
+
* [`src/model/diagram.mjs`](./src/model/diagram.mjs). It shows how the
|
|
54
|
+
* reusable arrow classes sit underneath both component connections and
|
|
55
|
+
* sequence messages, so future model classes appear in the README without
|
|
56
|
+
* hand-maintained PlantUML.
|
|
57
|
+
*/
|
|
58
|
+
|
|
49
59
|
import { parsePlantUml } from "./src/parser/plantuml.mjs";
|
|
50
60
|
import { layoutDiagram } from "./src/layout/elk_layout.mjs";
|
|
51
61
|
import { exportDiagram } from "./src/render/excalidraw.mjs";
|
|
@@ -76,15 +86,36 @@ export {
|
|
|
76
86
|
parseSimpleYaml,
|
|
77
87
|
} from "./src/style/style.mjs";
|
|
78
88
|
export {
|
|
89
|
+
ARROW_ANCHORS,
|
|
90
|
+
ARROW_DIRECTIONS,
|
|
91
|
+
ARROW_HEADS,
|
|
92
|
+
ARROW_LINE_STYLES,
|
|
93
|
+
ArrowEndpoint,
|
|
94
|
+
ArrowLabel,
|
|
95
|
+
ArrowLine,
|
|
79
96
|
Box,
|
|
80
97
|
Connection,
|
|
98
|
+
DEFAULT_ARROW_HEAD_SIZE,
|
|
81
99
|
Diagram,
|
|
100
|
+
DiagramArrow,
|
|
82
101
|
Plane,
|
|
83
102
|
Subplane,
|
|
84
103
|
Participant,
|
|
85
104
|
Message,
|
|
86
105
|
SequenceDiagram,
|
|
106
|
+
SequenceActivation,
|
|
107
|
+
SequenceArrow,
|
|
108
|
+
SequenceArrowEndpoint,
|
|
109
|
+
SequenceArrowLine,
|
|
110
|
+
SequenceFragment,
|
|
111
|
+
SequenceMarker,
|
|
87
112
|
SequenceNote,
|
|
113
|
+
SequenceParticipantGroup,
|
|
114
|
+
SequenceReference,
|
|
115
|
+
SEQUENCE_ARROW_ANCHORS,
|
|
116
|
+
SEQUENCE_ARROW_DIRECTIONS,
|
|
117
|
+
SEQUENCE_ARROW_HEADS,
|
|
118
|
+
SEQUENCE_ARROW_LINE_STYLES,
|
|
88
119
|
SHAPES,
|
|
89
120
|
} from "./src/model/diagram.mjs";
|
|
90
121
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@grethel-labs/excaliplant",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.7.0",
|
|
4
4
|
"description": "PlantUML → ELK layout → Excalidraw renderer with a plugin-based parser.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "index.mjs",
|
|
@@ -11,6 +11,7 @@
|
|
|
11
11
|
"index.mjs",
|
|
12
12
|
"bin/",
|
|
13
13
|
"src/",
|
|
14
|
+
"assets/arrowheads/",
|
|
14
15
|
"assets/fonts/",
|
|
15
16
|
"README.md",
|
|
16
17
|
"CHANGELOG.md",
|
|
@@ -34,11 +35,12 @@
|
|
|
34
35
|
"./style": "./src/style/style.mjs"
|
|
35
36
|
},
|
|
36
37
|
"scripts": {
|
|
37
|
-
"
|
|
38
|
+
"pretest": "node scripts/clean-test-output.mjs",
|
|
39
|
+
"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/sequence_components.test.mjs tests/style.test.mjs",
|
|
38
40
|
"typecheck": "tsc -p tsconfig.json",
|
|
39
41
|
"build:docs": "node docs/scripts/build-docs.mjs",
|
|
40
42
|
"build:api": "node docs/scripts/build-docs.mjs",
|
|
41
|
-
"build": "npm run build:docs",
|
|
43
|
+
"build": "npm run test && npm run build:docs && npm run build:api && tsc -p tsconfig.json --emitDeclarationOnly",
|
|
42
44
|
"format": "prettier --write .",
|
|
43
45
|
"format:check": "prettier --check .",
|
|
44
46
|
"prepare": "husky && node scripts/setup-merge-drivers.mjs",
|
|
@@ -62,6 +64,8 @@
|
|
|
62
64
|
"svg",
|
|
63
65
|
"png",
|
|
64
66
|
"uml",
|
|
67
|
+
"javascript",
|
|
68
|
+
"js",
|
|
65
69
|
"sequence-diagram"
|
|
66
70
|
],
|
|
67
71
|
"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).
|