@djangocfg/ui-tools 2.1.156 → 2.1.158

package/src/tools/Mermaid/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/tools/Mermaid/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/ui-tools/tools/Mermaid/builders';
+ *
+ * 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/tools/Mermaid/components/MermaidFullscreenModal.tsx

@@ -1,11 +1,12 @@
 'use client';
 
-import React, { useEffect, useMemo } from 'react';
+import React, { useEffect } from 'react';
 import { createPortal } from 'react-dom';
+import { X, ZoomIn, ZoomOut, RotateCcw } from 'lucide-react';
+import { TransformWrapper, TransformComponent, useControls } from 'react-zoom-pan-pinch';
 
-import { useTypedT, type I18nTranslations } from '@djangocfg/i18n';
+import { Button } from '@djangocfg/ui-core/components';
 import { applyMermaidTextColors } from '../utils/mermaid-helpers';
-import { MermaidCodeViewer } from './MermaidCodeViewer';
 
 interface MermaidFullscreenModalProps {
     isOpen: boolean;
@@ -13,25 +14,40 @@ interface MermaidFullscreenModalProps {
     isVertical: boolean;
     theme: string;
     chart: string;
-    fullscreenRef: React.RefObject<HTMLDivElement>;
+    fullscreenRef: React.RefObject<HTMLDivElement | null>;
     onClose: () => void;
     onBackdropClick: (e: React.MouseEvent) => void;
 }
 
+// Zoom controls component
+function ZoomControls() {
+    const { zoomIn, zoomOut, resetTransform } = useControls();
+
+    return (
+        <div className="absolute bottom-4 left-1/2 -translate-x-1/2 flex gap-2 z-10">
+            <Button variant="secondary" size="icon" onClick={() => zoomOut()}>
+                <ZoomOut className="h-4 w-4" />
+            </Button>
+            <Button variant="secondary" size="icon" onClick={() => resetTransform()}>
+                <RotateCcw className="h-4 w-4" />
+            </Button>
+            <Button variant="secondary" size="icon" onClick={() => zoomIn()}>
+                <ZoomIn className="h-4 w-4" />
+            </Button>
+        </div>
+    );
+}
+
 export const MermaidFullscreenModal: React.FC<MermaidFullscreenModalProps> = ({
     isOpen,
     svgContent,
     isVertical,
     theme,
-    chart,
     fullscreenRef,
     onClose,
     onBackdropClick,
 }) => {
-    const t = useTypedT<I18nTranslations>();
-    const diagramTitle = useMemo(() => t('tools.diagram.title'), [t]);
-
-    // Apply text colors to fullscreen modal after render
+    // Apply text colors
     useEffect(() => {
         if (isOpen && fullscreenRef.current) {
             const getCSSVariable = (variable: string) => {
@@ -45,62 +61,70 @@ export const MermaidFullscreenModal: React.FC<MermaidFullscreenModalProps> = ({
                 : getCSSVariable('--foreground') || 'hsl(222.2 84% 4.9%)';
 
             applyMermaidTextColors(fullscreenRef.current, textColor);
+        }
+    }, [isOpen, theme, isVertical, fullscreenRef, svgContent]);
+
+    // Handle escape key
+    useEffect(() => {
+        if (!isOpen) return;
 
-            // Make SVG responsive
-            const svgElement = fullscreenRef.current.querySelector('svg');
-            if (svgElement) {
-                svgElement.style.display = 'block';
-                svgElement.style.height = 'auto';
-                svgElement.style.maxWidth = '100%';
+        const handleKeyDown = (e: KeyboardEvent) => {
+            if (e.key === 'Escape') onClose();
+        };
 
-                // For vertical diagrams, limit width
-                if (isVertical) {
-                    svgElement.style.maxWidth = '600px';
-                    svgElement.style.margin = '0 auto';
-                }
-            }
-        }
-    }, [isOpen, theme, isVertical, fullscreenRef]);
+        document.addEventListener('keydown', handleKeyDown);
+        return () => document.removeEventListener('keydown', handleKeyDown);
+    }, [isOpen, onClose]);
 
     if (!isOpen || typeof document === 'undefined') return null;
 
     return createPortal(
         <div
-            className="fixed inset-0 z-9999 flex items-center justify-center p-4"
-            style={{ backgroundColor: 'rgb(0 0 0 / 0.75)' }}
+            className="fixed inset-0 z-9999 bg-background/95 backdrop-blur-sm"
             onClick={onBackdropClick}
         >
-            <div className={`relative bg-card rounded-sm shadow-xl max-h-[95vh] flex flex-col border border-border ${
-                isVertical
-                    ? 'w-auto min-w-[400px] max-w-[600px]'
-                    : 'min-w-[600px] max-w-[90vw] w-auto'
-            }`}>
-                {/* Header */}
-                <div className="flex items-center justify-between py-4 px-6 border-b border-border">
-                    <h3 className="text-sm font-medium text-foreground py-0 my-0">{diagramTitle}</h3>
-                    <button
-                        onClick={onClose}
-                        className="text-muted-foreground hover:text-foreground transition-colors"
-                    >
-                        <svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
-                        </svg>
-                    </button>
-                </div>
+            {/* Close button */}
+            <Button
+                variant="ghost"
+                size="icon"
+                className="absolute top-4 right-4 z-10"
+                onClick={onClose}
+            >
+                <X className="h-5 w-5" />
+            </Button>
 
-                {/* Content - Code Viewer with tabs */}
-                <div className="flex-1 overflow-hidden">
-                    <MermaidCodeViewer
-                        chart={chart}
-                        renderPreview={() => (
-                            <div
-                                ref={fullscreenRef}
-                                dangerouslySetInnerHTML={{ __html: svgContent }}
-                            />
-                        )}
+            {/* Zoomable diagram */}
+            <TransformWrapper
+                initialScale={1}
+                minScale={0.1}
+                maxScale={10}
+                centerOnInit
+                wheel={{ step: 0.1 }}
+                pinch={{ step: 5 }}
+                doubleClick={{ mode: 'reset' }}
+            >
+                <ZoomControls />
+                <TransformComponent
+                    wrapperStyle={{
+                        width: '100%',
+                        height: '100%',
+                    }}
+                    contentStyle={{
+                        width: '100%',
+                        height: '100%',
+                        display: 'flex',
+                        alignItems: 'center',
+                        justifyContent: 'center',
+                    }}
+                >
+                    <div
+                        ref={fullscreenRef}
+                        className="p-8"
+                        dangerouslySetInnerHTML={{ __html: svgContent }}
+                        onClick={(e) => e.stopPropagation()}
                     />
-                </div>
-            </div>
+                </TransformComponent>
+            </TransformWrapper>
         </div>,
         document.body
     );

package/src/tools/Mermaid/index.tsx

@@ -14,16 +14,8 @@ const MermaidClient = lazy(() => import('./Mermaid.client'));
 
 // Loading fallback component
 const LoadingFallback = () => (
-  <div className="relative bg-card rounded-sm border border-border overflow-hidden">
-    <div className="p-4 border-b border-border bg-muted/50">
-      <h6 className="text-sm font-semibold text-foreground">Diagram</h6>
-      <p className="text-xs text-muted-foreground mt-1">Loading...</p>
-    </div>
-    <div className="p-4">
-      <div className="flex justify-center items-center min-h-[200px]">
-        <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-primary"></div>
-      </div>
-    </div>
+  <div className="flex justify-center items-center min-h-[100px]">
+    <div className="animate-spin rounded-full h-6 w-6 border-b-2 border-primary" />
   </div>
 );
 
@@ -31,6 +23,8 @@ export interface MermaidProps {
   chart: string;
   className?: string;
   isCompact?: boolean;
+  /** Enable click-to-fullscreen functionality (default: true) */
+  fullscreen?: boolean;
 }
 
 const Mermaid: React.FC<MermaidProps> = (props) => {
@@ -42,3 +36,50 @@ const Mermaid: React.FC<MermaidProps> = (props) => {
 };
 
 export default Mermaid;
+
+// 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/tools/Mermaid/lazy.tsx

@@ -11,16 +11,13 @@
  */
 
 import { createLazyComponent, CardLoadingFallback } from '../../components';
+import type { MermaidProps } from './index';
 
 // ============================================================================
 // Types
 // ============================================================================
 
-export interface MermaidProps {
-  chart: string;
-  className?: string;
-  isCompact?: boolean;
-}
+export type { MermaidProps };
 
 // ============================================================================
 // Lazy Component