@djangocfg/widget-visual 0.1.1

package/src/lottie/lazy.tsx

@@ -0,0 +1,65 @@
+'use client';
+
+/**
+ * Lazy-loaded LottiePlayer Component
+ *
+ * Lottie library (~200KB) is loaded only when component is rendered.
+ * Use this for automatic code-splitting with Suspense fallback.
+ *
+ * For direct imports without lazy loading, use:
+ * import { LottiePlayer } from '@djangocfg/widget-visual/lottie-player'
+ */
+
+import { createLazyComponent } from '@djangocfg/widget-kit/lazy';
+import type { LottiePlayerProps } from './types';
+
+// ============================================================================
+// Re-export types
+// ============================================================================
+
+export type {
+  LottiePlayerProps,
+  LottieSize,
+  LottieSpeed,
+  LottieDirection,
+  LottieSegment,
+} from './types';
+
+// ============================================================================
+// Lottie Loading Fallback
+// ============================================================================
+
+function LottieLoadingFallback() {
+  return (
+    <div
+      className="flex items-center justify-center p-8"
+      role="status"
+      aria-live="polite"
+    >
+      <div className="flex flex-col items-center gap-2">
+        <div
+          className="h-8 w-8 animate-spin rounded-full border-4 border-muted border-t-primary motion-reduce:animate-[spin_1.5s_linear_infinite]"
+          aria-hidden="true"
+        />
+        <span className="text-sm text-muted-foreground">Loading animation...</span>
+      </div>
+    </div>
+  );
+}
+
+// ============================================================================
+// Lazy Component
+// ============================================================================
+
+/**
+ * LazyLottiePlayer - Lazy-loaded Lottie animation player
+ *
+ * Automatically shows loading state while Lottie loads (~200KB)
+ */
+export const LazyLottiePlayer = createLazyComponent<LottiePlayerProps>(
+  () => import('./LottiePlayer.client').then((mod) => ({ default: mod.LottiePlayer })),
+  {
+    displayName: 'LazyLottiePlayer',
+    fallback: <LottieLoadingFallback />,
+  }
+);

package/src/lottie/lottie-player.stories.tsx

@@ -0,0 +1,173 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { LazyLottiePlayer as LottiePlayer } from './lazy';
+
+// Public CC0 Lottie animations (stable hosts).
+const ANIMATIONS = {
+  loadingDots: 'https://assets1.lottiefiles.com/packages/lf20_iv4dsx3q.json',
+  successCheck:
+    'https://lottie.host/4db68bbd-31f6-4cd8-84eb-189de081159a/IGmMCqhzpt.json',
+  rocket: 'https://assets3.lottiefiles.com/packages/lf20_x62chJ.json',
+} as const;
+
+const DEFAULT_SRC = ANIMATIONS.rocket;
+
+const meta = {
+  title: 'Widgets/Visual/Lottie',
+  component: LottiePlayer,
+  tags: ['autodocs'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    src: {
+      control: 'select',
+      options: Object.values(ANIMATIONS),
+      table: { category: 'Source' },
+      description: 'Animation JSON URL or inline data object.',
+    },
+    size: {
+      control: 'select',
+      options: ['xs', 'sm', 'md', 'lg', 'xl', 'full'],
+      table: { category: 'Layout' },
+    },
+    autoplay: {
+      control: 'boolean',
+      table: { category: 'Playback', defaultValue: { summary: 'true' } },
+    },
+    loop: {
+      control: 'boolean',
+      table: { category: 'Playback', defaultValue: { summary: 'true' } },
+    },
+    speed: {
+      control: { type: 'select' },
+      options: [0.5, 1, 1.5, 2],
+      table: { category: 'Playback', defaultValue: { summary: '1' } },
+    },
+    direction: {
+      control: { type: 'inline-radio' },
+      options: [1, -1],
+      table: { category: 'Playback', defaultValue: { summary: '1' } },
+    },
+    controls: {
+      control: 'boolean',
+      table: { category: 'UI', defaultValue: { summary: 'false' } },
+    },
+    background: {
+      control: 'color',
+      table: { category: 'UI' },
+    },
+    showLoading: {
+      control: 'boolean',
+      table: { category: 'UI', defaultValue: { summary: 'true' } },
+    },
+  },
+  args: {
+    src: DEFAULT_SRC,
+    size: 'md',
+    autoplay: true,
+    loop: true,
+    speed: 1,
+    direction: 1,
+    controls: false,
+    showLoading: true,
+  },
+  render: (args) => (
+    <div className="h-64 w-64">
+      <LottiePlayer {...args} />
+    </div>
+  ),
+} satisfies Meta<typeof LottiePlayer>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+// -----------------------------------------------------------------------------
+// Playground — all controls wired up
+// -----------------------------------------------------------------------------
+
+export const Playground: Story = {};
+
+// -----------------------------------------------------------------------------
+// Curated presets
+// -----------------------------------------------------------------------------
+
+export const FromUrl: Story = {
+  args: {
+    src: ANIMATIONS.loadingDots,
+    autoplay: true,
+    loop: true,
+  },
+};
+
+export const Paused: Story = {
+  args: {
+    src: ANIMATIONS.rocket,
+    autoplay: false,
+    controls: true,
+  },
+};
+
+export const Slow: Story = {
+  args: {
+    src: ANIMATIONS.rocket,
+    speed: 0.5,
+    loop: true,
+  },
+};
+
+export const Fast: Story = {
+  args: {
+    src: ANIMATIONS.rocket,
+    speed: 2,
+    loop: true,
+  },
+};
+
+export const Reverse: Story = {
+  args: {
+    src: ANIMATIONS.rocket,
+    direction: -1,
+    loop: true,
+  },
+};
+
+export const Looped: Story = {
+  args: {
+    src: ANIMATIONS.successCheck,
+    loop: true,
+    autoplay: true,
+  },
+};
+
+// -----------------------------------------------------------------------------
+// Interactive controls — play/pause, loop toggle, speed cycle
+// -----------------------------------------------------------------------------
+
+export const InteractiveControls: Story = {
+  args: {
+    src: ANIMATIONS.rocket,
+    controls: true,
+    autoplay: true,
+  },
+};
+
+// -----------------------------------------------------------------------------
+// Hover to play — animation runs only while the pointer is over it
+// -----------------------------------------------------------------------------
+
+export const HoverToPlay: Story = {
+  args: {
+    src: ANIMATIONS.rocket,
+    hoverToPlay: true,
+    autoplay: false,
+  },
+};
+
+// -----------------------------------------------------------------------------
+// Error state — invalid URL surfaces a retryable error
+// -----------------------------------------------------------------------------
+
+export const ErrorState: Story = {
+  args: {
+    src: 'https://lottie.host/this-animation-does-not-exist.json',
+  },
+};

package/src/lottie/types.ts

@@ -0,0 +1,138 @@
+/**
+ * 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;
+
+/**
+ * Inclusive [start, end] frame range for segment playback.
+ */
+export type LottieSegment = [number, number];
+
+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 interactive playback controls (play/pause, loop, speed)
+   * @default false
+   */
+  controls?: boolean;
+
+  /**
+   * Play only a frame range, e.g. [30, 90]. Overrides full-clip playback.
+   */
+  segment?: LottieSegment;
+
+  /**
+   * Play the animation only while the pointer is over it. When the
+   * pointer leaves, playback pauses. Ignored when `controls` drive playback.
+   * @default false
+   */
+  hoverToPlay?: boolean;
+
+  /**
+   * Background color
+   */
+  background?: string;
+
+  /**
+   * CSS class name
+   */
+  className?: string;
+
+  /**
+   * Accessible label describing the animation for screen readers.
+   */
+  ariaLabel?: string;
+
+  /**
+   * Respect the user's `prefers-reduced-motion` setting. When the user
+   * prefers reduced motion the animation renders a static first frame
+   * instead of playing.
+   * @default true
+   */
+  respectReducedMotion?: boolean;
+
+  /**
+   * 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/lottie/useLottie.ts

@@ -0,0 +1,187 @@
+/**
+ * useLottie Hook
+ *
+ * Hook for loading and managing Lottie animation data
+ */
+
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+
+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
+ * - Aborts in-flight requests on unmount / src change
+ * - 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.
+    // Only update state when the reference actually changes so that
+    // callers passing an inline object literal do not trigger an
+    // infinite render loop.
+    if (typeof src === 'object' && src !== null) {
+      setAnimationData((prev) => (prev === src ? prev : src));
+      setIsLoading(false);
+      setError(null);
+      return;
+    }
+
+    // If src is a string (URL), fetch it
+    if (typeof src === 'string') {
+      const abortController = new AbortController();
+
+      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, { signal: abortController.signal });
+
+          if (!response.ok) {
+            throw new Error(`Failed to load animation: ${response.status} ${response.statusText}`);
+          }
+
+          let data: unknown;
+          try {
+            data = await response.json();
+          } catch {
+            throw new Error('Animation file is not valid JSON');
+          }
+
+          // Validate that it's a valid Lottie animation
+          if (
+            !data ||
+            typeof data !== 'object' ||
+            !('v' in data) ||
+            !('layers' in data) ||
+            !Array.isArray((data as { layers: unknown }).layers)
+          ) {
+            throw new Error('Invalid Lottie animation data');
+          }
+
+          // Cache the loaded animation
+          if (cache) {
+            animationCache.set(src, data as object);
+          }
+
+          if (isMountedRef.current) {
+            setAnimationData(data as object);
+            setIsLoading(false);
+          }
+        } catch (err) {
+          // Ignore aborts triggered by unmount / src change.
+          if (abortController.signal.aborted) {
+            return;
+          }
+          if (isMountedRef.current) {
+            setError(err instanceof Error ? err : new Error('Failed to load animation'));
+            setIsLoading(false);
+          }
+        }
+      };
+
+      loadAnimation();
+
+      return () => {
+        abortController.abort();
+      };
+    }
+  }, [src, cache, retryCount]);
+
+  const retry = () => {
+    setRetryCount((prev) => prev + 1);
+  };
+
+  return {
+    animationData,
+    isLoading,
+    error,
+    retry,
+  };
+}

package/src/lottie/usePrefersReducedMotion.ts

@@ -0,0 +1,46 @@
+/**
+ * usePrefersReducedMotion Hook
+ *
+ * Tracks the `prefers-reduced-motion` media query so animations can be
+ * suppressed for users who request reduced motion (a11y).
+ */
+
+'use client';
+
+import { useEffect, useState } from 'react';
+
+const QUERY = '(prefers-reduced-motion: reduce)';
+
+/**
+ * Returns `true` when the user has requested reduced motion.
+ *
+ * SSR-safe: returns `false` on the server and during the first client
+ * render, then syncs with the actual media query after mount.
+ */
+export function usePrefersReducedMotion(): boolean {
+  const [prefersReducedMotion, setPrefersReducedMotion] = useState(false);
+
+  useEffect(() => {
+    if (typeof window === 'undefined' || !window.matchMedia) {
+      return;
+    }
+
+    const mediaQuery = window.matchMedia(QUERY);
+    setPrefersReducedMotion(mediaQuery.matches);
+
+    const handleChange = (event: MediaQueryListEvent) => {
+      setPrefersReducedMotion(event.matches);
+    };
+
+    // Safari < 14 only supports the deprecated addListener API.
+    if (typeof mediaQuery.addEventListener === 'function') {
+      mediaQuery.addEventListener('change', handleChange);
+      return () => mediaQuery.removeEventListener('change', handleChange);
+    }
+
+    mediaQuery.addListener(handleChange);
+    return () => mediaQuery.removeListener(handleChange);
+  }, []);
+
+  return prefersReducedMotion;
+}