react-native-gesture-image-viewer 2.2.0 → 2.3.0

package/src/types.ts

@@ -75,6 +75,15 @@ export type TriggerRect = {
   height: number;
 };
 
+export type GestureViewerSingleTapEvent<ItemT> = {
+  x: number;
+  y: number;
+  index: number;
+  item: ItemT;
+};
+
+export type GestureViewerDismissDirection = 'down' | 'up' | 'both';
+
 export interface TriggerAnimationConfig extends WithTimingConfig {
   /**
    * Animation duration in milliseconds
@@ -121,9 +130,18 @@ export interface GestureViewerProps<ItemT, LC> {
    * A callback function that is called to render the item.
    */
   renderItem: (item: ItemT, index: number) => React.ReactElement;
+  /**
+   * A callback function that is called when a single tap is confirmed on the viewer content.
+   * @remarks
+   * - The callback runs only after the tap is resolved as a single tap, so it may be slightly delayed when double-tap zoom is enabled.
+   * - It is not called for swipe, pinch, dismiss, or double-tap zoom gestures.
+   * - Prefer this callback over overlaying a pressable in `renderContainer` for fullscreen tap handling.
+   */
+  onSingleTap?: (event: GestureViewerSingleTapEvent<ItemT>) => void;
   /**
    * A callback function that is called to render the container.
    * @remarks Useful for composing additional UI (e.g., close button, toolbars) around the viewer.
+   * Prefer `onSingleTap` for fullscreen tap handling instead of overlaying a pressable over the viewer content.
    * The second argument provides control helpers such as `dismiss()` to close the viewer.
    *
    * @param children - The viewer content to be rendered inside your container.
@@ -183,8 +201,8 @@ export interface GestureViewerProps<ItemT, LC> {
    */
   autoPlayInterval?: number;
   /**
-   * Dismiss gesture options. Calls `onDismiss` function when swiping down.
-   * @remarks Useful for closing modals with downward swipe gestures.
+   * Dismiss gesture options.
+   * @remarks Useful for closing modals with configurable vertical swipe gestures.
    */
   dismiss?: {
     /**
@@ -192,6 +210,12 @@ export interface GestureViewerProps<ItemT, LC> {
      * @defaultValue true
      */
     enabled?: boolean;
+    /**
+     * Controls which vertical swipe direction can trigger `onDismiss`.
+     * @remarks Use `down` for backward-compatible behavior, `up` for upward-only dismiss, or `both` for either direction.
+     * @defaultValue 'down'
+     */
+    direction?: GestureViewerDismissDirection;
     /**
      * `threshold` controls when `onDismiss` is called by applying a threshold value during vertical gestures.
      * @defaultValue 80
@@ -203,7 +227,7 @@ export interface GestureViewerProps<ItemT, LC> {
      */
     resistance?: number;
     /**
-     * By default, the background `opacity` gradually decreases from 1 to 0 during downward swipe gestures.
+     * By default, the background `opacity` gradually decreases as you drag in the configured dismiss direction.
      * @remarks When `false`, this animation is disabled.
      * @defaultValue true
      */
@@ -425,11 +449,14 @@ export type GestureViewerState = {
   readonly totalCount: number;
 };
 
-export type GestureViewerEventType = 'zoomChange' | 'rotationChange';
+export type GestureViewerEventType = 'zoomChange' | 'rotationChange' | 'tap';
+
+export type SingleTapEventData = { kind: 'single'; x: number; y: number; index: number };
 
 export type GestureViewerEventData = {
   zoomChange: { scale: number; previousScale: number | null };
   rotationChange: { rotation: number; previousRotation: number | null };
+  tap: SingleTapEventData;
 };
 
 export type GestureViewerEventCallback<T extends GestureViewerEventType> = (

package/src/useGestureViewer.ts

@@ -17,6 +17,7 @@ import { registry } from './GestureViewerRegistry';
 import type { GestureViewerProps, TriggerRect } from './types';
 import { useGestureViewerPaging } from './useGestureViewerPaging';
 import { createBoundsConstraint, createScrollAction } from './utils';
+import { getDismissDistance, shouldDismissByDirection } from './utils/dismiss';
 import { applyTapZoomAtPoint } from './utils/tapZoom';
 
 type UseGestureViewerProps<ItemT, LC> = Omit<
@@ -34,6 +35,7 @@ export const useGestureViewer = <ItemT, LC>({
   data,
   initialIndex = 0,
   onDismiss,
+  onSingleTap,
   width: customWidth,
   dismiss,
   enableDoubleTapZoom = true,
@@ -68,6 +70,9 @@ export const useGestureViewer = <ItemT, LC>({
   const triggerRectRef = useRef<TriggerRect | null>(null);
   const pendingIndexRef = useRef(initialIndex);
   const onAnimationCompleteRef = useRef(triggerAnimation?.onAnimationComplete);
+  const onSingleTapRef = useRef(onSingleTap);
+  const dataRef = useRef(data);
+  const managerRef = useRef(manager);
 
   const isValidTriggerRect = useCallback((rect: TriggerRect | null): rect is TriggerRect => {
     return !!rect && rect.width > 0 && rect.height > 0;
@@ -104,12 +109,19 @@ export const useGestureViewer = <ItemT, LC>({
 
   const dismissOptions = useMemo(
     () => ({
+      direction: dismiss?.direction ?? 'down',
       enabled: dismiss?.enabled ?? true,
       fadeBackdrop: dismiss?.fadeBackdrop ?? true,
       resistance: dismiss?.resistance ?? 2,
       threshold: dismiss?.threshold ?? 80,
     }),
-    [dismiss?.enabled, dismiss?.threshold, dismiss?.resistance, dismiss?.fadeBackdrop],
+    [
+      dismiss?.direction,
+      dismiss?.enabled,
+      dismiss?.threshold,
+      dismiss?.resistance,
+      dismiss?.fadeBackdrop,
+    ],
   );
 
   const adjustedInitialIndex = useMemo(() => {
@@ -176,23 +188,13 @@ export const useGestureViewer = <ItemT, LC>({
     [dataLength, manager, resetTransformState],
   );
 
-  const emitZoomChange = useCallback(
-    (currentScale: number, prevScale: number | null) => {
-      if (manager) {
-        manager.emitZoomChange(currentScale, prevScale);
-      }
-    },
-    [manager],
-  );
+  const emitZoomChange = useCallback((currentScale: number, prevScale: number | null) => {
+    managerRef.current?.emitZoomChange(currentScale, prevScale);
+  }, []);
 
-  const emitRotationChange = useCallback(
-    (currentRotation: number, prevRotation: number | null) => {
-      if (manager) {
-        manager.emitRotationChange(currentRotation, prevRotation);
-      }
-    },
-    [manager],
-  );
+  const emitRotationChange = useCallback((currentRotation: number, prevRotation: number | null) => {
+    managerRef.current?.emitRotationChange(currentRotation, prevRotation);
+  }, []);
 
   const onAnimationComplete = useCallback(() => {
     onAnimationCompleteRef.current?.();
@@ -317,6 +319,18 @@ export const useGestureViewer = <ItemT, LC>({
     onAnimationCompleteRef.current = triggerAnimation?.onAnimationComplete;
   }, [triggerAnimation?.onAnimationComplete]);
 
+  useEffect(() => {
+    dataRef.current = data;
+  }, [data]);
+
+  useEffect(() => {
+    managerRef.current = manager;
+  }, [manager]);
+
+  useEffect(() => {
+    onSingleTapRef.current = onSingleTap;
+  }, [onSingleTap]);
+
   useEffect(() => {
     if (shouldStartTriggerAnimation && triggerRectRef.current) {
       const startX = triggerRectRef.current.x + triggerRectRef.current.width / 2 - width / 2;
@@ -475,7 +489,14 @@ export const useGestureViewer = <ItemT, LC>({
         translateY.value = event.translationY / dismissOptions.resistance;
       })
       .onEnd((event) => {
-        if (canDismiss && event.translationY > dismissOptions.threshold) {
+        if (
+          canDismiss &&
+          shouldDismissByDirection(
+            event.translationY,
+            dismissOptions.threshold,
+            dismissOptions.direction,
+          )
+        ) {
           scheduleOnRN(handleDismiss);
           return;
         }
@@ -647,6 +668,40 @@ export const useGestureViewer = <ItemT, LC>({
     ],
   );
 
+  const emitSingleTap = useCallback((x: number, y: number) => {
+    const index = pendingIndexRef.current;
+    const currentData = dataRef.current;
+
+    if (index < 0 || index >= currentData.length) {
+      return;
+    }
+
+    managerRef.current?.emitTap({ kind: 'single', x, y, index });
+
+    const item = currentData[index];
+
+    if (item === undefined) {
+      return;
+    }
+
+    onSingleTapRef.current?.({ x, y, index, item });
+  }, []);
+
+  const singleTapGesture = useMemo(
+    () =>
+      Gesture.Tap()
+        .enabled(Platform.OS !== 'web')
+        .numberOfTaps(1)
+        .onEnd((event, success) => {
+          if (!success) {
+            return;
+          }
+
+          scheduleOnRN(emitSingleTap, event.x, event.y);
+        }),
+    [emitSingleTap],
+  );
+
   const doubleTapGesture = useMemo(
     () =>
       Gesture.Tap()
@@ -667,9 +722,14 @@ export const useGestureViewer = <ItemT, LC>({
     [enableDoubleTapZoom, height, maxZoomScale, scale, translateX, translateY, width],
   );
 
+  const tapGesture = useMemo(
+    () => Gesture.Exclusive(doubleTapGesture, singleTapGesture),
+    [doubleTapGesture, singleTapGesture],
+  );
+
   const zoomGesture = useMemo(
-    () => Gesture.Race(zoomPinchGesture, Gesture.Exclusive(zoomPanGesture, doubleTapGesture)),
-    [zoomPinchGesture, zoomPanGesture, doubleTapGesture],
+    () => Gesture.Race(zoomPinchGesture, Gesture.Exclusive(zoomPanGesture, tapGesture)),
+    [zoomPinchGesture, zoomPanGesture, tapGesture],
   );
 
   const animatedStyle = useAnimatedStyle(() => ({
@@ -693,39 +753,40 @@ export const useGestureViewer = <ItemT, LC>({
       return { opacity: baseOpacity };
     }
 
-    const dismissOpacity = interpolate(translateY.value, [0, 200], [1, 0], 'clamp');
+    const dismissDistance = getDismissDistance(translateY.value, dismissOptions.direction);
+    const dismissOpacity = interpolate(dismissDistance, [0, 200], [1, 0], 'clamp');
 
     return { opacity: baseOpacity * dismissOpacity };
-  }, [dismissOptions.fadeBackdrop]);
+  }, [dismissOptions.direction, dismissOptions.fadeBackdrop]);
 
   const nativeScrollGesture = useMemo(() => {
     return Gesture.Native().requireExternalGestureToFail(dismissGestureRef);
   }, []);
 
-  const { onMomentumScrollEnd, onScroll, onScrollBeginDrag, onWebDoubleClick } =
-    useGestureViewerPaging({
-      adjustedInitialIndex,
-      autoPlay,
-      autoPlayInterval,
-      currentIndex,
-      dataLength,
-      enableDoubleTapZoom,
-      enableHorizontalSwipe,
-      enableLoop,
-      height,
-      isRotated,
-      isZoomed,
-      itemSpacing,
-      manager,
-      maxZoomScale,
-      scale,
-      scrollTo,
-      syncCurrentIndex,
-      syncPendingIndex,
-      translateX,
-      translateY,
-      width,
-    });
+  const { onMomentumScrollEnd, onScroll, onScrollBeginDrag, onWebClick } = useGestureViewerPaging({
+    adjustedInitialIndex,
+    autoPlay,
+    autoPlayInterval,
+    currentIndex,
+    dataLength,
+    enableDoubleTapZoom,
+    enableHorizontalSwipe,
+    enableLoop,
+    height,
+    isRotated,
+    isZoomed,
+    itemSpacing,
+    manager,
+    maxZoomScale,
+    onSingleTap: emitSingleTap,
+    scale,
+    scrollTo,
+    syncCurrentIndex,
+    syncPendingIndex,
+    translateX,
+    translateY,
+    width,
+  });
 
   return {
     animatedStyle,
@@ -739,7 +800,7 @@ export const useGestureViewer = <ItemT, LC>({
     isZoomed,
     listRef,
     nativeScrollGesture,
-    onWebDoubleClick,
+    onWebClick,
     onMomentumScrollEnd,
     onScroll,
 

package/src/useGestureViewerEvent.ts

@@ -8,7 +8,7 @@ import type { GestureViewerEventCallback, GestureViewerEventType } from './types
  * Hook for subscribing to GestureViewer events on the default instance.
  *
  * This hook allows you to listen to specific events from the default GestureViewer instance
- * (with ID 'default'), such as zoom changes or rotation changes. Events are automatically
+ * (with ID 'default'), such as zoom changes, rotation changes, or confirmed tap events. Events are automatically
  * throttled to prevent excessive callback invocations during gestures.
  *
  * @param eventType - The type of event to listen for
@@ -25,6 +25,13 @@ import type { GestureViewerEventCallback, GestureViewerEventType } from './types
  * useGestureViewerEvent('rotationChange', (data) => {
  *   console.log(`Rotation changed from ${data.previousRotation}° to ${data.rotation}°`);
  * });
+ *
+ * // Listen to confirmed single taps on the default instance (ID: 'default')
+ * useGestureViewerEvent('tap', (data) => {
+ *   if (data.kind === 'single') {
+ *     console.log(`Tapped item ${data.index} at (${data.x}, ${data.y})`);
+ *   }
+ * });
  * ```
  */
 export function useGestureViewerEvent<T extends GestureViewerEventType>(
@@ -53,6 +60,13 @@ export function useGestureViewerEvent<T extends GestureViewerEventType>(
  * useGestureViewerEvent('modal-viewer', 'rotationChange', (data) => {
  *   updateRotationIndicator(data.rotation);
  * });
+ *
+ * // Listen to confirmed single taps on a specific instance
+ * useGestureViewerEvent('gallery', 'tap', (data) => {
+ *   if (data.kind === 'single') {
+ *     console.log(`Gallery tap on item ${data.index}`);
+ *   }
+ * });
  * ```
  */
 export function useGestureViewerEvent<T extends GestureViewerEventType>(

package/src/useGestureViewerPaging.ts

@@ -123,6 +123,6 @@ export function useGestureViewerPaging({
     onMomentumScrollEnd,
     onScroll,
     onScrollBeginDrag,
-    onWebDoubleClick: undefined,
+    onWebClick: undefined,
   };
 }

package/src/useGestureViewerPaging.types.ts

@@ -1,3 +1,4 @@
+import type { MouseEvent } from 'react';
 import type { ScrollViewProps } from 'react-native';
 import type { SharedValue } from 'react-native-reanimated';
 
@@ -18,6 +19,7 @@ export type UseGestureViewerPagingArgs = {
   itemSpacing: number;
   manager: GestureViewerManager | null;
   maxZoomScale: number;
+  onSingleTap?: (x: number, y: number) => void;
   scale: SharedValue<number>;
   scrollTo: (index: number, animated: boolean) => void;
   syncCurrentIndex: (nextIndex: number) => void;
@@ -27,9 +29,13 @@ export type UseGestureViewerPagingArgs = {
   width: number;
 };
 
+export type WebClickTarget = {
+  getBoundingClientRect: () => { left: number; top: number };
+};
+
 export type UseGestureViewerPagingResult = {
   onMomentumScrollEnd?: ScrollViewProps['onMomentumScrollEnd'];
   onScroll?: ScrollViewProps['onScroll'];
   onScrollBeginDrag?: ScrollViewProps['onScrollBeginDrag'];
-  onWebDoubleClick?: (event: any) => void;
+  onWebClick?: (event: MouseEvent<WebClickTarget>) => void;
 };

package/src/useGestureViewerPaging.web.ts

@@ -1,9 +1,10 @@
-import { useCallback, useEffect, useRef } from 'react';
+import { useCallback, useEffect, useRef, type MouseEvent } from 'react';
 import type { NativeScrollEvent, NativeSyntheticEvent } from 'react-native';
 
 import type {
   UseGestureViewerPagingArgs,
   UseGestureViewerPagingResult,
+  WebClickTarget,
 } from './useGestureViewerPaging.types';
 import { applyTapZoomAtPoint } from './utils/tapZoom';
 import {
@@ -35,6 +36,7 @@ export function useGestureViewerPaging({
   enableHorizontalSwipe,
   enableLoop,
   height,
+  onSingleTap,
   isRotated,
   isZoomed,
   itemSpacing,
@@ -48,6 +50,8 @@ export function useGestureViewerPaging({
   translateY,
   width,
 }: UseGestureViewerPagingArgs): UseGestureViewerPagingResult {
+  const webSingleTapTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
   const webScrollRuntimeRef = useRef<WebScrollRuntime>({
     actor: 'idle',
     isAutoplayPausedByUser: false,
@@ -59,6 +63,13 @@ export function useGestureViewerPaging({
     resumeAutoplayTimer: null,
   });
 
+  const clearWebSingleTapTimer = useCallback(() => {
+    if (webSingleTapTimerRef.current) {
+      clearTimeout(webSingleTapTimerRef.current);
+      webSingleTapTimerRef.current = null;
+    }
+  }, []);
+
   const clearWebSettleTimer = useCallback(() => {
     const runtime = webScrollRuntimeRef.current;
 
@@ -232,10 +243,11 @@ export function useGestureViewerPaging({
 
   useEffect(() => {
     return () => {
+      clearWebSingleTapTimer();
       clearWebSettleTimer();
       clearWebAutoplayResumeTimer();
     };
-  }, [clearWebAutoplayResumeTimer, clearWebSettleTimer]);
+  }, [clearWebAutoplayResumeTimer, clearWebSettleTimer, clearWebSingleTapTimer]);
 
   useEffect(() => {
     if (
@@ -351,50 +363,62 @@ export function useGestureViewerPaging({
     manager?.handleScrollBeginDrag();
   }, [beginWebUserInteraction, clearWebSettleTimer, manager]);
 
-  const onWebDoubleClick = useCallback(
-    (event: any) => {
-      if (!enableDoubleTapZoom || event?.nativeEvent?.detail !== 2) {
+  const onWebClick = useCallback(
+    (event: MouseEvent<WebClickTarget>) => {
+      const detail = event.detail;
+      const rect = event.currentTarget.getBoundingClientRect();
+      const resolvedX = event.clientX - rect.left;
+      const resolvedY = event.clientY - rect.top;
+
+      if (!enableDoubleTapZoom) {
+        if (!onSingleTap) {
+          return;
+        }
+
+        clearWebSingleTapTimer();
+        onSingleTap(resolvedX, resolvedY);
         return;
       }
 
-      pauseWebAutoplayWithoutPagingInteraction();
-      scheduleWebAutoplayResume();
+      if (detail === 2) {
+        clearWebSingleTapTimer();
 
-      const nativeEvent = event?.nativeEvent;
-      const eventTarget = event?.currentTarget ?? nativeEvent?.currentTarget ?? nativeEvent?.target;
-      let locationX = nativeEvent?.locationX;
-      let locationY = nativeEvent?.locationY;
+        pauseWebAutoplayWithoutPagingInteraction();
+        scheduleWebAutoplayResume();
 
-      if (
-        (!Number.isFinite(locationX) || !Number.isFinite(locationY)) &&
-        typeof eventTarget?.getBoundingClientRect === 'function' &&
-        Number.isFinite(nativeEvent?.clientX) &&
-        Number.isFinite(nativeEvent?.clientY)
-      ) {
-        const rect = eventTarget.getBoundingClientRect();
+        applyTapZoomAtPoint({
+          x: resolvedX,
+          y: resolvedY,
+          width,
+          height,
+          maxZoomScale,
+          scale,
+          translateX,
+          translateY,
+        });
+        return;
+      }
 
-        locationX = nativeEvent.clientX - rect.left;
-        locationY = nativeEvent.clientY - rect.top;
+      if (detail !== 1 || !onSingleTap) {
+        return;
       }
 
-      applyTapZoomAtPoint({
-        x: Number.isFinite(locationX) ? locationX : width / 2,
-        y: Number.isFinite(locationY) ? locationY : height / 2,
-        width,
-        height,
-        maxZoomScale,
-        scale,
-        translateX,
-        translateY,
-      });
+      clearWebSingleTapTimer();
+
+      webSingleTapTimerRef.current = setTimeout(() => {
+        onSingleTap(resolvedX, resolvedY);
+        webSingleTapTimerRef.current = null;
+      }, 250);
     },
     [
+      clearWebSingleTapTimer,
       enableDoubleTapZoom,
       height,
       maxZoomScale,
+      onSingleTap,
       pauseWebAutoplayWithoutPagingInteraction,
-      scheduleWebAutoplayResume,
       scale,
+      scheduleWebAutoplayResume,
       translateX,
       translateY,
       width,
@@ -405,6 +429,6 @@ export function useGestureViewerPaging({
     onMomentumScrollEnd,
     onScroll,
     onScrollBeginDrag,
-    onWebDoubleClick,
+    onWebClick,
   };
 }

package/src/utils/dismiss.ts

@@ -0,0 +1,36 @@
+import type { GestureViewerDismissDirection } from '../types';
+
+export const shouldDismissByDirection = (
+  translationY: number,
+  threshold: number,
+  direction: GestureViewerDismissDirection,
+): boolean => {
+  'worklet';
+
+  if (direction === 'up') {
+    return translationY < -threshold;
+  }
+
+  if (direction === 'both') {
+    return Math.abs(translationY) > threshold;
+  }
+
+  return translationY > threshold;
+};
+
+export const getDismissDistance = (
+  translationY: number,
+  direction: GestureViewerDismissDirection,
+): number => {
+  'worklet';
+
+  if (direction === 'up') {
+    return Math.max(-translationY, 0);
+  }
+
+  if (direction === 'both') {
+    return Math.abs(translationY);
+  }
+
+  return Math.max(translationY, 0);
+};