@djangocfg/ui-tools 2.1.91

package/src/tools/LottiePlayer/types.ts

@@ -0,0 +1,108 @@
+/**
+ * LottiePlayer Types
+ *
+ * Type definitions for the Lottie animation player component
+ */
+
+export type LottieSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'full';
+
+export type LottieSpeed = 0.5 | 1 | 1.5 | 2;
+
+export type LottieDirection = 1 | -1;
+
+export interface LottiePlayerProps {
+  /**
+   * Animation data (JSON object) or URL to load from
+   */
+  src: string | object;
+
+  /**
+   * Size preset for the player
+   * @default 'md'
+   */
+  size?: LottieSize;
+
+  /**
+   * Custom width (overrides size preset)
+   */
+  width?: number | string;
+
+  /**
+   * Custom height (overrides size preset)
+   */
+  height?: number | string;
+
+  /**
+   * Autoplay animation
+   * @default true
+   */
+  autoplay?: boolean;
+
+  /**
+   * Loop animation
+   * @default true
+   */
+  loop?: boolean | number;
+
+  /**
+   * Playback speed
+   * @default 1
+   */
+  speed?: LottieSpeed;
+
+  /**
+   * Direction (1 = forward, -1 = reverse)
+   * @default 1
+   */
+  direction?: LottieDirection;
+
+  /**
+   * Show playback controls
+   * @default false
+   */
+  controls?: boolean;
+
+  /**
+   * Background color
+   */
+  background?: string;
+
+  /**
+   * CSS class name
+   */
+  className?: string;
+
+  /**
+   * Show loading state
+   * @default true
+   */
+  showLoading?: boolean;
+
+  /**
+   * Callback when animation completes
+   */
+  onComplete?: () => void;
+
+  /**
+   * Callback when animation loads
+   */
+  onLoad?: () => void;
+
+  /**
+   * Callback on error
+   */
+  onError?: (error: Error) => void;
+}
+
+export interface LottieAnimationData {
+  v: string;
+  fr: number;
+  ip: number;
+  op: number;
+  w: number;
+  h: number;
+  nm: string;
+  ddd: number;
+  assets: any[];
+  layers: any[];
+}

package/src/tools/LottiePlayer/useLottie.ts

@@ -0,0 +1,164 @@
+/**
+ * useLottie Hook
+ *
+ * Hook for loading and managing Lottie animation data
+ */
+
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+
+import { LottieAnimationData } from './types';
+
+export interface UseLottieOptions {
+  /**
+   * Animation data (JSON object) or URL to load from
+   */
+  src: string | object;
+
+  /**
+   * Enable caching of loaded animations
+   * @default true
+   */
+  cache?: boolean;
+}
+
+export interface UseLottieReturn {
+  /**
+   * Loaded animation data
+   */
+  animationData: object | null;
+
+  /**
+   * Loading state
+   */
+  isLoading: boolean;
+
+  /**
+   * Error state
+   */
+  error: Error | null;
+
+  /**
+   * Retry loading the animation
+   */
+  retry: () => void;
+}
+
+// Simple in-memory cache for loaded animations
+const animationCache = new Map<string, object>();
+
+/**
+ * Hook for loading Lottie animations from URLs or objects
+ *
+ * Features:
+ * - Loads animations from URLs or accepts animation objects directly
+ * - Caching support to prevent re-fetching the same animation
+ * - Error handling with retry capability
+ * - Loading states
+ *
+ * Usage:
+ * ```tsx
+ * const { animationData, isLoading, error, retry } = useLottie({
+ *   src: 'https://example.com/animation.json'
+ * });
+ *
+ * if (isLoading) return <div>Loading...</div>;
+ * if (error) return <div>Error: {error.message} <button onClick={retry}>Retry</button></div>;
+ * if (!animationData) return null;
+ *
+ * return <LottiePlayer animationData={animationData} />;
+ * ```
+ */
+export function useLottie(options: UseLottieOptions): UseLottieReturn {
+  const { src, cache = true } = options;
+
+  const [animationData, setAnimationData] = useState<object | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [retryCount, setRetryCount] = useState(0);
+
+  // Track if component is mounted to prevent state updates on unmounted component
+  const isMountedRef = useRef(true);
+
+  useEffect(() => {
+    isMountedRef.current = true;
+    return () => {
+      isMountedRef.current = false;
+    };
+  }, []);
+
+  useEffect(() => {
+    // If src is already an object, use it directly
+    if (typeof src === 'object' && src !== null) {
+      setAnimationData(src);
+      setIsLoading(false);
+      setError(null);
+      return;
+    }
+
+    // If src is a string (URL), fetch it
+    if (typeof src === 'string') {
+      const loadAnimation = async () => {
+        // Check cache first
+        if (cache && animationCache.has(src)) {
+          if (isMountedRef.current) {
+            setAnimationData(animationCache.get(src)!);
+            setIsLoading(false);
+            setError(null);
+          }
+          return;
+        }
+
+        // Load from URL
+        if (isMountedRef.current) {
+          setIsLoading(true);
+          setError(null);
+        }
+
+        try {
+          const response = await fetch(src);
+
+          if (!response.ok) {
+            throw new Error(`Failed to load animation: ${response.status} ${response.statusText}`);
+          }
+
+          const data = await response.json();
+
+          // Validate that it's a valid Lottie animation
+          if (!data || typeof data !== 'object' || !data.v || !data.layers) {
+            throw new Error('Invalid Lottie animation data');
+          }
+
+          // Cache the loaded animation
+          if (cache) {
+            animationCache.set(src, data);
+          }
+
+          if (isMountedRef.current) {
+            setAnimationData(data);
+            setIsLoading(false);
+          }
+        } catch (err) {
+          if (isMountedRef.current) {
+            setError(err instanceof Error ? err : new Error('Failed to load animation'));
+            setIsLoading(false);
+          }
+        }
+      };
+
+      loadAnimation();
+    }
+  }, [src, cache, retryCount]);
+
+  const retry = () => {
+    setRetryCount((prev) => prev + 1);
+  };
+
+  return {
+    animationData,
+    isLoading,
+    error,
+    retry,
+  };
+}

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

@@ -0,0 +1,82 @@
+'use client';
+
+import React from 'react';
+
+import { useResolvedTheme } from '@djangocfg/ui-core/hooks';
+import { MermaidFullscreenModal } from './components/MermaidFullscreenModal';
+import { useMermaidFullscreen } from './hooks/useMermaidFullscreen';
+import { useMermaidRenderer } from './hooks/useMermaidRenderer';
+
+interface MermaidProps {
+    chart: string;
+    className?: string;
+    isCompact?: boolean;
+}
+
+const Mermaid: React.FC<MermaidProps> = ({ chart, className = '', isCompact = false }) => {
+    const theme = useResolvedTheme();
+
+    // Rendering logic
+    const { mermaidRef, svgContent, isVertical, isRendering } = useMermaidRenderer({
+        chart,
+        theme,
+        isCompact,
+    });
+
+    // Fullscreen modal logic
+    const {
+        isFullscreen,
+        fullscreenRef,
+        openFullscreen,
+        closeFullscreen,
+        handleBackdropClick,
+    } = useMermaidFullscreen();
+
+    const handleClick = () => {
+        if (svgContent) {
+            openFullscreen();
+        }
+    };
+
+    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">Diagram</h6>
+                    <p className="text-xs text-muted-foreground mt-1">Click to view fullscreen</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">Rendering diagram...</p>
+                            </div>
+                        </div>
+                    )}
+                </div>
+            </div>
+
+            <MermaidFullscreenModal
+                isOpen={isFullscreen}
+                svgContent={svgContent}
+                isVertical={isVertical}
+                theme={theme}
+                chart={chart}
+                fullscreenRef={fullscreenRef}
+                onClose={closeFullscreen}
+                onBackdropClick={handleBackdropClick}
+            />
+        </>
+    );
+};
+
+export default Mermaid;

package/src/tools/Mermaid/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/tools/Mermaid/components/MermaidFullscreenModal.tsx

@@ -0,0 +1,103 @@
+'use client';
+
+import React, { useEffect } from 'react';
+import { createPortal } from 'react-dom';
+
+import { applyMermaidTextColors } from '../utils/mermaid-helpers';
+import { MermaidCodeViewer } from './MermaidCodeViewer';
+
+interface MermaidFullscreenModalProps {
+    isOpen: boolean;
+    svgContent: string;
+    isVertical: boolean;
+    theme: string;
+    chart: string;
+    fullscreenRef: React.RefObject<HTMLDivElement>;
+    onClose: () => void;
+    onBackdropClick: (e: React.MouseEvent) => void;
+}
+
+export const MermaidFullscreenModal: React.FC<MermaidFullscreenModalProps> = ({
+    isOpen,
+    svgContent,
+    isVertical,
+    theme,
+    chart,
+    fullscreenRef,
+    onClose,
+    onBackdropClick,
+}) => {
+    // Apply text colors to fullscreen modal after render
+    useEffect(() => {
+        if (isOpen && fullscreenRef.current) {
+            const getCSSVariable = (variable: string) => {
+                if (typeof document === 'undefined') return '';
+                const value = getComputedStyle(document.documentElement).getPropertyValue(variable).trim();
+                return value ? `hsl(${value})` : '';
+            };
+
+            const textColor = theme === 'dark'
+                ? getCSSVariable('--foreground') || 'hsl(0 0% 90%)'
+                : getCSSVariable('--foreground') || 'hsl(222.2 84% 4.9%)';
+
+            applyMermaidTextColors(fullscreenRef.current, textColor);
+
+            // Make SVG responsive
+            const svgElement = fullscreenRef.current.querySelector('svg');
+            if (svgElement) {
+                svgElement.style.display = 'block';
+                svgElement.style.height = 'auto';
+                svgElement.style.maxWidth = '100%';
+
+                // For vertical diagrams, limit width
+                if (isVertical) {
+                    svgElement.style.maxWidth = '600px';
+                    svgElement.style.margin = '0 auto';
+                }
+            }
+        }
+    }, [isOpen, theme, isVertical, fullscreenRef]);
+
+    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)' }}
+            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">Diagram</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>
+
+                {/* Content - Code Viewer with tabs */}
+                <div className="flex-1 overflow-hidden">
+                    <MermaidCodeViewer
+                        chart={chart}
+                        renderPreview={() => (
+                            <div
+                                ref={fullscreenRef}
+                                dangerouslySetInnerHTML={{ __html: svgContent }}
+                            />
+                        )}
+                    />
+                </div>
+            </div>
+        </div>,
+        document.body
+    );
+};

package/src/tools/Mermaid/hooks/index.ts

@@ -0,0 +1,4 @@
+export { useMermaidRenderer } from './useMermaidRenderer';
+export { useMermaidValidation } from './useMermaidValidation';
+export { useMermaidCleanup } from './useMermaidCleanup';
+export { useMermaidFullscreen } from './useMermaidFullscreen';

package/src/tools/Mermaid/hooks/useMermaidCleanup.ts

@@ -0,0 +1,73 @@
+/**
+ * Hook for cleaning up orphaned Mermaid DOM nodes
+ */
+
+import { useCallback, useEffect } from 'react';
+
+export function useMermaidCleanup() {
+    const cleanupMermaidErrors = useCallback(() => {
+        if (typeof document === 'undefined') return;
+
+        // Remove all orphaned mermaid elements from body
+        // Mermaid can append: SVGs, divs with errors, text nodes
+
+        // 1. Remove elements with mermaid-* IDs directly in body
+        document.querySelectorAll('[id^="mermaid-"]').forEach((node) => {
+            if (node.parentNode === document.body) {
+                node.remove();
+            }
+        });
+
+        // 2. Remove elements with d prefix (mermaid diagram IDs) directly in body
+        document.querySelectorAll('[id^="d"]').forEach((node) => {
+            if (node.parentNode === document.body && node.id.match(/^d\d+$/)) {
+                node.remove();
+            }
+        });
+
+        // 3. Remove orphaned SVG elements that mermaid creates in body
+        document.querySelectorAll('body > svg').forEach((node) => {
+            // Check if it's a mermaid SVG (has mermaid classes or aria-roledescription)
+            if (node.getAttribute('aria-roledescription') ||
+                node.classList.contains('mermaid') ||
+                node.querySelector('.mermaid') ||
+                node.id?.includes('mermaid')) {
+                node.remove();
+            }
+        });
+
+        // 4. Remove any orphaned error divs with "Syntax error" text
+        document.querySelectorAll('body > div').forEach((node) => {
+            const text = node.textContent || '';
+            if (text.includes('Syntax error in text') ||
+                text.includes('mermaid version') ||
+                node.id?.startsWith('mermaid-') ||
+                node.id?.startsWith('d') && node.id.match(/^d\d+$/)) {
+                node.remove();
+            }
+        });
+
+        // 5. Remove orphaned pre elements with error info
+        document.querySelectorAll('body > pre').forEach((node) => {
+            const text = node.textContent || '';
+            if (text.includes('Syntax error') || text.includes('mermaid')) {
+                node.remove();
+            }
+        });
+    }, []);
+
+    // Cleanup on unmount
+    useEffect(() => {
+        return () => {
+            cleanupMermaidErrors();
+        };
+    }, [cleanupMermaidErrors]);
+
+    // Also run cleanup periodically to catch any stray elements
+    useEffect(() => {
+        const interval = setInterval(cleanupMermaidErrors, 1000);
+        return () => clearInterval(interval);
+    }, [cleanupMermaidErrors]);
+
+    return { cleanupMermaidErrors };
+}

package/src/tools/Mermaid/hooks/useMermaidFullscreen.ts

@@ -0,0 +1,46 @@
+/**
+ * Hook for managing Mermaid fullscreen modal
+ */
+
+import { useEffect, useRef, useState } from 'react';
+
+export function useMermaidFullscreen() {
+    const [isFullscreen, setIsFullscreen] = useState(false);
+    const fullscreenRef = useRef<HTMLDivElement>(null);
+
+    const openFullscreen = () => setIsFullscreen(true);
+    const closeFullscreen = () => setIsFullscreen(false);
+
+    const handleBackdropClick = (e: React.MouseEvent) => {
+        if (e.target === e.currentTarget) {
+            closeFullscreen();
+        }
+    };
+
+    // Handle ESC key
+    useEffect(() => {
+        const handleEscKey = (event: KeyboardEvent) => {
+            if (event.key === 'Escape' && isFullscreen) {
+                closeFullscreen();
+            }
+        };
+
+        if (isFullscreen) {
+            document.addEventListener('keydown', handleEscKey);
+            document.body.style.overflow = 'hidden';
+        }
+
+        return () => {
+            document.removeEventListener('keydown', handleEscKey);
+            document.body.style.overflow = 'unset';
+        };
+    }, [isFullscreen]);
+
+    return {
+        isFullscreen,
+        fullscreenRef,
+        openFullscreen,
+        closeFullscreen,
+        handleBackdropClick,
+    };
+}