@bpmnkit/core 1.8.0 → 1.10.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 (110) hide show
  1. package/agent-cards/bpmn.md +4 -2
  2. package/builder-reference.md +11 -9
  3. package/dist/bpmn/auto-layout.js +82 -26
  4. package/dist/bpmn/bpmn-builder.d.ts +84 -7
  5. package/dist/bpmn/bpmn-builder.js +321 -76
  6. package/dist/bpmn/bpmn-model.d.ts +2 -0
  7. package/dist/bpmn/bpmn-parser.js +68 -76
  8. package/dist/bpmn/bpmn-serializer.js +60 -19
  9. package/dist/bpmn/bpmnlint.js +4 -69
  10. package/dist/bpmn/builder-rules.d.ts +20 -0
  11. package/dist/bpmn/builder-rules.js +120 -0
  12. package/dist/bpmn/camunda-compat-data.d.ts +10 -148
  13. package/dist/bpmn/camunda-compat-data.js +16 -407
  14. package/dist/bpmn/camunda-compat-feel.d.ts +3 -0
  15. package/dist/bpmn/camunda-compat-feel.js +1 -1
  16. package/dist/bpmn/camunda-compat.js +7 -6
  17. package/dist/bpmn/camunda7/export.js +4 -1
  18. package/dist/bpmn/camunda7/juel.js +2 -1
  19. package/dist/bpmn/camunda7/migrate.d.ts +23 -0
  20. package/dist/bpmn/camunda7/migrate.js +75 -3
  21. package/dist/bpmn/compact-stream.js +2 -1
  22. package/dist/bpmn/compact.d.ts +80 -4
  23. package/dist/bpmn/compact.js +220 -38
  24. package/dist/bpmn/feel-condition.d.ts +9 -0
  25. package/dist/bpmn/feel-condition.js +19 -0
  26. package/dist/bpmn/full-operations.js +31 -4
  27. package/dist/bpmn/index.d.ts +17 -1
  28. package/dist/bpmn/index.js +19 -25
  29. package/dist/bpmn/operations.d.ts +4 -4
  30. package/dist/bpmn/operations.js +14 -2
  31. package/dist/bpmn/optimize/bpmnlint-rules.js +7 -40
  32. package/dist/bpmn/optimize/index.js +15 -1
  33. package/dist/bpmn/optimize/tasks.js +12 -3
  34. package/dist/bpmn/process-delta.d.ts +18 -0
  35. package/dist/bpmn/process-delta.js +20 -2
  36. package/dist/bpmn/process-text-writer.js +27 -1
  37. package/dist/bpmn/process-text.d.ts +9 -3
  38. package/dist/bpmn/process-text.js +122 -16
  39. package/dist/bpmn/stable-ids.d.ts +2 -0
  40. package/dist/bpmn/stable-ids.js +8 -0
  41. package/dist/bpmn/xsd-guards.d.ts +8 -0
  42. package/dist/bpmn/xsd-guards.js +56 -0
  43. package/dist/bpmn/zeebe-extensions.js +2 -1
  44. package/dist/bpmn/zeebe-placement.js +6 -129
  45. package/dist/bpmn/zeebe-validate/context.d.ts +132 -0
  46. package/dist/bpmn/zeebe-validate/context.js +241 -0
  47. package/dist/bpmn/zeebe-validate/gate.d.ts +87 -0
  48. package/dist/bpmn/zeebe-validate/gate.js +492 -0
  49. package/dist/bpmn/zeebe-validate/index.d.ts +37 -0
  50. package/dist/bpmn/zeebe-validate/index.js +106 -0
  51. package/dist/bpmn/zeebe-validate/rules/events.d.ts +4 -0
  52. package/dist/bpmn/zeebe-validate/rules/events.js +580 -0
  53. package/dist/bpmn/zeebe-validate/rules/extensions.d.ts +4 -0
  54. package/dist/bpmn/zeebe-validate/rules/extensions.js +411 -0
  55. package/dist/bpmn/zeebe-validate/rules/gateways.d.ts +3 -0
  56. package/dist/bpmn/zeebe-validate/rules/gateways.js +296 -0
  57. package/dist/bpmn/zeebe-validate/rules/references.d.ts +3 -0
  58. package/dist/bpmn/zeebe-validate/rules/references.js +495 -0
  59. package/dist/bpmn/zeebe-validate/rules/structure.d.ts +3 -0
  60. package/dist/bpmn/zeebe-validate/rules/structure.js +629 -0
  61. package/dist/bpmn/zeebe-validate/rules/tasks.d.ts +4 -0
  62. package/dist/bpmn/zeebe-validate/rules/tasks.js +446 -0
  63. package/dist/bpmn/zeebe-validate/xml.d.ts +15 -0
  64. package/dist/bpmn/zeebe-validate/xml.js +1062 -0
  65. package/dist/bpmn/zeebe-validate/xsd.d.ts +19 -0
  66. package/dist/bpmn/zeebe-validate/xsd.js +350 -0
  67. package/dist/connectors/apply-element.d.ts +5 -2
  68. package/dist/connectors/apply-element.js +6 -0
  69. package/dist/connectors/apply-many.d.ts +9 -2
  70. package/dist/connectors/apply-many.js +17 -2
  71. package/dist/connectors/apply.d.ts +4 -2
  72. package/dist/connectors/deployability.d.ts +27 -0
  73. package/dist/connectors/deployability.js +41 -0
  74. package/dist/connectors/index.d.ts +1 -0
  75. package/dist/connectors/lines.d.ts +10 -0
  76. package/dist/connectors/lines.js +13 -4
  77. package/dist/dmn/dmn-model.d.ts +24 -4
  78. package/dist/dmn/dmn-parser.js +37 -3
  79. package/dist/dmn/dmn-serializer.js +48 -47
  80. package/dist/dmn/lint.js +4 -11
  81. package/dist/errors.d.ts +30 -1
  82. package/dist/errors.js +31 -0
  83. package/dist/form/form-model.d.ts +11 -0
  84. package/dist/form/form-parser.d.ts +1 -0
  85. package/dist/form/form-parser.js +48 -12
  86. package/dist/form/form-serializer.js +40 -17
  87. package/dist/form/lint.js +6 -40
  88. package/dist/generated/bpmn-elements.d.ts +5 -0
  89. package/dist/generated/bpmn-elements.js +151 -0
  90. package/dist/generated/camunda-compat-data.d.ts +148 -0
  91. package/dist/generated/camunda-compat-data.js +371 -0
  92. package/dist/generated/dmn-elements.d.ts +12 -0
  93. package/dist/generated/dmn-elements.js +45 -0
  94. package/dist/generated/form-elements.d.ts +5 -0
  95. package/dist/generated/form-elements.js +45 -0
  96. package/dist/generated/lint-rules.d.ts +17 -0
  97. package/dist/generated/lint-rules.js +116 -0
  98. package/dist/generated/zeebe-elements.d.ts +10 -0
  99. package/dist/generated/zeebe-elements.js +168 -0
  100. package/dist/generated/zeebe-rules.d.ts +25 -0
  101. package/dist/generated/zeebe-rules.js +202 -0
  102. package/dist/index.d.ts +11 -4
  103. package/dist/index.js +4 -1
  104. package/dist/layout/annotations.js +21 -1
  105. package/dist/layout/orthogonal.js +9 -3
  106. package/dist/plan/compile.d.ts +26 -1
  107. package/dist/plan/compile.js +48 -6
  108. package/dist/plan/merge.d.ts +2 -1
  109. package/dist/plan/merge.js +13 -5
  110. package/package.json +2 -2
@@ -71,16 +71,18 @@ if (report.counts.error > 0) process.exit(1)
71
71
  - FEEL in the builder starts with `=` (`"=amount > 1000"`); a value without `=` is a literal string.
72
72
  - Unknown option names are silently dropped: `timer: { duration }` does nothing; use `timerDuration`.
73
73
 
74
+ - **`build()`, `expand()` and `Bpmn.export` refuse what Camunda 8 cannot deploy**: a gateway branch without `condition`/`defaultFlow`, a task or message throw/end event without `taskType`, a message without name or `correlationKey`, a timer without a time, anything after an end event. The `DeployabilityError` message has one line per problem, `- <id>: <message> (zeebe/<rule>)`: fix each. `{ placeholders: true }` fills documented values to replace before deploying; `{ validate: false }` only for a draft.
75
+
74
76
  ## Lint before you deploy or test
75
77
 
76
78
  ```sh
77
79
  casen check order.bpmn risk.dmn review-order.form --deploy # one gate: BPMN + DMN + forms, and the ids that link them
78
80
  casen lint lint order.bpmn --profile deploy # BPMN only, errors only
79
- casen deploy deploy order.bpmn # local Reebe; --target camunda8 for a cluster
81
+ casen deploy deploy order.bpmn # gated first; local Reebe, --target camunda8 for a cluster
80
82
  ```
81
83
 
82
84
  In code, `lintDiagram(definitions)` returns `{ diagnostics, counts }`; fail on `counts.error > 0`. Warnings (no timer boundary, no output mapping) are advice.
83
85
 
84
86
  ## Writing a process as text instead
85
87
 
86
- A model writing the diagram itself can use the line format: `parseProcessText(text)` then `expand(result.diagram)` from `@bpmnkit/core`. `casen agent-card bpmn --text` prints its guide. Related cards: `casen agent-card dmn`, `casen agent-card form`.
88
+ A model writing the diagram itself can use the line format: `parseProcessText(text)` then `expand(result.diagram)` from `@bpmnkit/core`; `expand` throws the same gate message, naming what to add (`msg=`, `key=`, `every=`, …). `casen agent-card bpmn --text` prints its guide. Related cards: `casen agent-card dmn`, `casen agent-card form`.
@@ -7,10 +7,11 @@ Generated from `bpmn-builder.ts`; do not edit.
7
7
  - Start with `Bpmn.createProcess(id)`, end with `.build()`, then `Bpmn.export(definitions)` for the XML. Call `.withAutoLayout()` before `.build()`, or the diagram has no shapes.
8
8
  - Element ids are unique. Each element connects to the previous one automatically; there are no manual flows.
9
9
  - `subProcess`, `transaction`, `eventSubProcess` and `adHocSubProcess` take the callback as the SECOND argument and options THIRD: `.subProcess(id, (sub) => sub.startEvent()..., { name })`. Swapped order is tolerated.
10
- - Gateways fork with `.branch(name, (b) => b...)`. Inside, `b.condition(feelExpr)` sets the flow condition and `b.defaultFlow()` marks the default flow. To merge, end a branch with `.connectTo(targetId)` and declare that target after the last branch.
10
+ - Gateways fork with `.branch(name, (b) => b...)`. Inside, `b.condition(feelExpr)` sets the flow condition and `b.defaultFlow()` marks the default flow; every branch of an exclusive or inclusive gateway needs one of them. To merge, end a branch with `.connectTo(targetId)` and declare that target after the last branch.
11
11
  - Event definitions are named options, not nested objects: `timerDuration`, `timerDate`, `timerCycle`, `messageName` + `correlationKey`, `signalName`, `errorCode`, `escalationCode`, `linkName`. Unknown options are silently dropped: `timer: { duration }` does nothing.
12
12
  - `withBoundary(id, options, (b) => ...)` attaches a boundary event to the PRECEDING activity; the callback builds the path leaving it, and the main chain continues from the activity.
13
13
  - FEEL expressions start with `=`. Options without `?` are required.
14
+ - `build()` refuses what Camunda 8 cannot deploy: send tasks and message throw/end events need `taskType`, and nothing may follow an end event.
14
15
 
15
16
  ## Methods
16
17
 
@@ -28,7 +29,7 @@ Tasks and connectors:
28
29
  - restConnector(id: string, config: RestConnectorConfig)
29
30
  - scriptTask(id: string, options: ScriptTaskOptions)
30
31
  - userTask(id: string, options?: UserTaskOptions)
31
- - sendTask(id: string, options?: MessageTaskOptions)
32
+ - sendTask(id: string, options?: SendTaskOptions)
32
33
  - receiveTask(id: string, options?: MessageTaskOptions)
33
34
  - businessRuleTask(id: string, options?: BusinessRuleTaskOptions)
34
35
  - callActivity(id: string, options: CallActivityOptions)
@@ -81,19 +82,20 @@ Not available inside callbacks (top-level only): at, insertAfter, withAutoLayout
81
82
 
82
83
  ## Options
83
84
 
84
- `+El` = also accepts the ElementOptions fields.
85
+ `+El` = also accepts the ElementOptions fields; `+X` = also accepts X's fields.
85
86
 
86
87
  - ElementOptions: name?: string; documentation?: string (Free-text documentation…)
87
- - StartEventOptions +El: condition?: string (FEEL condition); timerDuration?: string (Timer duration (ISO 8601)); timerDate?: string (Timer date (ISO 8601)); timerCycle?: string (Timer cycle (ISO 8601)); messageName?: string (Message name); formId?: string (Form to show when the process is…); isInterrupting?: boolean (Non-interrupting flag)
88
- - EndEventOptions +El: errorCode?: string (Error code); messageName?: string; signalName?: string (Signal name); escalationCode?: string (Escalation code)
89
- - IntermediateThrowEventOptions +El: messageName?: string; signalName?: string; escalationCode?: string; compensation?: boolean (Emit a compensateEventDefinition); linkName?: string (Link name)
90
- - IntermediateCatchEventOptions +El: timerDuration?: string; timerDate?: string; timerCycle?: string; messageName?: string; correlationKey?: string (FEEL expression correlating this…); signalName?: string; linkName?: string; condition?: string
88
+ - StartEventOptions +El: condition?: string (FEEL condition); timerDuration?: string (Timer duration (ISO 8601)); timerDate?: string (Timer date (ISO 8601)); timerCycle?: string (Timer cycle (ISO 8601)); messageName?: string (Message name); correlationKey?: string (FEEL expression correlating the…); formId?: string (Form to show when the process is…); isInterrupting?: boolean (Non-interrupting flag)
89
+ - EndEventOptions +El: errorCode?: string (Error code); messageName?: string; signalName?: string (Signal name); escalationCode?: string (Escalation code); taskType?: string (Job type of the worker that…)
90
+ - IntermediateThrowEventOptions +El: messageName?: string; signalName?: string; escalationCode?: string; compensation?: boolean (Emit a compensateEventDefinition); linkName?: string (Link name); taskType?: string
91
+ - IntermediateCatchEventOptions +El: timerDuration?: string; timerDate?: string; timerCycle?: string; messageName?: string; correlationKey?: string; signalName?: string; linkName?: string; condition?: string
91
92
  - BoundaryEventOptions +El: attachedTo: string (ID of the activity this boundary…); cancelActivity?: boolean (Whether the host activity is…); errorCode?: string; timerDuration?: string; timerDate?: string; timerCycle?: string; messageName?: string; correlationKey?: string; signalName?: string; compensation?: boolean; condition?: string
92
- - ServiceTaskOptions: multiInstance?: MultiInstanceOptions (Runs the activity once per item…); name: string; taskType: string (Zeebe job type for this task); retries?: string (Number of retries…); ioMapping?: ioMapping shape (Input/output variable mappings); taskHeaders?: Record<string, string> (Task header key-value pairs); linkedResources?: ZeebeLinkedResource[] (Resources the task runs, e.g. an…); documentation?: string
93
+ - ServiceTaskOptions: multiInstance?: MultiInstanceOptions (Runs the activity once per item…); name: string; taskType: string; retries?: string (Number of retries…); ioMapping?: ioMapping shape (Input/output variable mappings); taskHeaders?: Record<string, string> (Task header key-value pairs); linkedResources?: ZeebeLinkedResource[] (Resources the task runs, e.g. an…); documentation?: string
93
94
  - MultiInstanceOptions: isSequential?: boolean; collection?: string; elementVariable?: string; outputCollection?: string (Variable that collects each…); outputElement?: string (FEEL expression evaluated per…); completionCondition?: string
94
95
  - RestConnectorConfig: name?: string; method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" (HTTP method…); url: string (Target URL); authentication?: {type: "noAuth"} | {type: "bearer"; token: string} (Authentication configuration); headers?: Record<string, string> | string (HTTP headers as key-value pairs…); body?: string (Request body); retries?: string; resultVariable?: string (Variable name to store the full…); resultExpression?: string (FEEL expression to extract values…)
95
96
  - ScriptTaskOptions: multiInstance?: MultiInstanceOptions; name?: string; expression: string (FEEL expression for the script); resultVariable: string; documentation?: string
96
97
  - UserTaskOptions: multiInstance?: MultiInstanceOptions; name?: string; formId?: string; externalReference?: string (External form URL…); embeddedForm?: {id: string; schema: string} (Embeds a Camunda Form: writes a…); ioMapping?: ioMapping shape; taskHeaders?: Record<string, string>; documentation?: string; assignee?: string (Static assignee…); candidateGroups?: string (Candidate groups, comma-separated…); candidateUsers?: string (Candidate users, comma-separated…); dueDate?: string (Due date); followUpDate?: string (Follow-up date); priority?: number (Task priority 0-100, default 50…)
98
+ - SendTaskOptions +MessageTaskOptions: taskType?: string
97
99
  - MessageTaskOptions +El: multiInstance?: MultiInstanceOptions; messageName?: string; correlationKey?: string
98
100
  - BusinessRuleTaskOptions: multiInstance?: MultiInstanceOptions; name?: string; taskType?: string; decisionId?: string (DMN decision ID to evaluate); resultVariable?: string; documentation?: string
99
101
  - CallActivityOptions: multiInstance?: MultiInstanceOptions; name?: string; processId: string (Process ID to call); propagateAllChildVariables?: boolean (Whether to propagate all child…); propagateAllParentVariables?: boolean (Whether the child process…); bindingType?: "latest" | "deployment" | "versionTag" (How the called process version is…); versionTag?: string (Version tag of the called…); ioMapping?: ioMapping shape; documentation?: string
@@ -102,7 +104,7 @@ Not available inside callbacks (top-level only): at, insertAfter, withAutoLayout
102
104
  - SubProcessOptions +El: multiInstance?: MultiInstanceOptions
103
105
  - DataElementOptions: name?: string; isCollection?: boolean (Draws the collection…)
104
106
  - AnnotateOptions: side?: "above" | "below" | "left" | "right" (Which side of the element…)
105
- - BuildOptions: explicitJoins?: boolean (Refuse to infer join gateways, so…)
107
+ - BuildOptions: validate?: boolean (Refuse a Camunda 8 model Zeebe…); explicitJoins?: boolean (Refuse to infer join gateways, so…)
106
108
  - ioMapping shape = {inputs?: Array<{source: string; target: string}>; outputs?: Array<{source: string; target: string}>}
107
109
 
108
110
  ## Examples
@@ -87,6 +87,26 @@ function edgeToShape(edge, dx, dy) {
87
87
  }
88
88
  return diEdge;
89
89
  }
90
+ /**
91
+ * Lane shapes for one process: the engine's bands when it placed nodes by lane,
92
+ * otherwise the top-level lanes tiled proportionally over the content height.
93
+ */
94
+ function laneShapesFor(lanes, laneBands, nodes, dx, dy, top, x, width, height) {
95
+ if (!laneBands)
96
+ return buildLaneShapes(lanes, nodes, dx, dy, top, x, width, height);
97
+ return laneBands.map((lane) => ({
98
+ id: `${lane.id}_di`,
99
+ bpmnElement: lane.id,
100
+ isHorizontal: true,
101
+ bounds: {
102
+ x: Math.round(x),
103
+ y: Math.round(lane.bounds.y + dy),
104
+ width: Math.round(width),
105
+ height: Math.round(lane.bounds.height),
106
+ },
107
+ unknownAttributes: {},
108
+ }));
109
+ }
90
110
  function buildLaneShapes(lanes, nodes, dx, dy, poolY, poolHeaderWidth, laneContentWidth, poolHeight) {
91
111
  const elemToLane = new Map();
92
112
  for (const lane of lanes) {
@@ -197,6 +217,22 @@ export function addAnnotationShapes(process, layoutNodes, annLocalBounds, allSha
197
217
  });
198
218
  }
199
219
  for (const assoc of process.associations) {
220
+ // Two annotations: both boxes are packed, so dock edge to edge between them.
221
+ const sourceAnn = annLocalBounds.get(assoc.sourceRef);
222
+ const targetAnn = annLocalBounds.get(assoc.targetRef);
223
+ if (sourceAnn && targetAnn) {
224
+ const { pElem, pAnn } = associationWaypoints(sourceAnn, targetAnn);
225
+ allEdges.push({
226
+ id: `${assoc.id}_di`,
227
+ bpmnElement: assoc.id,
228
+ waypoints: [
229
+ { x: Math.round(pElem.x + dx), y: Math.round(pElem.y + dy) },
230
+ { x: Math.round(pAnn.x + dx), y: Math.round(pAnn.y + dy) },
231
+ ],
232
+ unknownAttributes: {},
233
+ });
234
+ continue;
235
+ }
200
236
  const annId = annLocalBounds.has(assoc.sourceRef)
201
237
  ? assoc.sourceRef
202
238
  : annLocalBounds.has(assoc.targetRef)
@@ -698,8 +734,11 @@ export function applyAutoLayout(defs, engine = "semantic", hints) {
698
734
  const alignDx = alignment[poolIndex] ?? 0;
699
735
  // A participant with no process, or one whose process has no flow nodes,
700
736
  // is a black box: it still needs a pool of its own to dock message flows
701
- // onto, and to stay visible at all.
702
- if (result.nodes.length === 0) {
737
+ // onto, and to stay visible at all. One whose process holds annotations
738
+ // is not: it takes the content path below, so the pool is sized around them
739
+ // and they get shapes instead of being dropped.
740
+ const annotationsOnlyPool = participantId !== undefined && process !== undefined && process.textAnnotations.length > 0;
741
+ if (result.nodes.length === 0 && !annotationsOnlyPool) {
703
742
  // A process can be nothing but annotations; they still belong on the plane.
704
743
  if (!participantId && process && process.textAnnotations.length > 0) {
705
744
  const annOnly = packAnnotations(process, []);
@@ -736,13 +775,15 @@ export function applyAutoLayout(defs, engine = "semantic", hints) {
736
775
  // Engine lane bands already stack the content vertically, so the pool
737
776
  // aligns to the band space rather than to the content bounding box —
738
777
  // otherwise the shapes drift out of the lanes drawn around them.
739
- const laneBands = participantId && hasLanes ? engineLanes : undefined;
778
+ const laneBands = hasLanes ? engineLanes : undefined;
740
779
  // Bands arrive outermost first and nested lanes overlap their parent, so the
741
780
  // pool spans their extent rather than the first band or the sum of heights.
742
781
  const bandTop = laneBands ? Math.min(...laneBands.map((lane) => lane.bounds.y)) : 0;
743
782
  const bandHeight = laneBands
744
783
  ? Math.max(...laneBands.map((lane) => lane.bounds.y + lane.bounds.height)) - bandTop
745
784
  : 0;
785
+ // Below any pools already stacked; poolY is 0 without a collaboration.
786
+ const processTop = process?.id === primaryProcessId ? poolY : 0;
746
787
  let dx;
747
788
  let dy;
748
789
  if (participantId) {
@@ -751,10 +792,17 @@ export function applyAutoLayout(defs, engine = "semantic", hints) {
751
792
  dy = laneBands ? poolY - bandTop : poolY + PADDING - minY;
752
793
  }
753
794
  else {
754
- dx = PADDING - minX;
755
- // Below any pools already stacked; poolY is 0 without a collaboration.
756
- dy = (process?.id === primaryProcessId ? poolY : 0) + PADDING - minY;
795
+ // A process outside any pool draws its lanes on the plane itself (bpmn-js
796
+ // imports lane DI under a process root), header at x 0, so the content
797
+ // clears the lane header the way it does in a pool.
798
+ // A layout pass must not invent a participant to hold them.
799
+ dx = (hasLanes ? LANE_HEADER : 0) + PADDING - minX;
800
+ dy = laneBands ? processTop - bandTop : processTop + PADDING - minY;
757
801
  }
802
+ /** Lanes of a process outside any pool, drawn straight on its plane. */
803
+ const bareLanes = !participantId && hasLanes
804
+ ? laneShapesFor(lanes, laneBands, result.nodes, dx, dy, processTop, 0, LANE_HEADER + contentW + 2 * PADDING, laneBands ? bandHeight : contentH + 2 * PADDING)
805
+ : [];
758
806
  // Only the primary process shares the root plane; any other root process
759
807
  // owns one, instead of being stacked on top of the first at the origin.
760
808
  if (!participantId && process && process.id !== primaryProcessId) {
@@ -765,6 +813,7 @@ export function applyAutoLayout(defs, engine = "semantic", hints) {
765
813
  for (const edge of result.edges)
766
814
  edges.push(edgeToShape(edge, dx, dy));
767
815
  addAnnotationShapes(annProcess ?? process, result.nodes, annBounds, shapes, edges, dx, dy);
816
+ shapes.push(...bareLanes);
768
817
  rootPlanes.push({ elementId: process.id, shapes, edges });
769
818
  continue;
770
819
  }
@@ -775,6 +824,7 @@ export function applyAutoLayout(defs, engine = "semantic", hints) {
775
824
  if (process) {
776
825
  addAnnotationShapes(annProcess ?? process, result.nodes, annBounds, allShapes, allEdges, dx, dy);
777
826
  }
827
+ allShapes.push(...bareLanes);
778
828
  if (participantId) {
779
829
  const innerW = (hasLanes ? LANE_HEADER : 0) + contentW + 2 * PADDING + alignDx;
780
830
  // Lanes must tile the pool exactly, so the pool takes their height.
@@ -788,21 +838,7 @@ export function applyAutoLayout(defs, engine = "semantic", hints) {
788
838
  unknownAttributes: {},
789
839
  });
790
840
  if (hasLanes) {
791
- const laneShapes = laneBands
792
- ? laneBands.map((lane) => ({
793
- id: `${lane.id}_di`,
794
- bpmnElement: lane.id,
795
- isHorizontal: true,
796
- bounds: {
797
- x: Math.round(POOL_HEADER),
798
- y: Math.round(lane.bounds.y + dy),
799
- width: Math.round(innerW),
800
- height: Math.round(lane.bounds.height),
801
- },
802
- unknownAttributes: {},
803
- }))
804
- : buildLaneShapes(lanes, result.nodes, dx, dy, poolY, POOL_HEADER, innerW, innerH);
805
- allShapes.push(...laneShapes);
841
+ allShapes.push(...laneShapesFor(lanes, laneBands, result.nodes, dx, dy, poolY, POOL_HEADER, innerW, innerH));
806
842
  }
807
843
  poolY += innerH + POOL_GAP;
808
844
  }
@@ -906,7 +942,18 @@ export function applyAutoLayout(defs, engine = "semantic", hints) {
906
942
  for (const plane of rootPlanes)
907
943
  repair(plane.shapes, plane.edges);
908
944
  const planeBpmnElement = collab?.id ?? defs.processes[0]?.id ?? "plane";
909
- const existingDiagram = defs.diagrams[0];
945
+ // The primary plane keeps the ids of the source diagram that drew the same
946
+ // element. The first diagram is the fallback only while no other plane
947
+ // reuses it: a root or sub-process plane keeps its own source diagram, and
948
+ // two diagrams with one id lose a plane to any reader that resolves by id.
949
+ const claimed = new Set([
950
+ ...rootPlanes.map((plane) => plane.elementId),
951
+ ...childPlanes.map((plane) => plane.elementId),
952
+ ...collapsed,
953
+ ]);
954
+ const firstDiagram = defs.diagrams[0];
955
+ const existingDiagram = defs.diagrams.find((d) => d.plane.bpmnElement === planeBpmnElement) ??
956
+ (firstDiagram && !claimed.has(firstDiagram.plane.bpmnElement) ? firstDiagram : undefined);
910
957
  return {
911
958
  ...defs,
912
959
  diagrams: keepDiAttributes(defs.diagrams, [
@@ -975,11 +1022,15 @@ function keepDiAttributes(source, laidOut) {
975
1022
  const used = new Set();
976
1023
  // An empty source id means the source omitted it; that is not one to keep.
977
1024
  const keepId = (generated, previous) => {
978
- let id = previous && !used.has(previous) ? previous : generated;
979
- if (id !== previous) {
980
- for (let n = 2; sourceIds.has(id) || used.has(id); n++)
981
- id = `${generated}_${n}`;
1025
+ if (previous && !used.has(previous)) {
1026
+ used.add(previous);
1027
+ return previous;
982
1028
  }
1029
+ // Checked even when `generated` equals a previous id already taken (two
1030
+ // source shapes sharing `X_di`): that id is in use, so it is not free.
1031
+ let id = generated;
1032
+ for (let n = 2; sourceIds.has(id) || used.has(id); n++)
1033
+ id = `${generated}_${n}`;
983
1034
  used.add(id);
984
1035
  return id;
985
1036
  };
@@ -1080,6 +1131,11 @@ function routeRepair(defs) {
1080
1131
  target: flow.targetRef,
1081
1132
  });
1082
1133
  }
1134
+ // A sub-process's associations are drawn on the same plane as the
1135
+ // process's own (withNestedAnnotations), so they need the same repair.
1136
+ for (const a of scope.associations ?? []) {
1137
+ connections.set(a.id, { kind: "association", source: a.sourceRef, target: a.targetRef });
1138
+ }
1083
1139
  if (scope.flowElements)
1084
1140
  walk(scope.flowElements, element.id);
1085
1141
  }
@@ -20,6 +20,14 @@ export interface MessageTaskOptions extends ElementOptions {
20
20
  /** FEEL expression correlating this message to a specific process instance (`zeebe:subscription`). */
21
21
  correlationKey?: string;
22
22
  }
23
+ /** Options for a send task. */
24
+ export interface SendTaskOptions extends MessageTaskOptions {
25
+ /**
26
+ * Job type of the worker that sends the message (`zeebe:taskDefinition`).
27
+ * Camunda 8 runs a send task as a job, so `build()` requires it.
28
+ */
29
+ taskType?: string;
30
+ }
23
31
  /** Variable change that re-evaluates a conditional event's condition. */
24
32
  export type ConditionVariableEvent = "create" | "update";
25
33
  /** Options for creating a start event. */
@@ -36,6 +44,12 @@ export interface StartEventOptions extends ElementOptions {
36
44
  timerCycle?: string;
37
45
  /** Message name — creates a message start event. */
38
46
  messageName?: string;
47
+ /**
48
+ * FEEL expression correlating the message (`zeebe:subscription`). Required for
49
+ * the message start event of an event sub-process; a process's own message
50
+ * start does not need one.
51
+ */
52
+ correlationKey?: string;
39
53
  /**
40
54
  * Form to show when the process is started (`zeebe:formDefinition formId`).
41
55
  * Camunda uses start forms only on the process's none start event, so set it
@@ -264,7 +278,7 @@ export interface GatewayOptions extends ElementOptions {
264
278
  defaultFlow?: string;
265
279
  }
266
280
  /** Options for {@link ProcessBuilder.build}. */
267
- export interface BuildOptions {
281
+ export interface BuildOptions extends BuildGateOptions {
268
282
  /**
269
283
  * Refuse to infer join gateways, so converging branches must be declared.
270
284
  *
@@ -274,6 +288,38 @@ export interface BuildOptions {
274
288
  */
275
289
  explicitJoins?: boolean;
276
290
  }
291
+ /**
292
+ * The deployability options shared by {@link ProcessBuilder.build} and
293
+ * {@link DiagramBuilder.build}.
294
+ *
295
+ * With `validate` on (the default) and a model that targets Camunda 8 (the
296
+ * builder writes `modeler:executionPlatform="Camunda Cloud"`; a document
297
+ * continued with {@link ProcessBuilder.from} keeps its own platform), `build()`
298
+ * first applies the builder's Camunda 8 rules, which name the option or call
299
+ * that fixes the model, then runs {@link assertDeployable} on the result.
300
+ *
301
+ * To see what `placeholders: true` filled, build with `validate: false` and call
302
+ * `assertDeployable(defs, { placeholders: true })` yourself: its `placeholders`
303
+ * lists every value written.
304
+ */
305
+ export interface BuildGateOptions {
306
+ /**
307
+ * Refuse a Camunda 8 model Zeebe would reject (default `true`). `false` skips the
308
+ * Camunda 8 rules and the deploy check, for a model that is not meant for
309
+ * Camunda 8 or is not finished; structural rules (nothing after an end event)
310
+ * still apply.
311
+ */
312
+ validate?: boolean;
313
+ /**
314
+ * Fill the documented {@link PLACEHOLDERS} (job types, conditions, message
315
+ * names, ...) instead of refusing, and return the filled model. The rules a
316
+ * placeholder satisfies (a missing `taskType` or branch condition) are then not
317
+ * applied. Default `false`.
318
+ */
319
+ placeholders?: boolean;
320
+ /** The Camunda 8 version to check for; defaults to the model's `executionPlatformVersion`. */
321
+ camundaVersion?: string;
322
+ }
277
323
  /** Options for a collaboration participant (a pool). */
278
324
  export interface ParticipantOptions {
279
325
  /** Pool label. */
@@ -342,6 +388,11 @@ export interface IntermediateThrowEventOptions extends ElementOptions {
342
388
  * last element of a branch it leaves no open end to join.
343
389
  */
344
390
  linkName?: string;
391
+ /**
392
+ * Job type of the worker that publishes the message (`zeebe:taskDefinition`).
393
+ * Camunda 8 runs a message throw event as a job, so `build()` requires it with `messageName`.
394
+ */
395
+ taskType?: string;
345
396
  }
346
397
  /** Options for an end event. */
347
398
  export interface EndEventOptions extends ElementOptions {
@@ -355,6 +406,11 @@ export interface EndEventOptions extends ElementOptions {
355
406
  signalName?: string;
356
407
  /** Escalation code — creates an escalation end event. */
357
408
  escalationCode?: string;
409
+ /**
410
+ * Job type of the worker that publishes the message (`zeebe:taskDefinition`).
411
+ * Camunda 8 runs a message end event as a job, so `build()` requires it with `messageName`.
412
+ */
413
+ taskType?: string;
358
414
  }
359
415
  /** Options for a boundary event. */
360
416
  export interface BoundaryEventOptions extends ElementOptions {
@@ -574,7 +630,7 @@ export declare class BranchBuilder {
574
630
  serviceTask(id: string, options: ServiceTaskOptions): this;
575
631
  userTask(id: string, options?: UserTaskOptions): this;
576
632
  scriptTask(id: string, options: ScriptTaskOptions): this;
577
- sendTask(id: string, options?: MessageTaskOptions): this;
633
+ sendTask(id: string, options?: SendTaskOptions): this;
578
634
  receiveTask(id: string, options?: MessageTaskOptions): this;
579
635
  businessRuleTask(id: string, options?: BusinessRuleTaskOptions): this;
580
636
  callActivity(id: string, options: CallActivityOptions): this;
@@ -688,7 +744,7 @@ export declare class SubProcessContentBuilder {
688
744
  userTask(id: string, options?: UserTaskOptions): this;
689
745
  businessRuleTask(id: string, options?: BusinessRuleTaskOptions): this;
690
746
  callActivity(id: string, options: CallActivityOptions): this;
691
- sendTask(id: string, options?: MessageTaskOptions): this;
747
+ sendTask(id: string, options?: SendTaskOptions): this;
692
748
  receiveTask(id: string, options?: MessageTaskOptions): this;
693
749
  /** Add a manual task — work performed outside the engine, with no job worker. */
694
750
  manualTask(id: string, options?: ElementOptions): this;
@@ -910,7 +966,11 @@ export declare class ProcessBuilder {
910
966
  code: string;
911
967
  name?: string;
912
968
  }): this;
913
- /** Add a start event. Start events never auto-connect from the previous element. */
969
+ /**
970
+ * Add a start event. Like every element it chains from the current position;
971
+ * at the beginning of a process there is none. Use `addStartEvent()` for a
972
+ * start event that begins a new, disconnected path.
973
+ */
914
974
  startEvent(id?: string, options?: StartEventOptions): this;
915
975
  /**
916
976
  * Add a disconnected start event — begins a new parallel path in the process.
@@ -957,7 +1017,7 @@ export declare class ProcessBuilder {
957
1017
  /** Add a user task with optional form reference. */
958
1018
  userTask(id: string, options?: UserTaskOptions): this;
959
1019
  /** Add a send task (aspirational). */
960
- sendTask(id: string, options?: MessageTaskOptions): this;
1020
+ sendTask(id: string, options?: SendTaskOptions): this;
961
1021
  /** Add a receive task (aspirational). */
962
1022
  receiveTask(id: string, options?: MessageTaskOptions): this;
963
1023
  /** Add a business rule task. */
@@ -1055,9 +1115,19 @@ export declare class ProcessBuilder {
1055
1115
  * says: inference reads the whole topology, and on a document you were handed
1056
1116
  * that means rewriting edges you never touched.
1057
1117
  *
1058
- * @param options - `explicitJoins` refuses inferred join gateways.
1118
+ * **The deploy gate.** A model that targets Camunda 8 (every new one does) must
1119
+ * deploy: `build()` refuses with a clear error what the builder can name (a
1120
+ * branch without a condition, a send task without a `taskType`, ...) and then
1121
+ * runs {@link assertDeployable}, which throws a `DeployabilityError` listing
1122
+ * whatever Zeebe would still reject. See {@link BuildGateOptions} for
1123
+ * `validate`, `placeholders` and `camundaVersion`.
1124
+ *
1125
+ * @param options - `explicitJoins` refuses inferred join gateways; `validate`,
1126
+ * `placeholders` and `camundaVersion` control the deploy gate.
1127
+ * @throws {DeployabilityError} When the gate runs and Zeebe would reject the model.
1059
1128
  */
1060
1129
  build(options?: BuildOptions): BpmnDefinitions;
1130
+ private buildModel;
1061
1131
  /**
1062
1132
  * Writes this process's contents back into the document it came from.
1063
1133
  *
@@ -1141,7 +1211,14 @@ export declare class DiagramBuilder {
1141
1211
  private collaborationProblems;
1142
1212
  /** Maps every participant id and every flow node id to its owning participant. */
1143
1213
  private participantIndex;
1144
- build(): BpmnDefinitions;
1214
+ /**
1215
+ * Build the document. Gated like {@link ProcessBuilder.build}: see
1216
+ * {@link BuildGateOptions}.
1217
+ *
1218
+ * @throws {DeployabilityError} When the gate runs and Zeebe would reject the document.
1219
+ */
1220
+ build(options?: BuildGateOptions): BpmnDefinitions;
1221
+ private buildModel;
1145
1222
  /**
1146
1223
  * A document with no participants has no collaboration — an empty
1147
1224
  * `<bpmn:collaboration/>` is not a neutral addition, it makes every process a