@snowcone-app/ui 0.1.43 → 0.2.0

package/src/hooks/useImagePreloader.ts

@@ -0,0 +1,268 @@
+"use client";
+
+/**
+ * useImagePreloader - Preload images before they enter the viewport
+ *
+ * Uses IntersectionObserver with a configurable rootMargin to detect when images
+ * are approaching the viewport and preload them. This provides consistent behavior
+ * across browsers (Safari's native lazy loading has a more conservative threshold
+ * than Chrome).
+ *
+ * @example
+ * ```tsx
+ * function ImageGallery({ images }) {
+ *   const { registerElement, isPreloaded } = useImagePreloader({
+ *     preloadMargin: 1000,
+ *   });
+ *
+ *   return images.map((img, index) => (
+ *     <div
+ *       key={index}
+ *       ref={(el) => registerElement(`img-${index}`, el, img.src)}
+ *     >
+ *       <img
+ *         src={img.src}
+ *         loading={index <= 1 || isPreloaded(img.src) ? "eager" : "lazy"}
+ *       />
+ *     </div>
+ *   ));
+ * }
+ * ```
+ */
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { observe } from "./visibility/observerPool";
+
+export interface UseImagePreloaderOptions {
+  /** Distance in pixels before viewport to start preloading (default: 1000) */
+  preloadMargin?: number;
+  /** Maximum concurrent preloads (default: 2) */
+  maxConcurrent?: number;
+}
+
+export interface UseImagePreloaderReturn {
+  /**
+   * Register an element for visibility-based preloading.
+   * Can be used as a ref callback.
+   */
+  registerElement: (
+    key: string,
+    element: HTMLElement | null,
+    src: string | undefined
+  ) => void;
+  /** Set of image URLs that have been preloaded */
+  preloadedUrls: Set<string>;
+  /** Check if a specific URL has been preloaded */
+  isPreloaded: (src: string | undefined) => boolean;
+}
+
+interface PreloadEntry {
+  element: HTMLElement;
+  src: string;
+  unobserve?: () => void;
+}
+
+/**
+ * Hook for preloading images before they enter the viewport.
+ *
+ * Uses IntersectionObserver with a configurable margin to detect images
+ * approaching the viewport and trigger preloading via hidden Image objects.
+ */
+export function useImagePreloader(
+  options: UseImagePreloaderOptions = {}
+): UseImagePreloaderReturn {
+  const { preloadMargin = 1000, maxConcurrent = 2 } = options;
+
+  // Track which URLs have been preloaded
+  const [preloadedUrls, setPreloadedUrls] = useState<Set<string>>(new Set());
+
+  // Track registered elements
+  const entriesRef = useRef<Map<string, PreloadEntry>>(new Map());
+
+  // Track currently preloading count
+  const preloadingCountRef = useRef(0);
+
+  // Queue for pending preloads
+  const preloadQueueRef = useRef<string[]>([]);
+
+  // Track preloading state (to avoid duplicate preloads)
+  const preloadingUrlsRef = useRef<Set<string>>(new Set());
+
+  // Process the preload queue
+  const processQueue = useCallback(() => {
+    while (
+      preloadingCountRef.current < maxConcurrent &&
+      preloadQueueRef.current.length > 0
+    ) {
+      const src = preloadQueueRef.current.shift()!;
+
+      // Skip if already preloaded or preloading
+      if (
+        preloadingUrlsRef.current.has(src) ||
+        preloadedUrls.has(src)
+      ) {
+        continue;
+      }
+
+      preloadingUrlsRef.current.add(src);
+      preloadingCountRef.current++;
+
+      // Preload using hidden Image object
+      const img = new Image();
+      img.crossOrigin = 'anonymous';
+      img.src = src;
+
+      const handleComplete = () => {
+        preloadingCountRef.current--;
+        preloadingUrlsRef.current.delete(src);
+
+        // Add to preloaded set
+        setPreloadedUrls((prev) => {
+          const next = new Set(prev);
+          next.add(src);
+          return next;
+        });
+
+        // Process next in queue
+        processQueue();
+      };
+
+      img.onload = handleComplete;
+      img.onerror = handleComplete; // Still mark as "preloaded" to avoid retries
+    }
+  }, [maxConcurrent, preloadedUrls]);
+
+  // IntersectionObserver options
+  const observerOptionsRef = useRef<IntersectionObserverInit>({
+    rootMargin: `${preloadMargin}px 0px`,
+    threshold: 0,
+  });
+
+  // Update observer options if margin changes
+  useEffect(() => {
+    observerOptionsRef.current = {
+      rootMargin: `${preloadMargin}px 0px`,
+      threshold: 0,
+    };
+  }, [preloadMargin]);
+
+  // Register element for preloading
+  const registerElement = useCallback(
+    (key: string, element: HTMLElement | null, src: string | undefined) => {
+      const entries = entriesRef.current;
+
+      // Get existing entry
+      const existingEntry = entries.get(key);
+
+      // If element is null, unregister
+      if (!element) {
+        if (existingEntry?.unobserve) {
+          existingEntry.unobserve();
+        }
+        entries.delete(key);
+        return;
+      }
+
+      // If no src, nothing to preload
+      if (!src) {
+        if (existingEntry?.unobserve) {
+          existingEntry.unobserve();
+        }
+        entries.delete(key);
+        return;
+      }
+
+      // If already preloaded, no need to observe
+      if (preloadedUrls.has(src)) {
+        if (existingEntry?.unobserve) {
+          existingEntry.unobserve();
+        }
+        entries.delete(key);
+        return;
+      }
+
+      // If element/src unchanged, keep existing observer
+      if (existingEntry?.element === element && existingEntry?.src === src) {
+        return;
+      }
+
+      // Clean up old observer if exists
+      if (existingEntry?.unobserve) {
+        existingEntry.unobserve();
+      }
+
+      // Create new entry
+      const entry: PreloadEntry = {
+        element,
+        src,
+      };
+
+      // SSR check - IntersectionObserver not available
+      if (typeof IntersectionObserver === "undefined") {
+        // On SSR, mark everything as preloaded to fall back to native behavior
+        setPreloadedUrls((prev) => {
+          const next = new Set(prev);
+          next.add(src);
+          return next;
+        });
+        entries.set(key, entry);
+        return;
+      }
+
+      // Set up observer
+      entry.unobserve = observe(
+        element,
+        (intersectionEntry) => {
+          if (intersectionEntry.isIntersecting) {
+            // Element is in preload zone - queue for preload
+            if (
+              !preloadingUrlsRef.current.has(src) &&
+              !preloadedUrls.has(src) &&
+              !preloadQueueRef.current.includes(src)
+            ) {
+              preloadQueueRef.current.push(src);
+              processQueue();
+            }
+
+            // Unobserve after triggering preload
+            if (entry.unobserve) {
+              entry.unobserve();
+              entry.unobserve = undefined;
+            }
+          }
+        },
+        observerOptionsRef.current
+      );
+
+      entries.set(key, entry);
+    },
+    [preloadedUrls, processQueue]
+  );
+
+  // Check if URL is preloaded
+  const isPreloaded = useCallback(
+    (src: string | undefined): boolean => {
+      if (!src) return false;
+      return preloadedUrls.has(src);
+    },
+    [preloadedUrls]
+  );
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      entriesRef.current.forEach((entry) => {
+        if (entry.unobserve) {
+          entry.unobserve();
+        }
+      });
+      entriesRef.current.clear();
+    };
+  }, []);
+
+  return {
+    registerElement,
+    preloadedUrls,
+    isPreloaded,
+  };
+}