feat(react): render ```dot code blocks as Graphviz diagrams

.changeset/graphviz-diagrams.md

@@ -0,0 +1,5 @@
+---
+'@doc-kit/generator-react': minor
+---
+
+Render ` ```dot ` code blocks as Graphviz diagrams when the optional `@hpcc-js/wasm-graphviz` dependency is installed, with `${light|dark}` colors rendering a diagram per color scheme.

packages/react/package.json

@@ -59,6 +59,15 @@
     "vite": "~8.3.1"
   },
   "devDependencies": {
+    "@hpcc-js/wasm-graphviz": "^1.22.0",
     "dedent": "^1.7.2"
+  },
+  "peerDependencies": {
+    "@hpcc-js/wasm-graphviz": "^1.22.0"
+  },
+  "peerDependenciesMeta": {
+    "@hpcc-js/wasm-graphviz": {
+      "optional": true
+    }
   }
 }

packages/react/src/html/ui/index.css

@@ -204,4 +204,18 @@ main {
       }
     }
   }
+
+  /* Graphviz diagrams; with colors for each color scheme, there is one per
+     scheme, and the one of the current scheme shows */
+  .diagram svg {
+    display: block;
+    max-width: 100%;
+    height: auto;
+    margin: 1rem auto;
+  }
+
+  :where([data-theme='dark']) & .diagram-light,
+  :where(:root:not([data-theme='dark'])) & .diagram-dark {
+    display: none;
+  }
 }

packages/react/src/jsx-ast/utils/plugins/__tests__/diagrams.test.mjs

@@ -0,0 +1,44 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import { u } from 'unist-builder';
+
+import transformDiagrams, { renderDiagram } from '../diagrams.mjs';
+
+const transform = transformDiagrams();
+
+describe('transformDiagrams', () => {
+  it('renders ```dot code blocks as inline SVG', () => {
+    const tree = u('root', [u('code', { lang: 'dot' }, 'digraph { a -> b }')]);
+
+    transform(tree);
+
+    const [node] = tree.children;
+    assert.equal(node.type, 'html');
+    assert.match(
+      node.value,
+      /^<div class="diagram">[\s\S]*<svg[\s\S]*<\/svg><\/div>$/
+    );
+    assert.doesNotMatch(node.value, /\n\s*\n/);
+  });
+
+  it('leaves other code blocks alone', () => {
+    const code = u('code', { lang: 'js' }, 'a -> b');
+    const tree = u('root', [code]);
+
+    transform(tree);
+
+    assert.equal(tree.children[0], code);
+  });
+});
+
+describe('renderDiagram', () => {
+  it('renders a diagram per color scheme for themed colors', () => {
+    const html = renderDiagram('digraph { a [color="${#000000|#ffffff}"] }');
+
+    assert.match(html, /class="diagram diagram-light"/);
+    assert.match(html, /class="diagram diagram-dark"/);
+    assert.match(html.split('diagram-dark')[0], /#000000/);
+    assert.match(html.split('diagram-dark')[1], /#ffffff/);
+  });
+});

packages/react/src/jsx-ast/utils/plugins/diagrams.mjs

@@ -0,0 +1,76 @@
+'use strict';
+
+import { visit } from 'unist-util-visit';
+
+/**
+ * Graphviz, when the optional `@hpcc-js/wasm-graphviz` dependency is
+ * installed. Loaded up front, as the Markdown pipeline runs synchronously.
+ *
+ * @type {import('@hpcc-js/wasm-graphviz').Graphviz | undefined}
+ */
+const graphviz = await import('@hpcc-js/wasm-graphviz')
+  .then(({ Graphviz }) => Graphviz.load())
+  .catch(() => undefined);
+
+/** A color for each color scheme: `${#3c3c43|#dfdfd6}` */
+const THEMED_COLOR = /\$\{([^|}]*)\|([^}]*)\}/g;
+
+/**
+ * Renders DOT source as an inline SVG.
+ *
+ * @param {string} dot
+ */
+const render = dot =>
+  graphviz
+    .dot(dot, 'svg_inline')
+    // A blank line would end the HTML block the SVG is embedded in
+    .replace(/\n\s*\n/g, '\n')
+    .trim();
+
+/**
+ * Renders a diagram. One using colors for each color scheme renders twice,
+ * one SVG per scheme, the page's styles showing the one of the current
+ * scheme.
+ *
+ * @param {string} dot
+ */
+export const renderDiagram = dot => {
+  if (!dot.includes('${')) {
+    return `<div class="diagram">${render(dot)}</div>`;
+  }
+
+  return ['light', 'dark']
+    .map(scheme => {
+      const colors = dot.replace(THEMED_COLOR, (_, light, dark) =>
+        scheme === 'light' ? light : dark
+      );
+
+      return `<div class="diagram diagram-${scheme}">${render(colors)}</div>`;
+    })
+    .join('\n');
+};
+
+/**
+ * Renders ```dot code blocks as Graphviz diagrams, when Graphviz is
+ * installed; otherwise, they stay code blocks.
+ *
+ * @param {import('mdast').Root} tree
+ */
+const transformer = tree => {
+  if (!graphviz) {
+    return;
+  }
+
+  visit(tree, 'code', (node, index, parent) => {
+    if (node.lang !== 'dot') {
+      return;
+    }
+
+    parent.children[index] = { type: 'html', value: renderDiagram(node.value) };
+  });
+};
+
+/**
+ * The remark plugin rendering Graphviz diagrams.
+ */
+export default () => transformer;

packages/react/src/jsx-ast/utils/remark.mjs

@@ -15,6 +15,7 @@ import { visit } from 'unist-util-visit';
 
 import { AST_NODE_TYPES } from '../constants.mjs';
 import transformAlerts from './plugins/alerts.mjs';
+import transformDiagrams from './plugins/diagrams.mjs';
 import transformElements from './plugins/transformer.mjs';
 
 const passThrough = ['element', ...Object.values(AST_NODE_TYPES.MDX)];
@@ -58,6 +59,7 @@ export const getRemarkRecma = lazy(() =>
   unified()
     .use(remarkParse)
     .use(transformAlerts)
+    .use(transformDiagrams)
     // We make Rehype ignore existing HTML nodes, and JSX nodes
     // as these are nodes we manually created during the generation process
     // We also allow dangerous HTML to be passed through, since we have HTML within our Markdown