@bpmnkit/core 1.5.0 → 1.6.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 (39) hide show
  1. package/dist/bpmn/agentic.d.ts +9 -2
  2. package/dist/bpmn/agentic.js +8 -3
  3. package/dist/bpmn/auto-layout.d.ts +7 -2
  4. package/dist/bpmn/auto-layout.js +111 -7
  5. package/dist/bpmn/bpmn-builder.d.ts +65 -4
  6. package/dist/bpmn/bpmn-builder.js +126 -45
  7. package/dist/bpmn/compact.d.ts +24 -0
  8. package/dist/bpmn/compact.js +78 -4
  9. package/dist/bpmn/full-operations.js +20 -0
  10. package/dist/bpmn/optimize/patterns.js +2 -2
  11. package/dist/bpmn/optimize/variable-flow.d.ts +1 -0
  12. package/dist/bpmn/optimize/variable-flow.js +1 -1
  13. package/dist/bpmn/process-delta.d.ts +21 -1
  14. package/dist/bpmn/process-delta.js +33 -3
  15. package/dist/bpmn/process-text-writer.js +80 -6
  16. package/dist/bpmn/process-text.d.ts +22 -1
  17. package/dist/bpmn/process-text.js +268 -9
  18. package/dist/bpmn/stable-ids.d.ts +11 -0
  19. package/dist/bpmn/stable-ids.js +76 -10
  20. package/dist/connectors/apply-many.d.ts +49 -0
  21. package/dist/connectors/apply-many.js +162 -0
  22. package/dist/connectors/index.d.ts +2 -0
  23. package/dist/connectors/index.js +1 -0
  24. package/dist/connectors/lines.d.ts +1 -1
  25. package/dist/connectors/lines.js +13 -3
  26. package/dist/connectors/select.d.ts +2 -0
  27. package/dist/connectors/select.js +11 -0
  28. package/dist/index.d.ts +3 -3
  29. package/dist/layout/annotations.d.ts +3 -1
  30. package/dist/layout/annotations.js +11 -4
  31. package/dist/layout/index.d.ts +1 -1
  32. package/dist/layout/layout-engine.d.ts +4 -2
  33. package/dist/layout/layout-engine.js +4 -2
  34. package/dist/layout/semantic/index.d.ts +7 -3
  35. package/dist/layout/semantic/index.js +11 -7
  36. package/dist/layout/semantic/place.d.ts +4 -2
  37. package/dist/layout/semantic/place.js +12 -9
  38. package/dist/layout/types.d.ts +18 -0
  39. package/package.json +2 -2
@@ -3,7 +3,7 @@ import { generateId } from "../types/id-generator.js";
3
3
  import { applyAutoLayout } from "./auto-layout.js";
4
4
  import { createFlowElement } from "./element-shape.js";
5
5
  import { REST_CONNECTOR_TEMPLATE_VERSION, restConnectorRetries, restConnectorTaskType, restConnectorToIoMappingInputs, restConnectorToTaskHeaders, } from "./rest-connector.js";
6
- import { assignStableFlowIds, rootDefinitionId } from "./stable-ids.js";
6
+ import { assertExplicitFlowIdsUnique, assignStableFlowIds, markExplicitFlowId, rootDefinitionId, setFlowDiscriminatorSource, } from "./stable-ids.js";
7
7
  import { ensureZeebeExtension, zeebeExtensionsToXmlElements, } from "./zeebe-extensions.js";
8
8
  // Keep in sync with packages/core/package.json version
9
9
  const EXPORTER_VERSION = "0.0.23";
@@ -254,13 +254,9 @@ function recomputeIncomingOutgoing(elements, flows) {
254
254
  elementMap.get(flow.targetRef)?.incoming.push(flow.id);
255
255
  }
256
256
  }
257
- function buildServiceTaskExtensions(options) {
258
- const extensions = {
259
- taskDefinition: {
260
- type: options.taskType,
261
- retries: options.retries,
262
- },
263
- };
257
+ /** The ioMapping / taskHeaders / properties extensions shared by service and user tasks. */
258
+ function buildMappingExtensions(options) {
259
+ const extensions = {};
264
260
  if (options.ioMapping) {
265
261
  extensions.ioMapping = {
266
262
  inputs: options.ioMapping.inputs ?? [],
@@ -278,6 +274,16 @@ function buildServiceTaskExtensions(options) {
278
274
  if (options.zeebeProperties) {
279
275
  extensions.properties = { properties: options.zeebeProperties };
280
276
  }
277
+ return extensions;
278
+ }
279
+ function buildServiceTaskExtensions(options) {
280
+ const extensions = {
281
+ taskDefinition: {
282
+ type: options.taskType,
283
+ retries: options.retries,
284
+ },
285
+ ...buildMappingExtensions(options),
286
+ };
281
287
  if (options.agentDefinition)
282
288
  extensions.agentDefinition = options.agentDefinition;
283
289
  return zeebeExtensionsToXmlElements(extensions);
@@ -395,6 +401,30 @@ function makeScriptTaskEl(id, options) {
395
401
  el.isForCompensation = true;
396
402
  return el;
397
403
  }
404
+ function applyModelerTemplate(el, options) {
405
+ if (options.modelerTemplate)
406
+ el.unknownAttributes["zeebe:modelerTemplate"] = options.modelerTemplate;
407
+ if (options.modelerTemplateVersion) {
408
+ el.unknownAttributes["zeebe:modelerTemplateVersion"] = options.modelerTemplateVersion;
409
+ }
410
+ if (options.modelerTemplateIcon) {
411
+ el.unknownAttributes["zeebe:modelerTemplateIcon"] = options.modelerTemplateIcon;
412
+ }
413
+ }
414
+ /** Start-event shell shared by all three builders; the caller adds event definitions. */
415
+ function makeStartEventEl(id, options) {
416
+ const el = makeFlowElement(id, "startEvent", {
417
+ name: options?.name,
418
+ documentation: options?.documentation,
419
+ extensionElements: zeebeExtensionsToXmlElements({
420
+ ...(options?.formId ? { formDefinition: { formId: options.formId } } : {}),
421
+ ...(options?.zeebeProperties ? { properties: { properties: options.zeebeProperties } } : {}),
422
+ }),
423
+ });
424
+ if (options)
425
+ applyModelerTemplate(el, options);
426
+ return el;
427
+ }
398
428
  function makeUserTaskEl(id, options) {
399
429
  const ext = zeebeExtensionsToXmlElements({
400
430
  ...(options?.zeebeUserTask ? { userTask: true } : {}),
@@ -414,12 +444,15 @@ function makeUserTaskEl(id, options) {
414
444
  ...(options?.priority !== undefined
415
445
  ? { priorityDefinition: { priority: String(options.priority) } }
416
446
  : {}),
447
+ ...(options ? buildMappingExtensions(options) : {}),
417
448
  });
418
449
  const el = makeFlowElement(id, "userTask", {
419
450
  name: options?.name,
420
451
  documentation: options?.documentation,
421
452
  extensionElements: ext,
422
453
  });
454
+ if (options)
455
+ applyModelerTemplate(el, options);
423
456
  if (options?.isForCompensation)
424
457
  el.isForCompensation = true;
425
458
  return el;
@@ -531,6 +564,19 @@ function resolveBoundaryEventArgs(id, attachedToOrOptions, maybeOptions) {
531
564
  }
532
565
  return options;
533
566
  }
567
+ function emptyLayoutHints() {
568
+ return { grids: new Map(), annotationSides: new Map() };
569
+ }
570
+ /** Remembers an ad-hoc sub-process's `toolGrid` for the layout. */
571
+ function recordToolGrid(hints, id, options) {
572
+ const grid = options?.toolGrid;
573
+ if (!grid)
574
+ return;
575
+ if (grid.columns !== undefined && !(Number.isInteger(grid.columns) && grid.columns > 0)) {
576
+ throw new Error(`adHocSubProcess("${id}"): toolGrid.columns must be a positive integer, got ${grid.columns}`);
577
+ }
578
+ hints.grids.set(id, grid);
579
+ }
534
580
  /**
535
581
  * Build a transaction element from a content callback.
536
582
  *
@@ -686,6 +732,8 @@ export class BranchBuilder {
686
732
  branchName;
687
733
  isFirstElement = true;
688
734
  pendingCondition;
735
+ pendingLabel;
736
+ pendingFlowId;
689
737
  pendingDefault = false;
690
738
  /** @internal – true once connectTo() has been called, meaning the branch end is already wired */
691
739
  _connected = false;
@@ -702,8 +750,9 @@ export class BranchBuilder {
702
750
  rootMessages;
703
751
  rootSignals;
704
752
  rootEscalations;
753
+ rootLayoutHints;
705
754
  /** @internal */
706
- constructor(gatewayId, branchName, rootErrors = [], rootMessages = [], rootSignals = [], rootEscalations = []) {
755
+ constructor(gatewayId, branchName, rootErrors = [], rootMessages = [], rootSignals = [], rootEscalations = [], rootLayoutHints = emptyLayoutHints()) {
707
756
  this.gatewayId = gatewayId;
708
757
  this.branchName = branchName;
709
758
  this.lastNodeId = gatewayId;
@@ -711,6 +760,7 @@ export class BranchBuilder {
711
760
  this.rootMessages = rootMessages;
712
761
  this.rootSignals = rootSignals;
713
762
  this.rootEscalations = rootEscalations;
763
+ this.rootLayoutHints = rootLayoutHints;
714
764
  }
715
765
  roots() {
716
766
  return {
@@ -718,6 +768,7 @@ export class BranchBuilder {
718
768
  messages: this.rootMessages,
719
769
  signals: this.rootSignals,
720
770
  escalations: this.rootEscalations,
771
+ layoutHints: this.rootLayoutHints,
721
772
  };
722
773
  }
723
774
  /** Set a FEEL condition expression on this branch's outgoing sequence flow. */
@@ -725,11 +776,30 @@ export class BranchBuilder {
725
776
  this.pendingCondition = expression;
726
777
  return this;
727
778
  }
779
+ /**
780
+ * Set the name shown on this branch's first flow. Without it the branch id is
781
+ * the name. The generated flow id still follows the branch id, not the label.
782
+ */
783
+ label(text) {
784
+ this.pendingLabel = text;
785
+ return this;
786
+ }
787
+ /** Use `id` for this branch's first flow instead of a generated one. */
788
+ flowId(id) {
789
+ this.pendingFlowId = id;
790
+ return this;
791
+ }
728
792
  /** Mark this branch as the gateway's default (no-condition) flow. */
729
793
  defaultFlow() {
730
794
  this.pendingDefault = true;
731
795
  return this;
732
796
  }
797
+ /** Keeps label() and flowId() out of the stable-id derivation; see stable-ids.ts. */
798
+ registerFirstFlow(flow) {
799
+ setFlowDiscriminatorSource(flow, this.branchName);
800
+ if (this.pendingFlowId !== undefined)
801
+ markExplicitFlowId(flow);
802
+ }
733
803
  addElement(element) {
734
804
  this._elements.push(element);
735
805
  this._ids.add(element.id);
@@ -739,12 +809,14 @@ export class BranchBuilder {
739
809
  return this;
740
810
  }
741
811
  if (this.lastNodeId) {
742
- const flowId = generateId("Flow");
812
+ const flowId = this.isFirstElement
813
+ ? (this.pendingFlowId ?? generateId("Flow"))
814
+ : generateId("Flow");
743
815
  const flow = {
744
816
  id: flowId,
745
817
  sourceRef: this.lastNodeId,
746
818
  targetRef: element.id,
747
- name: this.isFirstElement ? this.branchName : undefined,
819
+ name: this.isFirstElement ? (this.pendingLabel ?? this.branchName) : undefined,
748
820
  conditionExpression: this.isFirstElement && this.pendingCondition
749
821
  ? makeConditionExpression(this.pendingCondition)
750
822
  : undefined,
@@ -752,6 +824,8 @@ export class BranchBuilder {
752
824
  unknownAttributes: {},
753
825
  };
754
826
  this._flows.push(flow);
827
+ if (this.isFirstElement)
828
+ this.registerFirstFlow(flow);
755
829
  if (this.isFirstElement && this.pendingDefault) {
756
830
  this._defaultFlowId = flowId;
757
831
  }
@@ -775,13 +849,15 @@ export class BranchBuilder {
775
849
  * Supports forward references (element created later) and backward references (loops).
776
850
  */
777
851
  connectTo(targetId) {
778
- const flowId = generateId("Flow");
852
+ const flowId = this.isFirstElement
853
+ ? (this.pendingFlowId ?? generateId("Flow"))
854
+ : generateId("Flow");
779
855
  const flow = {
780
856
  id: flowId,
781
857
  // biome-ignore lint/style/noNonNullAssertion: lastNodeId starts as gatewayId and is always defined in pre-branch context
782
858
  sourceRef: this.lastNodeId,
783
859
  targetRef: targetId,
784
- name: this.isFirstElement ? this.branchName : undefined,
860
+ name: this.isFirstElement ? (this.pendingLabel ?? this.branchName) : undefined,
785
861
  conditionExpression: this.isFirstElement && this.pendingCondition
786
862
  ? makeConditionExpression(this.pendingCondition)
787
863
  : undefined,
@@ -789,6 +865,8 @@ export class BranchBuilder {
789
865
  unknownAttributes: {},
790
866
  };
791
867
  this._flows.push(flow);
868
+ if (this.isFirstElement)
869
+ this.registerFirstFlow(flow);
792
870
  if (this.isFirstElement && this.pendingDefault) {
793
871
  this._defaultFlowId = flowId;
794
872
  }
@@ -812,10 +890,12 @@ export class BranchBuilder {
812
890
  return this.annotate(this.lastNodeId, text);
813
891
  }
814
892
  /** Attach a text annotation to an element by explicit ID. */
815
- annotate(elementId, text) {
893
+ annotate(elementId, text, options) {
816
894
  const n = (this._annCounters.get(elementId) ?? 0) + 1;
817
895
  this._annCounters.set(elementId, n);
818
896
  const annId = `TextAnnotation_${elementId}_${n}`;
897
+ if (options?.side)
898
+ this.rootLayoutHints.annotationSides.set(annId, options.side);
819
899
  this._textAnnotations.push({ id: annId, text, unknownAttributes: {} });
820
900
  this._associations.push({
821
901
  id: `Association_${elementId}_${n}`,
@@ -876,7 +956,7 @@ export class BranchBuilder {
876
956
  return this.addElement(el);
877
957
  }
878
958
  startEvent(id, options) {
879
- const el = makeFlowElement(id ?? generateId("StartEvent"), "startEvent", options);
959
+ const el = makeStartEventEl(id ?? generateId("StartEvent"), options);
880
960
  if (el.type === "startEvent" && options) {
881
961
  el.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
882
962
  }
@@ -1018,6 +1098,7 @@ export class BranchBuilder {
1018
1098
  */
1019
1099
  adHocSubProcess(id, content, options) {
1020
1100
  const resolved = resolveSubProcessArgs(content, options);
1101
+ recordToolGrid(this.rootLayoutHints, id, resolved.options);
1021
1102
  // Ad-hoc sub-process children are unordered — see SubProcessContentBuilder.autoConnect.
1022
1103
  const sub = new SubProcessContentBuilder(this.roots(), false);
1023
1104
  resolved.content(sub);
@@ -1065,7 +1146,7 @@ export class BranchBuilder {
1065
1146
  if (!this.currentGatewayId) {
1066
1147
  throw new Error("branch() must be called after a gateway element");
1067
1148
  }
1068
- const b = new BranchBuilder(this.currentGatewayId, name, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
1149
+ const b = new BranchBuilder(this.currentGatewayId, name, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations, this.rootLayoutHints);
1069
1150
  callback(b);
1070
1151
  for (const el of b._elements) {
1071
1152
  if (this._ids.has(el.id)) {
@@ -1125,6 +1206,7 @@ export class SubProcessContentBuilder {
1125
1206
  rootMessages;
1126
1207
  rootSignals;
1127
1208
  rootEscalations;
1209
+ rootLayoutHints;
1128
1210
  /**
1129
1211
  * Whether sequential calls chain themselves with sequence flows.
1130
1212
  *
@@ -1138,11 +1220,18 @@ export class SubProcessContentBuilder {
1138
1220
  */
1139
1221
  autoConnect;
1140
1222
  /** @internal */
1141
- constructor(roots = { errors: [], messages: [], signals: [], escalations: [] }, autoConnect = true) {
1223
+ constructor(roots = {
1224
+ errors: [],
1225
+ messages: [],
1226
+ signals: [],
1227
+ escalations: [],
1228
+ layoutHints: emptyLayoutHints(),
1229
+ }, autoConnect = true) {
1142
1230
  this.rootErrors = roots.errors;
1143
1231
  this.rootMessages = roots.messages;
1144
1232
  this.rootSignals = roots.signals;
1145
1233
  this.rootEscalations = roots.escalations;
1234
+ this.rootLayoutHints = roots.layoutHints;
1146
1235
  this.autoConnect = autoConnect;
1147
1236
  }
1148
1237
  roots() {
@@ -1151,6 +1240,7 @@ export class SubProcessContentBuilder {
1151
1240
  messages: this.rootMessages,
1152
1241
  signals: this.rootSignals,
1153
1242
  escalations: this.rootEscalations,
1243
+ layoutHints: this.rootLayoutHints,
1154
1244
  };
1155
1245
  }
1156
1246
  addElement(element) {
@@ -1203,7 +1293,7 @@ export class SubProcessContentBuilder {
1203
1293
  }
1204
1294
  // ---- Events ----
1205
1295
  startEvent(id, options) {
1206
- const el = makeFlowElement(id ?? generateId("StartEvent"), "startEvent", options);
1296
+ const el = makeStartEventEl(id ?? generateId("StartEvent"), options);
1207
1297
  if (el.type === "startEvent" && options) {
1208
1298
  el.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
1209
1299
  if (options.isInterrupting === false)
@@ -1311,10 +1401,12 @@ export class SubProcessContentBuilder {
1311
1401
  return this.annotate(this.lastNodeId, text);
1312
1402
  }
1313
1403
  /** Attach a text annotation to an element by explicit ID. */
1314
- annotate(elementId, text) {
1404
+ annotate(elementId, text, options) {
1315
1405
  const n = (this._annCounters.get(elementId) ?? 0) + 1;
1316
1406
  this._annCounters.set(elementId, n);
1317
1407
  const annId = `TextAnnotation_${elementId}_${n}`;
1408
+ if (options?.side)
1409
+ this.rootLayoutHints.annotationSides.set(annId, options.side);
1318
1410
  this._textAnnotations.push({ id: annId, text, unknownAttributes: {} });
1319
1411
  this._associations.push({
1320
1412
  id: `Association_${elementId}_${n}`,
@@ -1330,7 +1422,7 @@ export class SubProcessContentBuilder {
1330
1422
  if (!this.currentGatewayId) {
1331
1423
  throw new Error("branch() must be called after a gateway element");
1332
1424
  }
1333
- const b = new BranchBuilder(this.currentGatewayId, name, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
1425
+ const b = new BranchBuilder(this.currentGatewayId, name, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations, this.rootLayoutHints);
1334
1426
  callback(b);
1335
1427
  for (const el of b._elements) {
1336
1428
  if (this._ids.has(el.id)) {
@@ -1477,6 +1569,7 @@ export class SubProcessContentBuilder {
1477
1569
  */
1478
1570
  adHocSubProcess(id, content, options) {
1479
1571
  const resolved = resolveSubProcessArgs(content, options);
1572
+ recordToolGrid(this.rootLayoutHints, id, resolved.options);
1480
1573
  // Ad-hoc sub-process children are unordered — see SubProcessContentBuilder.autoConnect.
1481
1574
  const sub = new SubProcessContentBuilder(this.roots(), false);
1482
1575
  resolved.content(sub);
@@ -1533,6 +1626,7 @@ export class ProcessBuilder {
1533
1626
  rootMessages = [];
1534
1627
  rootSignals = [];
1535
1628
  rootEscalations = [];
1629
+ rootLayoutHints = emptyLayoutHints();
1536
1630
  _textAnnotations = [];
1537
1631
  _associations = [];
1538
1632
  _annCounters = new Map();
@@ -1560,6 +1654,7 @@ export class ProcessBuilder {
1560
1654
  messages: this.rootMessages,
1561
1655
  signals: this.rootSignals,
1562
1656
  escalations: this.rootEscalations,
1657
+ layoutHints: this.rootLayoutHints,
1563
1658
  };
1564
1659
  }
1565
1660
  /**
@@ -1794,32 +1889,12 @@ export class ProcessBuilder {
1794
1889
  // ---- Events ----
1795
1890
  /** Add a start event. Start events never auto-connect from the previous element. */
1796
1891
  startEvent(id, options) {
1797
- const nodeId = id ?? generateId("StartEvent");
1798
- const extElements = [];
1799
- if (options?.zeebeProperties) {
1800
- extElements.push(...zeebeExtensionsToXmlElements({
1801
- properties: { properties: options.zeebeProperties },
1802
- }));
1803
- }
1804
- const element = makeFlowElement(nodeId, "startEvent", {
1805
- name: options?.name,
1806
- documentation: options?.documentation,
1807
- extensionElements: extElements,
1808
- });
1892
+ const element = makeStartEventEl(id ?? generateId("StartEvent"), options);
1809
1893
  if (element.type === "startEvent" && options) {
1810
1894
  element.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
1811
1895
  if (options.isInterrupting === false)
1812
1896
  element.isInterrupting = false;
1813
1897
  }
1814
- if (options?.modelerTemplate) {
1815
- element.unknownAttributes["zeebe:modelerTemplate"] = options.modelerTemplate;
1816
- }
1817
- if (options?.modelerTemplateVersion) {
1818
- element.unknownAttributes["zeebe:modelerTemplateVersion"] = options.modelerTemplateVersion;
1819
- }
1820
- if (options?.modelerTemplateIcon) {
1821
- element.unknownAttributes["zeebe:modelerTemplateIcon"] = options.modelerTemplateIcon;
1822
- }
1823
1898
  this.addFlowElement(element);
1824
1899
  return this;
1825
1900
  }
@@ -2082,7 +2157,7 @@ export class ProcessBuilder {
2082
2157
  if (!this.currentGatewayId) {
2083
2158
  throw new Error("branch() must be called after a gateway element");
2084
2159
  }
2085
- const b = new BranchBuilder(this.currentGatewayId, name, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
2160
+ const b = new BranchBuilder(this.currentGatewayId, name, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations, this.rootLayoutHints);
2086
2161
  callback(b);
2087
2162
  for (const el of b._elements) {
2088
2163
  if (this.elementIds.has(el.id)) {
@@ -2163,6 +2238,7 @@ export class ProcessBuilder {
2163
2238
  */
2164
2239
  adHocSubProcess(id, content, options) {
2165
2240
  const resolved = resolveSubProcessArgs(content, options);
2241
+ recordToolGrid(this.rootLayoutHints, id, resolved.options);
2166
2242
  // Ad-hoc sub-process children are unordered — see SubProcessContentBuilder.autoConnect.
2167
2243
  const sub = new SubProcessContentBuilder(this.roots(), false);
2168
2244
  resolved.content(sub);
@@ -2236,10 +2312,12 @@ export class ProcessBuilder {
2236
2312
  return this.annotate(this.lastNodeId, text);
2237
2313
  }
2238
2314
  /** Attach a text annotation to any flow element by explicit ID. */
2239
- annotate(elementId, text) {
2315
+ annotate(elementId, text, options) {
2240
2316
  const n = (this._annCounters.get(elementId) ?? 0) + 1;
2241
2317
  this._annCounters.set(elementId, n);
2242
2318
  const annId = `TextAnnotation_${elementId}_${n}`;
2319
+ if (options?.side)
2320
+ this.rootLayoutHints.annotationSides.set(annId, options.side);
2243
2321
  this._textAnnotations.push({ id: annId, text, unknownAttributes: {} });
2244
2322
  this._associations.push({
2245
2323
  id: `Association_${elementId}_${n}`,
@@ -2299,6 +2377,7 @@ export class ProcessBuilder {
2299
2377
  // Flows the document already had keep their ids: continuing a model must
2300
2378
  // not renumber the part the caller did not touch.
2301
2379
  assignStableFlowIds(this.flowElements, this.sequenceFlows, this._source === undefined ? undefined : new Set(this._sourceFlowTargets.keys()));
2380
+ assertExplicitFlowIdsUnique(this.flowElements, this.sequenceFlows);
2302
2381
  recomputeIncomingOutgoing(this.flowElements, this.sequenceFlows);
2303
2382
  if (this._source !== undefined)
2304
2383
  return this.buildOntoSource(this._source);
@@ -2361,7 +2440,7 @@ export class ProcessBuilder {
2361
2440
  ]
2362
2441
  : [],
2363
2442
  };
2364
- return hoistMessageSubscriptions(this._autoLayout ? applyAutoLayout(defs) : defs);
2443
+ return hoistMessageSubscriptions(this._autoLayout ? applyAutoLayout(defs, "semantic", this.rootLayoutHints) : defs);
2365
2444
  }
2366
2445
  /**
2367
2446
  * Writes this process's contents back into the document it came from.
@@ -2397,7 +2476,9 @@ export class ProcessBuilder {
2397
2476
  definitions.messages = this.rootMessages;
2398
2477
  definitions.signals = this.rootSignals;
2399
2478
  definitions.escalations = this.rootEscalations;
2400
- return hoistMessageSubscriptions(this._autoLayout ? applyAutoLayout(definitions) : definitions);
2479
+ return hoistMessageSubscriptions(this._autoLayout
2480
+ ? applyAutoLayout(definitions, "semantic", this.rootLayoutHints)
2481
+ : definitions);
2401
2482
  }
2402
2483
  /**
2403
2484
  * Refuses to rewire a flow that was already in the document.
@@ -28,6 +28,13 @@ export interface CompactElement {
28
28
  * optionally `headers`, `queryParameters`, `body`, `authentication.type`.
29
29
  */
30
30
  inputs?: Record<string, string>;
31
+ /** Zeebe output mappings (target→source), read like {@link inputs}. */
32
+ outputs?: Record<string, string>;
33
+ /**
34
+ * Marks a user task as a Camunda 8 native one (`zeebe:userTask`), which a linked
35
+ * form needs from Camunda 8.10.
36
+ */
37
+ nativeUserTask?: boolean;
31
38
  /** The element template applied to this element (`zeebe:modelerTemplate`). */
32
39
  modelerTemplate?: {
33
40
  id: string;
@@ -97,6 +104,12 @@ export interface CompactFlow {
97
104
  */
98
105
  isDefault?: boolean;
99
106
  }
107
+ /** A text annotation and the element it is associated with. */
108
+ export interface CompactNote {
109
+ /** The annotated element, at any depth of the process. */
110
+ elementId: string;
111
+ text: string;
112
+ }
100
113
  /** A single process in compact form. */
101
114
  export interface CompactProcess {
102
115
  id: string;
@@ -105,6 +118,12 @@ export interface CompactProcess {
105
118
  documentation?: string;
106
119
  elements: CompactElement[];
107
120
  flows: CompactFlow[];
121
+ /**
122
+ * Text annotations, each tied to an element by an association. {@link expand}
123
+ * puts them on the process and lays them out; {@link compactify} does not
124
+ * produce them.
125
+ */
126
+ notes?: CompactNote[];
108
127
  }
109
128
  /**
110
129
  * Token-efficient representation of a {@link BpmnDefinitions} document.
@@ -123,6 +142,11 @@ export interface CompactProcess {
123
142
  */
124
143
  export interface CompactDiagram {
125
144
  id: string;
145
+ /**
146
+ * The Camunda 8 version the diagram targets, such as `8.10.0`. {@link expand}
147
+ * writes it as `modeler:executionPlatformVersion`; without it none is written.
148
+ */
149
+ executionPlatformVersion?: string;
126
150
  processes: CompactProcess[];
127
151
  }
128
152
  /**
@@ -1,5 +1,7 @@
1
+ import { packAnnotations } from "../layout/annotations.js";
1
2
  import { layoutProcess } from "../layout/index.js";
2
3
  import { assertBpmnDefinitions, assertCompactDiagram } from "./argument-guards.js";
4
+ import { addAnnotationShapes } from "./auto-layout.js";
3
5
  import { restConnectorTaskType } from "./rest-connector.js";
4
6
  // ── Default flows ────────────────────────────────────────────────────────────
5
7
  /**
@@ -115,6 +117,18 @@ function compactifyElement(el) {
115
117
  }
116
118
  if (Object.keys(inputs).length > 0)
117
119
  result.inputs = inputs;
120
+ // `source: "= response"` is the job worker's result, which expand writes back from `resultVariable`.
121
+ const outputs = {};
122
+ for (const output of ext.find((e) => e.name === "zeebe:ioMapping")?.children ?? []) {
123
+ const { source, target } = output.attributes;
124
+ if (output.name !== "zeebe:output" || source === undefined || target === undefined)
125
+ continue;
126
+ if (result.jobType !== undefined && source === "= response")
127
+ continue;
128
+ outputs[target] = source;
129
+ }
130
+ if (Object.keys(outputs).length > 0)
131
+ result.outputs = outputs;
118
132
  const template = el.unknownAttributes["zeebe:modelerTemplate"];
119
133
  if (template) {
120
134
  const version = Number.parseInt(el.unknownAttributes["zeebe:modelerTemplateVersion"] ?? "", 10);
@@ -238,6 +252,8 @@ const EVENT_TYPES = new Set([
238
252
  function compactProblems(compact) {
239
253
  const problems = [];
240
254
  const seen = new Set();
255
+ /** Every element id, at any depth: what a note may name. */
256
+ const elementIds = new Set();
241
257
  const claim = (id, what) => {
242
258
  if (seen.has(id))
243
259
  problems.push(`duplicate id "${id}" (${what})`);
@@ -252,6 +268,7 @@ function compactProblems(compact) {
252
268
  }
253
269
  claim(el.id, el.type);
254
270
  ids.add(el.id);
271
+ elementIds.add(el.id);
255
272
  if (el.eventType !== undefined && !EVENT_TYPES.has(el.eventType)) {
256
273
  problems.push(`element "${el.id}" has unknown eventType "${el.eventType}" (expected one of ${[...EVENT_TYPES].join(", ")})`);
257
274
  }
@@ -280,6 +297,11 @@ function compactProblems(compact) {
280
297
  for (const process of compact.processes) {
281
298
  claim(process.id, "process");
282
299
  checkScope(process.elements, process.flows, `process "${process.id}"`);
300
+ for (const note of process.notes ?? []) {
301
+ if (!elementIds.has(note.elementId)) {
302
+ problems.push(`a note is on "${note.elementId}", which is not an element in the diagram`);
303
+ }
304
+ }
283
305
  }
284
306
  return problems;
285
307
  }
@@ -375,6 +397,9 @@ export function makeExtensions(el) {
375
397
  children: [],
376
398
  });
377
399
  }
400
+ if (el.nativeUserTask && el.type === "userTask") {
401
+ ext.push({ name: "zeebe:userTask", attributes: {}, children: [] });
402
+ }
378
403
  if (el.formId) {
379
404
  ext.push({ name: "zeebe:formDefinition", attributes: { formId: el.formId }, children: [] });
380
405
  }
@@ -400,7 +425,14 @@ export function makeExtensions(el) {
400
425
  attributes: { source, target },
401
426
  children: [],
402
427
  }));
403
- if (el.resultVariable && el.jobType && !el.decisionId && !isConnectorJobType(el.jobType)) {
428
+ for (const [target, source] of Object.entries(el.outputs ?? {})) {
429
+ ioMapping.push({ name: "zeebe:output", attributes: { source, target }, children: [] });
430
+ }
431
+ if (el.resultVariable &&
432
+ el.jobType &&
433
+ !el.decisionId &&
434
+ !isConnectorJobType(el.jobType) &&
435
+ el.outputs?.[el.resultVariable] === undefined) {
404
436
  // A job worker's result: map its `response` variable to the result variable
405
437
  ioMapping.push({
406
438
  name: "zeebe:output",
@@ -588,6 +620,24 @@ function buildDiagram(processId, process) {
588
620
  waypoints: e.waypoints,
589
621
  unknownAttributes: {},
590
622
  }));
623
+ if (process.textAnnotations.length > 0) {
624
+ // An annotation may sit above the topmost shape; the plane keeps to the positive quadrant.
625
+ const placed = packAnnotations(process, layout.nodes, layout.edges);
626
+ addAnnotationShapes(process, layout.nodes, placed, shapes, edges, 0, 0);
627
+ const dx = -Math.min(0, ...shapes.map((s) => s.bounds.x));
628
+ const dy = -Math.min(0, ...shapes.map((s) => s.bounds.y));
629
+ if (dx !== 0 || dy !== 0) {
630
+ for (const shape of shapes) {
631
+ shape.bounds = { ...shape.bounds, x: shape.bounds.x + dx, y: shape.bounds.y + dy };
632
+ const label = shape.label?.bounds;
633
+ if (label)
634
+ shape.label = { bounds: { ...label, x: label.x + dx, y: label.y + dy } };
635
+ }
636
+ for (const edge of edges) {
637
+ edge.waypoints = edge.waypoints.map((w) => ({ x: w.x + dx, y: w.y + dy }));
638
+ }
639
+ }
640
+ }
591
641
  return {
592
642
  id: `BPMNDiagram_${processId}`,
593
643
  plane: {
@@ -620,6 +670,23 @@ function expandProcess(compact) {
620
670
  extensionElements: [],
621
671
  unknownAttributes: {},
622
672
  }));
673
+ // Ids as the builder's `annotate` makes them, numbered per element
674
+ const textAnnotations = [];
675
+ const associations = [];
676
+ const noted = new Map();
677
+ for (const note of compact.notes ?? []) {
678
+ const n = (noted.get(note.elementId) ?? 0) + 1;
679
+ noted.set(note.elementId, n);
680
+ const id = `TextAnnotation_${note.elementId}_${n}`;
681
+ textAnnotations.push({ id, text: note.text, unknownAttributes: {} });
682
+ associations.push({
683
+ id: `Association_${note.elementId}_${n}`,
684
+ sourceRef: note.elementId,
685
+ targetRef: id,
686
+ associationDirection: "None",
687
+ unknownAttributes: {},
688
+ });
689
+ }
623
690
  const process = {
624
691
  id: compact.id,
625
692
  name: compact.name,
@@ -628,8 +695,8 @@ function expandProcess(compact) {
628
695
  extensionElements: [],
629
696
  flowElements,
630
697
  sequenceFlows,
631
- textAnnotations: [],
632
- associations: [],
698
+ textAnnotations,
699
+ associations,
633
700
  groups: [],
634
701
  unknownAttributes: {},
635
702
  };
@@ -664,6 +731,7 @@ export function expand(compact) {
664
731
  processes.push(process);
665
732
  diagrams.push(diagram);
666
733
  }
734
+ const platform = compact.executionPlatformVersion;
667
735
  return {
668
736
  id: compact.id,
669
737
  targetNamespace: "http://bpmn.io/schema/bpmn",
@@ -673,8 +741,14 @@ export function expand(compact) {
673
741
  dc: "http://www.omg.org/spec/DD/20100524/DC",
674
742
  di: "http://www.omg.org/spec/DD/20100524/DI",
675
743
  zeebe: "http://camunda.org/schema/zeebe/1.0",
744
+ ...(platform === undefined ? {} : { modeler: "http://camunda.org/schema/modeler/1.0" }),
676
745
  },
677
- unknownAttributes: {},
746
+ unknownAttributes: platform === undefined
747
+ ? {}
748
+ : {
749
+ "modeler:executionPlatform": "Camunda Cloud",
750
+ "modeler:executionPlatformVersion": platform,
751
+ },
678
752
  errors: [],
679
753
  escalations: [],
680
754
  messages: [],