feat: complete usecase diagram integration & validation

[Sudhanshu-Ambastha]

📑 Summary

Implements a dedicated Use Case Diagram renderer for Mermaid (usecaseDiagram), resolving the approved diagram request and addressing the curved path routing issue for include/extend relationships within system boundaries.

The implementation follows UML 2.x standards for correct element shapes, relationship types, and layout conventions.

Resolves #7414
Also closes #4628

---

📏 Design Decisions

• Parser (usecaseDb.ts) — A text-based parser reads usecaseDiagram syntax directly.
• Syntax Support — Supports actor, usecase, system {} boundary, external, collaboration, note, and 9 relationship types.
• Validation — Relationship validity is enforced via an explicit allow-list based on UML 2.x rules. Invalid connections are skipped with a log.warn hint instead of causing runtime failures.
• Renderer (usecaseRenderer.ts) — D3-based SVG renderer aligned with Mermaid’s rendering architecture.
• Curved Routing — Internal relationships (include/extend/dependency) use quadratic Bézier curves routed along the boundary edge to eliminate zig-zag artifacts and improve readability.
• External Connections — Straight-line routing with ellipse-edge intersection for precise arrow attachment.
• Configuration (config.yaml) — Introduces UsecaseDiagramConfig into the global Mermaid configuration schema.
• IntelliSense — Enables full editor support (e.g., VS Code) and aligns with Mermaid’s global config patterns.
• Theming (usecaseStyles.ts) — Uses standard Mermaid theme variables (primaryColor, lineColor, etc.).
• Style Validation (styles.spec.ts) — Adds automated tests (Vitest) to ensure consistent rendering across default themes.
• Detector (usecaseDetector.ts) — Activates on usecaseDiagram or useCase keywords at the start of input.

---

Example Syntax

usecaseDiagram
    actor "Customer" as C
    actor "Technician" as T
    external "Bank Server" as S
    system "ATM System" {
        usecase "Withdraw Cash" as UC1
        usecase "Check Balance" as UC2
        usecase "Login" as UC3
    }
    note "Requires PIN" as N1
    C --> UC1; UC2
    T --> UC3
    include: UC1 --> UC3
    dependency: UC1 --> S
    generalization: T --> C
    anchor: N1 --> UC3

📝 Notes for Reviewers

Relationship Rules

• Defined in usecaseDb.ts (ALLOWED table)
• If any rule is missing or incorrect, please flag it or update directly
• Each rule includes reasoning aligned with UML 2.x semantics

Invalid Relationships

• Never fatal
• Silently skipped with a log.warn hint for easier debugging

Rendering

• Diagram renders correctly in deploy preview when manually tested
• Curved routing resolves previously reported layout issues

Known Issue

• The "Use Case" option is currently missing from the "Sample Diagrams" sidebar
• Likely due to a registry/build sync issue in the monorepo
• Please advise if additional registry files require updates

---

even same in old pr [7519](https://github.com//pull/7519)

📋 Tasks

• 📖 Read the contribution guidelines
• 💻 Added unit/e2e tests (including style validation suite)
• 📓 Added documentation
• 🦋 Generated a changeset using pnpm changeset

[netlify]

✅ Deploy Preview for mermaid-js ready!

Name	Link
🔨 Latest commit	46dee6f
🔍 Latest deploy log	https://app.netlify.com/projects/mermaid-js/deploys/69ccc10e75815700089d14dc
😎 Deploy Preview	https://deploy-preview-7530--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.

[changeset-bot]

🦋 Changeset detected

Latest commit: 46dee6f

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

This PR includes changesets to release 2 packages

Name	Type
@mermaid-js/examples	Patch
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

[pkg-pr-new]

Open in StackBlitz

@mermaid-js/examples

npm i https://pkg.pr.new/@mermaid-js/examples@7530

mermaid

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

@mermaid-js/layout-elk

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

@mermaid-js/layout-tidy-tree

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

@mermaid-js/mermaid-zenuml

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

@mermaid-js/parser

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

@mermaid-js/tiny

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

commit: 46dee6f

[codecov]

Codecov Report

❌ Patch coverage is 1.34100% with 1030 lines in your changes missing coverage. Please review.
✅ Project coverage is 3.31%. Comparing base (e9d4c11) to head (46dee6f).
⚠️ Report is 68 commits behind head on develop.

Files with missing lines	Patch %	Lines
...es/mermaid/src/diagrams/usecase/usecaseRenderer.ts	0.18%	540 Missing ⚠️
packages/mermaid/src/diagrams/usecase/usecaseDb.ts	0.30%	323 Missing ⚠️
...ages/mermaid/src/diagrams/usecase/usecaseStyles.ts	2.43%	40 Missing ⚠️
packages/examples/src/examples/usecase.ts	6.25%	15 Missing ⚠️
...ges/mermaid/src/diagrams/usecase/usecaseDiagram.ts	6.25%	15 Missing ⚠️
...es/mermaid/src/diagrams/usecase/usecaseDetector.ts	8.33%	11 Missing ⚠️
packages/mermaid/src/themes/theme-base.js	0.00%	8 Missing ⚠️
packages/mermaid/src/themes/theme-dark.js	0.00%	8 Missing ⚠️
packages/mermaid/src/themes/theme-forest.js	0.00%	8 Missing ⚠️
packages/mermaid/src/themes/theme-neo-dark.js	0.00%	8 Missing ⚠️
... and 10 more

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #7530      +/-   ##
==========================================
- Coverage     3.34%   3.31%   -0.04%     
==========================================
  Files          524     531       +7     
  Lines        55256   56311    +1055     
  Branches       795     805      +10     
==========================================
+ Hits          1850    1864      +14     
- Misses       53406   54447    +1041     

Flag	Coverage Δ
unit	3.31% <1.34%> (-0.04%)	⬇️

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

Files with missing lines	Coverage Δ
packages/mermaid/src/config.type.ts	100.00% <ø> (ø)
packages/mermaid/src/themes/theme-default.js	95.45% <100.00%> (+0.08%)	⬆️
.build/jsonSchema.ts	0.00% <0.00%> (ø)
packages/mermaid/src/docs/.vitepress/config.ts	0.40% <0.00%> (-0.01%)	⬇️
packages/examples/src/index.ts	1.78% <0.00%> (-0.07%)	⬇️
...s/mermaid/src/diagram-api/diagram-orchestration.ts	0.00% <0.00%> (ø)
packages/mermaid/src/themes/theme-base.js	2.34% <0.00%> (-0.06%)	⬇️
packages/mermaid/src/themes/theme-dark.js	2.12% <0.00%> (-0.05%)	⬇️
packages/mermaid/src/themes/theme-forest.js	2.34% <0.00%> (-0.05%)	⬇️
packages/mermaid/src/themes/theme-neo-dark.js	2.36% <0.00%> (-0.06%)	⬇️
... and 12 more

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

[Sudhanshu-Ambastha]

Hi @rolivencia, @knsv,
The UseCase diagram logic is stable, but I’m hitting a wall with "discovery" wiring—it isn't showing up in samples/live-reloads unless I explicitly write the code for it.

Could you point me to the specific file for global diagram type registration? Or, if it's easier, assign a maintainer to help me with this final integration step?
Note on E2E: Most tests are passing; if i am right the remaining failures are purely due to the screenshot limit in the E2E suite (because of the additional samples I’ve included), rather than a logic error. 🚀
Thanks!

[argos-ci]

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

Build	Status	Details	Updated (UTC)
default (Inspect)	⚠️ Changes detected (Review)	347 changed, 508 added	Apr 1, 2026, 7:06 AM