react-native-gesture-image-viewer 1.2.2 → 1.2.3

package/README.md

@@ -193,7 +193,7 @@ function App() {
 
 #### Content Components
 
-You can inject various types of content components like `expo-image`, `FastImage`, etc., through the `renderImage` prop to use gestures.
+You can inject various types of content components like `expo-image`, `FastImage`, etc., through the `renderItem` prop to use gestures.
 
 ```tsx
 import { GestureViewer } from 'react-native-gesture-image-viewer';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-gesture-image-viewer",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "description": "🖼️ A highly customizable and easy-to-use React Native image viewer with gesture support and external controls",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
@@ -14,6 +14,7 @@
   },
   "files": [
     "lib",
+    "src",
     "android",
     "ios",
     "cpp",

package/src/GestureViewer.tsx

@@ -0,0 +1,171 @@
+import { useCallback, useEffect, useMemo } 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 WebPagingFixStyle from './WebPagingFixStyle';
+
+export function GestureViewer<T = any, LC = typeof FlatList>({
+  id = 'default',
+  data,
+  renderItem: renderItemProp,
+  renderContainer,
+  ListComponent,
+  width: customWidth,
+  listProps,
+  backdropStyle: backdropStyleProps,
+  containerStyle,
+  initialIndex = 0,
+  itemSpacing = 0,
+  useSnap = false,
+  ...props
+}: GestureViewerProps<T, LC>) {
+  const Component = ListComponent as React.ComponentType<any>;
+
+  const { width: screenWidth } = useWindowDimensions();
+
+  const width = useSnap ? customWidth || screenWidth : screenWidth;
+
+  const { listRef, isZoomed, dismissGesture, zoomGesture, onMomentumScrollEnd, animatedStyle, backdropStyle } =
+    useGestureViewer({
+      id,
+      data,
+      width,
+      initialIndex,
+      itemSpacing,
+      useSnap,
+      ...props,
+    });
+
+  const renderItem = useCallback(
+    ({ item, index }: { item: T; index: number }) => {
+      return (
+        <View
+          key={typeof item === 'string' ? item : index}
+          style={[
+            {
+              width,
+              height: '100%',
+              justifyContent: 'center',
+              alignItems: 'center',
+              marginHorizontal: itemSpacing / 2,
+            },
+          ]}
+        >
+          {renderItemProp(item, index)}
+        </View>
+      );
+    },
+    [width, itemSpacing, renderItemProp],
+  );
+
+  const getItemLayout = useCallback(
+    (_: ArrayLike<T> | null | undefined, index: number) => ({
+      length: width + itemSpacing,
+      offset: (width + itemSpacing) * index,
+      index,
+    }),
+    [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]);
+
+  useEffect(() => {
+    registry.createManager(id);
+
+    return () => registry.deleteManager(id);
+  }, [id]);
+
+  const commonProps: ScrollViewProps = useMemo(
+    () => ({
+      horizontal: true,
+      scrollEnabled: !isZoomed,
+      showsHorizontalScrollIndicator: false,
+      onMomentumScrollEnd: onMomentumScrollEnd,
+      ...(useSnap
+        ? {
+            snapToInterval: width + itemSpacing,
+            snapToAlignment: 'center',
+            decelerationRate: 'fast',
+          }
+        : {
+            pagingEnabled: true,
+          }),
+      scrollEventThrottle: 16,
+      removeClippedSubviews: true,
+    }),
+    [width, itemSpacing, isZoomed, onMomentumScrollEnd, useSnap],
+  );
+
+  const listComponent = (
+    <GestureHandlerRootView>
+      <GestureDetector gesture={gesture}>
+        <View style={[styles.container, containerStyle]}>
+          <Animated.View style={[styles.background, backdropStyleProps, backdropStyle]} />
+          <Animated.View
+            style={[styles.content, animatedStyle]}
+            {...(Platform.OS === 'web' &&
+              isFlashListLike(Component) && { dataSet: { 'flash-list-paging-enabled-fix': true } })}
+          >
+            {isScrollViewLike(Component) ? (
+              <Component ref={listRef} {...commonProps} {...listProps}>
+                {data.map((item, index) => renderItem({ item, index }))}
+              </Component>
+            ) : (
+              isFlatListLike(Component) && (
+                <Component
+                  ref={listRef}
+                  {...commonProps}
+                  data={data}
+                  renderItem={renderItem}
+                  initialScrollIndex={initialIndex}
+                  keyExtractor={keyExtractor}
+                  windowSize={3}
+                  maxToRenderPerBatch={3}
+                  getItemLayout={getItemLayout}
+                  {...(isFlashListLike(Component) && { estimatedItemSize: width + itemSpacing })}
+                  // NOTE - https://github.com/necolas/react-native-web/issues/1299
+                  {...(Platform.OS === 'web' &&
+                    isFlatListLike(Component) && { dataSet: { 'flat-list-paging-enabled-fix': true } })}
+                  {...listProps}
+                />
+              )
+            )}
+          </Animated.View>
+          <WebPagingFixStyle Component={Component} />
+        </View>
+      </GestureDetector>
+    </GestureHandlerRootView>
+  );
+
+  return renderContainer ? renderContainer(listComponent) : listComponent;
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+  content: {
+    flex: 1,
+    width: '100%',
+    height: '100%',
+  },
+  background: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    backgroundColor: 'black',
+  },
+});

package/src/GestureViewerManager.ts

@@ -0,0 +1,103 @@
+export type GestureViewerManagerState = {
+  currentIndex: number;
+  dataLength: number;
+};
+
+class GestureViewerManager {
+  private currentIndex = 0;
+  private dataLength = 0;
+  private width = 0;
+  private listRef: any | null = null;
+  private enableSwipeGesture = true;
+  private listeners = new Set<(state: GestureViewerManagerState) => void>();
+
+  // private updateState(newState: Partial<any>) {
+  //   Object.assign(this, newState);
+  //   this.notifyListeners();
+  // }
+
+  private notifyListeners() {
+    const state = this.getState();
+
+    this.listeners.forEach((listener) => listener(state));
+  }
+
+  subscribe(listener: (state: GestureViewerManagerState) => void) {
+    this.listeners.add(listener);
+
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  getState() {
+    return {
+      currentIndex: this.currentIndex,
+      dataLength: this.dataLength,
+    };
+  }
+
+  setWidth(width: number) {
+    this.width = width;
+  }
+
+  setListRef(ref: any) {
+    this.listRef = ref;
+  }
+
+  setDataLength(length: number) {
+    this.dataLength = length;
+  }
+
+  setEnableSwipeGesture(enabled: boolean) {
+    this.enableSwipeGesture = enabled;
+  }
+
+  setCurrentIndex(index: number) {
+    if (index !== this.currentIndex) {
+      this.currentIndex = index;
+    }
+  }
+
+  notifyStateChange() {
+    this.notifyListeners();
+  }
+
+  goToIndex = (index: number) => {
+    if (index < 0 || index >= this.dataLength || !this.enableSwipeGesture || !this.listRef) {
+      return;
+    }
+
+    this.currentIndex = index;
+
+    if (this.listRef.scrollToIndex) {
+      this.listRef.scrollToIndex({ index, animated: true });
+    } else if (this.listRef.scrollTo) {
+      this.listRef.scrollTo({ x: index * this.width, animated: true });
+    }
+
+    this.notifyListeners();
+  };
+
+  goToPrevious = () => {
+    if (this.currentIndex > 0) {
+      this.goToIndex(this.currentIndex - 1);
+    }
+  };
+
+  goToNext = () => {
+    if (this.currentIndex < this.dataLength - 1) {
+      this.goToIndex(this.currentIndex + 1);
+    }
+  };
+
+  cleanUp() {
+    this.listeners.clear();
+    this.listRef = null;
+    this.enableSwipeGesture = true;
+    this.currentIndex = 0;
+    this.dataLength = 0;
+  }
+}
+
+export default GestureViewerManager;

package/src/GestureViewerRegistry.ts

@@ -0,0 +1,66 @@
+import GestureViewerManager from './GestureViewerManager';
+
+class GestureViewerRegistry {
+  private managers = new Map<string, GestureViewerManager>();
+  private subscribers = new Map<string, Set<(manager: GestureViewerManager | null) => void>>();
+
+  subscribeToManager(id: string, callback: (manager: GestureViewerManager | null) => void) {
+    if (!this.subscribers.has(id)) {
+      this.subscribers.set(id, new Set());
+    }
+
+    this.subscribers.get(id)?.add(callback);
+
+    const manager = this.managers.get(id) || null;
+
+    callback(manager);
+
+    return () => {
+      const subscribers = this.subscribers.get(id);
+
+      subscribers?.delete(callback);
+
+      if (subscribers && subscribers.size === 0) {
+        this.subscribers.delete(id);
+      }
+    };
+  }
+
+  createManager(id: string): GestureViewerManager | null {
+    if (this.managers.has(id)) {
+      return this.managers.get(id) || null;
+    }
+
+    const manager = new GestureViewerManager();
+    this.managers.set(id, manager);
+
+    this.notifySubscribers(id, manager);
+
+    return manager;
+  }
+
+  getManager(id: string): GestureViewerManager | null {
+    return this.managers.get(id) || null;
+  }
+
+  deleteManager(id: string) {
+    const manager = this.managers.get(id);
+
+    if (manager) {
+      manager.cleanUp();
+      this.managers.delete(id);
+
+      this.notifySubscribers(id, null);
+    }
+  }
+
+  notifySubscribers(id: string, manager: GestureViewerManager | null) {
+    const listeners = this.subscribers.get(id);
+
+    if (listeners) {
+      [...listeners].forEach((callback) => callback(manager));
+    }
+  }
+}
+
+export const registry = new GestureViewerRegistry();

package/src/WebPagingFixStyle.tsx

@@ -0,0 +1,24 @@
+import { Platform } from 'react-native';
+import { isFlashListLike, isFlatListLike } from './utils';
+
+type WebPagingFixStyleProps = {
+  Component: React.ComponentType<any>;
+};
+
+function WebPagingFixStyle({ Component }: WebPagingFixStyleProps) {
+  if (Platform.OS !== 'web') {
+    return null;
+  }
+
+  if (isFlashListLike(Component)) {
+    return <style>{`[data-flash-list-paging-enabled-fix] > div {height: 100%;}`}</style>;
+  }
+
+  if (isFlatListLike(Component)) {
+    return <style>{`[data-flat-list-paging-enabled-fix] > div > div > div {height: 100%;}`}</style>;
+  }
+
+  return null;
+}
+
+export default WebPagingFixStyle;

package/src/index.tsx

@@ -0,0 +1,3 @@
+export { GestureViewer } from './GestureViewer';
+export type { GestureViewerProps } from './types';
+export { useGestureViewerController } from './useGestureViewerController';

package/src/types.ts

@@ -0,0 +1,144 @@
+import type React from 'react';
+import type { FlatList as RNFlatList, ScrollView as RNScrollView, StyleProp, ViewStyle } from 'react-native';
+import type { FlatList as GHFlatList, ScrollView as GHScrollView } from 'react-native-gesture-handler';
+
+export type FlatListComponent = typeof RNFlatList | typeof GHFlatList;
+export type ScrollViewComponent = typeof RNScrollView | typeof GHScrollView;
+
+type GetComponentProps<T> = T extends React.ComponentType<infer P> ? P : never;
+
+type ConditionalListProps<LC> = LC extends FlatListComponent
+  ? React.ComponentProps<LC>
+  : LC extends ScrollViewComponent
+    ? React.ComponentProps<LC>
+    : GetComponentProps<LC>;
+
+export interface GestureViewerProps<T = any, LC = typeof RNFlatList> {
+  /**
+   * When you want to efficiently manage multiple `GestureViewer` instances, you can use the `id` prop to use multiple `GestureViewer` components.
+   * @remark `GestureViewer` automatically removes instances from memory when components are unmounted, so no manual memory management is required.
+   * @default 'default'
+   */
+  id?: string;
+  /**
+   * The data to display in the `GestureViewer`.
+   */
+  data: T[];
+  /**
+   * The index of the item to display in the `GestureViewer` when the component is mounted.
+   * @default 0
+   */
+  initialIndex?: number;
+  /**
+   * A callback function that is called when the index of the item changes.
+   */
+  onIndexChange?: (index: number) => void;
+  /**
+   * A callback function that is called when the `GestureViewer` is dismissed.
+   */
+  onDismiss?: () => void;
+  /**
+   * A callback function that is called to render the item.
+   */
+  renderItem: (item: T, index: number) => React.ReactElement;
+  /**
+   * A callback function that is called to render the container.
+   */
+  renderContainer?: (children: React.ReactElement) => React.ReactElement;
+  /**
+   * Support for any list component like `ScrollView`, `FlatList`, `FlashList` through the `ListComponent` prop.
+   */
+  ListComponent: LC;
+  /**
+   * The width of the `GestureViewer`.
+   * @remark If you don't set this prop, the width of the `GestureViewer` will be the same as the width of the screen.
+   * @default screen width
+   */
+  width?: number;
+  /**
+   * Enables snap scrolling mode.
+   *
+   * @remark
+   * **`false` (default)**: Paging mode (`pagingEnabled: true`)
+   * - Scrolls by full screen size increments
+   *
+   * **`true`**: Snap mode (`snapToInterval` auto-calculated)
+   * - `snapToInterval` is automatically calculated based on `width` and `itemSpacing` values
+   * - Use this option when you need item spacing
+   * @default false
+   *
+   */
+  useSnap?: boolean;
+  /**
+   * `dismissThreshold` controls when `onDismiss` is called by applying a threshold value during vertical gestures.
+   * @default 80
+   */
+  dismissThreshold?: number;
+  // swipeThreshold?: number;
+  // velocityThreshold?: number;
+  /**
+   * Calls `onDismiss` function when swiping down.
+   * @remark Useful for closing modals with downward swipe gestures.
+   * @default true
+   */
+  enableDismissGesture?: boolean;
+  /**
+   * Controls left/right swipe gestures.
+   * @remark When `false`, horizontal gestures are disabled.
+   * @default true
+   */
+  enableSwipeGesture?: boolean;
+  /**
+   * `resistance` controls the range of vertical movement by applying resistance during vertical gestures.
+   * @default 2
+   */
+  resistance?: number;
+  /**
+   * The props to pass to the list component.
+   * @remark The `listProps` provides **type inference based on the selected list component**, ensuring accurate autocompletion and type safety in your IDE.
+   */
+  listProps?: Partial<ConditionalListProps<LC>>;
+  /**
+   * The style of the backdrop.
+   */
+  backdropStyle?: StyleProp<ViewStyle>;
+  /**
+   * The style of the container.
+   */
+  containerStyle?: StyleProp<ViewStyle>;
+  /**
+   * By default, the background `opacity` gradually decreases from 1 to 0 during downward swipe gestures.
+   * @remark When `false`, this animation is disabled.
+   * @default true
+   */
+  animateBackdrop?: boolean;
+  /**
+   * Only works when zoom is active, allows moving item position when zoomed.
+   * @remark When `false`, gesture movement is disabled during zoom.
+   * @default true
+   */
+  enableZoomPanGesture?: boolean;
+  /**
+   * Controls two-finger pinch gestures.
+   * @remark When `false`, two-finger zoom gestures are disabled.
+   * @default true
+   */
+  enableZoomGesture?: boolean;
+  /**
+   * Controls double-tap zoom gestures.
+   * @remark When `false`, double-tap zoom gestures are disabled.
+   * @default true
+   */
+  enableDoubleTapGesture?: boolean;
+  /**
+   * The maximum zoom scale.
+   * @default 2
+   */
+  maxZoomScale?: number;
+  /**
+   * The spacing between items in pixels.
+   * @remark Only applied when `useSnap` is `true`.
+   * @default 0
+   */
+  itemSpacing?: number;
+}

package/src/useGestureViewer.ts

@@ -0,0 +1,424 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import {
+  InteractionManager,
+  type NativeScrollEvent,
+  type NativeSyntheticEvent,
+  useWindowDimensions,
+} from 'react-native';
+import { Gesture } from 'react-native-gesture-handler';
+import {
+  Easing,
+  interpolate,
+  runOnJS,
+  useAnimatedReaction,
+  useAnimatedStyle,
+  useSharedValue,
+  withSpring,
+  withTiming,
+} from 'react-native-reanimated';
+import type GestureViewerManager from './GestureViewerManager';
+import { registry } from './GestureViewerRegistry';
+import type { GestureViewerProps } from './types';
+
+type UseGestureViewerProps<T = any> = Omit<
+  GestureViewerProps<T>,
+  'renderItem' | 'renderContainer' | 'ListComponent' | 'listProps' | 'containerStyle' | 'backdropStyle'
+>;
+
+export const useGestureViewer = <T = any>({
+  data,
+  initialIndex = 0,
+  onIndexChange,
+  onDismiss,
+  width: customWidth,
+  dismissThreshold = 80,
+  resistance = 2,
+  // swipeThreshold = 0.5,
+  // velocityThreshold = 200,
+  animateBackdrop = true,
+  enableDismissGesture = true,
+  enableSwipeGesture = true,
+  enableZoomGesture = true,
+  enableDoubleTapGesture = true,
+  enableZoomPanGesture = true,
+  maxZoomScale = 2,
+  itemSpacing = 0,
+  useSnap = false,
+  id = 'default',
+}: UseGestureViewerProps<T>) => {
+  const { width: screenWidth, height: screenHeight } = useWindowDimensions();
+  const width = useSnap ? customWidth || screenWidth : screenWidth;
+
+  const [isZoomed, setIsZoomed] = useState(false);
+
+  const [currentIndex, setCurrentIndex] = useState(initialIndex);
+  const [manager, setManager] = useState<GestureViewerManager | null>(null);
+
+  const unsubscribeRef = useRef<(() => void) | null>(null);
+
+  const initialTranslateY = useSharedValue(0);
+  const initialTranslateX = useSharedValue(0);
+  const startScale = useSharedValue(1);
+
+  const translateY = useSharedValue(0);
+  const translateX = useSharedValue(0);
+  const scale = useSharedValue(1);
+  const backdropOpacity = useSharedValue(1);
+
+  const listRef = useRef<any>(null);
+
+  const dataLength = data?.length || 0;
+
+  const constrainToBounds = useCallback(
+    (translateX: number, translateY: number, scale: number) => {
+      'worklet';
+      if (scale <= 1) {
+        return {
+          x: translateX,
+          y: translateY,
+        };
+      }
+
+      const maxTranslateX = (width * scale - width) / 2;
+      const maxTranslateY = (screenHeight * scale - screenHeight) / 2;
+
+      return {
+        x: Math.max(-maxTranslateX, Math.min(maxTranslateX, translateX)),
+        y: Math.max(-maxTranslateY, Math.min(maxTranslateY, translateY)),
+      };
+    },
+    [width, screenHeight],
+  );
+
+  useAnimatedReaction(
+    () => scale.value,
+    (currentScale) => {
+      runOnJS(setIsZoomed)(currentScale > 1);
+    },
+  );
+
+  useEffect(() => {
+    const handleManagerChange = (manager: GestureViewerManager | null) => {
+      unsubscribeRef.current?.();
+      unsubscribeRef.current = null;
+
+      setManager(manager);
+
+      if (manager) {
+        setCurrentIndex(manager.getState().currentIndex);
+        unsubscribeRef.current = manager.subscribe((state) => {
+          setCurrentIndex(state.currentIndex);
+        });
+        return;
+      }
+
+      setCurrentIndex(0);
+    };
+
+    const unsubscribeFromRegistry = registry.subscribeToManager(id, handleManagerChange);
+
+    return () => {
+      unsubscribeFromRegistry();
+      unsubscribeRef.current?.();
+    };
+  }, [id]);
+
+  useEffect(() => {
+    if (!manager) {
+      return;
+    }
+
+    manager.setDataLength(dataLength);
+    manager.setEnableSwipeGesture(enableSwipeGesture);
+    manager.setCurrentIndex(initialIndex);
+    manager.setWidth(width + itemSpacing);
+    manager.notifyStateChange();
+  }, [dataLength, enableSwipeGesture, initialIndex, manager, width, itemSpacing]);
+
+  useEffect(() => {
+    if (!manager || !listRef.current) {
+      return;
+    }
+
+    manager.setListRef(listRef.current);
+  }, [manager]);
+
+  useEffect(() => {
+    onIndexChange?.(currentIndex);
+  }, [currentIndex, onIndexChange]);
+
+  useEffect(() => {
+    translateY.value = 0;
+    translateX.value = 0;
+    scale.value = 1;
+    backdropOpacity.value = 1;
+    startScale.value = 1;
+
+    if (initialIndex <= 0 || !listRef.current) {
+      return;
+    }
+
+    const runAfterInteractions = InteractionManager.runAfterInteractions(() => {
+      if (listRef.current.scrollToIndex) {
+        listRef.current.scrollToIndex({
+          index: initialIndex,
+          animated: false,
+        });
+      } else if (listRef.current.scrollTo) {
+        listRef.current.scrollTo({
+          x: initialIndex * (width + itemSpacing),
+          animated: false,
+        });
+      }
+    });
+
+    return () => {
+      runAfterInteractions?.cancel();
+    };
+  }, [initialIndex, translateY, backdropOpacity, translateX, scale, startScale, width, itemSpacing]);
+
+  const onMomentumScrollEnd = useCallback(
+    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      if (!enableSwipeGesture) {
+        return;
+      }
+
+      const contentOffset = event.nativeEvent.contentOffset;
+      const newIndex = Math.round(contentOffset.x / (width + itemSpacing));
+
+      if (newIndex !== currentIndex && newIndex >= 0 && newIndex < dataLength) {
+        if (manager) {
+          manager.setCurrentIndex(newIndex);
+          setCurrentIndex(newIndex);
+          manager.notifyStateChange();
+        }
+
+        translateX.value = withTiming(0);
+        translateY.value = withTiming(0);
+        initialTranslateX.value = withTiming(0);
+        initialTranslateY.value = withTiming(0);
+        startScale.value = withTiming(1);
+        scale.value = withTiming(1);
+      }
+    },
+    [
+      manager,
+      currentIndex,
+      dataLength,
+      width,
+      itemSpacing,
+      enableSwipeGesture,
+      translateX,
+      translateY,
+      scale,
+      initialTranslateX,
+      initialTranslateY,
+      startScale,
+    ],
+  );
+
+  const dismissGesture = useMemo(() => {
+    return Gesture.Pan()
+      .minDistance(10)
+      .averageTouches(true)
+      .activeCursor('grabbing')
+      .activeOffsetY([-10, 10])
+      .failOffsetX([-10, 10])
+      .enabled(!isZoomed)
+      .onUpdate((event) => {
+        translateY.value = event.translationY / resistance;
+      })
+      .onEnd((event) => {
+        if (event.translationY > dismissThreshold && enableDismissGesture && onDismiss) {
+          runOnJS(onDismiss)();
+          return;
+        }
+
+        translateY.value = withSpring(0, {
+          damping: 15,
+          stiffness: 150,
+        });
+      });
+  }, [translateY, dismissThreshold, enableDismissGesture, onDismiss, resistance, isZoomed]);
+
+  const zoomPinchGesture = useMemo(() => {
+    return Gesture.Pinch()
+      .enabled(enableZoomGesture)
+      .onBegin(() => {
+        startScale.value = scale.value;
+        initialTranslateX.value = translateX.value;
+        initialTranslateY.value = translateY.value;
+      })
+      .onUpdate((event) => {
+        const newScale = startScale.value * event.scale;
+
+        const deltaScale = newScale - startScale.value;
+        const centerX = event.focalX - width / 2;
+        const centerY = event.focalY - screenHeight / 2;
+
+        scale.value = newScale;
+        // NOTE 새로운 이동값 = 기존 이동값 - (중심점 거리 × 스케일 변화량) / 원래 스케일 (중심점이 화면 중심에서 멀수록, 확대 배율이 클수록 더 많이 이동)
+        const newTranslateX = initialTranslateX.value - (centerX * deltaScale) / startScale.value;
+        const newTranslateY = initialTranslateY.value - (centerY * deltaScale) / startScale.value;
+
+        const constrained = constrainToBounds(newTranslateX, newTranslateY, newScale);
+
+        if (newScale <= 1) {
+          translateX.value = withTiming(0);
+          translateY.value = withTiming(0);
+          return;
+        }
+
+        translateX.value = constrained.x;
+        translateY.value = constrained.y;
+      })
+      .onEnd(() => {
+        if (scale.value > maxZoomScale) {
+          scale.value = withTiming(maxZoomScale, {
+            duration: 300,
+            easing: Easing.bezier(0.25, 0.1, 0.25, 1.0),
+          });
+
+          const constrained = constrainToBounds(translateX.value, translateY.value, maxZoomScale);
+
+          translateX.value = withTiming(constrained.x);
+          translateY.value = withTiming(constrained.y);
+
+          return;
+        }
+
+        if (scale.value < 1) {
+          scale.value = withTiming(1, {
+            duration: 300,
+            easing: Easing.bezier(0.25, 0.1, 0.25, 1.0),
+          });
+          translateX.value = withTiming(0);
+          translateY.value = withTiming(0);
+          initialTranslateX.value = withTiming(0);
+          initialTranslateY.value = withTiming(0);
+          return;
+        }
+
+        const finalConstrained = constrainToBounds(translateX.value, translateY.value, scale.value);
+        translateX.value = withTiming(finalConstrained.x);
+        translateY.value = withTiming(finalConstrained.y);
+      });
+  }, [
+    scale,
+    enableZoomGesture,
+    maxZoomScale,
+    translateX,
+    translateY,
+    startScale,
+    initialTranslateX,
+    initialTranslateY,
+    width,
+    screenHeight,
+    constrainToBounds,
+  ]);
+
+  const zoomPanGesture = useMemo(() => {
+    return Gesture.Pan()
+      .enabled(enableZoomPanGesture && isZoomed)
+      .activeCursor('grabbing')
+      .averageTouches(true)
+      .onBegin(() => {
+        initialTranslateX.value = translateX.value;
+        initialTranslateY.value = translateY.value;
+      })
+      .onUpdate((event) => {
+        if (scale.value > 1) {
+          const newTranslateX = initialTranslateX.value + event.translationX;
+          const newTranslateY = initialTranslateY.value + event.translationY;
+
+          const constrained = constrainToBounds(newTranslateX, newTranslateY, scale.value);
+
+          translateX.value = constrained.x;
+          translateY.value = constrained.y;
+        }
+      });
+  }, [
+    translateX,
+    translateY,
+    enableZoomPanGesture,
+    isZoomed,
+    scale,
+    initialTranslateX,
+    initialTranslateY,
+    constrainToBounds,
+  ]);
+
+  const doubleTapGesture = useMemo(() => {
+    return Gesture.Tap()
+      .enabled(enableDoubleTapGesture)
+      .numberOfTaps(2)
+      .onEnd((event) => {
+        const nextScale = scale.value > 1 ? 1 : maxZoomScale;
+
+        if (nextScale > 1) {
+          const centerX = event.x - width / 2;
+          const centerY = event.y - screenHeight / 2;
+
+          // NOTE 확대로 밀려난 거리만큼 반대로 이동해서 탭 지점을 제자리에 유지
+          translateX.value = withTiming(-centerX * (nextScale - 1), {
+            duration: 300,
+            easing: Easing.bezier(0.25, 0.1, 0.25, 1.0),
+          });
+          translateY.value = withTiming(-centerY * (nextScale - 1), {
+            duration: 300,
+            easing: Easing.bezier(0.25, 0.1, 0.25, 1.0),
+          });
+        } else {
+          translateX.value = withTiming(0, {
+            duration: 300,
+            easing: Easing.bezier(0.25, 0.1, 0.25, 1.0),
+          });
+          translateY.value = withTiming(0, {
+            duration: 300,
+            easing: Easing.bezier(0.25, 0.1, 0.25, 1.0),
+          });
+        }
+
+        scale.value = withTiming(nextScale, {
+          duration: 300,
+          easing: Easing.bezier(0.25, 0.1, 0.25, 1.0),
+        });
+      });
+  }, [scale, enableDoubleTapGesture, maxZoomScale, translateX, translateY, width, screenHeight]);
+
+  const zoomGesture = useMemo(() => {
+    return Gesture.Race(zoomPinchGesture, Gesture.Exclusive(zoomPanGesture, doubleTapGesture));
+  }, [zoomPinchGesture, zoomPanGesture, doubleTapGesture]);
+
+  const animatedStyle = useAnimatedStyle(() => {
+    return {
+      transform: [{ translateY: translateY.value }, { translateX: translateX.value }, { scale: scale.value }],
+    };
+  });
+
+  const backdropStyle = useAnimatedStyle(() => {
+    if (!animateBackdrop || scale.value !== 1) {
+      return { opacity: 1 };
+    }
+
+    const opacity = interpolate(translateY.value, [0, 200], [1, 0], 'clamp');
+
+    return { opacity };
+  }, [animateBackdrop]);
+
+  return {
+    currentIndex,
+    dataLength,
+    translateY,
+    listRef,
+    isZoomed,
+
+    dismissGesture,
+    zoomGesture,
+
+    onMomentumScrollEnd,
+
+    animatedStyle,
+    backdropStyle,
+  };
+};

package/src/useGestureViewerController.ts

@@ -0,0 +1,48 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import type GestureViewerManager from './GestureViewerManager';
+import type { GestureViewerManagerState } from './GestureViewerManager';
+import { registry } from './GestureViewerRegistry';
+
+export const useGestureViewerController = (id = 'default') => {
+  const [state, setState] = useState<GestureViewerManagerState>({
+    currentIndex: 0,
+    dataLength: 0,
+  });
+
+  const [manager, setManager] = useState<GestureViewerManager | null>(null);
+  const unsubscribeRef = useRef<(() => void) | null>(null);
+
+  useEffect(() => {
+    const handleManagerChange = (newManager: GestureViewerManager | null) => {
+      unsubscribeRef.current?.();
+      unsubscribeRef.current = null;
+
+      setManager(newManager);
+
+      if (newManager) {
+        setState(newManager.getState());
+        unsubscribeRef.current = newManager.subscribe(setState);
+        return;
+      }
+
+      setState({ currentIndex: 0, dataLength: 0 });
+    };
+
+    const unsubscribeFromRegistry = registry.subscribeToManager(id, handleManagerChange);
+
+    return () => {
+      unsubscribeFromRegistry();
+      unsubscribeRef.current?.();
+    };
+  }, [id]);
+
+  const noopFunction = useMemo(() => () => {}, []);
+
+  return {
+    goToIndex: manager?.goToIndex || noopFunction,
+    goToPrevious: manager?.goToPrevious || noopFunction,
+    goToNext: manager?.goToNext || noopFunction,
+    currentIndex: state.currentIndex,
+    totalCount: state.dataLength,
+  };
+};

package/src/utils.ts

@@ -0,0 +1,29 @@
+import { FlatList as RNFlatList, ScrollView as RNScrollView } from 'react-native';
+import { FlatList as GestureFlatList, ScrollView as GestureScrollView } from 'react-native-gesture-handler';
+import type { FlatListComponent, ScrollViewComponent } from './types';
+
+export const isScrollViewLike = (component: any): component is ScrollViewComponent => {
+  return component === RNScrollView || component === GestureScrollView;
+};
+
+export const isFlatListLike = (component: any): component is FlatListComponent => {
+  if (component === RNFlatList || component === GestureFlatList || isFlashListLike(component)) {
+    return true;
+  }
+
+  return false;
+};
+
+export const isFlashListLike = (component: any): component is any => {
+  try {
+    const FlashList = require('@shopify/flash-list')?.FlashList;
+
+    if (FlashList && component === FlashList) {
+      return true;
+    }
+  } catch {
+    // do nothing
+  }
+
+  return component?.name === 'FlashList';
+};