@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
@@ -105,17 +105,24 @@ export interface AiAgentOptions {
105
105
  }
106
106
  /** The two pieces `adHocSubProcess(id, content, options)` needs to build the agent. */
107
107
  export interface AiAgentBuild {
108
+ /** Echoes `AiAgentOptions.id`, the element id to pass to `.adHocSubProcess()`. */
109
+ id: string;
108
110
  content: (b: SubProcessContentBuilder) => void;
109
111
  options: AdHocSubProcessOptions;
110
112
  }
111
113
  /**
112
114
  * Builds the ad-hoc sub-process content callback + options for the Camunda 8
113
- * AI Agent Sub-process connector. Feed the result into `.adHocSubProcess()`:
115
+ * AI Agent connector. Feed the result into `.adHocSubProcess()`:
114
116
  *
115
117
  * ```ts
116
118
  * const agent = buildAiAgentSubProcess({ ... })
117
- * builder.adHocSubProcess(agent.options.id ?? "Agent_1", agent.content, agent.options)
119
+ * builder.adHocSubProcess(agent.id, agent.content, agent.options)
118
120
  * ```
121
+ *
122
+ * This helper builds the v1 job-worker agent (`io.camunda.agenticai:aiagent-job-worker:1`).
123
+ * For the `io.camunda.connectors.agenticai.ai-agent-subprocess.v2` template of Camunda 8.10,
124
+ * build the ad-hoc sub-process yourself and apply that template after `build()` with
125
+ * `applyTemplates` from `@bpmnkit/core/connectors`.
119
126
  */
120
127
  export declare function buildAiAgentSubProcess(opts: AiAgentOptions): AiAgentBuild;
121
128
  //# sourceMappingURL=agentic.d.ts.map
@@ -50,12 +50,17 @@ function buildToolElement(spec) {
50
50
  }
51
51
  /**
52
52
  * Builds the ad-hoc sub-process content callback + options for the Camunda 8
53
- * AI Agent Sub-process connector. Feed the result into `.adHocSubProcess()`:
53
+ * AI Agent connector. Feed the result into `.adHocSubProcess()`:
54
54
  *
55
55
  * ```ts
56
56
  * const agent = buildAiAgentSubProcess({ ... })
57
- * builder.adHocSubProcess(agent.options.id ?? "Agent_1", agent.content, agent.options)
57
+ * builder.adHocSubProcess(agent.id, agent.content, agent.options)
58
58
  * ```
59
+ *
60
+ * This helper builds the v1 job-worker agent (`io.camunda.agenticai:aiagent-job-worker:1`).
61
+ * For the `io.camunda.connectors.agenticai.ai-agent-subprocess.v2` template of Camunda 8.10,
62
+ * build the ad-hoc sub-process yourself and apply that template after `build()` with
63
+ * `applyTemplates` from `@bpmnkit/core/connectors`.
59
64
  */
60
65
  export function buildAiAgentSubProcess(opts) {
61
66
  if (opts.tools.length === 0) {
@@ -94,6 +99,6 @@ export function buildAiAgentSubProcess(opts) {
94
99
  b.addDisconnected(buildToolElement(tool));
95
100
  }
96
101
  };
97
- return { content, options };
102
+ return { id: opts.id, content, options };
98
103
  }
99
104
  //# sourceMappingURL=agentic.js.map
@@ -1,10 +1,15 @@
1
1
  import type { LayoutEngine } from "../layout/layout-engine.js";
2
- import type { BpmnDefinitions } from "./bpmn-model.js";
2
+ import type { Bounds, LayoutHints, LayoutNode } from "../layout/types.js";
3
+ import type { BpmnDefinitions, BpmnDiEdge, BpmnDiShape, BpmnProcess } from "./bpmn-model.js";
4
+ /** Also used by `expand`, which lays out one process without the pool handling above. */
5
+ export declare function addAnnotationShapes(process: BpmnProcess, layoutNodes: LayoutNode[], annLocalBounds: Map<string, Bounds>, allShapes: BpmnDiShape[], allEdges: BpmnDiEdge[], dx: number, dy: number): void;
3
6
  /**
4
7
  * Replace every diagram-interchange position in `defs` with a computed layout.
5
8
  *
6
9
  * @param engine - Which process layout algorithm to run. Defaults to `semantic`;
7
10
  * `grid` runs the older cell-grid walk and is used to compare the two.
11
+ * @param hints - Tool-grid shapes and annotation sides the builder collected;
12
+ * they steer placement only and are not written to `defs`.
8
13
  */
9
- export declare function applyAutoLayout(defs: BpmnDefinitions, engine?: LayoutEngine): BpmnDefinitions;
14
+ export declare function applyAutoLayout(defs: BpmnDefinitions, engine?: LayoutEngine, hints?: LayoutHints): BpmnDefinitions;
10
15
  //# sourceMappingURL=auto-layout.d.ts.map
@@ -49,6 +49,10 @@ function nodeToShape(node, dx, dy) {
49
49
  };
50
50
  if (node.isExpanded !== undefined)
51
51
  shape.isExpanded = node.isExpanded;
52
+ // The bpmn-js Viewer draws the "X" only when the shape says so; the Modeler
53
+ // assumes it. `keepDiAttributes` lets an explicit value in the source win.
54
+ if (node.type === "exclusiveGateway")
55
+ shape.isMarkerVisible = true;
52
56
  if (node.labelBounds) {
53
57
  shape.label = {
54
58
  bounds: {
@@ -144,7 +148,8 @@ function buildLaneShapes(lanes, nodes, dx, dy, poolY, poolHeaderWidth, laneConte
144
148
  return shape;
145
149
  });
146
150
  }
147
- function addAnnotationShapes(process, layoutNodes, annLocalBounds, allShapes, allEdges, dx, dy) {
151
+ /** Also used by `expand`, which lays out one process without the pool handling above. */
152
+ export function addAnnotationShapes(process, layoutNodes, annLocalBounds, allShapes, allEdges, dx, dy) {
148
153
  if (process.textAnnotations.length === 0 && process.associations.length === 0)
149
154
  return;
150
155
  const nodeById = new Map(layoutNodes.map((n) => [n.id, n]));
@@ -590,8 +595,10 @@ function ancestorIndex(defs, collab) {
590
595
  *
591
596
  * @param engine - Which process layout algorithm to run. Defaults to `semantic`;
592
597
  * `grid` runs the older cell-grid walk and is used to compare the two.
598
+ * @param hints - Tool-grid shapes and annotation sides the builder collected;
599
+ * they steer placement only and are not written to `defs`.
593
600
  */
594
- export function applyAutoLayout(defs, engine = "semantic") {
601
+ export function applyAutoLayout(defs, engine = "semantic", hints) {
595
602
  if (defs.processes.length === 0)
596
603
  return defs;
597
604
  const collab = defs.collaborations[0];
@@ -623,7 +630,7 @@ export function applyAutoLayout(defs, engine = "semantic") {
623
630
  // stack follows the message flows rather than the declaration order.
624
631
  for (const pool of participantPools) {
625
632
  if (pool.process && !layoutOf.has(pool.process)) {
626
- layoutOf.set(pool.process, layoutProcess(pool.process, engine, collapsed));
633
+ layoutOf.set(pool.process, layoutProcess(pool.process, engine, collapsed, hints?.grids));
627
634
  }
628
635
  }
629
636
  const depths = depthIndex(layoutOf.values());
@@ -645,7 +652,7 @@ export function applyAutoLayout(defs, engine = "semantic") {
645
652
  // Lay every pool out first: alignment needs to see all of them before any
646
653
  // geometry is committed.
647
654
  const layouts = pools.map((pool) => pool.process
648
- ? (layoutOf.get(pool.process) ?? layoutProcess(pool.process, engine, collapsed))
655
+ ? (layoutOf.get(pool.process) ?? layoutProcess(pool.process, engine, collapsed, hints?.grids))
649
656
  : { nodes: [], edges: [] });
650
657
  const alignment = alignPools(pools.length, layouts.map((layout) => contentWidth(layout)), messageLinks(collab, pools, layouts));
651
658
  /** Pools with nothing to draw; widened to match the others once all are placed. */
@@ -693,7 +700,7 @@ export function applyAutoLayout(defs, engine = "semantic") {
693
700
  const engineLanes = result.lanes;
694
701
  // Pre-compute annotation positions in layout space so they're included in the bbox
695
702
  const annBounds = process
696
- ? packAnnotations(process, result.nodes, result.edges)
703
+ ? packAnnotations(process, result.nodes, result.edges, hints?.annotationSides)
697
704
  : new Map();
698
705
  const { minX, minY, maxX, maxY } = contentBbox(result.nodes, annBounds.values());
699
706
  const contentW = maxX - minX;
@@ -873,7 +880,7 @@ export function applyAutoLayout(defs, engine = "semantic") {
873
880
  const existingDiagram = defs.diagrams[0];
874
881
  return {
875
882
  ...defs,
876
- diagrams: [
883
+ diagrams: keepDiAttributes(defs.diagrams, [
877
884
  {
878
885
  id: existingDiagram?.id ?? "BPMNDiagram_1",
879
886
  plane: {
@@ -896,8 +903,105 @@ export function applyAutoLayout(defs, engine = "semantic") {
896
903
  };
897
904
  }),
898
905
  ...childPlaneDiagrams(childPlanes, defs, collapsed),
899
- ],
906
+ ]),
907
+ };
908
+ }
909
+ /**
910
+ * Layout recomputes geometry only: bounds, waypoints, label bounds, and the
911
+ * `isExpanded` / `isHorizontal` that describe them. Everything else the source
912
+ * diagram said carries over by `bpmnElement` (DI ids, gateway markers, colours
913
+ * and other vendor attributes, diagram names and label styles), as a plain
914
+ * parse and export would keep it.
915
+ */
916
+ function keepDiAttributes(source, laidOut) {
917
+ // Diagrams match by the element their plane draws; `id` is optional in DI,
918
+ // and matching on an empty one would hand every diagram the first one's
919
+ // attributes and label styles (duplicate XML ids).
920
+ const diagramByElement = new Map();
921
+ const diagramById = new Map();
922
+ const shapeByElement = new Map();
923
+ const edgeByElement = new Map();
924
+ const sourceIds = new Set();
925
+ for (const diagram of source) {
926
+ const element = diagram.plane.bpmnElement;
927
+ if (element && !diagramByElement.has(element))
928
+ diagramByElement.set(element, diagram);
929
+ if (diagram.id && !diagramById.has(diagram.id))
930
+ diagramById.set(diagram.id, diagram);
931
+ for (const shape of diagram.plane.shapes) {
932
+ if (!shapeByElement.has(shape.bpmnElement))
933
+ shapeByElement.set(shape.bpmnElement, shape);
934
+ sourceIds.add(shape.id);
935
+ }
936
+ for (const edge of diagram.plane.edges) {
937
+ if (!edgeByElement.has(edge.bpmnElement))
938
+ edgeByElement.set(edge.bpmnElement, edge);
939
+ sourceIds.add(edge.id);
940
+ }
941
+ }
942
+ // A source id is reused only once, so a malformed source with two shapes
943
+ // for one element cannot produce duplicate ids. A generated `X_di` may
944
+ // already be the source id of another element (one renamed from `X`), so
945
+ // generated ids steer clear of every source id.
946
+ const used = new Set();
947
+ // An empty source id means the source omitted it; that is not one to keep.
948
+ const keepId = (generated, previous) => {
949
+ let id = previous && !used.has(previous) ? previous : generated;
950
+ if (id !== previous) {
951
+ for (let n = 2; sourceIds.has(id) || used.has(id); n++)
952
+ id = `${generated}_${n}`;
953
+ }
954
+ used.add(id);
955
+ return id;
900
956
  };
957
+ const keepLabel = (item, previous) => {
958
+ const attrs = previous.label?.unknownAttributes;
959
+ if (!attrs)
960
+ return item;
961
+ // When layout gives the element no label bounds, the label still carries
962
+ // its style; BPMN DI allows a `BPMNLabel` without bounds.
963
+ return { ...item, label: { ...item.label, unknownAttributes: { ...attrs } } };
964
+ };
965
+ return laidOut.map((diagram) => {
966
+ const previousDiagram = (diagram.plane.bpmnElement && diagramByElement.get(diagram.plane.bpmnElement)) ||
967
+ (diagram.id ? diagramById.get(diagram.id) : undefined);
968
+ const shapes = diagram.plane.shapes.map((shape) => {
969
+ const previous = shapeByElement.get(shape.bpmnElement);
970
+ if (!previous)
971
+ return { ...shape, id: keepId(shape.id, undefined) };
972
+ const kept = {
973
+ ...shape,
974
+ id: keepId(shape.id, previous.id),
975
+ unknownAttributes: { ...previous.unknownAttributes },
976
+ };
977
+ // Layout sets the marker only on exclusive gateways; a source value on
978
+ // any other shape is stale (left from an element whose type changed).
979
+ if (shape.isMarkerVisible !== undefined && previous.isMarkerVisible !== undefined)
980
+ kept.isMarkerVisible = previous.isMarkerVisible;
981
+ return keepLabel(kept, previous);
982
+ });
983
+ const edges = diagram.plane.edges.map((edge) => {
984
+ const previous = edgeByElement.get(edge.bpmnElement);
985
+ if (!previous)
986
+ return { ...edge, id: keepId(edge.id, undefined) };
987
+ const kept = {
988
+ ...edge,
989
+ id: keepId(edge.id, previous.id),
990
+ unknownAttributes: { ...previous.unknownAttributes },
991
+ };
992
+ return keepLabel(kept, previous);
993
+ });
994
+ const plane = { ...diagram.plane, shapes, edges };
995
+ const planeAttrs = previousDiagram?.plane.unknownAttributes;
996
+ if (planeAttrs)
997
+ plane.unknownAttributes = { ...planeAttrs };
998
+ const result = { ...diagram, plane };
999
+ if (previousDiagram?.unknownAttributes)
1000
+ result.unknownAttributes = { ...previousDiagram.unknownAttributes };
1001
+ if (previousDiagram?.unknownChildren)
1002
+ result.unknownChildren = structuredClone(previousDiagram.unknownChildren);
1003
+ return result;
1004
+ });
901
1005
  }
902
1006
  /**
903
1007
  * The final pass over a finished plane: any connection still running through a
@@ -1,3 +1,4 @@
1
+ import type { GridHint, LayoutHints } from "../layout/types.js";
1
2
  import type { BpmnAssociation, BpmnDefinitions, BpmnError, BpmnEscalation, BpmnFlowElement, BpmnMessage, BpmnSequenceFlow, BpmnSignal, BpmnTextAnnotation } from "./bpmn-model.js";
2
3
  import type { RestConnectorConfig } from "./rest-connector.js";
3
4
  /** Options shared by all element methods. */
@@ -24,6 +25,12 @@ export interface StartEventOptions extends ElementOptions {
24
25
  timerCycle?: string;
25
26
  /** Message name — creates a message start event. */
26
27
  messageName?: string;
28
+ /**
29
+ * Form to show when the process is started (`zeebe:formDefinition formId`).
30
+ * Camunda uses start forms only on the process's none start event, so set it
31
+ * there and not on message, timer or signal start events.
32
+ */
33
+ formId?: string;
27
34
  /** Zeebe properties (e.g. webhook connector config). */
28
35
  zeebeProperties?: Array<{
29
36
  name: string;
@@ -103,6 +110,30 @@ export interface UserTaskOptions {
103
110
  formId?: string;
104
111
  /** Emit <zeebe:userTask /> to mark as a Camunda 8 native user task. */
105
112
  zeebeUserTask?: boolean;
113
+ /** Input/output variable mappings. */
114
+ ioMapping?: {
115
+ inputs?: Array<{
116
+ source: string;
117
+ target: string;
118
+ }>;
119
+ outputs?: Array<{
120
+ source: string;
121
+ target: string;
122
+ }>;
123
+ };
124
+ /** Task header key-value pairs. */
125
+ taskHeaders?: Record<string, string>;
126
+ /** Zeebe property key-value pairs (`zeebe:properties`/`zeebe:property`). */
127
+ zeebeProperties?: Array<{
128
+ name: string;
129
+ value: string;
130
+ }>;
131
+ /** Zeebe modeler template ID. */
132
+ modelerTemplate?: string;
133
+ /** Zeebe modeler template version. */
134
+ modelerTemplateVersion?: string;
135
+ /** Zeebe modeler template icon (data URI). */
136
+ modelerTemplateIcon?: string;
106
137
  /** Mark this task as a compensation handler. */
107
138
  isForCompensation?: boolean;
108
139
  /** Free-text documentation (`<bpmn:documentation>`). */
@@ -334,6 +365,20 @@ export interface AdHocSubProcessOptions extends ElementOptions {
334
365
  completionCondition?: string;
335
366
  /** Whether still-running inner activity instances are cancelled once the completion condition is met (default true). */
336
367
  cancelRemainingInstances?: boolean;
368
+ /**
369
+ * Shape of the grid `withAutoLayout()` packs the unconnected children (tools)
370
+ * into: a fixed column count, and `fill: "column"` to read declaration order
371
+ * top to bottom instead of left to right. Layout only; not written to the XML.
372
+ */
373
+ toolGrid?: GridHint;
374
+ }
375
+ /** Options for `annotate()`. */
376
+ export interface AnnotateOptions {
377
+ /**
378
+ * Which side of the element `withAutoLayout()` puts the annotation on,
379
+ * instead of the side it would choose. Layout only; not written to the XML.
380
+ */
381
+ side?: "above" | "below";
337
382
  }
338
383
  /**
339
384
  * The root-level messages, errors, signals and escalations of one process.
@@ -348,6 +393,8 @@ interface RootDefinitions {
348
393
  messages: BpmnMessage[];
349
394
  signals: BpmnSignal[];
350
395
  escalations: BpmnEscalation[];
396
+ /** Shared by every nested builder, so hints reach the process's `build()`. */
397
+ layoutHints: Required<LayoutHints>;
351
398
  }
352
399
  /**
353
400
  * Builder for a single named branch path from a gateway.
@@ -369,6 +416,8 @@ export declare class BranchBuilder {
369
416
  private readonly branchName;
370
417
  private isFirstElement;
371
418
  private pendingCondition;
419
+ private pendingLabel;
420
+ private pendingFlowId;
372
421
  private pendingDefault;
373
422
  /** @internal – true once connectTo() has been called, meaning the branch end is already wired */
374
423
  _connected: boolean;
@@ -385,13 +434,23 @@ export declare class BranchBuilder {
385
434
  private readonly rootMessages;
386
435
  private readonly rootSignals;
387
436
  private readonly rootEscalations;
437
+ private readonly rootLayoutHints;
388
438
  /** @internal */
389
- constructor(gatewayId: string, branchName: string, rootErrors?: BpmnError[], rootMessages?: BpmnMessage[], rootSignals?: BpmnSignal[], rootEscalations?: BpmnEscalation[]);
439
+ constructor(gatewayId: string, branchName: string, rootErrors?: BpmnError[], rootMessages?: BpmnMessage[], rootSignals?: BpmnSignal[], rootEscalations?: BpmnEscalation[], rootLayoutHints?: Required<LayoutHints>);
390
440
  private roots;
391
441
  /** Set a FEEL condition expression on this branch's outgoing sequence flow. */
392
442
  condition(expression: string): this;
443
+ /**
444
+ * Set the name shown on this branch's first flow. Without it the branch id is
445
+ * the name. The generated flow id still follows the branch id, not the label.
446
+ */
447
+ label(text: string): this;
448
+ /** Use `id` for this branch's first flow instead of a generated one. */
449
+ flowId(id: string): this;
393
450
  /** Mark this branch as the gateway's default (no-condition) flow. */
394
451
  defaultFlow(): this;
452
+ /** Keeps label() and flowId() out of the stable-id derivation; see stable-ids.ts. */
453
+ private registerFirstFlow;
395
454
  private addElement;
396
455
  /**
397
456
  * Connect the current position to an existing or future element by ID.
@@ -405,7 +464,7 @@ export declare class BranchBuilder {
405
464
  /** Attach a text annotation to the element at the current cursor position. */
406
465
  textAnnotation(text: string): this;
407
466
  /** Attach a text annotation to an element by explicit ID. */
408
- annotate(elementId: string, text: string): this;
467
+ annotate(elementId: string, text: string, options?: AnnotateOptions): this;
409
468
  serviceTask(id: string, options: ServiceTaskOptions): this;
410
469
  userTask(id: string, options?: UserTaskOptions): this;
411
470
  scriptTask(id: string, options: ScriptTaskOptions): this;
@@ -488,6 +547,7 @@ export declare class SubProcessContentBuilder {
488
547
  private readonly rootMessages;
489
548
  private readonly rootSignals;
490
549
  private readonly rootEscalations;
550
+ private readonly rootLayoutHints;
491
551
  /**
492
552
  * Whether sequential calls chain themselves with sequence flows.
493
553
  *
@@ -536,7 +596,7 @@ export declare class SubProcessContentBuilder {
536
596
  /** Attach a text annotation to the element at the current cursor position. */
537
597
  textAnnotation(text: string): this;
538
598
  /** Attach a text annotation to an element by explicit ID. */
539
- annotate(elementId: string, text: string): this;
599
+ annotate(elementId: string, text: string, options?: AnnotateOptions): this;
540
600
  branch(name: string, callback: (b: BranchBuilder) => void): this;
541
601
  connectTo(targetId: string): this;
542
602
  element(elementId: string): this;
@@ -590,6 +650,7 @@ export declare class ProcessBuilder {
590
650
  private readonly rootMessages;
591
651
  private readonly rootSignals;
592
652
  private readonly rootEscalations;
653
+ private readonly rootLayoutHints;
593
654
  private readonly _textAnnotations;
594
655
  private readonly _associations;
595
656
  private readonly _annCounters;
@@ -848,7 +909,7 @@ export declare class ProcessBuilder {
848
909
  /** Attach a text annotation to the element at the current cursor position. */
849
910
  textAnnotation(text: string): this;
850
911
  /** Attach a text annotation to any flow element by explicit ID. */
851
- annotate(elementId: string, text: string): this;
912
+ annotate(elementId: string, text: string, options?: AnnotateOptions): this;
852
913
  /**
853
914
  * Build the complete BPMN definitions model.
854
915
  *