Feature/event modeling diagram

[lgazo]

📑 Summary

This PR implements Event Modeling Diagram.

Event Modeling is a method of describing systems using an example of how information has changed within them over time.

There was an attempt within #5860 ticket, but I have chosen different approach where writing the text description must be rapid and compact in the first place.

Resolves #5860

📏 Design Decisions

EM Diagram uses a specific layout that is a combination of timeline / sequence diagram, swimlanes and limited amount of Entity types. Relations among Entities are inferred as much as possible so a Designer focuses primarily on capturing the requirements.

I have studied and looked for existing layout algorithms (e.g. ELK, GraphViz,...) but they were not sufficient for this case so far.

The grammar uses Langium. Initially the grammar was developed separately and then brought to Mermaid, where after a few iteration it reached its completeness. The grammar contains more elements than what is currently covered by the renderer.

The renderer and the underlying DB uses Decider pattern to build required state data object out of the AST. In the first iteration it uses the provided D3 renderer but other types of outputs might be possible in the future. The properties of the final diagram are hardcoded at the moment. Colours follow the convention introduced by a standard EM diagram.

No additional external libraries were used.

I assume that further improvements to the implementation might be possible as I have just initial familiarity with Mermaid project and its available components.

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

[lgazo]

Hi @pbrolin47, I have hopefully fixed the issues being raised. Additionally I've merged current develop. The PR checks are mostly ok, but fail on "argos" and E2E. It does not seem related to my changes and I'm not experienced in those parts of the project. Can you advise how to fix it please? Is there something else to do for the final acceptance? Thanks.

[pbrolin47]

Hi @lgazo,
Thanks for addressing the raised issues. I'll start looking at the changes and get back to you.

[pbrolin47]

Hi @lgazo
I agree the failing E2e, argos in this PR is not related to your changes. I rerun e2e (5) to get a clean run, but unfortunately we hit a screen-shot limitation on the license we are on. I raised the question to @ashishjain0512 and we addressing the problem

[pbrolin47]

Hi @lgazo
All the blocking issues and several important issues are resolved now which is great!! A few things need attention:

🟡 [important] — Theme variables not defined in built-in themes

db.ts calculateEntityVisualProps() and renderer.ts now read from themeVariables.emCommandFill, themeVariables.emEventFill, etc. — but these variables are never defined in any of the 5 built-in
Mermaid theme files (default, dark, forest, neutral, base).

The result: the ?? 'hardcoded' fallbacks are always used. Switching to theme: 'dark' will not give the event modeling diagram dark-appropriate colors. Users can override via themeVariables config,
but the automatic theme integration doesn't work.

Fix: Add the EM color variables to each theme file (or at minimum the default and dark themes), following the pattern used by gitGraph, pie, and radar.

🟡 [important] — wrapLabel() still applied to assembled HTML string

db.ts end of calculateTextProps() still applies wrapLabel() to the fully-assembled HTML content:

content = <b>${name}</b>;
// ... content += <code ...>${toHtml}</code>;
content = wrapLabel(content, diagramProps.textMaxWidth, wrapLabelConfig); // ← processes HTML as text

wrapLabel() splits on spaces without HTML awareness — it can split Hello and World into separate "words". With the user inputs now sanitized, this is no longer an XSS risk, but it can produce
malformed HTML and incorrect layout for multi-word names.

Fix: Apply wrapLabel() to the plain-text name and toHtml before wrapping them in HTML tags, then build the HTML string from the already-wrapped text.

🟡 [important] — Relation stroke color still hardcoded in db.ts

db.ts evolveRelationPositioned() sets:
visual: { fill: 'none', stroke: '#000' }

The renderer uses themeVariables.emArrowhead for the arrowhead polygon fill, but the path stroke is hardcoded in the DB. This should either be moved to the renderer (consistent with how the arrowhead
reads themeVariables) or themeVariables.emRelationStroke should be used.

🟡 [important] — Merge conflict in PR
Please resolve the conflicts in the PR

[lgazo]

Hi @pbrolin47, all items should be fixed. I've merged it with the latest develop as well. There is one issue in e2e but that seems to be related to architecture diagram.

[pbrolin47]

@lgazo. Final comments addressed. Thanks for your effort!

[mermaid-bot]

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

[adymitruk]

Please follow the event->state view->processor->command->event pattern for any automation

[adymitruk]

Also, state views can only attach to events from a single swimlane. This is because it's clear where the implementation for the state view will exist.

[diegosasw]

Also, state views can only attach to events from a single swimlane. This is because it's clear where the implementation for the state view will exist.

@adymitruk this raised a question for me.

I often model read models as projections across multiple streams, and I’ve been representing those as state views attached to events from multiple swimlanes.

How do you approach cases where a read model combines data from different aggregates? It makes me think my assumption that state views map directly to read models might not be quite right.

I can see the value of keeping a state view within a single swimlane if the goal is to show the information needed to make a decision (either automated or in a UI), independent of how it’s implemented. But since you mentioned implementation as the reason, I’d be interested in understanding that perspective a bit more.

[adymitruk]

@diegosasw you first translate them into a single swimlane where the state view will live.