feat(xychart): add per-point text labels for line charts

[DominicBurkart]

📑 Summary

Adds syntax for per-point text labels on xychart line plots:

xychart
    title "Quarterly Performance"
    x-axis [Q1, Q2, Q3, Q4]
    y-axis "Revenue ($M)" 0 --> 100
    line [25, 45, 80 "target hit", 90]

From the deploy preview:

Resolves #7549

Note: I added stacked PRs to elaborate the label placement, namely:

• checks for collision with the line itself fix(xychart): auto-flip point labels to avoid line collision #7551
• checks for collision with the x axis fix(xychart): prevent flipped point label from clipping x-axis #7552

📷 QA Screenshots

All test cases rendered via Playwright (Chromium) with the default theme. (full QA comment with details)

1. Basic Labeled Line — line [10 "A", 20 "B", 30 "C"]

2. Mixed Labels — line [10 "Start", 20, 30 "End"]

3. Backward Compatibility — line [10, 20, 30] (no labels)

4. Horizontal Orientation — labeled line with xychart horizontal

5. Multiple Lines — one labeled, one unlabeled

6. Real-World Use Case — MMLU Model Performance

Test Summary

Test Case	Status
Basic labeled line	✅ PASS
Mixed labels	✅ PASS
Backward compat (no labels)	✅ PASS
Horizontal orientation	✅ PASS
Multiple lines	✅ PASS
Real-world MMLU	✅ PASS

Automated tests: 58/58 parser unit tests pass, 4008/4008 full suite tests pass, 0 regressions.

📋 Tasks

• 📖 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: cd2e1d3

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	cd2e1d3
🔍 Latest deploy log	https://app.netlify.com/projects/mermaid-js/deploys/6a1687fca3024c0008b0f907
😎 Deploy Preview	https://deploy-preview-7550--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@7550

mermaid

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

@mermaid-js/layout-elk

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

@mermaid-js/layout-tidy-tree

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

@mermaid-js/mermaid-zenuml

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

@mermaid-js/parser

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

@mermaid-js/tiny

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

commit: cd2e1d3

[codecov]

Codecov Report

❌ Patch coverage is 0% with 52 lines in your changes missing coverage. Please review.
✅ Project coverage is 3.25%. Comparing base (a930ea2) to head (cd2e1d3).

Files with missing lines	Patch %	Lines
...s/xychart/chartBuilder/components/plot/linePlot.ts	0.00%	43 Missing ⚠️
packages/mermaid/src/diagrams/xychart/xychartDb.ts	0.00%	9 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #7550      +/-   ##
==========================================
- Coverage     3.26%   3.25%   -0.01%     
==========================================
  Files          599     600       +1     
  Lines        60899   60957      +58     
  Branches       917     917              
==========================================
  Hits          1986    1986              
- Misses       58913   58971      +58     

Flag	Coverage Δ
unit	3.25% <0.00%> (-0.01%)	⬇️

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

Files with missing lines	Coverage Δ
...id/src/diagrams/xychart/chartBuilder/interfaces.ts	10.00% <ø> (ø)
packages/mermaid/src/diagrams/xychart/xychartDb.ts	0.00% <0.00%> (ø)
...s/xychart/chartBuilder/components/plot/linePlot.ts	0.00% <0.00%> (ø)

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

[argos-ci]

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

Build	Status	Details	Updated (UTC)
default (Inspect)	⚠️ Changes detected (Review)	4 added	May 27, 2026, 6:10 AM

[knsv]

[sisyphus-bot]

Thanks for this contribution, @DominicBurkart! Really nice feature — per-point labels on line charts is something that comes up a lot in real-world use cases like benchmark visualizations and trend annotations. The syntax extension feels natural and the backward compatibility is well preserved.

---

What's working well

🎉 [praise] Clean, intuitive syntax design. line [540 "PaLM", 65 "LLaMA-65B"] reads naturally and extends the existing data array format without ambiguity. Mixing labeled and unlabeled points is a great ergonomic choice.

🎉 [praise] Excellent test coverage — both parser unit tests (6 new test cases covering labels, mixed labels, spaces in labels, decimal values) and 4 E2E visual regression tests including horizontal orientation and multi-line scenarios. This is exactly what we look for.

🎉 [praise] Documentation uses MERMAID_RELEASE_VERSION placeholder correctly, changeset is properly configured as minor with feat: prefix, and source docs are in the right location (packages/mermaid/src/docs/).

---

Things to address

🟡 [important] — Point labels bypass textSanitizer()

In xychartDb.ts, all other user-provided text goes through textSanitizer() (which calls sanitizeText from diagrams/common/common.js):

• setXAxisTitle → textSanitizer(title.text) (line 89)
• setXAxisBand → textSanitizer(c.text) for each category (line 99)
• setYAxisTitle → textSanitizer(title.text) (line 104)

But the new setLineData passes labels through without sanitization:

const labels = data.map((d) => d.label);  // no textSanitizer() call

The rendering pipeline uses D3's .text() (safe) and DOMPurify sanitizes the final SVG, so this isn't an active XSS vector — but it breaks the defense-in-depth pattern established by the codebase. It would be great to add sanitization for consistency:

const labels = data.map((d) => (d.label ? textSanitizer(d.label) : ''));

🟡 [important] — Generated docs/syntax/xyChart.md appears to be manually edited

The top-level docs/ directory is auto-generated from packages/mermaid/src/docs/. The PR modifies both:

• packages/mermaid/src/docs/syntax/xyChart.md (source — correct ✓)
• docs/syntax/xyChart.md (generated — should not be manually edited)

The generated file has duplicated mermaid-example + mermaid block pairs and different formatting (> **Note** vs the source's ```note), confirming it's the build output. This file should be removed from the PR and regenerated via the docs build instead. Otherwise the next docs rebuild will overwrite these changes or create a confusing diff.

🟢 [nit] — Bar data labels are parsed but silently discarded

The JISON grammar change means bar [10 "A", 20 "B"] now parses successfully and produces {value, label} objects, but setBarData only extracts values — labels are silently dropped. This is fine for the scope of this PR (feature is for line charts), but worth a brief note in the docs that labels are currently only supported on line plots, so users don't wonder why bar labels have no effect.

🟢 [nit] — Hardcoded font size and label offset

In linePlot.ts:48-49:

const labelOffset = 10;
const fontSize = 12;

These magic numbers work for now, but other text in xychart (axis labels, title) uses configurable sizes from XYChartConfig and theme variables. Not blocking, but worth considering making these configurable in a follow-up — especially fontSize, which won't scale well if users customize other chart text sizes.

---

Security

Reviewed the full data flow: JISON parser → ParsedDataPoint.label → xychartDb.setLineData → LinePlotData.pointLabels → linePlot.ts → TextElem → D3 .text() rendering → DOMPurify final sanitization.

No XSS or injection vulnerabilities identified. The rendering uses D3's safe .text() method (sets textContent, not innerHTML), and DOMPurify sanitizes the final SVG output. The missing textSanitizer() call (noted above) is a defense-in-depth concern, not an active vulnerability.

---

Looking forward to getting this landed — it's a well-scoped, well-tested feature. The two 🟡 items should be quick to address. Let me know if you have any questions!

[DominicBurkart]

Hello @knsv! Let me know if any additional action is needed on my end on this PR!

Would it be easier if I merged all three into one large PR, or kept them separate as-is?

[knsv-bot]

Hi @DominicBurkart, thanks for the ping and apologies for the delay!

Let's keep them as three separate PRs. Each one is a meaningfully distinct piece of work — base feature, line collision avoidance, axis collision avoidance — and reviewing them independently makes it easier to evaluate each on its own merits, lets us land them incrementally as they're ready, and keeps the diffs small enough to bisect or revert cleanly if anything ever surfaces downstream. The stacked structure you set up works really well for that.

A couple of quick notes on this one before we move forward:

• 🎉 Thanks for adding the textSanitizer() call in 706df00 — that closes the defense-in-depth gap nicely.

This is approved now!

[mermaid-bot]

@DominicBurkart, Thank you for the contribution!
You are now eligible for a year of Premium account on MermaidChart.
Sign up with your GitHub account to activate.