@bpmnkit/core 0.0.23 → 0.0.24

package/dist/bpmn/index.d.ts

@@ -1,4 +1,4 @@
-import { ProcessBuilder } from "./bpmn-builder.js";
+import { DiagramBuilder, ProcessBuilder } from "./bpmn-builder.js";
 import type { BpmnDefinitions } from "./bpmn-model.js";
 /** A minimal 3-element BPMN diagram useful for first-launch or "New Diagram" defaults. */
 export declare const SAMPLE_BPMN_XML = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<bpmn:definitions xmlns:bpmn=\"http://www.omg.org/spec/BPMN/20100524/MODEL\"\n  xmlns:bpmndi=\"http://www.omg.org/spec/BPMN/20100524/DI\"\n  xmlns:dc=\"http://www.omg.org/spec/DD/20100524/DC\"\n  xmlns:di=\"http://www.omg.org/spec/DD/20100524/DI\"\n  id=\"Definitions_1\" targetNamespace=\"http://bpmn.io/schema/bpmn\">\n  <bpmn:process id=\"proc\" isExecutable=\"true\">\n    <bpmn:startEvent id=\"start\" name=\"Start\">\n      <bpmn:outgoing>flow1</bpmn:outgoing>\n    </bpmn:startEvent>\n    <bpmn:serviceTask id=\"task1\" name=\"Process Order\">\n      <bpmn:incoming>flow1</bpmn:incoming>\n      <bpmn:outgoing>flow2</bpmn:outgoing>\n    </bpmn:serviceTask>\n    <bpmn:endEvent id=\"end\" name=\"End\">\n      <bpmn:incoming>flow2</bpmn:incoming>\n    </bpmn:endEvent>\n    <bpmn:sequenceFlow id=\"flow1\" sourceRef=\"start\" targetRef=\"task1\"/>\n    <bpmn:sequenceFlow id=\"flow2\" sourceRef=\"task1\" targetRef=\"end\"/>\n  </bpmn:process>\n  <bpmndi:BPMNDiagram id=\"diagram1\">\n    <bpmndi:BPMNPlane id=\"plane1\" bpmnElement=\"proc\">\n      <bpmndi:BPMNShape id=\"start_di\" bpmnElement=\"start\">\n        <dc:Bounds x=\"152\" y=\"202\" width=\"36\" height=\"36\"/>\n      </bpmndi:BPMNShape>\n      <bpmndi:BPMNShape id=\"task1_di\" bpmnElement=\"task1\">\n        <dc:Bounds x=\"260\" y=\"180\" width=\"100\" height=\"80\"/>\n      </bpmndi:BPMNShape>\n      <bpmndi:BPMNShape id=\"end_di\" bpmnElement=\"end\">\n        <dc:Bounds x=\"432\" y=\"202\" width=\"36\" height=\"36\"/>\n      </bpmndi:BPMNShape>\n      <bpmndi:BPMNEdge id=\"flow1_di\" bpmnElement=\"flow1\">\n        <di:waypoint x=\"188\" y=\"220\"/>\n        <di:waypoint x=\"260\" y=\"220\"/>\n      </bpmndi:BPMNEdge>\n      <bpmndi:BPMNEdge id=\"flow2_di\" bpmnElement=\"flow2\">\n        <di:waypoint x=\"360\" y=\"220\"/>\n        <di:waypoint x=\"432\" y=\"220\"/>\n      </bpmndi:BPMNEdge>\n    </bpmndi:BPMNPlane>\n  </bpmndi:BPMNDiagram>\n</bpmn:definitions>";
@@ -41,6 +41,20 @@ export declare const Bpmn: {
      * ```
      */
     readonly createProcess: (processId: string) => ProcessBuilder;
+    /**
+     * Create a multi-process BPMN definitions document using the fluent builder API.
+     *
+     * @param id - Unique identifier for the definitions element (defaults to `"Definitions_1"`).
+     *
+     * @example
+     * ```typescript
+     * const defs = Bpmn.createDiagram("OrderSystem")
+     *   .process("caller", (p) => p.startEvent("s").callActivity("call", { processId: "callee" }).endEvent("e"))
+     *   .process("callee", (p) => p.startEvent("s2").serviceTask("work", { name: "Work", taskType: "work" }).endEvent("e2"))
+     *   .build()
+     * ```
+     */
+    readonly createDiagram: (id?: string) => DiagramBuilder;
     /**
      * Parse a BPMN 2.0 XML string into a typed {@link BpmnDefinitions} model.
      *

package/dist/bpmn/index.js

@@ -1,5 +1,5 @@
 import { applyAutoLayout } from "./auto-layout.js";
-import { ProcessBuilder } from "./bpmn-builder.js";
+import { DiagramBuilder, ProcessBuilder } from "./bpmn-builder.js";
 import { parseBpmn } from "./bpmn-parser.js";
 import { serializeBpmn } from "./bpmn-serializer.js";
 /** A minimal 3-element BPMN diagram useful for first-launch or "New Diagram" defaults. */
@@ -86,6 +86,22 @@ export const Bpmn = {
     createProcess(processId) {
         return new ProcessBuilder(processId);
     },
+    /**
+     * Create a multi-process BPMN definitions document using the fluent builder API.
+     *
+     * @param id - Unique identifier for the definitions element (defaults to `"Definitions_1"`).
+     *
+     * @example
+     * ```typescript
+     * const defs = Bpmn.createDiagram("OrderSystem")
+     *   .process("caller", (p) => p.startEvent("s").callActivity("call", { processId: "callee" }).endEvent("e"))
+     *   .process("callee", (p) => p.startEvent("s2").serviceTask("work", { name: "Work", taskType: "work" }).endEvent("e2"))
+     *   .build()
+     * ```
+     */
+    createDiagram(id = "Definitions_1") {
+        return new DiagramBuilder(id);
+    },
     /**
      * Parse a BPMN 2.0 XML string into a typed {@link BpmnDefinitions} model.
      *

package/dist/bpmn/zeebe-extensions.d.ts

@@ -64,6 +64,8 @@ export interface ZeebeExtensions {
     formDefinition?: ZeebeFormDefinition;
     /** DMN decision invoked by a business rule task (zeebe:calledDecision). */
     calledDecision?: ZeebeCalledDecision;
+    /** Marks this as a Camunda 8 native user task (zeebe:userTask). */
+    userTask?: true;
     /** Unrecognized extension elements preserved for roundtrip. */
     unknownElements?: XmlElement[];
 }

package/dist/bpmn/zeebe-extensions.js

@@ -71,6 +71,9 @@ export function zeebeExtensionsToXmlElements(extensions) {
             attrs.activeElementsCollection = activeElementsCollection;
         elements.push({ name: "zeebe:adHoc", attributes: attrs, children: [] });
     }
+    if (extensions.userTask) {
+        elements.push({ name: "zeebe:userTask", attributes: {}, children: [] });
+    }
     if (extensions.formDefinition) {
         elements.push({
             name: "zeebe:formDefinition",

package/dist/index.d.ts

@@ -4,7 +4,8 @@ export { isBpmnActivity, isBpmnAdHocSubProcess, isBpmnBoundaryEvent, isBpmnBusin
 export { findElement, findElementInProcess, findProcess, findSequenceFlow, getAllElements, getElementType, getZeebeExtensions, } from "./bpmn/utils.js";
 export { Bpmn, SAMPLE_BPMN_XML } from "./bpmn/index.js";
 export { applyAutoLayout } from "./bpmn/auto-layout.js";
-export type { ProcessBuilder, BranchBuilder, SubProcessContentBuilder, ServiceTaskOptions, ScriptTaskOptions, UserTaskOptions, CallActivityOptions, BusinessRuleTaskOptions, ElementOptions, GatewayOptions, MultiInstanceOptions, SubProcessOptions, StartEventOptions, IntermediateCatchEventOptions, IntermediateThrowEventOptions, BoundaryEventOptions, AdHocSubProcessOptions, } from "./bpmn/bpmn-builder.js";
+export { DiagramBuilder } from "./bpmn/bpmn-builder.js";
+export type { ProcessBuilder, BranchBuilder, SubProcessContentBuilder, ServiceTaskOptions, ScriptTaskOptions, UserTaskOptions, CallActivityOptions, BusinessRuleTaskOptions, ElementOptions, GatewayOptions, MultiInstanceOptions, SubProcessOptions, StartEventOptions, IntermediateCatchEventOptions, IntermediateThrowEventOptions, EndEventOptions, BoundaryEventOptions, AdHocSubProcessOptions, } from "./bpmn/bpmn-builder.js";
 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, 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";
 export type { RestConnectorConfig, RestAuthentication, HttpMethod, } from "./bpmn/rest-connector.js";
 export type { ZeebeExtensions, ZeebeTaskDefinition, ZeebeIoMapping, ZeebeIoMappingEntry, ZeebeTaskHeaders, ZeebeTaskHeaderEntry, ZeebeProperties, ZeebePropertyEntry, ZeebeFormDefinition, ZeebeCalledDecision, } from "./bpmn/zeebe-extensions.js";

package/dist/index.js

@@ -3,6 +3,7 @@ export { isBpmnActivity, isBpmnAdHocSubProcess, isBpmnBoundaryEvent, isBpmnBusin
 export { findElement, findElementInProcess, findProcess, findSequenceFlow, getAllElements, getElementType, getZeebeExtensions, } from "./bpmn/utils.js";
 export { Bpmn, SAMPLE_BPMN_XML } from "./bpmn/index.js";
 export { applyAutoLayout } from "./bpmn/auto-layout.js";
+export { DiagramBuilder } from "./bpmn/bpmn-builder.js";
 export { zeebeExtensionsToXmlElements } from "./bpmn/zeebe-extensions.js";
 export { Dmn, layoutDmn, benchmarkDmnLayout, compactifyDmn, expandDmn } from "./dmn/index.js";
 export { Form, compactifyForm, expandForm } from "./form/index.js";

package/dist/layout/layout-engine.d.ts

@@ -10,7 +10,8 @@ import type { LayoutResult } from "./types.js";
  * 4. Coordinate assignment — Fixed element sizes with spacing
  * 5. Sub-process layout — Recursive nested passes
  * 6. Edge routing — Orthogonal waypoints
- * 7. Overlap assertion — Post-condition validation
+ * 7. Boundary event repositioning — place events on host border
+ * 8. Overlap assertion — Post-condition validation
  */
 export declare function layoutProcess(process: BpmnProcess): LayoutResult;
 /**

package/dist/layout/layout-engine.js

@@ -7,6 +7,133 @@ import { assignLayers, groupByLayer } from "./layers.js";
 import { assertNoOverlap } from "./overlap.js";
 import { routeEdges } from "./routing.js";
 import { layoutSubProcesses } from "./subprocess.js";
+const CHAIN_GAP = 30;
+const CHAIN_V_GAP = 20;
+/**
+ * Reposition boundary events to the bottom edge of their host task, then walk
+ * each boundary event's exclusive downstream chain and place those nodes
+ * horizontally to the right of the host task. Re-routes all affected edges.
+ */
+function repositionBoundaryEvents(flowElements, result) {
+    const boundaryMap = new Map();
+    for (const el of flowElements) {
+        if (el.type !== "boundaryEvent")
+            continue;
+        const list = boundaryMap.get(el.attachedToRef) ?? [];
+        list.push(el.id);
+        boundaryMap.set(el.attachedToRef, list);
+    }
+    if (boundaryMap.size === 0)
+        return;
+    const nodeById = new Map(result.nodes.map((n) => [n.id, n]));
+    const succIds = new Map();
+    const predIds = new Map();
+    for (const edge of result.edges) {
+        const se = succIds.get(edge.sourceRef) ?? [];
+        se.push(edge.targetRef);
+        succIds.set(edge.sourceRef, se);
+        const ps = predIds.get(edge.targetRef) ?? new Set();
+        ps.add(edge.sourceRef);
+        predIds.set(edge.targetRef, ps);
+    }
+    for (const [hostId, beIds] of boundaryMap) {
+        const hostNode = nodeById.get(hostId);
+        if (!hostNode)
+            continue;
+        for (let i = 0; i < beIds.length; i++) {
+            const beId = beIds[i];
+            if (!beId)
+                continue;
+            const beNode = nodeById.get(beId);
+            if (!beNode)
+                continue;
+            const bW = beNode.bounds.width;
+            const bH = beNode.bounds.height;
+            // Place boundary event on the bottom edge of the host task, stacking leftward
+            const rightEdge = hostNode.bounds.x + hostNode.bounds.width;
+            beNode.bounds.x = Math.round(rightEdge - bW / 2 - i * (bW + 4));
+            beNode.bounds.y = Math.round(hostNode.bounds.y + hostNode.bounds.height - bH / 2);
+            if (beNode.labelBounds) {
+                beNode.labelBounds.x = beNode.bounds.x + Math.round(bW / 2 - beNode.labelBounds.width / 2);
+                beNode.labelBounds.y = beNode.bounds.y + bH + 4;
+            }
+            // Collect nodes exclusively reachable from this boundary event (BFS)
+            const chainSet = new Set([beId]);
+            const chainOrder = [];
+            const queue = [...(succIds.get(beId) ?? [])];
+            while (queue.length > 0) {
+                const id = queue.shift();
+                if (!id || chainSet.has(id))
+                    continue;
+                const preds = predIds.get(id) ?? new Set();
+                if ([...preds].every((p) => chainSet.has(p))) {
+                    chainSet.add(id);
+                    chainOrder.push(id);
+                    queue.push(...(succIds.get(id) ?? []));
+                }
+            }
+            // Each boundary event's chain gets its own vertical lane
+            let maxChainH = 0;
+            for (const id of chainOrder) {
+                const n = nodeById.get(id);
+                if (n)
+                    maxChainH = Math.max(maxChainH, n.bounds.height);
+            }
+            const laneOffset = i * (maxChainH + CHAIN_V_GAP + 10);
+            const chainCenterY = Math.round(beNode.bounds.y + bH + CHAIN_V_GAP + maxChainH / 2 + laneOffset);
+            const chainStartX = Math.max(Math.round(beNode.bounds.x + bW / 2) + CHAIN_GAP, hostNode.bounds.x + hostNode.bounds.width + CHAIN_GAP);
+            let curX = chainStartX;
+            for (const id of chainOrder) {
+                const n = nodeById.get(id);
+                if (!n)
+                    continue;
+                n.bounds.x = curX;
+                n.bounds.y = chainCenterY - Math.round(n.bounds.height / 2);
+                if (n.labelBounds) {
+                    // Center label on node, but clamp so it never extends left of the node —
+                    // wide event labels would otherwise overlap the preceding chain element.
+                    const labelX = n.bounds.x + Math.round(n.bounds.width / 2 - n.labelBounds.width / 2);
+                    n.labelBounds.x = Math.max(labelX, n.bounds.x);
+                    n.labelBounds.y = n.bounds.y + n.bounds.height + 4;
+                }
+                // Advance past the node AND its label so the next element doesn't overlap.
+                const nodeRight = n.bounds.x + n.bounds.width;
+                const labelRight = n.labelBounds ? n.labelBounds.x + n.labelBounds.width : 0;
+                curX = Math.max(nodeRight, labelRight) + CHAIN_GAP;
+            }
+            // Re-route edges touching the boundary event or its chain
+            for (const edge of result.edges) {
+                if (!chainSet.has(edge.sourceRef))
+                    continue;
+                const src = nodeById.get(edge.sourceRef);
+                const tgt = nodeById.get(edge.targetRef);
+                if (!src || !tgt)
+                    continue;
+                if (edge.sourceRef === beId) {
+                    const srcX = Math.round(src.bounds.x + bW / 2);
+                    const srcY = Math.round(src.bounds.y + bH);
+                    const tgtX = Math.round(tgt.bounds.x);
+                    const tgtY = Math.round(tgt.bounds.y + tgt.bounds.height / 2);
+                    edge.waypoints = [
+                        { x: srcX, y: srcY },
+                        { x: srcX, y: tgtY },
+                        { x: tgtX, y: tgtY },
+                    ];
+                }
+                else {
+                    const srcX = Math.round(src.bounds.x + src.bounds.width);
+                    const srcY = Math.round(src.bounds.y + src.bounds.height / 2);
+                    const tgtX = Math.round(tgt.bounds.x);
+                    const tgtY = Math.round(tgt.bounds.y + tgt.bounds.height / 2);
+                    edge.waypoints = [
+                        { x: srcX, y: srcY },
+                        { x: tgtX, y: tgtY },
+                    ];
+                }
+            }
+        }
+    }
+}
 /**
  * Auto-layout a BPMN process using the Sugiyama/layered algorithm.
  *
@@ -17,10 +144,12 @@ import { layoutSubProcesses } from "./subprocess.js";
  * 4. Coordinate assignment — Fixed element sizes with spacing
  * 5. Sub-process layout — Recursive nested passes
  * 6. Edge routing — Orthogonal waypoints
- * 7. Overlap assertion — Post-condition validation
+ * 7. Boundary event repositioning — place events on host border
+ * 8. Overlap assertion — Post-condition validation
  */
 export function layoutProcess(process) {
     const result = layoutFlowNodes(process.flowElements, process.sequenceFlows);
+    repositionBoundaryEvents(process.flowElements, result);
     assertNoOverlap(result);
     return result;
 }

package/dist/layout/overlap.js

@@ -8,6 +8,9 @@
 export function assertNoOverlap(result) {
     const allBounds = [];
     for (const node of result.nodes) {
+        // Boundary events intentionally overlap their host activity — skip them.
+        if (node.type === "boundaryEvent")
+            continue;
         allBounds.push({ id: node.id, kind: "element", bounds: node.bounds });
         if (node.labelBounds) {
             allBounds.push({ id: `${node.id}-label`, kind: "label", bounds: node.labelBounds });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmnkit/core",
-  "version": "0.0.23",
+  "version": "0.0.24",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -17,7 +17,7 @@
     "dist/**/*.d.ts"
   ],
   "dependencies": {
-    "@bpmnkit/feel": "0.0.18"
+    "@bpmnkit/feel": "0.0.19"
   },
   "description": "TypeScript-first BPMN 2.0 SDK — parse, build, layout, and optimize diagrams",
   "keywords": [