@djangocfg/widget-diagram 0.1.1

package/src/hooks/useMermaidValidation.ts

@@ -0,0 +1,97 @@
+/**
+ * Hook for validating Mermaid code completeness.
+ *
+ * Purpose: while a diagram is being *streamed* (token by token from an
+ * LLM, or typed) the source is briefly invalid. Rendering it would throw
+ * a parse error and flash an error panel on every keystroke. This
+ * heuristic detects "obviously still-being-written" source so the
+ * renderer can wait instead. It is intentionally conservative — false
+ * "complete" is fine (the real parser catches it), false "incomplete"
+ * just delays a render.
+ */
+
+import { useCallback } from 'react';
+
+/** Diagram keywords that, alone, are a valid first line. */
+const DIAGRAM_KEYWORDS = [
+    'graph',
+    'flowchart',
+    'sequenceDiagram',
+    'classDiagram',
+    'stateDiagram',
+    'stateDiagram-v2',
+    'erDiagram',
+    'journey',
+    'gantt',
+    'pie',
+    'mindmap',
+    'timeline',
+    'gitGraph',
+    'quadrantChart',
+    'requirementDiagram',
+    'C4Context',
+    'sankey-beta',
+    'xychart-beta',
+    'block-beta',
+];
+
+/** Count occurrences of a character that are not inside a quoted string. */
+function countUnquoted(text: string, open: string, close: string): number {
+    let depth = 0;
+    let inQuote = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (ch === '"') {
+            inQuote = !inQuote;
+            continue;
+        }
+        if (inQuote) continue;
+        if (ch === open) depth++;
+        else if (ch === close) depth--;
+    }
+    return depth;
+}
+
+export function useMermaidValidation() {
+    const isMermaidCodeComplete = useCallback((code: string): boolean => {
+        if (!code || code.trim().length === 0) return false;
+
+        const trimmed = code.trim();
+
+        // Must start with a recognised diagram keyword. During streaming
+        // the very first tokens may be a partial keyword — wait for it.
+        const firstToken = trimmed.split(/[\s\n;]/)[0] ?? '';
+        const hasKnownType = DIAGRAM_KEYWORDS.some(
+            (kw) => firstToken === kw || trimmed.startsWith(kw),
+        );
+        if (!hasKnownType) return false;
+
+        const lines = trimmed.split('\n');
+        const lastLine = (lines[lines.length - 1] ?? '').trim();
+
+        // Trailing edge with no destination: `A -->` / `A --` / `A -.->`.
+        if (/(-{1,3}>?|={1,3}>?|-\.->?|\.\.>?|--[ox])\s*$/.test(lastLine)) {
+            return false;
+        }
+        // Trailing edge label still open: `A -->|label` (no closing `|`).
+        if (/-{1,3}>?\s*\|[^|]*$/.test(lastLine)) return false;
+
+        // Unbalanced shape brackets across the whole source (open > close).
+        if (countUnquoted(trimmed, '[', ']') > 0) return false;
+        if (countUnquoted(trimmed, '(', ')') > 0) return false;
+        // ER diagrams use `{` / `}` for crow's-foot cardinality
+        // (`||--o{`, `}|--||`) — those braces are deliberately unbalanced
+        // and must not be counted, or the diagram never renders.
+        if (!trimmed.startsWith('erDiagram') && countUnquoted(trimmed, '{', '}') > 0) {
+            return false;
+        }
+
+        // Odd number of double quotes — an unterminated string literal.
+        const quoteCount = (trimmed.match(/"/g) ?? []).length;
+        if (quoteCount % 2 !== 0) return false;
+
+        return true;
+    }, []);
+
+    return { isMermaidCodeComplete };
+}

package/src/index.tsx

@@ -0,0 +1,79 @@
+/**
+ * Two halves that belong together and ship apart.
+ *
+ * WRITING a diagram — `FlowDiagram`, `SequenceDiagram`, `JourneyDiagram` — is
+ * a pure string function a server pass, a test or a CLI can call, and it costs
+ * nothing. DRAWING one loads `mermaid`, which unpacks to ~84 MB, so `Mermaid`
+ * arrives behind `React.lazy` and the library only when a diagram mounts.
+ *
+ * `@djangocfg/widget-media/diagram` is the OTHER renderer and is not a
+ * duplicate of this one. It parses with `beautiful-mermaid` (~2 MB) and covers
+ * flowchart, sequence, state, class and ER, falling back to the source for the
+ * rest — the right trade for a chat transcript, where most messages carry no
+ * diagram at all. This one carries the full parser: gantt, mindmap, pie and
+ * everything else, for a surface whose job IS the diagram.
+ *
+ * Pick by what the surface is for, and do not import both into one app.
+ */
+
+'use client';
+
+export type { MermaidProps } from './types';
+
+/**
+ * The renderer, behind its dynamic import.
+ *
+ * ONE lazy boundary, not two: this file used to wrap `Mermaid.client` in its
+ * own `React.lazy` with a hand-rolled spinner while `lazy.tsx` wrapped the same
+ * module again with the shared placeholder. Two boundaries around one module
+ * split nothing extra and gave the same component two different loading states
+ * depending on which name a consumer imported.
+ */
+export { LazyMermaid, LazyMermaid as Mermaid, LazyMermaid as default } from './lazy';
+
+// Re-export builders for declarative diagram construction
+export {
+  // Core
+  DiagramStore,
+  sanitizeLabel,
+  toNodeId,
+  // Theme hooks
+  useThemePalette,
+  useStylePresets,
+  useBoxColors,
+  // FlowDiagram
+  FlowDiagram,
+  STYLE_PRESETS,
+  // SequenceDiagram
+  SequenceDiagram,
+  // JourneyDiagram
+  JourneyDiagram,
+} from './builders';
+
+export type {
+  // Core types
+  DiagramStoreOptions,
+  FlowDirection,
+  NodeShape,
+  ParticipantType,
+  TaskScore,
+  // Theme types
+  ThemePalette,
+  StyleColors,
+  StylePresets,
+  BoxColors,
+  // FlowDiagram types
+  FlowDiagramOptions,
+  FlowDiagramBuilder,
+  NodeBuilder,
+  EdgeBuilder,
+  StyleBuilder,
+  // SequenceDiagram types
+  ParticipantsObject,
+  SequenceDiagramOptions,
+  SequenceDiagramBuilder,
+  // JourneyDiagram types
+  JourneyDiagramOptions,
+  JourneyDiagramBuilder,
+  SectionBuilder,
+} from './builders';

package/src/lazy.tsx

@@ -0,0 +1,40 @@
+'use client';
+
+/**
+ * The renderer's single lazy boundary.
+ *
+ * `mermaid` unpacks to ~84 MB, so it must never be a static edge. The barrel
+ * re-exports what is here rather than wrapping it a second time.
+ */
+
+import { createLazyComponent, CardLoadingFallback } from '@djangocfg/widget-kit/lazy';
+import type { MermaidProps } from './types';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type { MermaidProps };
+
+// ============================================================================
+// Lazy Component
+// ============================================================================
+
+/**
+ * LazyMermaid - Lazy-loaded Mermaid diagram renderer
+ *
+ * Automatically shows loading state while Mermaid loads (~800KB)
+ */
+export const LazyMermaid = createLazyComponent<MermaidProps>(
+  () => import('./Mermaid.client'),
+  {
+    displayName: 'LazyMermaid',
+    fallback: (
+      <CardLoadingFallback
+        title="Diagram"
+        description="Loading..."
+        minHeight={200}
+      />
+    ),
+  }
+);

package/src/mermaid.stories.tsx

@@ -0,0 +1,217 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import * as React from 'react';
+import { LazyMermaid as Mermaid } from '.';
+
+// ============================================================================
+// Curated diagram payloads
+// ============================================================================
+
+const FLOWCHART = `graph TD
+  A[Client] -->|HTTP| B(Next.js)
+  B --> C{Auth?}
+  C -->|yes| D[Render]
+  C -->|no| E[/Redirect/]`;
+
+const SEQUENCE = `sequenceDiagram
+  participant U as User
+  participant W as WebApp
+  participant API as Backend
+  U->>W: click "Save"
+  W->>API: PATCH /profile
+  API-->>W: 200 OK
+  W-->>U: toast "Saved"`;
+
+const GANTT = `gantt
+  title djangocfg storybook rollout
+  dateFormat YYYY-MM-DD
+  section Phases
+  Scaffold        :done, p1, 2026-05-18, 1d
+  Workspaces      :done, p2, after p1, 1d
+  UI seed         :done, p3, after p2, 2d
+  Demo migration  :active, p4, after p3, 3d
+  Ship            :p5, after p4, 2d`;
+
+const CLASS_DIAGRAM = `classDiagram
+  class Animal {
+    +String name
+    +int age
+    +makeSound() void
+  }
+  class Dog {
+    +String breed
+    +bark() void
+  }
+  class Cat {
+    +bool indoor
+    +meow() void
+  }
+  Animal <|-- Dog
+  Animal <|-- Cat`;
+
+const STATE_DIAGRAM = `stateDiagram-v2
+  [*] --> Idle
+  Idle --> Loading: fetch()
+  Loading --> Success: 200 OK
+  Loading --> Error: 5xx
+  Success --> Idle: reset
+  Error --> Idle: retry
+  Success --> [*]`;
+
+const ER_DIAGRAM = `erDiagram
+  CUSTOMER ||--o{ ORDER : places
+  ORDER ||--|{ LINE_ITEM : contains
+  CUSTOMER {
+    string name
+    string email
+  }
+  ORDER {
+    int id
+    date created
+  }
+  LINE_ITEM {
+    string sku
+    int qty
+    float price
+  }`;
+
+const MINDMAP = `mindmap
+  root((djangocfg))
+    Frontend
+      Next.js
+      Storybook
+      UI Tools
+    Backend
+      Django
+      DRF
+      Celery
+    Infra
+      Docker
+      Postgres
+      Redis`;
+
+const PIE = `pie title Browser usage
+  "Chrome" : 62
+  "Safari" : 18
+  "Firefox" : 9
+  "Edge" : 7
+  "Other" : 4`;
+
+const TIMELINE = `timeline
+  title djangocfg release timeline
+  2024 : Project kickoff : Core packages
+  2025 : Public beta : UI Tools v1
+  2026 : Storybook reorg : Mermaid stories`;
+
+const JOURNEY = `journey
+  title User onboarding
+  section Discovery
+    Visit landing: 5: User
+    Read features: 4: User
+  section Sign up
+    Click signup: 5: User
+    Fill form: 2: User
+    Verify email: 4: User, System
+  section First run
+    Complete profile: 3: User
+    Create project: 5: User`;
+
+// ============================================================================
+// Meta
+// ============================================================================
+
+const Frame: React.FC<React.PropsWithChildren> = ({ children }) => (
+  <div className="w-[720px] rounded-lg border border-border bg-card p-4">
+    {children}
+  </div>
+);
+
+const meta = {
+  title: 'Widgets/Diagram/Mermaid',
+  component: Mermaid,
+  tags: ['autodocs'],
+  argTypes: {
+    chart: { control: 'text', table: { category: 'Content' } },
+    fullscreen: {
+      control: 'boolean',
+      description: 'Enable click-to-fullscreen overlay',
+      table: { category: 'Behaviour', defaultValue: { summary: 'true' } },
+    },
+    isCompact: {
+      control: 'boolean',
+      description: 'Use compact layout',
+      table: { category: 'Behaviour', defaultValue: { summary: 'false' } },
+    },
+    scrollIsolation: {
+      control: 'boolean',
+      description: 'Enable the FloatingToolbar scroll-lock overlay',
+      table: { category: 'Behaviour', defaultValue: { summary: 'false' } },
+    },
+    className: { control: 'text', table: { category: 'Styling' } },
+  },
+  render: (args) => (
+    <Frame>
+      <Mermaid {...args} />
+    </Frame>
+  ),
+} satisfies Meta<typeof Mermaid>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+// ============================================================================
+// Playground (Controls-driven)
+// ============================================================================
+
+export const Playground: Story = {
+  args: {
+    chart: FLOWCHART,
+    fullscreen: true,
+    isCompact: false,
+    scrollIsolation: false,
+  },
+};
+
+// ============================================================================
+// Curated presets
+// ============================================================================
+
+export const Flowchart: Story = {
+  args: { chart: FLOWCHART },
+};
+
+export const Sequence: Story = {
+  args: { chart: SEQUENCE },
+};
+
+export const Gantt: Story = {
+  args: { chart: GANTT },
+};
+
+export const Class: Story = {
+  args: { chart: CLASS_DIAGRAM },
+};
+
+export const State: Story = {
+  args: { chart: STATE_DIAGRAM },
+};
+
+export const ER: Story = {
+  args: { chart: ER_DIAGRAM },
+};
+
+export const Mindmap: Story = {
+  args: { chart: MINDMAP },
+};
+
+export const Pie: Story = {
+  args: { chart: PIE },
+};
+
+export const Timeline: Story = {
+  args: { chart: TIMELINE },
+};
+
+export const Journey: Story = {
+  args: { chart: JOURNEY },
+};

package/src/types.ts

@@ -0,0 +1,28 @@
+/**
+ * The renderer's props.
+ *
+ * In their own module because both the barrel and `lazy.tsx` need them, and
+ * having `lazy` import them from the barrel while the barrel re-exports `lazy`
+ * is a cycle — one that resolves at build time and bites at runtime.
+ */
+
+export interface MermaidProps {
+  chart: string;
+  className?: string;
+  isCompact?: boolean;
+  /** Enable click-to-fullscreen functionality (default: true) */
+  fullscreen?: boolean;
+  /**
+   * Enable the FloatingToolbar's "click to scroll" lock overlay.
+   * Defaults to `false` — Mermaid diagrams don't scroll internally,
+   * so the lock overlay just steals page wheel events. See the
+   * Mermaid.client implementation for the full rationale.
+   */
+  scrollIsolation?: boolean;
+  /**
+   * Debounce window (ms) before (re)rendering after `chart` changes.
+   * Lower feels snappier for static charts; higher reduces churn while
+   * a diagram is streamed in. Default 300.
+   */
+  debounceMs?: number;
+}

package/src/utils/mermaid-helpers.ts

@@ -0,0 +1,157 @@
+/**
+ * Helper utilities for Mermaid diagram rendering
+ */
+
+/**
+ * Read a semantic color token from CSS custom properties.
+ *
+ * Theme tokens (`light.css` / `dark.css`) ship fully-wrapped CSS colors
+ * (`hsl(0 0% 94%)`) — see `ui-core/src/styles/theme/tokens.css`. Older
+ * tokens stored bare HSL components (`0 0% 94%`), so this helper handles
+ * both: complete colors pass through untouched, bare components get
+ * wrapped once. Never double-wrap an already-complete color.
+ *
+ * @param variable CSS custom property name, e.g. `--foreground`.
+ * @param fallback Returned when the variable is empty / unavailable.
+ */
+export const getThemeColor = (variable: string, fallback = ''): string => {
+    if (typeof document === 'undefined') return fallback;
+    const value = getComputedStyle(document.documentElement)
+        .getPropertyValue(variable)
+        .trim();
+    if (!value) return fallback;
+    // Already a complete color (hex / rgb / hsl / oklch / named).
+    if (
+        value.startsWith('#') ||
+        value.startsWith('rgb') ||
+        value.startsWith('hsl(') ||
+        value.startsWith('oklch') ||
+        value.startsWith('oklab') ||
+        value.startsWith('color(') ||
+        value.startsWith('var(')
+    ) {
+        return value;
+    }
+    // Bare HSL components — wrap once.
+    return `hsl(${value})`;
+};
+
+/** Resolve the diagram text color for the given theme. */
+export const getTextColor = (theme: string): string =>
+    theme === 'dark'
+        ? getThemeColor('--foreground', 'hsl(0 0% 98%)')
+        : getThemeColor('--foreground', 'hsl(222.2 84% 4.9%)');
+
+/**
+ * Diagram types whose labels sit on per-section colored backgrounds
+ * (timeline sections, journey tasks, pie slices, mindmap nodes, gitgraph
+ * commits). For these, Mermaid already picks a contrasting label color
+ * from the `cScaleLabel*` / `pie*` theme variables — re-asserting a single
+ * `--foreground` would put dark text on dark boxes (and vice versa).
+ *
+ * We detect them via the wrapper class Mermaid puts on the root `<g>` /
+ * `<svg>` and skip the blanket text override for those SVGs.
+ */
+const SECTION_COLORED_SELECTORS = [
+    '.timeline',
+    '.mindmap',
+    '[id^="mermaid"][aria-roledescription="timeline"]',
+    '[id^="mermaid"][aria-roledescription="journey"]',
+    '[id^="mermaid"][aria-roledescription="mindmap"]',
+    '[id^="mermaid"][aria-roledescription="pie"]',
+];
+
+/** True when the SVG renders a diagram type that colors its own labels. */
+const usesSectionColors = (svg: SVGSVGElement): boolean => {
+    const role = svg.getAttribute('aria-roledescription') ?? '';
+    if (['timeline', 'journey', 'mindmap', 'pie'].includes(role)) return true;
+    return SECTION_COLORED_SELECTORS.some((sel) => svg.querySelector(sel) !== null);
+};
+
+/**
+ * Apply theme text colors to a rendered Mermaid SVG.
+ *
+ * Mermaid's `base` theme bakes `themeVariables` at render time, but text
+ * fill on `<text>` nodes and `color` on foreignObject labels can drift
+ * from our tokens — this re-asserts them after render.
+ *
+ * Diagrams that color their own labels per section (timeline, journey,
+ * mindmap, pie) are skipped: their `themeVariables` already encode
+ * contrasting label colors, so a blanket override would re-introduce the
+ * dark-text-on-dark-box problem.
+ */
+export const applyMermaidTextColors = (container: HTMLElement, textColor: string): void => {
+    const svgElement = container.querySelector('svg');
+    if (!svgElement) return;
+    if (usesSectionColors(svgElement)) return;
+    // SVG text elements use 'fill'.
+    svgElement.querySelectorAll('text').forEach((el) => {
+        (el as SVGElement).style.fill = textColor;
+    });
+    // HTML elements inside foreignObject use 'color'.
+    svgElement.querySelectorAll('.nodeLabel, .edgeLabel').forEach((el) => {
+        (el as HTMLElement).style.color = textColor;
+    });
+};
+
+/**
+ * Re-color ER diagram attribute-row backgrounds.
+ *
+ * Mermaid derives the zebra-stripe fills for `.row-rect-odd` /
+ * `.row-rect-even` by lightening `mainBkg` — in dark mode the odd stripe
+ * lands on a light gray (`hsl(0 0% 83%)`) while the attribute text stays
+ * white, so it vanishes. `themeVariables` has no hook for these, so we
+ * re-assert themed fills after render.
+ *
+ * @param container Host element holding the rendered SVG.
+ * @param oddFill   Background for odd attribute rows.
+ * @param evenFill  Background for even attribute rows.
+ */
+export const applyMermaidErRowColors = (
+    container: HTMLElement,
+    oddFill: string,
+    evenFill: string,
+): void => {
+    const svgElement = container.querySelector('svg');
+    if (!svgElement) return;
+    svgElement.querySelectorAll('.row-rect-odd path').forEach((el) => {
+        const fill = (el as SVGElement).getAttribute('fill');
+        if (fill && fill !== 'none') (el as SVGElement).setAttribute('fill', oddFill);
+    });
+    svgElement.querySelectorAll('.row-rect-even path').forEach((el) => {
+        const fill = (el as SVGElement).getAttribute('fill');
+        if (fill && fill !== 'none') (el as SVGElement).setAttribute('fill', evenFill);
+    });
+};
+
+/**
+ * Detect whether a diagram is vertical (tall and narrow).
+ *
+ * Used to pick a sensible fullscreen fit. Prefers the `viewBox` (stable,
+ * available immediately) and falls back to `getBBox()` only when needed.
+ */
+export const isVerticalDiagram = (svgElement: SVGSVGElement): boolean => {
+    const viewBox = svgElement.getAttribute('viewBox');
+    if (viewBox) {
+        const [, , width, height] = viewBox.split(/\s+/).map(Number);
+        if (
+            width === undefined ||
+            height === undefined ||
+            !Number.isFinite(width) ||
+            !Number.isFinite(height) ||
+            width <= 0
+        ) {
+            return false;
+        }
+        return height > width * 1.5;
+    }
+    try {
+        const bbox = svgElement.getBBox?.();
+        if (bbox && bbox.width > 0) {
+            return bbox.height > bbox.width * 1.5;
+        }
+    } catch {
+        // getBBox throws if the SVG is not attached / not rendered.
+    }
+    return false;
+};