feat(1624): first draft, prototype of context map grammar and diagram

[AngeloChecked]

📑 Summary

Hi Mermaid Guys, this PR addresses the diagram discussed in this GitHub issue: 1624.

You can find a demo here: https://angelochecked.github.io/mermaid/

I've started implementing something, but it's in its early and raw stages. If anyone has a better prototype, please reach out to me (writing here) so I can contribute to it.

I've opened this draft pull request primarily to gather feedback from those more skilled than me in drawing 2D elements. I'll be working on this in my spare time, and I'm unsure when it will reach production grade. However, I'm very open to suggestions. If anyone wants to collaborate on the implementation of this diagram, please let me know.

I'm experimenting with rendering using plain d3 in this orphan branch: contextMapDiagramGluedPrototype branch.

Mermaid Devs: I hope this draft PR doesn't create noise. If it does, I can close it and use the related issues to seek feedback.
Additionally, feel free to share/post here any insights you believe could enhance both this contribution and the diagram implementation. Your input is greatly appreciated in beautifying and refining the the diagram implementation :).

I'll continue to provide updates here on the current state of the implementation.

Resolves #1624

📏 Design Decisions

I'm starting to experiment with the prototype design of this diagram using plain d3 in the simplest way possible. My decisions might be subjective, as I'm not particularly skilled in this domain of drawing d3 elements, but I'm learning along the way. I'm completely open to suggestions and improvements in the approach.

📋 Tasks

TODO:

• 📖 have read the contribution guidelines
• 🔖 targeted develop branch
• added diagram example

Big Picture

• 💻 have added necessary unit/e2e tests.
• 📓 have added documentation. Make sure MERMAID_RELEASE_VERSION is used for all new features.
• styles and theme implementation
• other? open to suggestions

Parsing

• Basic recognition of the contextMap scope
• Simple parsing of nodes using the contains prefix keywords
• Simple parsing of links
• Parsing of nodes with multiline contains keyword
• additional features...? (teams...) open to suggestions

Diagram Rendering

• Basic arrangement of nodes, labels, and links
• Drawing simple nodes as ellipses
• Drawing simple links
• Drawing simple labels
• Resolving label collisions
• Resolving mid-link text collisions
• Preventing link intersection with nodes
• other? open to suggestions

[netlify]

❌ Deploy Preview for mermaid-js failed.

Name	Link
🔨 Latest commit	e5e3415
🔍 Latest deploy log	https://app.netlify.com/sites/mermaid-js/deploys/65e3cc6b4cfac5000849ebbd

[AngeloChecked]

As mentioned in the todo, my current focus is on addressing some key pain points:

• Resolving label collisions
• Resolving mid-link text collisions
• Preventing link intersection with nodes

These issues are readily apparent in the demo

I'm completely open to suggestions and advice for enhancing the graph implementation. Please feel free to share here any thoughts or ideas you have in mind!

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 43.41%. Comparing base (2ac4e08) to head (e5e3415).

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #5353      +/-   ##
===========================================
+ Coverage    43.37%   43.41%   +0.04%     
===========================================
  Files           23       23              
  Lines         5130     5134       +4     
  Branches        23       23              
===========================================
+ Hits          2225     2229       +4     
  Misses        2904     2904              
  Partials         1        1              

Flag	Coverage Δ
unit	43.41% <100.00%> (+0.04%)	⬆️

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

Files	Coverage Δ
packages/mermaid/src/defaultConfig.ts	45.84% <100.00%> (+0.79%)	⬆️

[sidharthv96]

Can you please refer to these PRs and use langium instead of jison?
We are migrating away from JISON, and would prefer new diagrams in langium, so that we don't have to do a migration.

• feat: Add packet diagram #4839
• feat: add pie langium parser #4751

[AngeloChecked]

Can you please refer to these PRs and use langium instead of jison? We are migrating away from JISON, and would prefer new diagrams in langium, so that we don't have to do a migration.

• feat: Add packet diagram #4839
• feat: add pie langium parser #4751

Hi! @sidharthv96, thanks a lot for the heads up! I totally missed that earlier.
I'm getting ideas from these PRs now! But I'm worried I might have missed some docs. Did I overlook something? Also, quick question: Should I stick with the 'packages/Mermaid' package or create a new one? Appreciate your help! 🙏

edit: is it acceptable for me to target the 'next' branch at this point?

[Yokozuna59]

But I'm worried I might have missed some docs. Did I overlook something?

Currently, the documentation is kind of outdated, so it may not be relevant in some aspects, especially when creating new diagrams with Langium.

Also, quick question: Should I stick with the 'packages/Mermaid' package or create a new one? Appreciate your help! 🙏

You don't need to create a new package; just create new folders with the name of the diagram in:

• packages/parser/src/language
• packages/mermaid/src/diagrams

Then please refer to the listed PRs above to know what other files should be modified or added.

edit: is it acceptable for me to target the 'next' branch at this point?

Yes, the packages/parser exists only on the next branch for now. So it would be better if you checkouted from it instead of develop. It's fine if you targeted next now, but you may need to resolve conflict to update the current branch.