@djangocfg/widget-diagram 0.1.1

package/src/builders/core/DiagramStore.ts

@@ -0,0 +1,138 @@
+/**
+ * DiagramStore - Base class for building Mermaid diagrams
+ * Accumulates diagram lines with proper indentation
+ * @module Mermaid/builders/core/DiagramStore
+ */
+
+export interface DiagramStoreOptions {
+  /** Indentation string (default: '  ' - two spaces) */
+  indent?: string;
+}
+
+const DEFAULT_OPTIONS: Required<DiagramStoreOptions> = {
+  indent: '  ',
+};
+
+/**
+ * Base store for accumulating Mermaid diagram code
+ * Handles indentation and line management
+ */
+export class DiagramStore {
+  protected lines: string[] = [];
+  protected indentLevel = 0;
+  protected options: Required<DiagramStoreOptions>;
+
+  constructor(header: string, options: DiagramStoreOptions = {}) {
+    this.options = { ...DEFAULT_OPTIONS, ...options };
+    this.lines.push(header);
+  }
+
+  /**
+   * Add a line to the diagram with current indentation
+   */
+  add(line: string): this {
+    const indent = this.options.indent.repeat(this.indentLevel);
+    this.lines.push(indent + line);
+    return this;
+  }
+
+  /**
+   * Add a raw line without indentation
+   */
+  addRaw(line: string): this {
+    this.lines.push(line);
+    return this;
+  }
+
+  /**
+   * Add an empty line
+   */
+  addBlank(): this {
+    this.lines.push('');
+    return this;
+  }
+
+  /**
+   * Add a comment line
+   */
+  addComment(comment: string): this {
+    return this.add(`%% ${comment}`);
+  }
+
+  /**
+   * Increase indentation level
+   */
+  indent(): this {
+    this.indentLevel++;
+    return this;
+  }
+
+  /**
+   * Decrease indentation level
+   */
+  dedent(): this {
+    if (this.indentLevel > 0) {
+      this.indentLevel--;
+    }
+    return this;
+  }
+
+  /**
+   * Execute a callback within an indented block
+   * @param header - Block header line
+   * @param fn - Callback to execute inside the block
+   * @param footer - Block footer line (default: 'end')
+   */
+  block(header: string, fn: () => void, footer = 'end'): this {
+    this.add(header);
+    this.indent();
+    fn();
+    this.dedent();
+    this.add(footer);
+    return this;
+  }
+
+  /**
+   * Execute a callback within a subgraph block
+   * @param name - Subgraph name/title
+   * @param fn - Callback to execute inside the subgraph
+   */
+  subgraph(name: string, fn: () => void): this {
+    return this.block(`subgraph ${name}`, fn);
+  }
+
+  /**
+   * Add direction directive (for subgraphs)
+   */
+  direction(dir: 'TB' | 'BT' | 'LR' | 'RL'): this {
+    return this.add(`direction ${dir}`);
+  }
+
+  /**
+   * Get the current indentation string
+   */
+  getIndent(): string {
+    return this.options.indent.repeat(this.indentLevel);
+  }
+
+  /**
+   * Get the current indentation level
+   */
+  getIndentLevel(): number {
+    return this.indentLevel;
+  }
+
+  /**
+   * Convert the diagram to a Mermaid string
+   */
+  toString(): string {
+    return this.lines.join('\n');
+  }
+
+  /**
+   * Get all lines (for debugging)
+   */
+  getLines(): readonly string[] {
+    return this.lines;
+  }
+}

package/src/builders/core/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Core exports for Mermaid builders
+ * @module Mermaid/builders/core
+ */
+
+export { DiagramStore, type DiagramStoreOptions } from './DiagramStore';
+export * from './types';
+export * from './theme';

package/src/builders/core/sanitize.ts

@@ -0,0 +1,83 @@
+/**
+ * Sanitization utilities for Mermaid diagrams
+ * @module Mermaid/builders/core/sanitize
+ */
+
+/**
+ * Characters that need to be escaped or removed in Mermaid labels
+ */
+const UNSAFE_CHARS = /["\n\r\\<>{}|]/g;
+
+/**
+ * Mermaid reserved keywords that cannot be used as node IDs.
+ *
+ * Stored LOWERCASE because the lookup lowercases its input. Held as `classDef`
+ * and `linkStyle`, those two never matched — a node called `classDef` emitted a
+ * style directive where a node was meant, and what followed was read as its
+ * arguments.
+ */
+const RESERVED_WORDS = new Set([
+  'end',
+  'graph',
+  'subgraph',
+  'direction',
+  'click',
+  'style',
+  'class',
+  'classdef',
+  'linkstyle',
+  'callback',
+]);
+
+/**
+ * Sanitize a label for use in Mermaid diagrams
+ * Removes or escapes characters that could break the diagram syntax
+ */
+export function sanitizeLabel(label: string): string {
+  return label
+    .replace(UNSAFE_CHARS, '')
+    .replace(/&/g, '&amp;')
+    .replace(/'/g, "'")
+    .trim();
+}
+
+/**
+ * Convert an ID to a valid Mermaid node ID
+ * - Removes special characters
+ * - Adds optional prefix to ensure uniqueness
+ * - Ensures ID starts with a letter
+ * - Escapes reserved Mermaid keywords
+ */
+export function toNodeId(id: string, prefix = ''): string {
+  // Remove special characters and spaces
+  const cleanId = id.replace(/[^a-zA-Z0-9_]/g, '_');
+
+  // Ensure starts with letter
+  let safeId = /^[a-zA-Z]/.test(cleanId) ? cleanId : `n${cleanId}`;
+
+  // Escape reserved words by adding underscore suffix
+  if (RESERVED_WORDS.has(safeId.toLowerCase())) {
+    safeId = `${safeId}_`;
+  }
+
+  return prefix ? `${prefix}_${safeId}` : safeId;
+}
+
+/**
+ * Escape a string for use in quoted Mermaid labels
+ */
+export function escapeQuoted(str: string): string {
+  return str
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '<br/>');
+}
+
+/**
+ * Format a label with optional subtitle using HTML-like syntax
+ */
+export function formatLabel(main: string, subtitle?: string): string {
+  const sanitized = sanitizeLabel(main);
+  if (!subtitle) return sanitized;
+  return `${sanitized}<br/><small>${sanitizeLabel(subtitle)}</small>`;
+}

package/src/builders/core/theme.ts

@@ -0,0 +1,42 @@
+/**
+ * Theme utilities for Mermaid builders
+ *
+ * Re-exports palette hooks from @djangocfg/ui-core for convenience.
+ *
+ * @example
+ * ```tsx
+ * import { useStylePresets, useBoxColors } from './theme';
+ *
+ * function MyDiagram() {
+ *   const presets = useStylePresets();
+ *   const boxes = useBoxColors();
+ *
+ *   const flow = FlowDiagram();
+ *   flow.style.define('success', presets.success);
+ *
+ *   const { rect } = SequenceDiagram({ ... });
+ *   rect(boxes.primary, () => { ... });
+ * }
+ * ```
+ *
+ * @module Mermaid/builders/core/theme
+ */
+
+// Re-export from ui-core palette
+export {
+  // Types
+  type ThemePalette,
+  type StyleColors,
+  type StylePresets,
+  type BoxColors,
+
+  // Hooks
+  useThemePalette,
+  useStylePresets,
+  useBoxColors,
+
+  // Utils
+  hslToHex,
+  hslToRgbString,
+  hslToRgba,
+} from '@djangocfg/ui-core/styles/palette';

package/src/builders/core/types.ts

@@ -0,0 +1,183 @@
+/**
+ * Shared types for Mermaid diagram builders
+ * @module Mermaid/builders/core/types
+ */
+
+// ============================================================================
+// Node Types
+// ============================================================================
+
+export type NodeId = string;
+
+/**
+ * Node shapes supported by Mermaid flowcharts
+ * @see https://mermaid.js.org/syntax/flowchart.html#node-shapes
+ */
+export type NodeShape =
+  | 'rect'           // [text]
+  | 'round'          // (text)
+  | 'stadium'        // ([text])
+  | 'subroutine'     // [[text]]
+  | 'cylinder'       // [(text)]
+  | 'circle'         // ((text))
+  | 'asymmetric'     // >text]
+  | 'rhombus'        // {text}
+  | 'hexagon'        // {{text}}
+  | 'parallelogram'  // [/text/]
+  | 'parallelogramAlt' // [\text\]
+  | 'trapezoid'      // [/text\]
+  | 'trapezoidAlt'   // [\text/]
+  | 'doubleCircle';  // (((text)))
+
+/**
+ * Shape syntax lookup for Mermaid
+ */
+export const NODE_SHAPE_SYNTAX: Record<NodeShape, [string, string]> = {
+  rect: ['[', ']'],
+  round: ['(', ')'],
+  stadium: ['([', '])'],
+  subroutine: ['[[', ']]'],
+  cylinder: ['[(', ')]'],
+  circle: ['((', '))'],
+  asymmetric: ['>', ']'],
+  rhombus: ['{', '}'],
+  hexagon: ['{{', '}}'],
+  parallelogram: ['[/', '/]'],
+  parallelogramAlt: ['[\\', '\\]'],
+  trapezoid: ['[/', '\\]'],
+  trapezoidAlt: ['[\\', '/]'],
+  doubleCircle: ['(((', ')))'],
+};
+
+// ============================================================================
+// Edge Types
+// ============================================================================
+
+/**
+ * Edge line styles
+ */
+export type EdgeLineStyle = 'solid' | 'dotted' | 'thick';
+
+/**
+ * Arrow head types
+ */
+export type ArrowHead = 'arrow' | 'open' | 'circle' | 'cross' | 'none';
+
+/**
+ * Edge syntax lookup
+ */
+export const EDGE_SYNTAX: Record<EdgeLineStyle, Record<ArrowHead, string>> = {
+  solid: {
+    arrow: '-->',
+    open: '---',
+    circle: '--o',
+    cross: '--x',
+    none: '---',
+  },
+  dotted: {
+    arrow: '-..->',
+    open: '-.-',
+    circle: '-.-o',
+    cross: '-.-x',
+    none: '-.-',
+  },
+  thick: {
+    arrow: '==>',
+    open: '===',
+    circle: '==o',
+    cross: '==x',
+    none: '===',
+  },
+};
+
+/**
+ * Simplified edge syntax for common cases
+ */
+export const SIMPLE_EDGE_SYNTAX = {
+  solid: '-->',
+  dotted: '-.->',
+  thick: '==>',
+  solidOpen: '---',
+  dottedOpen: '-.-',
+} as const;
+
+// ============================================================================
+// Style Types
+// ============================================================================
+
+/**
+ * CSS-like style properties for nodes
+ */
+export interface StyleProperties {
+  fill?: string;
+  stroke?: string;
+  'stroke-width'?: string;
+  color?: string;
+  'font-weight'?: 'bold' | 'normal';
+  'stroke-dasharray'?: string;
+}
+
+/**
+ * Style class definition
+ */
+export interface StyleClass {
+  name: string;
+  properties: StyleProperties;
+}
+
+// ============================================================================
+// Flow Diagram Types
+// ============================================================================
+
+/**
+ * Flow diagram directions
+ */
+export type FlowDirection = 'TB' | 'BT' | 'LR' | 'RL';
+
+// ============================================================================
+// Sequence Diagram Types
+// ============================================================================
+
+/**
+ * Participant types in sequence diagrams
+ */
+export type ParticipantType = 'participant' | 'actor';
+
+/**
+ * Message arrow types in sequence diagrams
+ */
+export const MESSAGE_ARROWS = {
+  sync: '->>',        // Synchronous call
+  syncReply: '-->>',  // Synchronous reply
+  async: '-)',        // Async call
+  asyncReply: '--)',  // Async reply
+  solid: '->',        // Solid line
+  dotted: '-->',      // Dotted line
+  cross: '-x',        // Cross (failure)
+  crossDotted: '--x', // Dotted cross
+} as const;
+
+export type MessageArrowType = keyof typeof MESSAGE_ARROWS;
+
+// ============================================================================
+// Journey Diagram Types
+// ============================================================================
+
+/**
+ * Task score (1-5, where 5 is best)
+ */
+export type TaskScore = 1 | 2 | 3 | 4 | 5;
+
+// ============================================================================
+// Utility Types
+// ============================================================================
+
+/**
+ * Makes all properties in T writable (removes readonly)
+ */
+export type Writable<T> = { -readonly [P in keyof T]: T[P] };
+
+/**
+ * Extracts keys from a const object
+ */
+export type KeysOf<T> = keyof T & string;

package/src/builders/index.ts

@@ -0,0 +1,96 @@
+/**
+ * Mermaid Diagram Builders
+ *
+ * Declarative, type-safe builders for creating Mermaid diagrams.
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   FlowDiagram,
+ *   SequenceDiagram,
+ *   JourneyDiagram,
+ *   useStylePresets,
+ *   useBoxColors
+ * } from '@djangocfg/widget-diagram';
+ *
+ * function MyDiagram() {
+ *   const presets = useStylePresets();
+ *   const boxes = useBoxColors();
+ *
+ *   // Flow diagram
+ *   const flow = FlowDiagram<'A' | 'B'>({ direction: 'LR' });
+ *   flow.node('A').rect('Start');
+ *   flow.edge('A').to('B').solid();
+ *   flow.style.define('highlight', presets.success);
+ *
+ *   // Sequence diagram
+ *   const { d, rect } = SequenceDiagram({
+ *     Alice: 'participant',
+ *     Bob: 'actor',
+ *   });
+ *   rect(boxes.primary, () => {
+ *     d.Alice.sync.Bob.msg('Hello!');
+ *   });
+ *
+ *   // Journey diagram
+ *   const journey = JourneyDiagram({ title: 'User Flow' });
+ *   journey.section('Start').task('Open app', 5, 'User');
+ * }
+ * ```
+ *
+ * @module Mermaid/builders
+ */
+
+// Core
+export { DiagramStore, type DiagramStoreOptions } from './core/DiagramStore';
+export { sanitizeLabel, toNodeId, escapeQuoted, formatLabel } from './core/sanitize';
+export * from './core/types';
+
+// Theme hooks and utilities (re-exported from @djangocfg/ui-core/styles/palette)
+export {
+  useThemePalette,
+  useStylePresets,
+  useBoxColors,
+  hslToHex,
+  hslToRgbString,
+  hslToRgba,
+  type ThemePalette,
+  type StyleColors,
+  type StylePresets,
+  type BoxColors,
+} from './core/theme';
+
+// FlowDiagram
+export { FlowDiagram, STYLE_PRESETS } from './FlowDiagram';
+export type {
+  FlowDiagramOptions,
+  FlowDiagramBuilder,
+  NodeBuilder,
+  EdgeBuilder,
+  EdgeEndBuilder,
+  StyleBuilder,
+  SubgraphBuilder,
+} from './FlowDiagram';
+
+// SequenceDiagram
+export { SequenceDiagram } from './SequenceDiagram';
+export type {
+  ParticipantsObject,
+  SequenceDiagramOptions,
+  SequenceDiagramBuilder,
+  MessageBuilder,
+  MessageArrows,
+  MessageTarget,
+  MessageAction,
+  NoteBuilder,
+  ActivationBuilder,
+} from './SequenceDiagram';
+
+// JourneyDiagram
+export { JourneyDiagram } from './JourneyDiagram';
+export type {
+  JourneyDiagramOptions,
+  JourneyDiagramBuilder,
+  SectionBuilder,
+  TaskDefinition,
+} from './JourneyDiagram';

package/src/components/MermaidCodeViewer.tsx

@@ -0,0 +1,95 @@
+'use client';
+
+import React, { useState } from 'react';
+
+interface MermaidCodeViewerProps {
+    chart: string;
+    renderPreview: () => React.ReactNode;
+}
+
+export const MermaidCodeViewer: React.FC<MermaidCodeViewerProps> = ({
+    chart,
+    renderPreview,
+}) => {
+    const [activeTab, setActiveTab] = useState<'preview' | 'code'>('preview');
+    const [copied, setCopied] = useState(false);
+
+    const handleCopy = async () => {
+        await navigator.clipboard.writeText(chart);
+        setCopied(true);
+        setTimeout(() => setCopied(false), 2000);
+    };
+
+    return (
+        <div className="flex flex-col h-full">
+            {/* Tabs */}
+            <div className="flex items-center justify-between border-b border-border px-4">
+                <div className="flex">
+                    <button
+                        onClick={() => setActiveTab('preview')}
+                        className={`px-4 py-3 text-sm font-medium transition-colors relative ${
+                            activeTab === 'preview'
+                                ? 'text-foreground'
+                                : 'text-muted-foreground hover:text-foreground'
+                        }`}
+                    >
+                        Preview
+                        {activeTab === 'preview' && (
+                            <div className="absolute bottom-0 left-0 right-0 h-0.5 bg-primary" />
+                        )}
+                    </button>
+                    <button
+                        onClick={() => setActiveTab('code')}
+                        className={`px-4 py-3 text-sm font-medium transition-colors relative ${
+                            activeTab === 'code'
+                                ? 'text-foreground'
+                                : 'text-muted-foreground hover:text-foreground'
+                        }`}
+                    >
+                        Code
+                        {activeTab === 'code' && (
+                            <div className="absolute bottom-0 left-0 right-0 h-0.5 bg-primary" />
+                        )}
+                    </button>
+                </div>
+
+                {/* Copy button - show only on Code tab */}
+                {activeTab === 'code' && (
+                    <button
+                        onClick={handleCopy}
+                        className="flex items-center gap-2 px-3 py-1.5 text-xs font-medium bg-primary/10 hover:bg-primary/20 text-primary rounded transition-colors"
+                    >
+                        {copied ? (
+                            <>
+                                <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M5 13l4 4L19 7" />
+                                </svg>
+                                Copied!
+                            </>
+                        ) : (
+                            <>
+                                <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M8 16H6a2 2 0 01-2-2V6a2 2 0 012-2h8a2 2 0 012 2v2m-6 12h8a2 2 0 002-2v-8a2 2 0 00-2-2h-8a2 2 0 00-2 2v8a2 2 0 002 2z" />
+                                </svg>
+                                Copy
+                            </>
+                        )}
+                    </button>
+                )}
+            </div>
+
+            {/* Content */}
+            <div className="flex-1 overflow-auto">
+                {activeTab === 'preview' ? (
+                    <div className="p-6 flex items-center justify-center min-h-full">
+                        {renderPreview()}
+                    </div>
+                ) : (
+                    <pre className="p-6 text-sm font-mono text-foreground bg-muted/30 h-full overflow-auto">
+                        <code>{chart}</code>
+                    </pre>
+                )}
+            </div>
+        </div>
+    );
+};

package/src/components/MermaidErrorPanel.tsx

@@ -0,0 +1,31 @@
+'use client';
+
+import React from 'react';
+import { AlertTriangle } from 'lucide-react';
+
+interface MermaidErrorPanelProps {
+    /** Human-readable error message from the Mermaid parser. */
+    message: string;
+}
+
+/**
+ * Inline error panel shown when a Mermaid diagram fails to parse.
+ *
+ * Replaces the previous `innerHTML`-injected markup — keeps rendering in
+ * React, uses semantic `destructive` tokens, and stays accessible
+ * (`role="alert"`).
+ */
+export const MermaidErrorPanel: React.FC<MermaidErrorPanelProps> = ({ message }) => {
+    return (
+        <div
+            role="alert"
+            className="flex items-start gap-3 rounded-md border border-destructive/30 bg-destructive/10 p-4 text-destructive"
+        >
+            <AlertTriangle className="mt-0.5 h-4 w-4 shrink-0" aria-hidden="true" />
+            <div className="min-w-0">
+                <p className="text-sm font-semibold">Diagram syntax error</p>
+                <p className="mt-0.5 break-words text-sm text-destructive/90">{message}</p>
+            </div>
+        </div>
+    );
+};