diagram-wc

Declarative diagram renderer — wraps Mermaid (v1) with VB token-driven theming, lazy load, and HTML-first authoring via fenced code blocks.

Overview

A web component that progressively enhances a fenced Mermaid code block into a rendered SVG figure. Without JavaScript the page shows the source as a readable code block; with JavaScript the source is replaced by an SVG <figure>.

Mermaid is loaded from a CDN URL via dynamic import() only when a <diagram-wc> reaches setup, so the library never lands in VB's core or pack bundles.

Diagram type gallery

Six common diagram types — flowchart, sequence, ER, journey, gantt, mindmap — share the same authoring shape. Mermaid supports many more in v11.

Theme integration

VB design tokens drive Mermaid's appearance. The component reads tokens at render time via getComputedStyle, maps them onto Mermaid's themeVariables (see src/lib/diagram-tokens.js), and re-renders when the global vb:theme-change event fires. No per-instance config is required.

Token map

Mermaid `themeVariables`	VB token
`primaryColor`, `primaryBorderColor`	`--color-primary`
`primaryTextColor`, `titleColor`, `actorTextColor`, `noteTextColor`	`--color-text`
`secondaryColor`, `secondBkg`	`--color-secondary`
`tertiaryColor`, `tertiaryBkg`	`--color-accent`
`mainBkg`, `background`, `actorBkg`, `edgeLabelBackground`	`--color-surface`
`lineColor`, `nodeBorder`, `gridColor`, `defaultLinkColor`, `actorBorder`, `noteBorderColor`	`--color-border`
`clusterBkg`, `noteBkgColor`, `labelBoxBkgColor`	`--color-surface-raised`
`fontFamily`	`--font-sans`
`fontSize`	`--font-size-md`

Markdown integration

<markdown-viewer> emits standard <pre><code class="language-mermaid"> for Mermaid fences. To upgrade those automatically, set data-auto-mermaid on the viewer (or on a <markdown-editor> wrapping it):

The bridge debounces re-enhancement so live editor previews don't thrash Mermaid:

For manual wiring (no data-auto-mermaid):

Attributes

Attribute	Purpose
`type`	Backend selector. v1 only supports `"mermaid"`; reserved for future `"d2"`, `"kroki"`.
`src`	URL of a diagram source file. Inline `<pre><code>` takes priority if absent.
`caption`	Rendered as `<figcaption>` below the SVG.
`loading="lazy"`	Defers render until the element scrolls into view.
`data-theme-base`	Mermaid base theme (`base\|default\|dark\|forest\|neutral`). Default `"base"` so VB tokens win.
`data-mermaid-src`	Override the URL Mermaid loads from (per-element). The default is jsDelivr; `window.VB_MERMAID_URL` overrides globally.
`min-height`	CSS length reserved for the diagram before render to prevent layout shift.

Events

Event	Detail	When
`diagram-wc:ready`	`{ svg, type, source }`	After successful render
`diagram-wc:error`	`{ error, source, type }`	Render failed; the `<pre>` fallback is restored
`diagram-wc:source-changed`	`{ source }`	The `.source` setter was used

JavaScript API

Notes

Mermaid runs with securityLevel: 'strict' by default. Author content is escaped.
This is the first VB component to wrap an external runtime library. The library is loaded from a CDN URL at runtime — never bundled. The type="mermaid" attribute reserves the door for substitution backends per VB's wrapped-dependency policy.
Bundle audit: enabling <diagram-wc> in the ux-planning pack adds < 5 KB gzip; Mermaid (~360 KB gzip) is fetched from jsDelivr only on pages that use a diagram.