@bpmnkit/core 1.0.0 → 1.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.
Files changed (64) hide show
  1. package/README.md +25 -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/full-operations.js +5 -2
  21. package/dist/bpmn/label-style.d.ts +51 -0
  22. package/dist/bpmn/label-style.js +116 -0
  23. package/dist/bpmn/lint.d.ts +23 -3
  24. package/dist/bpmn/lint.js +47 -10
  25. package/dist/bpmn/optimize/bpmnlint-rules.d.ts +31 -0
  26. package/dist/bpmn/optimize/bpmnlint-rules.js +916 -0
  27. package/dist/bpmn/optimize/deploy.d.ts +8 -2
  28. package/dist/bpmn/optimize/deploy.js +16 -3
  29. package/dist/bpmn/optimize/index.js +11 -2
  30. package/dist/bpmn/optimize/types.d.ts +14 -0
  31. package/dist/bpmn/optimize/variable-flow.js +4 -1
  32. package/dist/bpmn/process-types.d.ts +112 -0
  33. package/dist/bpmn/process-types.js +490 -0
  34. package/dist/bpmn/svg.js +51 -22
  35. package/dist/doc/docx.d.ts +20 -0
  36. package/dist/doc/docx.js +253 -0
  37. package/dist/doc/html.d.ts +21 -0
  38. package/dist/doc/html.js +303 -0
  39. package/dist/doc/index.d.ts +7 -0
  40. package/dist/doc/index.js +5 -0
  41. package/dist/doc/markdown.d.ts +11 -0
  42. package/dist/doc/markdown.js +160 -0
  43. package/dist/doc/model.d.ts +129 -0
  44. package/dist/doc/model.js +617 -0
  45. package/dist/doc/zip.d.ts +5 -0
  46. package/dist/doc/zip.js +75 -0
  47. package/dist/index.d.ts +16 -0
  48. package/dist/index.js +8 -0
  49. package/dist/layout/annotations.d.ts +4 -2
  50. package/dist/layout/annotations.js +31 -2
  51. package/dist/layout/collaboration/ordering.d.ts +8 -0
  52. package/dist/layout/collaboration/ordering.js +57 -18
  53. package/dist/layout/orthogonal.d.ts +32 -0
  54. package/dist/layout/orthogonal.js +367 -0
  55. package/dist/layout/repair.d.ts +31 -0
  56. package/dist/layout/repair.js +220 -0
  57. package/dist/layout/semantic/route.js +45 -3
  58. package/dist/node/bpmnlint.d.ts +109 -0
  59. package/dist/node/bpmnlint.js +198 -0
  60. package/dist/node/index.d.ts +2 -0
  61. package/dist/node/index.js +1 -0
  62. package/dist/xml/xml-patch.d.ts +21 -0
  63. package/dist/xml/xml-patch.js +27 -1
  64. package/package.json +2 -2
@@ -0,0 +1,20 @@
1
+ import type { BpmnDefinitions } from "../bpmn/bpmn-model.js";
2
+ import { type DocumentationOptions, type ProcessDocumentation } from "./model.js";
3
+ /** Options for {@link renderDocumentationDocx}. */
4
+ export interface DocxDocumentationOptions extends DocumentationOptions {
5
+ /** Page size. Default `"a4"`. */
6
+ paper?: "a4" | "letter";
7
+ }
8
+ /** Renders already-built documentation as the bytes of a Word (.docx) file. */
9
+ export declare function documentationToDocx(doc: ProcessDocumentation, paper?: "a4" | "letter"): Uint8Array;
10
+ /**
11
+ * Renders a BPMN model as a Word document (.docx) with the same sections as
12
+ * {@link renderDocumentationHtml}. Headings use Word's built-in heading styles,
13
+ * so the navigation pane and an inserted table of contents pick them up. The
14
+ * diagram is embedded as SVG on a landscape page, with no bitmap fallback:
15
+ * readers without SVG support (Word before 2019) show no image.
16
+ *
17
+ * Returns the file's bytes: write them to disk or wrap them in a `Blob`.
18
+ */
19
+ export declare function renderDocumentationDocx(defs: BpmnDefinitions, options?: DocxDocumentationOptions): Uint8Array;
20
+ //# sourceMappingURL=docx.d.ts.map
@@ -0,0 +1,253 @@
1
+ import { buildProcessDocumentation, } from "./model.js";
2
+ import { zipStore } from "./zip.js";
3
+ // Page sizes in twentieths of a point (twips).
4
+ const PAPER = {
5
+ a4: { w: 11906, h: 16838 },
6
+ letter: { w: 12240, h: 15840 },
7
+ };
8
+ const MARGIN = 1134; // 20 mm
9
+ const EMU_PER_TWIP = 635;
10
+ const W_NS = 'xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing" xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture"';
11
+ // biome-ignore lint/suspicious/noControlCharactersInRegex: matching them is the point — Word rejects a file that contains them.
12
+ const XML_FORBIDDEN = /[\u0000-\u0008\u000b\u000c\u000e-\u001f]/g;
13
+ /** XML-escapes text and drops the control characters XML 1.0 cannot carry. */
14
+ function x(s) {
15
+ return s
16
+ .replace(XML_FORBIDDEN, "")
17
+ .replace(/&/g, "&")
18
+ .replace(/</g, "&lt;")
19
+ .replace(/>/g, "&gt;")
20
+ .replace(/"/g, "&quot;");
21
+ }
22
+ function run(text, style = {}) {
23
+ const props = [];
24
+ if (style.bold)
25
+ props.push("<w:b/>");
26
+ if (style.italic)
27
+ props.push("<w:i/>");
28
+ if (style.mono)
29
+ props.push('<w:rFonts w:ascii="Consolas" w:hAnsi="Consolas" w:cs="Consolas"/>');
30
+ if (style.muted)
31
+ props.push('<w:color w:val="4A5058"/>');
32
+ const rPr = props.length > 0 ? `<w:rPr>${props.join("")}</w:rPr>` : "";
33
+ const lines = text.split(/\r?\n/);
34
+ const body = lines
35
+ .map((l, i) => `${i > 0 ? "<w:br/>" : ""}<w:t xml:space="preserve">${x(l)}</w:t>`)
36
+ .join("");
37
+ return `<w:r>${rPr}${body}</w:r>`;
38
+ }
39
+ function para(content, style, keepNext = false) {
40
+ const pPr = [];
41
+ if (style)
42
+ pPr.push(`<w:pStyle w:val="${style}"/>`);
43
+ if (keepNext)
44
+ pPr.push("<w:keepNext/>");
45
+ return `<w:p>${pPr.length > 0 ? `<w:pPr>${pPr.join("")}</w:pPr>` : ""}${content}</w:p>`;
46
+ }
47
+ function text(s, style, runStyle) {
48
+ return para(run(s, runStyle), style);
49
+ }
50
+ function tableXml(head, rows, widths) {
51
+ const borders = ["top", "left", "bottom", "right", "insideH", "insideV"]
52
+ .map((b) => `<w:${b} w:val="single" w:sz="4" w:space="0" w:color="D9DBDF"/>`)
53
+ .join("");
54
+ const grid = widths
55
+ ? `<w:tblGrid>${widths.map((w) => `<w:gridCol w:w="${w}"/>`).join("")}</w:tblGrid>`
56
+ : "";
57
+ const cellXml = (content, header, i) => {
58
+ const width = widths?.[i] ? `<w:tcW w:w="${widths[i]}" w:type="dxa"/>` : "";
59
+ const shade = header ? '<w:shd w:val="clear" w:color="auto" w:fill="ECEEF1"/>' : "";
60
+ // Several values in one cell become one paragraph each.
61
+ const lines = Array.isArray(content) ? content : [content];
62
+ const paras = lines.map((l) => para(run(l, header ? { bold: true } : {}), "TableText")).join("");
63
+ return `<w:tc><w:tcPr>${width}${shade}</w:tcPr>${paras}</w:tc>`;
64
+ };
65
+ const headRow = `<w:tr><w:trPr><w:tblHeader/><w:cantSplit/></w:trPr>${head.map((h, i) => cellXml(h, true, i)).join("")}</w:tr>`;
66
+ const bodyRows = rows
67
+ .map((r) => `<w:tr><w:trPr><w:cantSplit/></w:trPr>${r.map((c, i) => cellXml(c, false, i)).join("")}</w:tr>`)
68
+ .join("");
69
+ return `<w:tbl><w:tblPr><w:tblW w:w="5000" w:type="pct"/><w:tblBorders>${borders}</w:tblBorders><w:tblCellMar><w:left w:w="80" w:type="dxa"/><w:right w:w="80" w:type="dxa"/></w:tblCellMar></w:tblPr>${grid}${headRow}${bodyRows}</w:tbl>${para("")}`;
70
+ }
71
+ function sectPr(paper, landscape) {
72
+ const size = landscape
73
+ ? `<w:pgSz w:w="${paper.h}" w:h="${paper.w}" w:orient="landscape"/>`
74
+ : `<w:pgSz w:w="${paper.w}" w:h="${paper.h}"/>`;
75
+ return `<w:sectPr>${size}<w:pgMar w:top="${MARGIN}" w:right="${MARGIN}" w:bottom="${MARGIN}" w:left="${MARGIN}" w:header="708" w:footer="708" w:gutter="0"/></w:sectPr>`;
76
+ }
77
+ function diagramXml(svg, paper) {
78
+ const w = Number(/\bwidth="([\d.]+)"/.exec(svg)?.[1] ?? 0);
79
+ const h = Number(/\bheight="([\d.]+)"/.exec(svg)?.[1] ?? 0);
80
+ if (!(w > 0 && h > 0))
81
+ return "";
82
+ // Landscape page, less margins and room for the heading.
83
+ const maxW = (paper.h - 2 * MARGIN) * EMU_PER_TWIP;
84
+ const maxH = (paper.w - 2 * MARGIN - 1200) * EMU_PER_TWIP;
85
+ const px = 9525; // EMU per CSS pixel
86
+ const scale = Math.min(1, maxW / (w * px), maxH / (h * px));
87
+ const cx = Math.round(w * px * scale);
88
+ const cy = Math.round(h * px * scale);
89
+ // The SVG is referenced from both the plain blip and the Office SVG
90
+ // extension (the one Word writes itself). The spec wants a bitmap in the
91
+ // plain blip as a fallback for readers without SVG support; rasterising
92
+ // needs a canvas this package does not have, so those readers get no image.
93
+ const blip = `<a:blip r:embed="rIdDiagram"><a:extLst><a:ext uri="{96DAC541-7B7A-43D3-8B79-37D633B846F1}"><asvg:svgBlip xmlns:asvg="http://schemas.microsoft.com/office/drawing/2016/SVG/main" r:embed="rIdDiagram"/></a:ext></a:extLst></a:blip>`;
94
+ return para(`<w:r><w:drawing><wp:inline distT="0" distB="0" distL="0" distR="0"><wp:extent cx="${cx}" cy="${cy}"/><wp:docPr id="1" name="Diagram"/><a:graphic><a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/picture"><pic:pic><pic:nvPicPr><pic:cNvPr id="1" name="diagram.svg"/><pic:cNvPicPr/></pic:nvPicPr><pic:blipFill>${blip}<a:stretch><a:fillRect/></a:stretch></pic:blipFill><pic:spPr><a:xfrm><a:off x="0" y="0"/><a:ext cx="${cx}" cy="${cy}"/></a:xfrm><a:prstGeom prst="rect"><a:avLst/></a:prstGeom></pic:spPr></pic:pic></a:graphicData></a:graphic></wp:inline></w:drawing></w:r>`);
95
+ }
96
+ function processXml(p) {
97
+ const out = [text(p.title, "Heading1")];
98
+ const meta = [`Process ID ${p.id}`];
99
+ if (p.participant)
100
+ meta.push("drawn as a pool");
101
+ meta.push(p.executable ? "executable" : "not executable");
102
+ out.push(text(meta.join(" · "), undefined, { muted: true }));
103
+ if (p.documentation)
104
+ out.push(text(p.documentation));
105
+ if (p.lanes.length > 0) {
106
+ out.push(text("Lanes and performers", "Heading2"));
107
+ out.push(tableXml(["Lane", "Responsible for"], p.lanes.map((l) => [[...l.path, l.name].join(" / "), l.elements.join(", ") || "—"])));
108
+ }
109
+ if (p.elements.length === 0) {
110
+ out.push(text("This process has no elements.", undefined, { italic: true }));
111
+ return out;
112
+ }
113
+ const laneCol = p.lanes.length > 0;
114
+ out.push(text("Steps at a glance", "Heading2"));
115
+ out.push(tableXml(["#", "Name", "Type", ...(laneCol ? ["Lane"] : [])], p.elements.map((el) => [
116
+ el.number,
117
+ el.name ?? el.id,
118
+ el.typeLabel,
119
+ ...(laneCol ? [el.lane ?? ""] : []),
120
+ ]), laneCol ? [900, 3600, 2700, 2400] : [900, 4800, 3900]));
121
+ out.push(text("Step details", "Heading2"));
122
+ for (const el of p.elements) {
123
+ out.push(text(`${el.number} ${el.name ?? el.id}`, "Heading3"));
124
+ out.push(para(run(el.typeLabel, { italic: true, muted: true }), undefined, true));
125
+ if (el.documentation)
126
+ out.push(para(run(el.documentation), undefined, true));
127
+ const rows = [];
128
+ if (el.lane)
129
+ rows.push(["Lane", el.lane]);
130
+ for (const prop of el.properties)
131
+ rows.push([prop.label, prop.value]);
132
+ rows.push(["ID", el.id]);
133
+ out.push(tableXml(["Property", "Value"], rows, [2600, 7000]));
134
+ }
135
+ return out;
136
+ }
137
+ function documentXml(doc, paper) {
138
+ const body = [
139
+ text("PROCESS DOCUMENTATION", undefined, { muted: true }),
140
+ text(doc.title, "Title"),
141
+ ];
142
+ if (doc.subtitle)
143
+ body.push(text(doc.subtitle, undefined, { muted: true }));
144
+ if (doc.documentation)
145
+ body.push(text(doc.documentation));
146
+ const diagram = doc.diagramSvg ? diagramXml(doc.diagramSvg, paper) : "";
147
+ if (diagram) {
148
+ // The diagram gets a landscape section of its own; everything else is portrait.
149
+ body.push(`<w:p><w:pPr>${sectPr(paper, false)}</w:pPr></w:p>`);
150
+ body.push(text("Diagram", "Heading1"), diagram);
151
+ body.push(`<w:p><w:pPr>${sectPr(paper, true)}</w:pPr></w:p>`);
152
+ }
153
+ doc.processes.forEach((p, i) => {
154
+ if (i > 0 || !diagram)
155
+ body.push(para('<w:r><w:br w:type="page"/></w:r>'));
156
+ body.push(...processXml(p));
157
+ });
158
+ if (doc.messageFlows.length > 0) {
159
+ body.push(text("Message flows", "Heading1"));
160
+ body.push(tableXml(["From", "To", "Message"], doc.messageFlows.map((m) => [m.from, m.to, m.name ?? m.message ?? ""])));
161
+ }
162
+ if (doc.decisions.length > 0) {
163
+ body.push(text("Decisions", "Heading1"));
164
+ for (const d of doc.decisions) {
165
+ body.push(text(d.name, "Heading2"));
166
+ const meta = [`Decision ID ${d.id}`, `hit policy ${d.hitPolicy}`];
167
+ if (d.calledBy.length > 0)
168
+ meta.push(`called by ${d.calledBy.join(", ")}`);
169
+ body.push(text(meta.join(" · "), undefined, { muted: true }));
170
+ body.push(tableXml([
171
+ "#",
172
+ ...d.inputs.map((i) => `When: ${i}`),
173
+ ...d.outputs.map((o) => `Then: ${o}`),
174
+ "Note",
175
+ ], d.rules.map((r, i) => [String(i + 1), ...r])));
176
+ }
177
+ }
178
+ if (doc.forms.length > 0) {
179
+ body.push(text("Forms", "Heading1"));
180
+ for (const f of doc.forms) {
181
+ body.push(text(f.id, "Heading2"));
182
+ if (f.usedBy.length > 0)
183
+ body.push(text(`Shown by ${f.usedBy.join(", ")}`, undefined, { muted: true }));
184
+ if (f.fields.length === 0) {
185
+ body.push(text("This form has no input fields.", undefined, { italic: true }));
186
+ continue;
187
+ }
188
+ body.push(tableXml(["Field", "Variable", "Type", "Required", "Options"], f.fields.map((field) => [
189
+ field.label,
190
+ field.key,
191
+ field.type,
192
+ field.required ? "Yes" : "No",
193
+ field.options,
194
+ ])));
195
+ }
196
+ }
197
+ return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n<w:document ${W_NS}><w:body>${body.join("")}${sectPr(paper, false)}</w:body></w:document>`;
198
+ }
199
+ const STYLES = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
200
+ <w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
201
+ <w:docDefaults><w:rPrDefault><w:rPr><w:rFonts w:ascii="Calibri" w:hAnsi="Calibri" w:eastAsia="Calibri" w:cs="Calibri"/><w:sz w:val="21"/><w:szCs w:val="21"/><w:color w:val="14161A"/><w:lang w:val="en-US"/></w:rPr></w:rPrDefault><w:pPrDefault><w:pPr><w:spacing w:after="120" w:line="264" w:lineRule="auto"/></w:pPr></w:pPrDefault></w:docDefaults>
202
+ <w:style w:type="paragraph" w:default="1" w:styleId="Normal"><w:name w:val="Normal"/><w:qFormat/></w:style>
203
+ <w:style w:type="paragraph" w:styleId="Title"><w:name w:val="Title"/><w:basedOn w:val="Normal"/><w:next w:val="Normal"/><w:qFormat/><w:pPr><w:spacing w:after="240"/></w:pPr><w:rPr><w:b/><w:sz w:val="56"/><w:szCs w:val="56"/></w:rPr></w:style>
204
+ <w:style w:type="paragraph" w:styleId="Heading1"><w:name w:val="heading 1"/><w:basedOn w:val="Normal"/><w:next w:val="Normal"/><w:qFormat/><w:pPr><w:keepNext/><w:spacing w:before="240" w:after="160"/><w:pBdr><w:bottom w:val="single" w:sz="4" w:space="4" w:color="D9DBDF"/></w:pBdr><w:outlineLvl w:val="0"/></w:pPr><w:rPr><w:b/><w:sz w:val="36"/><w:szCs w:val="36"/></w:rPr></w:style>
205
+ <w:style w:type="paragraph" w:styleId="Heading2"><w:name w:val="heading 2"/><w:basedOn w:val="Normal"/><w:next w:val="Normal"/><w:qFormat/><w:pPr><w:keepNext/><w:spacing w:before="240" w:after="100"/><w:outlineLvl w:val="1"/></w:pPr><w:rPr><w:b/><w:sz w:val="28"/><w:szCs w:val="28"/></w:rPr></w:style>
206
+ <w:style w:type="paragraph" w:styleId="Heading3"><w:name w:val="heading 3"/><w:basedOn w:val="Normal"/><w:next w:val="Normal"/><w:qFormat/><w:pPr><w:keepNext/><w:spacing w:before="200" w:after="40"/><w:outlineLvl w:val="2"/></w:pPr><w:rPr><w:b/><w:color w:val="A8503A"/><w:sz w:val="23"/><w:szCs w:val="23"/></w:rPr></w:style>
207
+ <w:style w:type="paragraph" w:styleId="TableText"><w:name w:val="Table Text"/><w:basedOn w:val="Normal"/><w:pPr><w:spacing w:before="20" w:after="20"/></w:pPr><w:rPr><w:sz w:val="19"/><w:szCs w:val="19"/></w:rPr></w:style>
208
+ </w:styles>`;
209
+ const CONTENT_TYPES = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
210
+ <Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Default Extension="xml" ContentType="application/xml"/><Default Extension="svg" ContentType="image/svg+xml"/><Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/><Override PartName="/word/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml"/></Types>`;
211
+ const ROOT_RELS = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
212
+ <Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/></Relationships>`;
213
+ function documentRels(withDiagram) {
214
+ const image = withDiagram
215
+ ? '<Relationship Id="rIdDiagram" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/image" Target="media/diagram.svg"/>'
216
+ : "";
217
+ return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
218
+ <Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rIdStyles" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/>${image}</Relationships>`;
219
+ }
220
+ /** Renders already-built documentation as the bytes of a Word (.docx) file. */
221
+ export function documentationToDocx(doc, paper = "a4") {
222
+ const size = PAPER[paper];
223
+ const enc = new TextEncoder();
224
+ const document = documentXml(doc, size);
225
+ const withDiagram = document.includes('r:embed="rIdDiagram"');
226
+ const files = [
227
+ { name: "[Content_Types].xml", data: enc.encode(CONTENT_TYPES) },
228
+ { name: "_rels/.rels", data: enc.encode(ROOT_RELS) },
229
+ { name: "word/document.xml", data: enc.encode(document) },
230
+ { name: "word/styles.xml", data: enc.encode(STYLES) },
231
+ { name: "word/_rels/document.xml.rels", data: enc.encode(documentRels(withDiagram)) },
232
+ ];
233
+ if (withDiagram && doc.diagramSvg) {
234
+ // Label halos rely on `paint-order`, which Word and LibreOffice ignore:
235
+ // the halo would be painted over the text and hide it.
236
+ const svg = doc.diagramSvg.replace(/;paint-order:stroke;stroke:[^;"]+;stroke-width:[^;"]+/g, "");
237
+ files.push({ name: "word/media/diagram.svg", data: enc.encode(svg) });
238
+ }
239
+ return zipStore(files);
240
+ }
241
+ /**
242
+ * Renders a BPMN model as a Word document (.docx) with the same sections as
243
+ * {@link renderDocumentationHtml}. Headings use Word's built-in heading styles,
244
+ * so the navigation pane and an inserted table of contents pick them up. The
245
+ * diagram is embedded as SVG on a landscape page, with no bitmap fallback:
246
+ * readers without SVG support (Word before 2019) show no image.
247
+ *
248
+ * Returns the file's bytes: write them to disk or wrap them in a `Blob`.
249
+ */
250
+ export function renderDocumentationDocx(defs, options = {}) {
251
+ return documentationToDocx(buildProcessDocumentation(defs, options), options.paper);
252
+ }
253
+ //# sourceMappingURL=docx.js.map
@@ -0,0 +1,21 @@
1
+ import type { BpmnDefinitions } from "../bpmn/bpmn-model.js";
2
+ import { type DocumentationOptions, type ProcessDocumentation } from "./model.js";
3
+ export declare function escapeHtml(s: string): string;
4
+ /** Renders already-built documentation as a standalone HTML document. */
5
+ export declare function documentationToHtml(doc: ProcessDocumentation): string;
6
+ /**
7
+ * Renders a BPMN model as a self-contained, print-ready HTML document: the
8
+ * diagram as inline SVG, a table of contents, one section per process or pool
9
+ * with its lanes and every element in flow order, then any message flows,
10
+ * decision tables and forms. No scripts, no network requests. The browser's
11
+ * Print → Save as PDF gives a paginated PDF on A4 or Letter.
12
+ *
13
+ * @example
14
+ * ```typescript
15
+ * import { Bpmn, renderDocumentationHtml } from "@bpmnkit/core"
16
+ *
17
+ * const html = renderDocumentationHtml(Bpmn.parse(xml), { title: "Order to Cash" })
18
+ * ```
19
+ */
20
+ export declare function renderDocumentationHtml(defs: BpmnDefinitions, options?: DocumentationOptions): string;
21
+ //# sourceMappingURL=html.d.ts.map
@@ -0,0 +1,303 @@
1
+ import { buildProcessDocumentation, } from "./model.js";
2
+ export function escapeHtml(s) {
3
+ return s
4
+ .replace(/&/g, "&amp;")
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