feat(sankey): add Apple-style rendering with smart labels and custom node colors

[xinbenlv]

📑 Summary

This PR adds Apple-style rendering enhancements to Sankey diagrams, including smart label positioning, outlined labels, and custom node colors.

Resolves #6129 - Sankey improvements: Let user specify node and path color

Related to #6290 - This PR provides an alternative/extended implementation with additional features beyond custom colors.

✨ New Features

1. Custom Node Colors (nodeColors)

Allows specifying colors for individual nodes via frontmatter config:

---
config:
  sankey:
    nodeColors:
      Revenue: "#424245"
      Profit: "#34c759"
      Expenses: "#ff3b30"
---
sankey
source,Revenue,100
Revenue,Profit,60
Revenue,Expenses,40

2. Outlined Labels (labelStyle: 'default')

New default label style with white stroke background for better readability on dark backgrounds.

To use the original plain text labels, set labelStyle: 'legacy'.

3. Smart Label Positioning

Labels automatically position based on node layer relative to the central node (node with maximum value):

• Nodes left of center → labels on left (right-aligned)
• Nodes right of center → labels on right (left-aligned)

4. Configurable Layout

New options:

• nodeWidth: Width of node rectangles (default: 10)
• nodePadding: Padding between nodes (default: 12)

📏 Design Decisions

• nodeColors vs colors: Used nodeColors (object mapping node ID → color) for clarity. Nodes not specified fall back to default D3 color scheme.
• labelStyle enum: 'default' = outlined labels (new), 'legacy' = plain text labels (original). No breaking change since 'default' is now the default.
• Smart label positioning: Inspired by Apple's financial flow diagrams - labels don't overlap with nodes and flows.
• Backward compatible: Existing diagrams render with the new outlined style automatically.

📋 Tasks

• 📖 have read the contribution guidelines
• 💻 have added necessary unit/e2e tests.
• 📓 have added documentation.
• 🦋 generate changeset

Energy Demo

Before

After

Apple Finance

Before

After

[changeset-bot]

⚠️ No Changeset found

Latest commit: a34ee8f

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[netlify]

✅ Deploy Preview for mermaid-js ready!

Name	Link
🔨 Latest commit	a34ee8f
🔍 Latest deploy log	https://app.netlify.com/projects/mermaid-js/deploys/6951d5510ddf470008f2fcdb
😎 Deploy Preview	https://deploy-preview-7272--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.

[pkg-pr-new]

Open in StackBlitz

@mermaid-js/examples

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

mermaid

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

@mermaid-js/layout-elk

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

@mermaid-js/layout-tidy-tree

npm i https://pkg.pr.new/mermaid-js/mermaid/@mermaid-js/layout-tidy-tree@7272

@mermaid-js/mermaid-zenuml

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

@mermaid-js/parser

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

@mermaid-js/tiny

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

commit: a34ee8f

[codecov]

Codecov Report

❌ Patch coverage is 3.06122% with 95 lines in your changes missing coverage. Please review.
✅ Project coverage is 3.57%. Comparing base (d5bc07d) to head (a34ee8f).

Files with missing lines	Patch %	Lines
...ages/mermaid/src/diagrams/sankey/sankeyRenderer.ts	0.00%	66 Missing ⚠️
packages/mermaid/src/diagrams/sankey/styles.js	0.00%	27 Missing ⚠️
packages/mermaid/src/utils/sanitizeDirective.ts	0.00%	2 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##           develop   #7272   +/-   ##
=======================================
  Coverage     3.57%   3.57%           
=======================================
  Files          473     473           
  Lines        47475   47551   +76     
  Branches       734     734           
=======================================
+ Hits          1696    1699    +3     
- Misses       45779   45852   +73     

Flag	Coverage Δ
unit	3.57% <3.06%> (+<0.01%)	⬆️

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

Files with missing lines	Coverage Δ
packages/mermaid/src/config.type.ts	100.00% <ø> (ø)
packages/mermaid/src/defaultConfig.ts	41.58% <100.00%> (+0.83%)	⬆️
packages/mermaid/src/utils/sanitizeDirective.ts	6.06% <0.00%> (-0.10%)	⬇️
packages/mermaid/src/diagrams/sankey/styles.js	0.00% <0.00%> (ø)
...ages/mermaid/src/diagrams/sankey/sankeyRenderer.ts	0.55% <0.00%> (-0.20%)	⬇️

🚀 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.

[argos-ci]

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

Build	Status	Details	Updated (UTC)
default (Inspect)	⚠️ Changes detected (Review)	9 changed, 9 added	Dec 29, 2025, 1:21 AM