Support mermaid.js diagrams

[emmby]

Github supports mermaid state diagrams, like:

---
title: Simple sample
---
stateDiagram-v2
    [*] --> Still
    Still --> [*]

    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]

It would be pretty cool if StateSmith was able to support mermaid as an additional input language. That way, you wouldn't actually need any additional tools like drawio, the drawio plugin, etc. You could diagram directly in markdown files and be able to see them in any editor that supports mermaid

You could also do things like point the cli to any mermaid SM on the web and generate a SM from urls.

[adamfk]

That's pretty cool. I didn't realize until now that those were dynamic images (I thought they were just screen caps). Very cool. vscode has a good mermaid markdown extension too.

I took a quick look at the mermaid syntax and it looks to be largely compatible with plantuml.

The biggest difference that I saw was the document title. Plantuml uses @startuml: https://github.com/StateSmith/StateSmith/blob/main/antlr/PlantUML.g4#L230-L237

Also the styling looks to be different at first glance, but styling can come later for mermaid.

---

Actually, looking further I don't think mermaid is fully featured enough yet. A big missing feature is being able to add non-transition behaviors like shown below (plantuml):

source

Is there a way to do that in mermaid? I didn't see away. It looks like states can only have titles or nested states?

[emmby]

It looks like you can:

stateDiagram
    Still: Still
    Still: enter / doTheThing()

    [*] --> Still
    Still --> [*]

    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]

I'm a little unclear on the quoting behavior and how to add curly braces, but otherwise seems to work.

Reference: https://github.com/mermaid-js/mermaid/blob/4f642428de5790d16604c094cce0314526235587/packages/mermaid/src/diagrams/state/stateDiagram.spec.js#L240C1-L255C1

[adamfk]

Nice! That gets us closer.

Maybe we could open an issue with mermaid to support more plantuml syntax? I love how fast the mermaid rendering is.

I think it is still missing the ability to have behaviors inside a parent state. Or at least I couldn't get it working after messing around for a bit.

https://www.plantuml.com/plantuml/duml/bP11IyD048NlyolUCH5Awqqib6ADMj1K6czjM58pe93TXDrPFPJ-TpUsXYGtZpjyxzjvitHIMF6wmfqNgKschrTDGxIxoZ5P8DsygTTjacN9FGLIk3_1aJ1utuADiCKKnxq1B3iMLVAXzkQTbNngjb4ytviJdUYYwwl-gm5gBuqNnLyX43K1T6Sz0K_9yzWqn3-uAZlwjsvPVvlGURL97zRRbtNwg5e9OJpfoCiVksutxQ8O2zpCPdbRyQ_GP7Z9Db94SOufB5TSE3wl5C9pQhb-hfV10JdHaatfTVK3

All that said, if you're keen to support mermaid syntax now with its current diagramming capabilities, I can help you. It's already more than good enough for simple non hierarchical state machines.

[emmby]

Adding some mermaid documentation about actions/guards/triggers: https://github.com/mermaid-js/mermaid/pull/5512

[emmby]

Hmm, true. This code display behaviors under First but doesn't:

stateDiagram-v2
    First: First
    First: enter [guard] / action()
    [*] --> First
    state First {
        second: Second
        second: enter [guard] / action()
        [*] --> second
        second --> [*]
    }

Filed as https://github.com/mermaid-js/mermaid/issues/5522. But agree it's probably not a blocker for many/most FSMs.

[adamfk]

thanks!