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: d94ee1b

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	d94ee1b
🔍 Latest deploy log	https://app.netlify.com/projects/mermaid-js/deploys/6a1ac38b0c2998000883d265
😎 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: d94ee1b

[codecov]

Codecov Report

❌ Patch coverage is 0% with 40 lines in your changes missing coverage. Please review.
✅ Project coverage is 3.27%. Comparing base (9bae92c) to head (d94ee1b).

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          599     600       +1     
  Lines        60986   61035      +49     
  Branches       921     921              
==========================================
  Hits          1997    1997              
- Misses       58989   59038      +49     

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%> (ø)

... 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)	✅ No changes detected	-	May 30, 2026, 11:06 AM

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

[puneetdixit200]

Added the browser coverage in 7c2f60f. The Cypress test renders the state click directive and asserts the wrapped link plus the titled state node.

Verified locally:

• pnpm exec prettier --check cypress/integration/rendering/state/stateDiagram-v2.spec.js
• git diff --check
• pnpm exec vitest run packages/mermaid/src/diagrams/state/stateRenderer-v3-unified.spec.js
• MERMAID_PORT=9000 CYPRESS_CACHE_FOLDER=/tmp/mermaid-7751-cache pnpm exec start-server-and-test "pnpm dev" http://localhost:9000/ "pnpm exec cypress run --spec cypress/integration/rendering/state/stateDiagram-v2.spec.js --config video=false,defaultCommandTimeout=10000"

The GitHub checks are green on the new head.

[pbrolin47]

Hi @puneetdixit200 Thanks for addressing issues. An additional thing to look at for improvement of a unit-test.

[sisyphos-bot]

---

What's working well

🎉 DOMPurify.sanitize(title) is applied before .html() — the tooltip text is sanitized before being inserted as HTML. Correct.

🎉 Follows the established flowDb.ts pattern — funs, setupToolTips, bindFunctions, createTooltip, D3 mouseover/mouseout handlers — this is the exact same approach flowchart uses. Consistent.

🎉 domId-based matching is the right fix for aliased states — the original text-matching (text === stateId) broke for A: Google because the displayed text is 'Google' but stateId is 'A'. Using g.id
=== stateNode?.domId (which the real render.ts sets) correctly matches by DOM identity. The Cypress test for this exact case (A: Google) verifies it end-to-end.

🎉 Cypress tests cover both classic and handDrawn looks — the loop over { look: 'classic', nodeSelector: 'g.node' } and { look: 'handDrawn', nodeSelector: 'g.rough-node' } is good regression
coverage.

🎉 Changeset present — patch bump and fix: prefix are correct for a bug fix.

---

Things to address

🟡 [important] Unit test mock doesn't simulate node.domId assignment, so it doesn't actually exercise the domId-based fix

In stateRenderer-v3-unified.spec.js, the render mock creates a DOM element using layoutNode?.domId ?? 'state-A-0' but doesn't mutate layoutNode.domId. The real render.ts (lines 67-68) does this:

const originalDomId = node.domId || node.id;
node.domId = ${data4Layout.diagramId}-${originalDomId};

Without that mutation, stateNode.domId in links.forEach is undefined, so g.id === stateNode?.domId is always false. The aliased-state case (A: Google) then also fails the text fallback ('Google' !==
'A'), meaning matchedElem stays undefined and the link wrapping silently skips. The unit test's expect(node).not.toBeNull() would catch this — could you confirm the test passes as-is, and if so,
explain how?

Adding one line to the mock would fix the coverage gap:

vi.mock('../../rendering-util/render.js', () => ({
render: vi.fn((data, svg) => {
const layoutNode = data.nodes.find((node) => node.id === 'A') ?? data.nodes[0];
+if (layoutNode) layoutNode.domId = ${svg.attr('id')}-${layoutNode.id};
// ...
}),
}));

---

[puneetdixit200]

Updated in d955a9c26 to mutate layoutNode.domId in the render mock before creating the SVG node, matching the real renderer behavior. The unit test now exercises the g.id === stateNode?.domId path for the aliased-state case.

Verified locally:

• CYPRESS_INSTALL_BINARY=0 PNPM_HOME=/tmp/mermaid-7751-pnpm-home XDG_CACHE_HOME=/tmp/mermaid-7751-xdg-cache CYPRESS_CACHE_FOLDER=/tmp/mermaid-7751-cypress-cache pnpm install --ignore-scripts --frozen-lockfile --store-dir /tmp/mermaid-7751-pnpm-store
• pnpm exec prettier --check packages/mermaid/src/diagrams/state/stateRenderer-v3-unified.spec.js
• pnpm exec vitest run packages/mermaid/src/diagrams/state/stateRenderer-v3-unified.spec.js
• git diff --check

[mermaid-bot]

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