@bpmnkit/core 1.14.0 → 1.16.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 (44) hide show
  1. package/AGENTS.md +5 -4
  2. package/agent-cards/bpmn.md +86 -80
  3. package/builder-reference.md +27 -8
  4. package/dist/bpmn/auto-layout.js +235 -42
  5. package/dist/bpmn/bpmn-builder.d.ts +171 -17
  6. package/dist/bpmn/bpmn-builder.js +792 -135
  7. package/dist/bpmn/bpmn-model.d.ts +15 -0
  8. package/dist/bpmn/bpmn-parser.js +32 -6
  9. package/dist/bpmn/bpmn-serializer.js +9 -2
  10. package/dist/bpmn/compact-stream.d.ts +7 -0
  11. package/dist/bpmn/compact-stream.js +7 -0
  12. package/dist/bpmn/compact.d.ts +126 -9
  13. package/dist/bpmn/compact.js +305 -30
  14. package/dist/bpmn/full-operations.d.ts +19 -0
  15. package/dist/bpmn/full-operations.js +191 -7
  16. package/dist/bpmn/make-room.d.ts +26 -0
  17. package/dist/bpmn/make-room.js +151 -0
  18. package/dist/bpmn/optimize/flow.js +8 -0
  19. package/dist/bpmn/place-new-shapes.d.ts +6 -1
  20. package/dist/bpmn/place-new-shapes.js +53 -2
  21. package/dist/bpmn/preserving-writer.d.ts +1 -1
  22. package/dist/bpmn/preserving-writer.js +1 -1
  23. package/dist/bpmn/process-delta.d.ts +32 -1
  24. package/dist/bpmn/process-delta.js +62 -1
  25. package/dist/bpmn/process-text-writer.d.ts +18 -7
  26. package/dist/bpmn/process-text-writer.js +105 -22
  27. package/dist/bpmn/process-text.d.ts +34 -2
  28. package/dist/bpmn/process-text.js +410 -7
  29. package/dist/bpmn/swimlanes.d.ts +178 -0
  30. package/dist/bpmn/swimlanes.js +774 -0
  31. package/dist/form/user-task-forms.d.ts +45 -0
  32. package/dist/form/user-task-forms.js +129 -0
  33. package/dist/index.d.ts +9 -4
  34. package/dist/index.js +5 -2
  35. package/dist/layout/collaboration/message-labels.d.ts +25 -0
  36. package/dist/layout/collaboration/message-labels.js +108 -0
  37. package/dist/layout/collaboration/ordering.d.ts +5 -1
  38. package/dist/layout/collaboration/ordering.js +24 -9
  39. package/dist/layout/semantic/graph.js +3 -0
  40. package/dist/layout/semantic/place.d.ts +2 -0
  41. package/dist/layout/semantic/place.js +77 -9
  42. package/dist/xml/xml-patch.d.ts +1 -1
  43. package/llms.txt +1 -1
  44. package/package.json +2 -2
@@ -1,10 +1,12 @@
1
1
  import type { GridHint, LayoutHints } from "../layout/types.js";
2
- import type { BpmnAssociation, BpmnDefinitions, BpmnError, BpmnEscalation, BpmnFlowElement, BpmnMessage, BpmnSequenceFlow, BpmnSignal, BpmnTextAnnotation } from "./bpmn-model.js";
2
+ import type { BpmnAssociation, BpmnDefinitions, BpmnError, BpmnEscalation, BpmnFlowElement, BpmnLaneSet, BpmnMessage, BpmnSequenceFlow, BpmnSignal, BpmnTextAnnotation } from "./bpmn-model.js";
3
3
  import type { RestConnectorConfig } from "./rest-connector.js";
4
4
  import { type ZeebeLinkedResource, type ZeebeListener } from "./zeebe-extensions.js";
5
5
  /** Options shared by all element methods. */
6
6
  export interface ElementOptions {
7
7
  name?: string;
8
+ /** Lane of this node only, overriding the one `inLane()` set; declared on first use. */
9
+ lane?: string;
8
10
  isForCompensation?: boolean;
9
11
  /** Free-text documentation (`<bpmn:documentation>`). Used by the AI Agent connector as a tool description. */
10
12
  documentation?: string;
@@ -75,6 +77,8 @@ export interface StartEventOptions extends ElementOptions {
75
77
  }
76
78
  /** Options for creating a service task. */
77
79
  export interface ServiceTaskOptions {
80
+ /** Lane of this node only, overriding the one `inLane()` set; declared on first use. */
81
+ lane?: string;
78
82
  /** Job-worker listeners on this element's lifecycle (`zeebe:executionListeners`). */
79
83
  executionListeners?: ZeebeListener[];
80
84
  /** Runs the activity once per item of a list. */
@@ -122,6 +126,8 @@ export interface ServiceTaskOptions {
122
126
  }
123
127
  /** Options for creating a script task. */
124
128
  export interface ScriptTaskOptions {
129
+ /** Lane of this node only, overriding the one `inLane()` set; declared on first use. */
130
+ lane?: string;
125
131
  /** Job-worker listeners on this element's lifecycle (`zeebe:executionListeners`). */
126
132
  executionListeners?: ZeebeListener[];
127
133
  /** Runs the activity once per item of a list. */
@@ -139,6 +145,8 @@ export interface ScriptTaskOptions {
139
145
  }
140
146
  /** Options for creating a user task. */
141
147
  export interface UserTaskOptions {
148
+ /** Lane of this node only, overriding the one `inLane()` set; declared on first use. */
149
+ lane?: string;
142
150
  /** Listeners on the user task's own lifecycle (`zeebe:taskListeners`); needs `zeebeUserTask`. */
143
151
  taskListeners?: ZeebeListener[];
144
152
  /** Job-worker listeners on this element's lifecycle (`zeebe:executionListeners`). */
@@ -210,6 +218,8 @@ export interface UserTaskOptions {
210
218
  }
211
219
  /** Options for creating a call activity. */
212
220
  export interface CallActivityOptions {
221
+ /** Lane of this node only, overriding the one `inLane()` set; declared on first use. */
222
+ lane?: string;
213
223
  /** Job-worker listeners on this element's lifecycle (`zeebe:executionListeners`). */
214
224
  executionListeners?: ZeebeListener[];
215
225
  /** Runs the activity once per item of a list. */
@@ -255,6 +265,8 @@ export interface CallActivityOptions {
255
265
  }
256
266
  /** Options for creating a business rule task. */
257
267
  export interface BusinessRuleTaskOptions {
268
+ /** Lane of this node only, overriding the one `inLane()` set; declared on first use. */
269
+ lane?: string;
258
270
  /** Job-worker listeners on this element's lifecycle (`zeebe:executionListeners`). */
259
271
  executionListeners?: ZeebeListener[];
260
272
  /** Runs the activity once per item of a list. */
@@ -374,6 +386,8 @@ export interface IntermediateCatchEventOptions extends ElementOptions {
374
386
  export interface IntermediateThrowEventOptions extends ElementOptions {
375
387
  /** Message name — creates a message throw event (aspirational). */
376
388
  messageName?: string;
389
+ /** FEEL expression correlating the message (`zeebe:subscription`, written on the message). Camunda 8 lint expects one on a message throw event's message. */
390
+ correlationKey?: string;
377
391
  /** Signal name — creates a signal throw event (aspirational). */
378
392
  signalName?: string;
379
393
  /** Escalation code — creates an escalation throw event (aspirational). */
@@ -402,6 +416,8 @@ export interface EndEventOptions extends ElementOptions {
402
416
  errorRef?: string;
403
417
  /** Message name — creates a message end event. */
404
418
  messageName?: string;
419
+ /** FEEL expression correlating the message (`zeebe:subscription`, written on the message). Camunda 8 lint expects one on a message end event's message. */
420
+ correlationKey?: string;
405
421
  /** Signal name — creates a signal end event. */
406
422
  signalName?: string;
407
423
  /** Escalation code — creates an escalation end event. */
@@ -534,6 +550,39 @@ export interface AnnotateOptions {
534
550
  */
535
551
  side?: "above" | "below" | "left" | "right";
536
552
  }
553
+ /** Options for {@link ProcessBuilder.inLane}. */
554
+ export interface LaneOptions {
555
+ /** Label shown on the lane; defaults to its id. */
556
+ name?: string;
557
+ }
558
+ /** Options for `ProcessBuilder.lane()`. */
559
+ export interface DeclaredLaneOptions extends LaneOptions {
560
+ /**
561
+ * Ids of the top-level flow nodes in this lane, written verbatim and in this
562
+ * order. Only a leaf lane (one no other lane names as `parent`) holds nodes;
563
+ * a boundary event follows its host and need not be listed.
564
+ */
565
+ flowNodes?: string[];
566
+ /** Id of the lane this one is a child lane of. */
567
+ parent?: string;
568
+ }
569
+ /**
570
+ * Lane bookkeeping shared by a process builder and its gateway branches (never by
571
+ * sub-process contents: nodes inside a sub-process are not lane members).
572
+ */
573
+ declare class LaneState {
574
+ /** Lane id -> name, in first-use order (top to bottom). */
575
+ readonly names: Map<string, string | undefined>;
576
+ readonly membership: Map<string, string>;
577
+ current: string | undefined;
578
+ declare(id: string, name?: string): void;
579
+ enter(id: string, name?: string): void;
580
+ record(el: BpmnFlowElement): void;
581
+ /** Runs `fn`, then puts back the lane that was current before it. */
582
+ scoped(fn: () => void): void;
583
+ /** The process's lane set, or undefined when no lane was used. */
584
+ toLaneSet(processId: string, elements: BpmnFlowElement[], inferredFrom: number): BpmnLaneSet | undefined;
585
+ }
537
586
  /**
538
587
  * The root-level messages, errors, signals and escalations of one process.
539
588
  *
@@ -550,12 +599,6 @@ interface RootDefinitions {
550
599
  /** Shared by every nested builder, so hints reach the process's `build()`. */
551
600
  layoutHints: Required<LayoutHints>;
552
601
  }
553
- /**
554
- * Builder for a single named branch path from a gateway.
555
- *
556
- * Use `.condition(expr)` to set a FEEL condition on the outgoing sequence
557
- * flow from the gateway, or `.defaultFlow()` to mark it as the default path.
558
- */
559
602
  export declare class BranchBuilder {
560
603
  /** @internal */
561
604
  readonly _elements: BpmnFlowElement[];
@@ -568,6 +611,8 @@ export declare class BranchBuilder {
568
611
  private lastNodeId;
569
612
  private readonly gatewayId;
570
613
  private readonly branchName;
614
+ /** False after a parallel or event-based gateway, whose outgoing flows Camunda lints as `superfluous-label` when named. */
615
+ private readonly nameFlow;
571
616
  private isFirstElement;
572
617
  private pendingCondition;
573
618
  private pendingLabel;
@@ -589,8 +634,10 @@ export declare class BranchBuilder {
589
634
  private readonly rootSignals;
590
635
  private readonly rootEscalations;
591
636
  private readonly rootLayoutHints;
637
+ /** Absent inside a sub-process, whose nodes are not lane members. */
638
+ private readonly lanes;
592
639
  /** @internal */
593
- constructor(gatewayId: string, branchName: string, rootErrors?: BpmnError[], rootMessages?: BpmnMessage[], rootSignals?: BpmnSignal[], rootEscalations?: BpmnEscalation[], rootLayoutHints?: Required<LayoutHints>);
640
+ constructor(gatewayId: string, branchName: string, rootErrors?: BpmnError[], rootMessages?: BpmnMessage[], rootSignals?: BpmnSignal[], rootEscalations?: BpmnEscalation[], rootLayoutHints?: Required<LayoutHints>, lanes?: LaneState, nameFlow?: boolean);
594
641
  private roots;
595
642
  /** Set a FEEL condition expression on this branch's outgoing sequence flow. */
596
643
  condition(expression: string): this;
@@ -605,6 +652,8 @@ export declare class BranchBuilder {
605
652
  defaultFlow(): this;
606
653
  /** Keeps label() and flowId() out of the stable-id derivation; see stable-ids.ts. */
607
654
  private registerFirstFlow;
655
+ /** Moves the rest of this branch (and branches nested in it) to a lane; undone when the branch ends. */
656
+ inLane(id: string, options?: LaneOptions): this;
608
657
  private addElement;
609
658
  /**
610
659
  * Connect the current position to an existing or future element by ID.
@@ -839,6 +888,11 @@ export declare class ProcessBuilder {
839
888
  private _pendingSpliceFlowId;
840
889
  /** Flows the caller deliberately spliced, exempt from the rewiring guard. */
841
890
  private readonly _splicedFlowIds;
891
+ /** `lane()` calls, in call order. */
892
+ private readonly _lanes;
893
+ /** Set by `participant()`: the pool this process is drawn in. */
894
+ private _participant?;
895
+ private readonly lanes;
842
896
  constructor(processId: string);
843
897
  private roots;
844
898
  /**
@@ -907,7 +961,11 @@ export declare class ProcessBuilder {
907
961
  }): this;
908
962
  /** Set the display name for this process. */
909
963
  name(name: string): this;
910
- /** Set whether this process is executable. */
964
+ /**
965
+ * Set whether this process is executable. Pass `false` for a partner pool the
966
+ * engine must not deploy: Flowable reads an absent `isExecutable` as
967
+ * executable, so a partner process has to say so explicitly.
968
+ */
911
969
  executable(value: boolean): this;
912
970
  /** Set the process version tag. */
913
971
  versionTag(tag: string): this;
@@ -1092,6 +1150,70 @@ export declare class ProcessBuilder {
1092
1150
  textAnnotation(text: string): this;
1093
1151
  /** Attach a text annotation to any flow element by explicit ID. */
1094
1152
  annotate(elementId: string, text: string, options?: AnnotateOptions): this;
1153
+ /**
1154
+ * Declares a swimlane, or a child lane of `options.parent`.
1155
+ *
1156
+ * Once any lane is declared, a fresh build puts every top-level flow node in
1157
+ * exactly one leaf lane and refuses otherwise, listing every problem at once
1158
+ * (`Invalid lanes:` …): an unknown or sub-process ref, a node listed twice,
1159
+ * flow nodes on a lane with child lanes, an undeclared or looping parent, a
1160
+ * lane id already in use, an unassigned node. Boundary events follow their
1161
+ * host, and an inferred join gateway the lane of its first predecessor.
1162
+ * Parent lanes list the union of their descendants' refs. Lanes imply a
1163
+ * pool: without {@link participant} the build adds `Participant_<processId>`,
1164
+ * named after the process.
1165
+ *
1166
+ * Continuing a document ({@link ProcessBuilder.from}) instead names one of its
1167
+ * existing leaf lanes: the listed nodes move there, `name` renames it, and a
1168
+ * new lane or a `parent` is refused. Nodes added in continue mode join the lane
1169
+ * of their predecessor (see `laneForNewNode`) without any `lane()` call.
1170
+ *
1171
+ * @param id - The lane's element id, used verbatim.
1172
+ * @example
1173
+ * ```typescript
1174
+ * Bpmn.createProcess("order")
1175
+ * .startEvent("start").userTask("review").serviceTask("ship", { taskType: "ship" }).endEvent("end")
1176
+ * .lane("Lane_sales", { name: "Sales", flowNodes: ["start", "review"] })
1177
+ * .lane("Lane_ops", { name: "Operations", flowNodes: ["ship", "end"] })
1178
+ * ```
1179
+ */
1180
+ lane(id: string, options?: DeclaredLaneOptions): this;
1181
+ /**
1182
+ * Names the pool this process is drawn in: the build writes a collaboration
1183
+ * with one participant `id` referencing this process, named `options.name`,
1184
+ * else the process name, else the process id. Without this call a process
1185
+ * gets a pool only when it has lanes.
1186
+ *
1187
+ * Continuing a document, `id` must be the process's existing pool, which
1188
+ * `name` renames; adding or replacing a pool there is refused.
1189
+ *
1190
+ * @param id - The participant's element id, used verbatim.
1191
+ */
1192
+ participant(id: string, options?: Omit<ParticipantOptions, "processId">): this;
1193
+ /**
1194
+ * Lanes and pool of a fresh build: `process` with its lane set, and the
1195
+ * collaboration `participant()` asked for. Both are returned untouched when
1196
+ * neither `lane()` nor `participant()` was called.
1197
+ *
1198
+ * @throws Error listing every lane and pool problem at once.
1199
+ */
1200
+ private freshSwimlanes;
1201
+ /**
1202
+ * Continue mode: new nodes join the lane `laneForNewNode` picks, then each
1203
+ * `lane()` call moves its nodes into, and renames, an existing leaf lane.
1204
+ * Existing refs are kept as they are, even ones a fresh build would refuse:
1205
+ * the document is the caller's.
1206
+ *
1207
+ * @throws Error listing every `lane()` call that cannot be applied.
1208
+ */
1209
+ private continueLanes;
1210
+ /**
1211
+ * Continue mode: `participant()` renames the pool that already references this
1212
+ * process.
1213
+ *
1214
+ * @throws Error when the process has no pool, or one with another id.
1215
+ */
1216
+ private continuePool;
1095
1217
  /**
1096
1218
  * Build the complete BPMN definitions model.
1097
1219
  *
@@ -1132,9 +1254,11 @@ export declare class ProcessBuilder {
1132
1254
  * Writes this process's contents back into the document it came from.
1133
1255
  *
1134
1256
  * Everything not listed here is kept by identity — other processes, the
1135
- * collaboration, diagram interchange, root elements, the process's own lanes,
1136
- * documentation, extensions and unmodelled content. That is the whole point of
1137
- * continuing rather than regenerating.
1257
+ * collaboration, diagram interchange, root elements, the process's existing
1258
+ * lane refs, documentation, extensions and unmodelled content. That is the
1259
+ * whole point of continuing rather than regenerating. The lanes change only
1260
+ * where nodes were added (each joins its predecessor's lane) or moved with
1261
+ * `lane()`; the pool only where `participant()` renames it.
1138
1262
  *
1139
1263
  * Diagram interchange is *not* regenerated: existing shapes keep their
1140
1264
  * positions, and elements added here have none until `placeNewShapes()` draws
@@ -1152,6 +1276,19 @@ export declare class ProcessBuilder {
1152
1276
  */
1153
1277
  private assertSourceTopologyIntact;
1154
1278
  private validate;
1279
+ /**
1280
+ * Puts the nodes that follow in lane `id`, declaring it on first use (top to
1281
+ * bottom in first-use order); a later call may name it. Inside a `branch()`
1282
+ * callback it changes the lane for that branch only. Once any lane is used,
1283
+ * every top-level flow node needs one, or `build()` throws.
1284
+ *
1285
+ * @example
1286
+ * ```ts
1287
+ * Bpmn.createProcess("p").inLane("sales", { name: "Sales" }).startEvent("s")
1288
+ * .inLane("ops").serviceTask("t", { taskType: "x" }).endEvent("e").build()
1289
+ * ```
1290
+ */
1291
+ inLane(id: string, options?: LaneOptions): this;
1155
1292
  private addFlowElement;
1156
1293
  }
1157
1294
  /**
@@ -1165,11 +1302,29 @@ export declare class DiagramBuilder {
1165
1302
  private readonly _messages;
1166
1303
  private readonly _participants;
1167
1304
  private readonly _messageFlows;
1305
+ /** Pools the processes brought along: `participant()` on the process, or the one lanes imply. */
1306
+ private readonly _processPools;
1307
+ private readonly _layoutHints;
1308
+ private _autoLayout;
1168
1309
  private _collaborationId;
1169
1310
  private _executionPlatformVersion;
1170
1311
  constructor(id: string);
1171
1312
  /** Set the Camunda execution platform version stamped into the BPMN definitions. Defaults to `"8.10.0"`. */
1172
1313
  executionPlatformVersion(version: string): this;
1314
+ /**
1315
+ * Adds a process built by `callback`.
1316
+ *
1317
+ * The process keeps its lanes, and its pool: the one `participant()` named on
1318
+ * the process builder, or the one its lanes imply. A `participant()` on this
1319
+ * diagram that references the same process replaces that pool.
1320
+ *
1321
+ * A process with no flow elements and no lanes, whose builder never called
1322
+ * `executable()`, is written `isExecutable: false`: it can only be the
1323
+ * process of a black-box partner pool, and Flowable would otherwise deploy
1324
+ * it, since it reads an absent attribute as executable. Every other process
1325
+ * keeps the builder's default, `true`; call `.executable(false)` on a partner
1326
+ * that has content.
1327
+ */
1173
1328
  process(id: string, callback: (b: ProcessBuilder) => void): this;
1174
1329
  /** Renames the collaboration element. Defaults to `"Collaboration_1"`. */
1175
1330
  collaborationId(id: string): this;
@@ -1206,12 +1361,11 @@ export declare class DiagramBuilder {
1206
1361
  */
1207
1362
  messageFlow(id: string, options: MessageFlowOptions): this;
1208
1363
  /**
1209
- * Reports every way the declared collaboration would not survive contact with
1210
- * a modeler, so `build()` can refuse rather than emit a file that opens broken.
1364
+ * Enable auto-layout: `build()` lays out the whole diagram (pools, lanes,
1365
+ * message flows and every process) and writes its diagram interchange, using
1366
+ * the layout hints each process builder recorded.
1211
1367
  */
1212
- private collaborationProblems;
1213
- /** Maps every participant id and every flow node id to its owning participant. */
1214
- private participantIndex;
1368
+ withAutoLayout(): this;
1215
1369
  /**
1216
1370
  * Build the document. Gated like {@link ProcessBuilder.build}: see
1217
1371
  * {@link BuildGateOptions}.