@r0b0t3d/react-native-carousel 3.4.5 → 3.4.7

package/lib/module/components/Carousel.js

@@ -1,19 +1,46 @@
-function _extends() { _extends = Object.assign || function (target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i]; for (var key in source) { if (Object.prototype.hasOwnProperty.call(source, key)) { target[key] = source[key]; } } } return target; }; return _extends.apply(this, arguments); }
+"use strict";
 
 /* eslint-disable @typescript-eslint/ban-ts-comment */
-import React, { useState, useRef, useEffect, useCallback, useMemo } from 'react';
-import { View, Dimensions, StyleSheet, Platform } from 'react-native';
+import React, { useState, useEffect, useCallback, useMemo } from 'react';
+import { Dimensions, StyleSheet, Platform, AppState } from 'react-native';
 import { useInterval } from '@r0b0t3d/react-native-hooks';
-import Animated, { useSharedValue, useAnimatedScrollHandler, runOnJS, useAnimatedRef } from 'react-native-reanimated';
+import Animated, { useSharedValue, useAnimatedScrollHandler, useAnimatedRef, scrollTo } from 'react-native-reanimated';
+import { scheduleOnRN, scheduleOnUI } from 'react-native-worklets';
 import PageItem from './PageItem';
-import { findNearestPage, generateOffsets } from '../utils';
+import { findNearestPage, generateOffsets, getLogicalPage, getLoopBoundaryTarget } from '../utils';
 import { useCarouselContext } from './useCarouselContext';
 import { useInternalCarouselContext } from './useInternalCarouselContext';
 
+// ---------------------------------------------------------------------------
+// Carousel state machine
+// ---------------------------------------------------------------------------
+// Transitions:
+//
+//   IDLE ── onBeginDrag ──► DRAGGING
+//   DRAGGING ── onMomentumEnd ──► IDLE (or LOOP_JUMP at boundary)
+//   LOOP_JUMP ── onScroll (arrival) ──► IDLE
+//   LOOP_JUMP ── onBeginDrag (user overrides) ──► DRAGGING
+//
+// Page change (onPageChange / animatedPage) only fires at IDLE transitions.
+// Autoplay only advances when state === IDLE.
+// ---------------------------------------------------------------------------
+import { jsx as _jsx } from "react/jsx-runtime";
+var CarouselState = /*#__PURE__*/function (CarouselState) {
+  CarouselState[CarouselState["IDLE"] = 0] = "IDLE";
+  CarouselState[CarouselState["DRAGGING"] = 1] = "DRAGGING";
+  CarouselState[CarouselState["LOOP_JUMP"] = 2] = "LOOP_JUMP";
+  return CarouselState;
+}(CarouselState || {}); // ---------------------------------------------------------------------------
+// Terminology
+// ---------------------------------------------------------------------------
+//   render index  – position in the padded pageItems array (includes loop
+//                   clones at head/tail). Used for scroll offsets.
+//   logical index – position in the original data array (0 .. data.length-1).
+//                   All consumer-facing callbacks receive logical indices.
+// ---------------------------------------------------------------------------
 const getScreenWidth = () => {
   return Dimensions.get('screen').width;
 };
-
 function Carousel({
   style,
   data,
@@ -34,26 +61,36 @@ function Carousel({
   onPageChange,
   scrollViewProps = {},
   keyExtractor,
-  onItemPress
+  onItemPress,
+  disableItemPress = false,
+  scrollViewRef: externalScrollViewRef
 }) {
-  const currentPage = useSharedValue(0);
+  // ---- shared values (UI-thread state) ------------------------------------
+
+  const currentRenderPage = useSharedValue(0);
+  const currentLogicalPage = useSharedValue(0);
   const animatedScroll = useSharedValue(0);
+  const carouselState = useSharedValue(CarouselState.IDLE);
+  // Destination render page for a loop jump. Used to detect arrival via
+  // onScroll and release the jump lock.
+  const jumpDestination = useSharedValue(-1);
+  // Suppresses parallax/opacity animations during instant scrolls on
+  // Android where the scroll isn't truly synchronous.
   const freeze = useSharedValue(false);
-  const [isDragging, setDragging] = useState(false);
-  const expectedPosition = useSharedValue(-1);
-  const pageMapper = useRef({});
+  // When false, autoplay is suppressed (app backgrounded).
+  const appActive = useSharedValue(true);
+  const internalAnimatedRef = useAnimatedRef();
   const {
     currentPage: animatedPage,
     totalPage
   } = useCarouselContext();
-  useEffect(() => {
-    animatedScroll.value = currentPage.value * sliderWidth;
-  }, []);
+
+  // ---- derived values -----------------------------------------------------
+
   const horizontalPadding = useMemo(() => {
     const padding = (sliderWidth - itemWidth) / 2;
     return firstItemAlignment === 'center' || loop ? padding : spaceHeadTail;
   }, [sliderWidth, itemWidth, firstItemAlignment, loop, spaceHeadTail]);
-  const scrollViewRef = useAnimatedRef();
   const offsets = useMemo(() => {
     return generateOffsets({
       sliderWidth,
@@ -61,89 +98,122 @@ function Carousel({
       itemCount: data.length + (loop ? additionalPagesPerSide * 2 : 0),
       horizontalPadding
     });
-  }, [sliderWidth, itemWidth, data, horizontalPadding]);
+  }, [sliderWidth, itemWidth, data.length, loop, additionalPagesPerSide, horizontalPadding]);
   const pageItems = useMemo(() => {
-    if (!data) {
+    if (!data || data.length === 0) {
       return [];
     }
-
-    totalPage.value = data.length;
-
     if (loop) {
       const headItems = data.slice(data.length - additionalPagesPerSide, data.length);
       const tailItems = data.slice(0, additionalPagesPerSide);
-      const newItems = [...headItems, ...data, ...tailItems];
+      return [...headItems, ...data, ...tailItems];
+    }
+    return data;
+  }, [data, loop, additionalPagesPerSide]);
 
-      for (let i = 0; i < newItems.length; i++) {
-        pageMapper.current[i] = (data.length - additionalPagesPerSide + i) % data.length;
-      }
+  // ---- side effects -------------------------------------------------------
 
-      return newItems;
-    } else {
-      for (let i = 0; i < data.length; i++) {
-        pageMapper.current[i] = i;
-      }
+  useEffect(() => {
+    totalPage.value = data.length;
+  }, [data.length, totalPage]);
 
-      return data;
+  // When the carousel layout or data changes (orientation, split-screen,
+  // toggling loop, data shrinking), reposition so the current logical
+  // page stays visible at its new render index and scroll offset.
+  useEffect(() => {
+    if (data.length === 0 || offsets.length === 0) return;
+
+    // Clamp logical page in case data shrank below current position.
+    const clampedLogical = Math.min(currentLogicalPage.value, data.length - 1);
+    const renderIdx = loop ? clampedLogical + additionalPagesPerSide : clampedLogical;
+
+    // Defensive: ensure render index is within bounds.
+    const safeRenderIdx = Math.max(0, Math.min(renderIdx, offsets.length - 1));
+    const safeLogicalIdx = getLogicalPage(safeRenderIdx, data.length, additionalPagesPerSide, loop);
+    currentRenderPage.value = safeRenderIdx;
+    currentLogicalPage.value = safeLogicalIdx;
+    animatedPage.value = safeLogicalIdx;
+    scheduleOnUI(idx => {
+      'worklet';
+
+      scrollTo(internalAnimatedRef, offsets[idx], 0, false);
+    }, safeRenderIdx);
+    animatedScroll.value = offsets[safeRenderIdx] ?? 0;
+    // Fire onPageChange if logical page actually changed (e.g. data shrank).
+    if (safeLogicalIdx !== currentLogicalPage.value) {
+      scheduleOnRN(handlePageChange, safeLogicalIdx);
     }
-  }, [data, loop]);
-  const getActualPage = useCallback(page => {
-    return pageMapper.current[page];
-  }, []);
-  const getRef = useCallback(() => {
-    if (!scrollViewRef.current) return;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [data.length, sliderWidth, itemWidth, loop, additionalPagesPerSide]);
+
+  // ---- app-state listener (pause autoplay when backgrounded) --------------
+
+  useEffect(() => {
+    const sub = AppState.addEventListener('change', state => {
+      appActive.value = state === 'active';
+    });
+    return () => sub.remove();
+  }, [appActive]);
+
+  // ---- page-change callback (JS thread) -----------------------------------
 
-    if (scrollViewRef.current.scrollTo) {
-      return scrollViewRef.current;
+  const handlePageChange = useCallback(logicalPage => {
+    animatedPage.value = logicalPage;
+    if (onPageChange) {
+      onPageChange(logicalPage);
     }
+  }, [onPageChange, animatedPage]);
 
-    return scrollViewRef.current.getNode();
-  }, []);
+  // ---- scroll helpers -----------------------------------------------------
+
+  // Safe accessor: returns offset for a render index, clamping to valid
+  // range and falling back to 0 if offsets is empty.
+  const renderOffset = useCallback(renderIdx => {
+    if (offsets.length === 0) return 0;
+    const clamped = Math.max(0, Math.min(renderIdx, offsets.length - 1));
+    return offsets[clamped];
+  }, [offsets]);
   const handleScrollTo = useCallback((page, animated = true) => {
-    if (getRef()) {
-      getRef().scrollTo({
-        x: offsets[page],
-        y: 0,
-        animated
-      });
-    }
-  }, [getRef, offsets]);
-  const jumpTo = useCallback((page, delay = 200) => {
-    expectedPosition.value = page;
+    scheduleOnUI((pageIndex, isAnimated) => {
+      'worklet';
 
-    if (Platform.OS === 'android') {
-      freeze.value = true;
-    }
+      scrollTo(internalAnimatedRef, offsets[pageIndex], 0, isAnimated);
+    }, page, animated);
+  }, [offsets, internalAnimatedRef]);
+
+  // ---- navigation ---------------------------------------------------------
 
-    setTimeout(() => {
-      animatedScroll.value = offsets[page];
-      handleScrollTo(page, false);
-    }, delay);
-  }, [handleScrollTo, animatedScroll, freeze]);
   const goNext = useCallback(() => {
-    const next = currentPage.value + 1;
-    handleScrollTo(next);
-  }, [handleScrollTo]);
+    if (carouselState.value !== CarouselState.IDLE || data.length === 0) return;
+    const next = currentRenderPage.value + 1;
+    if (next < offsets.length) {
+      currentRenderPage.value = next;
+      handleScrollTo(next);
+    }
+  }, [handleScrollTo, offsets.length, data.length]);
   const goPrev = useCallback(() => {
-    const prev = currentPage.value - 1;
-    handleScrollTo(prev);
+    if (carouselState.value !== CarouselState.IDLE || data.length === 0) return;
+    const prev = currentRenderPage.value - 1;
+    if (prev >= 0) {
+      currentRenderPage.value = prev;
+      handleScrollTo(prev);
+    }
   }, [handleScrollTo]);
   const snapToItem = useCallback((index, animated = true) => {
+    if (data.length === 0) return;
     if (index < 0 || index >= data.length) {
       console.error(`Index not valid ${index}`);
       return;
     }
+    const renderIndex = loop ? index + additionalPagesPerSide : index;
+    const clamped = Math.max(0, Math.min(renderIndex, offsets.length - 1));
+    currentRenderPage.value = clamped;
+    currentLogicalPage.value = index;
+    handleScrollTo(clamped, animated);
+  }, [loop, additionalPagesPerSide, offsets.length, handleScrollTo, data.length]);
 
-    let pageIndex = index;
-
-    if (loop) {
-      const indices = Object.keys(pageMapper.current).filter(idx => pageMapper.current[Number(idx)] === index).map(idx => Number(idx));
-      const toIndex = findNearestPage(currentPage.value, indices, 10);
-      pageIndex = indices[toIndex];
-    }
+  // ---- context wiring -----------------------------------------------------
 
-    handleScrollTo(pageIndex, animated);
-  }, [handleScrollTo]);
   const {
     setCarouselHandlers
   } = useInternalCarouselContext();
@@ -156,128 +226,163 @@ function Carousel({
       });
     }
   }, [goNext, goPrev, snapToItem, setCarouselHandlers]);
-  const handlePageChange = useCallback(page => {
-    const actualPage = getActualPage(page);
-    animatedPage.value = actualPage;
 
-    if (onPageChange) {
-      onPageChange(actualPage);
-    }
-
-    if (!loop) return;
-
-    if (page === pageItems.length - 1) {
-      jumpTo(additionalPagesPerSide * 2 - 1);
-    } else if (page === 0) {
-      jumpTo(pageItems.length - additionalPagesPerSide * 2);
-    }
-  }, [onPageChange, loop, getActualPage, jumpTo, pageItems]);
-  const refreshPage = useCallback(offset => {
-    'worklet';
-
-    const pageNum = findNearestPage(offset, offsets, 20);
+  // ---- autoplay -----------------------------------------------------------
 
-    if (pageNum === -1) {
-      return;
+  // isDragging acts as a debounce — autoplay resumes 200ms after the
+  // user lifts their finger, preventing an immediate auto-advance.
+  const [autoplayPaused, setAutoplayPaused] = useState(false);
+  useInterval(() => {
+    // Only advance when carousel is idle (not dragging, not in a
+    // loop jump) and the app is in the foreground.
+    if (carouselState.value === CarouselState.IDLE && appActive.value) {
+      goNext();
     }
+  }, !autoPlay || !loop || autoplayPaused ? -1 : duration);
 
-    if (pageNum !== currentPage.value) {
-      if (expectedPosition.value === pageNum) {
-        freeze.value = false;
-      }
+  // ---- initial page setup -------------------------------------------------
 
-      currentPage.value = pageNum;
-      runOnJS(handlePageChange)(pageNum);
-    }
-  }, [isDragging, offsets, handlePageChange]);
-  useInterval(() => {
-    goNext();
-  }, !autoPlay || !loop || isDragging ? -1 : duration);
   useEffect(() => {
+    if (data.length === 0) return;
     if (initialPage < 0 || initialPage >= data.length) {
       console.error(`Invalid initialPage ${initialPage}`);
       return;
     }
+    const renderIndex = loop ? initialPage + additionalPagesPerSide : initialPage;
+    const safeIdx = Math.max(0, Math.min(renderIndex, offsets.length - 1));
+    currentRenderPage.value = safeIdx;
+    currentLogicalPage.value = initialPage;
+    animatedPage.value = initialPage;
+    scheduleOnUI(idx => {
+      'worklet';
+
+      scrollTo(internalAnimatedRef, offsets[idx], 0, false);
+    }, safeIdx);
+    animatedScroll.value = offsets[safeIdx] ?? 0;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
 
-    let pageIndex = initialPage;
+  // ---- scroll handler (UI thread worklet) ---------------------------------
 
-    if (loop) {
-      pageIndex = initialPage + additionalPagesPerSide;
-    }
+  const scrollHandler = useAnimatedScrollHandler({
+    onScroll: event => {
+      animatedScroll.value = event.contentOffset.x;
 
-    if (currentPage.value !== pageIndex) {
-      setTimeout(() => {
-        handleScrollTo(pageIndex, false);
+      // During a loop jump, detect when the scroll arrives at the
+      // destination and transition back to IDLE.
+      if (carouselState.value === CarouselState.LOOP_JUMP && jumpDestination.value !== -1) {
+        const nearest = findNearestPage(event.contentOffset.x, offsets);
+        if (nearest === jumpDestination.value) {
+          freeze.value = false;
+          carouselState.value = CarouselState.IDLE;
+          jumpDestination.value = -1;
+        }
+      }
+    },
+    onBeginDrag: _e => {
+      // User gesture always wins. Cancel any in-flight loop jump
+      // so the carousel doesn't fight the user's drag.
+      if (carouselState.value === CarouselState.LOOP_JUMP) {
+        jumpDestination.value = -1;
         freeze.value = false;
-      });
-    }
-  }, []);
-  const beginDrag = useCallback(() => {
-    if (autoPlay) {
-      setDragging(true);
-    }
-  }, [autoPlay]);
-  const endDrag = useCallback(() => {
-    if (autoPlay) {
-      setTimeout(() => setDragging(false), 200);
+      }
+      carouselState.value = CarouselState.DRAGGING;
+      scheduleOnRN(setAutoplayPaused, true);
+    },
+    onEndDrag: _e => {
+      // Debounce autoplay resume — let momentum settle first.
+      scheduleOnRN(setAutoplayPaused, false);
+    },
+    onMomentumEnd: event => {
+      // Only process page changes when dragging ended naturally.
+      // Loop jumps are handled in onScroll.
+      if (carouselState.value !== CarouselState.DRAGGING) {
+        return;
+      }
+      const offset = event.contentOffset.x;
+      if (isNaN(offset) || offsets.length === 0) {
+        carouselState.value = CarouselState.IDLE;
+        return;
+      }
+      const renderPage = findNearestPage(offset, offsets);
+
+      // Loop boundary — user scrolled into the cloned head/tail pages.
+      if (loop) {
+        const boundaryTarget = getLoopBoundaryTarget(renderPage, data.length, additionalPagesPerSide);
+        if (boundaryTarget !== -1) {
+          // Jump instantly to the matching real page.
+          // On Android, freeze animations during the jump to prevent
+          // a visual flash from the clones.
+          carouselState.value = CarouselState.LOOP_JUMP;
+          jumpDestination.value = boundaryTarget;
+          freeze.value = Platform.OS === 'android';
+          animatedScroll.value = offsets[boundaryTarget];
+          scrollTo(internalAnimatedRef, offsets[boundaryTarget], 0, false);
+          currentRenderPage.value = boundaryTarget;
+          currentLogicalPage.value = getLogicalPage(boundaryTarget, data.length, additionalPagesPerSide, loop);
+          scheduleOnRN(handlePageChange, currentLogicalPage.value);
+          return;
+        }
+      }
+
+      // Normal page change — no loop boundary involved.
+      carouselState.value = CarouselState.IDLE;
+      currentRenderPage.value = renderPage;
+      currentLogicalPage.value = getLogicalPage(renderPage, data.length, additionalPagesPerSide, loop);
+      scheduleOnRN(handlePageChange, currentLogicalPage.value);
     }
-  }, [autoPlay]);
+  }, [offsets, loop, data.length, additionalPagesPerSide, handlePageChange, internalAnimatedRef]);
+
+  // ---- render helpers -----------------------------------------------------
+
   const getItemKey = useCallback((item, index) => {
     if (keyExtractor) {
       return `${keyExtractor(item, index)}-${index}`;
     }
-
     if (item.id) {
       return `${item.id}-${index}`;
     }
-
-    console.error('You need implement keyExtractor');
-    return '';
+    return `carousel-item-${index}`;
   }, [keyExtractor]);
-  const scrollHandler = useAnimatedScrollHandler({
-    onScroll: event => {
-      animatedScroll.value = event.contentOffset.x;
-      refreshPage(animatedScroll.value);
-    },
-    onBeginDrag: _e => {
-      runOnJS(beginDrag)();
-    },
-    onEndDrag: _e => {
-      runOnJS(endDrag)();
-    }
-  }, [beginDrag, endDrag, refreshPage]);
-  const containerStyle = useCallback(index => {
-    if (firstItemAlignment === 'start') {
+  const containerStyles = useMemo(() => {
+    if (data.length === 0) return [];
+    return pageItems.map((_, i) => {
+      if (firstItemAlignment !== 'start') {
+        return {
+          paddingLeft: spaceBetween / 2,
+          paddingRight: spaceBetween / 2
+        };
+      }
+      const logicalIndex = loop ? getLogicalPage(i, data.length, additionalPagesPerSide, loop) : i;
       return {
-        paddingLeft: index === 0 ? 0 : spaceBetween / 2,
-        paddingRight: index === data.length - 1 ? 0 : spaceBetween / 2
+        paddingLeft: logicalIndex === 0 ? 0 : spaceBetween / 2,
+        paddingRight: logicalIndex === data.length - 1 ? 0 : spaceBetween / 2
       };
-    }
-
-    return {
-      paddingLeft: spaceBetween / 2,
-      paddingRight: spaceBetween / 2
-    };
-  }, [spaceBetween, firstItemAlignment]);
-  const handleItemPress = useCallback((item, index) => () => {
-    handleScrollTo(index);
-
-    if (onItemPress) {
-      onItemPress(item, index);
-    }
-  }, [onItemPress, handlePageChange]);
-  const contentContainerStyle = useMemo(() => {
-    return {
-      paddingHorizontal: horizontalPadding
-    };
-  }, [horizontalPadding]);
-
-  function renderPage(item, i) {
-    return /*#__PURE__*/React.createElement(PageItem, {
-      key: getItemKey(item, i),
-      containerStyle: containerStyle(i),
+    });
+  }, [pageItems, firstItemAlignment, spaceBetween, data.length, loop, additionalPagesPerSide]);
+  const itemPressHandlers = useMemo(() => {
+    if (disableItemPress) return [];
+    return pageItems.map((item, i) => {
+      const logicalIndex = loop ? getLogicalPage(i, data.length, additionalPagesPerSide, loop) : i;
+      return () => {
+        handleScrollTo(i);
+        if (onItemPress) {
+          onItemPress(item, logicalIndex);
+        }
+      };
+    });
+  }, [pageItems, disableItemPress, loop, data.length, additionalPagesPerSide, handleScrollTo, onItemPress]);
+  const contentContainerStyle = useMemo(() => ({
+    paddingHorizontal: horizontalPadding
+  }), [horizontalPadding]);
+  const renderPage = useCallback((item, i) => {
+    // Compute the logical index so consumer callbacks (renderItem,
+    // onItemPress via `index` prop) receive logical, not render.
+    const logicalIndex = loop ? getLogicalPage(i, data.length, additionalPagesPerSide, loop) : i;
+    return /*#__PURE__*/_jsx(PageItem, {
+      containerStyle: containerStyles[i],
       item: item,
-      index: i,
+      index: logicalIndex,
       offset: offsets[i],
       itemWidth: itemWidth,
       animatedValue: animatedScroll,
@@ -286,15 +391,21 @@ function Carousel({
       freeze: freeze,
       inactiveOpacity: inactiveOpacity,
       inactiveScale: inactiveScale,
-      onPress: handleItemPress(item, i)
-    });
-  }
-
-  return /*#__PURE__*/React.createElement(View, {
-    style: style
-  }, /*#__PURE__*/React.createElement(Animated.ScrollView, _extends({}, scrollViewProps, {
-    ref: scrollViewRef,
-    style: styles.container,
+      onPress: itemPressHandlers[i]
+    }, getItemKey(item, i));
+  }, [loop, data.length, additionalPagesPerSide, getItemKey, containerStyles, offsets, itemWidth, animatedScroll, animation, renderItem, freeze, inactiveOpacity, inactiveScale, itemPressHandlers]);
+
+  // ---- render -------------------------------------------------------------
+
+  return /*#__PURE__*/_jsx(Animated.ScrollView, {
+    ...scrollViewProps,
+    ref: nativeRef => {
+      internalAnimatedRef(nativeRef);
+      if (externalScrollViewRef) {
+        externalScrollViewRef.current = nativeRef;
+      }
+    },
+    style: [styles.container, style],
     horizontal: true,
     disableScrollViewPanResponder: true,
     disableIntervalMomentum: true,
@@ -306,10 +417,10 @@ function Carousel({
     scrollEventThrottle: 4,
     onScroll: scrollHandler,
     bounces: false,
-    contentContainerStyle: contentContainerStyle
-  }), pageItems.map(renderPage)));
+    contentContainerStyle: contentContainerStyle,
+    children: pageItems.map(renderPage)
+  });
 }
-
 export default Carousel;
 const styles = StyleSheet.create({
   container: {