@zezosoft/zezo-ott-react-native-ui-kit 1.1.2 → 1.1.5

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

@@ -12,3 +12,6 @@ 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,
+  };
+};

package/src/hooks/useCards.ts

@@ -0,0 +1,228 @@
+/**
+ * Global Card Hook (No duplicates + single data key)
+ *
+ * Provides a unified interface for managing card data with:
+ * - Automatic deduplication
+ * - Skeleton loading states
+ * - Pagination support
+ * - Optimized performance
+ */
+
+import { useMemo, useCallback } from 'react';
+import type { IContentData } from '@zezosoft/zezo-ott-api-client';
+import { usePaginatedSection } from './usePaginatedSection';
+import type { IAdItem, MoreFetchData } from '../types';
+import { dummyContentData } from '../constants/dummySections';
+
+export type CardSource =
+  | { data: (IContentData | IAdItem)[] }
+  | (IContentData | IAdItem)[]
+  | null;
+
+export type UseCardsOptions = {
+  sectionId: string;
+  data?: CardSource;
+  fetchMore?: MoreFetchData<IContentData>;
+  loading?: boolean;
+  initialSkeleton?: number;
+  pagingSkeleton?: number;
+  adsRender?: boolean; // If false, ads will be filtered out from listData
+};
+
+export type UseCardsReturn = {
+  listData: (IContentData | IAdItem)[]; // ✔ Mixed array of content and ads
+  pagination: {
+    hasNextPage: boolean;
+    nextPage: number | null;
+  } | null;
+  isPaging: boolean;
+  hasMore: boolean;
+  loadMore: (page: number | null) => Promise<void>;
+  isEmpty: boolean;
+};
+
+// -----------------------------------------------------------
+// Constants
+// -----------------------------------------------------------
+
+const DEFAULT_INITIAL_SKELETON = 5;
+const DEFAULT_PAGING_SKELETON = 3;
+
+// -----------------------------------------------------------
+// Helpers
+// -----------------------------------------------------------
+
+/**
+ * Normalizes different data source formats into a single array
+ */
+const normalize = (src: CardSource): (IContentData | IAdItem)[] => {
+  if (!src) return [];
+  if (Array.isArray(src)) return src;
+  return src.data ?? [];
+};
+
+/**
+ * Removes duplicate items by _id using Map for O(n) performance
+ * Preserves order of first occurrence
+ * Handles both IContentData and IAdItem types
+ */
+const uniqueById = (
+  list: (IContentData | IAdItem)[]
+): (IContentData | IAdItem)[] => {
+  if (list.length === 0) return [];
+
+  const seen = new Map<string, IContentData | IAdItem>();
+  const result: (IContentData | IAdItem)[] = [];
+
+  for (const item of list) {
+    // Handle ads - check for type property and use appropriate ID field
+    if ('type' in item && item.type === 'ads') {
+      const adItem = item as IAdItem;
+      // Ads might have _id (from IServeAd) or use mediaUrl as identifier
+      let id: string;
+      if ('_id' in adItem && adItem._id) {
+        id = String(adItem._id);
+      } else if ('mediaUrl' in adItem && adItem.mediaUrl) {
+        id = `ad-${adItem.mediaUrl}`;
+      } else {
+        id = `ad-${Math.random()}`;
+      }
+
+      if (!seen.has(id)) {
+        seen.set(id, adItem);
+        result.push(adItem);
+      }
+      continue;
+    }
+
+    // Handle content items
+    const contentItem = item as IContentData;
+    if (!contentItem?._id) continue; // Skip items without valid IDs
+
+    const id = String(contentItem._id);
+    if (!seen.has(id)) {
+      seen.set(id, contentItem);
+      result.push(contentItem);
+    }
+  }
+
+  return result;
+};
+
+/**
+ * Creates skeleton items for loading states
+ * Memoized by count to avoid unnecessary recreations
+ * Returns IContentData[] for skeleton loading (ads don't need skeletons)
+ */
+const createSkeletonItems = (count: number, prefix: string): IContentData[] => {
+  if (count <= 0) return [];
+  return Array.from({ length: count }, (_, i) =>
+    dummyContentData(`${prefix}-${i}`)
+  );
+};
+
+// -----------------------------------------------------------
+// Hook
+// -----------------------------------------------------------
+
+export function useCards({
+  sectionId,
+  data,
+  fetchMore,
+  loading = false,
+  initialSkeleton = DEFAULT_INITIAL_SKELETON,
+  pagingSkeleton = DEFAULT_PAGING_SKELETON,
+  adsRender = false,
+}: UseCardsOptions): UseCardsReturn {
+  // Normalize input data
+  const baseItems = useMemo(() => normalize(data ?? { data: [] }), [data]);
+
+  // Use pagination hook for data management
+  const {
+    data: list,
+    pagination,
+    loadMoreData,
+    isPaginating,
+    hasMore,
+  } = usePaginatedSection<IContentData | IAdItem>(
+    sectionId,
+    fetchMore,
+    baseItems,
+    loading
+  );
+
+  // Apply deduplication to the list (handles both content and ads)
+  const uniqueList = useMemo(
+    () => uniqueById(list as (IContentData | IAdItem)[]),
+    [list]
+  );
+
+  // Memoize skeleton items - only recreate when count changes
+  const initialSkeletonItems = useMemo(
+    () => createSkeletonItems(initialSkeleton, 'sk'),
+    [initialSkeleton]
+  );
+
+  const pagingSkeletonItems = useMemo(
+    () => createSkeletonItems(pagingSkeleton, 'pagination-skeleton'),
+    [pagingSkeleton]
+  );
+
+  // Filter ads if adsRender is false
+  const filteredList = useMemo(() => {
+    if (adsRender) return uniqueList;
+    return uniqueList.filter(
+      (item): item is IContentData => item.type !== 'ads'
+    );
+  }, [uniqueList, adsRender]);
+
+  // Final data array for UI rendering
+  // Handles loading states and pagination skeletons
+  // Returns mixed array of IContentData | IAdItem (or only IContentData if adsRender is false)
+  const items = useMemo(() => {
+    // Show initial skeleton during initial load
+    if (loading) return initialSkeletonItems as (IContentData | IAdItem)[];
+
+    // Show data with pagination skeleton when loading more
+    if (isPaginating && filteredList.length > 0) {
+      return [
+        ...filteredList,
+        ...(pagingSkeletonItems as (IContentData | IAdItem)[]),
+      ];
+    }
+
+    // Return filtered list (with or without ads based on adsRender)
+    return filteredList;
+  }, [
+    loading,
+    isPaginating,
+    filteredList,
+    initialSkeletonItems,
+    pagingSkeletonItems,
+  ]);
+
+  // Determine if section is empty (only when not loading and no data)
+  const isEmpty = useMemo(
+    () => !loading && filteredList.length === 0,
+    [loading, filteredList.length]
+  );
+
+  // Memoize loadMore callback to prevent unnecessary re-renders
+  const handleLoadMore = useCallback(
+    async (page: number | null) => {
+      if (page && hasMore && !isPaginating) {
+        await loadMoreData(page);
+      }
+    },
+    [loadMoreData, hasMore, isPaginating]
+  );
+
+  return {
+    listData: items,
+    pagination,
+    isPaging: isPaginating,
+    hasMore,
+    loadMore: handleLoadMore,
+    isEmpty,
+  };
+}

package/src/hooks/usePaginatedSection.ts

@@ -3,7 +3,21 @@
  * @lastModified Wed 25 Jun 2025 at 12:00 PM
  */
 import React, { useCallback, useState } from 'react';
-import type { MoreFetchData } from '../types';
+import type { ISectionMeta } from '../types';
+
+export type MoreFetchData<T> = ({
+  sectionId,
+  meta,
+}: {
+  sectionId: string;
+  meta: {
+    hasNextPage: boolean;
+    nextPage: number;
+  };
+}) => Promise<{
+  data: T[];
+  meta: ISectionMeta;
+} | null>;
 
 export function usePaginatedSection<T>(
   sectionId: string,
@@ -19,7 +33,7 @@ export function usePaginatedSection<T>(
     hasNextPage: true,
     nextPage: 2,
   });
-  const [loading, setLoading] = useState(false);
+  const [isPaginating, setIsPaginating] = useState(false);
 
   // Sync initial data on mount or loading complete
   React.useEffect(() => {
@@ -30,9 +44,9 @@ export function usePaginatedSection<T>(
 
   const loadMoreData = useCallback(
     async (page: number | null) => {
-      if (!page || loading || !pagination.hasNextPage || !fetchFn) return;
+      if (!page || isPaginating || !pagination.hasNextPage || !fetchFn) return;
 
-      setLoading(true);
+      setIsPaginating(true);
       try {
         const res = await fetchFn({
           sectionId,
@@ -44,6 +58,11 @@ export function usePaginatedSection<T>(
 
         if (!res || !res.data || !res.meta?.pagination) {
           console.warn(`⚠️ Invalid response for section: ${sectionId}`, res);
+          // Stop further pagination attempts for this section
+          setPagination({
+            hasNextPage: false,
+            nextPage: null,
+          });
           return;
         }
 
@@ -66,16 +85,16 @@ export function usePaginatedSection<T>(
       } catch (err) {
         console.error(`❌ Error loading section [${sectionId}]:`, err);
       } finally {
-        setLoading(false);
+        setIsPaginating(false);
       }
     },
-    [loading, pagination.hasNextPage, fetchFn, sectionId]
+    [isPaginating, pagination.hasNextPage, fetchFn, sectionId]
   );
 
   return {
     data,
     pagination,
-    loading,
+    isPaginating,
     hasMore: pagination.hasNextPage,
     loadMoreData,
   };