@xhsreds/reds-rn-next 0.9.1-feat-swiper202511031535 → 0.9.1-feat-0.10.0-rc202511031536

package/lib/types/components/Swiper/LazyPage.d.ts

@@ -1,7 +0,0 @@
-import React from "react";
-import type { LazyPageProps } from "./types";
-/**
- * LazyPage component that conditionally mounts/unmounts content
- * based on proximity to current page
- */
-export declare const LazyPage: React.FC<LazyPageProps>;

package/lib/types/components/Swiper/Swiper.d.ts

@@ -1,5 +0,0 @@
-import React from "react";
-import type { SwiperProps, SwiperRef } from "./types";
-export declare const Swiper: <T>(props: SwiperProps<T> & {
-    ref?: React.Ref<SwiperRef>;
-}) => React.ReactElement;

package/lib/types/components/Swiper/SwiperFlatList.d.ts

@@ -1,5 +0,0 @@
-import React from "react";
-import type { SwiperProps, SwiperRef } from "./types";
-export declare const SwiperFlatList: <T>(props: SwiperProps<T> & {
-    ref?: React.Ref<SwiperRef>;
-}) => React.ReactElement;

package/lib/types/components/Swiper/SwiperPagerView.d.ts

@@ -1,5 +0,0 @@
-import React from "react";
-import type { SwiperProps, SwiperRef } from "./types";
-export declare const SwiperPagerView: <T>(props: SwiperProps<T> & {
-    ref?: React.Ref<SwiperRef>;
-}) => React.ReactElement;

package/lib/types/components/Swiper/index.d.ts

@@ -1,24 +0,0 @@
-/**
- * Swiper - A performant, data-driven carousel component
- *
- * @example
- * ```tsx
- * import { Swiper, SwiperRef } from '@/components/Swiper'
- *
- * const swiperRef = useRef<SwiperRef>(null)
- *
- * <Swiper
- *   ref={swiperRef}
- *   data={items}
- *   renderItem={(item, index) => <ItemCard item={item} />}
- *   infinite
- *   onPageChange={(index) => console.log('Page:', index)}
- * />
- *
- * // Programmatic control
- * swiperRef.current?.next()
- * swiperRef.current?.goToPage(5)
- * ```
- */
-export { Swiper } from "./Swiper";
-export type { SwiperProps, SwiperRef } from "./types";

package/lib/types/components/Swiper/types.d.ts

@@ -1,166 +0,0 @@
-import { ReactNode } from "react";
-import { StyleProp, ViewStyle } from "react-native";
-/**
- * Props for the Swiper component
- */
-export interface SwiperProps<T> {
-    /** Array of data items to render */
-    data: T[];
-    /** Function to render each item */
-    renderItem: (item: T, index: number) => ReactNode;
-    /** Optional key extractor for list items */
-    keyExtractor?: (item: T, index: number) => string;
-    /** Enable infinite/loop scrolling */
-    infinite?: boolean;
-    /** Initial page index to display */
-    initialPage?: number;
-    /**
-     * Choose implementation: 'pagerView' or 'flatlist'
-     *
-     * PagerView (default):
-     * - Native ViewPager (Android) / UIPageViewController (iOS)
-     * - Smooth 60fps gestures
-     * - Better UX for small-medium datasets
-     *
-     * FlatList:
-     * - Built-in virtualization (better for large datasets)
-     * - removeClippedSubviews support
-     * - More predictable behavior across platforms
-     *
-     * Default: 'pagerView'
-     */
-    implementation?: "pagerView" | "flatlist";
-    /**
-     * Number of items to clone on each end for infinite scroll (default: 2)
-     *
-     * Can be set larger than array length for maximum buffering.
-     * Higher values = smoother fast scrolling, but more memory usage.
-     *
-     * Examples:
-     * - cloneCount=2: Default, good for most cases
-     * - cloneCount=5-10: Better for fast scrolling
-     * - cloneCount=20+: Maximum buffer for very fast scrolling
-     */
-    cloneCount?: number;
-    /**
-     * Number of pages to mount on each side of current page (default: 2)
-     *
-     * Note: When cloneCount is large, the effective mount window will
-     * automatically scale up to prevent blank pages during fast scrolling.
-     * Effective window = max(lazyMountWindow, cloneCount/10, capped at 10)
-     */
-    lazyMountWindow?: number;
-    /**
-     * Enable aggressive memory management by unmounting pages far from current position
-     *
-     * When true, pages beyond unmountThreshold will be unmounted to free memory.
-     * When false (default), pages stay mounted once loaded for better UX.
-     *
-     * Recommended: true for large datasets with heavy content (images/videos)
-     */
-    removeClippedPages?: boolean;
-    /**
-     * Distance from current page before unmounting (default: lazyMountWindow * 3)
-     * Only applies when removeClippedPages is true
-     */
-    unmountThreshold?: number;
-    /** Callback when page changes */
-    onPageChange?: (index: number) => void;
-    /** Callback when swiping to next page */
-    onNext?: (index: number) => void;
-    /** Callback when swiping to previous page */
-    onPrev?: (index: number) => void;
-    /** Callback when scroll state changes */
-    onPageScrollStateChanged?: (state: "idle" | "dragging" | "settling") => void;
-    /**
-     * Callback when user releases drag (before momentum scroll begins)
-     *
-     * FlatList implementation only.
-     * Fires when user lifts finger after dragging, before momentum animation starts.
-     * Useful for immediate UI updates (e.g., updating active indicator)
-     * while deferring expensive operations (e.g., data fetching) to onPageChange.
-     *
-     * @param index - The page index where drag ended (real index, not display index)
-     *
-     * @example
-     * <Swiper
-     *   implementation="flatlist"
-     *   onScrollEndDrag={(index) => updateActiveIndex(index)}  // Fast UI update
-     *   onPageChange={(index) => fetchData(index)}             // Slower data fetch
-     * />
-     */
-    onScrollEndDrag?: (index: number) => void;
-    /** Style for the pager container */
-    style?: StyleProp<ViewStyle>;
-    /** Margin between pages (Android only) */
-    pageMargin?: number;
-    /** Enable/disable scrolling */
-    scrollEnabled?: boolean;
-    /** Allow overdrag effect */
-    overdrag?: boolean;
-    /**
-     * Number of pages to keep off-screen on each side (Android only)
-     *
-     * This is a NATIVE Android API that destroys/recreates views automatically.
-     * More efficient than our JS-based removeClippedPages approach.
-     *
-     * Note: iOS doesn't support this - all pages stay in memory on iOS
-     *
-     * Examples:
-     * - offscreenPageLimit=1: Keep 1 page on each side (3 total in memory)
-     * - offscreenPageLimit=2: Keep 2 pages on each side (5 total in memory)
-     *
-     * Default: Android default is 1, but PagerView doesn't set a default
-     */
-    offscreenPageLimit?: number;
-    /** Custom placeholder component for unmounted pages */
-    renderPlaceholder?: (index: number) => ReactNode;
-}
-/**
- * Ref methods exposed by Swiper component
- */
-export interface SwiperRef {
-    /** Navigate to specific page */
-    goToPage: (index: number, animated?: boolean) => void;
-    /** Go to next page */
-    next: (animated?: boolean) => void;
-    /** Go to previous page */
-    prev: (animated?: boolean) => void;
-    /** Get current page index */
-    getCurrentPage: () => number;
-}
-/**
- * Props for LazyPage component
- */
-export interface LazyPageProps {
-    /** Whether this page should be mounted */
-    shouldMount: boolean;
-    /** Whether this page should be unmounted if far away */
-    shouldUnmount?: boolean;
-    /** Content to render when mounted */
-    children: ReactNode;
-    /** Optional placeholder when not mounted */
-    placeholder?: ReactNode;
-    /** Style for page container */
-    style?: StyleProp<ViewStyle>;
-}
-/**
- * Return type for infinite data preparation
- */
-export interface InfiniteDataResult<T> {
-    /** Data array with clones added */
-    displayData: T[];
-    /** Offset where real data starts */
-    offset: number;
-    /** Number of clones on each side */
-    cloneCount: number;
-}
-/**
- * Return type for jump calculation
- */
-export interface JumpResult {
-    /** Whether a jump is needed */
-    shouldJump: boolean;
-    /** Target index to jump to (if shouldJump is true) */
-    jumpTo?: number;
-}

package/lib/types/components/Swiper/utils.d.ts

@@ -1,42 +0,0 @@
-import type { InfiniteDataResult, JumpResult } from "./types";
-/**
- * Prepare data array for infinite scrolling by cloning boundary items
- *
- * @param data Original data array
- * @param infinite Whether infinite scroll is enabled
- * @param cloneCount Number of items to clone on each end (default: 2)
- *                   Can exceed data.length - will repeat entire array multiple times
- * @returns Object with displayData (with clones), offset, and cloneCount
- *
- * @example
- * // With data=[A,B,C] and cloneCount=2: [B,C,A,B,C,A,B]
- * // With data=[A,B,C] and cloneCount=5: [A,B,C,A,B,C,A,B,C,A,B]
- */
-export declare function prepareInfiniteData<T>(data: T[], infinite: boolean, cloneCount?: number): InfiniteDataResult<T>;
-/**
- * Calculate if a jump is needed after page change for infinite scroll
- *
- * @param newPage Current display page index
- * @param dataLength Length of original data array
- * @param offset Offset where real data starts
- * @param cloneCount Number of clones on each side
- * @returns Object indicating if jump is needed and target index
- */
-export declare function shouldJumpForInfinite(newPage: number, dataLength: number, offset: number, cloneCount: number): JumpResult;
-/**
- * Convert display index to real data index
- *
- * @param displayIndex Index in the display array (with clones)
- * @param offset Offset where real data starts
- * @param dataLength Length of original data array
- * @returns Real index in original data array
- */
-export declare function getRealIndex(displayIndex: number, offset: number, dataLength: number): number;
-/**
- * Get display index from real data index
- *
- * @param realIndex Index in original data array
- * @param offset Offset where real data starts
- * @returns Display index in display array (with clones)
- */
-export declare function getDisplayIndex(realIndex: number, offset: number): number;

package/src/components/Swiper/LazyPage.tsx

@@ -1,44 +0,0 @@
-import React, { useState, useEffect } from "react";
-import { View, StyleSheet, Dimensions } from "react-native";
-import type { LazyPageProps } from "./types";
-
-/**
- * LazyPage component that conditionally mounts/unmounts content
- * based on proximity to current page
- */
-export const LazyPage: React.FC<LazyPageProps> = ({
-  shouldMount,
-  shouldUnmount = false,
-  children,
-  placeholder,
-  style,
-}) => {
-  const [mounted, setMounted] = useState(false);
-
-  useEffect(() => {
-    if (shouldMount && !mounted) {
-      // Mount the page when it enters the window
-      setMounted(true);
-    } else if (shouldUnmount && mounted) {
-      // Unmount the page when it's far from current position
-      // This helps free memory for large datasets
-      setMounted(false);
-    }
-    // Note: By default (shouldUnmount=false), pages stay mounted for better UX
-    // Enable shouldUnmount for aggressive memory management
-  }, [shouldMount, shouldUnmount, mounted]);
-
-  return (
-    <View style={[styles.page, style]}>{mounted ? children : placeholder || <View style={styles.placeholder} />}</View>
-  );
-};
-
-const styles = StyleSheet.create({
-  page: {
-    flex: 1,
-  },
-  placeholder: {
-    flex: 1,
-    backgroundColor: "transparent",
-  },
-});

package/src/components/Swiper/Swiper.tsx

@@ -1,31 +0,0 @@
-import React, { forwardRef } from "react";
-import type { SwiperProps, SwiperRef } from "./types";
-import { SwiperPagerView } from "./SwiperPagerView";
-import { SwiperFlatList } from "./SwiperFlatList";
-
-/**
- * Swiper Component - A performant, data-driven carousel with infinite scroll support
- *
- * Features:
- * - Two implementations: PagerView (default) and FlatList
- * - Lazy mounting for performance with large datasets
- * - Infinite/loop scrolling with seamless transitions
- * - Programmatic control via ref methods
- * - Event callbacks for page changes
- * - Nested scroll support
- * - TypeScript generic support for type-safe data
- */
-function SwiperComponent<T>(props: SwiperProps<T>, ref: React.Ref<SwiperRef>) {
-  const { implementation = "pagerView" } = props;
-
-  if (implementation === "flatlist") {
-    return <SwiperFlatList ref={ref} {...props} />;
-  }
-
-  return <SwiperPagerView ref={ref} {...props} />;
-}
-
-// Export with generic type support
-export const Swiper = forwardRef(SwiperComponent) as <T>(
-  props: SwiperProps<T> & { ref?: React.Ref<SwiperRef> },
-) => React.ReactElement;

package/src/components/Swiper/SwiperFlatList.tsx

@@ -1,299 +0,0 @@
-import React, { forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState } from "react";
-import { FlatList, StyleSheet, View, LayoutChangeEvent } from "react-native";
-import type { SwiperProps, SwiperRef } from "./types";
-import { prepareInfiniteData, shouldJumpForInfinite, getRealIndex, getDisplayIndex } from "./utils";
-
-/**
- * FlatList-based Swiper implementation
- */
-function SwiperFlatListComponent<T>(props: SwiperProps<T>, ref: React.Ref<SwiperRef>) {
-  const {
-    data,
-    renderItem,
-    keyExtractor,
-    infinite = false,
-    initialPage = 0,
-    cloneCount = 2,
-    onPageChange,
-    onNext,
-    onPrev,
-    onScrollEndDrag,
-    onPageScrollStateChanged,
-    style,
-  } = props;
-
-  // Refs
-  const flatListRef = useRef<FlatList>(null);
-  const currentPageRef = useRef<number>(initialPage);
-  const isJumpingRef = useRef<boolean>(false);
-  const scrollingRef = useRef<boolean>(false);
-
-  // State
-  const [currentPage, setCurrentPage] = useState(initialPage);
-  const [containerWidth, setContainerWidth] = useState(0);
-
-  // Prepare data for infinite scrolling
-  const {
-    displayData,
-    offset,
-    cloneCount: actualCloneCount,
-  } = useMemo(() => {
-    return prepareInfiniteData(data, infinite, cloneCount);
-  }, [data, infinite, cloneCount]);
-
-  // Calculate adjusted initial page for infinite mode
-  const adjustedInitialPage = useMemo(() => {
-    return infinite ? getDisplayIndex(initialPage, offset) : initialPage;
-  }, [infinite, initialPage, offset]);
-
-  /**
-   * Handle layout to measure actual container width
-   */
-  const handleLayout = useCallback((event: LayoutChangeEvent) => {
-    const { width } = event.nativeEvent.layout;
-    if (width > 0) {
-      setContainerWidth(width);
-    }
-  }, []);
-
-  /**
-   * Handle scroll begin drag - fires when user starts dragging
-   */
-  const handleScrollBeginDrag = useCallback(() => {
-    onPageScrollStateChanged?.("dragging");
-  }, [onPageScrollStateChanged]);
-
-  /**
-   * Handle scroll end drag - fires when user releases finger
-   */
-  const handleScrollEndDrag = useCallback(
-    (event: any) => {
-      if (isJumpingRef.current || containerWidth === 0) {
-        return;
-      }
-
-      const offsetX = event.nativeEvent.contentOffset.x;
-      const newDisplayPage = Math.round(offsetX / containerWidth);
-
-      const realIndex = getRealIndex(newDisplayPage, offset, data.length);
-
-      // Call the callback if provided
-      onScrollEndDrag?.(realIndex);
-
-      // Transition to settling state (momentum begins)
-      onPageScrollStateChanged?.("settling");
-    },
-    [data.length, offset, onScrollEndDrag, onPageScrollStateChanged, containerWidth],
-  );
-
-  /**
-   * Handle scroll end - detect which page we're on
-   */
-  const handleMomentumScrollEnd = useCallback(
-    (event: any) => {
-      if (isJumpingRef.current || containerWidth === 0) {
-        return;
-      }
-
-      const offsetX = event.nativeEvent.contentOffset.x;
-      const newDisplayPage = Math.round(offsetX / containerWidth);
-
-      if (newDisplayPage === currentPageRef.current) {
-        return;
-      }
-
-      const prevPage = currentPageRef.current;
-      currentPageRef.current = newDisplayPage;
-
-      const realIndex = getRealIndex(newDisplayPage, offset, data.length);
-      setCurrentPage(realIndex);
-
-      // Emit events
-      onPageChange?.(realIndex);
-
-      if (newDisplayPage > prevPage) {
-        onNext?.(realIndex);
-      } else if (newDisplayPage < prevPage) {
-        onPrev?.(realIndex);
-      }
-
-      // Transition to idle state (scroll complete)
-      onPageScrollStateChanged?.("idle");
-
-      // Handle infinite scroll jump - jump earlier to avoid hitting edge
-      if (infinite && data.length >= 3) {
-        // Use larger threshold for FlatList to jump before hitting edge
-        const threshold = Math.max(3, Math.min(5, Math.ceil(actualCloneCount / 5)));
-        const totalLength = offset + data.length + actualCloneCount;
-
-        // Near start
-        if (newDisplayPage < offset + threshold && newDisplayPage < offset + data.length / 2) {
-          const dataIndex =
-            actualCloneCount > data.length
-              ? newDisplayPage % data.length
-              : data.length - actualCloneCount + newDisplayPage;
-
-          const jumpTo = offset + dataIndex;
-          performJump(jumpTo);
-        }
-        // Near end
-        else if (newDisplayPage >= offset + data.length - threshold && newDisplayPage >= offset + data.length / 2) {
-          const offsetInCycle = (newDisplayPage - offset) % data.length;
-          const jumpTo = offset + offsetInCycle;
-          performJump(jumpTo);
-        }
-      }
-    },
-    [data.length, offset, actualCloneCount, infinite, onPageChange, onNext, onPrev, containerWidth],
-  );
-
-  /**
-   * Perform jump without animation
-   */
-  const performJump = useCallback((targetIndex: number) => {
-    isJumpingRef.current = true;
-
-    requestAnimationFrame(() => {
-      flatListRef.current?.scrollToIndex({
-        index: targetIndex,
-        animated: false,
-      });
-      currentPageRef.current = targetIndex;
-
-      requestAnimationFrame(() => {
-        isJumpingRef.current = false;
-      });
-    });
-  }, []);
-
-  /**
-   * Get item layout for proper scrollToIndex
-   */
-  const getItemLayout = useCallback(
-    (_: any, index: number) => ({
-      length: containerWidth,
-      offset: containerWidth * index,
-      index,
-    }),
-    [containerWidth],
-  );
-
-  /**
-   * Render each item
-   */
-  const renderFlatListItem = useCallback(
-    ({ item, index }: { item: T; index: number }) => {
-      const realIndex = getRealIndex(index, offset, data.length);
-      return <View style={[styles.page, { width: containerWidth }]}>{renderItem(item, realIndex)}</View>;
-    },
-    [renderItem, offset, data.length, containerWidth],
-  );
-
-  /**
-   * Expose ref methods
-   */
-  useImperativeHandle(
-    ref,
-    () => ({
-      goToPage: (index: number, animated = true) => {
-        const clampedIndex = Math.max(0, Math.min(index, data.length - 1));
-        const displayIndex = infinite ? getDisplayIndex(clampedIndex, offset) : clampedIndex;
-
-        flatListRef.current?.scrollToIndex({
-          index: displayIndex,
-          animated,
-        });
-      },
-
-      next: (animated = true) => {
-        const nextPage = currentPageRef.current + 1;
-        if (nextPage < displayData.length) {
-          flatListRef.current?.scrollToIndex({
-            index: nextPage,
-            animated,
-          });
-        }
-      },
-
-      prev: (animated = true) => {
-        const prevPage = currentPageRef.current - 1;
-        if (prevPage >= 0) {
-          flatListRef.current?.scrollToIndex({
-            index: prevPage,
-            animated,
-          });
-        }
-      },
-
-      getCurrentPage: () => currentPage,
-    }),
-    [currentPage, data.length, infinite, offset, displayData.length],
-  );
-
-  /**
-   * Initialize to initial page after container width is measured
-   */
-  useEffect(() => {
-    if (containerWidth > 0) {
-      const timer = setTimeout(() => {
-        flatListRef.current?.scrollToIndex({
-          index: adjustedInitialPage,
-          animated: false,
-        });
-      }, 100);
-
-      return () => clearTimeout(timer);
-    }
-  }, [adjustedInitialPage, containerWidth]);
-
-  if (data.length === 0) {
-    return null;
-  }
-
-  return (
-    <View style={[styles.container, style]} onLayout={handleLayout}>
-      {containerWidth > 0 && (
-        <FlatList
-          ref={flatListRef}
-          data={displayData}
-          renderItem={renderFlatListItem}
-          keyExtractor={(item, index) => {
-            const realIndex = getRealIndex(index, offset, data.length);
-            return keyExtractor?.(item, realIndex) ?? `swiper-fl-${index}`;
-          }}
-          horizontal
-          pagingEnabled
-          showsHorizontalScrollIndicator={false}
-          onScrollBeginDrag={onPageScrollStateChanged ? handleScrollBeginDrag : undefined}
-          onScrollEndDrag={onScrollEndDrag || onPageScrollStateChanged ? handleScrollEndDrag : undefined}
-          onMomentumScrollEnd={handleMomentumScrollEnd}
-          getItemLayout={getItemLayout}
-          initialScrollIndex={adjustedInitialPage}
-          // Optimized for fast scrolling with paging
-          initialNumToRender={10}
-          windowSize={21}
-          maxToRenderPerBatch={10}
-          updateCellsBatchingPeriod={30}
-          removeClippedSubviews={false}
-          style={styles.flatList}
-        />
-      )}
-    </View>
-  );
-}
-
-const styles = StyleSheet.create({
-  container: {
-    flex: 1,
-  },
-  flatList: {
-    flex: 1,
-  },
-  page: {
-    flex: 1,
-  },
-});
-
-export const SwiperFlatList = forwardRef(SwiperFlatListComponent) as <T>(
-  props: SwiperProps<T> & { ref?: React.Ref<SwiperRef> },
-) => React.ReactElement;