@bpmnkit/core 1.6.0 → 1.7.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 (41) hide show
  1. package/builder-reference.md +211 -0
  2. package/dist/bpmn/auto-layout.js +32 -4
  3. package/dist/bpmn/bpmn-builder.d.ts +125 -3
  4. package/dist/bpmn/bpmn-builder.js +253 -34
  5. package/dist/bpmn/bpmn-model.d.ts +2 -0
  6. package/dist/bpmn/bpmn-parser.js +8 -0
  7. package/dist/bpmn/bpmn-serializer.js +1 -1
  8. package/dist/bpmn/builder-coverage.js +4 -12
  9. package/dist/bpmn/camunda7/export.d.ts +25 -0
  10. package/dist/bpmn/camunda7/export.js +218 -0
  11. package/dist/bpmn/camunda7/migrate.d.ts +3 -0
  12. package/dist/bpmn/camunda7/migrate.js +3 -3
  13. package/dist/bpmn/compact.d.ts +21 -0
  14. package/dist/bpmn/compact.js +86 -1
  15. package/dist/bpmn/full-operations.js +336 -3
  16. package/dist/bpmn/operations.d.ts +42 -1
  17. package/dist/bpmn/operations.js +12 -2
  18. package/dist/bpmn/optimize/flow.js +2 -0
  19. package/dist/bpmn/strip-camunda8.d.ts +22 -0
  20. package/dist/bpmn/strip-camunda8.js +55 -0
  21. package/dist/bpmn/utils.js +151 -1
  22. package/dist/bpmn/zeebe-extensions.d.ts +59 -2
  23. package/dist/bpmn/zeebe-extensions.js +89 -1
  24. package/dist/connectors/apply-element.d.ts +7 -3
  25. package/dist/connectors/apply-element.js +115 -4
  26. package/dist/connectors/apply-many.d.ts +5 -1
  27. package/dist/connectors/apply-many.js +5 -2
  28. package/dist/connectors/apply.d.ts +24 -3
  29. package/dist/connectors/apply.js +103 -3
  30. package/dist/connectors/catalog.js +5 -0
  31. package/dist/connectors/index.d.ts +1 -1
  32. package/dist/connectors/template-types.d.ts +30 -0
  33. package/dist/connectors/validate.js +33 -0
  34. package/dist/index.d.ts +6 -2
  35. package/dist/index.js +2 -0
  36. package/dist/layout/annotations.d.ts +3 -1
  37. package/dist/layout/annotations.js +72 -14
  38. package/dist/layout/semantic/place.js +23 -5
  39. package/dist/layout/semantic/route.js +15 -0
  40. package/dist/layout/types.d.ts +2 -1
  41. package/package.json +2 -1
@@ -1,5 +1,5 @@
1
1
  import type { AdHocSubProcessOptions, BoundaryEventOptions, IntermediateCatchEventOptions, ServiceTaskOptions, StartEventOptions } from "../index.js";
2
- import type { ElementTemplate, TemplateCondition, TemplateProperty } from "./template-types.js";
2
+ import type { ElementTemplate, TemplateBinding, TemplateCondition, TemplateProperty } from "./template-types.js";
3
3
  export interface ApplyProblem {
4
4
  /** The property key this problem is about, if any. */
5
5
  key?: string;
@@ -62,7 +62,16 @@ export interface Accumulator {
62
62
  subscription: Record<string, string>;
63
63
  /** `zeebe:linkedResource` bindings, by `linkName` in template order. */
64
64
  linkedResources: Map<string, Record<string, string>>;
65
+ /** `zeebe:userTask` — a flag binding, set by the property being active, not by a value. */
66
+ userTask: boolean;
67
+ /** Task-extension bindings (`zeebe:calledElement` …), attribute name to value, by binding type. */
68
+ taskExtensions: Map<TaskExtensionBinding["type"], Record<string, string>>;
65
69
  }
70
+ export type TaskExtensionBinding = Extract<TemplateBinding, {
71
+ type: "zeebe:calledElement" | "zeebe:calledDecision" | "zeebe:formDefinition" | "zeebe:assignmentDefinition" | "zeebe:taskSchedule" | "zeebe:priorityDefinition" | "zeebe:script";
72
+ }>;
73
+ /** `bindingType` values Zeebe accepts on a called element, called decision or form. */
74
+ export declare const RESOURCE_BINDING_TYPES: ReadonlySet<string>;
66
75
  export declare function evalCondition(cond: TemplateCondition, values: Record<string, string>): boolean;
67
76
  /**
68
77
  * The effective value of every active property: user override, else template
@@ -85,6 +94,14 @@ export declare function resolveValues(template: ElementTemplate, values: Record<
85
94
  * one would apply silently and do nothing.
86
95
  */
87
96
  export declare const APPLIED_BINDING_TYPES: ReadonlySet<string>;
97
+ export interface ApplyOptions {
98
+ /**
99
+ * Leave out properties that would only carry the template's default, so the
100
+ * element holds what the caller chose. Hidden and required properties are
101
+ * always written. Default `false`.
102
+ */
103
+ omitDefaults?: boolean;
104
+ }
88
105
  /**
89
106
  * Resolves a template and a set of values into the bindings its active
90
107
  * properties write — the half of applying a template that does not depend on
@@ -94,8 +111,12 @@ export declare const APPLIED_BINDING_TYPES: ReadonlySet<string>;
94
111
  * @param generate - Supplies a value for an active property that declares a
95
112
  * `generatedValue` and was given none. Returning `undefined` leaves the
96
113
  * binding unwritten; the callback reports that however suits its caller.
114
+ * @param options.omitDefaults - Skip a property whose value is only the
115
+ * template's default: not in `values`, not Hidden, not `notEmpty`, with no
116
+ * `generatedValue`. The default still counts when other properties'
117
+ * conditions are evaluated, so the template's own gating is unchanged.
97
118
  */
98
- export declare function resolveBindings(template: ElementTemplate, values: Record<string, string>, generate: (key: string, prop: TemplateProperty) => string | undefined): {
119
+ export declare function resolveBindings(template: ElementTemplate, values: Record<string, string>, generate: (key: string, prop: TemplateProperty) => string | undefined, options?: ApplyOptions): {
99
120
  accum: Accumulator;
100
121
  problems: ApplyProblem[];
101
122
  };
@@ -125,7 +146,7 @@ export declare function resolveBindings(template: ElementTemplate, values: Recor
125
146
  * work the same way. Use {@link applyConnectorTemplate} to apply by bundled
126
147
  * template id instead.
127
148
  */
128
- export declare function applyElementTemplate(template: ElementTemplate, values?: Record<string, string>): ApplyResult;
149
+ export declare function applyElementTemplate(template: ElementTemplate, values?: Record<string, string>, options?: ApplyOptions): ApplyResult;
129
150
  /**
130
151
  * Applies a bundled Camunda 8 out-of-the-box connector element template by
131
152
  * id — see {@link applyElementTemplate} for the full binding-resolution
@@ -1,5 +1,11 @@
1
1
  import { parseExpression } from "@bpmnkit/feel";
2
2
  import { getTemplate, propertyKey } from "./catalog.js";
3
+ /** `bindingType` values Zeebe accepts on a called element, called decision or form. */
4
+ export const RESOURCE_BINDING_TYPES = new Set([
5
+ "latest",
6
+ "deployment",
7
+ "versionTag",
8
+ ]);
3
9
  export function evalCondition(cond, values) {
4
10
  if ("allMatch" in cond) {
5
11
  return cond.allMatch.every((c) => evalCondition(c, values));
@@ -75,6 +81,14 @@ export const APPLIED_BINDING_TYPES = new Set([
75
81
  "zeebe:property",
76
82
  "zeebe:adHoc",
77
83
  "zeebe:agentDefinition",
84
+ "zeebe:userTask",
85
+ "zeebe:calledElement",
86
+ "zeebe:calledDecision",
87
+ "zeebe:formDefinition",
88
+ "zeebe:assignmentDefinition",
89
+ "zeebe:taskSchedule",
90
+ "zeebe:priorityDefinition",
91
+ "zeebe:script",
78
92
  "property",
79
93
  "bpmn:Message#property",
80
94
  "bpmn:Message#zeebe:subscription#property",
@@ -111,6 +125,18 @@ function applyBinding(binding, value, accum) {
111
125
  case "zeebe:agentDefinition":
112
126
  accum.agentDefinition[binding.property] = value;
113
127
  return;
128
+ case "zeebe:calledElement":
129
+ case "zeebe:calledDecision":
130
+ case "zeebe:formDefinition":
131
+ case "zeebe:assignmentDefinition":
132
+ case "zeebe:taskSchedule":
133
+ case "zeebe:priorityDefinition":
134
+ case "zeebe:script": {
135
+ const attributes = accum.taskExtensions.get(binding.type) ?? {};
136
+ attributes[binding.property] = value;
137
+ accum.taskExtensions.set(binding.type, attributes);
138
+ return;
139
+ }
114
140
  case "property":
115
141
  // "name" binds to the element's display name — handled by the caller, not here.
116
142
  return;
@@ -130,6 +156,35 @@ function applyBinding(binding, value, accum) {
130
156
  return;
131
157
  }
132
158
  }
159
+ /** An extension whose required attribute resolved to nothing is not written; say so. */
160
+ function incompleteTaskExtensions(accum) {
161
+ const required = [
162
+ ["zeebe:calledElement", ["processId"]],
163
+ ["zeebe:calledDecision", ["decisionId", "resultVariable"]],
164
+ ["zeebe:script", ["expression"]],
165
+ ["zeebe:priorityDefinition", ["priority"]],
166
+ ];
167
+ const problems = [];
168
+ for (const [type, names] of required) {
169
+ const written = accum.taskExtensions.get(type);
170
+ const missing = written === undefined ? [] : names.filter((name) => written[name] === undefined);
171
+ if (missing.length > 0) {
172
+ problems.push({ message: `<${type}> needs ${missing.join(", ")}; it was not written` });
173
+ }
174
+ }
175
+ const form = accum.taskExtensions.get("zeebe:formDefinition");
176
+ if (form?.externalReference !== undefined && form.formId !== undefined) {
177
+ problems.push({
178
+ message: "<zeebe:formDefinition> has both formId and externalReference; only externalReference was written",
179
+ });
180
+ }
181
+ if (form && form.formId === undefined && form.externalReference === undefined) {
182
+ problems.push({
183
+ message: "<zeebe:formDefinition> needs formId or externalReference; it was not written",
184
+ });
185
+ }
186
+ return problems;
187
+ }
133
188
  /** A binding the template resolved but the builder options have no field for. */
134
189
  function notExpressible(what) {
135
190
  return {
@@ -148,8 +203,12 @@ function directionOf(template) {
148
203
  * @param generate - Supplies a value for an active property that declares a
149
204
  * `generatedValue` and was given none. Returning `undefined` leaves the
150
205
  * binding unwritten; the callback reports that however suits its caller.
206
+ * @param options.omitDefaults - Skip a property whose value is only the
207
+ * template's default: not in `values`, not Hidden, not `notEmpty`, with no
208
+ * `generatedValue`. The default still counts when other properties'
209
+ * conditions are evaluated, so the template's own gating is unchanged.
151
210
  */
152
- export function resolveBindings(template, values, generate) {
211
+ export function resolveBindings(template, values, generate, options = {}) {
153
212
  const resolved = resolveValues(template, values);
154
213
  const problems = [];
155
214
  const knownKeys = new Set(template.properties.map(propertyKey).filter(Boolean));
@@ -172,11 +231,26 @@ export function resolveBindings(template, values, generate) {
172
231
  message: {},
173
232
  subscription: {},
174
233
  linkedResources: new Map(),
234
+ userTask: false,
235
+ taskExtensions: new Map(),
175
236
  };
176
237
  for (const prop of template.properties) {
177
238
  const key = propertyKey(prop);
178
239
  if (prop.condition && !evalCondition(prop.condition, resolved))
179
240
  continue;
241
+ if (options.omitDefaults &&
242
+ !(key in values) &&
243
+ prop.type !== "Hidden" &&
244
+ !prop.constraints?.notEmpty &&
245
+ !prop.generatedValue) {
246
+ continue;
247
+ }
248
+ // A flag binding has no value of its own: the property being active is the signal.
249
+ if (prop.binding.type === "zeebe:userTask") {
250
+ if (resolved[key] !== "false")
251
+ accum.userTask = true;
252
+ continue;
253
+ }
180
254
  let value = resolved[key];
181
255
  if ((value === undefined || value === "") && prop.generatedValue) {
182
256
  value = generate(key, prop);
@@ -201,8 +275,28 @@ export function resolveBindings(template, values, generate) {
201
275
  });
202
276
  }
203
277
  }
278
+ if ("property" in prop.binding &&
279
+ prop.binding.property === "bindingType" &&
280
+ !RESOURCE_BINDING_TYPES.has(value)) {
281
+ problems.push({
282
+ key,
283
+ message: `Invalid bindingType "${value}" for "${key}": expected one of ${[...RESOURCE_BINDING_TYPES].join(", ")}; it was not written`,
284
+ });
285
+ continue;
286
+ }
287
+ if ("property" in prop.binding &&
288
+ /^propagateAll(Parent|Child)Variables$/.test(prop.binding.property) &&
289
+ value !== "true" &&
290
+ value !== "false") {
291
+ problems.push({
292
+ key,
293
+ message: `Invalid value "${value}" for "${key}": expected true or false; it was not written`,
294
+ });
295
+ continue;
296
+ }
204
297
  applyBinding(prop.binding, value, accum);
205
298
  }
299
+ problems.push(...incompleteTaskExtensions(accum));
206
300
  return { accum, problems };
207
301
  }
208
302
  /**
@@ -231,12 +325,12 @@ export function resolveBindings(template, values, generate) {
231
325
  * work the same way. Use {@link applyConnectorTemplate} to apply by bundled
232
326
  * template id instead.
233
327
  */
234
- export function applyElementTemplate(template, values = {}) {
328
+ export function applyElementTemplate(template, values = {}, options = {}) {
235
329
  const ungenerated = [];
236
330
  const { accum, problems } = resolveBindings(template, values, (key) => {
237
331
  ungenerated.push(key);
238
332
  return undefined;
239
- });
333
+ }, options);
240
334
  // Builder options name no element, so there is nothing to derive a per-element value from.
241
335
  for (const key of ungenerated) {
242
336
  problems.push({
@@ -248,6 +342,12 @@ export function applyElementTemplate(template, values = {}) {
248
342
  if (accum.linkedResources.size > 0) {
249
343
  problems.push(notExpressible("zeebe:linkedResource bindings"));
250
344
  }
345
+ for (const type of [
346
+ ...(accum.userTask ? ["zeebe:userTask"] : []),
347
+ ...accum.taskExtensions.keys(),
348
+ ]) {
349
+ problems.push(notExpressible(`${type} bindings`));
350
+ }
251
351
  const modelerTemplate = template.id;
252
352
  const modelerTemplateVersion = template.version !== undefined ? String(template.version) : undefined;
253
353
  const modelerTemplateIcon = template.icon?.contents;
@@ -27,6 +27,11 @@ export function propertyKey(prop) {
27
27
  return `adHoc.${b.property}`;
28
28
  if (b.type === "zeebe:agentDefinition")
29
29
  return `agentDefinition.${b.property}`;
30
+ if (b.type === "zeebe:userTask")
31
+ return "userTask";
32
+ if ("property" in b && b.type.startsWith("zeebe:") && b.type !== "zeebe:linkedResource") {
33
+ return `${b.type.slice("zeebe:".length)}.${b.property}`;
34
+ }
30
35
  if (b.type === "bpmn:Message#property")
31
36
  return `message.${b.name}`;
32
37
  if (b.type === "bpmn:Message#zeebe:subscription#property")
@@ -13,7 +13,7 @@
13
13
  export { listConnectors, searchConnectors, getTemplate, propertyKey, registerElementTemplates, clearRegisteredTemplates, summarizeTemplate, } from "./catalog.js";
14
14
  export type { ConnectorSummary, ConnectorInputSpec, ConnectorDirection } from "./catalog.js";
15
15
  export { applyConnectorTemplate, applyElementTemplate } from "./apply.js";
16
- export type { ApplyResult, ApplyProblem } from "./apply.js";
16
+ export type { ApplyOptions, ApplyResult, ApplyProblem } from "./apply.js";
17
17
  export { applyTemplateToElement } from "./apply-element.js";
18
18
  export type { ApplyToElementResult } from "./apply-element.js";
19
19
  export { applyTemplates } from "./apply-many.js";
@@ -136,6 +136,36 @@ export type TemplateBinding = {
136
136
  type: "zeebe:adHoc";
137
137
  property: "outputCollection" | "outputElement" | "activeElementsCollection";
138
138
  }
139
+ /**
140
+ * Task-level Zeebe extensions. `zeebe:userTask` is a flag (a Hidden property whose
141
+ * mere presence marks a Camunda user task); the rest name one attribute each.
142
+ * Camunda requires `zeebe:userTask` beside the user-task-only ones
143
+ * (`assignmentDefinition`, `taskSchedule`, `priorityDefinition`).
144
+ */
145
+ | {
146
+ type: "zeebe:userTask";
147
+ } | {
148
+ type: "zeebe:calledElement";
149
+ property: "processId" | "bindingType" | "versionTag" | "propagateAllParentVariables" | "propagateAllChildVariables";
150
+ } | {
151
+ type: "zeebe:calledDecision";
152
+ property: "decisionId" | "resultVariable" | "bindingType" | "versionTag";
153
+ } | {
154
+ type: "zeebe:formDefinition";
155
+ property: "formId" | "externalReference" | "bindingType" | "versionTag";
156
+ } | {
157
+ type: "zeebe:assignmentDefinition";
158
+ property: "assignee" | "candidateGroups" | "candidateUsers";
159
+ } | {
160
+ type: "zeebe:taskSchedule";
161
+ property: "dueDate" | "followUpDate";
162
+ } | {
163
+ type: "zeebe:priorityDefinition";
164
+ property: "priority";
165
+ } | {
166
+ type: "zeebe:script";
167
+ property: "expression" | "resultVariable";
168
+ }
139
169
  /** `zeebe:agentDefinition` (Camunda 8.10+), used by the AI Agent v2 templates. */
140
170
  | {
141
171
  type: "zeebe:agentDefinition";
@@ -39,6 +39,14 @@ const BINDING_FIELDS = {
39
39
  "zeebe:property": ["name"],
40
40
  "zeebe:adHoc": ["property"],
41
41
  "zeebe:agentDefinition": ["property"],
42
+ "zeebe:userTask": [],
43
+ "zeebe:calledElement": ["property"],
44
+ "zeebe:calledDecision": ["property"],
45
+ "zeebe:formDefinition": ["property"],
46
+ "zeebe:assignmentDefinition": ["property"],
47
+ "zeebe:taskSchedule": ["property"],
48
+ "zeebe:priorityDefinition": ["property"],
49
+ "zeebe:script": ["property"],
42
50
  "bpmn:Message#property": ["name"],
43
51
  "bpmn:Message#zeebe:subscription#property": ["name"],
44
52
  "zeebe:linkedResource": ["property", "linkName"],
@@ -46,6 +54,22 @@ const BINDING_FIELDS = {
46
54
  const TASK_DEFINITION_PROPERTIES = new Set(["type", "retries"]);
47
55
  const AD_HOC_PROPERTIES = new Set(["outputCollection", "outputElement", "activeElementsCollection"]);
48
56
  const AGENT_DEFINITION_PROPERTIES = new Set(["agentType"]);
57
+ /** The `property` values the schema allows per task-extension binding. */
58
+ const TASK_EXTENSION_PROPERTIES = {
59
+ "zeebe:calledElement": new Set([
60
+ "processId",
61
+ "bindingType",
62
+ "versionTag",
63
+ "propagateAllParentVariables",
64
+ "propagateAllChildVariables",
65
+ ]),
66
+ "zeebe:calledDecision": new Set(["decisionId", "resultVariable", "bindingType", "versionTag"]),
67
+ "zeebe:formDefinition": new Set(["formId", "externalReference", "bindingType", "versionTag"]),
68
+ "zeebe:assignmentDefinition": new Set(["assignee", "candidateGroups", "candidateUsers"]),
69
+ "zeebe:taskSchedule": new Set(["dueDate", "followUpDate"]),
70
+ "zeebe:priorityDefinition": new Set(["priority"]),
71
+ "zeebe:script": new Set(["expression", "resultVariable"]),
72
+ };
49
73
  function isRecord(value) {
50
74
  return typeof value === "object" && value !== null && !Array.isArray(value);
51
75
  }
@@ -100,6 +124,15 @@ function checkBinding(binding, path, problems, warnings) {
100
124
  });
101
125
  }
102
126
  }
127
+ const taskProperties = TASK_EXTENSION_PROPERTIES[type];
128
+ if (taskProperties !== undefined && isNonEmptyString(binding.property)) {
129
+ if (!taskProperties.has(binding.property)) {
130
+ problems.push({
131
+ path: `${path}.property`,
132
+ message: `expected one of ${[...taskProperties].join(", ")}`,
133
+ });
134
+ }
135
+ }
103
136
  if (type === "zeebe:agentDefinition" && isNonEmptyString(binding.property)) {
104
137
  if (!AGENT_DEFINITION_PROPERTIES.has(binding.property)) {
105
138
  problems.push({
package/dist/index.d.ts CHANGED
@@ -3,6 +3,8 @@ export type { ErrorCode } from "./errors.js";
3
3
  export { isBpmnActivity, isBpmnAdHocSubProcess, isBpmnBoundaryEvent, isBpmnBusinessRuleTask, isBpmnCallActivity, isBpmnComplexGateway, isBpmnDataObject, isBpmnDataObjectReference, isBpmnDataStoreReference, isBpmnEndEvent, isBpmnEvent, isBpmnEventBasedGateway, isBpmnEventSubProcess, isBpmnExclusiveGateway, isBpmnGateway, isBpmnInclusiveGateway, isBpmnIntermediateCatchEvent, isBpmnIntermediateThrowEvent, isBpmnManualTask, isBpmnParallelGateway, isBpmnReceiveTask, isBpmnScriptTask, isBpmnSendTask, isBpmnServiceTask, isBpmnStartEvent, isBpmnSubProcess, isBpmnTask, isBpmnTransaction, isBpmnUserTask, } from "./bpmn/type-guards.js";
4
4
  export { findElement, findElementInProcess, findProcess, findSequenceFlow, getAllElements, getElementType, getZeebeExtensions, } from "./bpmn/utils.js";
5
5
  export { Bpmn, SAMPLE_BPMN_XML } from "./bpmn/index.js";
6
+ export { stripCamunda8 } from "./bpmn/strip-camunda8.js";
7
+ export type { DroppedCamunda8Item, StripCamunda8Result } from "./bpmn/strip-camunda8.js";
6
8
  export { applyAutoLayout } from "./bpmn/auto-layout.js";
7
9
  export { diffSemantics, projectSemantics, semanticHash } from "./bpmn/semantic-hash.js";
8
10
  export type { JsonValue, SemanticDiff, SemanticProjection } from "./bpmn/semantic-hash.js";
@@ -27,10 +29,10 @@ export { checkDiCompleteness } from "./bpmn/di-check.js";
27
29
  export type { DiCompleteness } from "./bpmn/di-check.js";
28
30
  export { planeForElement, listPlaneElementIds } from "./bpmn/di-planes.js";
29
31
  export { DiagramBuilder, ProcessBuilder } from "./bpmn/bpmn-builder.js";
30
- export type { BranchBuilder, BuildOptions, MessageFlowOptions, ParticipantOptions, DiagramMessageOptions, SubProcessContentBuilder, ServiceTaskOptions, ScriptTaskOptions, UserTaskOptions, CallActivityOptions, BusinessRuleTaskOptions, ElementOptions, GatewayOptions, MultiInstanceOptions, SubProcessOptions, StartEventOptions, IntermediateCatchEventOptions, IntermediateThrowEventOptions, EndEventOptions, BoundaryEventOptions, AdHocSubProcessOptions, AnnotateOptions, } from "./bpmn/bpmn-builder.js";
32
+ export type { BranchBuilder, BuildOptions, MessageFlowOptions, ParticipantOptions, DiagramMessageOptions, SubProcessContentBuilder, ServiceTaskOptions, ScriptTaskOptions, UserTaskOptions, CallActivityOptions, BusinessRuleTaskOptions, ElementOptions, GatewayOptions, MultiInstanceOptions, SubProcessOptions, StartEventOptions, IntermediateCatchEventOptions, IntermediateThrowEventOptions, EndEventOptions, BoundaryEventOptions, ConditionVariableEvent, AdHocSubProcessOptions, AnnotateOptions, } from "./bpmn/bpmn-builder.js";
31
33
  export type { BpmnDefinitions, BpmnProcess, BpmnFlowNode, BpmnFlowElement, BpmnSequenceFlow, BpmnBoundaryEvent, BpmnElementType, BpmnStartEvent, BpmnEndEvent, BpmnIntermediateCatchEvent, BpmnIntermediateThrowEvent, BpmnTask, BpmnServiceTask, BpmnScriptTask, BpmnUserTask, BpmnSendTask, BpmnReceiveTask, BpmnBusinessRuleTask, BpmnManualTask, BpmnCallActivity, BpmnSubProcess, BpmnAdHocSubProcess, BpmnEventSubProcess, BpmnTransaction, BpmnExclusiveGateway, BpmnParallelGateway, BpmnInclusiveGateway, BpmnEventBasedGateway, BpmnComplexGateway, BpmnCollaboration, BpmnParticipant, BpmnMessageFlow, BpmnLane, BpmnLaneSet, BpmnError, BpmnEscalation, BpmnMessage, BpmnSignal, BpmnTextAnnotation, BpmnAssociation, BpmnGroup, BpmnDataObject, BpmnDataObjectReference, BpmnDataStoreReference, BpmnConditionExpression, BpmnEventDefinition, BpmnTimerEventDefinition, BpmnErrorEventDefinition, BpmnEscalationEventDefinition, BpmnMessageEventDefinition, BpmnSignalEventDefinition, BpmnConditionalEventDefinition, BpmnLinkEventDefinition, BpmnCancelEventDefinition, BpmnTerminateEventDefinition, BpmnCompensateEventDefinition, BpmnMultiInstanceLoopCharacteristics, BpmnDiagram, BpmnDiPlane, BpmnDiShape, BpmnDiEdge, BpmnDiLabel, BpmnBounds, BpmnWaypoint, } from "./bpmn/bpmn-model.js";
32
34
  export type { RestConnectorConfig, RestAuthentication, HttpMethod, } from "./bpmn/rest-connector.js";
33
- export type { ZeebeExtensions, ZeebeTaskDefinition, ZeebeIoMapping, ZeebeIoMappingEntry, ZeebeTaskHeaders, ZeebeTaskHeaderEntry, ZeebeProperties, ZeebePropertyEntry, ZeebeFormDefinition, ZeebeCalledDecision, ZeebeAssignmentDefinition, ZeebeTaskSchedule, ZeebePriorityDefinition, ZeebeSubscription, ZeebeAgentDefinition, } from "./bpmn/zeebe-extensions.js";
35
+ export type { ZeebeExtensions, ZeebeTaskDefinition, ZeebeIoMapping, ZeebeIoMappingEntry, ZeebeTaskHeaders, ZeebeTaskHeaderEntry, ZeebeProperties, ZeebePropertyEntry, ZeebeFormDefinition, ZeebeCalledDecision, ZeebeLinkedResource, ZeebeCalledElement, ZeebeAssignmentDefinition, ZeebeTaskSchedule, ZeebePriorityDefinition, ZeebeSubscription, ZeebeAgentDefinition, } from "./bpmn/zeebe-extensions.js";
34
36
  export { assertZeebePlacement, bpmnElementName, ensureZeebeExtension, isZeebePlacementAllowed, ZeebePlacementError, zeebeExtensionsToXmlElements, } from "./bpmn/zeebe-extensions.js";
35
37
  export { ZEEBE_PLACEMENT } from "./bpmn/zeebe-placement.js";
36
38
  export { buildAiAgentSubProcess, AI_AGENT_JOB_WORKER_TASK_TYPE, AI_AGENT_DEFAULT_OUTPUT_ELEMENT, } from "./bpmn/agentic.js";
@@ -87,6 +89,8 @@ export type { ApplyBpmnOperationsOptions, ApplyBpmnOperationsResult, OperationPr
87
89
  export { buildValidationDmn, findValidationStructure, getValidationInputNames, insertValidationStructure, removeValidationStructure, validationDecisionId, } from "./bpmn/input-validation.js";
88
90
  export type { InputVariableDef, ValidationStructure, ValidationVariableType, } from "./bpmn/input-validation.js";
89
91
  export { analyzeCamunda7, convertCamunda7 } from "./bpmn/camunda7/migrate.js";
92
+ export { convertCamunda8To7 } from "./bpmn/camunda7/export.js";
93
+ export type { Camunda8ExportFinding, Camunda8To7Conversion } from "./bpmn/camunda7/export.js";
90
94
  export type { Camunda7Conversion, Camunda7ConvertOptions, Camunda7Finding, Camunda7Report, Camunda7Severity, } from "./bpmn/camunda7/migrate.js";
91
95
  export { translateJuelToFeel } from "./bpmn/camunda7/juel.js";
92
96
  export type { JuelToFeelOptions, JuelToFeelResult } from "./bpmn/camunda7/juel.js";
package/dist/index.js CHANGED
@@ -2,6 +2,7 @@ export { BpmnSdkError, ParseError, ValidationError, WriteError, WriteVerificatio
2
2
  export { isBpmnActivity, isBpmnAdHocSubProcess, isBpmnBoundaryEvent, isBpmnBusinessRuleTask, isBpmnCallActivity, isBpmnComplexGateway, isBpmnDataObject, isBpmnDataObjectReference, isBpmnDataStoreReference, isBpmnEndEvent, isBpmnEvent, isBpmnEventBasedGateway, isBpmnEventSubProcess, isBpmnExclusiveGateway, isBpmnGateway, isBpmnInclusiveGateway, isBpmnIntermediateCatchEvent, isBpmnIntermediateThrowEvent, isBpmnManualTask, isBpmnParallelGateway, isBpmnReceiveTask, isBpmnScriptTask, isBpmnSendTask, isBpmnServiceTask, isBpmnStartEvent, isBpmnSubProcess, isBpmnTask, isBpmnTransaction, isBpmnUserTask, } from "./bpmn/type-guards.js";
3
3
  export { findElement, findElementInProcess, findProcess, findSequenceFlow, getAllElements, getElementType, getZeebeExtensions, } from "./bpmn/utils.js";
4
4
  export { Bpmn, SAMPLE_BPMN_XML } from "./bpmn/index.js";
5
+ export { stripCamunda8 } from "./bpmn/strip-camunda8.js";
5
6
  export { applyAutoLayout } from "./bpmn/auto-layout.js";
6
7
  export { diffSemantics, projectSemantics, semanticHash } from "./bpmn/semantic-hash.js";
7
8
  export { extractProcessContract, generateProcessTypes } from "./bpmn/process-types.js";
@@ -47,6 +48,7 @@ export { applyOperations } from "./bpmn/operations.js";
47
48
  export { applyBpmnOperations, reconcileCompact, OperationError } from "./bpmn/full-operations.js";
48
49
  export { buildValidationDmn, findValidationStructure, getValidationInputNames, insertValidationStructure, removeValidationStructure, validationDecisionId, } from "./bpmn/input-validation.js";
49
50
  export { analyzeCamunda7, convertCamunda7 } from "./bpmn/camunda7/migrate.js";
51
+ export { convertCamunda8To7 } from "./bpmn/camunda7/export.js";
50
52
  export { translateJuelToFeel } from "./bpmn/camunda7/juel.js";
51
53
  export { exportSvg } from "./bpmn/svg.js";
52
54
  export { buildProcessDocumentation, documentationToDocx, documentationToHtml, documentationToMarkdown, renderDocumentationDocx, renderDocumentationHtml, renderDocumentationMarkdown, } from "./doc/index.js";
@@ -6,6 +6,8 @@
6
6
  */
7
7
  import type { BpmnProcess } from "../bpmn/bpmn-model.js";
8
8
  import type { Bounds, LayoutEdge, LayoutNode, Waypoint } from "./types.js";
9
+ /** Side of the linked element an annotation is placed on. */
10
+ export type AnnotationSide = "above" | "below" | "left" | "right";
9
11
  /**
10
12
  * Sizes and packs text annotations around their linked elements without
11
13
  * overlapping each other or any other layout node (incl. node labels).
@@ -19,7 +21,7 @@ export declare function packAnnotations(process: BpmnProcess, layoutNodes: Layou
19
21
  /** Routed connections: an annotation box must not sit on top of one. */
20
22
  layoutEdges?: LayoutEdge[],
21
23
  /** Sides the author asked for, by annotation id. */
22
- sides?: ReadonlyMap<string, "above" | "below">): Map<string, Bounds>;
24
+ sides?: ReadonlyMap<string, AnnotationSide>): Map<string, Bounds>;
23
25
  /**
24
26
  * Edge-to-edge, clamped association waypoints between a linked element and
25
27
  * its annotation. Port of `chooseWaypoints` (tmp/01-annotation-layouting.cjs:365-389).
@@ -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:
@@ -1,8 +1,10 @@
1
- import { ELEMENT_SIZES, LABEL_CHAR_WIDTH, LABEL_MIN_WIDTH } from "../types.js";
1
+ import { ELEMENT_SIZES, LABEL_CHAR_WIDTH, LABEL_HEIGHT, LABEL_MIN_WIDTH, LABEL_VERTICAL_OFFSET, } from "../types.js";
2
2
  import { boundarySide } from "./bands.js";
3
3
  /** Geometry constants. Layout may add space beyond these; it never takes any back. */
4
4
  export const H_GAP = 100;
5
5
  export const V_GAP = 80;
6
+ const GRID_GAP_X = 40;
7
+ const GRID_GAP_Y = 20;
6
8
  export const COMPONENT_GAP = 80;
7
9
  export const LANE_PADDING = 40;
8
10
  export const BOUNDARY_SIZE = 36;
@@ -109,9 +111,18 @@ grid) {
109
111
  const band = bandLayout.bands.get(id) ?? 0;
110
112
  const cw = colWidth.get(rank) ?? size.width;
111
113
  const rh = rowHeight.get(band) ?? size.height;
114
+ // A container taller than the row's ordinary nodes hangs from the task
115
+ // line (top = line - half a task) instead of being centred, so the
116
+ // flows into and out of it stay straight.
117
+ const top = rowY.get(band) ?? 0;
118
+ const y = rh > DEFAULT_SIZE.height
119
+ ? size.height > DEFAULT_SIZE.height
120
+ ? top
121
+ : top + (DEFAULT_SIZE.height - size.height) / 2
122
+ : top + (rh - size.height) / 2;
112
123
  bounds.set(id, {
113
124
  x: (colX.get(rank) ?? 0) + (cw - size.width) / 2,
114
- y: (rowY.get(band) ?? 0) + (rh - size.height) / 2,
125
+ y,
115
126
  width: size.width,
116
127
  height: size.height,
117
128
  });
@@ -148,27 +159,34 @@ function placeGrid(graph, ids, sizes, top, bounds, hint) {
148
159
  const byColumn = hint?.fill === "column";
149
160
  let cellWidth = 0;
150
161
  let cellHeight = 0;
162
+ let labelled = false;
151
163
  for (const id of ids) {
152
164
  const size = sizes.get(id) ?? DEFAULT_SIZE;
153
165
  // An event's or gateway's label is centred below it and can be wider than the
154
166
  // shape; the cell holds it so neighbouring columns' labels never meet.
155
167
  const el = graph.byId.get(id);
156
168
  const label = el?.name ? externalLabelWidth(el.type, el.name) : undefined;
169
+ if (label !== undefined)
170
+ labelled = true;
157
171
  cellWidth = Math.max(cellWidth, size.width, label ?? 0);
158
172
  cellHeight = Math.max(cellHeight, size.height);
159
173
  }
174
+ // Loose nodes carry no flows, so the routing gutters are not needed between
175
+ // them; only a label below a cell needs vertical room.
176
+ const gapX = GRID_GAP_X;
177
+ const gapY = GRID_GAP_Y + (labelled ? LABEL_VERTICAL_OFFSET + LABEL_HEIGHT : 0);
160
178
  ids.forEach((id, i) => {
161
179
  const size = sizes.get(id) ?? DEFAULT_SIZE;
162
180
  const column = byColumn ? Math.floor(i / rows) : i % columns;
163
181
  const row = byColumn ? i % rows : Math.floor(i / columns);
164
182
  bounds.set(id, {
165
- x: column * (cellWidth + H_GAP) + (cellWidth - size.width) / 2,
166
- y: top + row * (cellHeight + V_GAP) + (cellHeight - size.height) / 2,
183
+ x: column * (cellWidth + gapX) + (cellWidth - size.width) / 2,
184
+ y: top + row * (cellHeight + gapY) + (cellHeight - size.height) / 2,
167
185
  width: size.width,
168
186
  height: size.height,
169
187
  });
170
188
  });
171
- return top + rows * (cellHeight + V_GAP) - V_GAP + COMPONENT_GAP;
189
+ return top + rows * (cellHeight + gapY) - gapY + COMPONENT_GAP;
172
190
  }
173
191
  /**
174
192
  * Two nodes can land in the same rank and band — a parallel split whose
@@ -290,6 +290,21 @@ function forwardCandidates(ctx, source, target, sourceRank, targetRank) {
290
290
  ],
291
291
  ];
292
292
  }
293
+ // A tall container hangs from the task line, so the other end's centre falls
294
+ // within its height: dock there and the flow stays straight.
295
+ if (rightOf) {
296
+ const inTarget = from.y > target.y && from.y < target.y + target.height;
297
+ const inSource = to.y > source.y && to.y < source.y + source.height;
298
+ if (inTarget !== inSource) {
299
+ const y = inTarget ? from.y : to.y;
300
+ return [
301
+ [
302
+ { x: source.x + source.width, y },
303
+ { x: target.x, y },
304
+ ],
305
+ ];
306
+ }
307
+ }
293
308
  // Same column, different band: drop straight between the two.
294
309
  if (sourceRank !== undefined && sourceRank === targetRank) {
295
310
  const down = to.y > from.y;
@@ -1,4 +1,5 @@
1
1
  import type { BpmnElementType } from "../bpmn/bpmn-model.js";
2
+ import type { AnnotationSide } from "./annotations.js";
2
3
  /** Fixed element dimensions by type. */
3
4
  export declare const ELEMENT_SIZES: Record<string, {
4
5
  width: number;
@@ -86,7 +87,7 @@ export interface LayoutHints {
86
87
  /** Tool grid per ad-hoc sub-process id. */
87
88
  grids?: Map<string, GridHint>;
88
89
  /** Side per text annotation id, overriding the side the packer would choose. */
89
- annotationSides?: Map<string, "above" | "below">;
90
+ annotationSides?: Map<string, AnnotationSide>;
90
91
  }
91
92
  /** Complete layout result for a process. */
92
93
  export interface LayoutResult {