@djangocfg/ui-tools 2.1.156 → 2.1.158

package/src/tools/Mermaid/Mermaid.client.tsx

@@ -1,8 +1,9 @@
 'use client';
 
-import React, { useMemo } from 'react';
+import React from 'react';
+import { Maximize2 } from 'lucide-react';
 
-import { useTypedT, type I18nTranslations } from '@djangocfg/i18n';
+import { Button } from '@djangocfg/ui-core/components';
 import { useResolvedTheme } from '@djangocfg/ui-core/hooks';
 import { MermaidFullscreenModal } from './components/MermaidFullscreenModal';
 import { useMermaidFullscreen } from './hooks/useMermaidFullscreen';
@@ -12,18 +13,18 @@ interface MermaidProps {
     chart: string;
     className?: string;
     isCompact?: boolean;
+    /** Enable click-to-fullscreen functionality (default: true) */
+    fullscreen?: boolean;
 }
 
-const Mermaid: React.FC<MermaidProps> = ({ chart, className = '', isCompact = false }) => {
-    const t = useTypedT<I18nTranslations>();
+const Mermaid: React.FC<MermaidProps> = ({
+    chart,
+    className = '',
+    isCompact = false,
+    fullscreen = true,
+}) => {
     const theme = useResolvedTheme();
 
-    const labels = useMemo(() => ({
-        title: t('tools.diagram.title'),
-        clickToView: t('tools.diagram.clickToView'),
-        loading: t('ui.form.loading'),
-    }), [t]);
-
     // Rendering logic
     const { mermaidRef, svgContent, isVertical, isRendering } = useMermaidRenderer({
         chart,
@@ -31,7 +32,7 @@ const Mermaid: React.FC<MermaidProps> = ({ chart, className = '', isCompact = fa
         isCompact,
     });
 
-    // Fullscreen modal logic
+    // Fullscreen modal logic (only used if fullscreen prop is true)
     const {
         isFullscreen,
         fullscreenRef,
@@ -40,7 +41,8 @@ const Mermaid: React.FC<MermaidProps> = ({ chart, className = '', isCompact = fa
         handleBackdropClick,
     } = useMermaidFullscreen();
 
-    const handleClick = () => {
+    const handleOpenFullscreen = (e: React.MouseEvent) => {
+        e.stopPropagation();
         if (svgContent) {
             openFullscreen();
         }
@@ -48,41 +50,43 @@ const Mermaid: React.FC<MermaidProps> = ({ chart, className = '', isCompact = fa
 
     return (
         <>
-            <div
-                className={`relative bg-card rounded-sm border border-border overflow-hidden cursor-pointer hover:shadow-sm transition-shadow ${className}`}
-                onClick={handleClick}
-            >
-                <div className="p-4 border-b border-border bg-muted/50">
-                    <h6 className="text-sm font-semibold text-foreground">{labels.title}</h6>
-                    <p className="text-xs text-muted-foreground mt-1">{labels.clickToView}</p>
-                </div>
-                <div className="relative p-4 overflow-hidden">
-                    <div
-                        ref={mermaidRef}
-                        className="flex justify-center items-center min-h-[200px]"
-                        style={{ isolation: 'isolate' }}
-                    />
-                    {isRendering && (
-                        <div className="absolute inset-0 flex items-center justify-center bg-background/50 backdrop-blur-sm">
-                            <div className="flex flex-col items-center gap-2">
-                                <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-primary"></div>
-                                <p className="text-xs text-muted-foreground">{labels.loading}</p>
-                            </div>
-                        </div>
-                    )}
-                </div>
+            <div className={`relative ${className}`}>
+                <div
+                    ref={mermaidRef}
+                    className="flex justify-center items-center"
+                    style={{ isolation: 'isolate' }}
+                />
+                {isRendering && (
+                    <div className="absolute inset-0 flex items-center justify-center">
+                        <div className="animate-spin rounded-full h-6 w-6 border-b-2 border-primary" />
+                    </div>
+                )}
+
+                {/* Fullscreen button in bottom-right corner */}
+                {fullscreen && svgContent && !isRendering && (
+                    <Button
+                        variant="secondary"
+                        size="icon"
+                        className="absolute bottom-2 right-2 h-8 w-8 opacity-60 hover:opacity-100 transition-opacity"
+                        onClick={handleOpenFullscreen}
+                    >
+                        <Maximize2 className="h-4 w-4" />
+                    </Button>
+                )}
             </div>
 
-            <MermaidFullscreenModal
-                isOpen={isFullscreen}
-                svgContent={svgContent}
-                isVertical={isVertical}
-                theme={theme}
-                chart={chart}
-                fullscreenRef={fullscreenRef}
-                onClose={closeFullscreen}
-                onBackdropClick={handleBackdropClick}
-            />
+            {fullscreen && (
+                <MermaidFullscreenModal
+                    isOpen={isFullscreen}
+                    svgContent={svgContent}
+                    isVertical={isVertical}
+                    theme={theme}
+                    chart={chart}
+                    fullscreenRef={fullscreenRef}
+                    onClose={closeFullscreen}
+                    onBackdropClick={handleBackdropClick}
+                />
+            )}
         </>
     );
 };

package/src/tools/Mermaid/Mermaid.story.tsx

@@ -1,131 +1,216 @@
 import { defineStory, useSelect, useBoolean } from '@djangocfg/playground';
-import Mermaid from './index';
+import Mermaid, {
+  FlowDiagram,
+  SequenceDiagram,
+  JourneyDiagram,
+  useStylePresets,
+  useBoxColors,
+} from './index';
 
 export default defineStory({
   title: 'Tools/Mermaid',
   component: Mermaid,
-  description: 'Mermaid diagram renderer for flowcharts, sequences, and more.',
+  description: 'Mermaid diagram renderer with declarative type-safe builders.',
 });
 
-const DIAGRAMS = {
-  flowchart: `flowchart TD
-    A[Start] --> B{Is it working?}
-    B -->|Yes| C[Great!]
-    B -->|No| D[Debug]
-    D --> B
-    C --> E[End]`,
-  sequence: `sequenceDiagram
-    participant U as User
-    participant F as Frontend
-    participant A as API
-    participant D as Database
-
-    U->>F: Click login
-    F->>A: POST /auth/login
-    A->>D: Query user
-    D-->>A: User data
-    A-->>F: JWT token
-    F-->>U: Redirect to dashboard`,
-  class: `classDiagram
-    class Vehicle {
-        +String id
-        +String make
-        +String model
-        +int year
-        +float price
-        +getFullName()
-    }
-    class Car {
-        +int doors
-        +String fuelType
-    }
-    class Motorcycle {
-        +String engineType
-    }
-    Vehicle <|-- Car
-    Vehicle <|-- Motorcycle`,
-  er: `erDiagram
-    USER ||--o{ ORDER : places
-    ORDER ||--|{ LINE_ITEM : contains
-    PRODUCT ||--o{ LINE_ITEM : "ordered in"
-    USER {
-        string id PK
-        string email
-        string name
-    }
-    ORDER {
-        string id PK
-        date created_at
-        string status
-    }
-    PRODUCT {
-        string id PK
-        string name
-        float price
-    }`,
-  gantt: `gantt
-    title Project Timeline
-    dateFormat YYYY-MM-DD
-    section Design
-        Research       :a1, 2024-01-01, 7d
-        Wireframes     :a2, after a1, 5d
-        UI Design      :a3, after a2, 10d
-    section Development
-        Frontend       :b1, after a3, 14d
-        Backend        :b2, after a3, 14d
-        Integration    :b3, after b1, 7d
-    section Testing
-        QA Testing     :c1, after b3, 7d
-        Bug Fixes      :c2, after c1, 5d`,
-};
+// ============================================================================
+// Diagram Generators
+// ============================================================================
+
+function useFlowDiagram() {
+  type Nodes = 'start' | 'check' | 'success' | 'debug' | 'finish';
+  const flow = FlowDiagram<Nodes>({ direction: 'TB' });
+  const presets = useStylePresets();
+
+  flow.node('start').rect('Start');
+  flow.node('check').rhombus('Is it working?');
+  flow.node('success').rect('Great!');
+  flow.node('debug').rect('Debug');
+  flow.node('finish').stadium('End');
+
+  flow.edge('start').to('check').solid();
+  flow.edge('check').to('success').solid('Yes');
+  flow.edge('check').to('debug').solid('No');
+  flow.edge('debug').to('check').dotted();
+  flow.edge('success').to('finish').solid();
+
+  flow.style.define('success', presets.success);
+  flow.style.define('primary', presets.primary);
+  flow.style.apply('success', 'success', 'finish');
+  flow.style.apply('primary', 'start');
+
+  return flow.toString();
+}
+
+function useSequenceDiagram() {
+  const boxes = useBoxColors();
+
+  const { d, rect, alt, loop, blank, toString } = SequenceDiagram({
+    User: 'actor',
+    App: 'participant',
+    Auth: 'participant',
+    DB: 'participant',
+  }, { autoNumber: true });
+
+  rect(boxes.primary, () => {
+    d.User.sync.App.msg('Enter credentials');
+    d.App.sync.Auth.msg('Validate credentials');
+
+    alt('Valid credentials', () => {
+      d.Auth.sync.DB.msg('Get user profile');
+      d.DB.syncReply.Auth.msg('Profile data');
+      d.Auth.syncReply.App.msg('Auth token');
+      d.App.syncReply.User.msg('Welcome!');
+    }).else('Invalid credentials', () => {
+      d.Auth.syncReply.App.msg('Auth failed');
+      d.App.syncReply.User.msg('Error message');
+    });
+  });
+
+  blank();
+
+  loop('Every 15 minutes', () => {
+    d.App.async.Auth.msg('Refresh token');
+    d.Auth.asyncReply.App.msg('New token');
+  });
+
+  return toString();
+}
+
+function useJourneyDiagram() {
+  const journey = JourneyDiagram({ title: 'User Onboarding' });
+
+  journey.section('Discovery')
+    .task('Visit landing page', 5, 'User')
+    .task('Read features', 4, 'User');
+
+  journey.section('Sign Up')
+    .task('Click Sign Up', 5, 'User')
+    .task('Fill form', 2, 'User')
+    .task('Verify email', 4, ['User', 'System']);
+
+  journey.section('Onboarding')
+    .task('Complete profile', 3, 'User')
+    .task('Create first project', 5, 'User');
+
+  return journey.toString();
+}
+
+function useArchitectureDiagram() {
+  type Nodes = 'client' | 'nginx' | 'api1' | 'api2' | 'db' | 'cache' | 'queue';
+  const flow = FlowDiagram<Nodes>({ direction: 'TB' });
+  const presets = useStylePresets();
+
+  flow.subgraph('Frontend', (sub) => {
+    sub.direction('LR');
+    sub.node('client').round('Browser');
+  });
+
+  flow.subgraph('Load Balancer', (sub) => {
+    sub.node('nginx').hexagon('Nginx');
+  });
+
+  flow.subgraph('API Servers', (sub) => {
+    sub.direction('LR');
+    sub.node('api1').rect('API Server 1');
+    sub.node('api2').rect('API Server 2');
+  });
+
+  flow.subgraph('Data Layer', (sub) => {
+    sub.direction('LR');
+    sub.node('db').cylinder('PostgreSQL');
+    sub.node('cache').cylinder('Redis');
+    sub.node('queue').cylinder('RabbitMQ');
+  });
+
+  flow.edge('client').to('nginx').solid();
+  flow.edge('nginx').to('api1').solid();
+  flow.edge('nginx').to('api2').solid();
+  flow.edge('api1').to('db').solid();
+  flow.edge('api2').to('db').solid();
+  flow.edge('api1').to('cache').dotted();
+  flow.edge('api2').to('cache').dotted();
+  flow.edge('api1').to('queue').dotted();
+
+  flow.style.define('frontend', presets.info);
+  flow.style.define('backend', presets.success);
+  flow.style.define('data', presets.warning);
+  flow.style.apply('frontend', 'client', 'nginx');
+  flow.style.apply('backend', 'api1', 'api2');
+  flow.style.apply('data', 'db', 'cache', 'queue');
+
+  return flow.toString();
+}
+
+// ============================================================================
+// Stories
+// ============================================================================
 
 export const Interactive = () => {
   const [diagramType] = useSelect('diagramType', {
-    options: ['flowchart', 'sequence', 'class', 'er', 'gantt'] as const,
-    defaultValue: 'flowchart',
+    options: ['flow', 'sequence', 'journey', 'architecture'] as const,
+    defaultValue: 'flow',
     label: 'Diagram Type',
-    description: 'Select Mermaid diagram type',
   });
 
-  const [isCompact] = useBoolean('isCompact', {
+  const [fullscreen] = useBoolean('fullscreen', {
     defaultValue: false,
-    label: 'Compact Mode',
-    description: 'Use smaller font size',
+    label: 'Enable Fullscreen',
   });
 
+  const flowChart = useFlowDiagram();
+  const sequenceChart = useSequenceDiagram();
+  const journeyChart = useJourneyDiagram();
+  const architectureChart = useArchitectureDiagram();
+
+  const charts = {
+    flow: flowChart,
+    sequence: sequenceChart,
+    journey: journeyChart,
+    architecture: architectureChart,
+  };
+
+  const chart = charts[diagramType];
+
   return (
-    <div className="max-w-4xl">
-      <Mermaid chart={DIAGRAMS[diagramType]} isCompact={isCompact} />
+    <div className="space-y-4">
+      <Mermaid chart={chart} fullscreen={fullscreen} />
+      <details className="text-xs">
+        <summary className="cursor-pointer text-muted-foreground">Generated Mermaid code</summary>
+        <pre className="mt-2 p-3 bg-muted rounded overflow-auto">{chart}</pre>
+      </details>
     </div>
   );
 };
 
-export const Flowchart = () => (
-  <div className="max-w-2xl">
-    <Mermaid chart={DIAGRAMS.flowchart} />
-  </div>
-);
-
-export const SequenceDiagram = () => (
-  <div className="max-w-3xl">
-    <Mermaid chart={DIAGRAMS.sequence} />
-  </div>
-);
-
-export const ClassDiagram = () => (
-  <div className="max-w-2xl">
-    <Mermaid chart={DIAGRAMS.class} />
-  </div>
-);
-
-export const ERDiagram = () => (
-  <div className="max-w-3xl">
-    <Mermaid chart={DIAGRAMS.er} />
-  </div>
-);
-
-export const GanttChart = () => (
-  <div className="max-w-4xl">
-    <Mermaid chart={DIAGRAMS.gantt} />
-  </div>
-);
+export const Flow = () => {
+  const chart = useFlowDiagram();
+  return <Mermaid chart={chart} />;
+};
+
+export const Sequence = () => {
+  const chart = useSequenceDiagram();
+  return <Mermaid chart={chart} />;
+};
+
+export const Journey = () => {
+  const chart = useJourneyDiagram();
+  return <Mermaid chart={chart} />;
+};
+
+export const Architecture = () => {
+  const chart = useArchitectureDiagram();
+  return <Mermaid chart={chart} />;
+};
+
+export const WithFullscreen = () => {
+  const chart = useFlowDiagram();
+  return (
+    <div className="space-y-2">
+      <p className="text-sm text-muted-foreground">
+        Click the expand button to open fullscreen
+      </p>
+      <Mermaid chart={chart} fullscreen />
+    </div>
+  );
+};

package/src/tools/Mermaid/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/tools/Mermaid/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/tools/Mermaid/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),
+  };
+}