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 ready!

Name	Link
🔨 Latest commit	cae456f
🔍 Latest deploy log	https://app.netlify.com/sites/mermaid-js/deploys/669bc91761a00b0008ac646d
😎 Deploy Preview	https://deploy-preview-5353--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 site configuration.

[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

Attention: Patch coverage is 0.60753% with 818 lines in your changes missing coverage. Please review.

Project coverage is 5.75%. Comparing base (3c3d28d) to head (cae456f).

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #5353      +/-   ##
==========================================
- Coverage     5.85%   5.75%   -0.11%     
==========================================
  Files          274     283       +9     
  Lines        41112   41922     +810     
  Branches       488     522      +34     
==========================================
+ Hits          2408    2413       +5     
- Misses       38704   39509     +805     

Flag	Coverage Δ
unit	5.75% <0.60%> (-0.11%)	⬇️

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

Files	Coverage Δ
packages/mermaid/src/defaultConfig.ts	47.33% <100.00%> (+0.95%)	⬆️
.build/jsonSchema.ts	0.00% <0.00%> (ø)
packages/parser/src/language/contextMap/index.ts	0.00% <0.00%> (ø)
...s/mermaid/src/diagram-api/diagram-orchestration.ts	0.00% <0.00%> (ø)
packages/parser/src/language/index.ts	0.00% <0.00%> (ø)
...ges/parser/src/language/contextMap/tokenBuilder.ts	0.00% <0.00%> (ø)
packages/parser/src/parse.ts	0.00% <0.00%> (ø)
...maid/src/diagrams/context-map/contextMapDiagram.ts	0.00% <0.00%> (ø)
...aid/src/diagrams/context-map/contextMapDetector.ts	0.00% <0.00%> (ø)
...s/mermaid/src/diagrams/context-map/contextMapDb.ts	0.00% <0.00%> (ø)
... and 5 more

... and 1 file with indirect coverage changes

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

[AngeloChecked]

Hi @nirname

Thank you for the feedback! I'll update the naming convention.

Regarding Jison, I'm currently working on the ContextMap Langium parser here, so the Jison version will be changed.

PS: yep, I initially called it 'mini-context-map' because it might not fully implement the language reference. However, I later removed the prefix as it didn't seem relevant.

[benr77]

We are really interested in this feature. Has there been any progress recently? Happy to help test or otherwise assist. Thanks.

[AngeloChecked]

We are really interested in this feature. Has there been any progress recently? Happy to help test or otherwise assist. Thanks.

Hi @benr77, sure!

I'm currently finishing the integration of the previous work with the new Langium parser. In a few days, I'll update this pull request with the master branch and resume work on the drawing part, which still lacks many features.

If you'd like, we can have a discussion on the Mermaid Discord once I wrap up my current task. Since I'm working on this in my spare time, my schedule isn't precise. I'm not an expert in this domain, so any insights or experience you can share would be super valuable. I'm also the first interested in making this kind of chart available on Mermaid, but consider that I'm treating it as an ongoing side project.

[benr77]

Hey @AngeloChecked thanks for the update. I am happy hear that this is still moving forward, and I completely understand it's a voluntary side project (I have several myself!).

Ping me a message when things are at a good stage to test, and I'll spend some time working with it and happy to report back with issues. I am no expert at context mapping or Mermaid but I am involved in a project whereby we are going to need this kind of diagramming a lot over the coming months so I'll have plenty of opportunities to test it.

Thanks!

[argos-ci]

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

Build	Status	Details	Updated (UTC)
default (Inspect)	✅ No changes detected	-	Jul 20, 2024, 2:37 PM

[AngeloChecked]

Hi @nirname, @sidharthv96, @Yokozuna59

I've force-pushed the entire branch with the new Langium parser implementation (and solved some linting).

I'm very open to any feedback, corrections, or improvements (config, naming, testing...).

Now, I'm shifting my focus back to the drawing part.