@roadlittledawn/docs-design-system-react 0.13.0 → 0.15.0

package/USAGE.md

@@ -2,6 +2,8 @@
 
 Hand-maintained reference for AI tools and human contributors. Covers when to use each component, when not to, how to choose between similar components, and full prop coverage.
 
+> **Requires React 19** (`react` and `react-dom` ≥ 19.0.0).
+
 ```
 // CLAUDE.md or equivalent:
 // Component usage guide: packages/react/USAGE.md (or https://raw.githubusercontent.com/roadlittledawn/docs-design-system/main/packages/react/USAGE.md)
@@ -1710,3 +1712,51 @@ const closeIconSvg = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor"
 <Icon svg={StarIcon} size={16} />                   {/* hidden from screen readers */}
 <Icon svg={StarIcon} size={16} aria-label="Favorite" /> {/* announced as "Favorite" */}
 ```
+
+---
+
+## MermaidDiagram
+
+Renders Mermaid diagram syntax as SVG. Automatically switches between light and dark Mermaid themes based on the design system's dark mode state (`.dds-dark`, `data-dds-theme`, or `prefers-color-scheme`). Multiple instances are safely handled with serialized rendering.
+
+> **Security note:** Mermaid diagrams are rendered to SVG and injected into the DOM via `dangerouslySetInnerHTML`. Only pass trusted, non–user-controlled `chart` strings (similar to the raw SVG guidance in `Icon`); do not render untrusted or arbitrary user input.
+
+### Import
+
+```tsx
+import { MermaidDiagram } from '@roadlittledawn/docs-design-system-react';
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `chart` | `string` | — | Mermaid diagram definition string |
+| `className` | `string` | `""` | Additional CSS classes |
+
+### Examples
+
+#### Flowchart
+
+```tsx
+<MermaidDiagram chart={`graph TD
+    A[Start] --> B{Decision}
+    B -->|Yes| C[Do something]
+    B -->|No| D[Do something else]
+    C --> E[End]
+    D --> E`} />
+```
+
+#### Gantt Chart
+
+```tsx
+<MermaidDiagram chart={`gantt
+    title Project Schedule
+    dateFormat  YYYY-MM-DD
+    section Planning
+    Requirements :a1, 2024-01-01, 14d
+    Design       :a2, after a1, 10d
+    section Development
+    Implementation :b1, after a2, 21d
+    Testing        :b2, after b1, 14d`} />
+```

package/dist/components/CollapserGroup.js

@@ -49,7 +49,7 @@ export var CollapserGroup = function (_a) {
                 return child;
             // Only inject props if child is a Collapser component
             if (((_a = child.type) === null || _a === void 0 ? void 0 : _a.displayName) === 'Collapser') {
-                return cloneElement(child, __assign(__assign(__assign({}, child.props), { open: openIndexes.includes(index), onToggle: function () { return handleToggle(index); } }), (numbered ? { stepNumber: index + 1 } : {})));
+                return cloneElement(child, __assign({ open: openIndexes.includes(index), onToggle: function () { return handleToggle(index); } }, (numbered ? { stepNumber: index + 1 } : {})));
             }
             return child;
         }) }));

package/dist/components/MermaidDiagram.d.ts

@@ -0,0 +1,7 @@
+export interface MermaidDiagramProps {
+    /** Mermaid diagram definition string */
+    chart: string;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function MermaidDiagram({ chart, className }: MermaidDiagramProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/MermaidDiagram.js

@@ -0,0 +1,186 @@
+'use client';
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useId, useRef, useState, useCallback } from "react";
+import mermaid from "mermaid";
+// Initialize mermaid once at module scope with base configuration
+mermaid.initialize({
+    startOnLoad: false,
+    securityLevel: "strict",
+});
+// Rendering queue to serialize mermaid operations and prevent global config conflicts
+var renderQueue = Promise.resolve();
+function renderMermaidWithTheme(id, chart, dark) {
+    return __awaiter(this, void 0, void 0, function () {
+        var resolveResult, rejectResult, resultPromise;
+        var _this = this;
+        return __generator(this, function (_a) {
+            resultPromise = new Promise(function (resolve, reject) {
+                resolveResult = resolve;
+                rejectResult = reject;
+            });
+            renderQueue = renderQueue.then(function () { return __awaiter(_this, void 0, void 0, function () {
+                var result, error_1;
+                return __generator(this, function (_a) {
+                    switch (_a.label) {
+                        case 0:
+                            _a.trys.push([0, 2, , 3]);
+                            // Configure theme for this specific render
+                            mermaid.initialize({
+                                startOnLoad: false,
+                                theme: dark ? "dark" : "default",
+                                securityLevel: "strict",
+                            });
+                            return [4 /*yield*/, mermaid.render(id, chart)];
+                        case 1:
+                            result = _a.sent();
+                            resolveResult(result);
+                            return [3 /*break*/, 3];
+                        case 2:
+                            error_1 = _a.sent();
+                            rejectResult(error_1);
+                            return [3 /*break*/, 3];
+                        case 3: return [2 /*return*/];
+                    }
+                });
+            }); }).catch(function () {
+                // Don't break the queue on error, but continue processing
+            });
+            return [2 /*return*/, resultPromise];
+        });
+    });
+}
+function isDarkMode(el) {
+    var doc = document.documentElement;
+    var body = document.body;
+    // Explicit light-mode opt-out takes priority over everything, including OS preference
+    if (doc.classList.contains("dds-light") ||
+        doc.dataset.ddsTheme === "light" ||
+        body.classList.contains("dds-light") ||
+        body.dataset.ddsTheme === "light" ||
+        !!(el && el.closest(".dds-light, [data-dds-theme='light']"))) {
+        return false;
+    }
+    return (doc.classList.contains("dds-dark") ||
+        doc.dataset.ddsTheme === "dark" ||
+        body.classList.contains("dds-dark") ||
+        body.dataset.ddsTheme === "dark" ||
+        !!(el && el.closest(".dds-dark, [data-dds-theme='dark']")) ||
+        window.matchMedia("(prefers-color-scheme: dark)").matches);
+}
+export function MermaidDiagram(_a) {
+    var _this = this;
+    var chart = _a.chart, _b = _a.className, className = _b === void 0 ? "" : _b;
+    var containerRef = useRef(null);
+    var _c = useState(null), svg = _c[0], setSvg = _c[1];
+    var _d = useState(null), error = _d[0], setError = _d[1];
+    // Stable unique prefix per instance — prevents duplicate IDs across multiple MermaidDiagram components
+    var instanceId = useId();
+    // Monotonically-increasing generation counter — stale async resolutions are discarded
+    var renderGen = useRef(0);
+    // Last known dark-mode state — prevents re-renders when attributes change but theme didn't flip
+    var lastDark = useRef(null);
+    var renderDiagram = useCallback(function () { return __awaiter(_this, void 0, void 0, function () {
+        var dark, generation, safePrefix, id, result, err_1;
+        var _a;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0:
+                    dark = isDarkMode(containerRef.current);
+                    lastDark.current = dark;
+                    generation = ++renderGen.current;
+                    safePrefix = instanceId.replace(/[^a-zA-Z0-9]/g, "");
+                    id = "dds-mermaid-".concat(safePrefix, "-").concat(generation);
+                    _b.label = 1;
+                case 1:
+                    _b.trys.push([1, 3, 4, 5]);
+                    return [4 /*yield*/, renderMermaidWithTheme(id, chart, dark)];
+                case 2:
+                    result = _b.sent();
+                    // Discard result if a newer render has since been requested
+                    if (generation !== renderGen.current)
+                        return [2 /*return*/];
+                    setSvg(result.svg);
+                    setError(null);
+                    return [3 /*break*/, 5];
+                case 3:
+                    err_1 = _b.sent();
+                    if (generation !== renderGen.current)
+                        return [2 /*return*/];
+                    setError(err_1 instanceof Error ? err_1.message : "Failed to render diagram");
+                    return [3 /*break*/, 5];
+                case 4:
+                    (_a = document.getElementById(id)) === null || _a === void 0 ? void 0 : _a.remove();
+                    return [7 /*endfinally*/];
+                case 5: return [2 /*return*/];
+            }
+        });
+    }); }, [chart, instanceId]);
+    useEffect(function () {
+        renderDiagram();
+    }, [renderDiagram]);
+    useEffect(function () {
+        // Only re-render when the effective dark/light state actually flips
+        var reRenderIfThemeChanged = function () {
+            var dark = isDarkMode(containerRef.current);
+            if (dark === lastDark.current)
+                return;
+            renderDiagram();
+        };
+        var observer = new MutationObserver(reRenderIfThemeChanged);
+        observer.observe(document.documentElement, {
+            attributes: true,
+            attributeFilter: ["class", "data-dds-theme"],
+        });
+        observer.observe(document.body, {
+            attributes: true,
+            attributeFilter: ["class", "data-dds-theme"],
+        });
+        var mq = window.matchMedia("(prefers-color-scheme: dark)");
+        mq.addEventListener("change", reRenderIfThemeChanged);
+        return function () {
+            observer.disconnect();
+            mq.removeEventListener("change", reRenderIfThemeChanged);
+        };
+    }, [renderDiagram]);
+    var classes = ["dds-mermaid", className].filter(Boolean).join(" ");
+    if (error) {
+        return (_jsx("div", { className: "".concat(classes, " dds-mermaid-error"), role: "alert", children: _jsxs("p", { className: "dds-mermaid-error-text", children: ["Diagram error: ", error] }) }));
+    }
+    return (_jsx("div", { className: classes, ref: containerRef, role: "img", "aria-label": "Mermaid diagram", dangerouslySetInnerHTML: svg ? { __html: svg } : undefined }));
+}

package/dist/components/MermaidDiagram.stories.d.ts

@@ -0,0 +1,11 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { MermaidDiagram } from './MermaidDiagram';
+declare const meta: Meta<typeof MermaidDiagram>;
+export default meta;
+type Story = StoryObj<typeof MermaidDiagram>;
+/** Basic flowchart diagram. */
+export declare const Flowchart: Story;
+/** Gantt chart diagram. */
+export declare const Gantt: Story;
+/** Shows the error state when diagram syntax is invalid. */
+export declare const InvalidSyntax: Story;

package/dist/components/MermaidDiagram.stories.js

@@ -0,0 +1,64 @@
+import { MermaidDiagram } from './MermaidDiagram';
+var meta = {
+    title: 'Components/MermaidDiagram',
+    component: MermaidDiagram,
+    tags: ['autodocs'],
+    argTypes: {
+        chart: {
+            control: 'text',
+            description: 'Mermaid diagram definition string.',
+        },
+        className: {
+            control: 'text',
+            description: 'Additional CSS classes.',
+            table: { defaultValue: { summary: '""' } },
+        },
+    },
+    parameters: {
+        docs: {
+            description: {
+                component: "\nRenders Mermaid diagram syntax as an SVG. Automatically switches between light and dark Mermaid themes based on the design system's dark mode state.\n\n## When to Use\n\n- Flowcharts, sequence diagrams, Gantt charts, or any Mermaid-supported diagram type\n- Inline diagrams in documentation pages\n- Architecture or process visualizations\n\n## When Not to Use\n\n- For static images or screenshots (use `<img>` or the `Icon` component)\n- For code snippets (use `CodeBlock`)\n- For simple bullet-point lists or tables\n\n## Accessibility\n\n- Container has `role=\"img\"` and `aria-label=\"Mermaid diagram\"`\n- Error states use `role=\"alert\"` for screen reader announcement\n        ",
+            },
+        },
+    },
+};
+export default meta;
+/** Basic flowchart diagram. */
+export var Flowchart = {
+    args: {
+        chart: "graph TD\n    A[Start] --> B{Decision}\n    B -->|Yes| C[Do something]\n    B -->|No| D[Do something else]\n    C --> E[End]\n    D --> E",
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: "<MermaidDiagram chart={`graph TD\n    A[Start] --> B{Decision}\n    B -->|Yes| C[Do something]\n    B -->|No| D[Do something else]\n    C --> E[End]\n    D --> E`} />",
+            },
+        },
+    },
+};
+/** Gantt chart diagram. */
+export var Gantt = {
+    args: {
+        chart: "gantt\n    title Project Schedule\n    dateFormat  YYYY-MM-DD\n    section Planning\n    Requirements :a1, 2024-01-01, 14d\n    Design       :a2, after a1, 10d\n    section Development\n    Implementation :b1, after a2, 21d\n    Testing        :b2, after b1, 14d",
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: "<MermaidDiagram chart={`gantt\n    title Project Schedule\n    dateFormat  YYYY-MM-DD\n    section Planning\n    Requirements :a1, 2024-01-01, 14d\n    Design       :a2, after a1, 10d\n    section Development\n    Implementation :b1, after a2, 21d\n    Testing        :b2, after b1, 14d`} />",
+            },
+        },
+    },
+};
+/** Shows the error state when diagram syntax is invalid. */
+export var InvalidSyntax = {
+    args: {
+        chart: 'this is not valid mermaid syntax %%%',
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: "<MermaidDiagram chart=\"this is not valid mermaid syntax %%%\" />",
+            },
+        },
+    },
+};

package/dist/index.d.ts

@@ -15,6 +15,7 @@ export * from './components/Table';
 export * from './components/Grid';
 export * from './components/Breadcrumb';
 export * from './components/Icon';
+export * from './components/MermaidDiagram';
 export * from './components/Tile';
 export * from './components/TileGrid';
 export * from './hooks/useKeyPress';

package/dist/index.js

@@ -16,6 +16,7 @@ export * from './components/Table';
 export * from './components/Grid';
 export * from './components/Breadcrumb';
 export * from './components/Icon';
+export * from './components/MermaidDiagram';
 export * from './components/Tile';
 export * from './components/TileGrid';
 // Export hooks

package/dist/styles.css

@@ -326,6 +326,16 @@
   --dds-breadcrumb-delimiter-color: #9ca3af; /* gray-400 */
   --dds-breadcrumb-ellipsis-radius: 0.25rem; /* rounded */
   --dds-breadcrumb-ellipsis-hover-bg: #f3f4f6; /* gray-100 */
+
+  /* MermaidDiagram */
+  --dds-mermaid-border: #e5e7eb; /* gray-200 */
+  --dds-mermaid-bg: #ffffff;
+  --dds-mermaid-radius: 0.5rem; /* rounded-lg */
+  --dds-mermaid-padding: 1.25rem;
+  --dds-mermaid-margin: 1rem 0;
+  --dds-mermaid-error-border: #fca5a5; /* red-300 */
+  --dds-mermaid-error-bg: #fef2f2; /* red-50 */
+  --dds-mermaid-error-text: #dc2626; /* red-600 */
 }
 /* ==========================================================================
    Dark Mode Tokens
@@ -526,6 +536,13 @@
   --dds-breadcrumb-current-color: #e5e7eb; /* gray-200 */
   --dds-breadcrumb-delimiter-color: #6b7280; /* gray-500 */
   --dds-breadcrumb-ellipsis-hover-bg: rgba(255, 255, 255, 0.08);
+
+  /* MermaidDiagram */
+  --dds-mermaid-border: #4b5563; /* gray-600 */
+  --dds-mermaid-bg: transparent;
+  --dds-mermaid-error-border: #991b1b; /* red-800 */
+  --dds-mermaid-error-bg: rgba(239, 68, 68, 0.08);
+  --dds-mermaid-error-text: #f87171; /* red-400 */
 }
 /* Auto dark mode — follows OS preference, opt-out with .dds-light */
 @media (prefers-color-scheme: dark) {
@@ -721,6 +738,13 @@
     --dds-breadcrumb-current-color: #e5e7eb; /* gray-200 */
     --dds-breadcrumb-delimiter-color: #6b7280; /* gray-500 */
     --dds-breadcrumb-ellipsis-hover-bg: rgba(255, 255, 255, 0.08);
+
+    /* MermaidDiagram */
+    --dds-mermaid-border: #4b5563;
+    --dds-mermaid-bg: transparent;
+    --dds-mermaid-error-border: #991b1b;
+    --dds-mermaid-error-bg: rgba(239, 68, 68, 0.08);
+    --dds-mermaid-error-text: #f87171;
   }
 }
 /* Explicit dark mode via data attribute (overrides OS preference) */
@@ -895,6 +919,13 @@
   --dds-breadcrumb-current-color: #e5e7eb; /* gray-200 */
   --dds-breadcrumb-delimiter-color: #6b7280; /* gray-500 */
   --dds-breadcrumb-ellipsis-hover-bg: rgba(255, 255, 255, 0.08);
+
+  /* MermaidDiagram */
+  --dds-mermaid-border: #4b5563;
+  --dds-mermaid-bg: transparent;
+  --dds-mermaid-error-border: #991b1b;
+  --dds-mermaid-error-bg: rgba(239, 68, 68, 0.08);
+  --dds-mermaid-error-text: #f87171;
 }
 /* Import PrismJS theme */
 /**
@@ -2480,6 +2511,29 @@ a.dds-breadcrumb-link:hover {
   width: 100%;
   height: 100%;
 }
+.dds-mermaid {
+  border: 1px solid var(--dds-mermaid-border);
+  border-radius: var(--dds-mermaid-radius);
+  background-color: var(--dds-mermaid-bg);
+  padding: var(--dds-mermaid-padding);
+  margin: var(--dds-mermaid-margin);
+  display: flex;
+  justify-content: center;
+  overflow-x: auto;
+}
+.dds-mermaid svg {
+  max-width: 100%;
+  height: auto;
+}
+.dds-mermaid-error {
+  border-color: var(--dds-mermaid-error-border);
+  background-color: var(--dds-mermaid-error-bg);
+}
+.dds-mermaid-error-text {
+  color: var(--dds-mermaid-error-text);
+  font-size: 0.875rem;
+  margin: 0;
+}
 a.dds-tile-link {
   display: block;
   text-decoration: none;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roadlittledawn/docs-design-system-react",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "license": "MIT",
   "description": "React components for documentation design system",
   "repository": {
@@ -24,14 +24,15 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
+    "mermaid": "^11.0.0",
     "prismjs": "^1.29.0",
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "slug": "^9.0.0"
   },
   "devDependencies": {
-    "@types/react": "^18.0.0",
-    "@types/react-dom": "^18.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
     "@types/slug": "^5.0.9",
     "postcss": "^8.4.0",
     "postcss-cli": "^11.0.0",
@@ -40,8 +41,8 @@
   },
   "sideEffects": false,
   "peerDependencies": {
-    "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0 || ^19.0.0"
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
   },
   "exports": {
     ".": {