bpmn-auto-layout-extended 1.0.2 → 1.0.5

package/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/krasucki/bpmn-auto-layout-extended/actions/workflows/CI.yml/badge.svg)](https://github.com/krasucki/bpmn-auto-layout-extended/actions/workflows/CI.yml)
 
-Extended fork of [bpmn-auto-layout](https://github.com/bpmn-io/bpmn-auto-layout) with support for collaborations, message flows, text annotations, groups, and sub-process expansion.
+Extended fork of [bpmn-auto-layout](https://github.com/bpmn-io/bpmn-auto-layout) with support for collaborations, message flows, text annotations, groups, lanes, and sub-process expansion.
 
 Create and layout the graphical representation of a BPMN diagram.
 
@@ -11,7 +11,7 @@ Create and layout the graphical representation of a BPMN diagram.
 This library works with [Node.js](https://nodejs.org/) and in the browser.
 
 ```javascript
-import { layoutProcess } from 'bpmn-auto-layout';
+import { layoutProcess } from 'bpmn-auto-layout-extended';
 
 import diagramXML from './diagram.bpmn';
 
@@ -36,6 +36,7 @@ await layoutProcess(diagramXML, options);
 * **Message flows** — message flows between participants are routed as orthogonal edges.
 * **Text annotations and associations** — process-level and collaboration-level annotations are positioned above their associated element.
 * **Groups** — group shapes are emitted around their member elements.
+* **Lanes (swimlanes)** — when a process defines a `laneSet`, elements are reorganized into lane-specific row bands and `BPMNShape` DI entries are emitted for each lane. Works both inside collaborations and for standalone processes (a collaboration+participant wrapper is synthesized automatically). Elements not explicitly assigned to a lane are inferred from their connections.
 * **Original participant gap preserved** — the gap between pool lanes from the input is carried over (capped at 100 px); annotations are accommodated by expanding the pool height.
 * **Sub-process expand support** — collapsed sub-processes retain their inner layout so they can be expanded; use `expandSubProcesses: true` to expand them inline during layout.
 

package/dist/index.cjs

@@ -947,6 +947,7 @@ var incomingHandler = {
 const handlers = [ elementHandler, incomingHandler, outgoingHandler, attacherHandler ];
 
 const PARTICIPANT_LABEL_WIDTH = 30;
+const LANE_LABEL_WIDTH = 30;
 
 class Layouter {
   constructor() {
@@ -979,19 +980,43 @@ class Layouter {
       const firstRootProcess = this.getProcess();
 
       if (firstRootProcess) {
-        this.setExpandedPropertyToModdleElements(moddleObj, options);
-        this.setExecutedProcesses(firstRootProcess);
-        this.createGridsForProcesses();
-        this.cleanDi();
-        this.createRootDi(firstRootProcess);
-        this.drawProcesses();
-
-        // Draw artifacts and data associations for each laid out process
-        for (const process of this.layoutedProcesses) {
-          const diagram = this.diagram.diagrams.find(d => d.plane.bpmnElement === process)
-            || this.diagram.diagrams[0];
-          this.generateArtifactsDi(process, diagram);
-          this.generateDataAssociationsDi(process, diagram);
+        const hasLanes = firstRootProcess.laneSets?.[0]?.lanes?.length > 0;
+
+        if (hasLanes) {
+
+          // Standalone process with lanes — synthesize a collaboration wrapper
+          // so layoutCollaboration() handles lane grid reorganization and DI.
+          const participant = this.moddle.create('bpmn:Participant', {
+            id: 'Participant_' + firstRootProcess.id,
+            name: firstRootProcess.name || firstRootProcess.id,
+            processRef: firstRootProcess
+          });
+          const collaboration = this.moddle.create('bpmn:Collaboration', {
+            id: 'Collaboration_' + firstRootProcess.id,
+            participants: [ participant ]
+          });
+          participant.$parent = collaboration;
+          collaboration.$parent = this.diagram;
+          this.diagram.get('rootElements').push(collaboration);
+
+          this.setExpandedPropertyToModdleElements(moddleObj, options);
+          this.cleanDi();
+          this.layoutCollaboration(collaboration, options);
+        } else {
+          this.setExpandedPropertyToModdleElements(moddleObj, options);
+          this.setExecutedProcesses(firstRootProcess);
+          this.createGridsForProcesses();
+          this.cleanDi();
+          this.createRootDi(firstRootProcess);
+          this.drawProcesses();
+
+          // Draw artifacts and data associations for each laid out process
+          for (const process of this.layoutedProcesses) {
+            const diagram = this.diagram.diagrams.find(d => d.plane.bpmnElement === process)
+              || this.diagram.diagrams[0];
+            this.generateArtifactsDi(process, diagram);
+            this.generateDataAssociationsDi(process, diagram);
+          }
         }
       }
     }
@@ -1005,17 +1030,26 @@ class Layouter {
     // Build grids per participant's process
     const participantLayouts = collaboration.participants.map(participant => {
       const process = participant.processRef;
-      if (!process) return { participant, process: null, layoutedProcesses: [], grid: null };
+      if (!process) return { participant, process: null, layoutedProcesses: [], grid: null, laneInfo: null };
 
       this.layoutedProcesses = [];
       this.setExecutedProcesses(process);
       this.createGridsForProcesses();
 
+      // Detect lanes and reorganize grid so each lane occupies distinct row bands
+      let laneInfo = null;
+      const laneMapping = this.getLaneMapping(process);
+      if (laneMapping && process.grid) {
+        const laneRowRanges = this.reorganizeGridByLanes(process.grid, laneMapping);
+        laneInfo = { lanes: laneMapping.lanes, laneRowRanges };
+      }
+
       return {
         participant,
         process,
         layoutedProcesses: [ ...this.layoutedProcesses ],
-        grid: process.grid
+        grid: process.grid,
+        laneInfo
       };
     });
 
@@ -1025,17 +1059,18 @@ class Layouter {
     const participantFloors = new Map();
     let currentY = 0;
 
-    for (const { participant, process, layoutedProcesses, grid } of participantLayouts) {
+    for (const { participant, process, layoutedProcesses, grid, laneInfo } of participantLayouts) {
       if (process) participantFloors.set(process, currentY);
 
       let participantWidth, participantHeight;
+      const hasLanes = !!laneInfo;
 
       if (!grid) {
         participantWidth = 400;
         participantHeight = DEFAULT_CELL_HEIGHT;
       } else {
         const [ rows, cols ] = grid.getGridDimensions();
-        participantWidth = PARTICIPANT_LABEL_WIDTH + Math.max(cols, 1) * DEFAULT_CELL_WIDTH;
+        participantWidth = PARTICIPANT_LABEL_WIDTH + (hasLanes ? LANE_LABEL_WIDTH : 0) + Math.max(cols, 1) * DEFAULT_CELL_WIDTH;
         participantHeight = Math.max(rows, 1) * DEFAULT_CELL_HEIGHT;
       }
 
@@ -1061,8 +1096,20 @@ class Layouter {
 
       if (grid) {
 
+        // Emit lane shapes BEFORE element shapes — bpmn-js uses DI order to
+        // establish parent-child containment (participant → lanes → elements → edges)
+        if (hasLanes) {
+          this.generateLanesDi(
+            laneInfo.lanes,
+            laneInfo.laneRowRanges,
+            { x: 0, y: currentY, width: participantWidth, height: participantHeight },
+            annotationPadding,
+            collaborationDi
+          );
+        }
+
         // Draw flow elements with participant offset (shifted down by annotation padding)
-        const shift = { x: PARTICIPANT_LABEL_WIDTH, y: currentY + annotationPadding };
+        const shift = { x: PARTICIPANT_LABEL_WIDTH + (hasLanes ? LANE_LABEL_WIDTH : 0), y: currentY + annotationPadding };
         this.generateDi(grid, shift, collaborationDi);
 
         // Draw expanded sub-processes within this participant
@@ -1468,8 +1515,10 @@ class Layouter {
     const participants = collaboration.participants;
     if (participants.length < 2) return 0;
 
-    const shapes = this.diagram.diagrams
-      .flatMap(d => d.plane.planeElement)
+    // Guard: when input XML for some reason has no DI section diagrams and planeElement are undefined
+    // until cleanDi() rebuilds them.
+    const shapes = (this.diagram.diagrams || [])
+      .flatMap(d => d.plane.planeElement || [])
       .filter(el => el.$type === 'bpmndi:BPMNShape' && participants.includes(el.bpmnElement));
 
     if (shapes.length < 2) return 0;
@@ -1560,6 +1609,154 @@ class Layouter {
   getProcDi(element) {
     return this.diagram.diagrams.find(diagram => diagram.plane.planeElement.includes(element));
   }
+
+  /**
+   * Detect lanes in a process and build element-to-lane mapping.
+   * @param {Object} process - BPMN process moddle element
+   * @returns {{ lanes: Object[], elementToLaneIdx: Map }|null}
+   */
+  getLaneMapping(process) {
+    const laneSet = (process.laneSets || [])[0];
+    if (!laneSet) return null;
+
+    const lanes = laneSet.lanes || [];
+    if (lanes.length === 0) return null;
+
+    // bpmn-moddle stores flowNodeRef as string IDs (not object references)
+    const idToLaneIdx = new Map();
+    lanes.forEach((lane, idx) => {
+      (lane.flowNodeRef || []).forEach(ref => {
+        const id = typeof ref === 'string' ? ref : ref.id;
+        idToLaneIdx.set(id, idx);
+      });
+    });
+
+    return { lanes, idToLaneIdx };
+  }
+
+  /**
+   * Reorganize grid rows so each lane's elements occupy distinct, non-overlapping
+   * row bands. Elements keep their column positions; only rows are remapped.
+   *
+   * @param {Grid} grid - The process grid (modified in place)
+   * @param {{ lanes: Object[], elementToLaneIdx: Map }} laneMapping
+   * @returns {Array<{ startRow: number, rowCount: number }>} Row range per lane
+   */
+  reorganizeGridByLanes(grid, laneMapping) {
+    const { lanes, idToLaneIdx } = laneMapping;
+    const positioned = grid.elementsByPosition();
+
+    // Group elements by lane index (lookup by element ID)
+    const byLane = new Map();
+    positioned.forEach(({ element, row, col }) => {
+      let laneIdx = idToLaneIdx.get(element.id);
+
+      // Infer lane for unassigned elements from connected elements
+      if (laneIdx === undefined) {
+        laneIdx = this.inferLane(element, idToLaneIdx) ?? 0;
+      }
+
+      if (!byLane.has(laneIdx)) byLane.set(laneIdx, []);
+      byLane.get(laneIdx).push({ element, origRow: row, col });
+    });
+
+    // Build new grid data with lanes in separate row bands
+    const newGridData = [];
+    const laneRowRanges = [];
+
+    for (let i = 0; i < lanes.length; i++) {
+      const group = byLane.get(i) || [];
+      const startRow = newGridData.length;
+
+      if (group.length === 0) {
+
+        // Empty lane still gets one row for visual presence
+        newGridData.push([]);
+        laneRowRanges.push({ startRow, rowCount: 1 });
+        continue;
+      }
+
+      // Map original rows to consecutive new rows within this lane band
+      const origRows = [ ...new Set(group.map(g => g.origRow)) ].sort((a, b) => a - b);
+      const rowMap = new Map();
+      origRows.forEach((r, idx) => rowMap.set(r, startRow + idx));
+
+      // Initialize empty rows
+      for (let j = 0; j < origRows.length; j++) newGridData.push([]);
+
+      // Place elements in their new positions
+      group.forEach(({ element, origRow, col }) => {
+        const newRow = rowMap.get(origRow);
+        while (newGridData[newRow].length <= col) newGridData[newRow].push(undefined);
+        newGridData[newRow][col] = element;
+      });
+
+      laneRowRanges.push({ startRow, rowCount: origRows.length });
+    }
+
+    // Replace grid's internal data
+    grid.grid = newGridData;
+    return laneRowRanges;
+  }
+
+  /**
+   * Infer lane index for an element not explicitly assigned to any lane,
+   * by checking its connected elements.
+   */
+  inferLane(element, idToLaneIdx) {
+    const outgoing = (element.outgoing || []).map(e => e.targetRef).filter(Boolean);
+    const incoming = (element.incoming || []).map(e => e.sourceRef).filter(Boolean);
+
+    for (const connected of [ ...outgoing, ...incoming ]) {
+      const idx = idToLaneIdx.get(connected.id);
+      if (idx !== undefined) return idx;
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Generate BPMNShape DI entries for lanes within a participant.
+   *
+   * @param {Object[]} lanes - Lane moddle elements
+   * @param {Array<{ startRow: number, rowCount: number }>} laneRowRanges
+   * @param {{ x: number, y: number, width: number, height: number }} participantBounds
+   * @param {number} annotationPadding - Extra top padding for annotations
+   * @param {Object} collaborationDi - Target diagram for DI shapes
+   */
+  generateLanesDi(lanes, laneRowRanges, participantBounds, annotationPadding, collaborationDi) {
+    const planeElement = collaborationDi.plane.get('planeElement');
+
+    const laneX = participantBounds.x + PARTICIPANT_LABEL_WIDTH;
+    const laneWidth = participantBounds.width - PARTICIPANT_LABEL_WIDTH;
+
+    let cumulativeY = participantBounds.y;
+
+    lanes.forEach((lane, idx) => {
+      const range = laneRowRanges[idx];
+      let laneHeight = range.rowCount * DEFAULT_CELL_HEIGHT;
+
+      // First lane absorbs annotation padding
+      if (idx === 0) {
+        laneHeight += annotationPadding;
+      }
+
+      const shape = this.diFactory.createDiShape(lane, {
+        x: laneX,
+        y: cumulativeY,
+        width: laneWidth,
+        height: laneHeight
+      }, {
+        id: lane.id + '_di',
+        isHorizontal: true
+      });
+
+      lane.di = shape;
+      planeElement.push(shape);
+
+      cumulativeY += laneHeight;
+    });
+  }
 }
 
 function containsElement(process, element) {