0.5.0 is the first element quality release, covering every A, B and C element. Components rebuild cleanly when moved or re-populated, keyboard and screen-reader access is fixed across the C components, and several XSS paths are closed. Themes gain a --btn-border-width hook,…
Declarative diagram renderer — wraps Mermaid (v1) with VB token-driven theming, lazy load, and HTML-first authoring via fenced code blocks.
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> renders, so the library never lands in VB's core or pack bundles.
<diagram-wc type="mermaid" caption="Login flow"> <pre><code class="language-mermaid">flowchart LR accTitle: Login flow accDescr: Valid credentials create a session; invalid ones return to the visit step. A[Visit] --> B{Valid creds?} B -->|Yes| C[Session] B -->|No| A </code></pre></diagram-wc>Six common diagram types — flowchart, sequence, ER, journey, gantt, mindmap — share the same authoring shape. Mermaid supports many more in v11.
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.
Mermaid themeVariables | VB token |
|---|---|
primaryColor | --color-primary (falls back to --color-interactive) |
secondaryColor | --color-secondary (falls back to --color-surface-raised) |
tertiaryColor | --color-accent (falls back to --color-primary) |
primaryTextColor, secondaryTextColor, tertiaryTextColor, nodeTextColor, titleColor, actorTextColor, signalColor, signalTextColor, labelTextColor, loopTextColor, noteTextColor | --color-text |
mainBkg, background, actorBkg, edgeLabelBackground | --color-surface |
secondBkg, tertiaryBkg, clusterBkg, noteBkgColor, labelBoxBkgColor | --color-surface-raised |
primaryBorderColor, secondaryBorderColor, tertiaryBorderColor, lineColor, nodeBorder, gridColor, clusterBorder, actorBorder, actorLineColor, labelBoxBorderColor, noteBorderColor | --color-border |
defaultLinkColor | --color-text-muted |
cScale0–cScale11, git0–git7 (mindmap, gitGraph) | Cycle --color-primary, --color-accent, --color-secondary; labels pinned to --color-text |
fontFamily | --font-sans |
fontSize | --font-size-m |
<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):
<markdown-viewer data-auto-mermaid> <script type="text/markdown"> ```mermaid flowchart LR A --> B ``` </script></markdown-viewer>The bridge debounces re-enhancement so live editor previews don't thrash Mermaid:
For manual wiring (no data-auto-mermaid):
// The per-component CDN build of diagram-wc re-exports enhanceMermaidFences// (and registers <diagram-wc> as a side effect).import { enhanceMermaidFences } from 'vanilla-breeze/dist/cdn/components/diagram-wc.js'; document.addEventListener('markdown-viewer:rendered', (e) => { enhanceMermaidFences(e.detail.node);});| Attribute | Purpose |
|---|---|
type | Backend selector. v1 only supports "mermaid"; reserved for future "d2", "kroki". |
src | URL of a diagram source file (.mmd). Takes priority over inline <pre><code> source. Fetched once per URL — moving the element does not refetch. |
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. |
min-height | CSS length reserved for the diagram before render to prevent layout shift. |
| Event | Detail | When |
|---|---|---|
diagram-wc:ready | { svg, type, source } | After a successful render (initial, source change, or theme re-render) |
diagram-wc:error | { error, source, type } | Render or src fetch failed. If nothing has rendered yet, the <pre> source is shown with an error note; otherwise the previous diagram stays visible with the note. |
diagram-wc:source-changed | { source } | The .source setter assigned a new value |
| Property | Type | Description |
|---|---|---|
source | string | Get/set the diagram source. Setting it re-renders; the previous diagram stays on screen until the new one is ready (crossfaded), and stays if the new source has a syntax error. The value survives moving the element. |
svg | string (read-only) | Serialized markup of the current SVG, or "" before the first render. |
const dw = document.querySelector('diagram-wc');dw.source = 'flowchart LR\n A --> B --> C'; // re-renders, fires source-changedconsole.log(dw.svg); // serialized current SVGgraphics-document role, so node and edge labels stay reachable to assistive technology. Nothing is collapsed into a single opaque image.accTitle: in the source. Without one, the caption attribute (the visible <figcaption>) names the diagram. If you give neither, no generic name like "diagram" is invented — add one.accDescr: becomes the SVG description. The diagram source is always kept in a collapsed Diagram source <details> in the figure and linked from the SVG through aria-describedby, so the full text alternative is available to everyone.role="status" note. Animations inside the SVG are disabled under prefers-reduced-motion, and the re-render crossfade is skipped.<diagram-wc caption="Checkout"> <pre><code class="language-mermaid">flowchart LR accTitle: Checkout flow accDescr: Cart leads to payment, then to the confirmation page. Cart --> Pay --> Done </code></pre></diagram-wc>https://cdn.jsdelivr.net/npm/[email protected]/dist/mermaid.esm.min.mjs. Only page script can change it, by setting window.VB_MERMAID_URL before the first diagram renders (for example, to self-host). There is no per-element override: markup — including sanitized markdown, which keeps custom elements and data-* attributes — can't choose which module is imported.script-src (script-src 'self' https://cdn.jsdelivr.net), or self-host Mermaid and point VB_MERMAID_URL at your origin. Mermaid also injects <style> elements into each SVG, so style-src must allow inline styles ('unsafe-inline') for diagrams to be styled.import() can't carry an integrity attribute. The CDN URL is version-pinned; if you need integrity guarantees, self-host the file.securityLevel: 'strict', which escapes labels and disables click handlers in diagram source.<script> window.VB_MERMAID_URL = '/vendor/mermaid/mermaid.esm.min.mjs';</script><script type="module" src="/cdn/vanilla-breeze.js"></script>type="mermaid" attribute reserves the door for substitution backends per VB's wrapped-dependency policy.<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.