@bpmnkit/core 1.14.0 → 1.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/AGENTS.md +5 -4
  2. package/agent-cards/bpmn.md +86 -80
  3. package/builder-reference.md +27 -8
  4. package/dist/bpmn/auto-layout.js +235 -42
  5. package/dist/bpmn/bpmn-builder.d.ts +171 -17
  6. package/dist/bpmn/bpmn-builder.js +792 -135
  7. package/dist/bpmn/bpmn-model.d.ts +15 -0
  8. package/dist/bpmn/bpmn-parser.js +32 -6
  9. package/dist/bpmn/bpmn-serializer.js +9 -2
  10. package/dist/bpmn/compact-stream.d.ts +7 -0
  11. package/dist/bpmn/compact-stream.js +7 -0
  12. package/dist/bpmn/compact.d.ts +126 -9
  13. package/dist/bpmn/compact.js +305 -30
  14. package/dist/bpmn/full-operations.d.ts +19 -0
  15. package/dist/bpmn/full-operations.js +191 -7
  16. package/dist/bpmn/make-room.d.ts +26 -0
  17. package/dist/bpmn/make-room.js +151 -0
  18. package/dist/bpmn/optimize/flow.js +8 -0
  19. package/dist/bpmn/place-new-shapes.d.ts +6 -1
  20. package/dist/bpmn/place-new-shapes.js +53 -2
  21. package/dist/bpmn/preserving-writer.d.ts +1 -1
  22. package/dist/bpmn/preserving-writer.js +1 -1
  23. package/dist/bpmn/process-delta.d.ts +32 -1
  24. package/dist/bpmn/process-delta.js +62 -1
  25. package/dist/bpmn/process-text-writer.d.ts +18 -7
  26. package/dist/bpmn/process-text-writer.js +105 -22
  27. package/dist/bpmn/process-text.d.ts +34 -2
  28. package/dist/bpmn/process-text.js +410 -7
  29. package/dist/bpmn/swimlanes.d.ts +178 -0
  30. package/dist/bpmn/swimlanes.js +774 -0
  31. package/dist/form/user-task-forms.d.ts +45 -0
  32. package/dist/form/user-task-forms.js +129 -0
  33. package/dist/index.d.ts +9 -4
  34. package/dist/index.js +5 -2
  35. package/dist/layout/collaboration/message-labels.d.ts +25 -0
  36. package/dist/layout/collaboration/message-labels.js +108 -0
  37. package/dist/layout/collaboration/ordering.d.ts +5 -1
  38. package/dist/layout/collaboration/ordering.js +24 -9
  39. package/dist/layout/semantic/graph.js +3 -0
  40. package/dist/layout/semantic/place.d.ts +2 -0
  41. package/dist/layout/semantic/place.js +77 -9
  42. package/dist/xml/xml-patch.d.ts +1 -1
  43. package/llms.txt +1 -1
  44. package/package.json +2 -2
@@ -0,0 +1,45 @@
1
+ import type { BpmnDefinitions } from "../bpmn/bpmn-model.js";
2
+ import type { FormComponent, FormDefinition } from "./form-model.js";
3
+ /** Options for {@link attachUserTaskForms}. */
4
+ export interface UserTaskFormsOptions {
5
+ /**
6
+ * Form fields per user task id, as `key[:type]` items separated by commas:
7
+ * `amount:number,approved:checkbox,decision:select(approve|reject),note:textarea,due:date,name`.
8
+ * Types: `text` (default), `textarea`, `number`, `checkbox`, `date`, `select(a|b)`.
9
+ * A task without an entry gets a heading and a "Done" checkbox.
10
+ */
11
+ fields?: Record<string, string>;
12
+ /** Form ids that already exist (a `.form` file next to the model); no form is generated for them. */
13
+ existing?: ReadonlySet<string>;
14
+ /** Element ids left as they are: an edit gives forms to the user tasks it adds, not to those already there. */
15
+ skip?: ReadonlySet<string>;
16
+ }
17
+ /** What {@link attachUserTaskForms} did. */
18
+ export interface UserTaskFormsResult {
19
+ /** Ids of the user tasks that had no form and now link one. */
20
+ attached: string[];
21
+ /** One generated form per linked form id not in `existing`; write each as `<id>.form`. */
22
+ forms: FormDefinition[];
23
+ }
24
+ /**
25
+ * Parses a `key[:type]` field list. Unknown types fall back to a text field, so a
26
+ * typo still yields a deployable form.
27
+ */
28
+ export declare function parseFormFields(spec: string): FormComponent[];
29
+ /**
30
+ * Gives every user task a Camunda form in one step, so the model passes the
31
+ * Camunda lint (`camunda-compat/user-task-definition`) and deploys with its forms.
32
+ *
33
+ * A user task with no `zeebe:formDefinition` (or `zeebe:formKey`) gets
34
+ * `formId="<processId>-<taskId>"` and becomes a Camunda user task
35
+ * (`zeebe:userTask`). Every form id a user task or start event links, and that
36
+ * is not in `options.existing`, gets a generated form. Changes `defs` in place.
37
+ *
38
+ * @example
39
+ * ```ts
40
+ * const { forms } = attachUserTaskForms(defs, { fields: { review: "amount:number,approved:checkbox" } })
41
+ * for (const form of forms) writeFileSync(`${form.id}.form`, Form.export(form))
42
+ * ```
43
+ */
44
+ export declare function attachUserTaskForms(defs: BpmnDefinitions, options?: UserTaskFormsOptions): UserTaskFormsResult;
45
+ //# sourceMappingURL=user-task-forms.d.ts.map
@@ -0,0 +1,129 @@
1
+ const FORM_LINK = new Set(["zeebe:formDefinition", "zeebe:formKey"]);
2
+ function* walk(elements) {
3
+ for (const el of elements) {
4
+ yield el;
5
+ if ("flowElements" in el && Array.isArray(el.flowElements))
6
+ yield* walk(el.flowElements);
7
+ }
8
+ }
9
+ function labelOf(key) {
10
+ const words = key
11
+ .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
12
+ .replace(/[_-]+/g, " ")
13
+ .trim();
14
+ return words.charAt(0).toUpperCase() + words.slice(1).toLowerCase();
15
+ }
16
+ /** A FEEL-safe variable name: form keys become process variables. */
17
+ function variableOf(text) {
18
+ const camel = text.replace(/[^A-Za-z0-9]+(.)?/g, (_m, c) => c === undefined ? "" : c.toUpperCase());
19
+ return /^[A-Za-z_]/.test(camel) ? camel : `v${camel}`;
20
+ }
21
+ /**
22
+ * Parses a `key[:type]` field list. Unknown types fall back to a text field, so a
23
+ * typo still yields a deployable form.
24
+ */
25
+ export function parseFormFields(spec) {
26
+ const components = [];
27
+ for (const raw of spec.split(",")) {
28
+ const item = raw.trim();
29
+ if (item === "")
30
+ continue;
31
+ const match = /^([^:]+)(?::(\w+)(?:\(([^)]*)\))?)?$/.exec(item);
32
+ const key = variableOf((match?.[1] ?? item).trim());
33
+ const type = (match?.[2] ?? "text").toLowerCase();
34
+ const id = `Field_${key}`;
35
+ const label = labelOf(key);
36
+ switch (type) {
37
+ case "number":
38
+ case "textarea":
39
+ case "checkbox":
40
+ components.push({ id, type, label, key });
41
+ break;
42
+ case "date":
43
+ components.push({ id, type: "datetime", key, subtype: "date", dateLabel: label });
44
+ break;
45
+ case "select": {
46
+ const values = (match?.[3] ?? "")
47
+ .split("|")
48
+ .map((v) => v.trim())
49
+ .filter(Boolean)
50
+ .map((value) => ({ label: labelOf(value), value }));
51
+ components.push({ id, type: "select", label, key, values });
52
+ break;
53
+ }
54
+ default:
55
+ components.push({ id, type: "textfield", label, key });
56
+ }
57
+ }
58
+ return components;
59
+ }
60
+ function formFor(formId, title, spec, taskId) {
61
+ const fields = spec !== undefined
62
+ ? parseFormFields(spec)
63
+ : [
64
+ {
65
+ id: "Field_done",
66
+ type: "checkbox",
67
+ label: "Done",
68
+ key: `${variableOf(taskId)}Done`,
69
+ },
70
+ ];
71
+ const form = {
72
+ id: formId,
73
+ type: "default",
74
+ executionPlatform: "Camunda Cloud",
75
+ executionPlatformVersion: "8.10.0",
76
+ schemaVersion: 16,
77
+ components: [{ id: "Field_title", type: "text", text: `## ${title}` }, ...fields],
78
+ };
79
+ return form;
80
+ }
81
+ /**
82
+ * Gives every user task a Camunda form in one step, so the model passes the
83
+ * Camunda lint (`camunda-compat/user-task-definition`) and deploys with its forms.
84
+ *
85
+ * A user task with no `zeebe:formDefinition` (or `zeebe:formKey`) gets
86
+ * `formId="<processId>-<taskId>"` and becomes a Camunda user task
87
+ * (`zeebe:userTask`). Every form id a user task or start event links, and that
88
+ * is not in `options.existing`, gets a generated form. Changes `defs` in place.
89
+ *
90
+ * @example
91
+ * ```ts
92
+ * const { forms } = attachUserTaskForms(defs, { fields: { review: "amount:number,approved:checkbox" } })
93
+ * for (const form of forms) writeFileSync(`${form.id}.form`, Form.export(form))
94
+ * ```
95
+ */
96
+ export function attachUserTaskForms(defs, options = {}) {
97
+ const attached = [];
98
+ const forms = new Map();
99
+ for (const process of defs.processes) {
100
+ for (const el of walk(process.flowElements)) {
101
+ if (el.type !== "userTask" && el.type !== "startEvent")
102
+ continue;
103
+ if (options.skip?.has(el.id))
104
+ continue;
105
+ const ext = el.extensionElements;
106
+ let link = ext.find((x) => FORM_LINK.has(x.name));
107
+ if (link === undefined && el.type === "userTask") {
108
+ link = {
109
+ name: "zeebe:formDefinition",
110
+ attributes: { formId: `${process.id}-${el.id}` },
111
+ children: [],
112
+ };
113
+ if (!ext.some((x) => x.name === "zeebe:userTask"))
114
+ ext.push({ name: "zeebe:userTask", attributes: {}, children: [] });
115
+ ext.push(link);
116
+ attached.push(el.id);
117
+ }
118
+ const formId = link?.attributes.formId;
119
+ // A FEEL form id is resolved at runtime; only a static one names a file to write.
120
+ if (formId === undefined || formId === "" || formId.startsWith("="))
121
+ continue;
122
+ if (options.existing?.has(formId) || forms.has(formId))
123
+ continue;
124
+ forms.set(formId, formFor(formId, el.name ?? el.id, options.fields?.[el.id], el.id));
125
+ }
126
+ }
127
+ return { attached, forms: [...forms.values()] };
128
+ }
129
+ //# sourceMappingURL=user-task-forms.js.map
package/dist/index.d.ts CHANGED
@@ -14,6 +14,8 @@ export { stripCamunda8 } from "./bpmn/strip-camunda8.js";
14
14
  export type { DroppedCamunda8Item, StripCamunda8Result } from "./bpmn/strip-camunda8.js";
15
15
  export { applyAutoLayout } from "./bpmn/auto-layout.js";
16
16
  export { placeNewShapes } from "./bpmn/place-new-shapes.js";
17
+ export { makeRoom } from "./bpmn/make-room.js";
18
+ export type { MakeRoomResult } from "./bpmn/make-room.js";
17
19
  export type { PlaceNewShapesOptions, PlaceNewShapesResult } from "./bpmn/place-new-shapes.js";
18
20
  export { diffSemantics, projectSemantics, semanticHash } from "./bpmn/semantic-hash.js";
19
21
  export type { JsonValue, SemanticDiff, SemanticProjection } from "./bpmn/semantic-hash.js";
@@ -48,7 +50,8 @@ export { checkDiCompleteness } from "./bpmn/di-check.js";
48
50
  export type { DiCompleteness } from "./bpmn/di-check.js";
49
51
  export { planeForElement, listPlaneElementIds } from "./bpmn/di-planes.js";
50
52
  export { DiagramBuilder, ProcessBuilder } from "./bpmn/bpmn-builder.js";
51
- export type { BranchBuilder, BuildOptions, BuildGateOptions, SendTaskOptions, 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";
53
+ export { allLanes, assignLane, collaborationProblems, laneForNewNode, laneOf, laneProblems, leafLanes, messageEndProblem, pinPrimaryProcess, primaryProcess, } from "./bpmn/swimlanes.js";
54
+ export type { BranchBuilder, BuildOptions, BuildGateOptions, SendTaskOptions, DeclaredLaneOptions, LaneOptions, 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";
52
55
  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";
53
56
  export type { RestConnectorConfig, RestAuthentication, HttpMethod, } from "./bpmn/rest-connector.js";
54
57
  export type { ZeebeExtensions, ZeebeTaskDefinition, ZeebeIoMapping, ZeebeIoMappingEntry, ZeebeTaskHeaders, ZeebeTaskHeaderEntry, ZeebeProperties, ZeebePropertyEntry, ZeebeFormDefinition, ZeebeCalledDecision, ZeebeLinkedResource, ZeebeCalledElement, ZeebeAssignmentDefinition, ZeebeTaskSchedule, ZeebePriorityDefinition, ZeebeSubscription, ZeebeAgentDefinition, } from "./bpmn/zeebe-extensions.js";
@@ -60,6 +63,8 @@ export { Dmn, drgId, layoutDmn, benchmarkDmnLayout, compactifyDmn, expandDmn } f
60
63
  export type { DmnBenchmarkResult, DmnElementPosition, CompactDmn, CompactDmnDecision, CompactDmnInput, CompactDmnOutput, CompactDmnRule, } from "./dmn/index.js";
61
64
  export { Form, compactifyForm, expandForm } from "./form/index.js";
62
65
  export { lintForm } from "./form/lint.js";
66
+ export { attachUserTaskForms, parseFormFields } from "./form/user-task-forms.js";
67
+ export type { UserTaskFormsOptions, UserTaskFormsResult } from "./form/user-task-forms.js";
63
68
  export { lintDmn } from "./dmn/lint.js";
64
69
  export type { CheckFinding, CheckSeverity } from "./check-finding.js";
65
70
  export type { CompactForm, CompactFormField } from "./form/index.js";
@@ -94,13 +99,13 @@ export { ELEMENT_SIZES, GRID_CELL_HEIGHT, GRID_CELL_WIDTH } from "./layout/index
94
99
  export { compactify, expand } from "./bpmn/compact.js";
95
100
  export { createCompactStream } from "./bpmn/compact-stream.js";
96
101
  export type { CompactStream, CompactStreamOptions } from "./bpmn/compact-stream.js";
97
- export { PROCESS_TEXT_GUIDE, conditionOrLabel, createProcessTextStream, parseProcessText, } from "./bpmn/process-text.js";
102
+ export { MESSAGE_LINE, POOL_LINE, PROCESS_TEXT_GUIDE, conditionOrLabel, createProcessTextStream, nameFromId, parseProcessText, } from "./bpmn/process-text.js";
98
103
  export type { ProcessTextProblem, ProcessTextQuestion, ProcessTextResult, ProcessTextStream, ConnectorRef, } from "./bpmn/process-text.js";
99
104
  export { parseConnectorLine } from "./bpmn/connector-line.js";
100
105
  export type { ConnectorLine } from "./bpmn/connector-line.js";
101
106
  export { PROCESS_DELTA_GUIDE, parseProcessDelta } from "./bpmn/process-delta.js";
102
107
  export type { DeltaFlow, DeltaNode, ProcessDelta } from "./bpmn/process-delta.js";
103
- export { writableCondition, writableLabel, writableName, writeProcessText, } from "./bpmn/process-text-writer.js";
108
+ export { writableCondition, writableLabel, writableMessageLabel, writableName, writeProcessText, } from "./bpmn/process-text-writer.js";
104
109
  export type { WriteProcessTextOptions, WrittenProcessText } from "./bpmn/process-text-writer.js";
105
110
  export { ELEMENT_GROUP_ORDER, ELEMENT_TYPE_GROUPS, allElementTypes, elementTypesInGroup, } from "./bpmn/element-catalog.js";
106
111
  export type { ElementTypeGroup } from "./bpmn/element-catalog.js";
@@ -123,7 +128,7 @@ export { exportDrdSvg, exportDecisionTableSvg } from "./dmn/svg.js";
123
128
  export type { DecisionTableSvgOptions, DmnSvgOptions } from "./dmn/svg.js";
124
129
  export { buildProcessDocumentation, documentationToDocx, documentationToHtml, documentationToMarkdown, renderDocumentationDocx, renderDocumentationHtml, renderDocumentationMarkdown, } from "./doc/index.js";
125
130
  export type { DocumentationLink, DocumentationOptions, DocumentedDecision, DocumentedElement, DocumentedForm, DocumentedFormField, DocumentedLane, DocumentedMessageFlow, DocumentedProcess, DocumentedProperty, DocxDocumentationOptions, ProcessDocumentation, } from "./doc/index.js";
126
- export type { CompactDiagram, CompactElement, CompactFlow, CompactNote, CompactProcess, ExpandOptions, } from "./bpmn/compact.js";
131
+ export type { CompactDiagram, CompactElement, CompactFlow, CompactLane, CompactMessageFlow, CompactNote, CompactParticipant, CompactProcess, ExpandOptions, } from "./bpmn/compact.js";
127
132
  export { compilePlan, extractPlan, mergePlan, slugify, uniqueId, } from "./plan/index.js";
128
133
  export type { CompilePlanOptions, ConnectorApplyResult, ConnectorResolver, ExtractResult, PlanAgentTool, PlanAiAgentStep, PlanBranch, PlanBusinessRuleTaskStep, PlanCallActivityStep, PlanConnectorRef, PlanConnectorStep, PlanEndStep, PlanErrorBoundary, PlanGatewayStep, PlanInputVariable, PlanProblem, PlanRawStep, PlanReceiveTaskStep, PlanScenario, PlanScriptTaskStep, PlanSendTaskStep, PlanServiceTaskStep, PlanStartStep, PlanStep, PlanSubProcessStep, PlanTimerBoundary, PlanUserTaskStep, PlanWaitStep, ProcessPlan, SynthResult, UnsupportedElement, } from "./plan/index.js";
129
134
  export { listSecrets } from "./bpmn/secrets.js";
package/dist/index.js CHANGED
@@ -11,6 +11,7 @@ export { Bpmn, SAMPLE_BPMN_XML } from "./bpmn/index.js";
11
11
  export { stripCamunda8 } from "./bpmn/strip-camunda8.js";
12
12
  export { applyAutoLayout } from "./bpmn/auto-layout.js";
13
13
  export { placeNewShapes } from "./bpmn/place-new-shapes.js";
14
+ export { makeRoom } from "./bpmn/make-room.js";
14
15
  export { diffSemantics, projectSemantics, semanticHash } from "./bpmn/semantic-hash.js";
15
16
  export { extractProcessContract, generateProcessTypes } from "./bpmn/process-types.js";
16
17
  export { isDeployable, validateDeployable, validateDeployableXml, } from "./bpmn/zeebe-validate/index.js";
@@ -30,12 +31,14 @@ export { compositeKey, stableToken } from "./types/stable-key.js";
30
31
  export { checkDiCompleteness } from "./bpmn/di-check.js";
31
32
  export { planeForElement, listPlaneElementIds } from "./bpmn/di-planes.js";
32
33
  export { DiagramBuilder, ProcessBuilder } from "./bpmn/bpmn-builder.js";
34
+ export { allLanes, assignLane, collaborationProblems, laneForNewNode, laneOf, laneProblems, leafLanes, messageEndProblem, pinPrimaryProcess, primaryProcess, } from "./bpmn/swimlanes.js";
33
35
  export { assertZeebePlacement, bpmnElementName, ensureZeebeExtension, isZeebePlacementAllowed, ZeebePlacementError, zeebeExtensionsToXmlElements, } from "./bpmn/zeebe-extensions.js";
34
36
  export { ZEEBE_PLACEMENT } from "./bpmn/zeebe-placement.js";
35
37
  export { buildAiAgentSubProcess, AI_AGENT_JOB_WORKER_TASK_TYPE, AI_AGENT_DEFAULT_OUTPUT_ELEMENT, } from "./bpmn/agentic.js";
36
38
  export { Dmn, drgId, layoutDmn, benchmarkDmnLayout, compactifyDmn, expandDmn } from "./dmn/index.js";
37
39
  export { Form, compactifyForm, expandForm } from "./form/index.js";
38
40
  export { lintForm } from "./form/lint.js";
41
+ export { attachUserTaskForms, parseFormFields } from "./form/user-task-forms.js";
39
42
  export { lintDmn } from "./dmn/lint.js";
40
43
  export { FormBuilder, GroupBuilder } from "./form/form-builder.js";
41
44
  export { generateId, resetIdCounter } from "./types/id-generator.js";
@@ -52,10 +55,10 @@ export { benchmarkLayout, compareLayouts, formatBenchmarkResult, generateAutoLay
52
55
  export { ELEMENT_SIZES, GRID_CELL_HEIGHT, GRID_CELL_WIDTH } from "./layout/index.js";
53
56
  export { compactify, expand } from "./bpmn/compact.js";
54
57
  export { createCompactStream } from "./bpmn/compact-stream.js";
55
- export { PROCESS_TEXT_GUIDE, conditionOrLabel, createProcessTextStream, parseProcessText, } from "./bpmn/process-text.js";
58
+ export { MESSAGE_LINE, POOL_LINE, PROCESS_TEXT_GUIDE, conditionOrLabel, createProcessTextStream, nameFromId, parseProcessText, } from "./bpmn/process-text.js";
56
59
  export { parseConnectorLine } from "./bpmn/connector-line.js";
57
60
  export { PROCESS_DELTA_GUIDE, parseProcessDelta } from "./bpmn/process-delta.js";
58
- export { writableCondition, writableLabel, writableName, writeProcessText, } from "./bpmn/process-text-writer.js";
61
+ export { writableCondition, writableLabel, writableMessageLabel, writableName, writeProcessText, } from "./bpmn/process-text-writer.js";
59
62
  export { ELEMENT_GROUP_ORDER, ELEMENT_TYPE_GROUPS, allElementTypes, elementTypesInGroup, } from "./bpmn/element-catalog.js";
60
63
  export { createFlowElement, retypeElement } from "./bpmn/element-shape.js";
61
64
  export { applyOperations } from "./bpmn/operations.js";
@@ -0,0 +1,25 @@
1
+ /**
2
+ * Labels around message flows, placed after the flows are routed.
3
+ *
4
+ * A message flow's name is what the pools say to each other, so it belongs on
5
+ * the flow where nothing else is: the empty band between two pools. And a flow
6
+ * docking under an event runs straight through the name the event carries
7
+ * below itself, so that name moves above the event (or beside it).
8
+ */
9
+ import type { BpmnDiEdge, BpmnDiShape } from "../../bpmn/bpmn-model.js";
10
+ export interface MessageLabelInput {
11
+ shapes: BpmnDiShape[];
12
+ edges: BpmnDiEdge[];
13
+ /** Named message flows by id. */
14
+ names: ReadonlyMap<string, string>;
15
+ /** Pools, lanes and expanded sub-processes: drawn around content, not obstacles. */
16
+ containers: ReadonlySet<string>;
17
+ /** Pools, top to bottom, for the bands between them. */
18
+ pools: ReadonlySet<string>;
19
+ }
20
+ /**
21
+ * Moves an event's name off the message flow docking on it, then gives each
22
+ * named message flow a label in the band between pools when one is free.
23
+ */
24
+ export declare function placeMessageFlowLabels(input: MessageLabelInput): void;
25
+ //# sourceMappingURL=message-labels.d.ts.map
@@ -0,0 +1,108 @@
1
+ import { LABEL_CHAR_WIDTH, LABEL_HEIGHT, LABEL_MIN_WIDTH } from "../types.js";
2
+ /** Space between a flow and the label beside it. */
3
+ const LABEL_GAP = 4;
4
+ /** How far a label slides along its segment per try. */
5
+ const SLIDE_STEP = 10;
6
+ function overlaps(a, b) {
7
+ 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;
8
+ }
9
+ function crosses(p, q, b) {
10
+ return (Math.max(p.x, q.x) > b.x &&
11
+ Math.min(p.x, q.x) < b.x + b.width &&
12
+ Math.max(p.y, q.y) > b.y &&
13
+ Math.min(p.y, q.y) < b.y + b.height);
14
+ }
15
+ function edgeThrough(edge, b) {
16
+ return edge.waypoints.slice(1).some((q, i) => {
17
+ const p = edge.waypoints[i];
18
+ return p !== undefined && crosses(p, q, b);
19
+ });
20
+ }
21
+ /**
22
+ * Moves an event's name off the message flow docking on it, then gives each
23
+ * named message flow a label in the band between pools when one is free.
24
+ */
25
+ export function placeMessageFlowLabels(input) {
26
+ const { shapes, edges, names, containers, pools } = input;
27
+ const messageEdges = edges.filter((e) => names.has(e.bpmnElement));
28
+ if (messageEdges.length === 0)
29
+ return;
30
+ const solids = shapes.filter((s) => !containers.has(s.bpmnElement)).map((s) => s.bounds);
31
+ const labels = () => [
32
+ ...shapes.flatMap((s) => (s.label?.bounds ? [s.label.bounds] : [])),
33
+ ...edges.flatMap((e) => (e.label?.bounds ? [e.label.bounds] : [])),
34
+ ];
35
+ const free = (b, own) => !solids.some((s) => overlaps(s, b)) &&
36
+ !labels().some((l) => l !== own && overlaps(l, b)) &&
37
+ !edges.some((e) => edgeThrough(e, b));
38
+ for (const shape of shapes) {
39
+ const label = shape.label?.bounds;
40
+ if (label === undefined || !messageEdges.some((e) => edgeThrough(e, label)))
41
+ continue;
42
+ const s = shape.bounds;
43
+ const cx = s.x + s.width / 2;
44
+ const spot = [
45
+ { x: cx - label.width / 2, y: s.y - LABEL_GAP - label.height },
46
+ { x: s.x + s.width + LABEL_GAP, y: s.y + s.height },
47
+ { x: s.x - LABEL_GAP - label.width, y: s.y + s.height },
48
+ { x: s.x + s.width + LABEL_GAP, y: s.y - label.height },
49
+ ]
50
+ .map((p) => ({
51
+ x: Math.round(p.x),
52
+ y: Math.round(p.y),
53
+ width: label.width,
54
+ height: label.height,
55
+ }))
56
+ .find((b) => free(b, label));
57
+ if (spot && shape.label)
58
+ shape.label.bounds = spot;
59
+ }
60
+ const poolBounds = shapes
61
+ .filter((s) => pools.has(s.bpmnElement))
62
+ .map((s) => s.bounds)
63
+ .sort((a, b) => a.y - b.y);
64
+ const bands = [];
65
+ for (let i = 0; i + 1 < poolBounds.length; i++) {
66
+ const above = poolBounds[i];
67
+ const below = poolBounds[i + 1];
68
+ if (above && below && below.y > above.y + above.height)
69
+ bands.push({ top: above.y + above.height, bottom: below.y });
70
+ }
71
+ for (const edge of messageEdges) {
72
+ const name = names.get(edge.bpmnElement) ?? "";
73
+ const width = Math.max(name.length * LABEL_CHAR_WIDTH, LABEL_MIN_WIDTH);
74
+ const height = LABEL_HEIGHT;
75
+ const beside = (x, y) => [
76
+ { x: Math.round(x + LABEL_GAP), y: Math.round(y - height / 2), width, height },
77
+ { x: Math.round(x - LABEL_GAP - width), y: Math.round(y - height / 2), width, height },
78
+ ];
79
+ const candidates = [];
80
+ const vertical = [];
81
+ for (let i = 0; i + 1 < edge.waypoints.length; i++) {
82
+ const p = edge.waypoints[i];
83
+ const q = edge.waypoints[i + 1];
84
+ if (!p || !q || p.x !== q.x)
85
+ continue;
86
+ vertical.push({ x: p.x, top: Math.min(p.y, q.y), bottom: Math.max(p.y, q.y) });
87
+ }
88
+ // In a band first: nothing else is drawn there.
89
+ for (const v of vertical)
90
+ for (const band of bands)
91
+ if (v.top <= band.top && band.bottom <= v.bottom)
92
+ candidates.push(...beside(v.x, (band.top + band.bottom) / 2));
93
+ // Then along the longest run, from its middle outwards.
94
+ vertical.sort((a, b) => b.bottom - b.top - (a.bottom - a.top));
95
+ for (const v of vertical) {
96
+ const mid = (v.top + v.bottom) / 2;
97
+ for (let d = 0; d <= (v.bottom - v.top) / 2; d += SLIDE_STEP)
98
+ candidates.push(...beside(v.x, mid + d), ...beside(v.x, mid - d));
99
+ }
100
+ const spot = candidates.find((b) => !solids.some((s) => overlaps(s, b)) &&
101
+ !labels().some((l) => overlaps(l, b)) &&
102
+ !edges.some((e) => e !== edge && edgeThrough(e, b)));
103
+ const chosen = spot ?? candidates[0];
104
+ if (chosen)
105
+ edge.label = { bounds: chosen };
106
+ }
107
+ }
108
+ //# sourceMappingURL=message-labels.js.map
@@ -24,6 +24,10 @@ export interface PoolLink {
24
24
  /**
25
25
  * Order pools by their message-flow relationships. Returns indices into the
26
26
  * input order; an input with no message flows comes back unchanged.
27
+ *
28
+ * `edges` are pools that read better at the top or bottom of the stack: black
29
+ * boxes, partners on the rim of the conversation. Preferred there when it costs
30
+ * the messages no more than one pool step.
27
31
  */
28
- export declare function orderPools(count: number, links: readonly PoolLink[]): number[];
32
+ export declare function orderPools(count: number, links: readonly PoolLink[], edges?: ReadonlySet<number>): number[];
29
33
  //# sourceMappingURL=ordering.d.ts.map
@@ -52,7 +52,13 @@ function pairCosts(links) {
52
52
  * term is a tie-break: with nothing to gain from moving, the pools stay where
53
53
  * the author put them.
54
54
  */
55
- function cost(order, pairs) {
55
+ /**
56
+ * What an edge pool costs for sitting between two others: one message's pool
57
+ * step. It settles near-ties toward the rim but never stretches the messages
58
+ * further, which reads worse than a black box in the middle.
59
+ */
60
+ const EDGE_PENALTY = 1;
61
+ function cost(order, pairs, edges = new Set()) {
56
62
  const position = [];
57
63
  for (let i = 0; i < order.length; i++) {
58
64
  const id = order[i];
@@ -67,6 +73,9 @@ function cost(order, pairs) {
67
73
  continue;
68
74
  total += pair.weight * Math.abs(a - b) + (a < b ? pair.aAbove : pair.aBelow);
69
75
  }
76
+ for (let i = 1; i + 1 < order.length; i++)
77
+ if (edges.has(order[i] ?? -1))
78
+ total += EDGE_PENALTY;
70
79
  let drift = 0;
71
80
  for (let i = 0; i < order.length; i++)
72
81
  drift += Math.abs((order[i] ?? i) - i);
@@ -75,21 +84,27 @@ function cost(order, pairs) {
75
84
  /**
76
85
  * Order pools by their message-flow relationships. Returns indices into the
77
86
  * input order; an input with no message flows comes back unchanged.
87
+ *
88
+ * `edges` are pools that read better at the top or bottom of the stack: black
89
+ * boxes, partners on the rim of the conversation. Preferred there when it costs
90
+ * the messages no more than one pool step.
78
91
  */
79
- export function orderPools(count, links) {
92
+ export function orderPools(count, links, edges = new Set()) {
80
93
  const identity = Array.from({ length: count }, (_, i) => i);
81
94
  if (count < 3 || links.length === 0)
82
95
  return identity;
83
96
  const pairs = pairCosts(links);
84
- return count <= EXHAUSTIVE_LIMIT ? exhaustive(identity, pairs) : refine(identity, pairs);
97
+ return count <= EXHAUSTIVE_LIMIT
98
+ ? exhaustive(identity, pairs, edges)
99
+ : refine(identity, pairs, edges);
85
100
  }
86
101
  /** Every order, best first-found wins — so declaration order survives a tie. */
87
- function exhaustive(identity, pairs) {
102
+ function exhaustive(identity, pairs, edges) {
88
103
  let best = identity;
89
- let bestCost = cost(identity, pairs);
104
+ let bestCost = cost(identity, pairs, edges);
90
105
  const permute = (prefix, rest) => {
91
106
  if (rest.length === 0) {
92
- const candidate = cost(prefix, pairs);
107
+ const candidate = cost(prefix, pairs, edges);
93
108
  if (candidate < bestCost) {
94
109
  best = [...prefix];
95
110
  bestCost = candidate;
@@ -110,9 +125,9 @@ function exhaustive(identity, pairs) {
110
125
  * Take each pool out and put it back wherever it fits best, repeating until a
111
126
  * full sweep changes nothing.
112
127
  */
113
- function refine(identity, pairs) {
128
+ function refine(identity, pairs, edges) {
114
129
  let order = [...identity];
115
- let current = cost(order, pairs);
130
+ let current = cost(order, pairs, edges);
116
131
  for (let sweep = 0; sweep < order.length; sweep++) {
117
132
  let improved = false;
118
133
  for (let from = 0; from < order.length; from++) {
@@ -124,7 +139,7 @@ function refine(identity, pairs) {
124
139
  if (to === from)
125
140
  continue;
126
141
  const candidate = [...without.slice(0, to), pool, ...without.slice(to)];
127
- const candidateCost = cost(candidate, pairs);
142
+ const candidateCost = cost(candidate, pairs, edges);
128
143
  if (candidateCost < current) {
129
144
  order = candidate;
130
145
  current = candidateCost;
@@ -17,6 +17,9 @@ export function buildSemanticGraph(flowElements, sequenceFlows) {
17
17
  const nodes = [];
18
18
  const attachers = new Map();
19
19
  for (const el of flowElements) {
20
+ // A data object has no shape: its references are what a diagram draws.
21
+ if (el.type === "dataObject")
22
+ continue;
20
23
  if (el.type === "boundaryEvent") {
21
24
  const be = el;
22
25
  const list = attachers.get(be.attachedToRef);
@@ -17,6 +17,8 @@ export declare const CONTAINER_GAP = 100;
17
17
  export declare const COMPONENT_GAP = 80;
18
18
  export declare const LANE_PADDING = 40;
19
19
  export declare const BOUNDARY_SIZE = 36;
20
+ /** Height of a lane band with nothing in it: room for one boundary-sized row. */
21
+ export declare const MIN_LANE_HEIGHT: number;
20
22
  /**
21
23
  * Width of the label an event or gateway carries centred below its shape;
22
24
  * undefined for types whose name sits inside the shape.
@@ -21,6 +21,8 @@ const GRID_GAP_Y = 20;
21
21
  export const COMPONENT_GAP = 80;
22
22
  export const LANE_PADDING = 40;
23
23
  export const BOUNDARY_SIZE = 36;
24
+ /** Height of a lane band with nothing in it: room for one boundary-sized row. */
25
+ export const MIN_LANE_HEIGHT = 2 * LANE_PADDING + BOUNDARY_SIZE;
24
26
  const DEFAULT_SIZE = { width: 100, height: 80 };
25
27
  const EXTERNAL_LABEL_TYPES = new Set([
26
28
  "startEvent",
@@ -449,6 +451,29 @@ function applyLanes(graph, laneSet, bounds) {
449
451
  for (const ref of leaf.refs)
450
452
  laneOf.set(ref, leaf);
451
453
  }
454
+ // A data object or store is never a lane member (BPMN lanes hold flow nodes), so it
455
+ // follows the first laned activity wired to it; otherwise it lands below the
456
+ // lanes, outside the pool.
457
+ const dataHome = new Map();
458
+ const follow = (ref, lane, activity) => {
459
+ if (laneOf.has(ref))
460
+ return;
461
+ laneOf.set(ref, lane);
462
+ dataHome.set(ref, activity);
463
+ };
464
+ for (const node of graph.nodes) {
465
+ const lane = laneOf.get(node.id);
466
+ if (!lane)
467
+ continue;
468
+ for (const a of node.dataInputAssociations ?? []) {
469
+ for (const ref of a.sourceRefs)
470
+ follow(ref, lane, node.id);
471
+ }
472
+ for (const a of node.dataOutputAssociations ?? []) {
473
+ if (a.targetRef !== undefined)
474
+ follow(a.targetRef, lane, node.id);
475
+ }
476
+ }
452
477
  const members = new Map();
453
478
  for (const leaf of leaves)
454
479
  members.set(leaf.id, []);
@@ -461,6 +486,7 @@ function applyLanes(graph, laneSet, bounds) {
461
486
  else
462
487
  orphans.push(node.id);
463
488
  }
489
+ placeDataUnderActivities(members, dataHome, bounds);
464
490
  let minX = Number.POSITIVE_INFINITY;
465
491
  let maxX = Number.NEGATIVE_INFINITY;
466
492
  for (const b of bounds.values()) {
@@ -477,7 +503,7 @@ function applyLanes(graph, laneSet, bounds) {
477
503
  const own = (members.get(leaf.id) ?? [])
478
504
  .map((n) => bounds.get(n))
479
505
  .filter((b) => b !== undefined);
480
- let height = 2 * LANE_PADDING + BOUNDARY_SIZE;
506
+ let height = MIN_LANE_HEIGHT;
481
507
  if (own.length > 0) {
482
508
  const lowest = Math.min(...own.map((b) => b.y));
483
509
  height = Math.max(...own.map((b) => b.y + b.height)) - lowest + 2 * LANE_PADDING;
@@ -509,6 +535,7 @@ function applyLanes(graph, laneSet, bounds) {
509
535
  span.set(node.id, own);
510
536
  slots.push({
511
537
  id: node.id,
538
+ depth: node.depth,
512
539
  bounds: { x: left, y: own.top, width, height: own.bottom - own.top },
513
540
  });
514
541
  extent = extent
@@ -518,15 +545,56 @@ function applyLanes(graph, laneSet, bounds) {
518
545
  return extent;
519
546
  };
520
547
  emit(tree);
521
- // Outermost first, so a parent lane is drawn behind the lanes it contains.
522
- return slots.sort((a, b) => b.bounds.height - a.bounds.height || a.bounds.y - b.bounds.y);
548
+ // Outermost first, so a parent lane is drawn behind the lanes it contains. A
549
+ // parent with one child has the child's exact bounds, so depth decides; the
550
+ // height and y keys keep the order flat lane sets have always had.
551
+ return slots
552
+ .sort((a, b) => a.depth - b.depth || b.bounds.height - a.bounds.height || a.bounds.y - b.bounds.y)
553
+ .map(({ id, bounds }) => ({ id, bounds }));
523
554
  }
524
- function laneTree(laneSet) {
525
- return laneSet.lanes.map((lane) => ({
526
- id: lane.id,
527
- refs: lane.flowNodeRefs,
528
- children: lane.childLaneSet ? laneTree(lane.childLaneSet) : [],
529
- }));
555
+ /**
556
+ * Puts each lane's data objects and stores in a row under the lane's flow nodes,
557
+ * each centred below the activity it is wired to, so the lane grows by one row
558
+ * instead of stretching to wherever the data was ranked.
559
+ */
560
+ function placeDataUnderActivities(members, dataHome, bounds) {
561
+ for (const ids of members.values()) {
562
+ const flow = ids.filter((id) => !dataHome.has(id)).map((id) => bounds.get(id));
563
+ const homeX = (id) => bounds.get(dataHome.get(id) ?? "")?.x ?? 0;
564
+ const data = ids.filter((id) => dataHome.has(id)).sort((a, b) => homeX(a) - homeX(b));
565
+ if (data.length === 0 || flow.length === 0)
566
+ continue;
567
+ const bottom = Math.max(...flow.map((b) => (b ? b.y + b.height : 0)));
568
+ let right = Number.NEGATIVE_INFINITY;
569
+ for (const id of data) {
570
+ const b = bounds.get(id);
571
+ const home = bounds.get(dataHome.get(id) ?? "");
572
+ if (!b || !home)
573
+ continue;
574
+ b.x = Math.max(home.x + home.width / 2 - b.width / 2, right + H_GAP / 2);
575
+ b.y = bottom + V_GAP / 2;
576
+ right = b.x + b.width;
577
+ }
578
+ }
579
+ }
580
+ /**
581
+ * The lane set as a tree of ids and refs.
582
+ *
583
+ * @throws Error when one lane object occurs twice, as a lane set that contains
584
+ * itself does; walking it would never end.
585
+ */
586
+ function laneTree(laneSet, depth = 0, seen = new Set()) {
587
+ return laneSet.lanes.map((lane) => {
588
+ if (seen.has(lane))
589
+ throw new Error(`Lane ${lane.id} occurs twice in its lane set`);
590
+ seen.add(lane);
591
+ return {
592
+ id: lane.id,
593
+ depth,
594
+ refs: lane.flowNodeRefs,
595
+ children: lane.childLaneSet ? laneTree(lane.childLaneSet, depth + 1, seen) : [],
596
+ };
597
+ });
530
598
  }
531
599
  /**
532
600
  * Dock boundary events on their host's edge — escalation on top, everything
@@ -41,7 +41,7 @@ export interface PreserveOptions {
41
41
  *
42
42
  * - `"remove"` (default) — take it out, because the update says so.
43
43
  * - `"keep"` — leave it. A serializer omits an attribute set to its schema
44
- * default, so `isExecutable="false"` disappears from a file that said it
44
+ * default, so `isSequential="false"` disappears from a file that said it
45
45
  * out loud. Keeping it is only safe when re-reading the result gives the
46
46
  * same model, which is a check the caller has to make; see
47
47
  * `exportPreserving` in the BPMN module.