@bpmnkit/core 1.15.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.
@@ -111,7 +111,7 @@ Not available inside callbacks (top-level only): at, insertAfter, withAutoLayout
111
111
 
112
112
  ## DiagramBuilder (pools, message flows)
113
113
 
114
- `Bpmn.createDiagram(id?)`: several processes in one file. `.build()` returns definitions; draw shapes with `applyAutoLayout(defs)` before `Bpmn.export`. Omit `processId` on `participant` for a black-box pool. No lane API yet.
114
+ `Bpmn.createDiagram(id?)`: several processes in one file. Call `.withAutoLayout()` before `.build()` to draw shapes. Omit `processId` on `participant` for a black-box pool. Lanes go on each process (`inLane()`).
115
115
 
116
116
  - executionPlatformVersion(version: string)
117
117
  - process(id: string, callback: (b: ProcessBuilder) => void)
@@ -119,6 +119,7 @@ Not available inside callbacks (top-level only): at, insertAfter, withAutoLayout
119
119
  - participant(id: string, options: ParticipantOptions)
120
120
  - message(id: string, options: DiagramMessageOptions)
121
121
  - messageFlow(id: string, options: MessageFlowOptions)
122
+ - withAutoLayout()
122
123
  - build(options?: BuildGateOptions)
123
124
 
124
125
  - ParticipantOptions: name?: string (Pool label); processId?: string (Id of the process this pool…)
@@ -5,6 +5,7 @@ import { orderPools } from "../layout/collaboration/ordering.js";
5
5
  import { collapseCollinear } from "../layout/grid/grid-router.js";
6
6
  import { layoutProcess } from "../layout/layout-engine.js";
7
7
  import { repairRoutes } from "../layout/repair.js";
8
+ import { MIN_LANE_HEIGHT } from "../layout/semantic/place.js";
8
9
  const POOL_HEADER = 30;
9
10
  const LANE_HEADER = 30;
10
11
  const PADDING = 20;
@@ -67,6 +68,23 @@ function contentBbox(nodes, extra) {
67
68
  }
68
69
  return { minX, minY, maxX, maxY };
69
70
  }
71
+ /**
72
+ * Data elements are never lane members, and the engine stacks them below the
73
+ * bands; growing the pool for them leaves tall empty tails, so only flow nodes
74
+ * count.
75
+ */
76
+ const NOT_LANE_MEMBERS = new Set(["dataObject", "dataObjectReference", "dataStoreReference"]);
77
+ /**
78
+ * Where a laned pool has to end so the nodes no lane claims stay inside it.
79
+ * The engine stacks those nodes below the lane bands, so they are the ones
80
+ * whose top lies at or under `bandBottom`; with none, `bandBottom` itself.
81
+ */
82
+ function orphanExtent(nodes, bandBottom) {
83
+ const orphans = nodes.filter((node) => node.bounds.y >= bandBottom && !NOT_LANE_MEMBERS.has(node.type));
84
+ if (orphans.length === 0)
85
+ return bandBottom;
86
+ return contentBbox(orphans).maxY + PADDING;
87
+ }
70
88
  function nodeToShape(node, dx, dy) {
71
89
  const shape = {
72
90
  id: `${node.id}_di`,
@@ -119,26 +137,6 @@ function edgeToShape(edge, dx, dy) {
119
137
  }
120
138
  return diEdge;
121
139
  }
122
- /**
123
- * Lane shapes for one process: the engine's bands when it placed nodes by lane,
124
- * otherwise the top-level lanes tiled proportionally over the content height.
125
- */
126
- function laneShapesFor(lanes, laneBands, nodes, dx, dy, top, x, width, height) {
127
- if (!laneBands)
128
- return buildLaneShapes(lanes, nodes, dx, dy, top, x, width, height);
129
- return laneBands.map((lane) => ({
130
- id: `${lane.id}_di`,
131
- bpmnElement: lane.id,
132
- isHorizontal: true,
133
- bounds: {
134
- x: Math.round(x),
135
- y: Math.round(lane.bounds.y + dy),
136
- width: Math.round(width),
137
- height: Math.round(lane.bounds.height),
138
- },
139
- unknownAttributes: {},
140
- }));
141
- }
142
140
  function buildLaneShapes(lanes, nodes, dx, dy, poolY, poolHeaderWidth, laneContentWidth, poolHeight) {
143
141
  const elemToLane = new Map();
144
142
  for (const lane of lanes) {
@@ -240,6 +238,36 @@ function withNestedAnnotations(process) {
240
238
  }
241
239
  return { ...process, textAnnotations, associations };
242
240
  }
241
+ /**
242
+ * The lane shapes of a laid-out process, outermost lanes first: the engine's
243
+ * bands when it placed the nodes by lane, each nesting level one header
244
+ * further in with right edges aligned; else top-level bands tiled in
245
+ * proportion to the nodes each lane holds. The outermost lanes start at
246
+ * `frame.left` and span `frame.width`; `frame.top` and `frame.height` are the
247
+ * extent the proportional bands tile. `dx` and `dy` shift layout space onto
248
+ * the plane.
249
+ */
250
+ function laneShapesOf(lanes, levels, laneBands, nodes, dx, dy, frame) {
251
+ if (!laneBands) {
252
+ return buildLaneShapes(lanes, nodes, dx, dy, frame.top, frame.left, frame.width, frame.height);
253
+ }
254
+ const depthOf = new Map(levels.map((level) => [level.lane.id, level.depth]));
255
+ return laneBands.map((lane) => {
256
+ const inset = (depthOf.get(lane.id) ?? 0) * LANE_HEADER;
257
+ return {
258
+ id: `${lane.id}_di`,
259
+ bpmnElement: lane.id,
260
+ isHorizontal: true,
261
+ bounds: {
262
+ x: Math.round(frame.left + inset),
263
+ y: Math.round(lane.bounds.y + dy),
264
+ width: Math.round(frame.width - inset),
265
+ height: Math.round(lane.bounds.height),
266
+ },
267
+ unknownAttributes: {},
268
+ };
269
+ });
270
+ }
243
271
  /** Also used by `expand`, which lays out one process without the pool handling above. */
244
272
  export function addAnnotationShapes(process, layoutNodes, annLocalBounds, allShapes, allEdges, dx, dy) {
245
273
  if (process.textAnnotations.length === 0 && process.associations.length === 0)
@@ -336,6 +364,96 @@ const MESSAGE_FLOW_STEM_STEP = 8;
336
364
  const MESSAGE_FLOW_JOG = 20;
337
365
  const MESSAGE_FLOW_MAX_JOG = 2400;
338
366
  const EMPTY_POOL_WIDTH = 300;
367
+ /**
368
+ * Every lane of a lane set, each parent before its children (pre-order).
369
+ * Empty for an absent lane set.
370
+ *
371
+ * @throws Error when one lane object occurs twice, as a lane set that contains
372
+ * itself does; walking it would never end.
373
+ */
374
+ function laneLevels(laneSet) {
375
+ const levels = [];
376
+ const seen = new Set();
377
+ const walk = (set, depth, parentId) => {
378
+ for (const lane of set.lanes) {
379
+ if (seen.has(lane))
380
+ throw new Error(`Lane ${lane.id} occurs twice in its lane set`);
381
+ seen.add(lane);
382
+ const leaf = (lane.childLaneSet?.lanes.length ?? 0) === 0;
383
+ levels.push(parentId === undefined ? { lane, depth, leaf } : { lane, depth, parentId, leaf });
384
+ if (lane.childLaneSet)
385
+ walk(lane.childLaneSet, depth + 1, lane.id);
386
+ }
387
+ };
388
+ if (laneSet)
389
+ walk(laneSet, 0);
390
+ return levels;
391
+ }
392
+ /**
393
+ * Width the lane headers take at the left of a pool: one header per nesting
394
+ * level, since each level is inset by one header; 0 without lanes.
395
+ */
396
+ function laneHeadersWidth(levels) {
397
+ if (levels.length === 0)
398
+ return 0;
399
+ return (Math.max(...levels.map((level) => level.depth)) + 1) * LANE_HEADER;
400
+ }
401
+ /**
402
+ * Pool and lane shapes for a laned process with no flow nodes. Each leaf lane
403
+ * gets a band of {@link MIN_LANE_HEIGHT} and each parent spans its children, so
404
+ * every lane keeps DI to draw and to drop into. Lanes come outermost first.
405
+ *
406
+ * @returns the shapes, pool first, and the pool height.
407
+ */
408
+ function emptyLanedPool(participantId, levels, poolY) {
409
+ const span = new Map();
410
+ let top = 0;
411
+ for (const level of levels) {
412
+ if (!level.leaf)
413
+ continue;
414
+ span.set(level.lane.id, { top, bottom: top + MIN_LANE_HEIGHT });
415
+ top += MIN_LANE_HEIGHT;
416
+ }
417
+ // Reversed pre-order reaches every child before its parent.
418
+ for (const level of [...levels].reverse()) {
419
+ const own = span.get(level.lane.id);
420
+ if (level.parentId === undefined || !own)
421
+ continue;
422
+ const parent = span.get(level.parentId);
423
+ span.set(level.parentId, parent
424
+ ? { top: Math.min(parent.top, own.top), bottom: Math.max(parent.bottom, own.bottom) }
425
+ : own);
426
+ }
427
+ const shapes = [
428
+ {
429
+ id: `${participantId}_di`,
430
+ bpmnElement: participantId,
431
+ isHorizontal: true,
432
+ bounds: { x: 0, y: poolY, width: EMPTY_POOL_WIDTH, height: top },
433
+ unknownAttributes: {},
434
+ },
435
+ ];
436
+ const ordered = [...levels].sort((a, b) => a.depth - b.depth || (span.get(a.lane.id)?.top ?? 0) - (span.get(b.lane.id)?.top ?? 0));
437
+ for (const { lane, depth } of ordered) {
438
+ const band = span.get(lane.id);
439
+ if (!band)
440
+ continue;
441
+ const inset = POOL_HEADER + depth * LANE_HEADER;
442
+ shapes.push({
443
+ id: `${lane.id}_di`,
444
+ bpmnElement: lane.id,
445
+ isHorizontal: true,
446
+ bounds: {
447
+ x: inset,
448
+ y: poolY + band.top,
449
+ width: EMPTY_POOL_WIDTH - inset,
450
+ height: band.bottom - band.top,
451
+ },
452
+ unknownAttributes: {},
453
+ });
454
+ }
455
+ return { shapes, height: top };
456
+ }
339
457
  /**
340
458
  * Sub-processes the source diagram draws collapsed. A collapsed sub-process
341
459
  * keeps its activity shape on the parent plane and carries its contents on a
@@ -655,8 +773,7 @@ function messageLinks(collab, pools, layouts) {
655
773
  if (!layout || !pool?.participantId || layout.nodes.length === 0)
656
774
  continue;
657
775
  const { minX } = contentBbox(layout.nodes);
658
- const hasLanes = (pool.process?.laneSet?.lanes.length ?? 0) > 0;
659
- const elemX = POOL_HEADER + (hasLanes ? LANE_HEADER : 0) + PADDING;
776
+ const elemX = POOL_HEADER + laneHeadersWidth(laneLevels(pool.process?.laneSet)) + PADDING;
660
777
  for (const node of layout.nodes) {
661
778
  centres.set(node.id, {
662
779
  pool: index,
@@ -775,6 +892,8 @@ export function applyAutoLayout(defs, engine = "semantic", hints) {
775
892
  const { participantId, process } = pool;
776
893
  const lanes = process?.laneSet?.lanes ?? [];
777
894
  const hasLanes = lanes.length > 0;
895
+ const levels = laneLevels(process?.laneSet);
896
+ const headersWidth = laneHeadersWidth(levels);
778
897
  const result = layouts[poolIndex] ?? { nodes: [], edges: [] };
779
898
  const alignDx = alignment[poolIndex] ?? 0;
780
899
  // A participant with no process, or one whose process has no flow nodes,
@@ -791,6 +910,13 @@ export function applyAutoLayout(defs, engine = "semantic", hints) {
791
910
  addAnnotationShapes(process, [], annOnly, allShapes, allEdges, PADDING - bbox.minX, PADDING - bbox.minY);
792
911
  continue;
793
912
  }
913
+ // Lanes with nothing in them still need bands, or they have no DI at all.
914
+ if (participantId && hasLanes) {
915
+ const empty = emptyLanedPool(participantId, levels, poolY);
916
+ allShapes.push(...empty.shapes);
917
+ poolY += empty.height + POOL_GAP;
918
+ continue;
919
+ }
794
920
  if (participantId) {
795
921
  const shape = {
796
922
  id: `${participantId}_di`,
@@ -832,21 +958,26 @@ export function applyAutoLayout(defs, engine = "semantic", hints) {
832
958
  let dx;
833
959
  let dy;
834
960
  if (participantId) {
835
- const elemX = POOL_HEADER + (hasLanes ? LANE_HEADER : 0) + PADDING;
961
+ const elemX = POOL_HEADER + headersWidth + PADDING;
836
962
  dx = elemX - minX + alignDx;
837
963
  dy = laneBands ? poolY - bandTop : poolY + PADDING - minY;
838
964
  }
839
965
  else {
840
966
  // A process outside any pool draws its lanes on the plane itself (bpmn-js
841
967
  // imports lane DI under a process root), header at x 0, so the content
842
- // clears the lane header the way it does in a pool.
968
+ // clears the lane headers the way it does in a pool.
843
969
  // A layout pass must not invent a participant to hold them.
844
- dx = (hasLanes ? LANE_HEADER : 0) + PADDING - minX;
970
+ dx = headersWidth + PADDING - minX;
845
971
  dy = laneBands ? processTop - bandTop : processTop + PADDING - minY;
846
972
  }
847
973
  /** Lanes of a process outside any pool, drawn straight on its plane. */
848
974
  const bareLanes = !participantId && hasLanes
849
- ? laneShapesFor(lanes, laneBands, result.nodes, dx, dy, processTop, 0, LANE_HEADER + contentW + 2 * PADDING, laneBands ? bandHeight : contentH + 2 * PADDING)
975
+ ? laneShapesOf(lanes, levels, laneBands, result.nodes, dx, dy, {
976
+ left: 0,
977
+ top: processTop,
978
+ width: headersWidth + contentW + 2 * PADDING,
979
+ height: laneBands ? bandHeight : contentH + 2 * PADDING,
980
+ })
850
981
  : [];
851
982
  // Only the primary process shares the root plane; any other root process
852
983
  // owns one, instead of being stacked on top of the first at the origin.
@@ -871,19 +1002,27 @@ export function applyAutoLayout(defs, engine = "semantic", hints) {
871
1002
  }
872
1003
  allShapes.push(...bareLanes);
873
1004
  if (participantId) {
874
- const innerW = (hasLanes ? LANE_HEADER : 0) + contentW + 2 * PADDING + alignDx;
875
- // Lanes must tile the pool exactly, so the pool takes their height.
876
- const innerH = laneBands ? bandHeight : contentH + 2 * PADDING;
877
- const poolW = POOL_HEADER + innerW;
1005
+ const innerW = headersWidth + contentW + 2 * PADDING + alignDx;
1006
+ // Lanes must tile the pool exactly, so the pool takes their height, and
1007
+ // grows past them only for nodes no lane claims, which the engine
1008
+ // places below the bands.
1009
+ const innerH = laneBands
1010
+ ? Math.max(bandHeight, orphanExtent(result.nodes, bandTop + bandHeight) - bandTop)
1011
+ : contentH + 2 * PADDING;
878
1012
  allShapes.push({
879
1013
  id: `${participantId}_di`,
880
1014
  bpmnElement: participantId,
881
1015
  isHorizontal: true,
882
- bounds: { x: 0, y: poolY, width: poolW, height: innerH },
1016
+ bounds: { x: 0, y: poolY, width: POOL_HEADER + innerW, height: innerH },
883
1017
  unknownAttributes: {},
884
1018
  });
885
1019
  if (hasLanes) {
886
- allShapes.push(...laneShapesFor(lanes, laneBands, result.nodes, dx, dy, poolY, POOL_HEADER, innerW, innerH));
1020
+ allShapes.push(...laneShapesOf(lanes, levels, laneBands, result.nodes, dx, dy, {
1021
+ left: POOL_HEADER,
1022
+ top: poolY,
1023
+ width: innerW,
1024
+ height: innerH,
1025
+ }));
887
1026
  }
888
1027
  poolY += innerH + POOL_GAP;
889
1028
  }
@@ -911,7 +1050,7 @@ export function applyAutoLayout(defs, engine = "semantic", hints) {
911
1050
  return current ?? id;
912
1051
  };
913
1052
  const participantIds = new Set(collab.participants.map((p) => p.id));
914
- const laneIds = new Set(defs.processes.flatMap((p) => (p.laneSet?.lanes ?? []).map((lane) => lane.id)));
1053
+ const laneIds = new Set(defs.processes.flatMap((p) => laneLevels(p.laneSet).map((level) => level.lane.id)));
915
1054
  // Pools and lanes are containers; message flows cross them by design. It is
916
1055
  // the elements inside that a route has to miss.
917
1056
  const obstacles = allShapes
@@ -1210,13 +1349,8 @@ function routeRepair(defs) {
1210
1349
  }
1211
1350
  for (const group of process.groups ?? [])
1212
1351
  containers.add(group.id);
1213
- const lanes = (set) => {
1214
- for (const lane of set?.lanes ?? []) {
1215
- containers.add(lane.id);
1216
- lanes(lane.childLaneSet);
1217
- }
1218
- };
1219
- lanes(process.laneSet);
1352
+ for (const level of laneLevels(process.laneSet))
1353
+ containers.add(level.lane.id);
1220
1354
  }
1221
1355
  const related = (id) => {
1222
1356
  const out = [...(attachers.get(id) ?? [])];
@@ -2,11 +2,6 @@ import type { GridHint, LayoutHints } from "../layout/types.js";
2
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
- /** Options for {@link ProcessBuilder.inLane}. */
6
- export interface LaneOptions {
7
- /** Label shown on the lane; defaults to its id. */
8
- name?: string;
9
- }
10
5
  /** Options shared by all element methods. */
11
6
  export interface ElementOptions {
12
7
  name?: string;
@@ -555,6 +550,22 @@ export interface AnnotateOptions {
555
550
  */
556
551
  side?: "above" | "below" | "left" | "right";
557
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
+ }
558
569
  /**
559
570
  * Lane bookkeeping shared by a process builder and its gateway branches (never by
560
571
  * sub-process contents: nodes inside a sub-process are not lane members).
@@ -877,6 +888,10 @@ export declare class ProcessBuilder {
877
888
  private _pendingSpliceFlowId;
878
889
  /** Flows the caller deliberately spliced, exempt from the rewiring guard. */
879
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?;
880
895
  private readonly lanes;
881
896
  constructor(processId: string);
882
897
  private roots;
@@ -946,7 +961,11 @@ export declare class ProcessBuilder {
946
961
  }): this;
947
962
  /** Set the display name for this process. */
948
963
  name(name: string): this;
949
- /** 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
+ */
950
969
  executable(value: boolean): this;
951
970
  /** Set the process version tag. */
952
971
  versionTag(tag: string): this;
@@ -1131,6 +1150,70 @@ export declare class ProcessBuilder {
1131
1150
  textAnnotation(text: string): this;
1132
1151
  /** Attach a text annotation to any flow element by explicit ID. */
1133
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;
1134
1217
  /**
1135
1218
  * Build the complete BPMN definitions model.
1136
1219
  *
@@ -1171,9 +1254,11 @@ export declare class ProcessBuilder {
1171
1254
  * Writes this process's contents back into the document it came from.
1172
1255
  *
1173
1256
  * Everything not listed here is kept by identity — other processes, the
1174
- * collaboration, diagram interchange, root elements, the process's own lanes,
1175
- * documentation, extensions and unmodelled content. That is the whole point of
1176
- * 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.
1177
1262
  *
1178
1263
  * Diagram interchange is *not* regenerated: existing shapes keep their
1179
1264
  * positions, and elements added here have none until `placeNewShapes()` draws
@@ -1206,6 +1291,10 @@ export declare class ProcessBuilder {
1206
1291
  inLane(id: string, options?: LaneOptions): this;
1207
1292
  private addFlowElement;
1208
1293
  }
1294
+ /**
1295
+ * Builder for a complete BPMN definitions document containing one or more processes.
1296
+ * Use `Bpmn.createDiagram(id?)` to obtain an instance.
1297
+ */
1209
1298
  export declare class DiagramBuilder {
1210
1299
  private readonly _id;
1211
1300
  private readonly _processes;
@@ -1213,11 +1302,29 @@ export declare class DiagramBuilder {
1213
1302
  private readonly _messages;
1214
1303
  private readonly _participants;
1215
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;
1216
1309
  private _collaborationId;
1217
1310
  private _executionPlatformVersion;
1218
1311
  constructor(id: string);
1219
1312
  /** Set the Camunda execution platform version stamped into the BPMN definitions. Defaults to `"8.10.0"`. */
1220
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
+ */
1221
1328
  process(id: string, callback: (b: ProcessBuilder) => void): this;
1222
1329
  /** Renames the collaboration element. Defaults to `"Collaboration_1"`. */
1223
1330
  collaborationId(id: string): this;
@@ -1254,12 +1361,11 @@ export declare class DiagramBuilder {
1254
1361
  */
1255
1362
  messageFlow(id: string, options: MessageFlowOptions): this;
1256
1363
  /**
1257
- * Reports every way the declared collaboration would not survive contact with
1258
- * 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.
1259
1367
  */
1260
- private collaborationProblems;
1261
- /** Maps every participant id and every flow node id to its owning participant. */
1262
- private participantIndex;
1368
+ withAutoLayout(): this;
1263
1369
  /**
1264
1370
  * Build the document. Gated like {@link ProcessBuilder.build}: see
1265
1371
  * {@link BuildGateOptions}.