@bpmnkit/core 1.0.0 → 1.2.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.
Files changed (73) hide show
  1. package/README.md +30 -3
  2. package/dist/bpmn/agentic.js +3 -1
  3. package/dist/bpmn/auto-layout.js +184 -15
  4. package/dist/bpmn/bpmn-builder.js +69 -7
  5. package/dist/bpmn/bpmn-model.d.ts +78 -0
  6. package/dist/bpmn/bpmn-parser.js +195 -37
  7. package/dist/bpmn/bpmn-serializer.js +121 -72
  8. package/dist/bpmn/bpmnlint.d.ts +153 -0
  9. package/dist/bpmn/bpmnlint.js +364 -0
  10. package/dist/bpmn/camunda-compat-data.d.ts +165 -0
  11. package/dist/bpmn/camunda-compat-data.js +423 -0
  12. package/dist/bpmn/camunda-compat-feel.d.ts +68 -0
  13. package/dist/bpmn/camunda-compat-feel.js +338 -0
  14. package/dist/bpmn/camunda-compat.d.ts +120 -0
  15. package/dist/bpmn/camunda-compat.js +1677 -0
  16. package/dist/bpmn/camunda7/juel.d.ts +41 -0
  17. package/dist/bpmn/camunda7/juel.js +333 -0
  18. package/dist/bpmn/camunda7/migrate.d.ts +72 -0
  19. package/dist/bpmn/camunda7/migrate.js +1152 -0
  20. package/dist/bpmn/compact.d.ts +4 -0
  21. package/dist/bpmn/compact.js +80 -0
  22. package/dist/bpmn/full-operations.js +5 -2
  23. package/dist/bpmn/label-style.d.ts +51 -0
  24. package/dist/bpmn/label-style.js +116 -0
  25. package/dist/bpmn/lint.d.ts +23 -3
  26. package/dist/bpmn/lint.js +47 -10
  27. package/dist/bpmn/optimize/bpmnlint-rules.d.ts +31 -0
  28. package/dist/bpmn/optimize/bpmnlint-rules.js +916 -0
  29. package/dist/bpmn/optimize/deploy.d.ts +8 -2
  30. package/dist/bpmn/optimize/deploy.js +16 -3
  31. package/dist/bpmn/optimize/index.js +11 -2
  32. package/dist/bpmn/optimize/patterns.js +3 -0
  33. package/dist/bpmn/optimize/types.d.ts +14 -0
  34. package/dist/bpmn/optimize/variable-flow.js +4 -1
  35. package/dist/bpmn/process-delta.d.ts +88 -0
  36. package/dist/bpmn/process-delta.js +236 -0
  37. package/dist/bpmn/process-text-writer.d.ts +53 -0
  38. package/dist/bpmn/process-text-writer.js +193 -0
  39. package/dist/bpmn/process-text.d.ts +175 -0
  40. package/dist/bpmn/process-text.js +1255 -0
  41. package/dist/bpmn/process-types.d.ts +112 -0
  42. package/dist/bpmn/process-types.js +490 -0
  43. package/dist/bpmn/svg.js +51 -22
  44. package/dist/doc/docx.d.ts +20 -0
  45. package/dist/doc/docx.js +253 -0
  46. package/dist/doc/html.d.ts +21 -0
  47. package/dist/doc/html.js +303 -0
  48. package/dist/doc/index.d.ts +7 -0
  49. package/dist/doc/index.js +5 -0
  50. package/dist/doc/markdown.d.ts +11 -0
  51. package/dist/doc/markdown.js +160 -0
  52. package/dist/doc/model.d.ts +129 -0
  53. package/dist/doc/model.js +617 -0
  54. package/dist/doc/zip.d.ts +5 -0
  55. package/dist/doc/zip.js +75 -0
  56. package/dist/index.d.ts +22 -0
  57. package/dist/index.js +11 -0
  58. package/dist/layout/annotations.d.ts +4 -2
  59. package/dist/layout/annotations.js +31 -2
  60. package/dist/layout/collaboration/ordering.d.ts +8 -0
  61. package/dist/layout/collaboration/ordering.js +57 -18
  62. package/dist/layout/orthogonal.d.ts +32 -0
  63. package/dist/layout/orthogonal.js +367 -0
  64. package/dist/layout/repair.d.ts +31 -0
  65. package/dist/layout/repair.js +220 -0
  66. package/dist/layout/semantic/route.js +45 -3
  67. package/dist/node/bpmnlint.d.ts +109 -0
  68. package/dist/node/bpmnlint.js +198 -0
  69. package/dist/node/index.d.ts +2 -0
  70. package/dist/node/index.js +1 -0
  71. package/dist/xml/xml-patch.d.ts +21 -0
  72. package/dist/xml/xml-patch.js +27 -1
  73. package/package.json +2 -2
@@ -0,0 +1,303 @@
1
+ import { buildProcessDocumentation, } from "./model.js";
2
+ export function escapeHtml(s) {
3
+ return s
4
+ .replace(/&/g, "&")
5
+ .replace(/</g, "&lt;")
6
+ .replace(/>/g, "&gt;")
7
+ .replace(/"/g, "&quot;")
8
+ .replace(/'/g, "&#39;");
9
+ }
10
+ /** Anchor ids are built from model ids, which a hostile file can fill with anything. */
11
+ function anchor(kind, id) {
12
+ return `${kind}-${id.replace(/[^A-Za-z0-9_-]/g, (c) => `_${c.charCodeAt(0).toString(16)}`)}`;
13
+ }
14
+ function processAnchor(p) {
15
+ return anchor("process", p.id);
16
+ }
17
+ // Print-first: the document is read on paper or as a PDF as often as on screen.
18
+ // Colours follow the bpmnkit design-system tokens, with fallbacks so the file
19
+ // stands alone — nothing is loaded from the network.
20
+ const CSS = `
21
+ :root {
22
+ --doc-ink: var(--bpmnkit-ds-ink, #14161a);
23
+ --doc-ink-2: var(--bpmnkit-ds-ink-3, #4a5058);
24
+ --doc-line: var(--bpmnkit-ds-line, #d9dbdf);
25
+ --doc-line-soft: var(--bpmnkit-ds-line-soft, #eceef1);
26
+ --doc-ground: var(--bpmnkit-ds-surface, #ffffff);
27
+ --doc-accent: var(--bpmnkit-ds-accent, #a8503a);
28
+ --doc-sans: var(--bpmnkit-ds-font-sans, system-ui, -apple-system, "Segoe UI", sans-serif);
29
+ --doc-mono: var(--bpmnkit-ds-font-mono, ui-monospace, "SFMono-Regular", Menlo, Consolas, monospace);
30
+ }
31
+ * { box-sizing: border-box; }
32
+ html { background: var(--doc-ground); color: var(--doc-ink); }
33
+ body { margin: 0 auto; max-width: 980px; padding: 40px 32px 64px; font: 14px/1.55 var(--doc-sans); }
34
+ h1, h2, h3, h4 { line-height: 1.25; margin: 0; font-weight: 600; }
35
+ h1 { font-size: 30px; margin-bottom: 6px; }
36
+ h2 { font-size: 21px; padding-top: 30px; margin-bottom: 12px; border-bottom: 1px solid var(--doc-line); padding-bottom: 6px; }
37
+ h3 { font-size: 16px; margin: 22px 0 8px; }
38
+ h4 { font-size: 14px; }
39
+ p { margin: 0 0 10px; }
40
+ a { color: var(--doc-accent); }
41
+ code, .mono { font-family: var(--doc-mono); font-size: 12px; }
42
+ .eyebrow { font-family: var(--doc-mono); font-size: 11px; letter-spacing: 0.12em; text-transform: uppercase; color: var(--doc-ink-2); }
43
+ .subtitle { color: var(--doc-ink-2); margin-bottom: 18px; }
44
+ .prose { white-space: pre-wrap; }
45
+ .print-hint { border: 1px solid var(--doc-line); padding: 8px 12px; margin: 0 0 24px; font-size: 12.5px; color: var(--doc-ink-2); }
46
+ nav.toc ol { margin: 0; padding-left: 20px; }
47
+ nav.toc li { margin: 2px 0; }
48
+ .diagram { border: 1px solid var(--doc-line); padding: 8px; margin: 8px 0 0; overflow: auto; }
49
+ .diagram svg { display: block; max-width: 100%; height: auto; margin: 0 auto; }
50
+ table { border-collapse: collapse; width: 100%; margin: 6px 0 14px; font-size: 13px; }
51
+ th, td { border: 1px solid var(--doc-line); padding: 5px 8px; text-align: left; vertical-align: top; }
52
+ th { font-family: var(--doc-mono); font-size: 10.5px; letter-spacing: 0.08em; text-transform: uppercase; font-weight: 500; color: var(--doc-ink-2); background: var(--doc-line-soft); }
53
+ td.num, th.num { width: 1%; white-space: nowrap; font-family: var(--doc-mono); font-size: 12px; }
54
+ td ul { margin: 0; padding-left: 16px; }
55
+ .element { border: 1px solid var(--doc-line); margin: 0 0 -1px; padding: 12px 14px; }
56
+ .element header { display: flex; gap: 10px; align-items: baseline; flex-wrap: wrap; margin-bottom: 6px; }
57
+ .element .num { font-family: var(--doc-mono); font-size: 12px; color: var(--doc-accent); }
58
+ .element .type { font-family: var(--doc-mono); font-size: 11px; letter-spacing: 0.06em; text-transform: uppercase; color: var(--doc-ink-2); }
59
+ .element dl { display: grid; grid-template-columns: max-content 1fr; gap: 3px 16px; margin: 6px 0 0; }
60
+ .element dt { color: var(--doc-ink-2); }
61
+ .element dd { margin: 0; word-break: break-word; }
62
+ .element dd ul { margin: 0; padding-left: 16px; }
63
+ .depth-1 { margin-left: 18px; } .depth-2 { margin-left: 36px; } .depth-3 { margin-left: 54px; }
64
+ .muted { color: var(--doc-ink-2); }
65
+ @page { size: auto; margin: 16mm 14mm; }
66
+ @page diagram { size: landscape; margin: 12mm; }
67
+ @media print {
68
+ html, body { background: #fff; }
69
+ body { max-width: none; padding: 0; font-size: 10.5pt; }
70
+ .print-hint { display: none; }
71
+ a { color: inherit; text-decoration: none; }
72
+ h2 { break-after: avoid; }
73
+ h3, h4 { break-after: avoid; }
74
+ section.process, section.decisions, section.forms, section.messages { break-before: page; }
75
+ section.diagram-page { page: diagram; break-before: page; }
76
+ .diagram { border: 0; padding: 0; overflow: visible; }
77
+ .diagram svg { max-height: 170mm; width: 100%; }
78
+ .element, tr, .diagram { break-inside: avoid; }
79
+ thead { display: table-header-group; }
80
+ }
81
+ `;
82
+ function valueHtml(p) {
83
+ const render = (v) => v.startsWith("=") ? `<code>${escapeHtml(v)}</code>` : escapeHtml(v);
84
+ if (Array.isArray(p.value)) {
85
+ if (p.value.length === 1)
86
+ return render(p.value[0] ?? "");
87
+ return `<ul>${p.value.map((v) => `<li>${render(v)}</li>`).join("")}</ul>`;
88
+ }
89
+ if (p.link)
90
+ return `<a href="#${anchor(p.link.kind, p.link.id)}">${escapeHtml(p.value)}</a>`;
91
+ return render(p.value);
92
+ }
93
+ function elementHtml(el) {
94
+ const title = el.name ?? el.id;
95
+ const lines = [
96
+ `<article class="element depth-${Math.min(el.depth, 3)}" id="${anchor("el", el.id)}">`,
97
+ `<header><span class="num">${escapeHtml(el.number)}</span><h4>${escapeHtml(title)}</h4><span class="type">${escapeHtml(el.typeLabel)}</span></header>`,
98
+ ];
99
+ if (el.documentation)
100
+ lines.push(`<p class="prose">${escapeHtml(el.documentation)}</p>`);
101
+ const rows = [];
102
+ if (el.lane)
103
+ rows.push(`<dt>Lane</dt><dd>${escapeHtml(el.lane)}</dd>`);
104
+ for (const p of el.properties)
105
+ rows.push(`<dt>${escapeHtml(p.label)}</dt><dd>${valueHtml(p)}</dd>`);
106
+ rows.push(`<dt>ID</dt><dd class="mono">${escapeHtml(el.id)}</dd>`);
107
+ lines.push(`<dl>${rows.join("")}</dl>`, "</article>");
108
+ return lines.join("\n");
109
+ }
110
+ function processHtml(p) {
111
+ const out = [`<section class="process" id="${processAnchor(p)}">`];
112
+ out.push(`<h2>${escapeHtml(p.title)}</h2>`);
113
+ const meta = [`Process ID <code>${escapeHtml(p.id)}</code>`];
114
+ if (p.participant)
115
+ meta.push("drawn as a pool");
116
+ meta.push(p.executable ? "executable" : "not executable");
117
+ out.push(`<p class="muted">${meta.join(" · ")}</p>`);
118
+ if (p.documentation)
119
+ out.push(`<p class="prose">${escapeHtml(p.documentation)}</p>`);
120
+ if (p.lanes.length > 0) {
121
+ out.push(`<h3 id="${processAnchor(p)}-lanes">Lanes and performers</h3>`);
122
+ out.push("<table><thead><tr><th>Lane</th><th>Responsible for</th></tr></thead><tbody>");
123
+ for (const lane of p.lanes) {
124
+ const name = [...lane.path, lane.name].map(escapeHtml).join(" / ");
125
+ const doc = lane.documentation
126
+ ? `<div class="prose muted">${escapeHtml(lane.documentation)}</div>`
127
+ : "";
128
+ const els = lane.elements.length > 0 ? lane.elements.map(escapeHtml).join(", ") : "—";
129
+ out.push(`<tr><td>${name}${doc}</td><td>${els}</td></tr>`);
130
+ }
131
+ out.push("</tbody></table>");
132
+ }
133
+ if (p.elements.length > 0) {
134
+ out.push(`<h3 id="${processAnchor(p)}-summary">Steps at a glance</h3>`);
135
+ const laneCol = p.lanes.length > 0;
136
+ out.push(`<table><thead><tr><th class="num">#</th><th>Name</th><th>Type</th>${laneCol ? "<th>Lane</th>" : ""}</tr></thead><tbody>`);
137
+ for (const el of p.elements) {
138
+ const lane = laneCol ? `<td>${escapeHtml(el.lane ?? "")}</td>` : "";
139
+ out.push(`<tr><td class="num">${escapeHtml(el.number)}</td><td><a href="#${anchor("el", el.id)}">${escapeHtml(el.name ?? el.id)}</a></td><td>${escapeHtml(el.typeLabel)}</td>${lane}</tr>`);
140
+ }
141
+ out.push("</tbody></table>");
142
+ out.push(`<h3 id="${processAnchor(p)}-steps">Step details</h3>`);
143
+ for (const el of p.elements)
144
+ out.push(elementHtml(el));
145
+ }
146
+ else {
147
+ out.push(`<p class="muted">This process has no elements.</p>`);
148
+ }
149
+ out.push("</section>");
150
+ return out.join("\n");
151
+ }
152
+ function tocHtml(doc) {
153
+ const items = [];
154
+ if (doc.diagramSvg)
155
+ items.push(`<li><a href="#diagram">Diagram</a></li>`);
156
+ for (const p of doc.processes) {
157
+ const sub = [];
158
+ if (p.lanes.length > 0)
159
+ sub.push(`<li><a href="#${processAnchor(p)}-lanes">Lanes and performers</a></li>`);
160
+ if (p.elements.length > 0) {
161
+ sub.push(`<li><a href="#${processAnchor(p)}-summary">Steps at a glance</a></li>`);
162
+ sub.push(`<li><a href="#${processAnchor(p)}-steps">Step details</a></li>`);
163
+ }
164
+ items.push(`<li><a href="#${processAnchor(p)}">${escapeHtml(p.title)}</a>${sub.length > 0 ? `<ol>${sub.join("")}</ol>` : ""}</li>`);
165
+ }
166
+ if (doc.messageFlows.length > 0)
167
+ items.push(`<li><a href="#messages">Message flows</a></li>`);
168
+ if (doc.decisions.length > 0) {
169
+ const sub = doc.decisions
170
+ .map((d) => `<li><a href="#${anchor("decision", d.id)}">${escapeHtml(d.name)}</a></li>`)
171
+ .join("");
172
+ items.push(`<li><a href="#decisions">Decisions</a><ol>${sub}</ol></li>`);
173
+ }
174
+ if (doc.forms.length > 0) {
175
+ const sub = doc.forms
176
+ .map((f) => `<li><a href="#${anchor("form", f.id)}">${escapeHtml(f.id)}</a></li>`)
177
+ .join("");
178
+ items.push(`<li><a href="#forms">Forms</a><ol>${sub}</ol></li>`);
179
+ }
180
+ return `<nav class="toc"><h2 id="contents">Contents</h2><ol>${items.join("")}</ol></nav>`;
181
+ }
182
+ function messagesHtml(doc) {
183
+ if (doc.messageFlows.length === 0)
184
+ return "";
185
+ const rows = doc.messageFlows.map((m) => {
186
+ const name = m.name ?? m.message ?? "";
187
+ const doc = m.documentation
188
+ ? `<div class="prose muted">${escapeHtml(m.documentation)}</div>`
189
+ : "";
190
+ return `<tr><td>${escapeHtml(m.from)}</td><td>${escapeHtml(m.to)}</td><td>${escapeHtml(name)}${doc}</td></tr>`;
191
+ });
192
+ return [
193
+ `<section class="messages" id="messages"><h2>Message flows</h2>`,
194
+ "<table><thead><tr><th>From</th><th>To</th><th>Message</th></tr></thead><tbody>",
195
+ ...rows,
196
+ "</tbody></table></section>",
197
+ ].join("\n");
198
+ }
199
+ function decisionsHtml(doc) {
200
+ if (doc.decisions.length === 0)
201
+ return "";
202
+ const out = [`<section class="decisions" id="decisions"><h2>Decisions</h2>`];
203
+ for (const d of doc.decisions) {
204
+ out.push(`<h3 id="${anchor("decision", d.id)}">${escapeHtml(d.name)}</h3>`);
205
+ const meta = [
206
+ `Decision ID <code>${escapeHtml(d.id)}</code>`,
207
+ `hit policy ${escapeHtml(d.hitPolicy)}`,
208
+ ];
209
+ if (d.calledBy.length > 0)
210
+ meta.push(`called by ${d.calledBy.map(escapeHtml).join(", ")}`);
211
+ out.push(`<p class="muted">${meta.join(" · ")}</p>`);
212
+ const head = [
213
+ `<th class="num">#</th>`,
214
+ ...d.inputs.map((i) => `<th>When: ${escapeHtml(i)}</th>`),
215
+ ...d.outputs.map((o) => `<th>Then: ${escapeHtml(o)}</th>`),
216
+ "<th>Note</th>",
217
+ ].join("");
218
+ out.push(`<table><thead><tr>${head}</tr></thead><tbody>`);
219
+ d.rules.forEach((r, i) => {
220
+ const cells = r
221
+ .map((c, j) => j < r.length - 1 ? `<td><code>${escapeHtml(c)}</code></td>` : `<td>${escapeHtml(c)}</td>`)
222
+ .join("");
223
+ out.push(`<tr><td class="num">${i + 1}</td>${cells}</tr>`);
224
+ });
225
+ out.push("</tbody></table>");
226
+ }
227
+ out.push("</section>");
228
+ return out.join("\n");
229
+ }
230
+ function formsHtml(doc) {
231
+ if (doc.forms.length === 0)
232
+ return "";
233
+ const out = [`<section class="forms" id="forms"><h2>Forms</h2>`];
234
+ for (const f of doc.forms) {
235
+ out.push(`<h3 id="${anchor("form", f.id)}">${escapeHtml(f.id)}</h3>`);
236
+ if (f.usedBy.length > 0)
237
+ out.push(`<p class="muted">Shown by ${f.usedBy.map(escapeHtml).join(", ")}</p>`);
238
+ if (f.fields.length === 0) {
239
+ out.push(`<p class="muted">This form has no input fields.</p>`);
240
+ continue;
241
+ }
242
+ out.push("<table><thead><tr><th>Field</th><th>Variable</th><th>Type</th><th>Required</th><th>Options</th></tr></thead><tbody>");
243
+ for (const field of f.fields) {
244
+ out.push(`<tr><td>${escapeHtml(field.label)}</td><td><code>${escapeHtml(field.key)}</code></td><td>${escapeHtml(field.type)}</td><td>${field.required ? "Yes" : "No"}</td><td>${escapeHtml(field.options)}</td></tr>`);
245
+ }
246
+ out.push("</tbody></table>");
247
+ }
248
+ out.push("</section>");
249
+ return out.join("\n");
250
+ }
251
+ /** Renders already-built documentation as a standalone HTML document. */
252
+ export function documentationToHtml(doc) {
253
+ const body = [
254
+ `<header><div class="eyebrow">Process documentation</div><h1>${escapeHtml(doc.title)}</h1>`,
255
+ ];
256
+ if (doc.subtitle)
257
+ body.push(`<p class="subtitle">${escapeHtml(doc.subtitle)}</p>`);
258
+ body.push("</header>");
259
+ body.push(`<p class="print-hint">To save this document as a PDF, use your browser's Print command and choose “Save as PDF”. A4 and Letter both work.</p>`);
260
+ if (doc.documentation)
261
+ body.push(`<p class="prose">${escapeHtml(doc.documentation)}</p>`);
262
+ body.push(tocHtml(doc));
263
+ if (doc.diagramSvg) {
264
+ body.push(`<section class="diagram-page"><h2 id="diagram">Diagram</h2><figure class="diagram">${doc.diagramSvg}</figure></section>`);
265
+ }
266
+ for (const p of doc.processes)
267
+ body.push(processHtml(p));
268
+ body.push(messagesHtml(doc), decisionsHtml(doc), formsHtml(doc));
269
+ return [
270
+ "<!DOCTYPE html>",
271
+ `<html lang="en">`,
272
+ "<head>",
273
+ `<meta charset="utf-8">`,
274
+ `<meta name="viewport" content="width=device-width, initial-scale=1">`,
275
+ `<meta name="generator" content="bpmnkit">`,
276
+ `<title>${escapeHtml(doc.title)} — process documentation</title>`,
277
+ `<style>${CSS}</style>`,
278
+ "</head>",
279
+ "<body>",
280
+ ...body.filter((s) => s !== ""),
281
+ "</body>",
282
+ "</html>",
283
+ "",
284
+ ].join("\n");
285
+ }
286
+ /**
287
+ * Renders a BPMN model as a self-contained, print-ready HTML document: the
288
+ * diagram as inline SVG, a table of contents, one section per process or pool
289
+ * with its lanes and every element in flow order, then any message flows,
290
+ * decision tables and forms. No scripts, no network requests. The browser's
291
+ * Print → Save as PDF gives a paginated PDF on A4 or Letter.
292
+ *
293
+ * @example
294
+ * ```typescript
295
+ * import { Bpmn, renderDocumentationHtml } from "@bpmnkit/core"
296
+ *
297
+ * const html = renderDocumentationHtml(Bpmn.parse(xml), { title: "Order to Cash" })
298
+ * ```
299
+ */
300
+ export function renderDocumentationHtml(defs, options) {
301
+ return documentationToHtml(buildProcessDocumentation(defs, options));
302
+ }
303
+ //# sourceMappingURL=html.js.map
@@ -0,0 +1,7 @@
1
+ export { buildProcessDocumentation } from "./model.js";
2
+ export type { DocumentationLink, DocumentationOptions, DocumentedDecision, DocumentedElement, DocumentedForm, DocumentedFormField, DocumentedLane, DocumentedMessageFlow, DocumentedProcess, DocumentedProperty, ProcessDocumentation, } from "./model.js";
3
+ export { documentationToHtml, renderDocumentationHtml } from "./html.js";
4
+ export { documentationToMarkdown, renderDocumentationMarkdown } from "./markdown.js";
5
+ export { documentationToDocx, renderDocumentationDocx } from "./docx.js";
6
+ export type { DocxDocumentationOptions } from "./docx.js";
7
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,5 @@
1
+ export { buildProcessDocumentation } from "./model.js";
2
+ export { documentationToHtml, renderDocumentationHtml } from "./html.js";
3
+ export { documentationToMarkdown, renderDocumentationMarkdown } from "./markdown.js";
4
+ export { documentationToDocx, renderDocumentationDocx } from "./docx.js";
5
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1,11 @@
1
+ import type { BpmnDefinitions } from "../bpmn/bpmn-model.js";
2
+ import { type DocumentationOptions, type ProcessDocumentation } from "./model.js";
3
+ /** Renders already-built documentation as Markdown (GitHub-flavoured tables). */
4
+ export declare function documentationToMarkdown(doc: ProcessDocumentation): string;
5
+ /**
6
+ * Renders a BPMN model as Markdown for wikis and Confluence imports: the same
7
+ * sections as {@link renderDocumentationHtml}, without the diagram (Markdown
8
+ * cannot carry an inline SVG portably — export it with `exportSvg` and link it).
9
+ */
10
+ export declare function renderDocumentationMarkdown(defs: BpmnDefinitions, options?: DocumentationOptions): string;
11
+ //# sourceMappingURL=markdown.d.ts.map
@@ -0,0 +1,160 @@
1
+ import { buildProcessDocumentation, } from "./model.js";
2
+ /**
3
+ * Escapes text for Markdown that wikis may render as HTML: markup characters
4
+ * become entities, Markdown syntax is backslash-escaped, and line starts that
5
+ * would open a heading, quote or list are neutralised.
6
+ */
7
+ function md(s) {
8
+ return s
9
+ .replace(/&/g, "&amp;")
10
+ .replace(/</g, "&lt;")
11
+ .replace(/>/g, "&gt;")
12
+ .replace(/[\\`*_[\]|~]/g, "\\$&")
13
+ .replace(/^(\s*)([#+-]|\d+\.)/gm, "$1\\$2");
14
+ }
15
+ /** A table cell: one line, pipes escaped. */
16
+ function cell(s) {
17
+ return md(s).replace(/\r?\n/g, "<br>");
18
+ }
19
+ function code(s) {
20
+ // A code span shows its content literally — renderers escape markup inside
21
+ // it themselves — so only what breaks the span or the table needs handling:
22
+ // backticks (longer fence) and pipes.
23
+ const body = s.replace(/\r?\n/g, " ").replace(/\|/g, "\\|");
24
+ const fence = body.includes("`") ? "``" : "`";
25
+ return `${fence}${fence.length > 1 ? " " : ""}${body}${fence.length > 1 ? " " : ""}${fence}`;
26
+ }
27
+ function prose(s) {
28
+ return s
29
+ .split(/\r?\n/)
30
+ .map((line) => md(line))
31
+ .join(" \n");
32
+ }
33
+ function value(v) {
34
+ return v.startsWith("=") ? code(v) : cell(v);
35
+ }
36
+ function propertyValue(p) {
37
+ return Array.isArray(p.value) ? p.value.map(value).join("<br>") : value(p.value);
38
+ }
39
+ function table(head, rows) {
40
+ return [
41
+ `| ${head.join(" | ")} |`,
42
+ `| ${head.map(() => "---").join(" | ")} |`,
43
+ ...rows.map((r) => `| ${r.join(" | ")} |`),
44
+ ];
45
+ }
46
+ function processMd(p) {
47
+ const out = [`## ${md(p.title)}`, ""];
48
+ const meta = [`Process ID ${code(p.id)}`];
49
+ if (p.participant)
50
+ meta.push("drawn as a pool");
51
+ meta.push(p.executable ? "executable" : "not executable");
52
+ out.push(meta.join(" · "), "");
53
+ if (p.documentation)
54
+ out.push(prose(p.documentation), "");
55
+ if (p.lanes.length > 0) {
56
+ out.push("### Lanes and performers", "");
57
+ out.push(...table(["Lane", "Responsible for"], p.lanes.map((l) => [
58
+ cell([...l.path, l.name].join(" / ")),
59
+ l.elements.length > 0 ? cell(l.elements.join(", ")) : "—",
60
+ ])), "");
61
+ }
62
+ if (p.elements.length === 0) {
63
+ out.push("_This process has no elements._", "");
64
+ return out;
65
+ }
66
+ const laneCol = p.lanes.length > 0;
67
+ out.push("### Steps at a glance", "");
68
+ out.push(...table(["#", "Name", "Type", ...(laneCol ? ["Lane"] : [])], p.elements.map((el) => [
69
+ el.number,
70
+ cell(el.name ?? el.id),
71
+ cell(el.typeLabel),
72
+ ...(laneCol ? [cell(el.lane ?? "")] : []),
73
+ ])), "");
74
+ out.push("### Step details", "");
75
+ for (const el of p.elements) {
76
+ out.push(`#### ${el.number} ${md(el.name ?? el.id)}`, "", `_${md(el.typeLabel)}_`, "");
77
+ if (el.documentation)
78
+ out.push(prose(el.documentation), "");
79
+ const rows = [];
80
+ if (el.lane)
81
+ rows.push(["Lane", cell(el.lane)]);
82
+ for (const prop of el.properties)
83
+ rows.push([cell(prop.label), propertyValue(prop)]);
84
+ rows.push(["ID", code(el.id)]);
85
+ out.push(...table(["Property", "Value"], rows), "");
86
+ }
87
+ return out;
88
+ }
89
+ /** Renders already-built documentation as Markdown (GitHub-flavoured tables). */
90
+ export function documentationToMarkdown(doc) {
91
+ const out = [`# ${md(doc.title)}`, ""];
92
+ if (doc.subtitle)
93
+ out.push(md(doc.subtitle), "");
94
+ if (doc.documentation)
95
+ out.push(prose(doc.documentation), "");
96
+ out.push("## Contents", "");
97
+ for (const p of doc.processes)
98
+ out.push(`- ${md(p.title)}`);
99
+ if (doc.messageFlows.length > 0)
100
+ out.push("- Message flows");
101
+ if (doc.decisions.length > 0)
102
+ out.push("- Decisions");
103
+ if (doc.forms.length > 0)
104
+ out.push("- Forms");
105
+ out.push("");
106
+ for (const p of doc.processes)
107
+ out.push(...processMd(p));
108
+ if (doc.messageFlows.length > 0) {
109
+ out.push("## Message flows", "");
110
+ out.push(...table(["From", "To", "Message"], doc.messageFlows.map((m) => [cell(m.from), cell(m.to), cell(m.name ?? m.message ?? "")])), "");
111
+ }
112
+ if (doc.decisions.length > 0) {
113
+ out.push("## Decisions", "");
114
+ for (const d of doc.decisions) {
115
+ out.push(`### ${md(d.name)}`, "");
116
+ const meta = [`Decision ID ${code(d.id)}`, `hit policy ${md(d.hitPolicy)}`];
117
+ if (d.calledBy.length > 0)
118
+ meta.push(`called by ${md(d.calledBy.join(", "))}`);
119
+ out.push(meta.join(" · "), "");
120
+ out.push(...table([
121
+ "#",
122
+ ...d.inputs.map((i) => `When: ${cell(i)}`),
123
+ ...d.outputs.map((o) => `Then: ${cell(o)}`),
124
+ "Note",
125
+ ], d.rules.map((r, i) => [
126
+ String(i + 1),
127
+ ...r.map((c, j) => (j < r.length - 1 ? code(c) : cell(c))),
128
+ ])), "");
129
+ }
130
+ }
131
+ if (doc.forms.length > 0) {
132
+ out.push("## Forms", "");
133
+ for (const f of doc.forms) {
134
+ out.push(`### ${md(f.id)}`, "");
135
+ if (f.usedBy.length > 0)
136
+ out.push(`Shown by ${md(f.usedBy.join(", "))}`, "");
137
+ if (f.fields.length === 0) {
138
+ out.push("_This form has no input fields._", "");
139
+ continue;
140
+ }
141
+ out.push(...table(["Field", "Variable", "Type", "Required", "Options"], f.fields.map((field) => [
142
+ cell(field.label),
143
+ code(field.key),
144
+ cell(field.type),
145
+ field.required ? "Yes" : "No",
146
+ cell(field.options),
147
+ ])), "");
148
+ }
149
+ }
150
+ return `${out.join("\n").trimEnd()}\n`;
151
+ }
152
+ /**
153
+ * Renders a BPMN model as Markdown for wikis and Confluence imports: the same
154
+ * sections as {@link renderDocumentationHtml}, without the diagram (Markdown
155
+ * cannot carry an inline SVG portably — export it with `exportSvg` and link it).
156
+ */
157
+ export function renderDocumentationMarkdown(defs, options) {
158
+ return documentationToMarkdown(buildProcessDocumentation(defs, { ...options, diagram: false }));
159
+ }
160
+ //# sourceMappingURL=markdown.js.map
@@ -0,0 +1,129 @@
1
+ import type { BpmnDefinitions, BpmnFlowElement } from "../bpmn/bpmn-model.js";
2
+ import type { DmnDefinitions } from "../dmn/dmn-model.js";
3
+ import type { FormDefinition } from "../form/form-model.js";
4
+ /** Options shared by every process documentation renderer. */
5
+ export interface DocumentationOptions {
6
+ /** Document title. Defaults to the first pool / process name, then the definitions id. */
7
+ title?: string;
8
+ /** DMN models whose decision tables are documented after the processes. */
9
+ decisions?: DmnDefinitions[];
10
+ /** Camunda forms whose fields are documented after the processes. */
11
+ forms?: FormDefinition[];
12
+ /** Include the diagram as an SVG image. Default `true`. Needs diagram interchange (DI) data. */
13
+ diagram?: boolean;
14
+ /**
15
+ * A line printed under the title, e.g. a version or a date. Nothing is added
16
+ * by default, so the same model always produces byte-identical output.
17
+ */
18
+ subtitle?: string;
19
+ }
20
+ /** A reference from an element to a decision or form documented in the same document. */
21
+ export interface DocumentationLink {
22
+ kind: "decision" | "form";
23
+ id: string;
24
+ }
25
+ /** One labelled fact about an element, e.g. `Job type: payment-charge`. */
26
+ export interface DocumentedProperty {
27
+ label: string;
28
+ /** One value, or several (rendered as a list). */
29
+ value: string | string[];
30
+ /** Set when the value names a decision or form included in the document. */
31
+ link?: DocumentationLink;
32
+ }
33
+ /** A flow element, in flow order, with everything a reader needs to know about it. */
34
+ export interface DocumentedElement {
35
+ id: string;
36
+ name?: string;
37
+ /** The BPMN element type, e.g. `serviceTask`. */
38
+ type: BpmnFlowElement["type"];
39
+ /** Readable type, e.g. `Timer start event` or `Error boundary event (non-interrupting)`. */
40
+ typeLabel: string;
41
+ /** Outline number: `3`, or `3.2` for the second element inside element 3. */
42
+ number: string;
43
+ /** Nesting depth: 0 for a process-level element, 1 inside a sub-process, and so on. */
44
+ depth: number;
45
+ /** The lane (performer) the element sits in, if the process has lanes. */
46
+ lane?: string;
47
+ documentation?: string;
48
+ properties: DocumentedProperty[];
49
+ }
50
+ /** A lane (performer) and the elements it owns. */
51
+ export interface DocumentedLane {
52
+ id: string;
53
+ name: string;
54
+ /** Parent lane names, outermost first, for nested lanes. */
55
+ path: string[];
56
+ documentation?: string;
57
+ /** Names (or ids) of the lane's elements, in flow order. */
58
+ elements: string[];
59
+ }
60
+ /** One process, or the process behind one pool. */
61
+ export interface DocumentedProcess {
62
+ id: string;
63
+ /** Pool name, process name or id, in that order. */
64
+ title: string;
65
+ /** The pool (participant) name, when the process is drawn as a pool. */
66
+ participant?: string;
67
+ documentation?: string;
68
+ executable: boolean;
69
+ lanes: DocumentedLane[];
70
+ elements: DocumentedElement[];
71
+ }
72
+ /** A message flow between pools. */
73
+ export interface DocumentedMessageFlow {
74
+ id: string;
75
+ name?: string;
76
+ from: string;
77
+ to: string;
78
+ message?: string;
79
+ documentation?: string;
80
+ }
81
+ /** A DMN decision table. */
82
+ export interface DocumentedDecision {
83
+ id: string;
84
+ name: string;
85
+ hitPolicy: string;
86
+ inputs: string[];
87
+ outputs: string[];
88
+ /** One row per rule: input entries, then output entries, then the annotation. */
89
+ rules: string[][];
90
+ /** Names of the elements that call this decision. */
91
+ calledBy: string[];
92
+ }
93
+ /** A form field. Group and dynamic-list children are flattened, their label path joined by ` / `. */
94
+ export interface DocumentedFormField {
95
+ label: string;
96
+ key: string;
97
+ type: string;
98
+ required: boolean;
99
+ /** Selectable values, or the expression / key they come from. */
100
+ options: string;
101
+ }
102
+ /** A Camunda form. */
103
+ export interface DocumentedForm {
104
+ id: string;
105
+ fields: DocumentedFormField[];
106
+ /** Names of the user tasks and start events that show this form. */
107
+ usedBy: string[];
108
+ }
109
+ /** The documentation of one BPMN model, ready for a renderer. */
110
+ export interface ProcessDocumentation {
111
+ title: string;
112
+ subtitle?: string;
113
+ documentation?: string;
114
+ /** The diagram as SVG, or undefined when disabled or when the model has no DI. */
115
+ diagramSvg?: string;
116
+ processes: DocumentedProcess[];
117
+ messageFlows: DocumentedMessageFlow[];
118
+ decisions: DocumentedDecision[];
119
+ forms: DocumentedForm[];
120
+ }
121
+ /** `PT48H` → `48 hours`. Returns undefined for anything that is not a plain ISO duration. */
122
+ export declare function humanizeDuration(value: string): string | undefined;
123
+ /**
124
+ * Collects everything a process document needs from a parsed model, in flow
125
+ * order. The HTML, Markdown and Word renderers all draw from this, so a custom
126
+ * renderer can too.
127
+ */
128
+ export declare function buildProcessDocumentation(defs: BpmnDefinitions, options?: DocumentationOptions): ProcessDocumentation;
129
+ //# sourceMappingURL=model.d.ts.map