@donotdev/components 0.0.4 → 0.0.6

package/dist/hooks/useIntersectionObserver.js

@@ -1,39 +1,92 @@
 // packages/components/src/hooks/useIntersectionObserver.ts
 /**
- * @fileoverview Intersection Observer Hook
- * @description React hook for observing element intersection with viewport. Provides intersection state and entry data for scroll-based animations.
- *
+ * @fileoverview useIntersectionObserver Hook - Basic Intersection Observation
+ * @description Lightweight hook for basic intersection observation with optimal performance
+ * @package @donotdev/components
  * @version 0.0.1
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
+ *
+ * Features:
+ * - CSR/SSR safe with proper fallbacks
+ * - Intersection Observer API with automatic cleanup
+ * - Once-only triggering option
+ * - TypeScript support with full type safety
+ * - Zero dependencies beyond React and framework utils
+ *
+ * Performance:
+ * - Uses native IntersectionObserver API
+ * - React 19 useSyncExternalStore pattern for optimal performance
+ * - Prevents tearing in concurrent rendering
+ * - Automatic cleanup prevents memory leaks
+ * - Minimal state updates with proper change detection
  */
-import { useRef, useEffect, useState, useCallback } from 'react';
-import { observeElement } from '../utils/intersectionObserver';
+import { useRef, useEffect, useSyncExternalStore, useMemo } from 'react';
 /**
- * Hook for intersection observer functionality
+ * useIntersectionObserver - Basic Intersection Observation Hook (React 19 Optimized)
+ *
+ * Lightweight hook for basic intersection observation with optimal performance.
+ * Uses React 19's useSyncExternalStore pattern for automatic cleanup, proper
+ * SSR handling, and tearing prevention in concurrent rendering.
+ *
+ * @param options - Configuration options for intersection observation
+ * @returns Object containing ref, isIntersecting state, and entry
+ *
+ * @example Basic intersection detection
+ * ```tsx
+ * function IntersectionComponent() {
+ *   const { ref, isIntersecting } = useIntersectionObserver();
+ *
+ *   return (
+ *     <div ref={ref} className={isIntersecting ? 'visible' : 'hidden'}>
+ *       Content that appears when intersecting
+ *     </div>
+ *   );
+ * }
+ * ```
  *
- * Provides a simple way to detect when an element enters/exits the viewport.
- * Replaces Framer Motion's useInView with our own implementation.
+ * @example With custom threshold
+ * ```tsx
+ * function ThresholdComponent() {
+ *   const { ref, isIntersecting } = useIntersectionObserver({
+ *     threshold: 0.5,
+ *     rootMargin: '50px'
+ *   });
+ *
+ *   return (
+ *     <div ref={ref}>
+ *       {isIntersecting ? '50% visible' : 'Not visible enough'}
+ *     </div>
+ *   );
+ * }
+ * ```
  *
- * @example Basic usage
+ * @example Once-only triggering (React 19 optimized)
  * ```tsx
- * const { ref, isIntersecting } = useIntersectionObserver({
- *   threshold: 0.3
- * });
+ * function OnceComponent() {
+ *   const { ref, isIntersecting } = useIntersectionObserver({ once: true });
  *
- * return (
- *   <div>
- *     {isIntersecting ? 'Visible!' : 'Not visible'}
- *   </div>
- * );
+ *   return (
+ *     <div ref={ref}>
+ *       {isIntersecting && <ExpensiveComponent />}
+ *     </div>
+ *   );
+ * }
  * ```
  *
- * @example With root margin (equivalent to Framer Motion's margin)
+ * @example SSR-safe implementation
  * ```tsx
- * const { ref, isIntersecting } = useIntersectionObserver({
- *   threshold: 0.3,
- *   rootMargin: '-70% 0px -30% 0px' // Trigger when 30% visible
- * });
+ * function SSRComponent() {
+ *   const { ref, isIntersecting } = useIntersectionObserver({
+ *     fallbackIntersecting: true // Shows content during SSR
+ *   });
+ *
+ *   return (
+ *     <div ref={ref}>
+ *       {isIntersecting ? 'Client-side' : 'SSR fallback'}
+ *     </div>
+ *   );
+ * }
  * ```
  *
  * @version 0.0.1
@@ -41,38 +94,128 @@ import { observeElement } from '../utils/intersectionObserver';
  * @author AMBROISE PARK Consulting
  */
 export function useIntersectionObserver(options = {}) {
-    const { threshold = 0.1, rootMargin = '0px', once = false } = options;
+    const { threshold = 0, root = null, rootMargin = '0px', once = false, fallbackIntersecting = true, } = options;
     const ref = useRef(null);
-    const [isIntersecting, setIsIntersecting] = useState(false);
-    const [hasTriggered, setHasTriggered] = useState(false);
-    const [entry, setEntry] = useState(null);
-    // Intersection observer callback
-    const handleIntersection = useCallback((intersectionEntry) => {
-        const isIntersectingNow = intersectionEntry.isIntersecting;
-        if (isIntersectingNow && (!hasTriggered || !once)) {
-            setIsIntersecting(true);
-            setHasTriggered(true);
-        }
-        else if (!isIntersectingNow && !once) {
-            setIsIntersecting(false);
-        }
-        setEntry(intersectionEntry);
-    }, [once, hasTriggered]);
-    // Set up intersection observer
-    useEffect(() => {
-        const element = ref.current;
-        if (!element)
-            return;
-        const cleanup = observeElement(element, handleIntersection, {
+    // Create intersection observer using React 19 patterns
+    const observer = useMemo(() => {
+        return createIntersectionObserver({
             threshold,
+            root,
             rootMargin,
+            once,
+            fallbackIntersecting,
         });
-        return cleanup;
-    }, [handleIntersection, threshold, rootMargin]);
+    }, [threshold, root, rootMargin, once, fallbackIntersecting]);
+    // Use useSyncExternalStore for optimal performance and proper tearing prevention
+    const state = useSyncExternalStore(observer.subscribe, observer.getSnapshot, observer.getServerSnapshot);
+    // Update observer when ref element changes
+    // Empty deps intentional: observer is stable from useMemo, ref updates are tracked internally
+    useEffect(() => {
+        if (ref.current) {
+            observer.setElement(ref.current);
+        }
+        return () => observer.setElement(null);
+    }, [observer]);
     return {
         ref,
-        isIntersecting,
-        hasTriggered,
-        entry,
+        isIntersecting: state.isIntersecting,
+        hasTriggered: state.hasTriggered,
+        entry: state.entry,
+    };
+}
+/**
+ * Create an intersection observer with React 19 patterns
+ * Follows same pattern as createLocalStorageObserver for consistency
+ */
+function createIntersectionObserver(options) {
+    const { threshold, root, rootMargin, once, fallbackIntersecting } = options;
+    let currentState = {
+        isIntersecting: fallbackIntersecting,
+        hasTriggered: false,
+        entry: null,
+    };
+    let listeners = new Set();
+    let intersectionObserver = null;
+    let currentElement = null;
+    let hasTriggered = false;
+    const handleIntersection = (entries) => {
+        const [entry] = entries;
+        if (!entry)
+            return;
+        const isIntersecting = entry.isIntersecting;
+        // Handle once option - disconnect after first intersection
+        if (once && isIntersecting && !hasTriggered) {
+            hasTriggered = true;
+            if (intersectionObserver) {
+                intersectionObserver.disconnect();
+                intersectionObserver = null;
+            }
+        }
+        // Update hasTriggered if intersecting for first time
+        if (isIntersecting && !hasTriggered) {
+            hasTriggered = true;
+        }
+        const newState = {
+            isIntersecting,
+            hasTriggered,
+            entry,
+        };
+        // Only update if state actually changed
+        if (newState.isIntersecting !== currentState.isIntersecting ||
+            newState.hasTriggered !== currentState.hasTriggered ||
+            newState.entry !== currentState.entry) {
+            currentState = newState;
+            listeners.forEach((listener) => listener());
+        }
+    };
+    const getSnapshot = () => {
+        return currentState;
+    };
+    const subscribe = (callback) => {
+        listeners.add(callback);
+        // If element is already set and we're on client, start observing
+        if (currentElement && !intersectionObserver && typeof window !== 'undefined') {
+            intersectionObserver = new IntersectionObserver(handleIntersection, {
+                threshold,
+                root,
+                rootMargin,
+            });
+            intersectionObserver.observe(currentElement);
+        }
+        return () => {
+            listeners.delete(callback);
+            // Cleanup observer when last listener is removed
+            if (listeners.size === 0 && intersectionObserver) {
+                intersectionObserver.disconnect();
+                intersectionObserver = null;
+            }
+        };
+    };
+    const setElement = (element) => {
+        // Disconnect existing observer
+        if (intersectionObserver) {
+            intersectionObserver.disconnect();
+            intersectionObserver = null;
+        }
+        currentElement = element;
+        // Observe new element if we have listeners and we're on client
+        if (element && listeners.size > 0 && typeof window !== 'undefined') {
+            intersectionObserver = new IntersectionObserver(handleIntersection, {
+                threshold,
+                root,
+                rootMargin,
+            });
+            intersectionObserver.observe(element);
+        }
+    };
+    return {
+        subscribe,
+        getSnapshot,
+        getServerSnapshot: () => ({
+            isIntersecting: fallbackIntersecting,
+            hasTriggered: false,
+            entry: null,
+        }),
+        setElement,
     };
 }