fix: render state diagram click tooltips

[puneetdixit200]

Summary

• Adds tooltip binding for state diagram nodes using the shared mermaidTooltip behavior.
• Sets the click directive tooltip title on the wrapped state node, including aliased states like A: Google.
• Adds regression coverage for clickable state diagram tooltips in classic and hand-drawn looks.

Tests

• vitest run packages/mermaid/src/diagrams/state/stateDiagram.spec.js packages/mermaid/src/diagrams/state/stateDiagram-v2.spec.js packages/mermaid/src/diagrams/state/stateDb.spec.js packages/mermaid/src/diagrams/state/stateRenderer-v3-unified.spec.js packages/mermaid/src/diagrams/state/parser/state-parser.spec.js packages/mermaid/src/diagrams/state/parser/state-style.spec.js
• cypress run --spec cypress/integration/rendering/state/stateDiagram-v2.spec.js --config video=false
• prettier --check on touched files
• eslint --quiet on touched files

Closes #6701

[changeset-bot]

🦋 Changeset detected

Latest commit: 0ea9ba6

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

mermaid

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

@mermaid-js/layout-elk

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

@mermaid-js/layout-tidy-tree

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

@mermaid-js/mermaid-zenuml

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

@mermaid-js/parser

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

@mermaid-js/tiny

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

commit: 0ea9ba6

[codecov]

Codecov Report

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

Files with missing lines	Patch %	Lines
packages/mermaid/src/diagrams/state/stateDb.ts	0.00%	36 Missing ⚠️
...aid/src/diagrams/state/stateRenderer-v3-unified.ts	0.00%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #7751      +/-   ##
==========================================
- Coverage     3.27%   3.27%   -0.01%     
==========================================
  Files          600     600              
  Lines        60657   60695      +38     
  Branches       916     916              
==========================================
  Hits          1985    1985              
- Misses       58672   58710      +38     

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

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

Files with missing lines	Coverage Δ
...aid/src/diagrams/state/stateRenderer-v3-unified.ts	0.00% <0.00%> (ø)
packages/mermaid/src/diagrams/state/stateDb.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)	✅ No changes detected	-	May 18, 2026, 3:36 PM

[Copilot]

Pull request overview

This PR adds state diagram click tooltip support by attaching Mermaid’s shared tooltip behavior to rendered state nodes and setting tooltip titles on clickable wrapped nodes.

Changes:

• Adds tooltip binding support to StateDB.
• Sets click directive tooltip titles on wrapped state nodes in the v3 unified renderer.
• Adds a regression test and patch changeset.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
packages/mermaid/src/diagrams/state/stateRenderer-v3-unified.ts	Narrows click target selection and adds tooltip titles to wrapped nodes.
packages/mermaid/src/diagrams/state/stateDb.ts	Adds tooltip binding via bindFunctions.
packages/mermaid/src/diagrams/state/stateRenderer-v3-unified.spec.js	Adds regression coverage for clickable tooltip rendering.
.changeset/state-tooltip-links.md	Adds a patch release note.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[pbrolin47]

Hi @puneetdixit200. Thanks for publishing this PR. Some feedback:

[sisyphos-bot]

---

What's working well

🎉 Idiomatic pattern. The funs/bindFunctions/setupToolTips triad is exactly how flowDb.ts and classDb.ts implement this. New contributors often miss this pattern; following
it correctly is the right call.

🎉 Binding in constructor. this.bindFunctions = this.bindFunctions.bind(this) is needed because mermaidAPI.ts:477 extracts the method as a property (bindFunctions:
diag.db.bindFunctions). Without this bind, this inside setupToolTips would be lost when called later. Getting this right without prompting is good.

🎉 clear() reinitializes funs. Each render gets a fresh tooltip setup. Missing this is a common bug with the funs pattern; the PR gets it right.

🎉 DOMPurify usage is correct. User-controlled tooltip text flows from stateId→linkInfo.tooltip→tooltipElem.html(DOMPurify.sanitize(title)). The sanitization happens at the
right boundary.

🎉 Hand-drawn mode coverage. The rough-node selector and it.each parametrized tests are a thoughtful addition in the follow-up commit.

🎉 Tests verified. Both parametrized tests pass against the PR's code (stateRenderer-v3-unified.spec.js, 2/2 ✓).

---

Things to address

🟡 [important] — No Cypress integration test for the click directive behavior

The change adds matchedElem.setAttribute('title', tooltip) to the renderer and wires up the full bindFunctions chain. The unit tests cover the tooltip lifecycle well, but
there's no Cypress test that verifies a state diagram with a click directive actually renders with the wrapper and title attribute in a real browser environment.

cypress/integration/rendering/stateDiagram-v2.spec.js has no test for click behavior. A test like:

it('renders clickable state nodes with title attribute', () => {
const diagram = stateDiagram-v2 A: Google click A href "https://google.com" "Visit Google" ;
cy.render(diagram);
cy.get('a[xlink\:href] > g.node[title="Visit Google"]').should('exist');
});

would give regression coverage for the wrapping + title attribution.

🟢 [nit] — Redundant .text(title) before .html(...) in setupToolTips (stateDb.ts:663)

tooltipElem
.text(title) // ← immediately overwritten
.style('left', ...)
.style('top', ...);
tooltipElem.html(DOMPurify.sanitize(title));

The .style() positioning doesn't depend on .text() being called first — it can be chained directly on tooltipElem. The .text() call is a no-op (.html() overwrites it on the
next line). The same pattern exists in flowDb.ts, so this is inherited tech debt rather than a new problem. Not blocking.

💡 [suggestion] — setupToolTips is now copy-pasted across three DB classes

stateDb.ts, flowDb.ts, and classDb.ts now each have nearly identical 30-line setupToolTips implementations. The only difference is the selector string ('g.node' vs 'g.node,
g.rough-node'). A single setupTooltipBehavior(element, selector) helper in diagrams/common/svgDrawCommon.ts would consolidate this. Not a requirement for this PR, but worth
a follow-up issue.

---

Security

No XSS concerns. The tooltip text is user-controlled content that flows through DOMPurify.sanitize() before being set as innerHTML. The title attribute on SVG elements does
not create an injection vector. The xlink:href URL sanitization concern (potential javascript: URLs) is a pre-existing issue from the original link-injection code in the
prior PR, not introduced here.

---

Summary: The fix is correctly implemented, follows established patterns, and the tests pass. The bindFunctions chain integrates cleanly with mermaidAPI.ts. A Cypress test
for the click directive would be the meaningful gap to fill before merge, but the unit coverage is solid enough that this reads as a strong fix.