Feature: Enhance Pie Chart - Enable donut chart, Set legend position, and highlight slice

[ngdaniels]

📑 Summary

This PR adds features that enhances pie chart.

• Enables donut chart
• Set legend position
• Highlight specific slice / highlight slice on hover

Resolves #7607

Resolves #

📏 Design Decisions

Enables donut chart

Add innerHole property on pieConfig. The value is the ratio of the hole to the outer diameter. Default to 0.

Set legend position

Add legendPosition property on pieConfig. The value is the position of the legend, relative to the chart. Default to right.

Set legend position

Add highlightSlice property on pieConfig. The value is the name of the label to be highlighted. Will highlight hovered slice if value is set to hover.

📋 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:.

[changeset-bot]

🦋 Changeset detected

Latest commit: d82a544

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

This PR includes changesets to release 1 package

Name	Type
mermaid	Minor

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

[netlify]

✅ Deploy Preview for mermaid-js ready!

Name	Link
🔨 Latest commit	d82a544
🔍 Latest deploy log	https://app.netlify.com/projects/mermaid-js/deploys/6a0daa0b18f2e500085d56b0
😎 Deploy Preview	https://deploy-preview-7760--mermaid-js.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

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/examples@7760

mermaid

npm i https://pkg.pr.new/mermaid@7760

@mermaid-js/layout-elk

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

@mermaid-js/layout-tidy-tree

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

@mermaid-js/mermaid-zenuml

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

@mermaid-js/parser

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

@mermaid-js/tiny

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

commit: d82a544

[codecov]

Codecov Report

❌ Patch coverage is 0% with 77 lines in your changes missing coverage. Please review.
✅ Project coverage is 3.26%. Comparing base (2a51ae4) to head (d82a544).
⚠️ Report is 39 commits behind head on develop.

Files with missing lines	Patch %	Lines
packages/mermaid/src/diagrams/pie/pieRenderer.ts	0.00%	77 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #7760      +/-   ##
==========================================
- Coverage     3.27%   3.26%   -0.01%     
==========================================
  Files          600     599       -1     
  Lines        60657   60826     +169     
  Branches       916     917       +1     
==========================================
+ Hits          1985    1986       +1     
- Misses       58672   58840     +168     

Flag	Coverage Δ
unit	3.26% <0.00%> (-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/diagrams/pie/pieStyles.ts	5.55% <ø> (ø)
packages/mermaid/src/diagrams/pie/pieRenderer.ts	0.47% <0.00%> (-0.20%)	⬇️

... and 18 files 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.

[argos-ci]

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

Build	Status	Details	Updated (UTC)
default (Inspect)	⚠️ Changes detected (Review)	6 added	May 20, 2026, 12:44 PM

[pbrolin47]

Hi @ngdaniels,
Thanks for this PR. It will make good improvements of the Pie Chart.

[sisyphos-bot]

What's Working Well

🎉 [praise] The CSS class approach for highlightSlice (pieCircleHighlighted, pieCircleHighlightedOnHover) is clean — class-based toggling is the right way to do this rather
than inlining styles, and decoupling the hover case from the permanent highlight is good API design.

🎉 [praise] The donutHole validation in the renderer is solid: donutHole > 0 && donutHole <= 0.9 ? donutHole : 0 silently falls back to a standard pie for out-of-range
values, and the two new Cypress tests (donutHole: 1.2 and donutHole: -0.3) verify the graceful degradation.

🎉 [praise] Grouping the pie chart visuals (circle, slices, text) into a pie group element and then translating the whole group for top/left legend positions is a much
cleaner approach than separately repositioning each element. Good refactor.

---

Items to Address

🔴 [blocking] config.type.ts was manually edited — regenerate from schema instead

config.type.ts is an auto-generated file. Per project conventions, it must only be changed by running pnpm run --filter mermaid types:build-config. The CI lint job validates
this via types:verify-config (.github/workflows/lint.yml:62).

The manual edits happen to produce content that matches the generator output (which is why lint passes), but the process is wrong. Please regenerate the file:

pnpm run --filter mermaid types:build-config

Then commit the result. Do not edit config.type.ts by hand.

🔴 [blocking] Missing changeset

The PR adds three new user-facing config options (donutHole, legendPosition, highlightSlice) with no changeset file. This is required for any user-facing change:

(The checklist item in your PR description is unchecked — easy to miss!)

🔴 [blocking] Default legend position changed — causes visual regression in all existing pie charts

This is the source of the 14 changed Argos screenshots.

The old code positioned the legend at a fixed horizontal = 12 * LEGEND_RECT_SIZE = 216px from center. The new default (right) case uses horizontal = radius +
LEGEND_RECT_SIZE + LEGEND_SPACING = radius + 22.

For a typical SVG height of 450px, radius = (450/2) - 40 = 185, so the new offset is 207 — close but not equal. For smaller diagrams (height=360), the old offset was 216
while the new is 162. Every existing pie chart in every GitHub/GitLab document now renders with a shifted legend. This is a breaking visual change.

The fix: for the default (right) case, preserve the original formula or ensure the new formula produces the same visual for the default configuration. The safest path is to
start from the original implementation for the default case:

case 'right':
default:
chartAndLegendWidth += LEGEND_RECT_SIZE + LEGEND_SPACING + longestTextWidth;
legend.attr('transform', (_datum, index: number): string => {
const height = LEGEND_RECT_SIZE + LEGEND_SPACING;
const offset = (height * allSectionData.length) / 2;
const horizontal = 12 * LEGEND_RECT_SIZE; // preserve original offset
const vertical = index * legendHeight - offset;
return translate(${horizontal}, ${vertical});
});
break;

(Or if you believe the new radius-relative positioning is better, that's a separate design discussion — but it needs Argos baseline approval from maintainers and
acknowledgment that it affects existing documents.)

---

🟡 [important] legendPosition typed as string — should be a union type

config.type.ts and config.schema.yaml both declare legendPosition?: string. The renderer only handles center, top, bottom, left, and falls through to right for anything
else. An invalid value silently renders as right-legend, with no error or warning.

The schema should constrain valid values:

legendPosition:
type: string
enum: ['top', 'bottom', 'left', 'right', 'center']
default: 'right'

And config.type.ts (after regeneration) would become:
legendPosition?: 'top' | 'bottom' | 'left' | 'right' | 'center';

This enables IDE autocomplete, catches typos at the config level, and documents the valid values explicitly.

🟡 [important] Schema maximum: 1 contradicts code cap of 0.9

config.schema.yaml declares:
donutHole:
maximum: 1

But pieRenderer.ts silently clamps at 0.9:
pieConfig.donutHole > 0 && pieConfig.donutHole <= 0.9 ? pieConfig.donutHole : 0

Users who read the schema or docs (which say "0 to 0.9") will be confused by the mismatch. Update the schema to match the code:

donutHole:
minimum: 0
maximum: 0.9

---

🟢 [nit] Two Cypress tests have identical descriptions

pie.spec.ts (patch 7/8):
it('should render a pie diagram if donutHole parameter is invalid', () => { // donutHole: 1.2
it('should render a pie diagram if donutHole parameter is invalid', () => { // donutHole: -0.3

Same string, different inputs — the second will shadow the first in test reporters. Rename them:
it('should render a pie diagram if donutHole is too large (1.2)', ...
it('should render a pie diagram if donutHole is negative (-0.3)', ...

🟢 [nit] !important in styles can likely be avoided

pieStyles.ts:
.pieCircleHighlighted {
scale: 1.05 !important;
opacity: 1 !important;
}

!important overrides the .pieCircle { opacity: ... } rule. A simpler fix is higher specificity: .pieCircle.pieCircleHighlighted { ... }. This avoids the !important arms race
and is easier to override downstream.

---

Security

No XSS or injection issues identified. highlightSlice is a config-level setting (not from diagram syntax), and label matching uses strict equality — no DOM interpolation.

---

Self-Check

• At least one 🎉 praise item (3)
• No duplicate comments
• Severity tally: 3 🔴 / 2 🟡 / 2 🟢 / 0 💡 / 3 🎉
• Verdict: REQUEST_CHANGES (3 🔴 issues)
• Not a draft PR
• Tone: community — warm, specific, actionable

---

Verdict: REQUEST_CHANGES

Three blocking items need attention: regenerate config.type.ts via the provided script (the manual edit is correct content but wrong process), add a changeset, and
investigate + fix the default legend position shift that's causing 14 visual regressions in Argos. The two 🟡 items (union type for legendPosition, schema/code range
mismatch) are also worth addressing before merge but are less urgent.

The core feature set is solid — once these are sorted this should be in good shape to land!

[ngdaniels]

Hi @pbrolin47 ,

Thanks for the feedback, really appreciate it.
I just started trying to contribute here, and these feedback gave me so much guidance.

I've tried running pnpm changeset, but I don't see any prompt to set the changes to minor.
Is it ok if I edit it manually?

[ashishjain0512]

Hi @pbrolin47 ,

Thanks for the feedback, really appreciate it. I just started trying to contribute here, and these feedback gave me so much guidance.

I've tried running pnpm changeset, but I don't see any prompt to set the changes to minor. Is it ok if I edit it manually?

Yes @ngdaniels , you can manually edit your changeset file to match the correct level, patch or minor