feat: add loop mode for GestureViewer (#51)

Author: saseungmin

.changeset/giant-wolves-share.md

@@ -0,0 +1,23 @@
+---
+"react-native-gesture-image-viewer": minor
+---
+
+feat: add loop mode for GestureViewer
+- Add `enableLoop` prop for seamless boundary crossing
+- Implement `goToNext`/`goToPrevious` with loop animation
+- Support both FlatList, FlashList and ScrollView components
+
+Example usage:
+
+```tsx
+// New prop
+<GestureViewer
+  enableLoop={true}  // Enable loop mode
+  data={images}
+  renderItem={renderItem}
+/>
+
+// Enhanced controller methods
+const { goToNext, goToPrevious } = useGestureViewerController();
+// Now supports loop transitions when enableLoop is true
+```

README-ko_kr.md

@@ -149,6 +149,7 @@ function App() {
     <GestureViewer
       data={images}
       renderItem={renderImage}
+      enableLoop={false}
       enableDismissGesture
       enableSwipeGesture
       enableZoomGesture
@@ -161,6 +162,7 @@ function App() {
 
 |속성|설명|기본값|
 |:--:|:-----|:--:|
+|`enableLoop`|루프 모드를 활성화합니다. `true`일 때 마지막 아이템에서 다음으로 가면 첫 번째로, 첫 번째에서 이전으로 가면 마지막으로 돌아갑니다.|`false`|
 |`enableDismissGesture`|아래로 스와이프할 때 `onDismiss` 함수를 호출합니다. 모달을 아래로 스와이프해서 닫는 제스처에 유용합니다.|`true`|
 |`enableSwipeGesture`|좌우 스와이프 제스처를 제어합니다. `false`일 때 가로 제스처가 비활성화됩니다.|`true`|
 |`enableZoomGesture`|두 손가락 핀치 제스처를 제어합니다. `false`일 때 핀치 줌 제스처가 비활성화됩니다. 핀치 줌은 두 손가락 사이의 중심점을 기준으로 확대됩니다.|`true`|

README.md

@@ -149,6 +149,7 @@ function App() {
     <GestureViewer
       data={images}
       renderItem={renderImage}
+      enableLoop={false}
       enableDismissGesture
       enableSwipeGesture
       enableZoomGesture
@@ -161,6 +162,7 @@ function App() {
 
 |Property|Description|Default|
 |:--:|:-----|:--:|
+|`enableLoop`|Enables loop mode. When `true`, navigating next from the last item goes to the first item, and navigating previous from the first item goes to the last item.|`false`|
 |`enableDismissGesture`|Calls `onDismiss` function when swiping down. Useful for closing modals with downward swipe gestures.|`true`|
 |`enableSwipeGesture`|Controls left/right swipe gestures. When `false`, horizontal gestures are disabled.|`true`|
 |`enableZoomGesture`|Controls two-finger pinch gestures with focal point zooming. When `false`, pinch zoom is disabled. Zoom centers on the point between your two fingers for intuitive scaling.|`true`|

example/src/Example.tsx

@@ -16,6 +16,7 @@ const images = [
 
 function Example() {
   const [visible, setVisible] = useState(false);
+  const [enableLoop, setEnableLoop] = useState(false);
 
   const { goToIndex, goToPrevious, goToNext, currentIndex, totalCount, zoomIn, zoomOut, resetZoom, rotate } =
     useGestureViewerController();
@@ -42,13 +43,15 @@ function Example() {
 
   return (
     <View style={styles.container}>
-      <Button title="Open" onPress={() => setVisible(true)} />
+      <Button title={`Loop: ${enableLoop ? 'ON' : 'OFF'}`} onPress={() => setEnableLoop(!enableLoop)} />
+      <Button title="Open Gallery" onPress={() => setVisible(true)} />
       <Modal visible={visible} onRequestClose={() => setVisible(false)}>
         <View style={{ flex: 1 }}>
           <GestureViewer
             data={images}
             initialIndex={0}
             onDismiss={() => setVisible(false)}
+            enableLoop={enableLoop}
             ListComponent={FlashList}
             renderItem={renderImage}
             backdropStyle={{ backgroundColor: 'rgba(0, 0, 0, 0.90)' }}

src/GestureViewer.tsx

@@ -1,11 +1,11 @@
-import { useCallback, useEffect, useMemo } from 'react';
+import { useCallback, useEffect, useMemo, useRef } from 'react';
 import { type FlatList, Platform, type ScrollViewProps, StyleSheet, useWindowDimensions, View } from 'react-native';
 import { Gesture, GestureDetector, GestureHandlerRootView } from 'react-native-gesture-handler';
 import Animated from 'react-native-reanimated';
 import { registry } from './GestureViewerRegistry';
 import type { GestureViewerProps } from './types';
 import { useGestureViewer } from './useGestureViewer';
-import { isFlashListLike, isFlatListLike, isScrollViewLike } from './utils';
+import { createLoopData, isFlashListLike, isFlatListLike, isScrollViewLike } from './utils';
 import WebPagingFixStyle from './WebPagingFixStyle';
 
 export function GestureViewer<T = any, LC = typeof FlatList>({
@@ -21,21 +21,28 @@ export function GestureViewer<T = any, LC = typeof FlatList>({
   initialIndex = 0,
   itemSpacing = 0,
   useSnap = false,
+  enableLoop = false,
   ...props
 }: GestureViewerProps<T, LC>) {
   const Component = ListComponent as React.ComponentType<any>;
 
+  const dataRef = useRef(data);
+  dataRef.current = data;
+
   const { width: screenWidth } = useWindowDimensions();
 
   const width = useSnap ? customWidth || screenWidth : screenWidth;
 
+  const loopData = useMemo(() => createLoopData(dataRef, enableLoop), [enableLoop]);
+
   const {
     listRef,
     isZoomed,
     isRotated,
     dismissGesture,
     zoomGesture,
     onMomentumScrollEnd,
+    onScrollBeginDrag,
     animatedStyle,
     backdropStyle,
   } = useGestureViewer({
@@ -45,14 +52,26 @@ export function GestureViewer<T = any, LC = typeof FlatList>({
     initialIndex,
     itemSpacing,
     useSnap,
+    enableLoop,
     ...props,
   });
 
+  const keyExtractor = useCallback(
+    (item: T, index: number) => {
+      if (enableLoop) {
+        return typeof item === 'string' ? `${item}-${index}` : `item-${index}`;
+      }
+
+      return typeof item === 'string' ? item : `image-${index}`;
+    },
+    [enableLoop],
+  );
+
   const renderItem = useCallback(
     ({ item, index }: { item: T; index: number }) => {
       return (
         <View
-          key={typeof item === 'string' ? item : index}
+          key={keyExtractor(item, index)}
           style={[
             {
               width,
@@ -67,7 +86,7 @@ export function GestureViewer<T = any, LC = typeof FlatList>({
         </View>
       );
     },
-    [width, itemSpacing, renderItemProp],
+    [width, itemSpacing, renderItemProp, keyExtractor],
   );
 
   const getItemLayout = useCallback(
@@ -79,11 +98,6 @@ export function GestureViewer<T = any, LC = typeof FlatList>({
     [width, itemSpacing],
   );
 
-  const keyExtractor = useCallback(
-    (item: T, index: number) => (typeof item === 'string' ? item : `image-${index}`),
-    [],
-  );
-
   const gesture = useMemo(() => {
     return Gesture.Race(dismissGesture, zoomGesture);
   }, [zoomGesture, dismissGesture]);
@@ -94,25 +108,27 @@ export function GestureViewer<T = any, LC = typeof FlatList>({
     return () => registry.deleteManager(id);
   }, [id]);
 
-  const commonProps: ScrollViewProps = useMemo(
-    () => ({
-      horizontal: true,
-      scrollEnabled: !isZoomed && !isRotated,
-      showsHorizontalScrollIndicator: false,
-      onMomentumScrollEnd: onMomentumScrollEnd,
-      ...(useSnap
-        ? {
-            snapToInterval: width + itemSpacing,
-            snapToAlignment: 'center',
-            decelerationRate: 'fast',
-          }
-        : {
-            pagingEnabled: true,
-          }),
-      scrollEventThrottle: 16,
-      removeClippedSubviews: true,
-    }),
-    [width, itemSpacing, isZoomed, isRotated, onMomentumScrollEnd, useSnap],
+  const commonProps = useMemo(
+    () =>
+      ({
+        horizontal: true,
+        scrollEnabled: !isZoomed && !isRotated,
+        showsHorizontalScrollIndicator: false,
+        onMomentumScrollEnd: onMomentumScrollEnd,
+        onScrollBeginDrag,
+        ...(useSnap
+          ? {
+              snapToInterval: width + itemSpacing,
+              snapToAlignment: 'center',
+              decelerationRate: 'fast',
+            }
+          : {
+              pagingEnabled: true,
+            }),
+        scrollEventThrottle: 16,
+        removeClippedSubviews: true,
+      }) satisfies ScrollViewProps,
+    [width, itemSpacing, isZoomed, isRotated, onMomentumScrollEnd, onScrollBeginDrag, useSnap],
   );
 
   const listComponent = (
@@ -127,16 +143,16 @@ export function GestureViewer<T = any, LC = typeof FlatList>({
           >
             {isScrollViewLike(Component) ? (
               <Component ref={listRef} {...commonProps} {...listProps}>
-                {data.map((item, index) => renderItem({ item, index }))}
+                {loopData.map((item, index) => renderItem({ item, index }))}
               </Component>
             ) : (
               isFlatListLike(Component) && (
                 <Component
                   ref={listRef}
                   {...commonProps}
-                  data={data}
+                  data={loopData}
                   renderItem={renderItem}
-                  initialScrollIndex={initialIndex}
+                  initialScrollIndex={enableLoop && data.length > 1 ? initialIndex + 1 : initialIndex}
                   keyExtractor={keyExtractor}
                   windowSize={3}
                   maxToRenderPerBatch={3}

src/GestureViewerManager.ts

@@ -5,7 +5,7 @@ import type {
   GestureViewerEventData,
   GestureViewerEventType,
 } from './types';
-import { createBoundsConstraint } from './utils';
+import { createBoundsConstraint, createScrollAction } from './utils';
 
 class GestureViewerManager {
   private currentIndex = 0;
@@ -18,9 +18,13 @@ class GestureViewerManager {
   private maxZoomScale = 2;
   private listRef: any | null = null;
   private enableSwipeGesture = true;
+  private enableLoop = false;
   private listeners = new Set<(state: GestureViewerControllerState) => void>();
   private rotation: SharedValue<number> | null = null;
   private eventListeners = new Map<GestureViewerEventType, Set<(data: any) => void>>();
+  private animationTimeout: NodeJS.Timeout | null = null;
+
+  private static readonly LOOP_ANIMATION_DURATION = 300;
 
   private notifyListeners() {
     const state = this.getState();
@@ -79,6 +83,10 @@ class GestureViewerManager {
     };
   }
 
+  setEnableLoop(enabled: boolean) {
+    this.enableLoop = enabled;
+  }
+
   setWidth(width: number) {
     this.width = width;
   }
@@ -215,47 +223,85 @@ class GestureViewerManager {
   };
 
   goToIndex = (index: number) => {
-    if (index < 0 || index >= this.dataLength || !this.enableSwipeGesture || !this.listRef) {
+    if (!this.enableSwipeGesture || !this.listRef) {
       return;
     }
 
-    this.currentIndex = index;
+    this.cancelAnimation();
+
+    const { scrollTo } = createScrollAction(this.listRef, this.width);
+
+    if (this.enableLoop && this.dataLength > 1) {
+      if (index < 0) {
+        scrollTo(0, true);
+
+        this.animationTimeout = setTimeout(() => {
+          scrollTo(this.dataLength, false);
+          this.updateCurrentIndex(this.dataLength - 1);
+        }, GestureViewerManager.LOOP_ANIMATION_DURATION);
+        return;
+      }
+
+      if (index >= this.dataLength) {
+        scrollTo(this.dataLength + 1, true);
+
+        this.animationTimeout = setTimeout(() => {
+          scrollTo(1, false);
+          this.updateCurrentIndex(0);
+        }, GestureViewerManager.LOOP_ANIMATION_DURATION);
+        return;
+      }
+
+      const scrollIndex = index + 1;
+
+      scrollTo(scrollIndex, true);
+      this.updateCurrentIndex(index);
+
+      return;
+    }
 
-    if (this.listRef.scrollToIndex) {
-      this.listRef.scrollToIndex({ index, animated: true });
-    } else if (this.listRef.scrollTo) {
-      this.listRef.scrollTo({ x: index * this.width, animated: true });
+    if (index < 0 || index >= this.dataLength) {
+      return;
     }
 
-    this.notifyListeners();
+    scrollTo(index, true);
+    this.updateCurrentIndex(index);
   };
 
-  goToPrevious = () => {
-    if (this.currentIndex > 0) {
-      this.goToIndex(this.currentIndex - 1);
+  cancelAnimation = () => {
+    if (this.animationTimeout) {
+      clearTimeout(this.animationTimeout);
+      this.animationTimeout = null;
     }
   };
 
+  goToPrevious = () => {
+    this.goToIndex(this.currentIndex - 1);
+  };
+
   goToNext = () => {
-    if (this.currentIndex < this.dataLength - 1) {
-      this.goToIndex(this.currentIndex + 1);
-    }
+    this.goToIndex(this.currentIndex + 1);
   };
 
   cleanUp() {
+    this.cancelAnimation();
     this.listeners.clear();
     this.listRef = null;
     this.enableSwipeGesture = true;
     this.currentIndex = 0;
     this.dataLength = 0;
-
     this.maxZoomScale = 2;
     this.scale = null;
     this.translateX = null;
     this.translateY = null;
     this.rotation = null;
     this.eventListeners.clear();
   }
+
+  private updateCurrentIndex = (targetIndex: number) => {
+    this.currentIndex = targetIndex;
+    this.notifyListeners();
+  };
 }
 
 export default GestureViewerManager;

src/types.ts

@@ -130,6 +130,11 @@ export interface GestureViewerProps<T = any, LC = typeof RNFlatList> {
    * @defaultValue true
    */
   enableDoubleTapGesture?: boolean;
+  /**
+   * Enables infinite loop navigation.
+   * @defaultValue false
+   */
+  enableLoop?: boolean;
   /**
    * The maximum zoom scale.
    * @defaultValue 2