@snowcone-app/ui 0.1.43 → 0.2.1

package/src/hooks/useImageTransition.ts

@@ -0,0 +1,608 @@
+"use client";
+
+import { useState, useCallback, useRef, useEffect } from "react";
+
+export interface UseImageTransitionOptions {
+  /** Duration of image crossfade in ms (default: 500) */
+  fadeDuration?: number;
+  /** Delay before showing shimmer during slow loads in ms (default: 200) */
+  shimmerDelay?: number;
+  /** Duration of shimmer fade in/out in ms for light shimmer (default: 500) */
+  shimmerFadeDuration?: number;
+  /** Duration of dark shimmer fade-in in ms (default: 300) */
+  darkShimmerFadeInDuration?: number;
+  /**
+   * Initial URL to display immediately without preloading.
+   * Use this when remounting a component that was already showing this image,
+   * allowing instant display without a network request or flicker.
+   */
+  initialUrl?: string | null;
+}
+
+/** A single image layer in the transition stack */
+export interface ImageLayer {
+  url: string;
+  opacity: number;
+  id: number; // Unique ID for React key
+  waitForLoad?: boolean; // If true, don't auto-fade - wait for onImageLoad
+  loaded?: boolean; // True after img.decode() completes - controls visibility
+}
+
+export interface UseImageTransitionReturn {
+  // What to render - a stack of image layers (bottom to top)
+  layers: ImageLayer[];
+  shimmerOpacity: number;
+  showShimmer: boolean;
+  shimmerType: "light" | "dark";
+
+  // Control
+  setTargetUrl: (url: string | null, shimmerType?: "light" | "dark") => void;
+  /**
+   * Add a URL directly to layers without preloading via new Image().
+   * The actual <img> element in the DOM will handle loading.
+   * Use this when you trust the URL and want the visible element to load it.
+   * @param options.skipTransition - If true, add at opacity 1 immediately (no fade-in)
+   */
+  addLayerDirectly: (url: string, options?: { showShimmer?: boolean; skipTransition?: boolean }) => void;
+  /** Trigger shimmer immediately (e.g., when canvas export starts, before URL is known) */
+  triggerShimmer: (type?: "light" | "dark") => void;
+  /** Called when the actual img element loads - hides shimmer and triggers fade-in */
+  onImageLoad: (layerId: number) => void;
+  preloadUrl: string | null;
+  onPreloadComplete: (loadedUrl: string) => void;
+  onPreloadError: () => void;
+  onLayerTransitionEnd: (layerId: number) => void;
+
+  // Durations (for CSS styling)
+  durations: {
+    fade: number;
+    shimmerFade: number;
+    darkShimmerFadeIn: number;
+  };
+}
+
+let layerIdCounter = 0;
+
+/**
+ * useImageTransition - Simple image transition hook with race condition protection
+ *
+ * Core principle: Use a monotonically increasing version number to prevent stale
+ * image loads from being displayed. Each call to setTargetUrl increments the version,
+ * and only images that match the current version are added to layers.
+ */
+export function useImageTransition(
+  options: UseImageTransitionOptions = {}
+): UseImageTransitionReturn {
+  const {
+    fadeDuration = 500,
+    shimmerDelay = 200,
+    shimmerFadeDuration = 500,
+    darkShimmerFadeInDuration = 300,
+    initialUrl,
+  } = options;
+
+  // State - initialize with a layer if initialUrl is provided (for instant display on remount)
+  // When initialUrl is provided, we trust it's valid and display immediately (browser handles caching)
+  const [state, setState] = useState<{
+    layers: ImageLayer[];
+    preloadUrl: string | null;
+    shimmerOpacity: number;
+    showShimmer: boolean;
+    shimmerType: "light" | "dark";
+  }>(() => {
+    return {
+      layers: initialUrl
+        ? [{ url: initialUrl, opacity: 1, id: ++layerIdCounter, loaded: true }]
+        : [],
+      preloadUrl: null,
+      shimmerOpacity: 0,
+      showShimmer: false,
+      shimmerType: "light",
+    };
+  });
+
+  // Version counter - increments on every setTargetUrl call
+  // This is the key to preventing race conditions
+  const versionRef = useRef(0);
+
+  // Current preloader
+  const preloaderRef = useRef<HTMLImageElement | null>(null);
+
+  // Track current preload URL for synchronous deduplication
+  // This is needed because setState is async and we need to prevent
+  // duplicate loads that happen in quick succession
+  const currentPreloadUrlRef = useRef<string | null>(null);
+
+  // Shimmer delay timer
+  const shimmerTimerRef = useRef<NodeJS.Timeout | null>(null);
+
+  // Track if mounted
+  const isMountedRef = useRef(true);
+
+  useEffect(() => {
+    isMountedRef.current = true;
+    return () => {
+      isMountedRef.current = false;
+      if (shimmerTimerRef.current) {
+        clearTimeout(shimmerTimerRef.current);
+      }
+      // DON'T cancel in-flight image loads on unmount!
+      // Let the browser finish loading and cache the response.
+      // When the component remounts, it will load instantly from cache.
+      // We just clear the callbacks to prevent state updates on unmounted component.
+      if (preloaderRef.current) {
+        preloaderRef.current.onload = null;
+        preloaderRef.current.onerror = null;
+        // NOTE: We intentionally do NOT set src = "" here
+        // Setting src = "" cancels the request before it completes
+        preloaderRef.current = null;
+      }
+    };
+  }, []);
+
+  const setTargetUrl = useCallback(
+    (url: string | null, shimmerType: "light" | "dark" = "light") => {
+      // Increment version - this invalidates any in-flight preloads
+      const version = ++versionRef.current;
+
+      // Cancel any pending shimmer timer
+      if (shimmerTimerRef.current) {
+        clearTimeout(shimmerTimerRef.current);
+        shimmerTimerRef.current = null;
+      }
+
+      // Cancel any in-flight preload
+      if (preloaderRef.current) {
+        preloaderRef.current.onload = null;
+        preloaderRef.current.onerror = null;
+        preloaderRef.current.src = "";
+        preloaderRef.current = null;
+        currentPreloadUrlRef.current = null;
+      }
+
+      // Handle null/reset
+      if (!url) {
+        currentPreloadUrlRef.current = null;
+        setState({
+          layers: [],
+          preloadUrl: null,
+          shimmerOpacity: 0,
+          showShimmer: false,
+          shimmerType: "light",
+        });
+        return;
+      }
+
+      // Track current preload URL in a ref for synchronous deduplication
+      // This prevents race conditions where multiple setTargetUrl calls happen
+      // before React state updates
+      if (currentPreloadUrlRef.current === url) {
+        return;
+      }
+
+      // Check if we're already showing this URL
+      // Use functional update to safely check current state
+      let skipLoad = false;
+      setState((prev) => {
+        const topLayer = prev.layers[prev.layers.length - 1];
+        // Compare base URL without cache buster
+        const topLayerBaseUrl = topLayer?.url?.split('&_t=')[0]?.split('?_t=')[0];
+        if (topLayerBaseUrl === url && topLayer.opacity === 1) {
+          skipLoad = true;
+          return prev;
+        }
+
+        // Start loading the new URL
+        return {
+          ...prev,
+          preloadUrl: url,
+          shimmerType,
+        };
+      });
+
+      // Note: skipLoad check here is a race but the ref check above handles most cases
+      // The worst case is starting a redundant load, which the server should handle
+
+      // Update ref to track current preload
+      currentPreloadUrlRef.current = url;
+
+      // Start the preload
+      const img = new Image();
+      img.crossOrigin = 'anonymous';
+      preloaderRef.current = img;
+
+      img.onload = () => {
+        // Clear the preload tracking ref
+        if (currentPreloadUrlRef.current === url) {
+          currentPreloadUrlRef.current = null;
+        }
+
+        // CRITICAL: Only accept this image if it's still the current version
+        if (version !== versionRef.current) {
+          return;
+        }
+
+        if (!isMountedRef.current) return;
+
+        // Cancel shimmer timer since image loaded
+        if (shimmerTimerRef.current) {
+          clearTimeout(shimmerTimerRef.current);
+          shimmerTimerRef.current = null;
+        }
+
+        setState((prev) => {
+          // Double-check version inside setState for extra safety
+          if (version !== versionRef.current) {
+            return prev;
+          }
+
+          const newLayer: ImageLayer = {
+            url,
+            opacity: 0,
+            id: ++layerIdCounter,
+            loaded: false,
+          };
+
+          // Keep max 2 layers for performance
+          let newLayers: ImageLayer[];
+          if (prev.layers.length >= 2) {
+            const baseLayer = prev.layers.find((l) => l.opacity === 1) || prev.layers[0];
+            newLayers = baseLayer ? [baseLayer, newLayer] : [newLayer];
+          } else {
+            newLayers = [...prev.layers, newLayer];
+          }
+
+          return {
+            ...prev,
+            layers: newLayers,
+            preloadUrl: null,
+            shimmerOpacity: 0,
+          };
+        });
+      };
+
+      img.onerror = () => {
+        // Check if this load is still relevant
+        if (version !== versionRef.current) {
+          return;
+        }
+        if (!isMountedRef.current) return;
+
+        // Clear the preload tracking ref
+        if (currentPreloadUrlRef.current === url) {
+          currentPreloadUrlRef.current = null;
+        }
+
+        // DON'T hide shimmer on error!
+        // The URL might have been invalidated because a NEWER one is coming.
+        // Keep showing shimmer (or existing image) until a successful load.
+        setState((prev) => {
+          // If we have no layers (no image showing), show shimmer to indicate loading
+          // If we have layers, keep showing the existing image
+          const shouldShowShimmer = prev.layers.length === 0 || prev.showShimmer;
+          return {
+            ...prev,
+            preloadUrl: null,
+            showShimmer: shouldShowShimmer,
+            shimmerOpacity: shouldShowShimmer ? 1 : 0,
+            shimmerType: prev.layers.length > 0 ? "dark" : "light",
+          };
+        });
+      };
+
+      img.src = url;
+
+      // Set up shimmer timer (show shimmer if load takes too long)
+      shimmerTimerRef.current = setTimeout(() => {
+        if (version !== versionRef.current) return;
+        if (!isMountedRef.current) return;
+
+        setState((prev) => {
+          if (!prev.preloadUrl) return prev; // Already loaded
+          return {
+            ...prev,
+            showShimmer: true,
+            shimmerOpacity: 0,
+          };
+        });
+      }, shimmerDelay);
+    },
+    [shimmerDelay]
+  );
+
+  // Trigger fade-in when new layer is added at opacity 0
+  // Skip layers with waitForLoad - they will fade in via onImageLoad
+  useEffect(() => {
+    const topLayer = state.layers[state.layers.length - 1];
+    if (topLayer && topLayer.opacity === 0 && !topLayer.waitForLoad) {
+      const targetId = topLayer.id;
+
+      // Double RAF for browser paint
+      const raf1 = requestAnimationFrame(() => {
+        if (!isMountedRef.current) return;
+        requestAnimationFrame(() => {
+          if (!isMountedRef.current) return;
+          setState((prev) => {
+            const idx = prev.layers.findIndex((l) => l.id === targetId);
+            if (idx === -1 || prev.layers[idx].opacity === 1) return prev;
+
+            const newLayers = [...prev.layers];
+            newLayers[idx] = { ...newLayers[idx], opacity: 1 };
+            return { ...prev, layers: newLayers };
+          });
+        });
+      });
+
+      return () => cancelAnimationFrame(raf1);
+    }
+  }, [state.layers]);
+
+  // Trigger shimmer fade-in
+  useEffect(() => {
+    if (state.showShimmer && state.shimmerOpacity === 0 && state.preloadUrl) {
+      const raf = requestAnimationFrame(() => {
+        if (!isMountedRef.current) return;
+        requestAnimationFrame(() => {
+          if (!isMountedRef.current) return;
+          setState((prev) => {
+            if (!prev.showShimmer || !prev.preloadUrl) return prev;
+            return { ...prev, shimmerOpacity: 1 };
+          });
+        });
+      });
+      return () => cancelAnimationFrame(raf);
+    }
+  }, [state.showShimmer, state.shimmerOpacity, state.preloadUrl]);
+
+  // Fade out shimmer when load completes
+  useEffect(() => {
+    if (state.showShimmer && state.shimmerOpacity === 0 && !state.preloadUrl) {
+      const duration = state.shimmerType === "dark" ? fadeDuration : shimmerFadeDuration;
+      const timer = setTimeout(() => {
+        setState((prev) => ({ ...prev, showShimmer: false }));
+      }, duration);
+      return () => clearTimeout(timer);
+    }
+  }, [state.showShimmer, state.shimmerOpacity, state.preloadUrl, state.shimmerType, fadeDuration, shimmerFadeDuration]);
+
+  const onLayerTransitionEnd = useCallback((layerId: number) => {
+    setState((prev) => {
+      const idx = prev.layers.findIndex((l) => l.id === layerId);
+      if (idx === -1 || prev.layers[idx].opacity !== 1) return prev;
+
+      // If this is the top layer and it's fully visible, remove layers below
+      if (idx === prev.layers.length - 1 && idx > 0) {
+        return {
+          ...prev,
+          layers: [prev.layers[idx]],
+          shimmerOpacity: 0,
+        };
+      }
+      return prev;
+    });
+  }, []);
+
+  // Legacy callbacks (for compatibility)
+  const onPreloadComplete = useCallback((_loadedUrl: string) => {
+    // Legacy callback - kept for API compatibility
+  }, []);
+
+  const onPreloadError = useCallback(() => {
+    // Legacy callback - kept for API compatibility
+  }, []);
+
+  // Add URL directly to layers without preloading via new Image()
+  // Instead, we create a hidden Image and call decode() to ensure Safari
+  // decodes the image BEFORE it enters the viewport (fixes Safari flash bug)
+  const addLayerDirectly = useCallback((url: string, options?: { showShimmer?: boolean; skipTransition?: boolean }) => {
+    const shouldShowShimmer = options?.showShimmer ?? true;
+    const skipTransition = options?.skipTransition ?? false;
+
+    // Increment version to invalidate any in-flight preloads
+    const currentVersion = ++versionRef.current;
+
+    // Cancel any pending preload
+    if (preloaderRef.current) {
+      preloaderRef.current.onload = null;
+      preloaderRef.current.onerror = null;
+      preloaderRef.current.src = "";
+      preloaderRef.current = null;
+      currentPreloadUrlRef.current = null;
+    }
+
+    // Cancel shimmer timer
+    if (shimmerTimerRef.current) {
+      clearTimeout(shimmerTimerRef.current);
+      shimmerTimerRef.current = null;
+    }
+
+    const directUrl = url;
+
+    // Track the layer ID we're about to create
+    const newLayerId = layerIdCounter + 1;
+
+    setState((prev) => {
+      // Check if we already have this URL at opacity 1 (compare base URL without cache buster)
+      const topLayer = prev.layers[prev.layers.length - 1];
+      const topLayerBaseUrl = topLayer?.url?.split('&_t=')[0]?.split('?_t=')[0];
+      // Deduplicate if we're already loading OR showing this URL
+      // (Previously only checked opacity === 1, which caused duplicate layers during rapid updates)
+      if (topLayerBaseUrl === url) {
+        return prev;
+      }
+
+      // Add new layer - either at opacity 0 (with fade-in) or opacity 1 (instant, for cached images)
+      // SAFARI FIX: When skipTransition is true, set loaded: true immediately to avoid
+      // any decode() calls or state changes that could cause flash on scroll.
+      const newLayer: ImageLayer = {
+        url: directUrl,
+        opacity: skipTransition ? 1 : 0,
+        id: ++layerIdCounter,
+        waitForLoad: skipTransition ? false : true,
+        loaded: skipTransition ? true : false,
+      };
+
+      // Keep max 2 layers
+      let newLayers: ImageLayer[];
+      if (prev.layers.length >= 2) {
+        const baseLayer = prev.layers.find((l) => l.opacity === 1) || prev.layers[0];
+        newLayers = baseLayer ? [baseLayer, newLayer] : [newLayer];
+      } else {
+        newLayers = [...prev.layers, newLayer];
+      }
+
+      // Preserve shimmer state - don't reset it here
+      // Shimmer will be hidden by onImageLoad when the img finishes loading
+      return {
+        ...prev,
+        layers: newLayers,
+      };
+    });
+
+    // SAFARI FIX: Skip decode() for skipTransition - avoids state changes that cause flash.
+    // When skipTransition is true, we trust the image is cached/ready and display it immediately.
+    // The decode() call is only needed for artwork changes where we want to ensure the new
+    // image is ready before showing it.
+    if (!skipTransition) {
+      // Proactively decode the image using a hidden Image element.
+      // Safari doesn't fire onLoad for off-screen images until they scroll into view,
+      // which causes a flash. By calling decode() here, we force Safari to decode
+      // the image immediately, and then mark it as loaded before it's visible.
+      const preloadImg = new Image();
+      preloadImg.crossOrigin = 'anonymous';
+      preloadImg.src = directUrl;
+
+      const markAsLoaded = () => {
+        // Check version to avoid stale updates
+        if (currentVersion !== versionRef.current) return;
+        if (!isMountedRef.current) return;
+
+        // Cancel shimmer timer since image is ready
+        if (shimmerTimerRef.current) {
+          clearTimeout(shimmerTimerRef.current);
+          shimmerTimerRef.current = null;
+        }
+
+        setState((prev) => {
+          const idx = prev.layers.findIndex((l) => l.id === newLayerId);
+          if (idx === -1 || prev.layers[idx].loaded) return prev;
+
+          const newLayers = [...prev.layers];
+          newLayers[idx] = { ...newLayers[idx], loaded: true, opacity: 1 };
+          return {
+            ...prev,
+            layers: newLayers,
+            preloadUrl: null,
+            shimmerOpacity: 0,
+          };
+        });
+      };
+
+      // Use decode() if available (modern browsers), otherwise fall back to onload
+      if (preloadImg.decode) {
+        preloadImg.decode().then(markAsLoaded).catch(markAsLoaded);
+      } else {
+        preloadImg.onload = markAsLoaded;
+        preloadImg.onerror = markAsLoaded;
+      }
+    }
+
+    // Start delayed shimmer timer - only show shimmer if image takes > 500ms to load
+    // This prevents flashing the dark overlay for cached/fast images
+    if (shouldShowShimmer) {
+      shimmerTimerRef.current = setTimeout(() => {
+        if (!isMountedRef.current) return;
+        if (currentVersion !== versionRef.current) return;
+        setState((prev) => {
+          // Only show shimmer if we still have a loading layer
+          const hasUnloadedLayer = prev.layers.some(l => !l.loaded);
+          if (!hasUnloadedLayer) return prev;
+
+          return {
+            ...prev,
+            showShimmer: true,
+            shimmerOpacity: 0,
+            shimmerType: "dark",
+            preloadUrl: "__pending__",
+          };
+        });
+      }, 500);
+    }
+  }, []);
+
+  // Trigger shimmer immediately (for early feedback before URL is known)
+  const triggerShimmer = useCallback((type: "light" | "dark" = "dark") => {
+    setState((prev) => {
+      // Only trigger if we have existing layers (dark shimmer on top of content)
+      if (prev.layers.length === 0) {
+        return prev;
+      }
+
+      // If shimmer is already showing AND visible (opacity 1), skip
+      // But if shimmer was fading out (opacity 0), re-trigger it
+      if (prev.showShimmer && prev.shimmerOpacity === 1) {
+        return prev;
+      }
+
+      return {
+        ...prev,
+        showShimmer: true,
+        shimmerOpacity: 0,
+        shimmerType: type,
+        // Set a placeholder preloadUrl to keep shimmer visible
+        // This will be replaced when setTargetUrl is called with the real URL
+        preloadUrl: prev.preloadUrl || "__pending__",
+      };
+    });
+  }, []);
+
+  // Called when the actual img element loads - hides shimmer AND triggers fade-in
+  const onImageLoad = useCallback((layerId: number) => {
+    // Cancel shimmer timer - image loaded before the 500ms delay
+    if (shimmerTimerRef.current) {
+      clearTimeout(shimmerTimerRef.current);
+      shimmerTimerRef.current = null;
+    }
+
+    setState((prev) => {
+      // Find the layer
+      const idx = prev.layers.findIndex((l) => l.id === layerId);
+      if (idx === -1) {
+        return prev;
+      }
+
+      // Set this layer to opacity 1 (will trigger CSS transition)
+      // and mark as loaded (for visibility control) since decode() completed
+      // Also hide shimmer since image is loaded
+      const newLayers = [...prev.layers];
+      newLayers[idx] = { ...newLayers[idx], opacity: 1, loaded: true };
+
+      return {
+        ...prev,
+        layers: newLayers,
+        preloadUrl: null,
+        shimmerOpacity: 0,
+      };
+    });
+  }, []);
+
+  return {
+    layers: state.layers,
+    shimmerOpacity: state.shimmerOpacity,
+    showShimmer: state.showShimmer,
+    shimmerType: state.shimmerType,
+    setTargetUrl,
+    addLayerDirectly,
+    triggerShimmer,
+    onImageLoad,
+    preloadUrl: state.preloadUrl,
+    onPreloadComplete,
+    onPreloadError,
+    onLayerTransitionEnd,
+    durations: {
+      fade: fadeDuration,
+      shimmerFade: shimmerFadeDuration,
+      darkShimmerFadeIn: darkShimmerFadeInDuration,
+    },
+  };
+}

package/src/hooks/usePlacementsProcessor.ts

@@ -0,0 +1,74 @@
+"use client";
+
+import { useMemo } from "react";
+import type { DesignElement } from "@snowcone-app/sdk";
+
+/**
+ * usePlacementsProcessor - Process placement prop to separate colors from images
+ *
+ * Takes a placements object where values can be either color codes or image URLs,
+ * and separates them into distinct arrays/objects for easier processing.
+ *
+ * **Color Detection:**
+ * - Hex colors: `#fff`, `#FF00FF`
+ * - RGB/RGBA: `rgb(255, 0, 0)`, `rgba(255, 0, 0, 0.5)`
+ * - HSL/HSLA: `hsl(120, 100%, 50%)`, `hsla(120, 100%, 50%, 0.3)`
+ *
+ * @example
+ * ```tsx
+ * const { processedImages, colorPlacements } = usePlacementsProcessor({
+ *   Front: 'https://example.com/art.jpg',
+ *   Back: '#FF0000',
+ *   Sleeve: 'rgb(0, 255, 0)'
+ * }, []);
+ *
+ * // Result:
+ * // processedImages = [{ placement: 'Front', imageUrl: 'https://example.com/art.jpg' }]
+ * // colorPlacements = { Back: '#FF0000', Sleeve: 'rgb(0, 255, 0)' }
+ * ```
+ *
+ * @param placements - Object mapping placement labels to color codes or image URLs
+ * @param fallbackImages - Images array to return if no placements provided
+ * @returns Object with processedImages array and colorPlacements object
+ */
+export function usePlacementsProcessor(
+  placements: Record<string, string> | undefined,
+  fallbackImages: DesignElement[]
+): {
+  processedImages: DesignElement[];
+  colorPlacements: Record<string, string> | null;
+} {
+  return useMemo(() => {
+    if (!placements) {
+      return { processedImages: fallbackImages, colorPlacements: null };
+    }
+
+    const imgPlacements: DesignElement[] = [];
+    const colors: Record<string, string> = {};
+
+    // Helper to detect if value is a color (hex, rgb, rgba, hsl, hsla)
+    const isColor = (value: string): boolean => {
+      return (
+        /^#([0-9A-F]{3}){1,2}$/i.test(value) || // hex
+        /^rgb/.test(value) || // rgb/rgba
+        /^hsl/.test(value) // hsl/hsla
+      );
+    };
+
+    Object.entries(placements).forEach(([placementLabel, value]) => {
+      if (isColor(value)) {
+        colors[placementLabel] = value;
+      } else {
+        imgPlacements.push({
+          placement: placementLabel,
+          imageUrl: value,
+        });
+      }
+    });
+
+    return {
+      processedImages: imgPlacements.length > 0 ? imgPlacements : fallbackImages,
+      colorPlacements: Object.keys(colors).length > 0 ? colors : null,
+    };
+  }, [placements, fallbackImages]);
+}