flowchart: add datastore shape

[aruncveli]

📑 Summary

Add data store as a flowchart shape, to represent data stores in data flow diagrams.

Resolves #7502.

📏 Design Decisions

The current solution attempts to add a top and bottom border to a rectangular node. For hand drawn look, remove the rectangle's border and draw rough.js lines on top and bottom edges. For the other two looks, use stroke-dasharray on the label container.

My unfamiliarity with the codebase led me to prompt GitHub Copilot to generate an initial solution and then modify it. Even then, I might have missed best practices or utility functions for achieving common tasks.

I also would like to have a discussion about the name of the shape. There are other options. I just went with datastore for now since that's what's popular at my workplace.

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

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

mermaid

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

@mermaid-js/layout-elk

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

@mermaid-js/layout-tidy-tree

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

@mermaid-js/mermaid-zenuml

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

@mermaid-js/parser

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

@mermaid-js/tiny

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

commit: dcd5774

[codecov]

Codecov Report

❌ Patch coverage is 1.72414% with 57 lines in your changes missing coverage. Please review.
✅ Project coverage is 3.33%. Comparing base (e74b11e) to head (dcd5774).
⚠️ Report is 8 commits behind head on develop.

Files with missing lines	Patch %	Lines
...dering-util/rendering-elements/shapes/datastore.ts	2.00%	49 Missing ⚠️
...id/src/rendering-util/rendering-elements/shapes.ts	0.00%	8 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #7512      +/-   ##
==========================================
- Coverage     3.33%   3.33%   -0.01%     
==========================================
  Files          536     536              
  Lines        56252   56299      +47     
  Branches       820     821       +1     
==========================================
+ Hits          1876    1877       +1     
- Misses       54376   54422      +46     

Flag	Coverage Δ
unit	3.33% <1.72%> (-0.01%)	⬇️

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

Files with missing lines	Coverage Δ
...id/src/rendering-util/rendering-elements/shapes.ts	0.22% <0.00%> (-0.01%)	⬇️
...dering-util/rendering-elements/shapes/datastore.ts	2.00% <2.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 approved	1 changed, 33 added, 32 removed	Apr 14, 2026, 4:24 PM

[lee-treehouse]

@aruncveli nice! I hear you about discussing the shape name, but in my opinion its worth updating the docs - at least https://mermaid.js.org/syntax/flowchart.html?id=flowcharts-basic-syntax#complete-list-of-new-shapes and the dataflow demo page https://github.com/mermaid-js/mermaid/blob/develop/demos/dataflowchart.html as well as adding the changeset.

[aruncveli]

@lee-treehouse One question about the documentation, should I add a (vMERMAID_RELEASE_VERSION+) to the right of the doc entry? I couldn't find such suffixes for headings of the same hierarchy.

[lee-treehouse]

@ashishjain0512 or @sidharthv96, I wondered if you’d be interested to take a look at this new shape PR to get dataflow diagrams working? 🙏

[lee-treehouse]

heya @aruncveli I took a look on your preview branch,

one thing I notice is that if you switch to hand drawn, the shape doesn't work

this won't be acceptable for a mature diagram like a flowchart.

I was interested in the problem, I don't know much about the hand drawn shapes (which use roughjs under the hood) so I ran a test which you can see here.
https://codepen.io/editor/Lee-Taylor-the-selector/pen/019d2c30-6f01-739c-84b2-a5f838d00405

roughjs uses the https://github.com/rough-stuff/rough/wiki#strokelinedash property rather than stroke-dasharray and doesn't seem to apply it the same way (seems like it starts from the beginning of the array as it renders each side, I demonstrate this by using an array of [100, 150] and it draws a 100px line on each side)

so I think we can't use the same approach for roughjs.. but we could instead draw the lines rather than have them come from stroke, as I show in the example.

I couldn't see any other shape with the same problem (I made a page, here #7510 to see them all together with normal vs hand drawn options)

what do you think? I will also post this comment in the open source discord to see if anyone has a suggestion

[aruncveli]

Hey, thanks for the experiments. I'm just realizing that the issue is also visible in the Argos report. I'll see what I can do.

[aruncveli]

From the latest Argos report:

1. I didn't understand why/how could the arch diagrams change due to the changes here? Can someone guide me where to start looking?
2. A test which contains stroke-dasharray as part of testing classDef seems to work "correctly" by overriding the styles of the shape. But should it? Should datastore not allow overriding stroke-dasharray?

[ashishjain0512]

Thanks @aruncveli for your effort

1. I didn't understand why/how could the arch diagrams change due to the changes here? Can someone guide me where to start looking?

--> It not related to your changes, that specific test for architecture diagram is flaky, and we will fix it separately. You can ignore that.

2. A test which contains stroke-dasharray as part of testing classDef seems to work "correctly" by overriding the styles of the shape. But should it? Should the datastore not allow overriding stroke-dasharray?

---> For flowchart shapes, the typical override behavior is in this order: theme < themeVariable in config < classDef < style statement.
You should aim for the same. I understand that data-store is a special shape, where overriding the stroke-dasharray can change the shape's meaning altogether; we could limit it. But frankly, if someone wants to use this shape, they'll probably not use the stroke-dasharray override.

[aruncveli]

Thanks for the response! What can be the next step for the PR?

[pbrolin47]

Hi @aruncveli, thanks for adding support for datastore shape. Some additional input:

---

🟡 [important] datastore.ts:24 — Fragile DOM selector with missing null guard in handDrawn mode:

const borderSelection = rect.select('.basic.label-container > path:nth-child(2)');
const borderPath = borderSelection.node() as SVGPathElement;
const bb = borderPath.getBBox(); // ← crashes if borderPath is null

This selector bakes in knowledge of rough.js's internal rendering structure (a group with two children for fill and stroke). If the selector doesn't match — wrong rough.js version, different node structure, or any DOM layout change — borderPath
is null and .getBBox() throws a TypeError, crashing the renderer for any handDrawn datastore node. It would be great to add a null guard and either fall back gracefully or log a warning:

const borderPath = borderSelection.node() as SVGPathElement | null;
if (!borderPath) return rect; // graceful fallback
const bb = borderPath.getBBox();

It would also be worth checking whether newShapes.spec.ts or any other E2E test exercises the handDrawn look for this shape — if not, that path has no regression coverage.

---

🟡 [important] datastore.ts:22-23 — Variable name shadowing:

const options: RectOptions = { ... }; // outer options
...
if (node.look === 'handDrawn') {
const rc = rough.svg(rect);
const options = userNodeOverrides(node, {}); // ← shadows outer options

The inner const options shadows the outer RectOptions. TypeScript doesn't error here, but it's easy to misread during a refactor and accidentally reference the wrong one. Consider renaming the inner to something like roughOptions

---

[aruncveli]

Thanks @pbrolin47 for your review. Please check if my latest changes have addressed your concerns.

AFAIU from the argos report, the shapes in newShapes.spec.ts are covered for handDrawn look. I've raised a question from such a test in an earlier comment.

[ashishjain0512]

[sisyphus-bot]

Final pass on this one. The latest changes in ddd4885 (PATCH 5) address the earlier feedback cleanly — variable shadowing fixed, null guard on borderPath, instanceof check before getBBox(). This is ready.

---

What's working well

🎉 Clever stroke-dasharray approach. ${width} ${height} on a rect's perimeter naturally produces top-bottom-only borders without any extra elements. Simple, no extra DOM, and renders correctly at any size.

🎉 Handdrawn mode implemented. Uses rough.js lines for top and bottom edges, removes the default path — exactly the right approach. The null check on borderPath means graceful degradation if drawRect internals ever change.

🎉 Full test suite. Alias test in nodes.spec.ts, visual regression in both flowchart-shape-alias.spec.ts and newShapes.spec.ts, plus docs coverage test in docs.spec.ts. The coverage is thorough for a single-shape addition.

🎉 Good docs and changeset. Source docs in src/docs/syntax/flowchart.md with mermaid-example blocks, changeset with minor bump and clear description, shape table entry added. Everything wired correctly.

---

Nits (non-blocking)

🟢 [nit] — Fragile selector in handDrawn path

packages/mermaid/src/rendering-util/rendering-elements/shapes/datastore.ts:22

const borderSelection = rect.select('.basic.label-container > path:nth-child(2)');

This selector depends on drawRect's internal DOM structure — the second path child. If drawRect is refactored, this silently degrades to a full-bordered rect (via the null guard — good). Worth a comment explaining what the selector targets, e.g., // Select the rough.js border path (second child of the container).

🟢 [nit] — @ts-ignore on rough.svg(rect)

Pre-existing pattern used by other shapes — not introduced here. Just noting it inherits the same TODO.

---

Security

No XSS surface. The shape manipulates only SVG presentation attributes (stroke-dasharray, rough.js line geometry) — no user-controlled strings flow into href, innerHTML, or event handlers. Label text is rendered through the standard drawRect → label pipeline, which is sanitized upstream.

---

Self-check

• 🔴 blocking: 0
• 🟡 important: 0
• 🟢 nit: 2
• 💡 suggestion: 0
• 🎉 praise: 4
• Verdict: APPROVE ✓

[mermaid-bot]

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