@zezosoft/zezo-ott-react-native-ui-kit 1.1.1 → 1.1.3

package/src/hooks/Images/useImageLoader.ts

@@ -0,0 +1,206 @@
+/**
+ * @author Naresh Dhamu
+ * @lastModified Wed 26 Nov 2025 at 02:19 PM
+ */
+
+import { useState, useEffect, useMemo, useCallback, useRef } from 'react';
+import FastImage from 'react-native-fast-image';
+import { isValidImageUrl, isLocalFile } from './useImageValidation';
+
+// Module-level cache to track successfully loaded images
+const loadedImageCache = new Set<string>();
+
+export type UseImageLoaderOptions = {
+  imageUri: string;
+  isLoading?: boolean;
+  enablePreload?: boolean;
+  onError?: () => void;
+  onLoad?: () => void;
+  onLoadStart?: () => void;
+};
+
+export type UseImageLoaderReturn = {
+  imageLoading: boolean;
+  imageError: boolean;
+  hasValidImage: boolean;
+  isImageCached: boolean;
+  showSkeleton: boolean;
+  showFallback: boolean;
+  imageSource: {
+    uri: string;
+    cache?: typeof FastImage.cacheControl.immutable;
+    priority?: typeof FastImage.priority.normal;
+  };
+  handleLoad: () => void;
+  handleError: () => void;
+  handleLoadStart?: () => void;
+};
+
+/**
+ * Custom hook to manage image loading state, caching, and validation
+ * @param options - Configuration options for image loading
+ * @returns Object containing image state and handlers
+ */
+export const useImageLoader = ({
+  imageUri,
+  isLoading = false,
+  enablePreload = false,
+  onError,
+  onLoad,
+  onLoadStart,
+}: UseImageLoaderOptions): UseImageLoaderReturn => {
+  const [imageLoading, setImageLoading] = useState(true);
+  const [imageError, setImageError] = useState(false);
+  const previousUriRef = useRef<string>('');
+  const onErrorRef = useRef(onError);
+
+  // Keep onError ref updated
+  useEffect(() => {
+    onErrorRef.current = onError;
+  }, [onError]);
+
+  // Validate image URL
+  const hasValidImage = useMemo(() => isValidImageUrl(imageUri), [imageUri]);
+
+  // Check if image is already cached
+  const isImageCached = useMemo(
+    () => loadedImageCache.has(imageUri),
+    [imageUri]
+  );
+
+  // Handle image state changes
+  useEffect(() => {
+    const uriChanged = previousUriRef.current !== imageUri;
+
+    // Update ref when URI changes
+    if (uriChanged) {
+      previousUriRef.current = imageUri;
+      // Reset error state when URI changes to allow new image to load
+      setImageError(false);
+    }
+
+    // Reset states when loading
+    if (isLoading) {
+      setImageLoading(true);
+      setImageError(false);
+      return;
+    }
+
+    // Handle valid image URL
+    if (hasValidImage) {
+      const isLocal = isLocalFile(imageUri);
+
+      if (isImageCached) {
+        // Image is cached, mark as loaded
+        setImageLoading(false);
+        setImageError(false);
+      } else {
+        // Image not cached, start loading
+        setImageLoading(true);
+        setImageError(false);
+        // Preload image if enabled (only for remote URLs, not local files)
+        if (enablePreload && !isLocal && uriChanged) {
+          FastImage.preload([{ uri: imageUri }]);
+        }
+      }
+    } else {
+      // For empty or invalid URLs
+      if (!imageUri || imageUri.trim() === '') {
+        // Empty URI - show error immediately (no point in trying to load)
+        setImageLoading(false);
+        setImageError(true);
+      } else {
+        // Invalid URL format - attempt to load anyway
+        // FastImage might still be able to load it, so keep loading state
+        setImageLoading(true);
+        setImageError(false);
+      }
+    }
+  }, [imageUri, hasValidImage, isLoading, isImageCached, enablePreload]);
+
+  // Determine if skeleton should be shown
+  const showSkeleton = useMemo(
+    () => isLoading || (imageLoading && !imageError),
+    [isLoading, imageLoading, imageError]
+  );
+
+  // Determine if fallback should be shown
+  // Show fallback when:
+  // 1. Not showing skeleton
+  // 2. AND (imageError is true OR URI is empty/invalid)
+  // This allows images with invalid format to attempt loading, but shows fallback for empty URIs
+  const showFallback = useMemo(() => {
+    if (showSkeleton) return false;
+    // Empty URI - show fallback immediately
+    if (!imageUri || imageUri.trim() === '') return true;
+    // Show fallback only after actual error (not just invalid format)
+    return imageError && !imageLoading;
+  }, [showSkeleton, imageError, imageLoading, imageUri]);
+
+  // Check if image is a local file
+  const isLocal = useMemo(() => isLocalFile(imageUri), [imageUri]);
+
+  // Image source configuration
+  // Local files don't need cache control, cloud URIs do
+  const imageSource = useMemo(() => {
+    const source: {
+      uri: string;
+      cache?: typeof FastImage.cacheControl.immutable;
+      priority?: typeof FastImage.priority.normal;
+    } = {
+      uri: imageUri,
+    };
+
+    // Only add cache control for remote URLs, not local files
+    if (!isLocal) {
+      source.cache = FastImage.cacheControl.immutable;
+      source.priority = FastImage.priority.normal;
+    }
+
+    return source;
+  }, [imageUri, isLocal]);
+
+  // Image event handlers
+  const handleLoad = useCallback(() => {
+    setImageLoading(false);
+    setImageError(false);
+    if (imageUri) {
+      loadedImageCache.add(imageUri);
+    }
+    if (onLoad) {
+      onLoad();
+    }
+  }, [imageUri, onLoad]);
+
+  const handleError = useCallback(() => {
+    setImageLoading(false);
+
+    setImageError(true);
+    if (onError) {
+      onError();
+    }
+  }, [onError]);
+
+  const handleLoadStart = useCallback(() => {
+    if (!isImageCached) {
+      setImageLoading(true);
+      setImageError(false);
+      if (onLoadStart) {
+        onLoadStart();
+      }
+    }
+  }, [isImageCached, onLoadStart]);
+
+  return {
+    imageLoading,
+    imageError,
+    hasValidImage,
+    isImageCached,
+    showSkeleton,
+    showFallback,
+    imageSource,
+    handleLoad,
+    handleError,
+    handleLoadStart: enablePreload ? handleLoadStart : undefined,
+  };
+};

package/src/hooks/Images/useImageValidation.ts

@@ -0,0 +1,36 @@
+/**
+ * @author Naresh Dhamu
+ * @lastModified Wed 26 Nov 2025 at 02:19 PM
+ */
+
+const IMAGE_URL_REGEX = /\.(jpg|jpeg|png|webp|gif|bmp)$/i;
+
+/**
+ * Utility function to check if URL is a local file path
+ * @param url - The URL to check
+ * @returns true if the URL is a local file path, false otherwise
+ */
+export const isLocalFile = (url: string): boolean => {
+  return url?.startsWith?.('file://') || url?.startsWith?.('/');
+};
+
+/**
+ * Utility function to validate image URL (supports both cloud URIs and local file paths)
+ * @param url - The URL to validate
+ * @returns true if the URL is a valid image URL, false otherwise
+ */
+export const isValidImageUrl = (url: string | null | undefined): boolean => {
+  if (!url || typeof url !== 'string') return false;
+  const cleaned = url.trim();
+
+  // Check for local file paths
+  if (isLocalFile(cleaned)) {
+    return IMAGE_URL_REGEX.test(cleaned) || cleaned.length > 0;
+  }
+
+  // Check for cloud URIs (http/https)
+  return (
+    (cleaned?.startsWith?.('http://') || cleaned?.startsWith?.('https://')) &&
+    IMAGE_URL_REGEX.test(cleaned)
+  );
+};

package/src/hooks/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @author Naresh Dhamu
+ * @lastModified Optimized for performance
+ */
+
+export * from './useDebounce';
+export * from './useKeyboard';
+export * from './useNavigationMode';
+export * from './usePaginatedSection';
+export * from './useSplashCache';
+export * from './usePrevious';
+export * from './useSafeCallback';
+export * from './useSkeletonItems';
+export * from './useThemeColors';
+export * from './useCards';
+export * from './Images';
+export * from './useAdTracking';

package/src/hooks/useAdTracking.ts

@@ -0,0 +1,349 @@
+import { useRef, useMemo, useCallback, useEffect } from 'react';
+import { type View, Dimensions } from 'react-native';
+import type { IServeAd } from '@zezosoft/zezo-ott-api-client';
+
+const CHECK_INTERVAL = 500;
+const INITIAL_CHECK_DELAY = 100;
+
+export interface ViewportOffsets {
+  top: number;
+  bottom: number;
+  left: number;
+  right: number;
+}
+
+export interface ScreenDimensions {
+  width: number;
+  height: number;
+}
+
+export interface UseAdTrackingOptions {
+  ad: IServeAd;
+  onDisplayAds?: (ad: IServeAd) => void;
+  isLoading?: boolean;
+  screenDimensions?: ScreenDimensions;
+  viewportOffsets?: ViewportOffsets;
+}
+
+export interface UseAdTrackingReturn {
+  viewRef: React.RefObject<View | null>;
+  layoutRef: React.MutableRefObject<{
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  } | null>;
+  hasDisplayed: React.MutableRefObject<boolean>;
+  adUniqueId: string;
+  handleLayout: () => void;
+}
+
+// Global set to track displayed ads - prevents duplicate tracking
+const globalDisplayedAds = new Set<string>();
+// Lock to prevent race conditions when checking and adding ads
+const trackingLock = new Map<string, boolean>();
+
+export const extractToken = (trackingUrl?: string): string => {
+  if (!trackingUrl) return '';
+  try {
+    const url = new URL(trackingUrl);
+    return url.searchParams.get('token') || '';
+  } catch {
+    const match = trackingUrl.match(/[?&]token=([^&]+)/);
+    return match?.[1] || '';
+  }
+};
+
+/**
+ * Creates a unique ID for an ad to prevent duplicate tracking
+ * Priority: _id > token > mediaUrl > fallback
+ */
+export const createAdUniqueId = (ad: IServeAd): string => {
+  // First try to use _id if available (most reliable)
+  if ('_id' in ad && ad._id) {
+    return `ad-${String(ad._id)}`;
+  }
+
+  // Then try token from tracking URL
+  const token = extractToken(ad.tracking?.impression);
+  if (token) {
+    return `ad-token-${token}`;
+  }
+
+  // Then use mediaUrl
+  const mediaUrl = ad.mediaUrl || '';
+  if (mediaUrl) {
+    return `ad-media-${mediaUrl}`;
+  }
+
+  // Last resort: use a combination of available fields
+  const clickUrl = ad.tracking?.click || '';
+  if (clickUrl) {
+    return `ad-click-${clickUrl}`;
+  }
+
+  // Fallback (should rarely happen)
+  return `ad-fallback-${Date.now()}-${Math.random()}`;
+};
+
+export const useAdTracking = (
+  options: UseAdTrackingOptions
+): UseAdTrackingReturn => {
+  const {
+    ad,
+    onDisplayAds,
+    isLoading = false,
+    screenDimensions: propScreenDimensions,
+    viewportOffsets: propViewportOffsets,
+  } = options;
+
+  const viewRef = useRef<View>(null);
+  const layoutRef = useRef<{
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  } | null>(null);
+  const hasDisplayedRef = useRef<boolean>(false);
+
+  const onDisplayAdsRef = useRef(onDisplayAds);
+  const adRef = useRef(ad);
+  const isLoadingRef = useRef(isLoading);
+
+  useEffect(() => {
+    onDisplayAdsRef.current = onDisplayAds;
+    adRef.current = ad;
+    isLoadingRef.current = isLoading;
+  }, [onDisplayAds, ad, isLoading]);
+
+  const adUniqueId = useMemo(() => createAdUniqueId(ad), [ad]);
+
+  const screenDimensions = useMemo(
+    () => propScreenDimensions || Dimensions.get('window'),
+    [propScreenDimensions]
+  );
+
+  const viewportOffsets = useMemo(
+    () => ({
+      top: propViewportOffsets?.top ?? 50,
+      bottom: propViewportOffsets?.bottom ?? 100,
+      left: propViewportOffsets?.left ?? 20,
+      right: propViewportOffsets?.right ?? 20,
+    }),
+    [
+      propViewportOffsets?.top,
+      propViewportOffsets?.bottom,
+      propViewportOffsets?.left,
+      propViewportOffsets?.right,
+    ]
+  );
+
+  const viewportBounds = useMemo(() => {
+    const { width: screenWidth, height: screenHeight } = screenDimensions;
+    return {
+      left: viewportOffsets.left,
+      right: screenWidth - viewportOffsets.right,
+      top: viewportOffsets.top,
+      bottom: screenHeight - viewportOffsets.bottom,
+    };
+  }, [screenDimensions, viewportOffsets]);
+
+  const checkVisibility = useCallback((): boolean => {
+    const layout = layoutRef.current;
+    if (!layout) {
+      return false;
+    }
+
+    const { x, y, width, height } = layout;
+
+    const isVisible =
+      x + width > viewportBounds.left &&
+      x < viewportBounds.right &&
+      y + height > viewportBounds.top &&
+      y < viewportBounds.bottom;
+
+    return isVisible;
+  }, [viewportBounds]);
+
+  const measureInWindow = useCallback((): void => {
+    const view = viewRef.current;
+    if (!view) return;
+
+    view.measureInWindow((x, y, width, height) => {
+      layoutRef.current = { x, y, width, height };
+    });
+  }, []);
+
+  /**
+   * Atomically checks and tracks ad display to prevent duplicate tracking
+   * Uses a lock mechanism to ensure only one instance can track the same ad
+   */
+  const trackAdDisplay = useCallback((): boolean => {
+    const currentOnDisplayAds = onDisplayAdsRef.current;
+    const currentIsLoading = isLoadingRef.current;
+
+    if (!currentOnDisplayAds || currentIsLoading) {
+      return false;
+    }
+
+    // Early return if already displayed by this instance
+    if (hasDisplayedRef.current) {
+      return false;
+    }
+
+    // Atomic check-and-set: if ad is already being tracked or displayed, return false
+    if (globalDisplayedAds.has(adUniqueId)) {
+      // Mark this instance as displayed to prevent further checks
+      hasDisplayedRef.current = true;
+      return false;
+    }
+
+    // Set lock to prevent other instances from tracking the same ad
+    if (trackingLock.get(adUniqueId) === true) {
+      return false;
+    }
+
+    // Acquire lock
+    trackingLock.set(adUniqueId, true);
+
+    try {
+      // Double-check after acquiring lock (another instance might have added it)
+      if (globalDisplayedAds.has(adUniqueId)) {
+        hasDisplayedRef.current = true;
+        return false;
+      }
+
+      // Mark as displayed in both local and global state
+      hasDisplayedRef.current = true;
+      globalDisplayedAds.add(adUniqueId);
+
+      // Call the tracking callback
+      currentOnDisplayAds(adRef.current);
+
+      return true;
+    } finally {
+      // Release lock after a short delay to ensure callback completes
+      setTimeout(() => {
+        trackingLock.delete(adUniqueId);
+      }, 100);
+    }
+  }, [adUniqueId]);
+
+  const checkAndTrackVisibility = useCallback((): void => {
+    // Early exit if already displayed
+    if (hasDisplayedRef.current) {
+      return;
+    }
+
+    // Early exit if ad is already tracked globally or locked
+    if (
+      globalDisplayedAds.has(adUniqueId) ||
+      trackingLock.get(adUniqueId) === true
+    ) {
+      // Mark this instance as displayed to prevent further checks
+      hasDisplayedRef.current = true;
+      return;
+    }
+
+    // Check visibility before tracking
+    if (!checkVisibility()) {
+      return;
+    }
+
+    // Attempt to track (will handle duplicate prevention internally)
+    trackAdDisplay();
+  }, [adUniqueId, checkVisibility, trackAdDisplay]);
+
+  const handleLayout = useCallback(() => {
+    const view = viewRef.current;
+    if (!view) return;
+
+    view.measureInWindow((x, y, width, height) => {
+      layoutRef.current = { x, y, width, height };
+      requestAnimationFrame(() => {
+        checkAndTrackVisibility();
+      });
+    });
+  }, [checkAndTrackVisibility]);
+
+  useEffect(() => {
+    if (isLoadingRef.current) {
+      return undefined;
+    }
+
+    let timeoutId: NodeJS.Timeout | null = null;
+    let rafId: number | null = null;
+
+    rafId = requestAnimationFrame(() => {
+      timeoutId = setTimeout(() => {
+        measureInWindow();
+        requestAnimationFrame(() => {
+          checkAndTrackVisibility();
+        });
+      }, INITIAL_CHECK_DELAY);
+    });
+
+    return () => {
+      if (rafId !== null) {
+        cancelAnimationFrame(rafId);
+      }
+      if (timeoutId !== null) {
+        clearTimeout(timeoutId);
+      }
+    };
+  }, [isLoading, checkAndTrackVisibility, measureInWindow]);
+
+  useEffect(() => {
+    if (
+      !onDisplayAdsRef.current ||
+      hasDisplayedRef.current ||
+      isLoadingRef.current
+    ) {
+      return undefined;
+    }
+
+    let rafId: number | null = null;
+    let lastCheckTime = 0;
+
+    const checkWithThrottle = () => {
+      const now = Date.now();
+
+      if (now - lastCheckTime < CHECK_INTERVAL) {
+        rafId = requestAnimationFrame(checkWithThrottle);
+        return;
+      }
+
+      lastCheckTime = now;
+
+      if (hasDisplayedRef.current || !viewRef.current) {
+        return;
+      }
+
+      measureInWindow();
+      requestAnimationFrame(() => {
+        if (!hasDisplayedRef.current) {
+          checkAndTrackVisibility();
+        }
+        if (!hasDisplayedRef.current) {
+          rafId = requestAnimationFrame(checkWithThrottle);
+        }
+      });
+    };
+
+    rafId = requestAnimationFrame(checkWithThrottle);
+
+    return () => {
+      if (rafId !== null) {
+        cancelAnimationFrame(rafId);
+      }
+    };
+  }, [checkAndTrackVisibility, measureInWindow]);
+
+  return {
+    viewRef,
+    layoutRef,
+    hasDisplayed: hasDisplayedRef,
+    adUniqueId,
+    handleLayout,
+  };
+};