@bpmnkit/core 0.0.22 → 0.0.24

package/dist/bpmn/auto-layout.js

@@ -1,9 +1,13 @@
 import { layoutProcess } from "../layout/layout-engine.js";
+import { resolveEdgeCrossings } from "../layout/routing.js";
 const POOL_HEADER = 30;
 const LANE_HEADER = 30;
 const PADDING = 20;
 const POOL_GAP = 30;
-function contentBbox(nodes) {
+const ANN_H = 50;
+const ANN_GAP = 60;
+const ANN_PADDING = 20;
+function contentBbox(nodes, extra) {
     let minX = Number.POSITIVE_INFINITY;
     let minY = Number.POSITIVE_INFINITY;
     let maxX = Number.NEGATIVE_INFINITY;
@@ -20,8 +24,107 @@ function contentBbox(nodes) {
             maxY = Math.max(maxY, n.labelBounds.y + n.labelBounds.height);
         }
     }
+    if (extra) {
+        for (const b of extra) {
+            minX = Math.min(minX, b.x);
+            minY = Math.min(minY, b.y);
+            maxX = Math.max(maxX, b.x + b.width);
+            maxY = Math.max(maxY, b.y + b.height);
+        }
+    }
     return { minX, minY, maxX, maxY };
 }
+/** Pre-compute annotation positions in layout space (before dx/dy shift). */
+function computeAnnotationLocalBounds(process, layoutNodes) {
+    const nodeById = new Map(layoutNodes.map((n) => [n.id, n]));
+    const placements = new Map();
+    // Occupied regions for overlap checks (node bounds + label bounds)
+    const occupied = [];
+    for (const n of layoutNodes) {
+        occupied.push({ ...n.bounds });
+        if (n.labelBounds)
+            occupied.push({ ...n.labelBounds });
+    }
+    // Static obstacles for crossing detection (nodes + labels only, not annotations)
+    const obstacles = [...occupied];
+    for (const ta of process.textAnnotations) {
+        const assoc = process.associations.find((a) => a.sourceRef === ta.id || a.targetRef === ta.id);
+        const connId = assoc
+            ? assoc.sourceRef === ta.id
+                ? assoc.targetRef
+                : assoc.sourceRef
+            : undefined;
+        const connNode = connId ? nodeById.get(connId) : undefined;
+        const annW = Math.min(200, Math.max(100, (ta.text?.length ?? 10) * 5));
+        if (!connNode) {
+            const candidate = { x: 0, y: 0, width: annW, height: ANN_H };
+            occupied.push({ ...candidate });
+            placements.set(ta.id, candidate);
+            continue;
+        }
+        const localX = connNode.bounds.x + connNode.bounds.width / 2 - annW / 2;
+        const anchorX = connNode.bounds.x + connNode.bounds.width / 2;
+        const pushStep = ANN_H + ANN_PADDING * 2 + 10;
+        // Try below: start below connected element, push down for overlaps
+        const belowY = connNode.bounds.y + connNode.bounds.height + ANN_GAP;
+        const below = { x: localX, y: belowY, width: annW, height: ANN_H };
+        for (let i = 0; i < 30 && hasOverlapPadded(below, occupied, ANN_PADDING); i++)
+            below.y += pushStep;
+        // Try above: gap scales with text length so longer annotations have more breathing room
+        const aboveGap = ANN_GAP + Math.round(annW * 0.2);
+        const aboveY = connNode.bounds.y - aboveGap - ANN_H;
+        const above = { x: localX, y: aboveY, width: annW, height: ANN_H };
+        for (let i = 0; i < 30 && hasOverlapPadded(above, occupied, ANN_PADDING); i++)
+            above.y -= pushStep;
+        // Count how many obstacles the association line would cross for each candidate
+        const belowCrossings = countLineCrossings(anchorX, connNode.bounds, below, obstacles);
+        const aboveCrossings = countLineCrossings(anchorX, connNode.bounds, above, obstacles);
+        const candidate = belowCrossings <= aboveCrossings ? below : above;
+        occupied.push({ ...candidate });
+        obstacles.push({ ...candidate });
+        placements.set(ta.id, candidate);
+    }
+    return placements;
+}
+/** Count how many obstacles the vertical association line from connNode to annotation crosses. */
+function countLineCrossings(lineX, connBounds, annBounds, obstacles) {
+    const annCY = annBounds.y + annBounds.height / 2;
+    const connCY = connBounds.y + connBounds.height / 2;
+    const top = Math.min(annCY, connCY);
+    const bottom = Math.max(annCY, connCY);
+    const tolerance = 20;
+    let crossings = 0;
+    for (const b of obstacles) {
+        // Skip the connected element itself
+        if (b.x === connBounds.x && b.y === connBounds.y && b.width === connBounds.width)
+            continue;
+        // Obstacle must overlap with the line's X corridor
+        if (b.x + b.width < lineX - tolerance || b.x > lineX + tolerance)
+            continue;
+        // Obstacle must be between connNode and annotation vertically
+        if (b.y + b.height <= top || b.y >= bottom)
+            continue;
+        crossings++;
+    }
+    return crossings;
+}
+function hasOverlap(a, others) {
+    for (const b of others) {
+        if (a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y)
+            return true;
+    }
+    return false;
+}
+function hasOverlapPadded(a, others, padding) {
+    for (const b of others) {
+        if (a.x - padding < b.x + b.width &&
+            a.x + a.width + padding > b.x &&
+            a.y - padding < b.y + b.height &&
+            a.y + a.height + padding > b.y)
+            return true;
+    }
+    return false;
+}
 function nodeToShape(node, dx, dy) {
     const shape = {
         id: `${node.id}_di`,
@@ -112,6 +215,70 @@ function buildLaneShapes(lanes, nodes, dx, dy, poolY, poolHeaderWidth, laneConte
         unknownAttributes: {},
     }));
 }
+function addAnnotationShapes(process, layoutNodes, annLocalBounds, allShapes, allEdges, dx, dy) {
+    if (process.textAnnotations.length === 0 && process.associations.length === 0)
+        return;
+    const nodeById = new Map(layoutNodes.map((n) => [n.id, n]));
+    for (const ta of process.textAnnotations) {
+        const b = annLocalBounds.get(ta.id);
+        if (!b)
+            continue;
+        allShapes.push({
+            id: `${ta.id}_di`,
+            bpmnElement: ta.id,
+            bounds: {
+                x: Math.round(b.x + dx),
+                y: Math.round(b.y + dy),
+                width: b.width,
+                height: b.height,
+            },
+            unknownAttributes: {},
+        });
+    }
+    for (const assoc of process.associations) {
+        const annId = annLocalBounds.has(assoc.sourceRef)
+            ? assoc.sourceRef
+            : annLocalBounds.has(assoc.targetRef)
+                ? assoc.targetRef
+                : undefined;
+        const elId = annId === assoc.sourceRef ? assoc.targetRef : assoc.sourceRef;
+        const annB = annId ? annLocalBounds.get(annId) : undefined;
+        const elNode = nodeById.get(elId);
+        if (!annB || !elNode)
+            continue;
+        const elB = elNode.bounds;
+        const annCx = Math.round(annB.x + annB.width / 2 + dx);
+        const elCx = Math.round(elB.x + elB.width / 2 + dx);
+        let waypoints;
+        if (annB.y >= elB.y + elB.height) {
+            // annotation below: element bottom-center → annotation top-center
+            waypoints = [
+                { x: elCx, y: Math.round(elB.y + elB.height + dy) },
+                { x: annCx, y: Math.round(annB.y + dy) },
+            ];
+        }
+        else if (annB.y + annB.height <= elB.y) {
+            // annotation above: element top-center → annotation bottom-center
+            waypoints = [
+                { x: elCx, y: Math.round(elB.y + dy) },
+                { x: annCx, y: Math.round(annB.y + annB.height + dy) },
+            ];
+        }
+        else {
+            // side-by-side: center-to-center
+            waypoints = [
+                { x: Math.round(elB.x + elB.width / 2 + dx), y: Math.round(elB.y + elB.height / 2 + dy) },
+                { x: annCx, y: Math.round(annB.y + annB.height / 2 + dy) },
+            ];
+        }
+        allEdges.push({
+            id: `${assoc.id}_di`,
+            bpmnElement: assoc.id,
+            waypoints,
+            unknownAttributes: {},
+        });
+    }
+}
 /**
  * Apply auto-layout to all processes in a BpmnDefinitions, replacing the
  * diagram interchange (BPMNDi) with freshly computed positions.
@@ -138,28 +305,39 @@ 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);
+        // Re-resolve edge crossings after boundary events moved shapes
+        const nodeMap = new Map(result.nodes.map((n) => [n.id, n]));
+        resolveEdgeCrossings(result.edges, nodeMap);
         if (result.nodes.length === 0)
             continue;
-        const { minX, minY, maxX, maxY } = contentBbox(result.nodes);
+        // Pre-compute annotation positions in layout space so they're included in the bbox
+        const annBounds = computeAnnotationLocalBounds(process, result.nodes);
+        const { minX, minY, maxX, maxY } = contentBbox(result.nodes, annBounds.values());
         const contentW = maxX - minX;
         const contentH = maxY - minY;
+        let dx;
+        let dy;
         if (participantId) {
-            // Elements sit inside pool content area:
-            // x starts at: POOL_HEADER + optional LANE_HEADER + PADDING
-            // y starts at: poolY + PADDING
             const elemX = POOL_HEADER + (hasLanes ? LANE_HEADER : 0) + PADDING;
             const elemY = poolY + PADDING;
-            const dx = elemX - minX;
-            const dy = elemY - minY;
-            for (const node of result.nodes)
-                allShapes.push(nodeToShape(node, dx, dy));
-            for (const edge of result.edges)
-                allEdges.push(edgeToShape(edge, dx, dy));
+            dx = elemX - minX;
+            dy = elemY - minY;
+        }
+        else {
+            dx = PADDING - minX;
+            dy = PADDING - minY;
+        }
+        for (const node of result.nodes)
+            allShapes.push(nodeToShape(node, dx, dy));
+        for (const edge of result.edges)
+            allEdges.push(edgeToShape(edge, dx, dy));
+        addAnnotationShapes(process, result.nodes, annBounds, allShapes, allEdges, dx, dy);
+        if (participantId) {
             const innerW = (hasLanes ? LANE_HEADER : 0) + contentW + 2 * PADDING;
             const innerH = contentH + 2 * PADDING;
             const poolW = POOL_HEADER + innerW;
-            // Pool (participant) shape
             allShapes.push({
                 id: `${participantId}_di`,
                 bpmnElement: participantId,
@@ -173,15 +351,6 @@ export function applyAutoLayout(defs) {
             }
             poolY += innerH + POOL_GAP;
         }
-        else {
-            // No collaboration — layout at (PADDING, PADDING)
-            const dx = PADDING - minX;
-            const dy = PADDING - minY;
-            for (const node of result.nodes)
-                allShapes.push(nodeToShape(node, dx, dy));
-            for (const edge of result.edges)
-                allEdges.push(edgeToShape(edge, dx, dy));
-        }
     }
     const planeBpmnElement = collab?.id ?? defs.processes[0]?.id ?? "plane";
     const existingDiagram = defs.diagrams[0];

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

@@ -1,4 +1,4 @@
-import type { BpmnDefinitions, BpmnFlowElement, BpmnSequenceFlow } from "./bpmn-model.js";
+import type { BpmnAssociation, BpmnDefinitions, BpmnFlowElement, BpmnSequenceFlow, BpmnTextAnnotation } from "./bpmn-model.js";
 import type { RestConnectorConfig } from "./rest-connector.js";
 /** Options shared by all element methods. */
 export interface ElementOptions {
@@ -69,6 +69,8 @@ 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;
 }
 /** Options for creating a call activity. */
 export interface CallActivityOptions {
@@ -117,6 +119,19 @@ export interface IntermediateThrowEventOptions extends ElementOptions {
     /** Escalation code — creates an escalation throw event (aspirational). */
     escalationCode?: string;
 }
+/** Options for an end event. */
+export interface EndEventOptions extends ElementOptions {
+    /** Error code — creates an error end event. */
+    errorCode?: string;
+    /** Error reference ID. */
+    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 {
     /** ID of the activity this boundary event is attached to. */
@@ -212,6 +227,11 @@ export declare class BranchBuilder {
     /** @internal – true once connectTo() has been called, meaning the branch end is already wired */
     _connected: boolean;
     /** @internal */
+    readonly _textAnnotations: BpmnTextAnnotation[];
+    /** @internal */
+    readonly _associations: BpmnAssociation[];
+    private readonly _annCounters;
+    /** @internal */
     constructor(gatewayId: string, branchName: string);
     /** Set a FEEL condition expression on this branch's outgoing sequence flow. */
     condition(expression: string): this;
@@ -225,6 +245,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;
@@ -233,7 +257,7 @@ export declare class BranchBuilder {
     businessRuleTask(id: string, options?: BusinessRuleTaskOptions): this;
     callActivity(id: string, options: CallActivityOptions): 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 +271,37 @@ 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;
+    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 +313,26 @@ export declare class ProcessBuilder {
     private readonly sequenceFlows;
     private readonly rootErrors;
     private readonly rootMessages;
+    private readonly _textAnnotations;
+    private readonly _associations;
+    private readonly _annCounters;
     private lastNodeId;
     private currentGatewayId;
     private openBranchEnds;
     private _autoLayout;
+    private _executionPlatformVersion;
+    private _serviceTaskDefaults;
     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 +349,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 +368,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()`. */
@@ -361,21 +434,36 @@ export declare class ProcessBuilder {
     subProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: SubProcessOptions): this;
     /** Add an event sub-process (aspirational). */
     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