Fix non-loop overscroll after left edge (credit PR 839) (#871)

fix: correct non-loop overscroll (credits pr839)

Author: dohooo

.changeset/fix-nonloop-overscroll.md

@@ -0,0 +1,5 @@
+---
+"react-native-reanimated-carousel": patch
+---
+
+Fix non-loop overscroll direction so tiny positive offsets at the first page no longer wrap to the last page when calling next()/scrollTo(), and add integration coverage for the scenario. Thanks to @hennessyevan for the original report and PR 839 inspiration.

src/components/Carousel.test.tsx

@@ -806,4 +806,87 @@ describe("Test the real swipe behavior of Carousel to ensure it's working as exp
     TICK();
     pushExpect(1);
   });
+
+  it("should keep correct page after left overscroll at first page when calling next() or scrollTo()", async () => {
+    const handlerOffset = { current: 0 };
+    let nextSlide: ((opts?: { animated?: boolean }) => void) | undefined;
+    let scrollToIndex: ((opts?: { index: number; animated?: boolean }) => void) | undefined;
+
+    const Wrapper: FC<Partial<TCarouselProps<string>>> = React.forwardRef((customProps, ref) => {
+      const progressAnimVal = useSharedValue(0);
+      const mockHandlerOffset = useSharedValue(handlerOffset.current);
+      const defaultRenderItem = ({
+        item,
+        index,
+      }: {
+        item: string;
+        index: number;
+      }) => (
+        <Animated.View
+          testID={`carousel-item-${index}`}
+          style={{ width: slideWidth, height: slideHeight }}
+        >
+          {item}
+        </Animated.View>
+      );
+      const { renderItem = defaultRenderItem, ...defaultProps } = createDefaultProps(
+        progressAnimVal,
+        customProps
+      );
+
+      useDerivedValue(() => {
+        handlerOffset.current = mockHandlerOffset.value;
+      }, [mockHandlerOffset]);
+
+      return (
+        <Carousel
+          {...defaultProps}
+          defaultScrollOffsetValue={mockHandlerOffset}
+          renderItem={renderItem}
+          ref={ref}
+        />
+      );
+    });
+
+    const { getByTestId } = render(
+      <Wrapper
+        ref={(ref) => {
+          if (ref) {
+            nextSlide = ref.next;
+            scrollToIndex = ref.scrollTo;
+          }
+        }}
+        loop={false}
+        overscrollEnabled
+        style={{ width: slideWidth, height: slideHeight }}
+      />
+    );
+    await verifyInitialRender(getByTestId);
+
+    // Simulate left overscroll at first page
+    fireGestureHandler<PanGesture>(getByGestureTestId(gestureTestId), [
+      { state: State.BEGAN, translationX: 0, velocityX: 0 },
+      { state: State.ACTIVE, translationX: slideWidth / 4, velocityX: slideWidth },
+      { state: State.ACTIVE, translationX: 0.00003996, velocityX: slideWidth },
+      { state: State.END, translationX: 0.00003996, velocityX: slideWidth },
+    ]);
+
+    nextSlide?.({ animated: false });
+    await waitFor(() => {
+      expect(handlerOffset.current).toBe(-slideWidth);
+    });
+
+    // Overscroll again, then call scrollTo()
+    fireGestureHandler<PanGesture>(getByGestureTestId(gestureTestId), [
+      { state: State.BEGAN, translationX: 0, velocityX: -slideWidth },
+      { state: State.ACTIVE, translationX: slideWidth, velocityX: slideWidth },
+      { state: State.ACTIVE, translationX: slideWidth + 0.00003996, velocityX: slideWidth },
+      { state: State.END, translationX: slideWidth + 0.00003996, velocityX: slideWidth },
+    ]);
+
+    scrollToIndex?.({ index: 1, animated: false });
+    await waitFor(() => {
+      expect(handlerOffset.current).toBe(-slideWidth);
+    });
+  });
 });

src/hooks/useCarouselController.tsx

@@ -83,10 +83,13 @@ export function useCarouselController(options: IOpts): ICarouselController {
     if (size <= 0) return 0;
     if (loop) return -Math.round(handlerOffset.value / size);
 
-    const fixed = (handlerOffset.value / size) % dataInfo.length;
-    return Math.round(
-      handlerOffset.value <= 0 ? Math.abs(fixed) : Math.abs(fixed > 0 ? dataInfo.length - fixed : 0)
-    );
+    // In non-loop mode, treat the offset as negative when moving forward.
+    // Clamp within valid range to avoid wrapping when a tiny positive offset
+    // appears after overscroll at index 0.
+    const rawPage = -handlerOffset.value / size;
+    const rounded = Math.round(rawPage);
+    const clamped = Math.max(0, Math.min(dataInfo.length - 1, rounded));
+    return clamped;
   }, [handlerOffset, dataInfo, size, loop]);
 
   function setSharedIndex(newSharedIndex: number) {
@@ -350,7 +353,15 @@ export function useCarouselController(options: IOpts): ICarouselController {
 
       onScrollStart?.();
       // direction -> 1 | -1
-      const direction = handlerOffsetDirection(handlerOffset, fixedDirection);
+      let direction: -1 | 1;
+      if (fixedDirection === "positive") direction = 1;
+      else if (fixedDirection === "negative") direction = -1;
+      else if (!loop) {
+        const currentPage = currentFixedPage();
+        direction = i >= currentPage ? -1 : 1;
+      } else {
+        direction = handlerOffsetDirection(handlerOffset);
+      }
 
       // target offset
       const offset = i * size * direction;