Add mermaid support

[ericwindmill]

Description of what this PR is changing or adding, and why:

Adds Mermaid diagram support. "Yeehaw" for code and version control instead of saving diagrams as images.

Presubmit checklist

• If you are unwilling, or unable, to sign the CLA, even for a tiny, one-word PR, please file an issue instead of a PR.
• If this PR is not meant to land until a future stable release, mark it as draft with an explanation.
• This PR follows the Google Developer Documentation Style Guidelines—for example, it doesn't use i.e. or e.g., and it avoids I and we (first-person pronouns).
• This PR uses semantic line breaks
  of 80 characters or fewer.

[ericwindmill]

I added this for demo purposes. It needs to be removed before this PR lands.

[gemini-code-assist]

Code Review

This pull request adds support for rendering Mermaid diagrams from Markdown code blocks, introducing a custom Markdown block syntax, a node processor, and a client-side MermaidViewer component that dynamically loads the Mermaid library and handles theme updates. Feedback on the implementation highlights a security risk with using securityLevel: 'loose' (XSS), a bug where the diagram does not re-render when its content changes due to a missing didUpdateComponent implementation, an optimization opportunity to cache the imported module, and a potential CSP violation caused by using eval for dynamic imports.

[ericwindmill]

I'm pretty far out of my element here using js interop and Jaspr, two things I'm only vaguely familiar with. I'd appreciate a thorough review @parlough !

[flutter-website-bot]

Staged preview of the updated docs.flutter.dev site (updated for commit bb978e2):

https://flutter-docs-prod--docs-pr13741-add-mermaid-support-ve3ntyr2.web.app

[flutter-website-bot]

Staged preview of the updated flutter.dev site (updated for commit 575f9eb):

https://flutter-dev-230821--www-pr13741-add-mermaid-support-fzptfisf.web.app

[schultek]

As an alternative approach instead of using mermaid.js, we could use https://github.com/orestesgaolin/mermaid/tree/main/packages/mermaid_core to render the diagrams to SVGs at serve/build time.

This is the demo https://roszkowski.dev/mermaid/

Seems like this is not published yet, but if we were to use it maybe we can convince @orestesgaolin to publish it :)

[ericwindmill]

As an alternative approach instead of using mermaid.js, we could use https://github.com/orestesgaolin/mermaid/tree/main/packages/mermaid_core to render the diagrams to SVGs at serve/build time.

This is the demo https://roszkowski.dev/mermaid/

Seems like this is not published yet, but if we were to use it maybe we can convince @orestesgaolin to publish it :)

I would much rather use this, I'll try it out

[orestesgaolin]

Would you like me to publish mermaid to pub.dev? For now I only published katex https://pub.dev/packages/katex

With mermaid I found that it sometimes does not well represent elk layouts and there are slight differences in rendering

[ericwindmill]

Would you like me to publish mermaid to pub.dev? For now I only published katex https://pub.dev/packages/katex

With mermaid I found that it sometimes does not well represent elk layouts and there are slight differences in rendering

I'm not concerned with those small rendering differences. I have noticed one bug, the arrow label renders in the wrong spot when the flowchart is LR oriented. It works correctly when the orientation is TD

If you plan on maintaining this library, we'd likely want to use it over the JSInterop solution (and we can find a way to contribute and help out). But if you don't plan on maintaining, thats okay, no pressure.

[parlough]

Thanks for exploring this @ericwindmill! It's exciting. Looks pretty good already, just some questions and comments, primarily about if we can move the rendering to the build?

[parlough]

Thanks for making those updates @ericwindmill!

Seems we need some upstream fixes, but I'm fine with landing this and iterating upstream and here.

Seemingly upstream issues:

1. SVG part IDs for aren't unique or namespaced for each diagram, causing overlap.
2. Seems there's no consistent classes for configuring global styling.
3. In the light mode version, there's a white background generated that visually conflicts with the background of the container.

[parlough]

Consider trying to update to 90c39dd66b5e798c12dd77ec8b3fba4d583f0a05. It seems it might include a fix to an issue you mentioned.

[ericwindmill]

That commit doesn't seem to be ready, it has broken dependencies internally, I'm going to file an issue