Tesserae - Mermaid

Mermaid

Description

Mermaid diagram source drawn as themed SVG

Mermaid takes diagram source (flowcharts, sequence, class and state diagrams, pie and gantt charts, and more) and draws it as SVG. Use it when the picture describes something, such as a process, a protocol or a schedule, rather than a canvas people arrange by hand; for that, use Diagram.

Drawing is done by Pele, a renderer for Mermaid syntax. It is not the Mermaid library. Colors, fonts and radius come from Tesserae's tokens, so a diagram follows light and dark mode and custom themes without being redrawn.

Pele is a separate file, fetched the first time a diagram is drawn. Until it loads, the component shows the source as text. A mermaid code fence in MarkdownBlock is drawn by the same renderer.

The diagram redraws to fit the width of its container, so keep it in a container whose width does not depend on the diagram. A diagram shrunk to fit can be zoomed and panned with Zoom().

Source is sanitized with DOMPurify before it is inserted. This is on by default; Sanitize(false) turns it off and should be used only for source you wrote. Links(false) and Images(false) remove the diagram's own click hyperlinks and pictures, which is the setting for source you do not trust.

A source that cannot be drawn does not throw. The diagram shows the reason, Error holds it, and OnError(...) is called with it. An empty source draws nothing.

Samples

Flowchart and sequence diagram

mermaid-diagrams-sample.cs

using Transpose.Core;
using Tesserae;
using static Transpose.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            const string flowchart =
@"flowchart LR
  A[Draft] --> B{Review}
  B -- approved --> C([Published])
  B -- changes --> D[Rework]
  D --> A";

            const string sequence =
@"sequenceDiagram
  participant U as User
  participant A as App
  participant S as Server
  U->>A: Click save
  A->>S: POST /documents
  S-->>A: 201 Created
  A-->>U: Saved";

            var component = VStack().W(640.px()).Gap(16.px()).Children(
                Card(Mermaid(flowchart)),
                Card(Mermaid(sequence)));

            document.body.style.overflow = "hidden";
            MountCenteredToBody(component);
        }
    }
}

Live editing

Assign Source to redraw in place. The error line is filled from OnError(...); the toggle switches Sanitize(...).

mermaid-live-sample.cs

using Transpose.Core;
using Tesserae;
using static Transpose.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            const string startingSource =
@"flowchart TD
  A[Edit the source] --> B{Valid?}
  B -- yes --> C[The diagram updates]
  B -- no --> D[The error is shown]";

            var live      = Mermaid(startingSource);
            var liveError = TextBlock("No error.").Secondary();
            var sanitize  = Toggle("Sanitize").Checked();

            live.OnError(e => liveError.Text = "Error: " + e);
            sanitize.OnChange((t, _) => live.Sanitize(t.IsChecked));

            var editor = TextArea(startingSource).WS().H(180).OnInput((ta, _) =>
            {
                liveError.Text = "No error.";
                live.Source    = ta.Text;
            });

            var component = VStack().W(640.px()).Gap(12.px()).Children(
                editor,
                sanitize,
                liveError,
                Card(live));

            document.body.style.overflow = "hidden";
            MountCenteredToBody(component);
        }
    }
}

Untrusted source

The first diagram keeps its click link. The second has Links(false) and Images(false), so the link is dropped.

mermaid-untrusted-sample.cs

using Transpose.Core;
using Tesserae;
using static Transpose.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            const string source =
@"flowchart LR
  A[""<img src=x onerror=alert(1)>""] --> B[Diagram text is escaped]
  click B ""https://example.com/tracker"" ""a link""";

            var component = VStack().W(640.px()).Gap(16.px()).Children(
                TextBlock("Default").SemiBold(),
                Card(Mermaid(source)),
                TextBlock("Links(false).Images(false)").SemiBold(),
                Card(Mermaid(source).Links(false).Images(false)));

            document.body.style.overflow = "hidden";
            MountCenteredToBody(component);
        }
    }
}

API reference

class

Mermaid

public class Mermaid : ComponentBase<Mermaid, HTMLElement>

Draws Mermaid diagram source as SVG, with Pele (not the Mermaid library), themed from Tesserae's tokens so it follows light/dark mode and custom themes without being redrawn. The same renderer draws a ```mermaid fence in MarkdownBlock.

Remarks

Pele is fetched the first time a diagram is drawn; until then the source is shown as text. Changing Source redraws in place, and a source that cannot be drawn is reported through Error and OnError (and shown in the diagram's place) rather than thrown.

Namespace: Tesserae
Inheritance: ComponentBase<Mermaid, HTMLElement> → Mermaid

Constructors

Name	Description
Mermaid	Initializes a new instance of the `Mermaid` class.

Constructor

Mermaid

public Mermaid(string source = "", bool sanitize = true)

Initializes a new instance of the Mermaid class.

Parameters

source: The Mermaid source, e.g. flowchart LR\n A --> B.
sanitize: Whether the SVG is run through DOMPurify before it is inserted, on top of Pele's own escaping of diagram text. On by default; turn it off only for source you wrote yourself.

Properties

Name	Description
Source	Gets or sets the Mermaid source. Setting it redraws the diagram.
IsSanitized	Gets whether the diagram's SVG is sanitized before it is inserted.
Error	Gets why the current source could not be drawn, or `null` when it was (or has not been tried yet).

Property

Mermaid.Source

public string Source { get ; set ; }

Gets or sets the Mermaid source. Setting it redraws the diagram.

Property

Mermaid.IsSanitized

public bool IsSanitized

Gets whether the diagram's SVG is sanitized before it is inserted.

Property

Mermaid.Error

public string Error

Gets why the current source could not be drawn, or null when it was (or has not been tried yet).

Methods

Name	Description
Sanitize	Sets whether the SVG is run through DOMPurify before it is inserted (on by default) and redraws.
Links	Sets whether the diagram's own hyperlinks (`click` statements) are kept (on by default) and redraws. Turn them off for source you do not trust to link anywhere.
Images	Sets whether the diagram's own images are kept (on by default) and redraws. An image is a request to whatever server hosts it, so turn them off for source you do not trust.
Zoom	Sets whether a diagram that has been shrunk to fit its container can be zoomed and panned (on by default) and redraws.
OnError	Registers a callback for when the source cannot be drawn (a syntax error, the library failing to load). It is called with the reason, once per failed attempt.
Render	Renders the component.

Method

Mermaid.Sanitize

public Mermaid Sanitize(bool sanitize = true)

Sets whether the SVG is run through DOMPurify before it is inserted (on by default) and redraws.

Method

Mermaid.Links

public Mermaid Links(bool allow = true)

Sets whether the diagram's own hyperlinks (click statements) are kept (on by default) and redraws. Turn them off for source you do not trust to link anywhere.

Method

Mermaid.Images

public Mermaid Images(bool allow = true)

Sets whether the diagram's own images are kept (on by default) and redraws. An image is a request to whatever server hosts it, so turn them off for source you do not trust.

Method

Mermaid.Zoom

public Mermaid Zoom(bool enabled = true)

Sets whether a diagram that has been shrunk to fit its container can be zoomed and panned (on by default) and redraws.

Method

Mermaid.OnError

public Mermaid OnError(Action<string> callback)

Registers a callback for when the source cannot be drawn (a syntax error, the library failing to load). It is called with the reason, once per failed attempt.

Method

Mermaid.Render

public override HTMLElement Render()

Renders the component.

Mermaid

Description

Samples

Flowchart and sequence diagram

Live editing

Untrusted source

API reference

Constructors

Mermaid

Parameters

Properties

Mermaid.Source

Mermaid.IsSanitized

Mermaid.Error

Methods

Mermaid.Sanitize

Mermaid.Links

Mermaid.Images

Mermaid.Zoom

Mermaid.OnError

Mermaid.Render

See also