feat: add mermaid diagram rendering support by marcoscaceres · Pull Request #5269 · speced/respec

marcoscaceres · 2026-05-05T13:09:16Z

Summary

Adds mermaid diagram rendering for <pre class="mermaid"> blocks inside <figure> elements
Lazy-loads mermaid from a separate build chunk (zero cost if unused)
Flip-card UI: hover reveals toolbar with "Mermaid" label, source toggle (</>), and clipboard copy
Error display: red-themed card with line-numbered source, inline error pointer, and ReSpec pill reporting
Supports i18n (6 languages), dark mode, prefers-reduced-motion, touch/mobile, and print

Details

Theme configurable via respecConfig.mermaid.theme (default: neutral)
Warns if diagram is not wrapped in a <figure> with <figcaption>
Shares clipboard infrastructure with WebIDL/CDDL copy buttons
Uses hyperHTML tagged templates for DOM construction (consistent with codebase)
CSS uses show/hide for prefers-reduced-motion instead of instant 3D flip
Print: hides toolbar and back face, neutralizes 3D transforms

Test plan

11 new integration tests covering rendering, toolbar, source preservation, errors, theme config, linting, highlight exclusion, and runtime injection
Full test suite passes (1085 tests, 0 failures)
Visual verification in Safari: diagrams, flip animation, error display, error source with line highlighting
Build succeeds (pnpm build:w3c)
ESLint + Prettier pass (pre-commit hooks)

Copilot

Pull request overview

This PR introduces first-class Mermaid diagram support to ReSpec by adding a new core/diagrams coordinator that detects pre.mermaid blocks, lazy-loads a Mermaid runtime bundle, renders diagrams to SVG, and provides a flip-card UI to view/copy the underlying source, plus linting/styling/test coverage updates.

Changes:

Added Mermaid rendering pipeline (runtime bundle + coordinator + renderer + runtime flip handler) and associated CSS for interactive diagrams.
Updated highlighting to exclude Mermaid source blocks and added a new linter rule for diagram placement.
Added integration tests and wired the new modules into the W3C profile + build/dependency graph.

Reviewed changes

Copilot reviewed 11 out of 15 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
worker/rollup.config.js	Adds a separate Rollup output to build a dedicated Mermaid runtime bundle.
worker/respec-mermaid.js	Implements the Mermaid runtime wrapper (`initialize`, `render`) and exposes it on `self`.
src/core/diagrams.js	New coordinator that loads Mermaid, renders SVG, builds UI/error views, injects runtime, and emits warnings/errors.
src/core/diagrams/mermaid.js	New “pure renderer” that delegates rendering to the injected runtime.
src/core/diagrams-runtime.js	New exported runtime script that wires up flip-button behavior in exported documents.
src/styles/diagrams.css.js	New styles for diagram flip-card UI, error presentation, reduced-motion, dark mode, and print.
src/core/highlight.js	Excludes `.mermaid` blocks from syntax highlighting selection.
src/core/linter-rules/no-uncaptioned-diagram.js	New linter rule to warn about Mermaid/Jake diagrams outside figures.
profiles/w3c.js	Ensures `core/diagrams` and the new linter rule run in the W3C profile.
tests/spec/core/diagrams-spec.js	Adds integration tests for Mermaid rendering, toolbar presence, errors, config, and highlighting behavior.
package.json	Adds `mermaid` dependency.
pnpm-lock.yaml	Locks Mermaid and transitive dependencies.

Files not reviewed (1)

pnpm-lock.yaml: Language not supported

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 14 out of 18 changed files in this pull request and generated 3 comments.

Files not reviewed (1)

pnpm-lock.yaml: Language not supported

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Adds native Mermaid diagram support to ReSpec. Authors write <pre class="mermaid"> inside a <figure>, and ReSpec renders SVG diagrams with a hover-reveal toolbar and 3D flip card for viewing source code. Features: - Lazy-loads mermaid from a separate build chunk (zero cost if unused) - Hover-reveal toolbar: 'Mermaid' label + flip button + copy button - 3D flip card animation (classic CSS preserve-3d pattern) - Copy button uses shared clipboard.js (matches WebIDL/CDDL style) - Error display: red toolbar, source shown by default (flipped state), line-numbered source with CSS Grid, error line highlighted with emoji + red border, parser pointer shown inline - Accessibility: aria-expanded toggles on flip, aria-label updates, visibility:hidden when header is opacity:0, prefers-reduced-motion uses opacity crossfade instead of 3D flip, error-pulse suppressed - Security: htmlLabels:false eliminates foreignObject attack surface, securityLevel:strict with DOMPurify 3.3.1 sanitization - CSS: all colors via custom properties, dark mode, RTL-safe logical properties, WCAG AAA contrast on header, min(20em, 100%) responsive - Figure integration with automatic numbering - i18n support (en, ja, ko, nl, es, fr) - Touch device support (toolbar always visible when hover:none) - Theme configurable via respecConfig.mermaid.theme (default: neutral) - Linter rule: no-uncaptioned-diagram (checks figure + figcaption) - Promise.withResolvers() in loadScript - Promise.allSettled for parallel diagram rendering

Move the caption check from a standalone linter rule into the diagrams module itself, where it runs before rendering replaces the pre nodes. This fixes the profile ordering issue (linter rules must be last) and replaces Promise.withResolvers() with new Promise() for browser compat.

marcoscaceres · 2026-05-19T02:22:38Z

-export function createCopyButton(headerSelector, title = "Copy to clipboard") {
+export function createCopyButton(
+  headerSelector,
+  title = "Copy to clipboard",


We should probably localize this.

marcoscaceres · 2026-05-19T02:23:24Z

+  }
  button.addEventListener("click", () => {
-    const pre = button.closest("pre");
+    const containerSel = button.dataset.copyContainer;


Nit: avoid abbreviations in variable names.

marcoscaceres · 2026-05-19T02:24:08Z

    document.querySelectorAll(".respec-button-copy-paste").forEach(function(btn) {
      btn.addEventListener("click", function() {
-        var pre = this.closest("pre");
+        var containerSel = this.dataset.copyContainer;


nit: use let or const where possible (applies throughout this PR.

marcoscaceres · 2026-05-19T02:26:12Z

+    document.querySelectorAll(".diagram-flip-btn").forEach(function(btn) {
+      btn.addEventListener("click", function(e) {
+        e.stopPropagation();
+        var container = btn.closest(".diagram-container");


nit: use let or const. Same with other vars.

marcoscaceres · 2026-05-19T02:27:24Z

+      // @ts-ignore
+      if (self.respecMermaid) return true;
+    } catch {
+      // fallback to next URL


Nit: probably console.warn here so we can at least see what's failing.

marcoscaceres · 2026-05-19T02:28:27Z

+    };
+    script.onerror = event => {
+      script.remove();
+      reject(new Error(`Failed to load: ${url}`, { cause: event }));


Should this be event or event.error?

marcoscaceres · 2026-05-19T02:29:24Z

+      </button>
+      ${copyBtn}
+    </header>
+    <div class="diagram-flip">


Nit: can we use more semantic markup here?

marcoscaceres · 2026-05-19T02:33:29Z

@@ -0,0 +1,329 @@
+/* --- Diagrams --- */


Can this file CSS be improved, consolidated, or simplified in any way?

marcoscaceres · 2026-05-19T02:35:14Z

+ * @param {{ id: string }} options
+ * @returns {Promise<{ svg: string } | { error: string }>}
+ */
+async function render(source, { id }) {


Is there a less ugly way to do this? What is here makes sense, but seems like a bit of a hack.

marcoscaceres requested a review from Copilot May 5, 2026 14:04

Copilot started reviewing on behalf of marcoscaceres May 5, 2026 14:05 View session

Copilot AI reviewed May 5, 2026

View reviewed changes

marcoscaceres requested a review from Copilot May 6, 2026 03:16

Copilot started reviewing on behalf of marcoscaceres May 6, 2026 03:17 View session

Copilot AI reviewed May 6, 2026

View reviewed changes

Comment thread src/core/diagrams.js Outdated

Comment thread profiles/w3c.js

Comment thread src/core/linter-rules/no-uncaptioned-diagram.js Outdated

marcoscaceres force-pushed the feat/diagrams branch from 4f54e6a to f60ebad Compare May 6, 2026 03:29

marcoscaceres force-pushed the feat/diagrams branch from f60ebad to 806a3a3 Compare May 6, 2026 03:45

marcoscaceres mentioned this pull request May 14, 2026

Add a diagram showing how things in the model relate to each other w3c-fedid/digital-credentials#66

Open

marcoscaceres commented May 19, 2026

View reviewed changes

Uh oh!

Uh oh!

Conversation

marcoscaceres commented May 5, 2026

Summary

Details

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants