bpmn-auto-layout 0.4.0 → 1.0.0

package/README.md

@@ -2,46 +2,65 @@
 
 [![CI](https://github.com/bpmn-io/bpmn-auto-layout/actions/workflows/CI.yml/badge.svg)](https://github.com/bpmn-io/bpmn-auto-layout/actions/workflows/CI.yml)
 
-Get a layouted diagram of a BPMN process without graphical representation.
-
+Create and layout the graphical representation of a BPMN diagram.
 
 ## Usage
 
-This library works in [Node.js](https://nodejs.org/) and in the browser.
-
-To layout diagrams these must have __exactly one single start event__.
+This library works with [Node.js](https://nodejs.org/) and in the browser.
 
 ```javascript
 import { layoutProcess } from 'bpmn-auto-layout';
 
-const diagramXML = '<bpmn:defintions ...></bpmn:defintions>';
+import diagramXML from './diagram.bpmn';
 
-const layoutedDiagramXML = await layoutProcess(diagramXML);
+const diagramWithLayoutXML = await layoutProcess(diagramXML);
 
-console.log(layoutedDiagramXML);
+console.log(diagramWithLayoutXML);
 ```
-## Unsupported Concepts and elements
 
-The Tool can currently not properly layout diagrams containing any of the following:
-- Pools
-- Data/Message Flows and Objects, Data Stores
-- event sub-processes
+## Limitations
 
+* Given a collaboration only the first participant's process will be laid out
+* Sub-processes will be laid out as collapsed sub-processes
+* The following elements are not laid out:
+  * Groups
+  * Text annotations
+  * Associations
+  * Message flows
 
 ## Resources
 
-*   [Issues](https://github.com/bpmn-io/bpmn-auto-layout/issues)
-
+* [Issues](https://github.com/bpmn-io/bpmn-auto-layout/issues)
 
-## Building
+## Build and Run
 
 ```sh
+# install dependencies
 npm install
+
+# build and run tests
 npm run all
+
+# run example
+npm start
 ```
 
-As part of the test run, visual test cases are generated to `test/generated/test.html`.
+## Test
+
+We use snapshot testing to verify old and new layout attempts. A mismatch is indicated as a test failure.
+
+```sh
+# run tests
+npm test
+
+# inspect the results
+npm run test:inspect
+
+# run update snapshots
+npm run test:update-snapshots
+```
 
+Add new test cases to [`test/fixtures`](./test/fixures) and they will be picked up automatically.
 
 ## License
 

package/dist/index.cjs

@@ -11,6 +11,27 @@ function isBoundaryEvent(element) {
   return !!element.attachedToRef;
 }
 
+function findElementInTree(currentElement, targetElement, visited = new Set()) {
+
+  if (currentElement === targetElement) return true;
+
+  if (visited.has(currentElement)) return false;
+
+  visited.add(currentElement);
+
+  // If currentElement has no outgoing connections, return false
+  if (!currentElement.outgoing || currentElement.outgoing.length === 0) return false;
+
+  // Recursively check each outgoing element
+  for (let nextElement of currentElement.outgoing.map(out => out.targetRef)) {
+    if (findElementInTree(nextElement, targetElement, visited)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
 class Grid {
   constructor() {
     this.grid = [];
@@ -54,7 +75,6 @@ class Grid {
     if (!element) {
       this._addStart(newElement);
     }
-
     const [ row, col ] = this.find(element);
     this.grid[row].splice(col + 1, 0, newElement);
   }
@@ -124,6 +144,84 @@ class Grid {
     return elements;
   }
 
+  adjustGridPosition(element) {
+    let [ row, col ] = this.find(element);
+    const [ , maxCol ] = this.getGridDimensions();
+
+    if (col < maxCol - 1) {
+
+      // add element in next column
+      this.grid[row].length = maxCol;
+      this.grid[row][maxCol] = element;
+      this.grid[row][col] = null;
+
+    }
+  }
+
+  adjustRowForMultipleIncoming(elements, currentElement) {
+    const results = elements.map(element => this.find(element));
+
+    // filter only rows that currently exist, excluding any future or non-existent rows
+    const lowestRow = Math.min(...results
+      .map(result => result[0])
+      .filter(row => row >= 0));
+
+    const [ row , col ] = this.find(currentElement);
+
+    // if element doesn't already exist in current row, add element
+    if (lowestRow < row && !this.grid[lowestRow][col]) {
+      this.grid[lowestRow][col] = currentElement;
+      this.grid[row][col] = null;
+    }
+  }
+
+  adjustColumnForMultipleIncoming(elements, currentElement) {
+    const results = elements.map(element => this.find(element));
+
+    // filter only col that currently exist, excluding any future or non-existent col
+    const maxCol = Math.max(...results
+      .map(result => result[1])
+      .filter(col => col >= 0));
+
+    const [ row , col ] = this.find(currentElement);
+
+    // add to the next column
+    if (maxCol + 1 > col) {
+      this.grid[row][maxCol + 1] = currentElement;
+      this.grid[row][col] = null;
+    }
+  }
+
+  getAllElements() {
+    const elements = [];
+
+    for (let row = 0; row < this.grid.length; row++) {
+      for (let col = 0; col < this.grid[row].length; col++) {
+        const element = this.get(row, col);
+
+        if (element) {
+          elements.push(element);
+        }
+      }
+    }
+
+    return elements;
+  }
+
+  getGridDimensions() {
+    const numRows = this.grid.length;
+    let maxCols = 0;
+
+    for (let i = 0; i < numRows; i++) {
+      const currentRowLength = this.grid[i].length;
+      if (currentRowLength > maxCols) {
+        maxCols = currentRowLength;
+      }
+    }
+
+    return [ numRows , maxCols ];
+  }
+
   elementsByPosition() {
     const elements = [];
 
@@ -142,6 +240,12 @@ class Grid {
 
     return elements;
   }
+
+  getElementsTotal() {
+    const flattenedGrid = this.grid.flat();
+    const uniqueElements = new Set(flattenedGrid.filter(value => value));
+    return uniqueElements.size;
+  }
 }
 
 class DiFactory {
@@ -323,12 +427,12 @@ function connectElements(source, target, layoutGrid) {
   if (dY === 0) {
     if (isDirectPathBlocked(source, target, layoutGrid)) {
 
-      // Route on top
+      // Route on bottom
       return [
-        getDockingPoint(sourceMid, sourceBounds, 't'),
-        { x: sourceMid.x, y: sourceMid.y - DEFAULT_CELL_HEIGHT / 2 },
-        { x: targetMid.x, y: sourceMid.y - DEFAULT_CELL_HEIGHT / 2 },
-        getDockingPoint(targetMid, targetBounds, 't')
+        getDockingPoint(sourceMid, sourceBounds, 'b'),
+        { x: sourceMid.x, y: sourceMid.y + DEFAULT_CELL_HEIGHT / 2 },
+        { x: targetMid.x, y: sourceMid.y + DEFAULT_CELL_HEIGHT / 2 },
+        getDockingPoint(targetMid, targetBounds, 'b')
       ];
     } else {
 
@@ -362,6 +466,15 @@ function connectElements(source, target, layoutGrid) {
     }
   }
 
+  // negative dX indicates connection from future to past
+  if (dX < 0 && dY <= 0) {
+    return [
+      getDockingPoint(sourceMid, sourceBounds, 'b'),
+      { x: sourceMid.x, y: sourceMid.y + DEFAULT_CELL_HEIGHT / 2 },
+      { x: targetMid.x, y: sourceMid.y + DEFAULT_CELL_HEIGHT / 2 },
+      getDockingPoint(targetMid, targetBounds, 'b')
+    ];
+  }
   const directManhattan = directManhattanConnect(source, target, layoutGrid);
 
   if (directManhattan) {
@@ -477,7 +590,7 @@ var attacherHandler = {
     const nextElements = [];
 
     const attachedOutgoing = (element.attachers || [])
-      .map(att => att.outgoing.reverse())
+      .map(attacher => (attacher.outgoing || []).reverse())
       .flat()
       .map(out => out.targetRef);
 
@@ -550,11 +663,6 @@ function insertIntoGrid(newElement, host, grid) {
     grid.createRow(row);
   }
 
-  // Host has element directly after, add space
-  if (grid.get(row, col + 1)) {
-    grid.addAfter(host, null);
-  }
-
   grid.add(newElement, [ row + 1, col + 1 ]);
 }
 
@@ -614,8 +722,8 @@ var elementHandler = {
 };
 
 var outgoingHandler = {
-  'addToGrid': ({ element, grid, visited }) => {
-    const nextElements = [];
+  'addToGrid': ({ element, grid, visited, stack }) => {
+    let nextElements = [];
 
     // Handle outgoing paths
     const outgoing = (element.outgoing || [])
@@ -623,14 +731,28 @@ var outgoingHandler = {
       .filter(el => el);
 
     let previousElement = null;
+
+    if (outgoing.length > 1 && isNextElementTasks(outgoing)) {
+      grid.adjustGridPosition(element);
+    }
+
     outgoing.forEach((nextElement, index, arr) => {
       if (visited.has(nextElement)) {
         return;
       }
 
+      // Prevents revisiting future incoming elements and ensures proper traversal without early exit.
+      if ((previousElement || stack.length > 0) && isFutureIncoming(nextElement, visited) && !checkForLoop(nextElement, visited)) {
+        return;
+      }
+
       if (!previousElement) {
         grid.addAfter(element, nextElement);
       }
+
+      else if (is(element, 'bpmn:ExclusiveGateway') && is(nextElement, 'bpmn:ExclusiveGateway')) {
+        grid.addAfter(previousElement, nextElement);
+      }
       else {
         grid.addBelow(arr[index - 1], nextElement);
       }
@@ -644,8 +766,11 @@ var outgoingHandler = {
       visited.add(nextElement);
     });
 
+    // Sort elements by priority to ensure proper stack placement
+    nextElements = sortByType(nextElements, 'bpmn:ExclusiveGateway'); // TODO: sort by priority
     return nextElements;
   },
+
   'createConnectionDi': ({ element, row, col, layoutGrid, diFactory }) => {
     const outgoing = element.outgoing || [];
 
@@ -663,7 +788,59 @@ var outgoingHandler = {
   }
 };
 
-const handlers = [ elementHandler, outgoingHandler, attacherHandler ];
+
+// helpers /////
+
+function sortByType(arr, type) {
+  const nonMatching = arr.filter(item => !is(item,type));
+  const matching = arr.filter(item => is(item,type));
+
+  return [ ...matching, ...nonMatching ];
+
+}
+
+function checkForLoop(element, visited) {
+  for (const incomingElement of element.incoming) {
+    if (!visited.has(incomingElement.sourceRef)) {
+      return findElementInTree(element, incomingElement.sourceRef);
+    }
+  }
+}
+
+
+function isFutureIncoming(element, visited) {
+  if (element.incoming.length > 1) {
+    for (const incomingElement of element.incoming) {
+      if (!visited.has(incomingElement.sourceRef)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+function isNextElementTasks(elements) {
+  return elements.every(element => is(element, 'bpmn:Task'));
+}
+
+var incomingHandler = {
+  'addToGrid': ({ element, grid, visited }) => {
+    const nextElements = [];
+
+    const incoming = (element.incoming || [])
+      .map(out => out.sourceRef)
+      .filter(el => el);
+
+    // adjust the row if it is empty
+    if (incoming.length > 1) {
+      grid.adjustColumnForMultipleIncoming(incoming, element);
+      grid.adjustRowForMultipleIncoming(incoming, element);
+    }
+    return nextElements;
+  },
+};
+
+const handlers = [ elementHandler, incomingHandler, outgoingHandler, attacherHandler ];
 
 class Layouter {
   constructor() {
@@ -686,8 +863,10 @@ class Layouter {
 
     const root = this.getProcess();
 
-    this.cleanDi();
-    this.handlePlane(root);
+    if (root) {
+      this.cleanDi();
+      this.handlePlane(root);
+    }
 
     return (await this.moddle.toXML(this.diagram, { format: true })).xml;
   }
@@ -704,7 +883,13 @@ class Layouter {
   createGridLayout(root) {
     const grid = new Grid();
 
-    const flowElements = root.flowElements;
+    const flowElements = root.flowElements || [];
+    const elements = flowElements.filter(el => !is(el,'bpmn:SequenceFlow'));
+
+    // check for empty process/subprocess
+    if (!flowElements) {
+      return grid;
+    }
 
     const startingElements = flowElements.filter(el => {
       return !isConnection(el) && !isBoundaryEvent(el) && (!el.incoming || el.length === 0);
@@ -727,19 +912,17 @@ class Layouter {
       visited.add(el);
     });
 
-    while (stack.length > 0) {
-      const currentElement = stack.pop();
+    this.handleGrid(grid,visited,stack);
 
-      if (is(currentElement, 'bpmn:SubProcess')) {
-        this.handlePlane(currentElement);
+    if (grid.getElementsTotal() != elements.length) {
+      const gridElements = grid.getAllElements();
+      const missingElements = elements.filter(el => !gridElements.includes(el) && !isBoundaryEvent(el));
+      if (missingElements.length > 1) {
+        stack.push(missingElements[0]);
+        grid.add(missingElements[0]);
+        visited.add(missingElements[0]);
+        this.handleGrid(grid,visited,stack);
       }
-
-      const nextElements = this.handle('addToGrid', { element: currentElement, grid, visited });
-
-      nextElements.flat().forEach(el => {
-        stack.push(el);
-        visited.add(el);
-      });
     }
 
     return grid;
@@ -784,6 +967,22 @@ class Layouter {
     });
   }
 
+  handleGrid(grid, visited, stack) {
+    while (stack.length > 0) {
+      const currentElement = stack.pop();
+
+      if (is(currentElement, 'bpmn:SubProcess')) {
+        this.handlePlane(currentElement);
+      }
+
+      const nextElements = this.handle('addToGrid', { element: currentElement, grid, visited, stack });
+
+      nextElements.flat().forEach(el => {
+        stack.push(el);
+        visited.add(el);
+      });
+    }
+  }
 
   getProcess() {
     return this.diagram.get('rootElements').find(el => el.$type === 'bpmn:Process');