fix(web): stabilize paging sync for autoplay, controller, and double-click zoom (#152)

* fix(web): stabilize paging sync for autoplay, controller, and double-click zoom

* fix(web): stabilize paging and double-click zoom behavior

* fix(web): stabilize paging state and double-click zoom behavior

* fix(controller): reset transforms before programmatic page navigation

Author: saseungmin

.changeset/shaggy-showers-judge.md

@@ -0,0 +1,9 @@
+---
+'react-native-gesture-image-viewer': patch
+---
+
+fix(web): stabilize paging sync for autoplay, controller, and double-click zoom
+
+Fix several web-specific paging and interaction issues in `GestureViewer`.
+
+This improves loop and autoplay index synchronization on web, keeps controller-driven navigation in sync, restores double-click zoom, and refines web paging behavior so settled pages match the browser's final scroll position more naturally.

src/GestureViewer.tsx

@@ -59,7 +59,9 @@ export function GestureViewer<ItemT, LC>({
     dismissGesture,
     zoomGesture,
     nativeScrollGesture,
+    onWebDoubleClick,
     onMomentumScrollEnd,
+    onScroll,
     onScrollBeginDrag,
     animatedStyle,
     backdropStyle,
@@ -136,7 +138,8 @@ export function GestureViewer<ItemT, LC>({
         horizontal: true,
         scrollEnabled: !isZoomed && !isRotated && !isPinching,
         showsHorizontalScrollIndicator: false,
-        onMomentumScrollEnd: onMomentumScrollEnd,
+        onMomentumScrollEnd,
+        onScroll,
         onScrollBeginDrag,
         ...(enableSnapMode
           ? {
@@ -157,6 +160,7 @@ export function GestureViewer<ItemT, LC>({
       isRotated,
       isPinching,
       onMomentumScrollEnd,
+      onScroll,
       onScrollBeginDrag,
       enableSnapMode,
     ],
@@ -187,6 +191,7 @@ export function GestureViewer<ItemT, LC>({
           <Animated.View style={[styles.background, backdropStyleProps, backdropStyle]} />
           <Animated.View
             style={[styles.content, animatedStyle]}
+            {...(Platform.OS === 'web' && { onClick: onWebDoubleClick })}
             {...(Platform.OS === 'web' &&
               isFlashListLike(Component) && { dataSet: { 'flash-list-paging-enabled-fix': true } })}
           >

src/GestureViewerManager.ts

@@ -22,8 +22,10 @@ class GestureViewerManager {
   private rotation: SharedValue<number> | null = null;
   private translateX: SharedValue<number> | null = null;
   private translateY: SharedValue<number> | null = null;
+  private resetTransformCallback: (() => void) | null = null;
 
   private loopCallback: (() => void) | null = null;
+  private programmaticScrollVersion = 0;
 
   private listeners = new Set<(state: GestureViewerState) => void>();
   private eventListeners = new Map<GestureViewerEventType, Set<(data: any) => void>>();
@@ -91,6 +93,10 @@ class GestureViewerManager {
     };
   }
 
+  getProgrammaticScrollVersion() {
+    return this.programmaticScrollVersion;
+  }
+
   setEnableLoop(enabled: boolean) {
     this.enableLoop = enabled;
   }
@@ -133,6 +139,10 @@ class GestureViewerManager {
     this.maxZoomScale = maxZoomScale;
   }
 
+  setResetTransformCallback(callback: (() => void) | null) {
+    this.resetTransformCallback = callback;
+  }
+
   notifyStateChange() {
     this.notifyListeners();
   }
@@ -255,7 +265,7 @@ class GestureViewerManager {
       return;
     }
 
-    this.loopCallback = null;
+    this.cancelPendingLoopTransition();
 
     const { scrollTo } = createScrollAction(this.listRef, this.width);
 
@@ -264,9 +274,11 @@ class GestureViewerManager {
         this.loopCallback = () => {
           scrollTo(this.dataLength, false);
           this.updateCurrentIndex(this.dataLength - 1);
-          this.loopCallback = null;
+          this.cancelPendingLoopTransition();
         };
 
+        this.resetTransformCallback?.();
+        this.programmaticScrollVersion += 1;
         scrollTo(0, true);
         return;
       }
@@ -275,13 +287,17 @@ class GestureViewerManager {
         this.loopCallback = () => {
           scrollTo(1, false);
           this.updateCurrentIndex(0);
-          this.loopCallback = null;
+          this.cancelPendingLoopTransition();
         };
 
+        this.resetTransformCallback?.();
+        this.programmaticScrollVersion += 1;
         scrollTo(this.dataLength + 1, true);
         return;
       }
 
+      this.resetTransformCallback?.();
+      this.programmaticScrollVersion += 1;
       scrollTo(index + 1, true);
       this.updateCurrentIndex(index);
 
@@ -292,6 +308,8 @@ class GestureViewerManager {
       return;
     }
 
+    this.resetTransformCallback?.();
+    this.programmaticScrollVersion += 1;
     scrollTo(index, true);
     this.updateCurrentIndex(index);
   };
@@ -306,14 +324,18 @@ class GestureViewerManager {
       return true;
     }
 
-    this.loopCallback = null;
+    this.cancelPendingLoopTransition();
     return true;
   };
 
-  handleScrollBeginDrag = () => {
+  cancelPendingLoopTransition = () => {
     this.loopCallback = null;
   };
 
+  handleScrollBeginDrag = () => {
+    this.cancelPendingLoopTransition();
+  };
+
   goToPrevious = () => {
     this.goToIndex(this.currentIndex - 1);
   };
@@ -323,7 +345,7 @@ class GestureViewerManager {
   };
 
   cleanUp() {
-    this.loopCallback = null;
+    this.cancelPendingLoopTransition();
     this.listeners.clear();
     this.listRef = null;
     this.enableHorizontalSwipe = true;
@@ -334,6 +356,7 @@ class GestureViewerManager {
     this.translateX = null;
     this.translateY = null;
     this.rotation = null;
+    this.resetTransformCallback = null;
     this.eventListeners.clear();
   }
 

src/__tests__/webScroll.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from '@jest/globals';
+
+import { getWebAutoPlayTargetPhysicalIndex, resolveWebScrollFinalState } from '../utils/webScroll';
+
+describe('web scroll settling', () => {
+  it('wraps from the first page to the last page when loop is enabled', () => {
+    expect(
+      resolveWebScrollFinalState({
+        dataLength: 5,
+        enableLoop: true,
+        lastSettledPhysicalIndex: 1,
+        offsetX: 0,
+        pageWidth: 100,
+      }),
+    ).toEqual({
+      logicalIndex: 4,
+      rawPhysicalIndex: 0,
+      settledPhysicalIndex: 5,
+    });
+  });
+
+  it('wraps from the last page to the first page when loop is enabled', () => {
+    expect(
+      resolveWebScrollFinalState({
+        dataLength: 5,
+        enableLoop: true,
+        lastSettledPhysicalIndex: 5,
+        offsetX: 600,
+        pageWidth: 100,
+      }),
+    ).toEqual({
+      logicalIndex: 0,
+      rawPhysicalIndex: 6,
+      settledPhysicalIndex: 1,
+    });
+  });
+
+  it('treats a FlashList-style jump from the first page to the loop tail as a wrap to the last page', () => {
+    expect(
+      resolveWebScrollFinalState({
+        dataLength: 5,
+        enableLoop: true,
+        lastSettledPhysicalIndex: 1,
+        offsetX: 500,
+        pageWidth: 100,
+      }),
+    ).toEqual({
+      logicalIndex: 4,
+      rawPhysicalIndex: 5,
+      settledPhysicalIndex: 5,
+    });
+  });
+
+  it('treats a FlashList-style jump from the last page to the loop head as a wrap to the first page', () => {
+    expect(
+      resolveWebScrollFinalState({
+        dataLength: 5,
+        enableLoop: true,
+        lastSettledPhysicalIndex: 5,
+        offsetX: 100,
+        pageWidth: 100,
+      }),
+    ).toEqual({
+      logicalIndex: 0,
+      rawPhysicalIndex: 1,
+      settledPhysicalIndex: 1,
+    });
+  });
+  it('does not settle on an intermediate raw page when the last observed raw page has already changed', () => {
+    const firstPass = resolveWebScrollFinalState({
+      dataLength: 5,
+      enableLoop: false,
+      lastSettledPhysicalIndex: 1,
+      offsetX: 200,
+      pageWidth: 100,
+    });
+
+    expect(firstPass).toEqual({
+      logicalIndex: 2,
+      rawPhysicalIndex: 2,
+      settledPhysicalIndex: 2,
+    });
+  });
+  it('keeps non-loop web paging aligned to the browser-settled logical page', () => {
+    expect(
+      resolveWebScrollFinalState({
+        dataLength: 5,
+        enableLoop: false,
+        lastSettledPhysicalIndex: 1,
+        offsetX: 400,
+        pageWidth: 100,
+      }),
+    ).toEqual({
+      logicalIndex: 4,
+      rawPhysicalIndex: 4,
+      settledPhysicalIndex: 4,
+    });
+  });
+
+  it('calculates the next autoplay target for looped web paging', () => {
+    expect(
+      getWebAutoPlayTargetPhysicalIndex({
+        currentIndex: 3,
+        dataLength: 5,
+        enableLoop: true,
+      }),
+    ).toBe(5);
+
+    expect(
+      getWebAutoPlayTargetPhysicalIndex({
+        currentIndex: 4,
+        dataLength: 5,
+        enableLoop: true,
+      }),
+    ).toBe(6);
+  });
+});