@schlessera/brain-ui-react 0.8.0 → 0.10.0

package/src/lib/mermaid-theme.ts

@@ -0,0 +1,246 @@
+/**
+ * Mermaid theme variables for the two surfaces a diagram can land on.
+ *
+ * Mermaid's stock "dark" theme is a blue-grey palette that reads as foreign
+ * next to the app's warm-neutral chrome, and its "neutral" theme is what the
+ * share renderer used to emit. Both are replaced by the "base" theme plus the
+ * variables below, so an in-app diagram and a shared PNG are recognisably the
+ * same product.
+ *
+ * Two rules kept the palette honest:
+ *   - Surfaces follow the tokens in theme.css, not approximations of them. A
+ *     chat diagram sits on `--color-surface` (#141619), not on the page
+ *     background, because MermaidBlock draws it on a raised plate.
+ *   - Multi-series colors reuse CATEGORICAL_SLOTS from the graph view, which
+ *     is the repo's one CVD-validated categorical palette. Slot order is the
+ *     CVD-safety mechanism there and is preserved here.
+ */
+import { CATEGORICAL_SLOTS, OTHER_COLOR } from "../components/graph/lib/graph-helpers.js";
+
+export type MermaidTheme = "dark" | "light";
+
+// These variables reach mermaid through initialize(), NOT through a
+// `%%{init: …}%%` directive: mermaid's directive path rewrites `'` to `"`
+// before parsing the JSON and drops any themeVariable containing a hyphen, so
+// a font stack cannot survive it. See the note in mermaid.ts.
+const SANS = '"Plus Jakarta Sans", system-ui, -apple-system, sans-serif';
+
+/** Ordered series colors, long enough for the 12-slot scales mermaid asks for. */
+const SERIES = [...CATEGORICAL_SLOTS, OTHER_COLOR, "#67b8e3", "#eab354", "#b197d4"];
+
+/** Expand a scale into the `${prefix}0..count-1` (or 1-based) shape mermaid wants. */
+function scale(prefix: string, count: number, oneBased = false): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (let i = 0; i < count; i++) {
+    out[`${prefix}${oneBased ? i + 1 : i}`] = SERIES[i % SERIES.length];
+  }
+  return out;
+}
+
+/**
+ * Dark: the in-app palette. Node fills use `--color-surface-overlay` so nodes
+ * sit a step above the block's own `--color-surface` plate, and borders use
+ * #3d4150 rather than `--color-border` (#2a2d35) — a 1px border at the token
+ * value all but disappears against the plate at diagram scale.
+ */
+const DARK: Record<string, string | boolean> = {
+  darkMode: true,
+  background: "#141619",
+  fontFamily: SANS,
+  fontSize: "14px",
+
+  primaryColor: "#1e2128",
+  primaryTextColor: "#e8e4df",
+  primaryBorderColor: "#3d4150",
+  secondaryColor: "#1a1d22",
+  secondaryTextColor: "#e8e4df",
+  secondaryBorderColor: "#3d4150",
+  tertiaryColor: "#0c0e12",
+  tertiaryTextColor: "#8a8691",
+  tertiaryBorderColor: "#2a2d35",
+
+  mainBkg: "#1e2128",
+  nodeBorder: "#3d4150",
+  nodeTextColor: "#e8e4df",
+  textColor: "#e8e4df",
+  lineColor: "#8a8691",
+  defaultLinkColor: "#8a8691",
+  titleColor: "#e09f3e",
+  edgeLabelBackground: "#141619",
+  clusterBkg: "#0c0e12",
+  clusterBorder: "#2a2d35",
+
+  noteBkgColor: "#1a1d22",
+  noteTextColor: "#e8e4df",
+  noteBorderColor: "#e09f3e",
+  errorBkgColor: "#2a1a1a",
+  errorTextColor: "#f87171",
+
+  // Sequence
+  actorBkg: "#1e2128",
+  actorBorder: "#3d4150",
+  actorTextColor: "#e8e4df",
+  actorLineColor: "#3d4150",
+  signalColor: "#8a8691",
+  signalTextColor: "#e8e4df",
+  labelBoxBkgColor: "#1a1d22",
+  labelBoxBorderColor: "#2a2d35",
+  labelTextColor: "#e8e4df",
+  loopTextColor: "#e8e4df",
+  activationBkgColor: "#1a1d22",
+  activationBorderColor: "#5bb5a2",
+  sequenceNumberColor: "#0c0e12",
+
+  // State / class / journey
+  labelColor: "#e8e4df",
+  altBackground: "#0c0e12",
+  classText: "#e8e4df",
+
+  // Gantt
+  sectionBkgColor: "#1a1d22",
+  altSectionBkgColor: "#141619",
+  sectionBkgColor2: "#1e2128",
+  gridColor: "#2a2d35",
+  taskBkgColor: "#2a2d35",
+  taskTextColor: "#e8e4df",
+  taskTextOutsideColor: "#e8e4df",
+  taskTextDarkColor: "#0c0e12",
+  taskBorderColor: "#3d4150",
+  doneTaskBkgColor: "#565b66",
+  doneTaskBorderColor: "#3d4150",
+  activeTaskBkgColor: "#e09f3e",
+  activeTaskBorderColor: "#e09f3e",
+  critBkgColor: "#d03b3b",
+  critBorderColor: "#d03b3b",
+  todayLineColor: "#5bb5a2",
+
+  // Pie
+  pieTitleTextColor: "#e8e4df",
+  pieSectionTextColor: "#0c0e12",
+  pieLegendTextColor: "#e8e4df",
+  pieStrokeColor: "#141619",
+  pieOuterStrokeColor: "#2a2d35",
+
+  // Quadrant / requirement / misc surfaces that don't inherit cleanly
+  quadrant1Fill: "#1e2128",
+  quadrant2Fill: "#1a1d22",
+  quadrant3Fill: "#141619",
+  quadrant4Fill: "#1e2128",
+  quadrantPointFill: "#e09f3e",
+  quadrantTitleFill: "#e8e4df",
+  quadrantInternalBorderStrokeFill: "#2a2d35",
+  quadrantExternalBorderStrokeFill: "#3d4150",
+};
+
+/**
+ * Light: what the share renderer emits. Tuned against the PNG/PDF template's
+ * own palette (`ui-server/src/render/template.ts`: #ffffff page, #f8fafc
+ * surface, #e5e7eb border, #1f2937 text) so a diagram doesn't look pasted in.
+ * The amber and teal are darkened from the app tokens — #e09f3e on white is a
+ * 1.9:1 line, unusable for edges or titles.
+ */
+const LIGHT: Record<string, string | boolean> = {
+  darkMode: false,
+  background: "#ffffff",
+  fontFamily: SANS,
+  fontSize: "14px",
+
+  primaryColor: "#f8fafc",
+  primaryTextColor: "#1f2937",
+  primaryBorderColor: "#c3c9d2",
+  secondaryColor: "#f3f4f6",
+  secondaryTextColor: "#1f2937",
+  secondaryBorderColor: "#c3c9d2",
+  tertiaryColor: "#ffffff",
+  tertiaryTextColor: "#6b7280",
+  tertiaryBorderColor: "#e5e7eb",
+
+  mainBkg: "#f8fafc",
+  nodeBorder: "#c3c9d2",
+  nodeTextColor: "#1f2937",
+  textColor: "#1f2937",
+  lineColor: "#6b7280",
+  defaultLinkColor: "#6b7280",
+  titleColor: "#9a6516",
+  edgeLabelBackground: "#ffffff",
+  clusterBkg: "#f3f4f6",
+  clusterBorder: "#d7dbe0",
+
+  noteBkgColor: "#fdf6e8",
+  noteTextColor: "#1f2937",
+  noteBorderColor: "#9a6516",
+  errorBkgColor: "#fdecec",
+  errorTextColor: "#b42323",
+
+  // Sequence
+  actorBkg: "#f8fafc",
+  actorBorder: "#c3c9d2",
+  actorTextColor: "#1f2937",
+  actorLineColor: "#c3c9d2",
+  signalColor: "#6b7280",
+  signalTextColor: "#1f2937",
+  labelBoxBkgColor: "#f3f4f6",
+  labelBoxBorderColor: "#d7dbe0",
+  labelTextColor: "#1f2937",
+  loopTextColor: "#1f2937",
+  activationBkgColor: "#f3f4f6",
+  activationBorderColor: "#2f7d6b",
+  sequenceNumberColor: "#ffffff",
+
+  // State / class / journey
+  labelColor: "#1f2937",
+  altBackground: "#f3f4f6",
+  classText: "#1f2937",
+
+  // Gantt
+  sectionBkgColor: "#f8fafc",
+  altSectionBkgColor: "#ffffff",
+  sectionBkgColor2: "#f3f4f6",
+  gridColor: "#e5e7eb",
+  taskBkgColor: "#e5e7eb",
+  taskTextColor: "#1f2937",
+  taskTextOutsideColor: "#1f2937",
+  taskTextDarkColor: "#1f2937",
+  taskBorderColor: "#c3c9d2",
+  doneTaskBkgColor: "#d7dbe0",
+  doneTaskBorderColor: "#c3c9d2",
+  activeTaskBkgColor: "#e0a75a",
+  activeTaskBorderColor: "#9a6516",
+  critBkgColor: "#e08a8a",
+  critBorderColor: "#b42323",
+  todayLineColor: "#2f7d6b",
+
+  // Pie
+  pieTitleTextColor: "#1f2937",
+  pieSectionTextColor: "#ffffff",
+  pieLegendTextColor: "#1f2937",
+  pieStrokeColor: "#ffffff",
+  pieOuterStrokeColor: "#d7dbe0",
+
+  // Quadrant
+  quadrant1Fill: "#f8fafc",
+  quadrant2Fill: "#f3f4f6",
+  quadrant3Fill: "#ffffff",
+  quadrant4Fill: "#f8fafc",
+  quadrantPointFill: "#9a6516",
+  quadrantTitleFill: "#1f2937",
+  quadrantInternalBorderStrokeFill: "#e5e7eb",
+  quadrantExternalBorderStrokeFill: "#d7dbe0",
+};
+
+const SERIES_SCALES: Record<string, string> = {
+  ...scale("pie", 12, true), // pie1..pie12
+  ...scale("cScale", 12), // cScale0..11 (journey, timeline, xychart)
+  ...scale("fillType", 8), // fillType0..7 (class/state/journey sections)
+  ...scale("git", 8), // git0..git7 (gitgraph branches)
+};
+
+const THEME_VARIABLES: Record<MermaidTheme, Record<string, string | boolean>> = {
+  dark: { ...DARK, ...SERIES_SCALES },
+  light: { ...LIGHT, ...SERIES_SCALES },
+};
+
+/** Theme variables for a target surface, as mermaid's `themeVariables` object. */
+export function mermaidThemeVariables(theme: MermaidTheme): Record<string, string | boolean> {
+  return THEME_VARIABLES[theme];
+}

package/src/lib/mermaid.ts

@@ -9,7 +9,9 @@
  * streaming message a cache hit.
  */
 
-export type MermaidTheme = "dark" | "neutral";
+import { mermaidThemeVariables, type MermaidTheme } from "./mermaid-theme.js";
+
+export type { MermaidTheme };
 
 type MermaidApi = typeof import("mermaid").default;
 
@@ -17,36 +19,50 @@ let mermaidPromise: Promise<MermaidApi> | null = null;
 
 function loadMermaid(): Promise<MermaidApi> {
   if (!mermaidPromise) {
-    mermaidPromise = import("mermaid").then((mod) => {
-      const mermaid = mod.default;
-      mermaid.initialize({
-        startOnLoad: false,
-        // "strict" sanitizes label HTML and blocks script/click payloads —
-        // diagram sources arrive from the model and from repo files.
-        securityLevel: "strict",
-        // Never inject mermaid's own error SVG into the document; failures
-        // surface as a null render result and the caller shows the source.
-        suppressErrorRendering: true,
-        theme: "dark",
-        fontFamily: "ui-sans-serif, system-ui, sans-serif",
-      });
-      return mermaid;
-    });
+    mermaidPromise = import("mermaid").then((mod) => mod.default);
   }
   return mermaidPromise;
 }
 
-const INIT_DIRECTIVE_RE = /%%\{\s*init/;
+/** Config shared by both themes; only `themeVariables` differs per render. */
+function baseConfig(theme: MermaidTheme) {
+  return {
+    startOnLoad: false,
+    // "strict" sanitizes label HTML and blocks script/click payloads —
+    // diagram sources arrive from the model and from repo files.
+    securityLevel: "strict" as const,
+    // Never inject mermaid's own error SVG into the document; failures
+    // surface as a null render result and the caller shows the source.
+    suppressErrorRendering: true,
+    theme: "base" as const,
+    themeVariables: mermaidThemeVariables(theme),
+  };
+}
 
 /**
- * Theme is applied per-diagram via an init directive rather than re-calling
- * mermaid.initialize(), so concurrent renders for different targets (dark
- * in-app, neutral for the light share template) can't race on global config.
- * A source that carries its own init directive is left alone.
+ * Renders are serialized through this chain because the theme is applied by
+ * re-calling mermaid.initialize(), which mutates GLOBAL config — a dark
+ * in-app render and a light share render would otherwise race and one would
+ * come out in the other's palette.
+ *
+ * The obvious alternative, a per-diagram `%%{init: …}%%` directive, does not
+ * work: mermaid rewrites every `'` to `"` before JSON.parse-ing a directive
+ * (chunk-NSK5VX7P), so a quoted font stack makes the whole directive
+ * unparseable and it is silently dropped; and its themeVariables sanitizer
+ * rejects any value outside /^[\\d "#%(),.;A-Za-z]+$/, which blanks every
+ * hyphenated CSS keyword (`system-ui`, `-apple-system`). A dropped directive
+ * fails SILENTLY — the diagram renders in whatever the last global config
+ * was — so this path is not worth the theming it appears to buy.
  */
-function withThemeDirective(source: string, theme: MermaidTheme): string {
-  if (INIT_DIRECTIVE_RE.test(source)) return source;
-  return `%%{init: {"theme": "${theme}"}}%%\n${source}`;
+let renderChain: Promise<unknown> = Promise.resolve();
+
+function serialized<T>(fn: () => Promise<T>): Promise<T> {
+  const run = renderChain.then(fn, fn);
+  renderChain = run.then(
+    () => undefined,
+    () => undefined
+  );
+  return run;
 }
 
 const svgCache = new Map<string, string>();
@@ -78,16 +94,22 @@ export async function renderMermaidSvg(
   if (hit !== undefined) return hit;
   try {
     const mermaid = await loadMermaid();
-    const text = withThemeDirective(trimmed, theme);
-    const ok = await mermaid.parse(text, { suppressErrors: true });
-    if (!ok) return null;
-    const { svg } = await mermaid.render(`brain-mermaid-${++renderSeq}`, text);
-    if (svgCache.size >= CACHE_MAX) {
-      const oldest = svgCache.keys().next().value;
-      if (oldest !== undefined) svgCache.delete(oldest);
-    }
-    svgCache.set(key, svg);
-    return svg;
+    return await serialized(async () => {
+      // Re-check inside the lock: an identical render may have been queued
+      // ahead of this one while both were waiting.
+      const queued = svgCache.get(key);
+      if (queued !== undefined) return queued;
+      mermaid.initialize(baseConfig(theme));
+      const ok = await mermaid.parse(trimmed, { suppressErrors: true });
+      if (!ok) return null;
+      const { svg } = await mermaid.render(`brain-mermaid-${++renderSeq}`, trimmed);
+      if (svgCache.size >= CACHE_MAX) {
+        const oldest = svgCache.keys().next().value;
+        if (oldest !== undefined) svgCache.delete(oldest);
+      }
+      svgCache.set(key, svg);
+      return svg;
+    });
   } catch {
     return null;
   }
@@ -184,7 +206,7 @@ export function replaceMermaidFences(
  * block. Used by the share pipeline: the PNG/PDF renderer runs the page with
  * JavaScript disabled and all network denied, so the diagram must already be
  * SVG by the time the markdown reaches the server. Defaults to the light
- * "neutral" theme to match the share template. Fences that fail to render are
+ * theme to match the share template. Fences that fail to render are
  * left as code fences — the pre-feature behavior.
  */
 /**
@@ -219,7 +241,7 @@ export function inlineRenderedFences(
 
 export async function inlineMermaidDiagrams(
   md: string,
-  theme: MermaidTheme = "neutral"
+  theme: MermaidTheme = "light"
 ): Promise<string> {
   const fences = findMermaidFences(md);
   if (fences.length === 0) return md;
@@ -227,6 +249,38 @@ export async function inlineMermaidDiagrams(
   return inlineRenderedFences(md, rendered);
 }
 
+const SVG_OPEN_TAG_RE = /<svg\b[^>]*>/i;
+const VIEWBOX_RE = /\bviewBox\s*=\s*"\s*[\d.+-]+\s+[\d.+-]+\s+([\d.+-]+)\s+([\d.+-]+)\s*"/i;
+
+/**
+ * Give a mermaid SVG an intrinsic pixel size taken from its viewBox.
+ *
+ * Mermaid ships its diagrams as `style="max-width: Npx"` with no width/height
+ * attribute, which is right for a responsive page and wrong for an export: a
+ * standalone .svg file then has no intrinsic size, and the PNG/PDF renderer
+ * lays it out at the full body width no matter how small the diagram is.
+ * Sizing it here is what lets the share page shrink-wrap the figure.
+ *
+ * Returns the input unchanged when there is no parseable viewBox — an
+ * un-sized export beats a corrupted one.
+ */
+export function sizeSvgForExport(svg: string, maxWidth = 1200): string {
+  const open = SVG_OPEN_TAG_RE.exec(svg);
+  if (!open) return svg;
+  const tag = open[0];
+  const vb = VIEWBOX_RE.exec(tag);
+  if (!vb) return svg;
+  const vbW = Number(vb[1]);
+  const vbH = Number(vb[2]);
+  if (!Number.isFinite(vbW) || !Number.isFinite(vbH) || vbW <= 0 || vbH <= 0) return svg;
+  const width = Math.max(1, Math.min(maxWidth, Math.round(vbW)));
+  const height = Math.max(1, Math.round((width / vbW) * vbH));
+  const sized = tag
+    .replace(/\s(?:width|height|style)\s*=\s*"[^"]*"/gi, "")
+    .replace(/<svg\b/i, `<svg width="${width}" height="${height}"`);
+  return svg.slice(0, open.index) + sized + svg.slice(open.index + tag.length);
+}
+
 /** Whether a repo path is a standalone mermaid source file (previewable as a diagram). */
 export function isMermaidPath(path: string): boolean {
   return /\.(mmd|mermaid)$/i.test(path);