fix: align branch label background with text for multi-line labels in LR GitGraph

[veeceey]

Fixes #7362

When using GitGraph with LR layout and branch names containing multi-line text (e.g. "Feature A\n(ongoing)"), the background rectangle for branch labels was vertically misaligned with the actual text.

Root cause

In drawBranches(), the background rect's vertical transform for LR layout used pos - bbox.height / 2, which is height-dependent. The label text, however, is positioned at a fixed center point of pos - 1 regardless of height. As bbox.height increases with multi-line text, the background rect shifts further up while the text stays centered, creating a visible offset.

Single-line (~16px height): rect center at pos + 2, text center at pos - 1 -- 3px off
Two lines (~32px height): rect center at pos - 6, text center at pos - 1 -- 5px off, opposite direction

Fix

Replaced the height-dependent transform pos - bbox.height / 2 with a constant offset pos - 11, derived from the constraint that the rect center must equal the text center:

transformY + (-bbox.height/2 + 8) + (bbox.height + 4)/2 = pos - 1
transformY + 10 = pos - 1
transformY = pos - 11

This keeps the background centered on the text regardless of how many lines the branch name spans.

Testing

• All 30 inline unit tests in gitGraphRenderer.ts pass
• All 70 parser tests in gitGraph.spec.ts pass
• Added Cypress snapshot test for multi-line branch label in LR layout

[changeset-bot]

🦋 Changeset detected

Latest commit: c541af4

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

This PR includes changesets to release 1 package

Name	Type
mermaid	Patch

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	c541af4
🔍 Latest deploy log	https://app.netlify.com/projects/mermaid-js/deploys/69a52de279eb950008b68937
😎 Deploy Preview	https://deploy-preview-7393--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/examples@7393

mermaid

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

@mermaid-js/layout-elk

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

@mermaid-js/layout-tidy-tree

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

@mermaid-js/mermaid-zenuml

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

@mermaid-js/parser

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

@mermaid-js/tiny

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

commit: a523212

[codecov]

Codecov Report

❌ Patch coverage is 0% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 3.55%. Comparing base (6f85f2b) to head (c541af4).
⚠️ Report is 25 commits behind head on develop.

Files with missing lines	Patch %	Lines
...kages/mermaid/src/diagrams/git/gitGraphRenderer.ts	0.00%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##           develop   #7393   +/-   ##
=======================================
  Coverage     3.55%   3.55%           
=======================================
  Files          490     490           
  Lines        48785   48785           
  Branches       765     765           
=======================================
  Hits          1734    1734           
  Misses       47051   47051           

Flag	Coverage Δ
unit	3.55% <0.00%> (ø)

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

Files with missing lines	Coverage Δ
...kages/mermaid/src/diagrams/git/gitGraphRenderer.ts	0.00% <0.00%> (ø)

🚀 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 approved	45 changed, 1 added	Mar 2, 2026, 6:38 AM

[veeceey]

Hi team, gentle ping on this PR — it fixes the branch label background misalignment for multi-line labels in LR GitGraph (#7362). The 44 changed Argos snapshots are expected since the fix affects the label positioning formula. Happy to walk through the changes if helpful!

[veeceey]

Gentle ping — is there anything else needed from my side for this PR? Happy to make any adjustments if needed.

[knsv]

Hey @veeceey Thanks for the reminder. Will review!

[knsv]

[sisyphus-bot]

Thanks for the thorough analysis and clean fix, @veeceey — the mathematical derivation in the PR description is excellent and makes the change easy to verify.

What's working well

🎉 [praise] — Outstanding root cause analysis. Walking through the geometry to show exactly how the old pos - bbox.height / 2 double-counted the height (since the rect's own y attribute already incorporates -bbox.height/2 + 8) makes this a joy to review. The algebraic derivation of the constant 11 is the kind of documentation reviewers dream about.

🎉 [praise] — This fix also quietly improves single-line label centering (from ~3px off to exactly centered), which is a nice bonus. The fact that a single constant replaces a height-dependent expression and works for all line counts confirms the math is right.

Minor notes

🟢 [nit] — The constant 11 is derived from the rect's y offset (8) and half the extra padding (4/2 = 2), giving a center offset of 10, hence pos - 11 to target pos - 1. If the rect attributes (y = -bbox.height/2 + 8, height = bbox.height + 4) ever change, this would need updating too. A brief inline comment like // derived: rect center offset is always +10, text center is pos-1 could help future contributors — but this is entirely optional given the codebase's existing style with magic numbers throughout the renderer.

💡 [suggestion] — The Cypress test covers the fix well. If you wanted to be extra thorough, a test with three-line labels (e.g., "Feature A\n(ongoing)\nv2") would further demonstrate that the fix is truly height-independent. Not needed for merge — just a thought.

Verdict

Clean, minimal, mathematically sound fix with good test coverage and a proper changeset. Approving — let's get this across the finish line. 🚀

[mermaid-bot]

@veeceey, 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.