@bpmnkit/core 0.0.23 → 0.0.25

package/dist/bpmn/auto-layout.js

@@ -4,136 +4,9 @@ const POOL_HEADER = 30;
 const LANE_HEADER = 30;
 const PADDING = 20;
 const POOL_GAP = 30;
-const CHAIN_GAP = 30;
-const CHAIN_V_GAP = 20;
 const ANN_H = 50;
 const ANN_GAP = 60;
 const ANN_PADDING = 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) {
-    // Collect boundary events grouped by host task id
-    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]));
-    // Build successor / predecessor maps from edges for chain walking
-    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 at bottom-right of 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 (in BFS order)
-            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;
-                // Include only if every predecessor is already in the chain
-                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) ?? []));
-                }
-            }
-            // Find tallest chain element to compute center Y below boundary event.
-            // Each boundary event's chain gets its own vertical lane to avoid overlaps.
-            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) {
-                    n.labelBounds.x = n.bounds.x + Math.round(n.bounds.width / 2 - n.labelBounds.width / 2);
-                    n.labelBounds.y = n.bounds.y + n.bounds.height + 4;
-                }
-                curX += n.bounds.width + CHAIN_GAP;
-            }
-            // Re-route all 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) {
-                    // Boundary event → first chain node: route down then right
-                    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 {
-                    // Within chain: straight horizontal edge
-                    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 },
-                    ];
-                }
-            }
-        }
-    }
-}
 function contentBbox(nodes, extra) {
     let minX = Number.POSITIVE_INFINITY;
     let minY = Number.POSITIVE_INFINITY;
@@ -432,11 +305,8 @@ export function applyAutoLayout(defs) {
         const participantId = processToParticipant.get(process.id);
         const lanes = process.laneSet?.lanes ?? [];
         const hasLanes = lanes.length > 0;
+        // layoutProcess now handles boundary event repositioning internally.
         const result = layoutProcess(process);
-        // Post-process boundary events: reposition each boundary event to the bottom
-        // of its host task, then walk its exclusive downstream chain and reposition
-        // those nodes horizontally to the right of the host task.
-        repositionBoundaryEvents(process.flowElements, result);
         // Re-resolve edge crossings after boundary events moved shapes
         const nodeMap = new Map(result.nodes.map((n) => [n.id, n]));
         resolveEdgeCrossings(result.edges, nodeMap);

package/dist/bpmn/bpmn-builder.d.ts

@@ -1,8 +1,9 @@
-import type { BpmnDefinitions, BpmnFlowElement, BpmnSequenceFlow } from "./bpmn-model.js";
+import type { BpmnAssociation, BpmnDefinitions, BpmnError, BpmnEscalation, BpmnFlowElement, BpmnMessage, BpmnSequenceFlow, BpmnSignal, BpmnTextAnnotation } from "./bpmn-model.js";
 import type { RestConnectorConfig } from "./rest-connector.js";
 /** Options shared by all element methods. */
 export interface ElementOptions {
     name?: string;
+    isForCompensation?: boolean;
 }
 /** Options for creating a start event. */
 export interface StartEventOptions extends ElementOptions {
@@ -25,6 +26,11 @@ export interface StartEventOptions extends ElementOptions {
     modelerTemplateVersion?: string;
     /** Zeebe modeler template icon (data URI). */
     modelerTemplateIcon?: string;
+    /**
+     * Non-interrupting flag — only meaningful for start events inside event sub-processes.
+     * Pass `false` to emit `isInterrupting="false"`. Omit for the default interrupting behavior.
+     */
+    isInterrupting?: boolean;
 }
 /** Options for creating a service task. */
 export interface ServiceTaskOptions {
@@ -53,6 +59,8 @@ export interface ServiceTaskOptions {
     modelerTemplateVersion?: string;
     /** Zeebe modeler template icon (data URI). */
     modelerTemplateIcon?: string;
+    /** Mark this task as a compensation handler. */
+    isForCompensation?: boolean;
 }
 /** Options for creating a script task. */
 export interface ScriptTaskOptions {
@@ -62,6 +70,8 @@ export interface ScriptTaskOptions {
     expression: string;
     /** Variable name to store the result. */
     resultVariable: string;
+    /** Mark this task as a compensation handler. */
+    isForCompensation?: boolean;
 }
 /** Options for creating a user task. */
 export interface UserTaskOptions {
@@ -69,6 +79,10 @@ export interface UserTaskOptions {
     name?: string;
     /** Form key or form reference. */
     formId?: string;
+    /** Emit <zeebe:userTask /> to mark as a Camunda 8 native user task. */
+    zeebeUserTask?: boolean;
+    /** Mark this task as a compensation handler. */
+    isForCompensation?: boolean;
 }
 /** Options for creating a call activity. */
 export interface CallActivityOptions {
@@ -78,6 +92,8 @@ export interface CallActivityOptions {
     processId: string;
     /** Whether to propagate all child variables. */
     propagateAllChildVariables?: boolean;
+    /** Mark this activity as a compensation handler. */
+    isForCompensation?: boolean;
 }
 /** Options for creating a business rule task. */
 export interface BusinessRuleTaskOptions {
@@ -89,6 +105,8 @@ export interface BusinessRuleTaskOptions {
     decisionId?: string;
     /** Variable to store the result. */
     resultVariable?: string;
+    /** Mark this task as a compensation handler. */
+    isForCompensation?: boolean;
 }
 /** Options for gateway elements. */
 export interface GatewayOptions extends ElementOptions {
@@ -116,6 +134,23 @@ export interface IntermediateThrowEventOptions extends ElementOptions {
     signalName?: string;
     /** Escalation code — creates an escalation throw event (aspirational). */
     escalationCode?: string;
+    /** Emit a compensateEventDefinition. */
+    compensation?: boolean;
+    /** Activity to compensate (activityRef attribute on compensateEventDefinition). */
+    activityRef?: string;
+}
+/** Options for an end event. */
+export interface EndEventOptions extends ElementOptions {
+    /** Error code — creates an error end event. */
+    errorCode?: string;
+    /** Error code — creates an error end event. Alias for errorCode. */
+    errorRef?: string;
+    /** Message name — creates a message end event. */
+    messageName?: string;
+    /** Signal name — creates a signal end event. */
+    signalName?: string;
+    /** Escalation code — creates an escalation end event. */
+    escalationCode?: string;
 }
 /** Options for a boundary event. */
 export interface BoundaryEventOptions extends ElementOptions {
@@ -125,7 +160,7 @@ export interface BoundaryEventOptions extends ElementOptions {
     cancelActivity?: boolean;
     /** Error code — creates an error boundary event. */
     errorCode?: string;
-    /** Error reference ID. */
+    /** Error code — creates an error boundary event. Alias for errorCode. */
     errorRef?: string;
     /** Timer duration — creates a timer boundary event (aspirational). */
     timerDuration?: string;
@@ -137,6 +172,8 @@ export interface BoundaryEventOptions extends ElementOptions {
     messageName?: string;
     /** Signal name — creates a signal boundary event (aspirational). */
     signalName?: string;
+    /** Creates a compensation boundary event. */
+    compensation?: boolean;
 }
 /** Multi-instance loop configuration. */
 export interface MultiInstanceOptions {
@@ -212,7 +249,16 @@ export declare class BranchBuilder {
     /** @internal – true once connectTo() has been called, meaning the branch end is already wired */
     _connected: boolean;
     /** @internal */
-    constructor(gatewayId: string, branchName: string);
+    readonly _textAnnotations: BpmnTextAnnotation[];
+    /** @internal */
+    readonly _associations: BpmnAssociation[];
+    private readonly _annCounters;
+    private readonly rootErrors;
+    private readonly rootMessages;
+    private readonly rootSignals;
+    private readonly rootEscalations;
+    /** @internal */
+    constructor(gatewayId: string, branchName: string, rootErrors?: BpmnError[], rootMessages?: BpmnMessage[], rootSignals?: BpmnSignal[], rootEscalations?: BpmnEscalation[]);
     /** Set a FEEL condition expression on this branch's outgoing sequence flow. */
     condition(expression: string): this;
     /** Mark this branch as the gateway's default (no-condition) flow. */
@@ -225,6 +271,10 @@ export declare class BranchBuilder {
     connectTo(targetId: string): this;
     /** @internal – ID of the last element added (or the gateway if branch is empty) */
     get _lastNodeId(): string;
+    /** Attach a text annotation to the element at the current cursor position. */
+    textAnnotation(text: string): this;
+    /** Attach a text annotation to an element by explicit ID. */
+    annotate(elementId: string, text: string): this;
     serviceTask(id: string, options: ServiceTaskOptions): this;
     userTask(id: string, options?: UserTaskOptions): this;
     scriptTask(id: string, options: ScriptTaskOptions): this;
@@ -232,8 +282,10 @@ export declare class BranchBuilder {
     receiveTask(id: string, options?: ElementOptions): this;
     businessRuleTask(id: string, options?: BusinessRuleTaskOptions): this;
     callActivity(id: string, options: CallActivityOptions): this;
+    /** Add an abstract task with no Zeebe extensions. */
+    task(id: string, options?: ElementOptions): this;
     startEvent(id?: string, options?: StartEventOptions): this;
-    endEvent(id?: string, options?: ElementOptions): this;
+    endEvent(id?: string, options?: EndEventOptions): this;
     intermediateThrowEvent(id?: string, options?: IntermediateThrowEventOptions): this;
     intermediateCatchEvent(id?: string, options?: IntermediateCatchEventOptions): this;
     exclusiveGateway(id: string, options?: GatewayOptions): this;
@@ -247,16 +299,39 @@ export declare class SubProcessContentBuilder {
     readonly _elements: BpmnFlowElement[];
     /** @internal */
     readonly _flows: BpmnSequenceFlow[];
+    /** @internal */
+    readonly _textAnnotations: BpmnTextAnnotation[];
+    /** @internal */
+    readonly _associations: BpmnAssociation[];
+    private readonly _annCounters;
     private lastNodeId;
+    private currentGatewayId;
+    private openBranchEnds;
     private addElement;
     startEvent(id?: string, options?: StartEventOptions): this;
-    endEvent(id?: string, options?: ElementOptions): this;
+    endEvent(id?: string, options?: EndEventOptions): this;
+    intermediateThrowEvent(id?: string, options?: IntermediateThrowEventOptions): this;
+    intermediateCatchEvent(id?: string, options?: IntermediateCatchEventOptions): this;
     serviceTask(id: string, options: ServiceTaskOptions): this;
-    userTask(id: string, options?: UserTaskOptions): this;
     scriptTask(id: string, options: ScriptTaskOptions): this;
+    userTask(id: string, options?: UserTaskOptions): this;
+    businessRuleTask(id: string, options?: BusinessRuleTaskOptions): this;
     callActivity(id: string, options: CallActivityOptions): this;
-    intermediateThrowEvent(id?: string, options?: IntermediateThrowEventOptions): this;
-    intermediateCatchEvent(id?: string, options?: IntermediateCatchEventOptions): this;
+    sendTask(id: string, options?: ElementOptions): this;
+    receiveTask(id: string, options?: ElementOptions): this;
+    /** Add an abstract task with no Zeebe extensions. */
+    task(id: string, options?: ElementOptions): this;
+    exclusiveGateway(id: string, options?: GatewayOptions): this;
+    parallelGateway(id: string, options?: ElementOptions): this;
+    inclusiveGateway(id: string, options?: GatewayOptions): this;
+    eventBasedGateway(id: string, options?: ElementOptions): this;
+    /** Attach a text annotation to the element at the current cursor position. */
+    textAnnotation(text: string): this;
+    /** Attach a text annotation to an element by explicit ID. */
+    annotate(elementId: string, text: string): this;
+    branch(name: string, callback: (b: BranchBuilder) => void): this;
+    connectTo(targetId: string): this;
+    element(elementId: string): this;
 }
 /** Fluent builder for constructing BPMN processes. */
 export declare class ProcessBuilder {
@@ -268,13 +343,29 @@ export declare class ProcessBuilder {
     private readonly sequenceFlows;
     private readonly rootErrors;
     private readonly rootMessages;
+    private readonly rootSignals;
+    private readonly rootEscalations;
+    private readonly _textAnnotations;
+    private readonly _associations;
+    private readonly _annCounters;
     private lastNodeId;
     private currentGatewayId;
     private openBranchEnds;
     private _autoLayout;
+    private _executionPlatformVersion;
+    private _serviceTaskDefaults;
+    private _savedMainFlowId;
     constructor(processId: string);
     /** Enable auto-layout: `build()` will run the layout engine and populate diagram interchange data. */
     withAutoLayout(): this;
+    /** Set the Camunda execution platform version stamped into the BPMN definitions. Defaults to `"8.9.0"`. */
+    executionPlatformVersion(version: string): this;
+    /** Set process-wide defaults applied to subsequently added elements. */
+    defaults(options: {
+        serviceTask?: {
+            retries?: string;
+        };
+    }): this;
     /** Set the display name for this process. */
     name(name: string): this;
     /** Set whether this process is executable. */
@@ -291,8 +382,14 @@ export declare class ProcessBuilder {
      * is completely disconnected.
      */
     addStartEvent(id?: string, options?: StartEventOptions): this;
+    /**
+     * Alias for `addStartEvent()` — begins a new disconnected parallel path.
+     *
+     * Use this for readability when modeling processes with multiple independent paths.
+     */
+    disconnectedStartEvent(id?: string, options?: StartEventOptions): this;
     /** Add an end event. */
-    endEvent(id?: string, options?: ElementOptions): this;
+    endEvent(id?: string, options?: EndEventOptions): this;
     /** Add an intermediate throw event (none, message, signal, escalation). */
     intermediateThrowEvent(id?: string, options?: IntermediateThrowEventOptions): this;
     /** Add an intermediate catch event (timer, message, signal). */
@@ -304,6 +401,15 @@ export declare class ProcessBuilder {
      * They start a new outgoing chain from the boundary event itself.
      */
     boundaryEvent(id: string, options: BoundaryEventOptions): this;
+    /**
+     * Attach a boundary event to the preceding task and build its outgoing path,
+     * then restore the builder cursor to the preceding task so the main flow continues.
+     *
+     * @param id - ID for the boundary event element.
+     * @param options - Boundary event options (without `attachedTo` — inferred from cursor).
+     * @param handler - Callback that chains elements from the boundary event.
+     */
+    withBoundary(id: string, options: Omit<BoundaryEventOptions, "attachedTo">, handler: (b: ProcessBuilder) => void): this;
     /** Add a service task with Zeebe task definition and optional IO mappings. */
     serviceTask(id: string, options: ServiceTaskOptions): this;
     /** Add a REST connector task — syntactic sugar over `serviceTask()`. */
@@ -320,6 +426,8 @@ export declare class ProcessBuilder {
     businessRuleTask(id: string, options?: BusinessRuleTaskOptions): this;
     /** Add a call activity referencing another process. */
     callActivity(id: string, options: CallActivityOptions): this;
+    /** Add an abstract task with no Zeebe extensions. */
+    task(id: string, options?: ElementOptions): this;
     /** Add an exclusive gateway (XOR split/join). */
     exclusiveGateway(id: string, options?: GatewayOptions): this;
     /** Add a parallel gateway (AND split/join). */
@@ -359,23 +467,38 @@ export declare class ProcessBuilder {
     adHocSubProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: AdHocSubProcessOptions): this;
     /** Add a sub-process (aspirational). */
     subProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: SubProcessOptions): this;
-    /** Add an event sub-process (aspirational). */
+    /** Add an event sub-process. Triggered by its start event — no incoming or outgoing sequence flows. */
     eventSubProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: ElementOptions): this;
+    /** Attach a text annotation to the element at the current cursor position. */
+    textAnnotation(text: string): this;
+    /** Attach a text annotation to any flow element by explicit ID. */
+    annotate(elementId: string, text: string): this;
     /**
      * Build the complete BPMN definitions model.
      *
      * Resolves all forward-referenced `incoming` / `outgoing` arrays and wraps
      * the process in a {@link BpmnDefinitions} ready for XML serialization.
      */
-    build(): BpmnDefinitions;
-    private buildDiagram;
-    /**
-     * Insert matching join gateways where split-gateway branches converge
-     * on a non-gateway target. BPMN best practice: every split has a join.
-     */
-    private insertJoinGateways;
-    /** Trace backward from a node to find which split gateway it belongs to. */
-    private traceBackToSplit;
+    build(options?: {
+        strict?: boolean;
+    }): BpmnDefinitions;
+    private validate;
     private addFlowElement;
 }
+/**
+ * Builder for a complete BPMN definitions document containing one or more processes.
+ * Use `Bpmn.createDiagram(id?)` to obtain an instance.
+ */
+export declare class DiagramBuilder {
+    private readonly _id;
+    private readonly _processes;
+    private readonly _errors;
+    private readonly _messages;
+    private _executionPlatformVersion;
+    constructor(id: string);
+    /** Set the Camunda execution platform version stamped into the BPMN definitions. Defaults to `"8.9.0"`. */
+    executionPlatformVersion(version: string): this;
+    process(id: string, callback: (b: ProcessBuilder) => void): this;
+    build(): BpmnDefinitions;
+}
 //# sourceMappingURL=bpmn-builder.d.ts.map