@djangocfg/ui-nextjs 1.4.45

package/src/tools/LottiePlayer/LottiePlayer.client.tsx

@@ -0,0 +1,212 @@
+/**
+ * LottiePlayer Component
+ *
+ * Universal Lottie animation player component
+ */
+
+'use client';
+
+import React from 'react';
+import Lottie from 'react-lottie-player';
+import { LottiePlayerProps } from './types';
+import { useLottie } from './useLottie';
+
+// Size presets mapping
+const SIZE_PRESETS = {
+  xs: { width: 64, height: 64 },
+  sm: { width: 128, height: 128 },
+  md: { width: 256, height: 256 },
+  lg: { width: 384, height: 384 },
+  xl: { width: 512, height: 512 },
+  full: { width: '100%', height: '100%' },
+} as const;
+
+/**
+ * LottiePlayer component for displaying Lottie animations
+ *
+ * Features:
+ * - Loads animations from URLs or objects
+ * - Size presets or custom dimensions
+ * - Playback controls (speed, direction, loop)
+ * - Loading and error states
+ * - Event callbacks
+ *
+ * Usage:
+ * ```tsx
+ * // From URL with size preset
+ * <LottiePlayer
+ *   src="https://example.com/animation.json"
+ *   size="md"
+ *   autoplay
+ *   loop
+ * />
+ *
+ * // From object with custom size
+ * <LottiePlayer
+ *   src={animationData}
+ *   width={300}
+ *   height={300}
+ *   speed={1.5}
+ *   controls
+ * />
+ *
+ * // With callbacks
+ * <LottiePlayer
+ *   src="https://example.com/animation.json"
+ *   onLoad={() => console.log('Animation loaded')}
+ *   onComplete={() => console.log('Animation completed')}
+ *   onError={(err) => console.error('Error:', err)}
+ * />
+ * ```
+ */
+export function LottiePlayer({
+  src,
+  size = 'md',
+  width,
+  height,
+  autoplay = true,
+  loop = true,
+  speed = 1,
+  direction = 1,
+  controls = false,
+  background,
+  className,
+  showLoading = true,
+  onComplete,
+  onLoad,
+  onError,
+}: LottiePlayerProps) {
+  // Load animation data using our custom hook
+  const { animationData, isLoading, error, retry } = useLottie({ src });
+
+  // Notify parent about load state
+  React.useEffect(() => {
+    if (animationData && onLoad) {
+      onLoad();
+    }
+  }, [animationData, onLoad]);
+
+  // Notify parent about errors
+  React.useEffect(() => {
+    if (error && onError) {
+      onError(error);
+    }
+  }, [error, onError]);
+
+  // Determine dimensions
+  const dimensions = React.useMemo(() => {
+    // Custom dimensions override size preset
+    if (width !== undefined || height !== undefined) {
+      return {
+        width: width ?? SIZE_PRESETS[size].width,
+        height: height ?? SIZE_PRESETS[size].height,
+      };
+    }
+
+    // Use size preset
+    return SIZE_PRESETS[size];
+  }, [size, width, height]);
+
+  // Handle complete event
+  const handleComplete = React.useCallback(() => {
+    if (onComplete) {
+      onComplete();
+    }
+  }, [onComplete]);
+
+  // Loading state
+  if (isLoading && showLoading) {
+    return (
+      <div
+        className={`flex items-center justify-center ${className || ''}`}
+        style={{
+          width: dimensions.width,
+          height: dimensions.height,
+          background: background || 'transparent',
+        }}
+      >
+        <div className="flex flex-col items-center gap-2">
+          <div className="h-8 w-8 animate-spin rounded-full border-4 border-gray-300 border-t-gray-900" />
+          <span className="text-sm text-gray-500">Loading animation...</span>
+        </div>
+      </div>
+    );
+  }
+
+  // Error state
+  if (error) {
+    return (
+      <div
+        className={`flex items-center justify-center ${className || ''}`}
+        style={{
+          width: dimensions.width,
+          height: dimensions.height,
+          background: background || 'transparent',
+        }}
+      >
+        <div className="flex flex-col items-center gap-2 p-4 text-center">
+          <svg
+            className="h-8 w-8 text-red-500"
+            fill="none"
+            stroke="currentColor"
+            viewBox="0 0 24 24"
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth={2}
+              d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z"
+            />
+          </svg>
+          <div className="text-sm text-red-600">{error.message}</div>
+          <button
+            onClick={retry}
+            className="rounded bg-red-100 px-3 py-1 text-sm text-red-700 hover:bg-red-200"
+          >
+            Retry
+          </button>
+        </div>
+      </div>
+    );
+  }
+
+  // No animation data
+  if (!animationData) {
+    return null;
+  }
+
+  // Render the Lottie player
+  return (
+    <div
+      className={className}
+      style={{
+        width: dimensions.width,
+        height: dimensions.height,
+        background: background || 'transparent',
+      }}
+    >
+      <Lottie
+        animationData={animationData}
+        play={autoplay}
+        loop={loop}
+        speed={speed}
+        direction={direction}
+        style={{
+          width: '100%',
+          height: '100%',
+        }}
+        onComplete={handleComplete}
+        rendererSettings={{
+          preserveAspectRatio: 'xMidYMid meet',
+        }}
+      />
+      {controls && (
+        <div className="mt-2 flex items-center justify-center gap-2">
+          <span className="text-xs text-gray-500">
+            Speed: {speed}x | Direction: {direction === 1 ? 'Forward' : 'Reverse'}
+          </span>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/tools/LottiePlayer/index.tsx

@@ -0,0 +1,54 @@
+/**
+ * LottiePlayer - Dynamic Import Wrapper
+ *
+ * Lazy loads the LottiePlayer component for optimal bundle size
+ */
+
+'use client';
+
+import dynamic from 'next/dynamic';
+import React from 'react';
+import { LottiePlayerProps } from './types';
+
+// Dynamically import the LottiePlayer component to reduce initial bundle size
+const LottiePlayerClient = dynamic(
+  () => import('./LottiePlayer.client').then((mod) => ({ default: mod.LottiePlayer })),
+  {
+    ssr: false,
+    loading: () => (
+      <div className="flex items-center justify-center p-8">
+        <div className="flex flex-col items-center gap-2">
+          <div className="h-8 w-8 animate-spin rounded-full border-4 border-gray-300 border-t-gray-900" />
+          <span className="text-sm text-gray-500">Loading player...</span>
+        </div>
+      </div>
+    ),
+  }
+);
+
+/**
+ * LottiePlayer component wrapper with dynamic import
+ *
+ * This component automatically handles code splitting and lazy loading
+ * of the Lottie player to optimize bundle size.
+ *
+ * Usage:
+ * ```tsx
+ * import { LottiePlayer } from '@djangocfg/ui-nextjs/tools';
+ *
+ * <LottiePlayer
+ *   src="https://example.com/animation.json"
+ *   size="md"
+ *   autoplay
+ *   loop
+ * />
+ * ```
+ */
+export function LottiePlayer(props: LottiePlayerProps) {
+  return <LottiePlayerClient {...props} />;
+}
+
+// Re-export types for convenience
+export type { LottiePlayerProps, LottieSize, LottieSpeed, LottieDirection } from './types';
+export { useLottie } from './useLottie';
+export type { UseLottieOptions, UseLottieReturn } from './useLottie';

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,163 @@
+/**
+ * useLottie Hook
+ *
+ * Hook for loading and managing Lottie animation data
+ */
+
+'use client';
+
+import { useState, useEffect, useRef } 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,
+  };
+}