@djangocfg/ui-tools 2.1.407 → 2.1.409

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

@@ -11,6 +11,7 @@ import Lottie from 'react-lottie-player';
 
 import { LottiePlayerProps } from './types';
 import { useLottie } from './useLottie';
+import { usePrefersReducedMotion } from './usePrefersReducedMotion';
 
 // Size presets mapping
 const SIZE_PRESETS = {
@@ -22,42 +23,33 @@ const SIZE_PRESETS = {
   full: { width: '100%', height: '100%' },
 } as const;
 
+const SPEED_STEPS = [0.5, 1, 1.5, 2] 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)
+ * - Interactive playback controls (play/pause, loop, speed)
+ * - Segment playback and hover-to-play
  * - Loading and error states
+ * - Respects `prefers-reduced-motion`
  * - Event callbacks
  *
  * Usage:
  * ```tsx
  * // From URL with size preset
- * <LottiePlayer
- *   src="https://example.com/animation.json"
- *   size="md"
- *   autoplay
- *   loop
- * />
+ * <LottiePlayer src="https://example.com/animation.json" size="md" autoplay loop />
+ *
+ * // Interactive controls
+ * <LottiePlayer src={animationData} controls />
  *
- * // From object with custom size
- * <LottiePlayer
- *   src={animationData}
- *   width={300}
- *   height={300}
- *   speed={1.5}
- *   controls
- * />
+ * // Play a frame range only
+ * <LottiePlayer src={animationData} segment={[30, 90]} />
  *
- * // 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)}
- * />
+ * // Play on hover
+ * <LottiePlayer src={animationData} hoverToPlay autoplay={false} />
  * ```
  */
 export function LottiePlayer({
@@ -70,8 +62,12 @@ export function LottiePlayer({
   speed = 1,
   direction = 1,
   controls = false,
+  segment,
+  hoverToPlay = false,
   background,
   className,
+  ariaLabel,
+  respectReducedMotion = true,
   showLoading = true,
   onComplete,
   onLoad,
@@ -79,18 +75,38 @@ export function LottiePlayer({
 }: LottiePlayerProps) {
   // Load animation data using our custom hook
   const { animationData, isLoading, error, retry } = useLottie({ src });
+  const prefersReducedMotion = usePrefersReducedMotion();
+  const reduceMotion = respectReducedMotion && prefersReducedMotion;
+
+  // Interactive playback state (only used when `controls` is enabled).
+  const [isPlaying, setIsPlaying] = React.useState(autoplay);
+  const [loopEnabled, setLoopEnabled] = React.useState(Boolean(loop));
+  const [currentSpeed, setCurrentSpeed] = React.useState<number>(speed);
+  const [hovered, setHovered] = React.useState(false);
 
-  // Notify parent about load state
+  // Keep internal state in sync if controlling props change.
+  React.useEffect(() => setIsPlaying(autoplay), [autoplay]);
+  React.useEffect(() => setLoopEnabled(Boolean(loop)), [loop]);
+  React.useEffect(() => setCurrentSpeed(speed), [speed]);
+
+  // Notify parent about load state once per loaded animation.
+  const notifiedLoadRef = React.useRef<object | null>(null);
   React.useEffect(() => {
-    if (animationData && onLoad) {
-      onLoad();
+    if (animationData && notifiedLoadRef.current !== animationData) {
+      notifiedLoadRef.current = animationData;
+      onLoad?.();
     }
   }, [animationData, onLoad]);
 
-  // Notify parent about errors
+  // Notify parent about errors once per error instance.
+  const notifiedErrorRef = React.useRef<Error | null>(null);
   React.useEffect(() => {
-    if (error && onError) {
-      onError(error);
+    if (error && notifiedErrorRef.current !== error) {
+      notifiedErrorRef.current = error;
+      onError?.(error);
+    }
+    if (!error) {
+      notifiedErrorRef.current = null;
     }
   }, [error, onError]);
 
@@ -103,32 +119,71 @@ export function LottiePlayer({
         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();
+    // When not looping, reflect the finished state in the controls.
+    if (!loopEnabled) {
+      setIsPlaying(false);
     }
-  }, [onComplete]);
+    onComplete?.();
+  }, [loopEnabled, onComplete]);
+
+  const togglePlay = React.useCallback(() => {
+    setIsPlaying((prev) => !prev);
+  }, []);
+
+  const cycleSpeed = React.useCallback(() => {
+    setCurrentSpeed((prev) => {
+      const idx = SPEED_STEPS.indexOf(prev as (typeof SPEED_STEPS)[number]);
+      return SPEED_STEPS[(idx + 1) % SPEED_STEPS.length];
+    });
+  }, []);
+
+  // Resolve the effective play / loop / speed values.
+  // Reduced motion forces a paused, non-looping static frame.
+  const effectivePlaying = reduceMotion
+    ? false
+    : hoverToPlay
+      ? hovered
+      : controls
+        ? isPlaying
+        : autoplay;
+  const effectiveLoop = reduceMotion ? false : controls ? loopEnabled : loop;
+  const effectiveSpeed = controls ? currentSpeed : speed;
+
+  // Segment playback: react-lottie-player expects [start, end].
+  const segments = React.useMemo(
+    () => (segment ? ([segment[0], segment[1]] as [number, number]) : undefined),
+    [segment]
+  );
+
+  const containerStyle = React.useMemo<React.CSSProperties>(
+    () => ({
+      width: dimensions.width,
+      height: dimensions.height,
+      background: background || 'transparent',
+    }),
+    [dimensions.width, dimensions.height, background]
+  );
 
   // Loading state
   if (isLoading && showLoading) {
     return (
       <div
         className={`flex items-center justify-center ${className || ''}`}
-        style={{
-          width: dimensions.width,
-          height: dimensions.height,
-          background: background || 'transparent',
-        }}
+        style={containerStyle}
+        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-gray-300 border-t-gray-900" />
-          <span className="text-sm text-gray-500">Loading animation...</span>
+          <div
+            className="h-8 w-8 animate-spin rounded-full border-4 border-muted border-t-foreground motion-reduce:animate-[spin_1.5s_linear_infinite]"
+            aria-hidden="true"
+          />
+          <span className="text-sm text-muted-foreground">Loading animation...</span>
         </div>
       </div>
     );
@@ -139,18 +194,16 @@ export function LottiePlayer({
     return (
       <div
         className={`flex items-center justify-center ${className || ''}`}
-        style={{
-          width: dimensions.width,
-          height: dimensions.height,
-          background: background || 'transparent',
-        }}
+        style={containerStyle}
+        role="alert"
       >
         <div className="flex flex-col items-center gap-2 p-4 text-center">
           <svg
-            className="h-8 w-8 text-red-500"
+            className="h-8 w-8 text-destructive"
             fill="none"
             stroke="currentColor"
             viewBox="0 0 24 24"
+            aria-hidden="true"
           >
             <path
               strokeLinecap="round"
@@ -159,10 +212,11 @@ export function LottiePlayer({
               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>
+          <div className="text-sm text-destructive">{error.message}</div>
           <button
+            type="button"
             onClick={retry}
-            className="rounded bg-red-100 px-3 py-1 text-sm text-red-700 hover:bg-red-200"
+            className="rounded bg-destructive/10 px-3 py-1 text-sm text-destructive transition-colors hover:bg-destructive/20 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
           >
             Retry
           </button>
@@ -180,32 +234,83 @@ export function LottiePlayer({
   return (
     <div
       className={className}
-      style={{
-        width: dimensions.width,
-        height: dimensions.height,
-        background: background || 'transparent',
-      }}
+      role="img"
+      aria-label={ariaLabel ?? 'Animation'}
+      onMouseEnter={hoverToPlay ? () => setHovered(true) : undefined}
+      onMouseLeave={hoverToPlay ? () => setHovered(false) : undefined}
     >
-      <Lottie
-        animationData={animationData}
-        play={autoplay}
-        loop={loop}
-        speed={speed}
-        direction={direction}
-        style={{
-          width: '100%',
-          height: '100%',
-        }}
-        onComplete={handleComplete}
-        rendererSettings={{
-          preserveAspectRatio: 'xMidYMid meet',
-        }}
-      />
+      <div style={containerStyle}>
+        <Lottie
+          animationData={animationData}
+          play={effectivePlaying}
+          loop={effectiveLoop}
+          speed={effectiveSpeed}
+          direction={direction}
+          segments={segments}
+          goTo={reduceMotion ? (segment ? segment[0] : 0) : undefined}
+          style={{ width: '100%', height: '100%' }}
+          onComplete={handleComplete}
+          rendererSettings={{
+            preserveAspectRatio: 'xMidYMid meet',
+          }}
+        />
+      </div>
       {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 className="mt-2 flex items-center justify-center gap-1">
+          <button
+            type="button"
+            onClick={togglePlay}
+            disabled={reduceMotion}
+            aria-label={effectivePlaying ? 'Pause animation' : 'Play animation'}
+            aria-pressed={effectivePlaying}
+            className="inline-flex h-7 w-7 items-center justify-center rounded text-foreground transition-colors hover:bg-muted disabled:opacity-40 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          >
+            {effectivePlaying ? (
+              <svg className="h-4 w-4" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+                <rect x="6" y="5" width="4" height="14" rx="1" />
+                <rect x="14" y="5" width="4" height="14" rx="1" />
+              </svg>
+            ) : (
+              <svg className="h-4 w-4" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+                <path d="M8 5v14l11-7z" />
+              </svg>
+            )}
+          </button>
+          <button
+            type="button"
+            onClick={() => setLoopEnabled((prev) => !prev)}
+            aria-label={loopEnabled ? 'Disable loop' : 'Enable loop'}
+            aria-pressed={loopEnabled}
+            className={`inline-flex h-7 w-7 items-center justify-center rounded transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring ${
+              loopEnabled ? 'text-foreground' : 'text-muted-foreground'
+            }`}
+          >
+            <svg
+              className="h-4 w-4"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth={2}
+              aria-hidden="true"
+            >
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                d="M17 1l4 4-4 4M3 11V9a4 4 0 014-4h14M7 23l-4-4 4-4M21 13v2a4 4 0 01-4 4H3"
+              />
+            </svg>
+          </button>
+          <button
+            type="button"
+            onClick={cycleSpeed}
+            aria-label={`Playback speed ${currentSpeed}x, click to change`}
+            className="inline-flex h-7 min-w-9 items-center justify-center rounded px-1.5 text-xs font-medium text-muted-foreground transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          >
+            {currentSpeed}x
+          </button>
+          {reduceMotion && (
+            <span className="ml-1 text-xs text-muted-foreground">Reduced motion</span>
+          )}
         </div>
       )}
     </div>

package/src/tools/LottiePlayer/index.tsx

@@ -16,10 +16,13 @@ const LottiePlayerClient = lazy(() =>
 
 // Loading fallback component
 const LoadingFallback = () => (
-  <div className="flex items-center justify-center p-8">
+  <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-gray-300 border-t-gray-900" />
-      <span className="text-sm text-gray-500">Loading player...</span>
+      <div
+        className="h-8 w-8 animate-spin rounded-full border-4 border-muted border-t-foreground motion-reduce:animate-[spin_1.5s_linear_infinite]"
+        aria-hidden="true"
+      />
+      <span className="text-sm text-muted-foreground">Loading player...</span>
     </div>
   </div>
 );
@@ -51,6 +54,13 @@ export function LottiePlayer(props: LottiePlayerProps) {
 }
 
 // Re-export types for convenience
-export type { LottiePlayerProps, LottieSize, LottieSpeed, LottieDirection } from './types';
+export type {
+  LottiePlayerProps,
+  LottieSize,
+  LottieSpeed,
+  LottieDirection,
+  LottieSegment,
+} from './types';
 export { useLottie } from './useLottie';
 export type { UseLottieOptions, UseLottieReturn } from './useLottie';
+export { usePrefersReducedMotion } from './usePrefersReducedMotion';

package/src/tools/LottiePlayer/lazy.tsx

@@ -10,7 +10,7 @@
  * import { LottiePlayer } from '@djangocfg/ui-tools/lottie'
  */
 
-import { createLazyComponent, LoadingFallback } from '../../components';
+import { createLazyComponent } from '../../components';
 import type { LottiePlayerProps } from './types';
 
 // ============================================================================
@@ -22,6 +22,7 @@ export type {
   LottieSize,
   LottieSpeed,
   LottieDirection,
+  LottieSegment,
 } from './types';
 
 // ============================================================================
@@ -30,9 +31,16 @@ export type {
 
 function LottieLoadingFallback() {
   return (
-    <div className="flex items-center justify-center p-8">
+    <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" />
+        <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>

package/src/tools/LottiePlayer/types.ts

@@ -10,6 +10,11 @@ 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
@@ -57,11 +62,23 @@ export interface LottiePlayerProps {
   direction?: LottieDirection;
 
   /**
-   * Show playback controls
+   * 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
    */
@@ -72,6 +89,19 @@ export interface LottiePlayerProps {
    */
   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

package/src/tools/LottiePlayer/useLottie.ts

@@ -8,8 +8,6 @@
 
 import { useEffect, useRef, useState } from 'react';
 
-import { LottieAnimationData } from './types';
-
 export interface UseLottieOptions {
   /**
    * Animation data (JSON object) or URL to load from
@@ -54,6 +52,7 @@ const animationCache = new Map<string, object>();
  * 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
  *
@@ -89,9 +88,12 @@ export function useLottie(options: UseLottieOptions): UseLottieReturn {
   }, []);
 
   useEffect(() => {
-    // If src is already an object, use it directly
+    // 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(src);
+      setAnimationData((prev) => (prev === src ? prev : src));
       setIsLoading(false);
       setError(null);
       return;
@@ -99,6 +101,8 @@ export function useLottie(options: UseLottieOptions): UseLottieReturn {
 
     // 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)) {
@@ -117,29 +121,44 @@ export function useLottie(options: UseLottieOptions): UseLottieReturn {
         }
 
         try {
-          const response = await fetch(src);
+          const response = await fetch(src, { signal: abortController.signal });
 
           if (!response.ok) {
             throw new Error(`Failed to load animation: ${response.status} ${response.statusText}`);
           }
 
-          const data = await response.json();
+          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' || !data.v || !data.layers) {
+          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);
+            animationCache.set(src, data as object);
           }
 
           if (isMountedRef.current) {
-            setAnimationData(data);
+            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);
@@ -148,6 +167,10 @@ export function useLottie(options: UseLottieOptions): UseLottieReturn {
       };
 
       loadAnimation();
+
+      return () => {
+        abortController.abort();
+      };
     }
   }, [src, cache, retryCount]);
 

package/src/tools/LottiePlayer/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;
+}