@xhsreds/reds-rn-next 0.9.1-beta202510291556 → 0.9.1-feat-swiper202511031535

package/src/components/Swiper/types.ts

@@ -0,0 +1,208 @@
+import { ReactNode } from "react";
+import { StyleProp, ViewStyle } from "react-native";
+
+/**
+ * Props for the Swiper component
+ */
+export interface SwiperProps<T> {
+  // Data
+  /** 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;
+
+  // Behavior
+  /** 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;
+
+  // Lazy mounting
+  /**
+   * 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;
+
+  // Events
+  /** 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;
+
+  // Styling
+  /** Style for the pager container */
+  style?: StyleProp<ViewStyle>;
+
+  /** Margin between pages (Android only) */
+  pageMargin?: number;
+
+  // PagerView passthrough props
+  /** 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;
+
+  // Advanced
+  /** 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/src/components/Swiper/utils.ts

@@ -0,0 +1,133 @@
+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 function prepareInfiniteData<T>(data: T[], infinite: boolean, cloneCount: number = 2): InfiniteDataResult<T> {
+  // Don't enable infinite for small datasets or when disabled
+  if (!infinite || data.length < 3) {
+    return {
+      displayData: data,
+      offset: 0,
+      cloneCount: 0,
+    };
+  }
+
+  // If cloneCount exceeds data length, we'll clone entire array multiple times
+  // This provides maximum buffering for fast scrolling
+  const actualCloneCount = cloneCount;
+
+  // Clone items for seamless looping
+  // If cloneCount > data.length, this will repeat the entire array
+  const firstClones = data.slice(-actualCloneCount); // Last N items (or full array if N > length)
+  const lastClones = data.slice(0, actualCloneCount); // First N items (or full array if N > length)
+
+  // Handle case where cloneCount > data.length by repeating the array
+  let leftClones: T[] = [];
+  let rightClones: T[] = [];
+
+  if (actualCloneCount > data.length) {
+    // Repeat entire array multiple times
+    const repeatCount = Math.ceil(actualCloneCount / data.length);
+    for (let i = 0; i < repeatCount; i++) {
+      leftClones.push(...data);
+      rightClones.push(...data);
+    }
+    // Trim to exact clone count
+    leftClones = leftClones.slice(-actualCloneCount);
+    rightClones = rightClones.slice(0, actualCloneCount);
+  } else {
+    leftClones = firstClones;
+    rightClones = lastClones;
+  }
+
+  // Structure: [leftClones, ...original, rightClones]
+  // This allows seamless transition in both directions
+  return {
+    displayData: [...leftClones, ...data, ...rightClones],
+    offset: actualCloneCount, // Real data starts at this index
+    cloneCount: actualCloneCount,
+  };
+}
+
+/**
+ * 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 function shouldJumpForInfinite(
+  newPage: number,
+  dataLength: number,
+  offset: number,
+  cloneCount: number,
+): JumpResult {
+  // Only jump when within threshold of absolute edges
+  // This prevents jumping too eagerly when cloneCount is large
+  const threshold = Math.min(2, Math.max(1, Math.floor(cloneCount / 10)));
+
+  // Near absolute start (left edge)
+  if (newPage < threshold) {
+    // Calculate position in the data cycle
+    const dataIndex = cloneCount > dataLength ? newPage % dataLength : dataLength - cloneCount + newPage;
+
+    return {
+      shouldJump: true,
+      jumpTo: offset + dataIndex,
+    };
+  }
+
+  // Near absolute end (right edge)
+  const totalLength = offset + dataLength + cloneCount;
+  if (newPage >= totalLength - threshold) {
+    // Calculate position in the data cycle
+    const offsetInCycle = (newPage - offset - dataLength) % dataLength;
+
+    return {
+      shouldJump: true,
+      jumpTo: offset + offsetInCycle,
+    };
+  }
+
+  return { shouldJump: false };
+}
+
+/**
+ * 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 function getRealIndex(displayIndex: number, offset: number, dataLength: number): number {
+  if (dataLength === 0) return 0;
+
+  // Adjust for offset and wrap around
+  const adjusted = displayIndex - offset;
+  return ((adjusted % dataLength) + dataLength) % dataLength;
+}
+
+/**
+ * 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 function getDisplayIndex(realIndex: number, offset: number): number {
+  return realIndex + offset;
+}

package/src/index.ts

@@ -73,5 +73,6 @@ export * from "./components/SlimAlert";
 export * from "./components/SlimNavigationBar";
 export * from "./components/Search";
 export * from "./components/ActionablePopover";
+export * from "./components/Swiper";
 import "react-native-url-polyfill/auto";
 bindPushDataEvent(pushGlobalData);