🚀 feat: Added support for ipsep-cola layout algorithm #6639

shubhamparikh2704 · 2025-06-09T15:22:23Z

📑 Summary

🧠 Summary: IPSEP-COLA Layout Algorithm Implementation

This PR introduces a complete implementation of the IPSEP-COLA layout algorithm for structured, layered graph drawing with advanced support for edge labels, self-loops, and group-aware positioning. The algorithm blends Sugiyama-style hierarchy with COLA (Constraint-Based Layout Algorithm) optimization to generate clean and readable diagrams.

🧩 Algorithm Overview

The layout proceeds through the following stages:

Edge Label Insertion
- Edge labels are treated as separate "dummy" nodes inserted between the source and target nodes.
- This ensures that labels are cleanly placed without overlapping edges or interfering with node spacing.
Layer Assignment
- Nodes (including edge label nodes) are assigned to vertical layers based on graph depth.
- Maintains hierarchy and ensures forward-flowing edge direction in DAGs.
Order Assignment
- Within each layer, nodes are ordered to reduce edge crossings using barycenter methods.
Initial Positioning (X, Y Coordinates)
- Based on layer and order data, initial (x, y) positions are assigned.
COLA-Based Refinement
- A constraint-based iterative force-directed engine refines the layout.
- Enforces horizontal/vertical spacing constraints, group containment, and alignment preservation.
- Resolves node overlaps and improves compactness while maintaining readability.

📏 Design Decisions

 To implement I have referred research paper of IPSep-CoLa: An Incremental Procedure for Separation Constraint Layout of Graphs.
 Added more details about the implementation into the doc server in the PR. Please refer.

📋 Tasks

Make sure you

📖 have read the contribution guidelines
💻 have added necessary unit/e2e tests.
📓 have added documentation. Make sure MERMAID_RELEASE_VERSION is used for all new features.
🦋 If your PR makes a change that should be noted in one or more packages' changelogs, generate a changeset by running pnpm changeset and following the prompts. Changesets that add features should be minor and those that fix bugs should be patch. Please prefix changeset messages with feat:, fix:, or chore:.

netlify · 2025-06-09T15:22:28Z

✅ Deploy Preview for mermaid-js ready!

Name	Link
🔨 Latest commit	`f06f1ba`
🔍 Latest deploy log	https://app.netlify.com/projects/mermaid-js/deploys/68931cfa266aca00080850f6
😎 Deploy Preview	https://deploy-preview-6639--mermaid-js.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

changeset-bot · 2025-06-09T15:22:28Z

🦋 Changeset detected

Latest commit: f06f1ba

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
mermaid	Minor
@mermaid-js/examples	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

pkg-pr-new · 2025-06-09T15:24:03Z

Open in StackBlitz

@mermaid-js/examples

npm i https://pkg.pr.new/mermaid-js/mermaid/@mermaid-js/examples@6639

mermaid

npm i https://pkg.pr.new/mermaid-js/mermaid@6639

@mermaid-js/layout-elk

npm i https://pkg.pr.new/mermaid-js/mermaid/@mermaid-js/layout-elk@6639

@mermaid-js/mermaid-zenuml

npm i https://pkg.pr.new/mermaid-js/mermaid/@mermaid-js/mermaid-zenuml@6639

@mermaid-js/parser

npm i https://pkg.pr.new/mermaid-js/mermaid/@mermaid-js/parser@6639

@mermaid-js/tiny

npm i https://pkg.pr.new/mermaid-js/mermaid/@mermaid-js/tiny@6639

commit: f06f1ba

argos-ci · 2025-06-09T15:31:01Z

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
default (Inspect)	⚠️ Changes detected (Review)	8 added	Aug 6, 2025, 9:25 AM

…nitial positions for ipsepcola layout

codecov · 2025-06-10T09:03:07Z

Codecov Report

❌ Patch coverage is 0.36675% with 1630 lines in your changes missing coverage. Please review.
✅ Project coverage is 3.59%. Comparing base (d93d9a5) to head (f06f1ba).

Files with missing lines	Patch %	Lines
...ring-util/layout-algorithms/ipsepCola/applyCola.ts	0.08%	1240 Missing ⚠️
...g-util/layout-algorithms/ipsepCola/nodeOrdering.ts	0.98%	101 Missing ⚠️
packages/mermaid/src/rendering-util/createGraph.ts	1.04%	95 Missing ⚠️
...endering-util/layout-algorithms/ipsepCola/index.ts	0.00%	66 Missing ⚠️
...til/layout-algorithms/ipsepCola/layerAssignment.ts	1.49%	66 Missing ⚠️
...g-util/layout-algorithms/ipsepCola/adjustLayout.ts	3.84%	25 Missing ⚠️
packages/mermaid/src/docs/.vitepress/config.ts	0.00%	21 Missing ⚠️
...out-algorithms/ipsepCola/assignInitialPositions.ts	7.14%	13 Missing ⚠️
packages/mermaid/src/rendering-util/render.ts	0.00%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #6639      +/-   ##
==========================================
- Coverage     3.71%   3.59%   -0.12%     
==========================================
  Files          454     462       +8     
  Lines        44752   46399    +1647     
  Branches       708     715       +7     
==========================================
+ Hits          1661    1667       +6     
- Misses       43091   44732    +1641

Flag	Coverage Δ
unit	`3.59% <0.36%> (-0.12%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
packages/mermaid/src/rendering-util/types.ts	`100.00% <ø> (ø)`
packages/mermaid/src/rendering-util/render.ts	`2.50% <0.00%> (-0.21%)`	⬇️
...out-algorithms/ipsepCola/assignInitialPositions.ts	`7.14% <7.14%> (ø)`
packages/mermaid/src/docs/.vitepress/config.ts	`0.38% <0.00%> (-0.04%)`	⬇️
...g-util/layout-algorithms/ipsepCola/adjustLayout.ts	`3.84% <3.84%> (ø)`
...endering-util/layout-algorithms/ipsepCola/index.ts	`0.00% <0.00%> (ø)`
...til/layout-algorithms/ipsepCola/layerAssignment.ts	`1.49% <1.49%> (ø)`
packages/mermaid/src/rendering-util/createGraph.ts	`1.04% <1.04%> (ø)`
...g-util/layout-algorithms/ipsepCola/nodeOrdering.ts	`0.98% <0.98%> (ø)`
...ring-util/layout-algorithms/ipsepCola/applyCola.ts	`0.08% <0.08%> (ø)`

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

sidharthv96 · 2025-06-17T07:02:47Z

packages/mermaid/src/docs/layouts/development.md

+## 📦 Prerequisites
+
+Before starting, ensure the following:
+
+- You have [Node.js](https://nodejs.org/) installed.
+- You have [pnpm](https://pnpm.io/) installed globally:
+  ```bash
+  npm install -g pnpm
+  ```
+
+---
+
+## 🔄 Step-by-Step Integration
+
+### 1. Clone the Mermaid Repository
+
+```bash
+git clone https://github.com/mermaid-js/mermaid.git
+cd mermaid
+```
+
+### 2. Install Dependencies
+
+Mermaid uses `pnpm` for dependency management:
+
+```bash
+pnpm i
+```
+
+### 3. Start the Development Server
+
+This will spin up a local dev environment with hot reload:
+
+```bash
+pnpm dev
+```


Please avoid duplicating the dev setup as it makes maintaining harder, better to link to our existing setup docs, and update it if required.

We even have a feature where we can inject markdown files if required.

sidharthv96 · 2025-06-17T07:12:47Z

packages/mermaid/src/docs/layouts/introduction.md

+
+## 🔍 Comparison Table
+
+| Feature                   | Dagre       | ELK                 | IPSep-CoLa (Upcoming)          |


Will IPSep-CoLa be upcoming after this is merged?

sidharthv96 · 2025-06-17T07:15:35Z

packages/mermaid/src/docs/layouts/ipsepcola/overview.md

+```
+---
+config:
+   layout: ipsepCola


General question, should we support an alias that's easier to remember?

sidharthv96 · 2025-06-17T07:17:07Z

packages/mermaid/src/rendering-util/layout-algorithms/ipsepCola/adjustLayout.ts

+    }
+  }
+
+  data4Layout.edges.forEach((edge) => {


nit: Better to stick with for..of loop for consistency.

sidharthv96 · 2025-06-17T07:17:39Z

packages/mermaid/src/rendering-util/layout-algorithms/ipsepCola/adjustLayout.ts

+  data4Layout.edges.forEach((edge) => {
+    insertEdge(
+      groups.edgePaths,
+      { ...edge },


Any reason to spread the edge here, rather than inside the function?

sidharthv96 · 2025-06-17T08:17:08Z

packages/mermaid/src/rendering-util/types.ts

+  isEdgeLabel?: boolean;
+  edgeStart?: string;
+  edgeEnd?: string;
+  layer?: number;
+  order?: number;
+  isDummy?: boolean;
 }

 export interface NonClusterNode extends BaseNode {
  shape?: ShapeID;
  isGroup: false;
+  isEdgeLabel?: boolean;
+  edgeStart?: string;
+  edgeEnd?: string;
+  layer?: number;
+  order?: number;
+  isDummy?: boolean;
 }


Can't this be added to base node?

sidharthv96 · 2025-08-13T17:07:10Z

packages/mermaid/src/rendering-util/render.ts

+    {
+      name: 'ipsepCola',
+      loader: async () => await import('./layout-algorithms/ipsepCola/index.js'),
+    },


Please follow a6d26ef

Added support for ipsep-cola layout algorithm

3a8952e

shubhamparikh2704 and others added 7 commits June 10, 2025 10:07

Updated calculateIterations for ipsepcola layout

cfd25ed

Added test cases for layer assignments, node ordering and assigning i…

13f8549

…nitial positions for ipsepcola layout

Updated folder name

99c8224

Updated all ts imports to js

a7e9f4f

Updated ts import to js

a46de01

[autofix.ci] apply automated fixes

75f940b

Updated test cases for ipsepcola layout algorithm

bb0aa40

Added changeset for layout algorithm

70eedd8

shubhamparikh2704 changed the title ~~Added support for ipsep-cola layout algorithm~~ Feat: Added support for ipsep-cola layout algorithm Jun 10, 2025

Added documentations for implemetation of layout algorithms

5e037ee

shubhamparikh2704 changed the title ~~Feat: Added support for ipsep-cola layout algorithm~~ feat: Added support for ipsep-cola layout algorithm Jun 10, 2025

shubhamparikh2704 and others added 3 commits June 10, 2025 20:42

Removed duplicate files

20ddc12

[autofix.ci] apply automated fixes

1a5a846

Updated nodeOrdering test case

b70abed

shubhamparikh2704 requested review from ashishjain0512, sidharthv96, aloisklink, knsv and saurabhg772244 June 10, 2025 15:38

shubhamparikh2704 self-assigned this Jun 10, 2025

shubhamparikh2704 added the feature label Jun 10, 2025

shubhamparikh2704 marked this pull request as ready for review June 10, 2025 15:41

shubhamparikh2704 changed the title ~~feat: Added support for ipsep-cola layout algorithm~~ 🚀 feat: Added support for ipsep-cola layout algorithm Jun 10, 2025

Added cypress testcase for ipsepCola layout

2785ca4

shubhamparikh2704 assigned ashishjain0512 Jun 12, 2025

shubhamparikh2704 added 2 commits June 16, 2025 13:35

Trigger Build

339927d

Merge branch 'develop' into ipsep-cola

3e99158

shubhamparikh2704 added the Sponsored by MermaidChart label Jul 9, 2025

sidharthv96 requested changes Jul 9, 2025

View reviewed changes

shubhamparikh2704 added 2 commits July 21, 2025 13:35

Resolved comments on pr of ipsep-cola

b01a0d7

Updated dead link in development.md

09c239f

shubhamparikh2704 requested a review from sidharthv96 July 21, 2025 08:47

shubhamparikh2704 added 3 commits July 29, 2025 16:12

Merge branch 'develop' into ipsep-cola

4ea4a7b

Merge branch 'develop' into ipsep-cola

e12036e

Merge branch 'develop' into ipsep-cola

f06f1ba

sidharthv96 reviewed Aug 13, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

🚀 feat: Added support for ipsep-cola layout algorithm #6639

🚀 feat: Added support for ipsep-cola layout algorithm #6639

Uh oh!

shubhamparikh2704 commented Jun 9, 2025 •

edited

Loading

Uh oh!

netlify bot commented Jun 9, 2025 •

edited

Loading

Uh oh!

changeset-bot bot commented Jun 9, 2025 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Jun 9, 2025 •

edited

Loading

Uh oh!

argos-ci bot commented Jun 9, 2025 •

edited

Loading

Uh oh!

codecov bot commented Jun 10, 2025 •

edited

Loading

Uh oh!

sidharthv96 Jun 17, 2025

Uh oh!

sidharthv96 Jun 17, 2025

Uh oh!

sidharthv96 Jun 17, 2025

Uh oh!

sidharthv96 Jun 17, 2025

Uh oh!

sidharthv96 Jun 17, 2025

Uh oh!

sidharthv96 Jun 17, 2025

Uh oh!

sidharthv96 Aug 13, 2025

Uh oh!

Uh oh!


		## 🔍 Comparison Table

		\| Feature \| Dagre \| ELK \| IPSep-CoLa (Upcoming) \|

Uh oh!

🚀 feat: Added support for ipsep-cola layout algorithm #6639

Are you sure you want to change the base?

🚀 feat: Added support for ipsep-cola layout algorithm #6639

Uh oh!

Conversation

shubhamparikh2704 commented Jun 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📑 Summary

🧠 Summary: IPSEP-COLA Layout Algorithm Implementation

🧩 Algorithm Overview

📏 Design Decisions

📋 Tasks

Uh oh!

netlify bot commented Jun 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for mermaid-js ready!

Uh oh!

changeset-bot bot commented Jun 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

pkg-pr-new bot commented Jun 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

argos-ci bot commented Jun 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Jun 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

sidharthv96 Jun 17, 2025

Choose a reason for hiding this comment

Uh oh!

sidharthv96 Jun 17, 2025

Choose a reason for hiding this comment

Uh oh!

sidharthv96 Jun 17, 2025

Choose a reason for hiding this comment

Uh oh!

sidharthv96 Jun 17, 2025

Choose a reason for hiding this comment

Uh oh!

sidharthv96 Jun 17, 2025

Choose a reason for hiding this comment

Uh oh!

sidharthv96 Jun 17, 2025

Choose a reason for hiding this comment

Uh oh!

sidharthv96 Aug 13, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

shubhamparikh2704 commented Jun 9, 2025 •

edited

Loading

netlify bot commented Jun 9, 2025 •

edited

Loading

changeset-bot bot commented Jun 9, 2025 •

edited

Loading

pkg-pr-new bot commented Jun 9, 2025 •

edited

Loading

argos-ci bot commented Jun 9, 2025 •

edited

Loading

codecov bot commented Jun 10, 2025 •

edited

Loading