fix: non-loop scrollTo offset regression (#891)

* fix: correct non-loop scrollTo offset regression

* chore: add changeset for non-loop scrollTo fix

* test: cover animated non-loop backward scrollTo

* test: cover loop branches for codecov

---------

Co-authored-by: Caspian Zhao <caspian.zhao@outlook.com>

Author: notsuhas

.changeset/fix-nonloop-scrollto-offset-regression.md

@@ -0,0 +1,6 @@
+---
+"react-native-reanimated-carousel": patch
+---
+
+- Fix non-loop `scrollTo()` so backward jumps keep the correct negative offset instead of briefly rendering a blank frame.
+- Add regression tests for non-loop backward `scrollTo()` and returning to index `0`.

src/hooks/useCarouselController.test.tsx

@@ -228,6 +228,76 @@ describe("useCarouselController", () => {
     expect(mockHandlerOffset.value).toBe(-900); // size * 3
   });
 
+  it("should keep negative offsets when scrollTo() moves backward in non-loop mode", () => {
+    const { result } = renderHook(
+      () =>
+        useCarouselController({
+          ...defaultProps,
+          loop: false,
+        }),
+      { wrapper }
+    );
+
+    act(() => {
+      result.current.scrollTo({ index: 3, animated: false });
+    });
+    expect(mockHandlerOffset.value).toBe(-900);
+
+    act(() => {
+      result.current.scrollTo({ index: 2, animated: false });
+    });
+    expect(mockHandlerOffset.value).toBe(-600);
+
+    act(() => {
+      result.current.scrollTo({ index: 1, animated: false });
+    });
+    expect(mockHandlerOffset.value).toBe(-300);
+  });
+
+  it("should keep negative offsets when animated backward scrollTo() runs in non-loop mode", () => {
+    const onFinished = jest.fn();
+    const { result } = renderHook(
+      () =>
+        useCarouselController({
+          ...defaultProps,
+          loop: false,
+        }),
+      { wrapper }
+    );
+
+    act(() => {
+      result.current.scrollTo({ index: 3, animated: true });
+    });
+    expect(mockHandlerOffset.value).toBe(-900);
+
+    act(() => {
+      result.current.scrollTo({ index: 2, animated: true, onFinished });
+    });
+    expect(mockHandlerOffset.value).toBe(-600);
+    expect(onFinished).toHaveBeenCalled();
+  });
+
+  it("should map scrollTo({ index: 0 }) to zero offset from end in non-loop mode", () => {
+    const { result } = renderHook(
+      () =>
+        useCarouselController({
+          ...defaultProps,
+          loop: false,
+        }),
+      { wrapper }
+    );
+
+    act(() => {
+      result.current.scrollTo({ index: 4, animated: false });
+    });
+    expect(mockHandlerOffset.value).toBe(-1200);
+
+    act(() => {
+      result.current.scrollTo({ index: 0, animated: false });
+    });
+    expect(Math.abs(mockHandlerOffset.value)).toBe(0);
+  });
+
   it("should handle animation callbacks", () => {
     const onFinished = jest.fn();
     const { result } = renderHook(() => useCarouselController(defaultProps), { wrapper });
@@ -1004,13 +1074,31 @@ describe("useCarouselController edge cases and uncovered lines", () => {
     expect(typeof currentIndex).toBe("number");
   });
 
-  it("should handle fixed direction in scrollTo", () => {
+  it("should handle positive fixed direction in scrollTo", () => {
+    const { result } = renderHook(
+      () =>
+        useCarouselController({
+          ...defaultProps,
+          loop: true,
+          fixedDirection: "positive",
+        }),
+      { wrapper }
+    );
+
+    act(() => {
+      result.current.scrollTo({ index: 3, animated: false });
+    });
+
+    expect(mockHandlerOffset.value).toBe(900); // size * 3
+  });
+
+  it("should handle negative fixed direction in scrollTo", () => {
     const { result } = renderHook(
       () =>
         useCarouselController({
           ...defaultProps,
           loop: true,
-          fixedDirection: 1,
+          fixedDirection: "negative",
         }),
       { wrapper }
     );
@@ -1022,7 +1110,7 @@ describe("useCarouselController edge cases and uncovered lines", () => {
     expect(mockHandlerOffset.value).toBe(-900); // size * 3
   });
 
-  it("should handle complex loop calculations in scrollTo", () => {
+  it("should handle scrollTo when loop position is close to next cycle", () => {
     const { result } = renderHook(
       () =>
         useCarouselController({
@@ -1032,14 +1120,13 @@ describe("useCarouselController edge cases and uncovered lines", () => {
       { wrapper }
     );
 
-    // Set to a high offset to test loop boundary calculations
-    mockHandlerOffset.value = -1800; // 6 * size, beyond data length
+    mockHandlerOffset.value = -900; // 3 * size, more than half-way through current cycle
 
     act(() => {
       result.current.scrollTo({ index: 1, animated: false });
     });
 
-    expect(typeof mockHandlerOffset.value).toBe("number");
+    expect(mockHandlerOffset.value).toBe(-1800);
   });
 
   it("should get shared index correctly", () => {

src/hooks/useCarouselController.tsx

@@ -352,34 +352,32 @@ export function useCarouselController(options: IOpts): ICarouselController {
       if (!canSliding()) return;
 
       onScrollStart?.();
-      // direction -> 1 | -1
-      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;
-      // page width size * page count
-      const totalSize = dataInfo.length * size;
-
-      let isCloseToNextLoop = false;
+      let finalOffset: number;
 
-      if (loop) {
-        isCloseToNextLoop = Math.abs(handlerOffset.value % totalSize) / totalSize >= 0.5;
+      if (!loop) {
+        // Non-loop mode always uses direct page-to-offset mapping.
+        // This avoids sign flips when moving to lower indices.
+        finalOffset = -i * size;
+      } else {
+        // direction -> 1 | -1
+        let direction: -1 | 1;
+        if (fixedDirection === "positive") direction = 1;
+        else if (fixedDirection === "negative") direction = -1;
+        else direction = handlerOffsetDirection(handlerOffset);
+
+        // target offset
+        const offset = i * size * direction;
+        // page width size * page count
+        const totalSize = dataInfo.length * size;
+        const isCloseToNextLoop = Math.abs(handlerOffset.value % totalSize) / totalSize >= 0.5;
+
+        finalOffset =
+          (Math.floor(Math.abs(handlerOffset.value / totalSize)) + (isCloseToNextLoop ? 1 : 0)) *
+            totalSize *
+            direction +
+          offset;
       }
 
-      const finalOffset =
-        (Math.floor(Math.abs(handlerOffset.value / totalSize)) + (isCloseToNextLoop ? 1 : 0)) *
-          totalSize *
-          direction +
-        offset;
-
       if (animated) {
         index.value = i;
         handlerOffset.value = scrollWithTiming(finalOffset, onFinished);