@bpmnkit/core 1.15.0 → 1.17.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 (60) hide show
  1. package/builder-reference.md +2 -1
  2. package/dist/bpmn/auto-layout.d.ts +0 -8
  3. package/dist/bpmn/auto-layout.js +605 -98
  4. package/dist/bpmn/bpmn-builder.d.ts +120 -14
  5. package/dist/bpmn/bpmn-builder.js +411 -152
  6. package/dist/bpmn/bpmn-model.d.ts +15 -0
  7. package/dist/bpmn/bpmn-parser.js +32 -6
  8. package/dist/bpmn/bpmn-serializer.js +9 -2
  9. package/dist/bpmn/compact-stream.d.ts +7 -0
  10. package/dist/bpmn/compact-stream.js +7 -0
  11. package/dist/bpmn/compact.d.ts +124 -9
  12. package/dist/bpmn/compact.js +295 -27
  13. package/dist/bpmn/full-operations.d.ts +19 -0
  14. package/dist/bpmn/full-operations.js +191 -7
  15. package/dist/bpmn/make-room.js +114 -0
  16. package/dist/bpmn/place-new-shapes.js +4 -2
  17. package/dist/bpmn/preserving-writer.d.ts +1 -1
  18. package/dist/bpmn/preserving-writer.js +1 -1
  19. package/dist/bpmn/process-delta.d.ts +32 -1
  20. package/dist/bpmn/process-delta.js +62 -1
  21. package/dist/bpmn/process-text-writer.d.ts +18 -7
  22. package/dist/bpmn/process-text-writer.js +105 -22
  23. package/dist/bpmn/process-text.d.ts +27 -1
  24. package/dist/bpmn/process-text.js +350 -2
  25. package/dist/bpmn/swimlanes.d.ts +178 -0
  26. package/dist/bpmn/swimlanes.js +774 -0
  27. package/dist/index.d.ts +5 -4
  28. package/dist/index.js +3 -2
  29. package/dist/layout/collaboration/crossings.d.ts +13 -0
  30. package/dist/layout/collaboration/crossings.js +37 -0
  31. package/dist/layout/collaboration/docked-labels.d.ts +21 -0
  32. package/dist/layout/collaboration/docked-labels.js +65 -0
  33. package/dist/layout/collaboration/message-tracks.d.ts +20 -0
  34. package/dist/layout/collaboration/message-tracks.js +78 -0
  35. package/dist/layout/collaboration/stack-crossings.d.ts +38 -0
  36. package/dist/layout/collaboration/stack-crossings.js +155 -0
  37. package/dist/layout/grid/edge-labels.js +21 -10
  38. package/dist/layout/layered/coords.d.ts +13 -0
  39. package/dist/layout/layered/coords.js +211 -0
  40. package/dist/layout/layered/index.d.ts +21 -0
  41. package/dist/layout/layered/index.js +288 -0
  42. package/dist/layout/layered/layers.d.ts +60 -0
  43. package/dist/layout/layered/layers.js +374 -0
  44. package/dist/layout/layered/route.d.ts +66 -0
  45. package/dist/layout/layered/route.js +369 -0
  46. package/dist/layout/layout-engine.d.ts +6 -2
  47. package/dist/layout/layout-engine.js +4 -2
  48. package/dist/layout/semantic/bands.js +8 -2
  49. package/dist/layout/semantic/graph.d.ts +33 -1
  50. package/dist/layout/semantic/graph.js +200 -4
  51. package/dist/layout/semantic/index.d.ts +8 -2
  52. package/dist/layout/semantic/index.js +114 -14
  53. package/dist/layout/semantic/lanes.d.ts +40 -0
  54. package/dist/layout/semantic/lanes.js +198 -0
  55. package/dist/layout/semantic/place.d.ts +46 -2
  56. package/dist/layout/semantic/place.js +248 -30
  57. package/dist/layout/semantic/route.js +35 -2
  58. package/dist/layout/types.d.ts +0 -8
  59. package/dist/xml/xml-patch.d.ts +1 -1
  60. package/package.json +2 -2
@@ -444,6 +444,10 @@ export interface BpmnLaneSet {
444
444
  export interface BpmnProcess {
445
445
  id: string;
446
446
  name?: string;
447
+ /**
448
+ * As the file says it; `undefined` when it says nothing. Kept apart from `false`
449
+ * because engines read an absent attribute differently (Flowable: executable).
450
+ */
447
451
  isExecutable?: boolean;
448
452
  documentation?: string;
449
453
  /** Attributes of the `<documentation>` element (`id`, `textFormat`), kept for round-trip. */
@@ -614,6 +618,7 @@ export interface BpmnDiagram {
614
618
  * ```
615
619
  */
616
620
  export interface BpmnDefinitions {
621
+ /** Empty when the file has none: the schema makes it optional and the Flowable Modeler omits it. */
617
622
  id: string;
618
623
  targetNamespace: string;
619
624
  exporter?: string;
@@ -639,6 +644,16 @@ export interface BpmnDefinitions {
639
644
  * modelled ones so a round trip cannot silently discard them.
640
645
  */
641
646
  unknownChildren?: XmlElement[];
647
+ /**
648
+ * The process the edits go to, once one has been chosen: `primaryProcess`
649
+ * returns it while `processes` holds it and no process is explicitly
650
+ * executable. The editor's ops and change scripts
651
+ * set it to the process they edited, so deleting the last nodes of the
652
+ * user's own pool does not hand the next edit to a partner's process. Read
653
+ * from and written to `<definitions bpmnkit:primaryProcess>`, but written
654
+ * only when the file alone would lead `primaryProcess` elsewhere.
655
+ */
656
+ primaryProcessId?: string;
642
657
  }
643
658
  export {};
644
659
  //# sourceMappingURL=bpmn-model.d.ts.map
@@ -1,6 +1,7 @@
1
1
  import { ParseError } from "../errors.js";
2
2
  import { BPMN_ELEMENTS_BY_TRAIT } from "../generated/bpmn-elements.js";
3
3
  import { Visit, scanXml } from "../xml/xml-parser.js";
4
+ import { BPMNKIT_NAMESPACE } from "./swimlanes.js";
4
5
  function localName(name) {
5
6
  const idx = name.indexOf(":");
6
7
  return idx >= 0 ? name.slice(idx + 1) : name;
@@ -23,6 +24,18 @@ function attr(attributes, name) {
23
24
  }
24
25
  return undefined;
25
26
  }
27
+ /**
28
+ * An `xsd:boolean` attribute: `true`/`1` or `false`/`0`, surrounding whitespace
29
+ * ignored. Undefined when absent or not a boolean, so it is not written back.
30
+ */
31
+ function xsdBoolean(value) {
32
+ const v = value?.trim();
33
+ if (v === "true" || v === "1")
34
+ return true;
35
+ if (v === "false" || v === "0")
36
+ return false;
37
+ return undefined;
38
+ }
26
39
  function requiredAttr(attributes, name, elementName) {
27
40
  const value = attr(attributes, name);
28
41
  if (value === undefined) {
@@ -1244,6 +1257,9 @@ class LaneFrame extends BaseElementFrame {
1244
1257
  case "flowNodeRef":
1245
1258
  return new TextFrame(this, SLOT_FLOW_NODE_REF, attrs);
1246
1259
  case "childLaneSet":
1260
+ // @bpmnkit/core up to 1.9.0 wrote nested lanes as <laneSet>; read those
1261
+ // files back rather than drop their lanes.
1262
+ case "laneSet":
1247
1263
  if (this.childLaneSetSeen)
1248
1264
  return null;
1249
1265
  this.childLaneSetSeen = true;
@@ -1329,11 +1345,9 @@ class ProcessFrame extends Frame {
1329
1345
  this.target.push({
1330
1346
  id: this.id,
1331
1347
  name: attr(attrs, "name"),
1332
- // Absent, "true" and "false" are three states: BPMN reads an absent flag as
1333
- // false, but a file that says "false" out loud should say it again.
1334
- isExecutable: attr(attrs, "isExecutable") === undefined
1335
- ? undefined
1336
- : attr(attrs, "isExecutable") === "true",
1348
+ // Absent, true and false are three states: BPMN reads an absent flag as
1349
+ // false and Flowable as true, so a file that says "false" should say it again.
1350
+ isExecutable: xsdBoolean(attr(attrs, "isExecutable")),
1337
1351
  ...(this.documentation !== undefined ? { documentation: this.documentation } : {}),
1338
1352
  ...(this.documentationAttributes
1339
1353
  ? { documentationAttributes: this.documentationAttributes }
@@ -1691,8 +1705,19 @@ class DefinitionsFrame extends Frame {
1691
1705
  unknownAttributes[key] = value;
1692
1706
  }
1693
1707
  }
1708
+ // Two prefixes may name the namespace; the pin is under the one that carries it.
1709
+ const prefix = Object.keys(namespaces).find((p) => p !== "" &&
1710
+ namespaces[p] === BPMNKIT_NAMESPACE &&
1711
+ unknownAttributes[`${p}:primaryProcess`] !== undefined);
1712
+ const pinKey = `${prefix}:primaryProcess`;
1713
+ const primaryProcessId = prefix === undefined ? undefined : unknownAttributes[pinKey];
1714
+ // The declaration stays: it is the model's, like any other (see pinPrimaryProcess).
1715
+ if (prefix !== undefined && primaryProcessId !== undefined) {
1716
+ Reflect.deleteProperty(unknownAttributes, pinKey);
1717
+ }
1694
1718
  this.sink.result = {
1695
- id: requiredAttr(attrs, "id", this.name),
1719
+ // Optional in the schema, and the Flowable Modeler leaves it out.
1720
+ id: attr(attrs, "id") ?? "",
1696
1721
  targetNamespace: requiredAttr(attrs, "targetNamespace", this.name),
1697
1722
  exporter: attr(attrs, "exporter"),
1698
1723
  exporterVersion: attr(attrs, "exporterVersion"),
@@ -1711,6 +1736,7 @@ class DefinitionsFrame extends Frame {
1711
1736
  processes: this.processes,
1712
1737
  diagrams: this.diagrams,
1713
1738
  ...(this.unknownChildren.length > 0 ? { unknownChildren: this.unknownChildren } : {}),
1739
+ ...(primaryProcessId !== undefined ? { primaryProcessId } : {}),
1714
1740
  };
1715
1741
  }
1716
1742
  }
@@ -1,4 +1,5 @@
1
1
  import { serializeXml } from "../xml/xml-parser.js";
2
+ import { pinnedPrimaryToWrite, withBpmnkitNamespace } from "./swimlanes.js";
2
3
  // ---------------------------------------------------------------------------
3
4
  // Namespace prefix resolution
4
5
  // ---------------------------------------------------------------------------
@@ -663,7 +664,10 @@ function serializeDiagram(diagram, ns) {
663
664
  // ---------------------------------------------------------------------------
664
665
  /** Serialize a BpmnDefinitions model to a BPMN XML string. */
665
666
  export function serializeBpmn(definitions) {
666
- const ns = definitions.namespaces;
667
+ const pinned = pinnedPrimaryToWrite(definitions);
668
+ // Declared with the others, so a parsed copy writes the same bytes.
669
+ const pin = pinned === undefined ? undefined : withBpmnkitNamespace(definitions.namespaces);
670
+ const ns = pin?.namespaces ?? definitions.namespaces;
667
671
  const bp = bpmnPrefix(ns);
668
672
  const attrs = {};
669
673
  // Namespace declarations
@@ -675,7 +679,8 @@ export function serializeBpmn(definitions) {
675
679
  attrs[`xmlns:${prefix}`] = uri;
676
680
  }
677
681
  }
678
- attrs.id = definitions.id;
682
+ if (definitions.id !== "")
683
+ attrs.id = definitions.id;
679
684
  attrs.targetNamespace = definitions.targetNamespace;
680
685
  if (definitions.exporter !== undefined)
681
686
  attrs.exporter = definitions.exporter;
@@ -685,6 +690,8 @@ export function serializeBpmn(definitions) {
685
690
  for (const [key, value] of Object.entries(definitions.unknownAttributes)) {
686
691
  attrs[key] = value;
687
692
  }
693
+ if (pin !== undefined && pinned !== undefined)
694
+ attrs[`${pin.prefix}:primaryProcess`] = pinned;
688
695
  const children = [];
689
696
  // Unmodelled children first: `import` and `extension` precede the root
690
697
  // elements in the schema, and the rest are root elements themselves, so they
@@ -15,6 +15,13 @@
15
15
  * block in an assistant's prose, or the body of a `compose_diagram` snippet all
16
16
  * carry the same literals, and none of them have to be valid as a whole.
17
17
  *
18
+ * Lanes, participants and message flows are not previewed: frames show one
19
+ * process without pools, and the authoritative result adds them at the end.
20
+ * Their literals never pass for an element or a flow, since none has a `type`,
21
+ * and a message flow says `source`/`target` rather than `from`/`to`. Reading
22
+ * them here would mean placing members whose nodes have not arrived yet and
23
+ * switching the preview to the pooled layout mid-stream, which moves every shape.
24
+ *
18
25
  * **Frames are advisory.** Everything here is a guess at an unfinished
19
26
  * document, and the caller is expected to have an authoritative result coming.
20
27
  * That is what lets it drop what it cannot place instead of reporting an error,
@@ -15,6 +15,13 @@
15
15
  * block in an assistant's prose, or the body of a `compose_diagram` snippet all
16
16
  * carry the same literals, and none of them have to be valid as a whole.
17
17
  *
18
+ * Lanes, participants and message flows are not previewed: frames show one
19
+ * process without pools, and the authoritative result adds them at the end.
20
+ * Their literals never pass for an element or a flow, since none has a `type`,
21
+ * and a message flow says `source`/`target` rather than `from`/`to`. Reading
22
+ * them here would mean placing members whose nodes have not arrived yet and
23
+ * switching the preview to the pooled layout mid-stream, which moves every shape.
24
+ *
18
25
  * **Frames are advisory.** Everything here is a guess at an unfinished
19
26
  * document, and the caller is expected to have an authoritative result coming.
20
27
  * That is what lets it drop what it cannot place instead of reporting an error,
@@ -1,5 +1,5 @@
1
1
  import type { XmlElement } from "../types/xml-element.js";
2
- import type { BpmnDefinitions, BpmnElementType, BpmnError, BpmnEscalation, BpmnEventDefinition, BpmnFlowElement, BpmnMessage, BpmnSignal } from "./bpmn-model.js";
2
+ import type { BpmnCollaboration, BpmnDefinitions, BpmnElementType, BpmnError, BpmnEscalation, BpmnEventDefinition, BpmnFlowElement, BpmnMessage, BpmnMessageFlow, BpmnParticipant, BpmnProcess, BpmnSignal } from "./bpmn-model.js";
3
3
  /** A single BPMN flow node in compact form. */
4
4
  export interface CompactElement {
5
5
  id: string;
@@ -176,21 +176,75 @@ export interface CompactProcess {
176
176
  * produce them.
177
177
  */
178
178
  notes?: CompactNote[];
179
+ /**
180
+ * Whether an engine deploys this process (`isExecutable`). Flowable reads an
181
+ * absent attribute as executable, so a partner pool's process must say `false`.
182
+ *
183
+ * When absent, {@link expand} makes the process executable, except in a diagram
184
+ * with pools or lanes: there only the first process without the key is
185
+ * executable and every later one is not. {@link compactify} writes the key for
186
+ * every process that rule would get wrong, and only for those, so lane-free
187
+ * output is unchanged.
188
+ */
189
+ executable?: boolean;
190
+ /**
191
+ * The swimlanes of this process, outermost first. Every top-level flow node
192
+ * belongs to exactly one leaf lane, listed in that lane's `members`; data
193
+ * references and sub-process children belong to none. {@link expand} puts a
194
+ * node no lane lists in the lane of its first sequence-flow predecessor (else
195
+ * successor, else the first leaf) rather than refusing the diagram, and gives
196
+ * a laned process a pool when no participant names it.
197
+ */
198
+ lanes?: CompactLane[];
199
+ }
200
+ /**
201
+ * A swimlane in compact form: a leaf lists its `members`, a parent lists its
202
+ * child `lanes` and no members. Assignable to {@link LaneSpec}.
203
+ */
204
+ export interface CompactLane {
205
+ id: string;
206
+ name?: string;
207
+ /** Ids of the top-level flow nodes in this lane. Leaf lanes only. */
208
+ members?: string[];
209
+ /** Child lanes, outermost first. A lane with children has no members of its own. */
210
+ lanes?: CompactLane[];
211
+ }
212
+ /** A pool in compact form. */
213
+ export interface CompactParticipant {
214
+ id: string;
215
+ name?: string;
216
+ /** The process drawn in this pool. Absent for a black box: a partner whose internals are not modelled. */
217
+ processId?: string;
218
+ }
219
+ /**
220
+ * A message flow in compact form. `source` and `target` are each a participant
221
+ * id or a flow node id, in different pools. Not `from`/`to`: those mark a
222
+ * sequence flow, which is what a streamed preview turns them into.
223
+ */
224
+ export interface CompactMessageFlow {
225
+ id: string;
226
+ source: string;
227
+ target: string;
228
+ name?: string;
179
229
  }
180
230
  /**
181
231
  * Token-efficient representation of a {@link BpmnDefinitions} document.
182
232
  *
183
- * **A read-only view, not a model.** It carries topology, names and the common
184
- * Zeebe bindings and drops everything else — collaborations, participants,
185
- * message flows, lanes, data stores, artifacts, root-level messages and errors,
186
- * multi-instance loop characteristics, full `zeebe:ioMapping` entries and the
187
- * diagram. Use it to show a model to a language model, and
188
- * {@link expand} to build a *new* model from one.
233
+ * **A read-only view, not a model.** It carries topology, names, the common
234
+ * Zeebe bindings, lanes, pools (the participants and message flows of the first
235
+ * collaboration) and each process's executability, and drops everything else:
236
+ * every extension element and foreign attribute it does not name (`flowable:*`
237
+ * among them, on nodes, lanes, pools and processes alike), artifacts,
238
+ * root-level messages, errors, signals and escalations, a message flow's
239
+ * `messageRef`, collaborations after the first, and the diagram. Use it to show
240
+ * a model to a language model, and {@link expand} to build a *new* model from
241
+ * one.
189
242
  *
190
243
  * Do not use it as an edit path for a file you need to keep:
191
244
  * `expand(compactify(defs))` is not `defs`. Edit the {@link BpmnDefinitions}
192
245
  * instead — `applyBpmnOperations` applies the same operation vocabulary to the
193
- * full model without going through this projection.
246
+ * full model without going through this projection, and `reconcileCompact`
247
+ * applies a whole edited compact view as changes.
194
248
  */
195
249
  export interface CompactDiagram {
196
250
  id: string;
@@ -200,6 +254,13 @@ export interface CompactDiagram {
200
254
  */
201
255
  executionPlatformVersion?: string;
202
256
  processes: CompactProcess[];
257
+ /**
258
+ * The pools, in drawing order. A process with content that no participant
259
+ * names gets a pool of its own from {@link expand} once the diagram has any.
260
+ */
261
+ participants?: CompactParticipant[];
262
+ /** Messages between pools. */
263
+ messageFlows?: CompactMessageFlow[];
203
264
  }
204
265
  /**
205
266
  * The flow each gateway marks as its default, keyed by the gateway's id.
@@ -229,6 +290,19 @@ export declare function defaultFlows(elements: readonly CompactElement[], flows:
229
290
  * ```
230
291
  */
231
292
  export declare function compactify(defs: BpmnDefinitions): CompactDiagram;
293
+ /** Element types that are not flow nodes: they sit in no lane. */
294
+ export declare const DATA_ELEMENT_TYPES: ReadonlySet<BpmnElementType>;
295
+ /**
296
+ * The lane tree of `process`, members on leaves only. A member is kept only
297
+ * when it is a top-level flow node, so what `expand` would refuse (a dangling
298
+ * ref, a data reference, a sub-process child) is not passed on; a parent's own
299
+ * refs, which repeat its children's under the union convention, are dropped.
300
+ */
301
+ export declare function compactifyLanes(process: BpmnProcess): CompactLane[];
302
+ /** A pool as compact writes it; a black box has no `processId`. */
303
+ export declare function compactifyParticipant(participant: BpmnParticipant): CompactParticipant;
304
+ /** A message flow as compact writes it, with `source`/`target` so streams never read it as a sequence flow. */
305
+ export declare function compactifyMessageFlow(flow: BpmnMessageFlow): CompactMessageFlow;
232
306
  export declare function makeEventDef(eventType: string): BpmnEventDefinition | undefined;
233
307
  /**
234
308
  * Job types run by the Camunda connector runtime (`io.camunda:http-json:1`,
@@ -260,6 +334,37 @@ export declare class CompactRoots {
260
334
  export declare function buildFlowElement(el: CompactElement, incoming: string[], outgoing: string[],
261
335
  /** Id of the outgoing flow marked `isDefault`, for a gateway that has one. */
262
336
  defaultFlow?: string, roots?: CompactRoots): BpmnFlowElement;
337
+ /**
338
+ * True when the compact describes pools or lanes, which switches `expand` to
339
+ * the collaboration path: pools, lanes, and a layout of the whole diagram.
340
+ */
341
+ export declare function isPooled(compact: CompactDiagram): boolean;
342
+ /**
343
+ * `isExecutable` per process of `compact`, in order, by the rule documented on
344
+ * {@link CompactProcess.executable}. `pooled` is {@link isPooled} of `compact`.
345
+ */
346
+ export declare function executability(compact: CompactDiagram, pooled: boolean): boolean[];
347
+ /**
348
+ * `process` with the lane set `lanes` describes, replacing any it had. Members
349
+ * are taken from leaf lanes only and written verbatim; a node no lane lists goes
350
+ * in the lane {@link laneForNewNode} picks for it. `lanes` must not loop back
351
+ * on itself. Returns `process` unchanged when `lanes` is absent or empty.
352
+ *
353
+ * @throws Error when `lanes` loops back on itself, or as {@link buildLaneSet} does.
354
+ */
355
+ export declare function withLanes(process: BpmnProcess, lanes: readonly CompactLane[] | undefined): BpmnProcess;
356
+ /**
357
+ * Puts each of `nodeIds` that is a top-level flow node of laned `process` and in
358
+ * no lane yet into the lane {@link laneForNewNode} picks, in the order given.
359
+ * Other ids are skipped. Returns `process` itself when it has no lanes.
360
+ */
361
+ export declare function fillLanes(process: BpmnProcess, nodeIds: readonly string[]): BpmnProcess;
362
+ /**
363
+ * The first collaboration `compact` describes, under the first free
364
+ * `Collaboration_<n>` id given the ids already taken. Empty without
365
+ * participants or message flows.
366
+ */
367
+ export declare function expandCollaborations(compact: CompactDiagram, ids: ReadonlySet<string>): BpmnCollaboration[];
263
368
  /**
264
369
  * Options for {@link expand}. A compact diagram is written for Camunda 8, so
265
370
  * the result is checked with `assertDeployable` unless `validate` is `false`.
@@ -290,9 +395,19 @@ export interface ExpandOptions {
290
395
  * Then `assertDeployable` refuses what Zeebe would reject, unless
291
396
  * `options.validate` is `false`.
292
397
  *
398
+ * A diagram with lanes, participants or message flows becomes one collaboration:
399
+ * every process with content gets a pool (a synthesized `Participant_<processId>`
400
+ * when none names it), and the whole diagram is laid out on one plane bound to
401
+ * the collaboration. Without them, each process is laid out on its own plane,
402
+ * exactly as before lanes existed.
403
+ *
293
404
  * @throws {Error} When the diagram cannot be valid BPMN — a flow or boundary
294
405
  * event naming an element that is not in its scope, a duplicate or missing id,
295
- * or an unknown `eventType`. The message lists every problem at once.
406
+ * an unknown `eventType`, or a lane member that is not a top-level flow node of
407
+ * its process, sits in two lanes or sits on a lane with child lanes. The message
408
+ * lists every such problem at once. Pool problems (a participant naming a
409
+ * missing process, a message-flow end in no pool, a message flow inside one
410
+ * pool) are reported by a second check once those pass.
296
411
  * @throws {DeployabilityError} When the gate runs and Zeebe would reject the model.
297
412
  *
298
413
  * @example