feat: Add support for mermaid.js rendering

[juliushaertl]

📝 Summary

Fixes #163

Implements mermaid js support for code blocks. By default the preview mode is used, unless the code block is empty or has faulty syntax. Users can then switch between preview/split and code mode. This also provides a way to switch the language of code blocks in the same location.

🖼️ Screenshots

Mermaid code block

Regular code bock

🚧 TODO

• There seems to be no syntax highlighting for mermaid on highlight.js -> no highlight
• Design: Figure out language selector
• Design: Check mode switcher and what the default should be
• Design: Maybe we shall have some border or boxing around the element
• BUG: Preview should probably be not contenteditable (noticable when selecting all text with Ctrl-A)
• BUG: Make sure to only render the preview in read only mode (Feature: Add support for mermaid diagrams collectives#284)
• Make preview the default and call it Diagram
• Use NcActions Edit button -> floating on the top right, move language selector to the menu

Follow up tickets

• Custom mermaid theme
• Ctrl-A in code block should probably only select the code block
• Clear preview if code block gets emptied
• Cypress tests

🏁 Checklist

• Code is properly formatted (npm run lint / npm run stylelint / composer run cs:check)
• Sign-off message is added to all commits
• Tests (unit, integration and/or end-to-end) passing and the changes are covered with tests
• Documentation (README or documentation) has been updated or is not required

[cypress]

2 flaky tests on run #11528 ↗︎

0

149

2

0

2

Details:

feat: Add support for mermaid.js rendering
Project: Text	Commit: a1b711687c
Status: Passed	Duration: 07:41 💡
Started: Aug 7, 2023 12:56 PM	Ended: Aug 7, 2023 1:04 PM

  nodes/FrontMatter.spec.js • 1 flaky test

View Output Video

Test		Artifacts
Front matter support > Add front matter		Output Screenshots

  api/SyncServiceProvider.spec.js • 1 flaky test

View Output Video

Test		Artifacts
Sync service provider > recovers from a dropped message		Output Screenshots

_{This comment has been generated by cypress-bot as a result of this project's GitHub integration settings.}

[juliushaertl]

@nextcloud/designers Do you have any suggestions to make the UI a bit nicer here?

[jancborchardt]

Looks nice! Some enhancements for the diagram style:

• It is purple now, could instead use the primary color: primary-light for bg, primary for the border
• The text in the boxes doesn’t look vertically aligned but a bit too far up / too much bottom padding
• Boxes could use border-radius (3px default), might look nicer and Nextcloud-y
• The Yes/No boxes in the example could use some more padding
• If it makes sense, the Yes/No text can also be bold? Or is the other stuff more important? (Either way maybe makes sense to bold one of the types)

[nimishavijay]

Super cool! :) 🎉 It looks great! Agreed with Jan's visual changes, and I'm also wondering if we can just change this to "Insert flowchart" as a separate formatting option and link to the mermaid language documentation for help with the syntax? so not have it as a part of the code block option. It can insert an example flowchart so people have something to start with. What do you think? :)

[juliushaertl]

Looks nice! Some enhancements for the diagram style:

I'll see how far we can influence the diagram rendering, but this might be more complex if we need to provide a custom theme: https://mermaid.js.org/config/theming.html

Would you consider this a blocker or just nice to have?

Super cool! :) 🎉 It looks great! I'm wondering if we can just change this to "Insert flowchart" as a separate formatting option and link to the mermaid language documentation for help with the syntax? :) so not have it as a part of the code block option, but a separate option :)

Mermaid supports all kinds of charts, but we could add a separate option "Insert diagram" with #4587 though I'd keep this as a follow up then. For the syntax documentation that seems like a nice suggestion.

[nimishavijay]

That works! Adding a separate option would be great to increase visibility for such a cool feature.
Also one other small change: instead of "Side by side" we could change the wording to "Both", as on mobile the horizontal space would be quite less and we should show them below one another.

[juliushaertl]

Theming is more complex as we'd need to set matching colors for all possible diagram formats and ideally also adapt them to the theme color from Nextcloud, so nothing we can easily achieve within the planned timeline.

[mejo-]

Looks really nice and I'm looking forward to use this myself 😊

Regarding the menu icon, I wonder whether it would be better to have a static one to avoid confusion and mark the selected view (Source code, Both or Diagram) as highlighted in the menu.

Personally I find it confusing that clicking on an eye icon allows me to change to source code view and the other way round.

We could use the Pencil icon (that we use for editing buttons) to open the menu, what do you think?

[mejo-]

Also, how about secondary button style for the menu button? Right now it looks a bit lost in the whitespace 😬

Or we set the --color-background-dark for the view mode of mermaid diagrams as well?

[juliushaertl]

The edit button seems more fitting indeed, but would probably not fit to indicate switching from edit to diagram view or in the regular code block to change the language.

Will think a bit about that, further input still welcome of course :)

[juliushaertl]

My suggestion would be:

• In diagram view mode -> show the edit icon
• In split mode -> show the split icon
• In code mode -> show the view icon
• In the regular code block -> show the curly braces icon as it probably fits the language setting best

[mejo-]

Just minor comments, otherwise looks good 😊

I wonder whether we should backport the setEditable() and defaultLanguage: 'plaintext' fixes to stable26 and stable27.

[juliushaertl]

/compile

Postponed

[mejo-]

/backport b9ea43f,62f5d3e846b604a9e7576f5b9eae85bdd82fba1f,6a8b01fa57d9ba253607257262d8c56cd7ee21ec,946ca9bcba925b9bca8809538a069d67c2303d73 to stable27

[backportbot-nextcloud]

The backport to stable27 failed. Please do this backport manually.

# Switch to the target branch and update it
git checkout stable27
git pull origin stable27

# Create the new backport branch
git checkout -b fix/foo-stable27

# Cherry pick the change from the commit sha1 of the change against the default branch
# This might cause conflicts. Resolve them.
git cherry-pick abc123

# Push the cherry pick commit to the remote repository and open a pull request
git push origin fix/foo-stable27

More info at https://docs.nextcloud.com/server/latest/developer_manual/getting_started/development_process.html#manual-backport