@grethel-labs/excaliplant 0.1.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 grethel-labs
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OF OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,302 @@
1
+ # excaliplant
2
+
3
+ PlantUML → Excalidraw renderer with a plugin-based parser. Standalone library.
4
+
5
+ <!-- BEGIN:version -->
6
+ **Version:** `0.1.0`
7
+ <!-- END:version -->
8
+
9
+ ## Self-rendered diagrams
10
+
11
+ The diagrams below are generated **by excaliplant itself** at build time
12
+ (`npm run build:docs`) from PlantUML sources that describe this very
13
+ repository. The doc snippets under each image are extracted from the
14
+ source code via `@diagram` JSDoc tags.
15
+
16
+ <!-- BEGIN:diagrams -->
17
+ ### Module structure
18
+
19
+ ![Module structure](./docs/modules.svg)
20
+
21
+ The module graph reflects how the source is laid out under
22
+ [`src/`](./src/). Note in particular how the parser is split into a
23
+ single tiny `engine` plus a stack of plugins under `parser/plugins/`,
24
+ each plugin handling one PlantUML construct.
25
+
26
+ ### renderPlantUml flow
27
+
28
+ ![renderPlantUml flow](./docs/sequence.svg)
29
+
30
+ The call graph for `renderPlantUml(text)` walks three subsystems:
31
+
32
+ 1. **parser** turns PlantUML text into a model (`Diagram` /
33
+ `SequenceDiagram`). The parser is plugin-driven; see the next
34
+ diagram for the plugin breakdown.
35
+ 2. **layout** decides positions. Component diagrams go through ELK
36
+ (layered + orthogonal routing); sequence diagrams use a small
37
+ deterministic tabular layout.
38
+ 3. **renderer** walks the laid-out model and emits Excalidraw JSON.
39
+ The same model can also be exported to SVG via
40
+ [`src/render/svg.mjs`](./src/render/svg.mjs) — used by the
41
+ documentation pipeline.
42
+
43
+ ### Parser plugins
44
+
45
+ ![Parser plugins](./docs/plugins.svg)
46
+
47
+ Each parser plugin is a tiny self-contained file that handles ONE
48
+ PlantUML construct. The engine offers each input line to plugins
49
+ in registration order; the first plugin that returns `true` wins.
50
+
51
+ To add support for a new PlantUML keyword, drop a new file in
52
+ `src/parser/plugins/` and append it to the default array in
53
+ [`plantuml.mjs`](./src/parser/plantuml.mjs). No engine change required.
54
+
55
+ <!-- END:diagrams -->
56
+
57
+ ## Module documentation
58
+
59
+ <!-- BEGIN:module-docs -->
60
+ #### layout
61
+
62
+ Layout chooses positions for every shape and routes every edge.
63
+ Component / use-case / deployment diagrams flow through ELK
64
+ (`elkjs`) using the `layered` algorithm with orthogonal edge
65
+ routing. After ELK returns we chamfer 90° corners so the result
66
+ matches Excalidraw's diagonal-corner aesthetic.
67
+
68
+ Sequence diagrams skip ELK entirely — their layout is strictly
69
+ tabular (lifelines on the X axis, time on the Y axis), so a
70
+ deterministic ~90-line algorithm produces better, more compact
71
+ results than a force-directed solver could.
72
+
73
+ #### model
74
+
75
+ Input-agnostic diagram model. Two top-level kinds:
76
+
77
+ - **`Diagram`** — component / deployment / use-case style
78
+ (planes, subplanes, boxes, connections).
79
+ - **`SequenceDiagram`** — lifelines + messages + notes.
80
+
81
+ Layout and renderer dispatch on the model class. Anything that
82
+ can be expressed as one of these two shapes flows through the
83
+ pipeline; the parser is just one possible source. Callers can
84
+ also build a `Diagram` programmatically and feed it to
85
+ `renderDiagram()`.
86
+
87
+ #### parser/engine
88
+
89
+ A ~50-line line-walker. The engine itself knows nothing about
90
+ PlantUML syntax; that lives entirely in plugins. Block plugins
91
+ (multi-line notes, class bodies) take exclusive ownership of
92
+ subsequent lines until they release.
93
+
94
+ Plugin contract:
95
+ ```js
96
+ {
97
+ name,
98
+ tryStart?(line, ctx): null | { onLine, tryEnd },
99
+ tryLine?(line, ctx): boolean,
100
+ }
101
+ ```
102
+
103
+ #### render
104
+
105
+ Emits Excalidraw JSON. Each model shape is dispatched to a
106
+ dedicated `renderXxx()` function that produces one or more
107
+ Excalidraw primitive elements (rectangle, ellipse, line, arrow,
108
+ text). The output document is a stand-alone `.excalidraw` file
109
+ that any Excalidraw front-end can open. The companion module
110
+ [`src/render/svg.mjs`](./src/render/svg.mjs) converts the same
111
+ JSON to SVG for the build-time documentation pipeline.
112
+
113
+ <!-- END:module-docs -->
114
+
115
+ ## Pipeline
116
+
117
+ ```
118
+ PlantUML text
119
+ │ parsePlantUml()
120
+ ▼
121
+ Diagram (planes, subplanes, boxes, connections)
122
+ │ layoutDiagram() (sizing → ELK layered + orthogonal routing → chamfer)
123
+ ▼
124
+ Diagram with absolute positions and edge paths
125
+ │ exportDiagram()
126
+ ▼
127
+ Excalidraw JSON
128
+ ```
129
+
130
+ ## API
131
+
132
+ ```js
133
+ import { renderPlantUml } from "./index.mjs";
134
+
135
+ const excalidraw = await renderPlantUml(plantumlText, { sourceLabel: "demo" });
136
+ ```
137
+
138
+ Lower-level entry points (`parsePlantUml`, `layoutDiagram`,
139
+ `exportDiagram`, `renderDiagram`) are also exported. The model classes
140
+ (`Diagram`, `Plane`, `Subplane`, `Box`, `Connection`) are exported for
141
+ callers that want to construct shapes programmatically.
142
+
143
+ ## Supported PlantUML subset
144
+
145
+ ### Component / use-case / deployment diagrams
146
+
147
+ ```plantuml
148
+ @startuml
149
+ title "<free text>"
150
+
151
+ ' --- containers (any nest the others) -------------------------------
152
+ package "<Title>" as <id> { ... }
153
+ frame "<Title>" as <id> { ... }
154
+ folder "<Title>" as <id> { ... }
155
+ node "<Title>" as <id> { ... }
156
+ rectangle "<Title>" as <id> { ... }
157
+ together { ... }
158
+
159
+ ' --- shapes --------------------------------------------------------
160
+ [Title] as <id> [: description]
161
+ component "Title" <<stereo>> as <id> [: description]
162
+ rectangle "Title" as <id>
163
+ actor "Title" as <id> ' or just `actor User`
164
+ usecase "Title" as <id> ' or `(Title) as <id>`
165
+ database "Title" as <id>
166
+ node "Title" as <id> ' (no `{}` → 3-D box shape)
167
+ cloud "Title" as <id>
168
+ interface "Title" as <id> ' rendered as a small "lollipop" circle
169
+ entity "Title" as <id>
170
+ class "Title" as <id> { member; member }
171
+
172
+ ' --- connections ---------------------------------------------------
173
+ a --> b : label ' solid arrow
174
+ a <-- b
175
+ a <--> b
176
+ a -up-> b ' direction hint (up|down|left|right)
177
+ a ..> b ' dependency (dashed)
178
+ a <|-- b ' inheritance (triangle on parent)
179
+ a ..|> b ' realization (dashed + triangle)
180
+ a *-- b ' composition (filled diamond)
181
+ a o-- b ' aggregation (open diamond)
182
+
183
+ ' --- notes ---------------------------------------------------------
184
+ note left of <id> : text
185
+ note right of <id> : text
186
+ note top of <id> : text
187
+ note bottom of <id> : text
188
+ note "free standing text" as N1
189
+ N1 .. <id>
190
+
191
+ ' Multi-line text everywhere via \n.
192
+ @enduml
193
+ ```
194
+
195
+ ### Sequence diagrams
196
+
197
+ The parser auto-switches to the sequence pipeline as soon as it sees a
198
+ `participant`/`boundary`/`control`/`collections`/`queue` keyword.
199
+
200
+ ```plantuml
201
+ @startuml
202
+ title "Login flow"
203
+ actor User
204
+ participant "Web UI" as ui
205
+ participant Auth as auth
206
+ database DB
207
+
208
+ User -> ui : open page
209
+ ui -> auth : login(name, pwd)
210
+ auth -> DB : SELECT user
211
+ DB --> auth : row ' dashed = reply
212
+ auth --> ui : ok\n(token)
213
+ ui --> User : show home
214
+ auth -> auth : audit ' self-message (loop arrow)
215
+
216
+ note right of auth : token has\n5 min ttl
217
+ note over ui, auth : TLS only
218
+ @enduml
219
+ ```
220
+
221
+ Sequence diagrams use a separate, deterministic tabular layout (no ELK),
222
+ since lifelines + time form a strictly tabular structure.
223
+
224
+ ## Architecture
225
+
226
+ The parser is built around a tiny line-driven engine plus a list of
227
+ self-contained **plugins** (one per PlantUML construct):
228
+
229
+ ```
230
+ src/parser/
231
+ ├── engine.mjs ← ~50 lines, walks lines + dispatches to plugins
232
+ ├── utils.mjs ← shared regexes / helpers (slug, classifyArrow, …)
233
+ ├── component_context.mjs ← mutable state for component-style parses
234
+ ├── sequence_context.mjs ← mutable state for sequence parses
235
+ ├── plantuml.mjs ← entry: dispatch + plugin registry
236
+ └── plugins/
237
+ ├── component/
238
+ │ ├── preamble.mjs ← title, closing brace
239
+ │ ├── containers.mjs ← package / frame / folder / node / rectangle / together
240
+ │ ├── shapes.mjs ← [X], (Y), shape keywords, class { members }
241
+ │ ├── connections.mjs ← all arrow flavours
242
+ │ └── notes.mjs ← note of, free notes, multi-line note blocks
243
+ └── sequence/
244
+ ├── preamble.mjs ← title
245
+ ├── participants.mjs
246
+ ├── messages.mjs
247
+ └── notes.mjs ← side / over notes (single + multi-line)
248
+ ```
249
+
250
+ A plugin is just `{ name, tryLine?(line, ctx), tryStart?(line, ctx) }`
251
+ — see `engine.mjs` for the full contract. Block plugins (notes, class
252
+ bodies) take over the engine until they decide to release.
253
+
254
+ ### Adding a new construct
255
+
256
+ 1. Create a new plugin file in `plugins/component/` or `plugins/sequence/`.
257
+ 2. Register it in `DEFAULT_COMPONENT_PLUGINS` / `DEFAULT_SEQUENCE_PLUGINS`
258
+ in `plantuml.mjs`. Order matters only when several plugins might match
259
+ the same line.
260
+
261
+ ### Injecting plugins from outside
262
+
263
+ Without forking, callers can append their own plugins:
264
+
265
+ ```js
266
+ parsePlantUml(src, {
267
+ plugins: {
268
+ component: [...DEFAULT_COMPONENT_PLUGINS, myCustomPlugin],
269
+ },
270
+ });
271
+ ```
272
+
273
+ ## Dependencies
274
+
275
+ - [`elkjs`](https://www.npmjs.com/package/elkjs) — Eclipse Layout Kernel
276
+ (port to JS). Provides hierarchical layered layout + orthogonal edge
277
+ routing.
278
+ - Excalidraw is consumed via its **file-format API**: this lib emits
279
+ the JSON document that any Excalidraw front-end can open. We do not
280
+ bundle the Excalidraw React component (47 MB, browser/DOM-bound;
281
+ not usable in Node).
282
+
283
+ ### Why not delegate parsing / rendering to a third-party library?
284
+
285
+ We evaluated:
286
+
287
+ | Candidate | Outcome |
288
+ |---|---|
289
+ | `plantuml-parser` (Enteee) | Drops `title`, `note`, `actor`/`database`/`cloud`/`entity`/`rectangle` shape declarations, sequence participants, and `-up->` direction hints — too lossy to replace our parser without re-introducing the same regex code as a "supplementary scanner". |
290
+ | `@excalidraw/excalidraw` | 47 MB React component, depends on `window` / `canvas`. Not usable in a Node library. |
291
+ | `@excalidraw/utils` | 96 MB, same DOM dependencies. Not usable. |
292
+ | `@excalidraw/mermaid-to-excalidraw` | Mermaid-only input; doesn't expose a generic skeleton API. |
293
+
294
+ So instead we make our **own** parser easy to extend (plugin
295
+ architecture above) and our renderer talks to Excalidraw via its
296
+ documented JSON file format.
297
+
298
+ ## Tests
299
+
300
+ ```sh
301
+ npm test
302
+ ```
package/index.mjs ADDED
@@ -0,0 +1,89 @@
1
+ // diagram-renderer — public API.
2
+ //
3
+ // PlantUML in, Excalidraw JSON out. Internally:
4
+ //
5
+ // PlantUML text
6
+ // │
7
+ // ▼
8
+ // parsePlantUml() → Diagram model
9
+ // │
10
+ // ▼
11
+ // layoutDiagram() → Diagram with absolute positions + edge paths
12
+ // │ (sizing, ELK layered routing, corner chamfering)
13
+ // ▼
14
+ // exportDiagram() → Excalidraw JSON
15
+ //
16
+ // External dependencies:
17
+ // * elkjs — Eclipse Layout Kernel (layout & orthogonal routing)
18
+ // * Excalidraw — consumed via its file-format API (we emit the JSON
19
+ // that Excalidraw's import expects). We never bundle
20
+ // the React component; this lib produces files that
21
+ // *any* Excalidraw front-end can open.
22
+
23
+ /**
24
+ * @diagram sequence
25
+ *
26
+ * The call graph for `renderPlantUml(text)` walks three subsystems:
27
+ *
28
+ * 1. **parser** turns PlantUML text into a model (`Diagram` /
29
+ * `SequenceDiagram`). The parser is plugin-driven; see the next
30
+ * diagram for the plugin breakdown.
31
+ * 2. **layout** decides positions. Component diagrams go through ELK
32
+ * (layered + orthogonal routing); sequence diagrams use a small
33
+ * deterministic tabular layout.
34
+ * 3. **renderer** walks the laid-out model and emits Excalidraw JSON.
35
+ * The same model can also be exported to SVG via
36
+ * [`src/render/svg.mjs`](./src/render/svg.mjs) — used by the
37
+ * documentation pipeline.
38
+ */
39
+
40
+ /**
41
+ * @diagram modules
42
+ *
43
+ * The module graph reflects how the source is laid out under
44
+ * [`src/`](./src/). Note in particular how the parser is split into a
45
+ * single tiny `engine` plus a stack of plugins under `parser/plugins/`,
46
+ * each plugin handling one PlantUML construct.
47
+ */
48
+
49
+ import { parsePlantUml } from "./src/parser/plantuml.mjs";
50
+ import { layoutDiagram } from "./src/layout/elk_layout.mjs";
51
+ import { exportDiagram } from "./src/render/excalidraw.mjs";
52
+
53
+ export { parsePlantUml } from "./src/parser/plantuml.mjs";
54
+ export { layoutDiagram } from "./src/layout/elk_layout.mjs";
55
+ export { exportDiagram } from "./src/render/excalidraw.mjs";
56
+ export {
57
+ Box, Connection, Diagram, Plane, Subplane,
58
+ Participant, Message, SequenceDiagram, SequenceNote,
59
+ SHAPES,
60
+ } from "./src/model/diagram.mjs";
61
+
62
+ /**
63
+ * Render a PlantUML source string to an Excalidraw JSON document.
64
+ *
65
+ * @param {string} plantuml PlantUML text (see src/parser/plantuml.mjs
66
+ * for the supported subset).
67
+ * @param {object} [opts]
68
+ * @param {string} [opts.sourceLabel] Forwarded to the renderer's
69
+ * appState.name.
70
+ * @returns {Promise<object>} Excalidraw JSON.
71
+ */
72
+ export async function renderPlantUml(plantuml, opts = {}) {
73
+ const diagram = parsePlantUml(plantuml);
74
+ await layoutDiagram(diagram);
75
+ return exportDiagram(diagram, {
76
+ sourceLabel: opts.sourceLabel ?? diagram.title ?? "",
77
+ });
78
+ }
79
+
80
+ /**
81
+ * Render an already-built Diagram model. Useful for callers that want
82
+ * to bypass the PlantUML parser and feed shapes programmatically.
83
+ */
84
+ export async function renderDiagram(diagram, opts = {}) {
85
+ await layoutDiagram(diagram);
86
+ return exportDiagram(diagram, {
87
+ sourceLabel: opts.sourceLabel ?? diagram.title ?? "",
88
+ });
89
+ }
package/package.json ADDED
@@ -0,0 +1,53 @@
1
+ {
2
+ "name": "@grethel-labs/excaliplant",
3
+ "version": "0.1.0",
4
+ "description": "PlantUML → ELK layout → Excalidraw renderer with a plugin-based parser.",
5
+ "type": "module",
6
+ "main": "index.mjs",
7
+ "files": [
8
+ "index.mjs",
9
+ "src/",
10
+ "README.md",
11
+ "LICENSE"
12
+ ],
13
+ "exports": {
14
+ ".": "./index.mjs",
15
+ "./parser/plantuml": "./src/parser/plantuml.mjs",
16
+ "./layout": "./src/layout/elk_layout.mjs",
17
+ "./render": "./src/render/excalidraw.mjs",
18
+ "./model": "./src/model/diagram.mjs"
19
+ },
20
+ "scripts": {
21
+ "test": "node --test tests/*.test.mjs",
22
+ "build:docs": "node scripts/build-docs.mjs",
23
+ "build:api": "typedoc",
24
+ "build": "npm run build:docs && npm run build:api",
25
+ "prepublishOnly": "npm test && npm run build"
26
+ },
27
+ "repository": {
28
+ "type": "git",
29
+ "url": "git+https://github.com/grethel-labs/excaliplant.git"
30
+ },
31
+ "homepage": "https://github.com/grethel-labs/excaliplant",
32
+ "bugs": "https://github.com/grethel-labs/excaliplant/issues",
33
+ "keywords": [
34
+ "plantuml",
35
+ "excalidraw",
36
+ "diagram",
37
+ "elk",
38
+ "renderer"
39
+ ],
40
+ "publishConfig": {
41
+ "access": "public"
42
+ },
43
+ "dependencies": {
44
+ "elkjs": "^0.9.3"
45
+ },
46
+ "engines": {
47
+ "node": ">=18"
48
+ },
49
+ "license": "MIT",
50
+ "devDependencies": {
51
+ "typedoc": "^0.28.19"
52
+ }
53
+ }