@bpmnkit/core 1.4.1 → 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 (42) 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 +99 -5
  6. package/dist/bpmn/bpmn-builder.js +203 -69
  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/bands.d.ts +10 -1
  35. package/dist/layout/semantic/bands.js +16 -8
  36. package/dist/layout/semantic/index.d.ts +9 -3
  37. package/dist/layout/semantic/index.js +119 -24
  38. package/dist/layout/semantic/place.d.ts +23 -3
  39. package/dist/layout/semantic/place.js +127 -7
  40. package/dist/layout/semantic/route.js +23 -12
  41. package/dist/layout/types.d.ts +18 -0
  42. package/package.json +2 -2
@@ -2,7 +2,7 @@ import { placeEdgeLabels } from "../grid/edge-labels.js";
2
2
  import { LABEL_CHAR_WIDTH, LABEL_HEIGHT, LABEL_MIN_WIDTH, SUBPROCESS_PADDING } from "../types.js";
3
3
  import { assignBands } from "./bands.js";
4
4
  import { buildSemanticGraph } from "./graph.js";
5
- import { place, sizeOf } from "./place.js";
5
+ import { externalLabelWidth, place, sizeOf } from "./place.js";
6
6
  import { routeFlows } from "./route.js";
7
7
  /** Padding between an expanded sub-process border and its children. */
8
8
  const SUB_PADDING = SUBPROCESS_PADDING;
@@ -11,40 +11,33 @@ const TITLE_BAND = 28;
11
11
  /** Gap between an event or gateway and its external label. */
12
12
  const LABEL_OFFSET = 4;
13
13
  const CONTAINER_TYPES = new Set(["subProcess", "adHocSubProcess", "eventSubProcess", "transaction"]);
14
- const EXTERNAL_LABEL_TYPES = new Set([
15
- "startEvent",
16
- "endEvent",
17
- "intermediateThrowEvent",
18
- "intermediateCatchEvent",
19
- "boundaryEvent",
20
- "exclusiveGateway",
21
- "parallelGateway",
22
- "inclusiveGateway",
23
- "eventBasedGateway",
24
- "complexGateway",
25
- ]);
26
14
  /**
27
15
  * Lay out a process the way the BPMN reads: ranks carry the flow left to right,
28
16
  * semantic bands carry branch meaning up and down, and lane membership wins over
29
17
  * both.
30
18
  */
31
- export function semanticLayoutProcess(process, collapsed) {
32
- return semanticLayout(process.flowElements, process.sequenceFlows, process.laneSet, collapsed);
19
+ export function semanticLayoutProcess(process, collapsed, grids) {
20
+ return semanticLayout(process.flowElements, process.sequenceFlows, process.laneSet, collapsed, false, grids);
33
21
  }
34
22
  export function semanticLayout(flowElements, sequenceFlows, laneSet,
35
23
  /** Sub-processes drawn collapsed: their contents go on a plane of their own. */
36
- collapsed = new Set()) {
24
+ collapsed = new Set(),
25
+ /** True for the contents of an expanded sub-process; see `place`'s `packLoose`. */
26
+ inContainer = false,
27
+ /** Tool-grid hints, by container id; applied to the containers in this scope and below. */
28
+ grids,
29
+ /** The hint for this scope's own grid, when it is a hinted container's interior. */
30
+ grid) {
37
31
  if (flowElements.length === 0)
38
32
  return { nodes: [], edges: [] };
39
33
  const graph = buildSemanticGraph(flowElements, sequenceFlows);
40
- const bandLayout = assignBands(graph);
41
34
  // Children first: an expanded sub-process is sized by what it contains, while
42
35
  // a collapsed one stays activity-sized and its contents move to their own plane.
43
36
  const childResults = new Map();
44
37
  const planes = [];
45
38
  const sizes = new Map();
46
39
  for (const el of graph.nodes) {
47
- const child = childLayoutOf(el, collapsed);
40
+ const child = childLayoutOf(el, collapsed, grids);
48
41
  if (!child) {
49
42
  sizes.set(el.id, sizeOf(el));
50
43
  continue;
@@ -60,7 +53,11 @@ collapsed = new Set()) {
60
53
  sizes.set(el.id, child.size);
61
54
  }
62
55
  }
63
- const { bounds, lanes, gutterX } = place(graph, bandLayout, sizes, laneSet);
56
+ // A named expanded sub-process draws its title along its top border.
57
+ const titled = new Set([...childResults.keys()].filter((id) => graph.byId.get(id)?.name !== undefined));
58
+ const bandLayout = assignBands(graph, titled);
59
+ const { bounds, lanes, gutterX } = place(graph, bandLayout, sizes, laneSet, inContainer, titled, grid);
60
+ const besideStem = boundaryLabels(graph, bounds);
64
61
  const nodes = [];
65
62
  for (const el of flowElements) {
66
63
  const b = bounds.get(el.id);
@@ -76,7 +73,7 @@ collapsed = new Set()) {
76
73
  };
77
74
  if (el.name) {
78
75
  node.label = el.name;
79
- const labelBounds = externalLabel(el.type, el.name, b);
76
+ const labelBounds = besideStem.get(el.id) ?? externalLabel(el.type, el.name, b);
80
77
  if (labelBounds)
81
78
  node.labelBounds = labelBounds;
82
79
  }
@@ -120,13 +117,16 @@ collapsed = new Set()) {
120
117
  return result;
121
118
  }
122
119
  /** Lay out a container's children and report the size its border needs. */
123
- function childLayoutOf(el, collapsed) {
120
+ function childLayoutOf(el, collapsed, grids) {
124
121
  if (!CONTAINER_TYPES.has(el.type))
125
122
  return null;
126
123
  const container = el;
127
124
  if (!container.flowElements || container.flowElements.length === 0)
128
125
  return null;
129
- const result = semanticLayout(container.flowElements, container.sequenceFlows ?? [], container.laneSet, collapsed);
126
+ const result = semanticLayout(container.flowElements, container.sequenceFlows ?? [], container.laneSet, collapsed,
127
+ // A collapsed container's contents go on a plane of their own, laid out
128
+ // like any top-level scope.
129
+ !collapsed.has(el.id), grids, grids?.get(el.id));
130
130
  const extent = extentOf(result);
131
131
  if (!extent)
132
132
  return null;
@@ -166,11 +166,106 @@ function extentOf(result) {
166
166
  function shift(b, dx, dy) {
167
167
  return { x: b.x + dx, y: b.y + dy, width: b.width, height: b.height };
168
168
  }
169
+ /**
170
+ * Labels for named boundary events, beside the event's exit stem rather than
171
+ * centred on it.
172
+ *
173
+ * A boundary event's flows leave its outward side at the centre, so a label
174
+ * centred below (or above) the event is crossed by its own exit edge. Labels
175
+ * sit on the outward side, outside the host, in the gaps between the stems of
176
+ * the events docked on that border: each gap holds at most one label, and the
177
+ * gaps beyond the first and last stem are unbounded. A label takes the gap on
178
+ * its left if it fits there, else the one on its right. When neither fits, it
179
+ * goes beyond the outermost stem on its nearer side, past the labels already
180
+ * there. Every label stays on one line in the one row next to the host:
181
+ * routing does not see labels, and anything farther out would reach the turn
182
+ * a route takes just past a stem.
183
+ */
184
+ function boundaryLabels(graph, bounds) {
185
+ const labels = new Map();
186
+ for (const [hostId, events] of graph.attachers) {
187
+ const host = bounds.get(hostId);
188
+ if (!host)
189
+ continue;
190
+ const docked = events
191
+ .map((event) => ({ event, b: bounds.get(event.id) }))
192
+ .filter((d) => d.b !== undefined);
193
+ for (const onTop of [true, false]) {
194
+ // Same side test the router uses to pick the exit direction.
195
+ const side = docked
196
+ .filter(({ b }) => b.y + b.height / 2 <= host.y + 1 === onTop)
197
+ .sort((p, q) => p.b.x - q.b.x);
198
+ const stems = side.map(({ b }) => b.x + b.width / 2);
199
+ /** How far labels beyond the first / last stem already reach. */
200
+ const outer = {
201
+ left: (stems[0] ?? 0) - LABEL_OFFSET,
202
+ right: (stems[stems.length - 1] ?? 0) + LABEL_OFFSET,
203
+ };
204
+ /** Labels that fit no gap, placed past the outer labels once those are known. */
205
+ const spill = { left: [], right: [] };
206
+ const place = (b, x, width) => ({
207
+ x,
208
+ y: onTop ? b.y - LABEL_OFFSET - LABEL_HEIGHT : b.y + b.height + LABEL_OFFSET,
209
+ width,
210
+ height: LABEL_HEIGHT,
211
+ });
212
+ let leftGapTaken = false;
213
+ side.forEach(({ event, b }, i) => {
214
+ const stem = stems[i];
215
+ const name = event.name;
216
+ if (!name) {
217
+ leftGapTaken = false;
218
+ return;
219
+ }
220
+ const previous = stems[i - 1] ?? Number.NEGATIVE_INFINITY;
221
+ const next = stems[i + 1] ?? Number.POSITIVE_INFINITY;
222
+ const leftRoom = leftGapTaken ? 0 : stem - previous - 2 * LABEL_OFFSET;
223
+ const rightRoom = next - stem - 2 * LABEL_OFFSET;
224
+ const full = Math.max(name.length * LABEL_CHAR_WIDTH, LABEL_MIN_WIDTH);
225
+ leftGapTaken = false;
226
+ if (leftRoom >= full) {
227
+ const x = stem - LABEL_OFFSET - full;
228
+ if (i === 0)
229
+ outer.left = x - LABEL_OFFSET;
230
+ labels.set(event.id, place(b, x, full));
231
+ return;
232
+ }
233
+ if (rightRoom >= full) {
234
+ if (i === side.length - 1)
235
+ outer.right = stem + 2 * LABEL_OFFSET + full;
236
+ labels.set(event.id, place(b, stem + LABEL_OFFSET, full));
237
+ leftGapTaken = true;
238
+ return;
239
+ }
240
+ // Neither gap holds it: beyond the outermost stem no stem crosses it.
241
+ if (i < side.length / 2) {
242
+ spill.left.push(() => {
243
+ outer.left -= full;
244
+ labels.set(event.id, place(b, outer.left, full));
245
+ outer.left -= LABEL_OFFSET;
246
+ });
247
+ }
248
+ else {
249
+ spill.right.push(() => {
250
+ labels.set(event.id, place(b, outer.right, full));
251
+ outer.right += full + LABEL_OFFSET;
252
+ });
253
+ }
254
+ });
255
+ // Nearest stems first, so the order outward matches the order of the events.
256
+ for (const put of spill.left.reverse())
257
+ put();
258
+ for (const put of spill.right)
259
+ put();
260
+ }
261
+ }
262
+ return labels;
263
+ }
169
264
  /** Events and gateways carry their name outside the shape; activities do not. */
170
265
  function externalLabel(type, name, bounds) {
171
- if (!EXTERNAL_LABEL_TYPES.has(type))
266
+ const width = externalLabelWidth(type, name);
267
+ if (width === undefined)
172
268
  return undefined;
173
- const width = Math.max(name.length * LABEL_CHAR_WIDTH, LABEL_MIN_WIDTH);
174
269
  return {
175
270
  x: bounds.x + bounds.width / 2 - width / 2,
176
271
  y: bounds.y + bounds.height + LABEL_OFFSET,
@@ -1,6 +1,6 @@
1
1
  import type { BpmnFlowElement, BpmnLaneSet } from "../../bpmn/bpmn-model.js";
2
- import type { Bounds } from "../types.js";
3
- import type { BandLayout } from "./bands.js";
2
+ import type { Bounds, GridHint } from "../types.js";
3
+ import { type BandLayout } from "./bands.js";
4
4
  import type { SemanticGraph } from "./graph.js";
5
5
  /** Geometry constants. Layout may add space beyond these; it never takes any back. */
6
6
  export declare const H_GAP = 100;
@@ -8,6 +8,11 @@ export declare const V_GAP = 80;
8
8
  export declare const COMPONENT_GAP = 80;
9
9
  export declare const LANE_PADDING = 40;
10
10
  export declare const BOUNDARY_SIZE = 36;
11
+ /**
12
+ * Width of the label an event or gateway carries centred below its shape;
13
+ * undefined for types whose name sits inside the shape.
14
+ */
15
+ export declare function externalLabelWidth(type: string, name: string): number | undefined;
11
16
  export interface Placement {
12
17
  /** Absolute bounds per flow node, boundary events included. */
13
18
  bounds: Map<string, Bounds>;
@@ -36,5 +41,20 @@ export declare function sizeOf(el: BpmnFlowElement, childExtent?: Bounds): {
36
41
  export declare function place(graph: SemanticGraph, bandLayout: BandLayout, sizes: Map<string, {
37
42
  width: number;
38
43
  height: number;
39
- }>, laneSet: BpmnLaneSet | undefined): Placement;
44
+ }>, laneSet: BpmnLaneSet | undefined,
45
+ /**
46
+ * Pack nodes that have no sequence flow at all into a wrapped grid rather
47
+ * than one row each. Set for the inside of an expanded sub-process, where
48
+ * such nodes are an unordered set (the tools of an ad-hoc sub-process) and a
49
+ * single column would both imply an order and grow the container into a
50
+ * tall strip.
51
+ */
52
+ packLoose?: boolean,
53
+ /**
54
+ * Hosts whose title is drawn along their top border — named expanded
55
+ * sub-processes. Boundary events stay off that border.
56
+ */
57
+ titled?: ReadonlySet<string>,
58
+ /** Shape of the `packLoose` grid, when the builder asked for one. */
59
+ grid?: GridHint): Placement;
40
60
  //# sourceMappingURL=place.d.ts.map
@@ -1,4 +1,5 @@
1
- import { ELEMENT_SIZES } from "../types.js";
1
+ import { ELEMENT_SIZES, LABEL_CHAR_WIDTH, LABEL_MIN_WIDTH } from "../types.js";
2
+ import { boundarySide } from "./bands.js";
2
3
  /** Geometry constants. Layout may add space beyond these; it never takes any back. */
3
4
  export const H_GAP = 100;
4
5
  export const V_GAP = 80;
@@ -6,6 +7,27 @@ export const COMPONENT_GAP = 80;
6
7
  export const LANE_PADDING = 40;
7
8
  export const BOUNDARY_SIZE = 36;
8
9
  const DEFAULT_SIZE = { width: 100, height: 80 };
10
+ const EXTERNAL_LABEL_TYPES = new Set([
11
+ "startEvent",
12
+ "endEvent",
13
+ "intermediateThrowEvent",
14
+ "intermediateCatchEvent",
15
+ "boundaryEvent",
16
+ "exclusiveGateway",
17
+ "parallelGateway",
18
+ "inclusiveGateway",
19
+ "eventBasedGateway",
20
+ "complexGateway",
21
+ ]);
22
+ /**
23
+ * Width of the label an event or gateway carries centred below its shape;
24
+ * undefined for types whose name sits inside the shape.
25
+ */
26
+ export function externalLabelWidth(type, name) {
27
+ if (!EXTERNAL_LABEL_TYPES.has(type))
28
+ return undefined;
29
+ return Math.max(name.length * LABEL_CHAR_WIDTH, LABEL_MIN_WIDTH);
30
+ }
9
31
  export function sizeOf(el, childExtent) {
10
32
  if (childExtent)
11
33
  return { width: childExtent.width, height: childExtent.height };
@@ -18,7 +40,22 @@ export function sizeOf(el, childExtent) {
18
40
  * their tallest. Nodes are centred in both, so any two nodes sharing a band
19
41
  * share a centre line and the spine routes as one straight segment.
20
42
  */
21
- export function place(graph, bandLayout, sizes, laneSet) {
43
+ export function place(graph, bandLayout, sizes, laneSet,
44
+ /**
45
+ * Pack nodes that have no sequence flow at all into a wrapped grid rather
46
+ * than one row each. Set for the inside of an expanded sub-process, where
47
+ * such nodes are an unordered set (the tools of an ad-hoc sub-process) and a
48
+ * single column would both imply an order and grow the container into a
49
+ * tall strip.
50
+ */
51
+ packLoose = false,
52
+ /**
53
+ * Hosts whose title is drawn along their top border — named expanded
54
+ * sub-processes. Boundary events stay off that border.
55
+ */
56
+ titled = new Set(),
57
+ /** Shape of the `packLoose` grid, when the builder asked for one. */
58
+ grid) {
22
59
  const bounds = new Map();
23
60
  const componentOf = new Map();
24
61
  for (let i = 0; i < graph.components.length; i++) {
@@ -41,11 +78,19 @@ export function place(graph, bandLayout, sizes, laneSet) {
41
78
  x += (colWidth.get(rank) ?? 0) + H_GAP;
42
79
  }
43
80
  // ── Rows: one per band, laid out per component then stacked ──
81
+ const loose = packLoose ? looseNodes(graph) : [];
82
+ const looseSet = new Set(loose);
44
83
  let cursorY = 0;
45
84
  for (let component = 0; component < graph.components.length; component++) {
46
85
  const members = (graph.components[component] ?? []).filter((id) => graph.byId.has(id));
47
86
  if (members.length === 0)
48
87
  continue;
88
+ if (members.length === 1 && looseSet.has(members[0])) {
89
+ // The whole grid takes the place of the first loose node; the rest are in it.
90
+ if (members[0] === loose[0])
91
+ cursorY = placeGrid(graph, loose, sizes, cursorY, bounds, grid);
92
+ continue;
93
+ }
49
94
  const rowHeight = new Map();
50
95
  for (const id of members) {
51
96
  const band = bandLayout.bands.get(id) ?? 0;
@@ -75,9 +120,56 @@ export function place(graph, bandLayout, sizes, laneSet) {
75
120
  }
76
121
  separateSameCell(graph, bandLayout, bounds);
77
122
  const lanes = laneSet ? applyLanes(graph, laneSet, bounds) : [];
78
- dockBoundaryEvents(graph, bounds);
123
+ dockBoundaryEvents(graph, bounds, titled);
79
124
  return { bounds, lanes, gutterX };
80
125
  }
126
+ /**
127
+ * Nodes with no incoming or outgoing flow, in declaration order — only when
128
+ * there are at least two of them, since one has nothing to be packed with.
129
+ */
130
+ function looseNodes(graph) {
131
+ const loose = graph.components
132
+ .filter((members) => members.length === 1)
133
+ .map((members) => members[0])
134
+ // A one-node component can still loop on itself; that node has flow.
135
+ .filter((id) => graph.byId.has(id) &&
136
+ (graph.outgoing.get(id) ?? []).length === 0 &&
137
+ (graph.incoming.get(id) ?? []).length === 0);
138
+ return loose.length >= 2 ? loose : [];
139
+ }
140
+ /**
141
+ * Place `ids` row by row in `ceil(sqrt(n))` columns of equal cells, starting at
142
+ * `top`, so the set grows roughly square. A hint can fix the column count and
143
+ * fill column by column instead. Returns the cursor for whatever is stacked below.
144
+ */
145
+ function placeGrid(graph, ids, sizes, top, bounds, hint) {
146
+ const columns = hint?.columns ?? Math.ceil(Math.sqrt(ids.length));
147
+ const rows = Math.ceil(ids.length / columns);
148
+ const byColumn = hint?.fill === "column";
149
+ let cellWidth = 0;
150
+ let cellHeight = 0;
151
+ for (const id of ids) {
152
+ const size = sizes.get(id) ?? DEFAULT_SIZE;
153
+ // An event's or gateway's label is centred below it and can be wider than the
154
+ // shape; the cell holds it so neighbouring columns' labels never meet.
155
+ const el = graph.byId.get(id);
156
+ const label = el?.name ? externalLabelWidth(el.type, el.name) : undefined;
157
+ cellWidth = Math.max(cellWidth, size.width, label ?? 0);
158
+ cellHeight = Math.max(cellHeight, size.height);
159
+ }
160
+ ids.forEach((id, i) => {
161
+ const size = sizes.get(id) ?? DEFAULT_SIZE;
162
+ const column = byColumn ? Math.floor(i / rows) : i % columns;
163
+ const row = byColumn ? i % rows : Math.floor(i / columns);
164
+ bounds.set(id, {
165
+ x: column * (cellWidth + H_GAP) + (cellWidth - size.width) / 2,
166
+ y: top + row * (cellHeight + V_GAP) + (cellHeight - size.height) / 2,
167
+ width: size.width,
168
+ height: size.height,
169
+ });
170
+ });
171
+ return top + rows * (cellHeight + V_GAP) - V_GAP + COMPONENT_GAP;
172
+ }
81
173
  /**
82
174
  * Two nodes can land in the same rank and band — a parallel split whose
83
175
  * branches were compacted onto one band, for instance. Push the later ones
@@ -223,16 +315,19 @@ function laneTree(laneSet) {
223
315
  /**
224
316
  * Dock boundary events on their host's edge — escalation on top, everything
225
317
  * else on the bottom — spread along it. Events sharing a side are ordered by
226
- * how far their handler runs, longest first, so long paths get the outer slot.
318
+ * how far out from that border their handler ended up, then how far it runs —
319
+ * farthest first, so outer slots serve outer paths and the routes nest.
320
+ * The side comes from {@link boundarySide}, the rule that also placed the
321
+ * handler's band, so a handler is never routed around its own host.
227
322
  */
228
- function dockBoundaryEvents(graph, bounds) {
323
+ function dockBoundaryEvents(graph, bounds, titled) {
229
324
  for (const [hostId, events] of graph.attachers) {
230
325
  const host = bounds.get(hostId);
231
326
  if (!host)
232
327
  continue;
233
328
  const sides = new Map();
234
329
  for (const event of events) {
235
- const side = event.eventDefinitions.some((d) => d.type === "escalation") ? "top" : "bottom";
330
+ const side = boundarySide(event, titled.has(hostId)) === -1 ? "top" : "bottom";
236
331
  const list = sides.get(side);
237
332
  if (list)
238
333
  list.push(event);
@@ -240,7 +335,9 @@ function dockBoundaryEvents(graph, bounds) {
240
335
  sides.set(side, [event]);
241
336
  }
242
337
  for (const [side, list] of sides) {
243
- const ordered = [...list].sort((a, b) => handlerReach(graph, b.id) - handlerReach(graph, a.id));
338
+ const ordered = [...list].sort((a, b) => handlerDepth(graph, bounds, hostId, host, side, b.id) -
339
+ handlerDepth(graph, bounds, hostId, host, side, a.id) ||
340
+ handlerReach(graph, b.id) - handlerReach(graph, a.id));
244
341
  const n = ordered.length;
245
342
  for (let i = 0; i < n; i++) {
246
343
  const event = ordered[i];
@@ -256,6 +353,29 @@ function dockBoundaryEvents(graph, bounds) {
256
353
  }
257
354
  }
258
355
  }
356
+ /**
357
+ * How far out from the docked border the handler of a boundary event sits,
358
+ * measured on the final positions (after lanes, which can reorder handlers
359
+ * against their bands). Negative when the handler lies behind the border.
360
+ *
361
+ * Each handler leaves its event straight out and turns toward its target, so
362
+ * the event docked outermost has to serve the farthest handler; otherwise its
363
+ * turn cuts across the stems of the events docked inside it.
364
+ */
365
+ function handlerDepth(graph, bounds, hostId, host, side, eventId) {
366
+ let depth = Number.NEGATIVE_INFINITY;
367
+ // Flows out of a boundary event are keyed by its host (see graph.ts).
368
+ for (const flow of graph.outgoing.get(hostId) ?? []) {
369
+ if (flow.sourceRef !== eventId)
370
+ continue;
371
+ const target = bounds.get(flow.targetRef);
372
+ if (!target)
373
+ continue;
374
+ const centre = target.y + target.height / 2;
375
+ depth = Math.max(depth, side === "top" ? host.y - centre : centre - (host.y + host.height));
376
+ }
377
+ return Number.isFinite(depth) ? depth : 0;
378
+ }
259
379
  /** How far the handler of a boundary event runs, in ranks. */
260
380
  function handlerReach(graph, eventId) {
261
381
  let reach = 0;
@@ -94,7 +94,7 @@ export function routeFlows(graph, flows, bounds, bandLayout, gutterX) {
94
94
  const direct = isBackEdge
95
95
  ? []
96
96
  : fromBoundary
97
- ? fromBoundaryCandidates(ctx, source, target, targetRank)
97
+ ? fromBoundaryCandidates(ctx, source, bounds.get(hostOf(graph, flow.sourceRef)), target, targetRank)
98
98
  : forwardCandidates(ctx, source, target, sourceRank, targetRank);
99
99
  const clear = pick(direct, ctx, flow.sourceRef, flow.targetRef);
100
100
  if (clear && clear.crossings <= CROSSING_TOLERANCE) {
@@ -335,14 +335,22 @@ function forwardCandidates(ctx, source, target, sourceRank, targetRank) {
335
335
  }
336
336
  return candidates;
337
337
  }
338
- /** A boundary event leaves through its outward side, never into its host. */
339
- function fromBoundaryCandidates(ctx, source, target, targetRank) {
338
+ /**
339
+ * A boundary event leaves through its outward side, never into its host.
340
+ *
341
+ * The side is where the event is docked, not where the target lies: lanes can
342
+ * put a handler above a host whose event sits on its bottom border. A target
343
+ * behind the docked side is reached around the stem, not straight at it.
344
+ */
345
+ function fromBoundaryCandidates(ctx, source, host, target, targetRank) {
340
346
  const from = centre(source);
341
347
  const to = centre(target);
342
- const down = to.y >= from.y;
348
+ // Same side test as searchRoute and the label placement.
349
+ const down = host === undefined ? to.y >= from.y : from.y > host.y + 1;
343
350
  const exitY = down ? source.y + source.height : source.y;
344
351
  const stem = down ? exitY + BOUNDARY_STEM : exitY - BOUNDARY_STEM;
345
- if (Math.abs(from.x - to.x) < 1) {
352
+ const ahead = down ? to.y >= exitY : to.y <= exitY;
353
+ if (ahead && Math.abs(from.x - to.x) < 1) {
346
354
  return [
347
355
  [
348
356
  { x: from.x, y: exitY },
@@ -352,19 +360,22 @@ function fromBoundaryCandidates(ctx, source, target, targetRank) {
352
360
  }
353
361
  if (target.x >= from.x) {
354
362
  const gutter = ctx.gutterX.get(targetRank ?? 0) ?? target.x - H_GAP / 2;
363
+ const around = [
364
+ { x: from.x, y: exitY },
365
+ { x: from.x, y: stem },
366
+ { x: gutter, y: stem },
367
+ { x: gutter, y: to.y },
368
+ { x: target.x, y: to.y },
369
+ ];
370
+ if (!ahead)
371
+ return [around];
355
372
  return [
356
373
  [
357
374
  { x: from.x, y: exitY },
358
375
  { x: from.x, y: to.y },
359
376
  { x: target.x, y: to.y },
360
377
  ],
361
- [
362
- { x: from.x, y: exitY },
363
- { x: from.x, y: stem },
364
- { x: gutter, y: stem },
365
- { x: gutter, y: to.y },
366
- { x: target.x, y: to.y },
367
- ],
378
+ around,
368
379
  ];
369
380
  }
370
381
  return [
@@ -70,6 +70,24 @@ export interface SubProcessChildResult {
70
70
  parentX: number;
71
71
  parentY: number;
72
72
  }
73
+ /** How the unconnected children of an ad-hoc sub-process are arranged in their grid. */
74
+ export interface GridHint {
75
+ /** Columns in the grid; defaults to `ceil(sqrt(n))`. */
76
+ columns?: number;
77
+ /** `row` (default) reads declaration order left to right; `column` top to bottom. */
78
+ fill?: "row" | "column";
79
+ }
80
+ /**
81
+ * Placement requests the builder collects while it builds and hands to
82
+ * {@link applyAutoLayout}. They steer the layout only; nothing of them is
83
+ * written to the model or the XML.
84
+ */
85
+ export interface LayoutHints {
86
+ /** Tool grid per ad-hoc sub-process id. */
87
+ grids?: Map<string, GridHint>;
88
+ /** Side per text annotation id, overriding the side the packer would choose. */
89
+ annotationSides?: Map<string, "above" | "below">;
90
+ }
73
91
  /** Complete layout result for a process. */
74
92
  export interface LayoutResult {
75
93
  nodes: LayoutNode[];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bpmnkit/core",
3
- "version": "1.4.1",
3
+ "version": "1.6.0",
4
4
  "type": "module",
5
5
  "main": "./dist/index.js",
6
6
  "types": "./dist/index.d.ts",
@@ -55,7 +55,7 @@
55
55
  },
56
56
  "scripts": {
57
57
  "build": "tsc",
58
- "typecheck": "tsc --noEmit",
58
+ "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",
59
59
  "check": "biome check .",
60
60
  "test": "vitest run",
61
61
  "check:descriptors": "tsx scripts/descriptor-report.ts",