@djangocfg/widget-diagram 0.1.1

package/src/Mermaid.client.tsx

@@ -0,0 +1,97 @@
+'use client';
+
+import React, { useRef } from 'react';
+
+import { useResolvedTheme } from '@djangocfg/ui-core/hooks';
+import { FloatingToolbar } from './FloatingToolbar';
+import { CopyAction, FullscreenAction } from './FloatingToolbar/actions';
+import { MermaidErrorPanel } from './components/MermaidErrorPanel';
+import { MermaidFullscreenModal } from './components/MermaidFullscreenModal';
+import { useMermaidFullscreen } from './hooks/useMermaidFullscreen';
+import { useMermaidRenderer } from './hooks/useMermaidRenderer';
+import type { MermaidProps } from './types';
+
+
+const Mermaid: React.FC<MermaidProps> = ({
+    chart,
+    className = '',
+    isCompact = false,
+    fullscreen = true,
+    scrollIsolation = false,
+    debounceMs = 300,
+}) => {
+    const containerRef = useRef<HTMLDivElement>(null);
+    const theme = useResolvedTheme();
+
+    // Rendering logic
+    const { mermaidRef, svgContent, isVertical, isRendering, error } = useMermaidRenderer({
+        chart,
+        theme,
+        isCompact,
+        debounceMs,
+    });
+
+    // Fullscreen modal logic (only used if fullscreen prop is true)
+    const {
+        isFullscreen,
+        fullscreenRef,
+        openFullscreen,
+        closeFullscreen,
+        handleBackdropClick,
+    } = useMermaidFullscreen();
+
+    // Hoist derived UI state out of JSX (data-before-JSX).
+    const hasError = error !== null;
+    // The spinner needs a box to sit in while the first diagram renders
+    // (empty SVG host has no intrinsic height).
+    const showPlaceholderHeight = isRendering && !svgContent && !hasError;
+    const showToolbar = !!svgContent && !isRendering && !hasError;
+
+    return (
+        <>
+            <div ref={containerRef} className={`relative ${className}`}>
+                {hasError && <MermaidErrorPanel message={error} />}
+
+                <div
+                    ref={mermaidRef}
+                    className="flex justify-center items-center"
+                    style={{
+                        isolation: 'isolate',
+                        minHeight: showPlaceholderHeight ? 100 : undefined,
+                        display: hasError ? 'none' : undefined,
+                    }}
+                />
+
+                {isRendering && !hasError && (
+                    <div className="absolute inset-0 flex items-center justify-center pointer-events-none">
+                        <div className="animate-spin rounded-full h-6 w-6 border-b-2 border-primary" />
+                    </div>
+                )}
+
+                {showToolbar && (
+                    <FloatingToolbar containerRef={containerRef} scrollIsolation={scrollIsolation}>
+                        <CopyAction value={chart} title="Copy source" />
+                        {fullscreen && (
+                            <FullscreenAction onToggle={openFullscreen} title="Fullscreen" />
+                        )}
+                    </FloatingToolbar>
+                )}
+            </div>
+
+            {fullscreen && (
+                <MermaidFullscreenModal
+                    isOpen={isFullscreen}
+                    svgContent={svgContent}
+                    isVertical={isVertical}
+                    theme={theme}
+                    chart={chart}
+                    fullscreenRef={fullscreenRef}
+                    onClose={closeFullscreen}
+                    onBackdropClick={handleBackdropClick}
+                />
+            )}
+        </>
+    );
+};
+
+export default Mermaid;

package/src/builders/FlowDiagram/FlowDiagram.ts

@@ -0,0 +1,96 @@
+/**
+ * FlowDiagram Builder
+ * Declarative API for building Mermaid flowchart diagrams
+ * @module Mermaid/builders/FlowDiagram/FlowDiagram
+ */
+
+import { DiagramStore } from '../core/DiagramStore';
+import type { FlowDirection } from '../core/types';
+import { createNodeBuilder } from './functions/getNodes';
+import { createEdgeBuilder } from './functions/getEdges';
+import { createStyleBuilder } from './functions/getStyles';
+import type {
+  FlowDiagramOptions,
+  FlowDiagramBuilder,
+  SubgraphBuilder,
+  NodeBuilder,
+} from './types';
+
+const DEFAULT_OPTIONS: Required<FlowDiagramOptions> = {
+  direction: 'TB',
+};
+
+/**
+ * Create a FlowDiagram builder
+ *
+ * @example
+ * ```typescript
+ * const flow = FlowDiagram<'A' | 'B' | 'C'>({ direction: 'LR' });
+ *
+ * flow.node('A').rect('Start');
+ * flow.node('B').circle('Process');
+ * flow.node('C').rect('End');
+ *
+ * flow.edge('A').to('B').solid();
+ * flow.edge('B').to('C').dotted('optional');
+ *
+ * flow.style.define('highlight', { fill: '#ff0', stroke: '#f00' });
+ * flow.style.apply('highlight', 'B');
+ *
+ * console.log(flow.toString());
+ * ```
+ *
+ * @param options - Diagram options
+ * @returns FlowDiagram builder instance
+ */
+export function FlowDiagram<Nodes extends string = string>(
+  options: FlowDiagramOptions = {},
+): FlowDiagramBuilder<Nodes> {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const store = new DiagramStore(`graph ${opts.direction}`);
+  const styleBuilder = createStyleBuilder(store);
+
+  /**
+   * Create a subgraph builder that operates within the subgraph context
+   */
+  const createSubgraphBuilder = (): SubgraphBuilder<Nodes> => ({
+    direction(dir: FlowDirection) {
+      store.add(`direction ${dir}`);
+    },
+    node(id: Nodes): NodeBuilder<Nodes> {
+      return createNodeBuilder<Nodes>(store, id);
+    },
+  });
+
+  return {
+    node(id: Nodes): NodeBuilder<Nodes> {
+      return createNodeBuilder<Nodes>(store, id);
+    },
+
+    edge(from: Nodes) {
+      return createEdgeBuilder<Nodes>(store, from);
+    },
+
+    subgraph(name: string, fn: (sub: SubgraphBuilder<Nodes>) => void) {
+      store.add(`subgraph ${name}`);
+      store.indent();
+      fn(createSubgraphBuilder());
+      store.dedent();
+      store.add('end');
+    },
+
+    style: styleBuilder,
+
+    comment(text: string) {
+      store.addComment(text);
+    },
+
+    blank() {
+      store.addBlank();
+    },
+
+    toString() {
+      return store.toString();
+    },
+  };
+}

package/src/builders/FlowDiagram/functions/getEdges.ts

@@ -0,0 +1,50 @@
+/**
+ * Edge builder functions for FlowDiagram
+ * @module Mermaid/builders/FlowDiagram/functions/getEdges
+ */
+
+import { DiagramStore } from '../../core/DiagramStore';
+import { SIMPLE_EDGE_SYNTAX } from '../../core/types';
+import { toNodeId, sanitizeLabel } from '../../core/sanitize';
+import type { EdgeBuilder, EdgeEndBuilder } from '../types';
+
+/**
+ * Create an edge builder for a specific source node
+ */
+export function createEdgeBuilder<Nodes extends string>(
+  store: DiagramStore,
+  fromId: Nodes,
+): EdgeBuilder<Nodes> {
+  const safeFromId = toNodeId(fromId);
+
+  return {
+    to(toId: Nodes): EdgeEndBuilder {
+      const safeToId = toNodeId(toId);
+
+      const addEdge = (arrow: string, label?: string) => {
+        if (label) {
+          store.add(`${safeFromId} ${arrow}|${sanitizeLabel(label)}| ${safeToId}`);
+        } else {
+          store.add(`${safeFromId} ${arrow} ${safeToId}`);
+        }
+      };
+
+      return {
+        solid: (label) => addEdge(SIMPLE_EDGE_SYNTAX.solid, label),
+        dotted: (label) => addEdge(SIMPLE_EDGE_SYNTAX.dotted, label),
+        thick: (label) => addEdge(SIMPLE_EDGE_SYNTAX.thick, label),
+        line: (label) => addEdge(SIMPLE_EDGE_SYNTAX.solidOpen, label),
+        dottedLine: (label) => addEdge(SIMPLE_EDGE_SYNTAX.dottedOpen, label),
+      };
+    },
+  };
+}
+
+/**
+ * Create multiple edges at once (for convenience)
+ */
+export function createEdgesBuilder<Nodes extends string>(
+  store: DiagramStore,
+): (from: Nodes) => EdgeBuilder<Nodes> {
+  return (from: Nodes) => createEdgeBuilder(store, from);
+}

package/src/builders/FlowDiagram/functions/getNodes.ts

@@ -0,0 +1,43 @@
+/**
+ * Node builder functions for FlowDiagram
+ * @module Mermaid/builders/FlowDiagram/functions/getNodes
+ */
+
+import { DiagramStore } from '../../core/DiagramStore';
+import { NODE_SHAPE_SYNTAX, type NodeShape } from '../../core/types';
+import { formatLabel, toNodeId } from '../../core/sanitize';
+import type { NodeBuilder } from '../types';
+
+/**
+ * Create a node builder for a specific node ID
+ */
+export function createNodeBuilder<Nodes extends string>(
+  store: DiagramStore,
+  nodeId: Nodes,
+): NodeBuilder<Nodes> {
+  const safeId = toNodeId(nodeId);
+
+  const addNode = (shape: NodeShape, label: string, subtitle?: string) => {
+    const [open, close] = NODE_SHAPE_SYNTAX[shape];
+    const formattedLabel = formatLabel(label, subtitle);
+
+    // Use quoted format for complex labels
+    if (subtitle || label.includes(' ') || label.includes(':')) {
+      store.add(`${safeId}${open}"${formattedLabel}"${close}`);
+    } else {
+      store.add(`${safeId}${open}${formattedLabel}${close}`);
+    }
+  };
+
+  return {
+    rect: (label, subtitle) => addNode('rect', label, subtitle),
+    round: (label, subtitle) => addNode('round', label, subtitle),
+    stadium: (label, subtitle) => addNode('stadium', label, subtitle),
+    circle: (label, subtitle) => addNode('circle', label, subtitle),
+    rhombus: (label, subtitle) => addNode('rhombus', label, subtitle),
+    hexagon: (label, subtitle) => addNode('hexagon', label, subtitle),
+    cylinder: (label, subtitle) => addNode('cylinder', label, subtitle),
+    subroutine: (label, subtitle) => addNode('subroutine', label, subtitle),
+    doubleCircle: (label, subtitle) => addNode('doubleCircle', label, subtitle),
+  };
+}

package/src/builders/FlowDiagram/functions/getStyles.ts

@@ -0,0 +1,90 @@
+/**
+ * Style builder functions for FlowDiagram
+ * @module Mermaid/builders/FlowDiagram/functions/getStyles
+ */
+
+import { DiagramStore } from '../../core/DiagramStore';
+import type { StyleProperties } from '../../core/types';
+import { toNodeId } from '../../core/sanitize';
+import type { StyleBuilder } from '../types';
+
+/**
+ * Convert style properties to Mermaid classDef syntax
+ */
+function propertiesToString(properties: StyleProperties): string {
+  const parts: string[] = [];
+
+  if (properties.fill) parts.push(`fill:${properties.fill}`);
+  if (properties.stroke) parts.push(`stroke:${properties.stroke}`);
+  if (properties['stroke-width']) parts.push(`stroke-width:${properties['stroke-width']}`);
+  if (properties.color) parts.push(`color:${properties.color}`);
+  if (properties['font-weight']) parts.push(`font-weight:${properties['font-weight']}`);
+  if (properties['stroke-dasharray']) parts.push(`stroke-dasharray:${properties['stroke-dasharray']}`);
+
+  return parts.join(',');
+}
+
+/**
+ * Create a style builder
+ */
+export function createStyleBuilder(store: DiagramStore): StyleBuilder {
+  return {
+    define(name: string, properties: StyleProperties): void {
+      const propsStr = propertiesToString(properties);
+      store.add(`classDef ${name} ${propsStr}`);
+    },
+
+    apply(className: string, ...nodeIds: string[]): void {
+      if (nodeIds.length === 0) return;
+      const safeIds = nodeIds.map((id) => toNodeId(id)).join(',');
+      store.add(`class ${safeIds} ${className}`);
+    },
+  };
+}
+
+// ============================================================================
+// Predefined Style Classes (Common patterns)
+// ============================================================================
+
+/**
+ * Common style presets for quick use
+ */
+export const STYLE_PRESETS = {
+  /** Green success style */
+  success: {
+    fill: '#22c55e',
+    stroke: '#16a34a',
+    color: '#fff',
+  },
+  /** Blue primary style */
+  primary: {
+    fill: '#3b82f6',
+    stroke: '#1d4ed8',
+    color: '#fff',
+  },
+  /** Red error/danger style */
+  danger: {
+    fill: '#ef4444',
+    stroke: '#dc2626',
+    color: '#fff',
+  },
+  /** Yellow warning style */
+  warning: {
+    fill: '#f59e0b',
+    stroke: '#d97706',
+    color: '#fff',
+  },
+  /** Gray muted style */
+  muted: {
+    fill: '#6b7280',
+    stroke: '#4b5563',
+    color: '#fff',
+  },
+  /** Emerald/teal accent */
+  accent: {
+    fill: '#10b981',
+    stroke: '#047857',
+    color: '#fff',
+    'font-weight': 'bold' as const,
+  },
+} satisfies Record<string, StyleProperties>;

package/src/builders/FlowDiagram/functions/index.ts

@@ -0,0 +1,8 @@
+/**
+ * FlowDiagram function exports
+ * @module Mermaid/builders/FlowDiagram/functions
+ */
+
+export { createNodeBuilder } from './getNodes';
+export { createEdgeBuilder, createEdgesBuilder } from './getEdges';
+export { createStyleBuilder, STYLE_PRESETS } from './getStyles';

package/src/builders/FlowDiagram/index.ts

@@ -0,0 +1,16 @@
+/**
+ * FlowDiagram builder exports
+ * @module Mermaid/builders/FlowDiagram
+ */
+
+export { FlowDiagram } from './FlowDiagram';
+export { STYLE_PRESETS } from './functions/getStyles';
+export type {
+  FlowDiagramOptions,
+  FlowDiagramBuilder,
+  NodeBuilder,
+  EdgeBuilder,
+  EdgeEndBuilder,
+  StyleBuilder,
+  SubgraphBuilder,
+} from './types';

package/src/builders/FlowDiagram/types.ts

@@ -0,0 +1,130 @@
+/**
+ * Types for FlowDiagram builder
+ * @module Mermaid/builders/FlowDiagram/types
+ */
+
+import type { FlowDirection, NodeShape, StyleProperties } from '../core/types';
+
+/**
+ * Options for FlowDiagram builder
+ */
+export interface FlowDiagramOptions {
+  /** Diagram direction (default: 'TB') */
+  direction?: FlowDirection;
+}
+
+/**
+ * Node definition
+ */
+export interface NodeDefinition {
+  id: string;
+  label: string;
+  shape: NodeShape;
+  subtitle?: string;
+}
+
+/**
+ * Edge definition
+ */
+export interface EdgeDefinition {
+  from: string;
+  to: string;
+  label?: string;
+  style: 'solid' | 'dotted' | 'thick';
+}
+
+/**
+ * Style class definition for flow diagrams
+ */
+export interface FlowStyleClass {
+  name: string;
+  properties: StyleProperties;
+}
+
+/**
+ * Node builder interface - chainable API for creating nodes
+ */
+export interface NodeBuilder<Nodes extends string> {
+  /** Create a rectangular node [label] */
+  rect(label: string, subtitle?: string): void;
+  /** Create a rounded node (label) */
+  round(label: string, subtitle?: string): void;
+  /** Create a stadium/pill node ([label]) */
+  stadium(label: string, subtitle?: string): void;
+  /** Create a circular node ((label)) */
+  circle(label: string, subtitle?: string): void;
+  /** Create a rhombus/diamond node {label} */
+  rhombus(label: string, subtitle?: string): void;
+  /** Create a hexagon node {{label}} */
+  hexagon(label: string, subtitle?: string): void;
+  /** Create a cylinder/database node [(label)] */
+  cylinder(label: string, subtitle?: string): void;
+  /** Create a subroutine node [[label]] */
+  subroutine(label: string, subtitle?: string): void;
+  /** Create a double circle node (((label))) */
+  doubleCircle(label: string, subtitle?: string): void;
+}
+
+/**
+ * Edge builder interface - chainable API for creating edges
+ */
+export interface EdgeBuilder<Nodes extends string> {
+  /** Target node for the edge */
+  to(target: Nodes): EdgeEndBuilder;
+}
+
+/**
+ * Edge end builder - configures the edge after target is specified
+ */
+export interface EdgeEndBuilder {
+  /** Solid arrow --> */
+  solid(label?: string): void;
+  /** Dotted arrow -.-> */
+  dotted(label?: string): void;
+  /** Thick arrow ==> */
+  thick(label?: string): void;
+  /** Solid line without arrow --- */
+  line(label?: string): void;
+  /** Dotted line without arrow -.- */
+  dottedLine(label?: string): void;
+}
+
+/**
+ * Style builder interface
+ */
+export interface StyleBuilder {
+  /** Define a style class */
+  define(name: string, properties: StyleProperties): void;
+  /** Apply a class to nodes */
+  apply(className: string, ...nodeIds: string[]): void;
+}
+
+/**
+ * Subgraph builder interface
+ */
+export interface SubgraphBuilder<Nodes extends string> {
+  /** Set direction inside subgraph */
+  direction(dir: FlowDirection): void;
+  /** Create a node inside subgraph */
+  node(id: Nodes): NodeBuilder<Nodes>;
+}
+
+/**
+ * Main FlowDiagram builder result
+ */
+export interface FlowDiagramBuilder<Nodes extends string> {
+  /** Create a node */
+  node: (id: Nodes) => NodeBuilder<Nodes>;
+  /** Create an edge from a node */
+  edge: (from: Nodes) => EdgeBuilder<Nodes>;
+  /** Create a subgraph */
+  subgraph: (name: string, fn: (sub: SubgraphBuilder<Nodes>) => void) => void;
+  /** Style utilities */
+  style: StyleBuilder;
+  /** Add a comment */
+  comment: (text: string) => void;
+  /** Add a blank line */
+  blank: () => void;
+  /** Get the Mermaid string */
+  toString: () => string;
+}

package/src/builders/JourneyDiagram/JourneyDiagram.ts

@@ -0,0 +1,88 @@
+/**
+ * JourneyDiagram Builder
+ * Declarative API for building Mermaid user journey diagrams
+ * @module Mermaid/builders/JourneyDiagram/JourneyDiagram
+ */
+
+import { DiagramStore } from '../core/DiagramStore';
+import type { TaskScore } from '../core/types';
+import { sanitizeLabel } from '../core/sanitize';
+import type { JourneyDiagramOptions, JourneyDiagramBuilder, SectionBuilder } from './types';
+
+/**
+ * Format actors for journey task
+ */
+function formatActors(actors: string | string[]): string {
+  if (Array.isArray(actors)) {
+    return actors.map(sanitizeLabel).join(', ');
+  }
+  return sanitizeLabel(actors);
+}
+
+/**
+ * Create a JourneyDiagram builder
+ *
+ * @example
+ * ```typescript
+ * const journey = JourneyDiagram({ title: 'User Registration Flow' });
+ *
+ * journey.section('Discovery')
+ *   .task('Visit website', 5, 'User')
+ *   .task('Read about product', 4, 'User');
+ *
+ * journey.section('Registration')
+ *   .task('Click sign up', 5, 'User')
+ *   .task('Fill form', 2, 'User')
+ *   .task('Verify email', 3, ['User', 'System']);
+ *
+ * journey.section('Onboarding')
+ *   .task('Complete profile', 4, 'User')
+ *   .task('Start using app', 5, 'User');
+ *
+ * console.log(journey.toString());
+ * ```
+ *
+ * @param options - Diagram options (title is required)
+ * @returns JourneyDiagram builder instance
+ */
+export function JourneyDiagram(options: JourneyDiagramOptions): JourneyDiagramBuilder {
+  const store = new DiagramStore('journey');
+  store.add(`title ${sanitizeLabel(options.title)}`);
+
+  /**
+   * Add a task line
+   */
+  const addTask = (name: string, score: TaskScore, actors: string | string[]) => {
+    const actorStr = formatActors(actors);
+    store.add(`${sanitizeLabel(name)}: ${score}: ${actorStr}`);
+  };
+
+  /**
+   * Create a section builder for chaining tasks
+   */
+  const createSectionBuilder = (): SectionBuilder => ({
+    task(name: string, score: TaskScore, actors: string | string[]) {
+      addTask(name, score, actors);
+      return this;
+    },
+  });
+
+  return {
+    section(name: string) {
+      store.add(`section ${sanitizeLabel(name)}`);
+      return createSectionBuilder();
+    },
+
+    task(name: string, score: TaskScore, actors: string | string[]) {
+      addTask(name, score, actors);
+    },
+
+    comment(text: string) {
+      store.addComment(text);
+    },
+
+    toString() {
+      return store.toString();
+    },
+  };
+}

package/src/builders/JourneyDiagram/index.ts

@@ -0,0 +1,12 @@
+/**
+ * JourneyDiagram builder exports
+ * @module Mermaid/builders/JourneyDiagram
+ */
+
+export { JourneyDiagram } from './JourneyDiagram';
+export type {
+  JourneyDiagramOptions,
+  JourneyDiagramBuilder,
+  SectionBuilder,
+  TaskDefinition,
+} from './types';

package/src/builders/JourneyDiagram/types.ts

@@ -0,0 +1,48 @@
+/**
+ * Types for JourneyDiagram builder
+ * @module Mermaid/builders/JourneyDiagram/types
+ */
+
+import type { TaskScore } from '../core/types';
+
+/**
+ * Options for JourneyDiagram builder
+ */
+export interface JourneyDiagramOptions {
+  /** Diagram title */
+  title: string;
+}
+
+/**
+ * Task definition
+ */
+export interface TaskDefinition {
+  /** Task name/description */
+  name: string;
+  /** Score (1-5, where 5 is best) */
+  score: TaskScore;
+  /** Actor(s) involved */
+  actors: string | string[];
+}
+
+/**
+ * Section builder interface
+ */
+export interface SectionBuilder {
+  /** Add a task to the current section */
+  task(name: string, score: TaskScore, actors: string | string[]): SectionBuilder;
+}
+
+/**
+ * Main JourneyDiagram builder result
+ */
+export interface JourneyDiagramBuilder {
+  /** Add a new section */
+  section(name: string): SectionBuilder;
+  /** Add a task directly (without section - goes to last section or creates implicit one) */
+  task(name: string, score: TaskScore, actors: string | string[]): void;
+  /** Add a comment */
+  comment(text: string): void;
+  /** Get the Mermaid string */
+  toString(): string;
+}