@bpmnkit/core 1.6.1 → 1.8.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 (78) hide show
  1. package/AGENTS.md +19 -0
  2. package/README.md +2 -0
  3. package/agent-cards/bpmn.md +86 -0
  4. package/agent-cards/dmn.md +105 -0
  5. package/agent-cards/form.md +72 -0
  6. package/builder-reference.md +211 -0
  7. package/dist/bpmn/auto-layout.js +34 -5
  8. package/dist/bpmn/bpmn-builder.d.ts +127 -5
  9. package/dist/bpmn/bpmn-builder.js +270 -40
  10. package/dist/bpmn/bpmn-model.d.ts +2 -0
  11. package/dist/bpmn/bpmn-parser.js +8 -0
  12. package/dist/bpmn/bpmn-serializer.js +1 -1
  13. package/dist/bpmn/builder-coverage.js +4 -12
  14. package/dist/bpmn/camunda7/export.d.ts +25 -0
  15. package/dist/bpmn/camunda7/export.js +218 -0
  16. package/dist/bpmn/camunda7/migrate.d.ts +4 -1
  17. package/dist/bpmn/camunda7/migrate.js +4 -4
  18. package/dist/bpmn/compact.d.ts +21 -0
  19. package/dist/bpmn/compact.js +86 -1
  20. package/dist/bpmn/full-operations.js +338 -3
  21. package/dist/bpmn/index.d.ts +2 -0
  22. package/dist/bpmn/index.js +2 -0
  23. package/dist/bpmn/operations.d.ts +42 -1
  24. package/dist/bpmn/operations.js +12 -2
  25. package/dist/bpmn/optimize/deploy.js +14 -0
  26. package/dist/bpmn/optimize/index.d.ts +2 -0
  27. package/dist/bpmn/optimize/index.js +5 -0
  28. package/dist/bpmn/optimize/types.d.ts +7 -0
  29. package/dist/bpmn/stable-ids.d.ts +15 -0
  30. package/dist/bpmn/stable-ids.js +26 -0
  31. package/dist/bpmn/strip-camunda8.d.ts +22 -0
  32. package/dist/bpmn/strip-camunda8.js +55 -0
  33. package/dist/bpmn/svg.js +5 -6
  34. package/dist/bpmn/utils.js +151 -1
  35. package/dist/bpmn/zeebe-extensions.d.ts +59 -2
  36. package/dist/bpmn/zeebe-extensions.js +89 -1
  37. package/dist/check-finding.d.ts +19 -0
  38. package/dist/check-finding.js +5 -0
  39. package/dist/connectors/apply-element.d.ts +7 -3
  40. package/dist/connectors/apply-element.js +115 -4
  41. package/dist/connectors/apply-many.d.ts +5 -1
  42. package/dist/connectors/apply-many.js +5 -2
  43. package/dist/connectors/apply.d.ts +24 -3
  44. package/dist/connectors/apply.js +103 -3
  45. package/dist/connectors/catalog.js +5 -0
  46. package/dist/connectors/index.d.ts +1 -1
  47. package/dist/connectors/template-types.d.ts +30 -0
  48. package/dist/connectors/validate.js +33 -0
  49. package/dist/dmn/compact.js +14 -5
  50. package/dist/dmn/dmn-builder.js +3 -3
  51. package/dist/dmn/drd-builder.d.ts +53 -0
  52. package/dist/dmn/drd-builder.js +100 -0
  53. package/dist/dmn/index.d.ts +35 -0
  54. package/dist/dmn/index.js +36 -0
  55. package/dist/dmn/lint.d.ts +19 -0
  56. package/dist/dmn/lint.js +414 -0
  57. package/dist/form/form-builder.d.ts +9 -1
  58. package/dist/form/form-builder.js +34 -1
  59. package/dist/form/form-model.d.ts +7 -0
  60. package/dist/form/form-parser.js +22 -0
  61. package/dist/form/form-serializer.js +10 -0
  62. package/dist/form/index.d.ts +11 -2
  63. package/dist/form/index.js +10 -1
  64. package/dist/form/lint.d.ts +19 -0
  65. package/dist/form/lint.js +356 -0
  66. package/dist/index.d.ts +19 -5
  67. package/dist/index.js +12 -2
  68. package/dist/layout/annotations.d.ts +3 -1
  69. package/dist/layout/annotations.js +72 -14
  70. package/dist/layout/grid/edge-labels.d.ts +7 -1
  71. package/dist/layout/grid/edge-labels.js +62 -1
  72. package/dist/layout/semantic/index.js +78 -8
  73. package/dist/layout/semantic/place.d.ts +19 -4
  74. package/dist/layout/semantic/place.js +245 -29
  75. package/dist/layout/semantic/route.js +60 -12
  76. package/dist/layout/types.d.ts +2 -1
  77. package/llms.txt +9 -0
  78. package/package.json +6 -1
@@ -8,6 +8,7 @@ const ELEMENT_GAP = 30; // min gap between annotation and a non-annotation shape
8
8
  const PREFERRED_OFFSET = 50; // preferred gap to associated element
9
9
  const MIN_HEIGHT = 30;
10
10
  const HORIZONTAL_SHIFTS = [0, 60, -60, 120, -120, 180, -180, 240, -240];
11
+ const VERTICAL_SHIFTS = [0, 40, -40, 80, -80, 120, -120, 160, -160, 200, -200];
11
12
  /** Cost added to a candidate whose association line would cross a shape. */
12
13
  const BLOCKED_LINE_COST = 10_000;
13
14
  /** Cost added per routed connection the association line would cut across. */
@@ -173,6 +174,74 @@ sides) {
173
174
  });
174
175
  }
175
176
  }
177
+ // A clear box is not enough: the association line drawn back to the
178
+ // element must not cut through anything either.
179
+ function candidateCost(item, x, y, naturalX, naturalY) {
180
+ const linked = item.linked;
181
+ const candidate = { x, y, width: item.bounds.width, height: item.bounds.height };
182
+ const { pElem, pAnn } = associationWaypoints(linked.bounds, candidate);
183
+ const crosses = obstacles.some((sh) => sh !== linked.bounds && segmentHitsBox(pElem, pAnn, sh));
184
+ const cuts = routeObstacles.filter((r) => segmentHitsBox(pElem, pAnn, r)).length;
185
+ return (Math.hypot(x - naturalX, y - naturalY) +
186
+ (crosses ? BLOCKED_LINE_COST : 0) +
187
+ cuts * CROSSED_ROUTE_COST);
188
+ }
189
+ const placedSideways = [];
190
+ /** Left/right: mirror of packSide; the box may shift off the element's centre to stay clear. */
191
+ function packHorizontal(side) {
192
+ const list = items
193
+ .filter((it) => it.side === side)
194
+ .sort((a, b) => center(a.linked.bounds).cy - center(b.linked.bounds).cy);
195
+ // Above/below annotations are already final, and the left pass fills
196
+ // `placedSideways` before the right pass runs.
197
+ const placed = [
198
+ ...items.filter((it) => it.side === "above" || it.side === "below"),
199
+ ...placedSideways,
200
+ ];
201
+ for (const item of list) {
202
+ const linked = item.linked;
203
+ const { width, height } = item.bounds;
204
+ const naturalX = side === "left"
205
+ ? linked.bounds.x - PREFERRED_OFFSET - width
206
+ : linked.bounds.x + linked.bounds.width + PREFERRED_OFFSET;
207
+ const naturalY = Math.round(center(linked.bounds).cy - height / 2);
208
+ let best = { x: naturalX, y: naturalY, cost: Number.POSITIVE_INFINITY };
209
+ for (const dy of VERTICAL_SHIFTS) {
210
+ const candidateY = naturalY + dy;
211
+ const ay2 = candidateY + height;
212
+ const intervals = [];
213
+ const collect = (b, gap) => {
214
+ if (ay2 + gap <= b.y || b.y + b.height + gap <= candidateY)
215
+ return;
216
+ intervals.push({ left: b.x - gap, right: b.x + b.width + gap });
217
+ };
218
+ for (const other of placed)
219
+ collect(other.bounds, ANN_GAP);
220
+ for (const sh of obstacles)
221
+ collect(sh, ELEMENT_GAP);
222
+ for (const r of routeObstacles)
223
+ collect(r, ANN_GAP);
224
+ let x = naturalX;
225
+ let changed = true;
226
+ while (changed) {
227
+ changed = false;
228
+ for (const iv of intervals) {
229
+ if (x + width > iv.left && x < iv.right) {
230
+ x = side === "left" ? iv.left - width : iv.right;
231
+ changed = true;
232
+ }
233
+ }
234
+ }
235
+ const cost = candidateCost(item, x, candidateY, naturalX, naturalY);
236
+ if (cost < best.cost)
237
+ best = { x, y: candidateY, cost };
238
+ }
239
+ item.bounds.x = Math.round(best.x);
240
+ item.bounds.y = Math.round(best.y);
241
+ placed.push(item);
242
+ placedSideways.push(item);
243
+ }
244
+ }
176
245
  function packSide(side) {
177
246
  const list = items
178
247
  .filter((it) => it.side === side)
@@ -224,20 +293,7 @@ sides) {
224
293
  }
225
294
  }
226
295
  }
227
- // A clear box is not enough: the association line drawn back to the
228
- // element must not cut through anything either.
229
- const candidate = {
230
- x: candidateX,
231
- y,
232
- width: item.bounds.width,
233
- height: item.bounds.height,
234
- };
235
- const { pElem, pAnn } = associationWaypoints(linked.bounds, candidate);
236
- const crosses = obstacles.some((sh) => sh !== linked.bounds && segmentHitsBox(pElem, pAnn, sh));
237
- const cuts = routeObstacles.filter((r) => segmentHitsBox(pElem, pAnn, r)).length;
238
- const cost = Math.hypot(candidateX - naturalX, y - naturalY) +
239
- (crosses ? BLOCKED_LINE_COST : 0) +
240
- cuts * CROSSED_ROUTE_COST;
296
+ const cost = candidateCost(item, candidateX, y, naturalX, naturalY);
241
297
  if (cost < best.cost)
242
298
  best = { x: candidateX, y, cost };
243
299
  }
@@ -248,6 +304,8 @@ sides) {
248
304
  }
249
305
  packSide("above");
250
306
  packSide("below");
307
+ packHorizontal("left");
308
+ packHorizontal("right");
251
309
  for (const item of items)
252
310
  result.set(item.id, item.bounds);
253
311
  // Fallback placement for annotations with no resolvable linked element:
@@ -4,5 +4,11 @@ import type { LayoutEdge, LayoutNode } from "../types.js";
4
4
  * For each labeled edge, generates candidate positions on the longest segment
5
5
  * and picks the first one that doesn't overlap nodes or already-placed labels.
6
6
  */
7
- export declare function placeEdgeLabels(edges: LayoutEdge[], nodeMap: Map<string, LayoutNode>): void;
7
+ export declare function placeEdgeLabels(edges: LayoutEdge[], nodeMap: Map<string, LayoutNode>,
8
+ /**
9
+ * Edges whose label belongs next to their source — a gateway's branch
10
+ * conditions. These try the first segment, just past the exit, before the
11
+ * usual spots, and only where no other flow runs through the label.
12
+ */
13
+ nearSource?: ReadonlySet<string>): void;
8
14
  //# sourceMappingURL=edge-labels.d.ts.map
@@ -1,6 +1,8 @@
1
1
  import { LABEL_CHAR_WIDTH, LABEL_HEIGHT, LABEL_MIN_WIDTH, LABEL_VERTICAL_OFFSET } from "../types.js";
2
2
  /** Collision tolerance in pixels — small overlap allowed for rounding. */
3
3
  const LABEL_COLLISION_TOLERANCE = 2;
4
+ /** Distance between a source's exit and a label placed beside it. */
5
+ const LABEL_SOURCE_GAP = 6;
4
6
  /** Number of slide steps along a segment when searching for clear space. */
5
7
  const LABEL_SLIDE_STEPS = 10;
6
8
  function boundsOverlap(a, b) {
@@ -14,8 +16,23 @@ function boundsOverlap(a, b) {
14
16
  * For each labeled edge, generates candidate positions on the longest segment
15
17
  * and picks the first one that doesn't overlap nodes or already-placed labels.
16
18
  */
17
- export function placeEdgeLabels(edges, nodeMap) {
19
+ export function placeEdgeLabels(edges, nodeMap,
20
+ /**
21
+ * Edges whose label belongs next to their source — a gateway's branch
22
+ * conditions. These try the first segment, just past the exit, before the
23
+ * usual spots, and only where no other flow runs through the label.
24
+ */
25
+ nearSource = new Set()) {
18
26
  const occupied = [];
27
+ const segments = [];
28
+ for (const edge of edges) {
29
+ for (let i = 0; i + 1 < edge.waypoints.length; i++) {
30
+ const a = edge.waypoints[i];
31
+ const b = edge.waypoints[i + 1];
32
+ if (a && b)
33
+ segments.push({ edge, a, b });
34
+ }
35
+ }
19
36
  // Collect all node bounds as obstacles
20
37
  for (const node of nodeMap.values()) {
21
38
  occupied.push(node.bounds);
@@ -27,6 +44,15 @@ export function placeEdgeLabels(edges, nodeMap) {
27
44
  continue;
28
45
  const labelWidth = Math.max(edge.label.length * LABEL_CHAR_WIDTH, LABEL_MIN_WIDTH);
29
46
  const labelHeight = LABEL_HEIGHT;
47
+ if (nearSource.has(edge.id)) {
48
+ const spot = sourceCandidates(edge.waypoints, labelWidth, labelHeight).find((c) => !occupied.some((ob) => boundsOverlap(c, ob)) &&
49
+ !segments.some((s) => s.edge !== edge && segmentThrough(s.a, s.b, c)));
50
+ if (spot) {
51
+ edge.labelBounds = spot;
52
+ occupied.push(spot);
53
+ continue;
54
+ }
55
+ }
30
56
  // Find the longest segment
31
57
  const { segStart, segEnd } = findLongestSegment(edge.waypoints);
32
58
  // Generate candidate positions along the segment
@@ -52,6 +78,41 @@ export function placeEdgeLabels(edges, nodeMap) {
52
78
  }
53
79
  }
54
80
  }
81
+ /**
82
+ * Spots on an edge's first segment, just past where it leaves its source:
83
+ * above a horizontal exit, beside a vertical one (right first, then left).
84
+ * The first segment has to be long enough to hold the label.
85
+ */
86
+ function sourceCandidates(waypoints, width, height) {
87
+ const a = waypoints[0];
88
+ const b = waypoints[1];
89
+ if (!a || !b)
90
+ return [];
91
+ const gap = LABEL_SOURCE_GAP;
92
+ if (Math.abs(a.y - b.y) < 1) {
93
+ if (Math.abs(b.x - a.x) < width + 2 * gap)
94
+ return [];
95
+ const x = b.x > a.x ? a.x + gap : a.x - gap - width;
96
+ return [
97
+ { x, y: a.y - LABEL_SOURCE_GAP / 2 - height, width, height },
98
+ { x, y: a.y + LABEL_SOURCE_GAP / 2, width, height },
99
+ ];
100
+ }
101
+ if (Math.abs(b.y - a.y) < height + 2 * gap)
102
+ return [];
103
+ const y = b.y > a.y ? a.y + gap : a.y - gap - height;
104
+ return [
105
+ { x: a.x + gap, y, width, height },
106
+ { x: a.x - gap - width, y, width, height },
107
+ ];
108
+ }
109
+ /** True when the axis-parallel segment a→b passes through the box. */
110
+ function segmentThrough(a, b, box) {
111
+ return (Math.max(a.x, b.x) > box.x &&
112
+ Math.min(a.x, b.x) < box.x + box.width &&
113
+ Math.max(a.y, b.y) > box.y &&
114
+ Math.min(a.y, b.y) < box.y + box.height);
115
+ }
55
116
  function findLongestSegment(waypoints) {
56
117
  let bestLen = 0;
57
118
  let bestStart = waypoints[0] ?? { x: 0, y: 0 };
@@ -36,6 +36,7 @@ grid) {
36
36
  const childResults = new Map();
37
37
  const planes = [];
38
38
  const sizes = new Map();
39
+ const axes = new Map();
39
40
  for (const el of graph.nodes) {
40
41
  const child = childLayoutOf(el, collapsed, grids);
41
42
  if (!child) {
@@ -51,12 +52,14 @@ grid) {
51
52
  childResults.set(el.id, child.result);
52
53
  planes.push(...(child.result.planes ?? []));
53
54
  sizes.set(el.id, child.size);
55
+ if (child.axis !== undefined)
56
+ axes.set(el.id, child.axis);
54
57
  }
55
58
  }
56
59
  // A named expanded sub-process draws its title along its top border.
57
60
  const titled = new Set([...childResults.keys()].filter((id) => graph.byId.get(id)?.name !== undefined));
58
61
  const bandLayout = assignBands(graph, titled);
59
- const { bounds, lanes, gutterX } = place(graph, bandLayout, sizes, laneSet, inContainer, titled, grid);
62
+ const { bounds, lanes, gutterX } = place(graph, bandLayout, sizes, laneSet, inContainer, titled, grid, axes);
60
63
  const besideStem = boundaryLabels(graph, bounds);
61
64
  const nodes = [];
62
65
  for (const el of flowElements) {
@@ -113,7 +116,11 @@ grid) {
113
116
  result.lanes = lanes;
114
117
  if (planes.length > 0)
115
118
  result.planes = planes;
116
- placeEdgeLabels(edges, new Map(nodes.map((n) => [n.id, n])));
119
+ clearExternalLabels(nodes, edges);
120
+ // A gateway's branch labels read as the answer to its question, so they go
121
+ // right at its exit rather than halfway along the flow.
122
+ const gateways = new Set(nodes.filter((n) => n.type.endsWith("Gateway")).map((n) => n.id));
123
+ placeEdgeLabels(edges, new Map(nodes.map((n) => [n.id, n])), new Set(edges.filter((e) => gateways.has(e.sourceRef)).map((e) => e.id)));
117
124
  return result;
118
125
  }
119
126
  /** Lay out a container's children and report the size its border needs. */
@@ -131,13 +138,18 @@ function childLayoutOf(el, collapsed, grids) {
131
138
  if (!extent)
132
139
  return null;
133
140
  const titleBand = el.name !== undefined ? TITLE_BAND : 0;
134
- return {
135
- result,
136
- size: {
137
- width: extent.width + 2 * SUB_PADDING,
138
- height: extent.height + 2 * SUB_PADDING + titleBand,
139
- },
141
+ // The inner spine is band 0; its first node sets the line the parent row continues.
142
+ const spineNode = result.edges.length > 0
143
+ ? result.nodes.find((n) => n.position === 0 && n.type !== "boundaryEvent")
144
+ : undefined;
145
+ const size = {
146
+ width: extent.width + 2 * SUB_PADDING,
147
+ height: extent.height + 2 * SUB_PADDING + titleBand,
140
148
  };
149
+ if (!spineNode)
150
+ return { result, size };
151
+ const axis = spineNode.bounds.y + spineNode.bounds.height / 2 - extent.y + SUB_PADDING + titleBand;
152
+ return { result, size, axis };
141
153
  }
142
154
  function extentOf(result) {
143
155
  let minX = Number.POSITIVE_INFINITY;
@@ -261,6 +273,64 @@ function boundaryLabels(graph, bounds) {
261
273
  }
262
274
  return labels;
263
275
  }
276
+ /**
277
+ * Move an event's or gateway's label off the flows that leave or pass it.
278
+ *
279
+ * The label starts centred below the shape, where a branch leaving through the
280
+ * bottom would cut through it. It then tries above, and beside the vertical
281
+ * stems on either side, keeping the first spot clear of every flow, shape and
282
+ * label; with none clear it stays below.
283
+ */
284
+ function clearExternalLabels(nodes, edges) {
285
+ const segments = [];
286
+ for (const edge of edges) {
287
+ for (let i = 0; i + 1 < edge.waypoints.length; i++) {
288
+ segments.push([edge.waypoints[i], edge.waypoints[i + 1]]);
289
+ }
290
+ }
291
+ const contains = (outer, inner) => outer.x <= inner.x &&
292
+ outer.y <= inner.y &&
293
+ outer.x + outer.width >= inner.x + inner.width &&
294
+ outer.y + outer.height >= inner.y + inner.height;
295
+ const labels = nodes.filter((n) => n.labelBounds).map((n) => n.labelBounds);
296
+ for (const node of nodes) {
297
+ const label = node.labelBounds;
298
+ if (!label || node.type === "boundaryEvent")
299
+ continue;
300
+ const clear = (b) => !segments.some(([p, q]) => segmentCuts(p, q, b)) &&
301
+ !nodes.some((other) => other !== node && !contains(other.bounds, node.bounds) && overlapsBox(other.bounds, b)) &&
302
+ !labels.some((other) => other !== label && overlapsBox(other, b));
303
+ if (clear(label))
304
+ continue;
305
+ const b = node.bounds;
306
+ const cx = b.x + b.width / 2;
307
+ const below = b.y + b.height + LABEL_OFFSET;
308
+ const above = b.y - LABEL_OFFSET - label.height;
309
+ const beside = 2 * LABEL_OFFSET;
310
+ const candidates = [
311
+ { ...label, y: above },
312
+ { ...label, x: cx + beside, y: below },
313
+ { ...label, x: cx - beside - label.width, y: below },
314
+ { ...label, x: cx + beside, y: above },
315
+ { ...label, x: cx - beside - label.width, y: above },
316
+ ];
317
+ const spot = candidates.find(clear);
318
+ if (spot) {
319
+ label.x = spot.x;
320
+ label.y = spot.y;
321
+ }
322
+ }
323
+ }
324
+ function overlapsBox(a, b) {
325
+ return a.x < b.x + b.width && b.x < a.x + a.width && a.y < b.y + b.height && b.y < a.y + a.height;
326
+ }
327
+ /** True when the axis-parallel segment p→q runs through the box. */
328
+ function segmentCuts(p, q, b) {
329
+ return (Math.max(p.x, q.x) > b.x &&
330
+ Math.min(p.x, q.x) < b.x + b.width &&
331
+ Math.max(p.y, q.y) > b.y &&
332
+ Math.min(p.y, q.y) < b.y + b.height);
333
+ }
264
334
  /** Events and gateways carry their name outside the shape; activities do not. */
265
335
  function externalLabel(type, name, bounds) {
266
336
  const width = externalLabelWidth(type, name);
@@ -2,9 +2,18 @@ import type { BpmnFlowElement, BpmnLaneSet } from "../../bpmn/bpmn-model.js";
2
2
  import type { Bounds, GridHint } from "../types.js";
3
3
  import { type BandLayout } from "./bands.js";
4
4
  import type { SemanticGraph } from "./graph.js";
5
- /** Geometry constants. Layout may add space beyond these; it never takes any back. */
6
- export declare const H_GAP = 100;
7
- export declare const V_GAP = 80;
5
+ /**
6
+ * Geometry constants. Layout may add space beyond these; it never takes any back.
7
+ * Hand-drawn diagrams keep about 50-60 px between neighbouring shapes; wider
8
+ * gaps only where a flow label or a long event label needs the room.
9
+ */
10
+ export declare const H_GAP = 60;
11
+ export declare const V_GAP = 60;
12
+ /**
13
+ * Gap beside a column holding an expanded container. The container's border,
14
+ * its title and the notes on its children crowd that gap, so it keeps more air.
15
+ */
16
+ export declare const CONTAINER_GAP = 100;
8
17
  export declare const COMPONENT_GAP = 80;
9
18
  export declare const LANE_PADDING = 40;
10
19
  export declare const BOUNDARY_SIZE = 36;
@@ -56,5 +65,11 @@ packLoose?: boolean,
56
65
  */
57
66
  titled?: ReadonlySet<string>,
58
67
  /** Shape of the `packLoose` grid, when the builder asked for one. */
59
- grid?: GridHint): Placement;
68
+ grid?: GridHint,
69
+ /**
70
+ * For expanded containers with a flow inside: the distance from the
71
+ * container's top to its inner spine. The container is hung so that spine
72
+ * continues the row's line, and the flow runs straight through it.
73
+ */
74
+ axes?: ReadonlyMap<string, number>): Placement;
60
75
  //# sourceMappingURL=place.d.ts.map