react-native-gesture-image-viewer 1.6.6 → 1.7.1

package/src/types.ts

@@ -1,6 +1,7 @@
 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';
+import type { WithTimingConfig } from 'react-native-reanimated';
 
 export type FlatListComponent = typeof RNFlatList | typeof GHFlatList;
 export type ScrollViewComponent = typeof RNScrollView | typeof GHScrollView;
@@ -13,10 +14,34 @@ type ConditionalListProps<LC> = LC extends FlatListComponent
     ? React.ComponentProps<LC>
     : GetComponentProps<LC>;
 
+export type TriggerRect = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+
+export interface TriggerAnimationConfig extends WithTimingConfig {
+  /**
+   * Animation duration in milliseconds
+   * @defaultValue 300
+   */
+  duration?: WithTimingConfig['duration'];
+  /**
+   * Animation easing function
+   * @defaultValue Easing.bezier(0.25, 0.1, 0.25, 1.0)
+   */
+  easing?: WithTimingConfig['easing'];
+  /**
+   * Callback function called after animation completion
+   */
+  onAnimationComplete?: () => void;
+}
+
 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.
+   * @remarks `GestureViewer` automatically removes instances from memory when components are unmounted, so no manual memory management is required.
    * @defaultValue 'default'
    */
   id?: string;
@@ -37,28 +62,39 @@ export interface GestureViewerProps<T = any, LC = typeof RNFlatList> {
    * A callback function that is called when the `GestureViewer` is dismissed.
    */
   onDismiss?: () => void;
+  /**
+   * A callback function that is called when the dismiss interaction starts.
+   * @remarks Useful to hide external UI (e.g., headers, buttons) while the dismiss gesture/animation is in progress.
+   */
+  onDismissStart?: () => 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.
+   * @remarks Useful for composing additional UI (e.g., close button, toolbars) around the viewer.
+   * The second argument provides control helpers such as `dismiss()` to close the viewer.
+   *
+   * @param children - The viewer content to be rendered inside your container.
+   * @param helpers - Control helpers for the viewer. Currently includes `dismiss()`.
+   * @returns A React element that wraps and renders the provided `children`.
    */
-  renderContainer?: (children: React.ReactElement) => React.ReactElement;
+  renderContainer?: (children: React.ReactElement, helpers: { dismiss: () => void }) => 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.
+   * @remarks If you don't set this prop, the width of the `GestureViewer` will be the same as the width of the screen.
    * @defaultValue screen width
    */
   width?: number;
   /**
    * Enables snap scrolling mode.
    *
-   * @remark
+   * @remarks
    * **`false` (default)**: Paging mode (`pagingEnabled: true`)
    * - Scrolls by full screen size increments
    *
@@ -74,17 +110,15 @@ export interface GestureViewerProps<T = any, LC = typeof RNFlatList> {
    * @defaultValue 80
    */
   dismissThreshold?: number;
-  // swipeThreshold?: number;
-  // velocityThreshold?: number;
   /**
    * Calls `onDismiss` function when swiping down.
-   * @remark Useful for closing modals with downward swipe gestures.
+   * @remarks Useful for closing modals with downward swipe gestures.
    * @defaultValue true
    */
   enableDismissGesture?: boolean;
   /**
    * Controls left/right swipe gestures.
-   * @remark When `false`, horizontal gestures are disabled.
+   * @remarks When `false`, horizontal gestures are disabled.
    * @defaultValue true
    */
   enableSwipeGesture?: boolean;
@@ -95,7 +129,7 @@ export interface GestureViewerProps<T = any, LC = typeof RNFlatList> {
   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.
+   * @remarks The `listProps` provides **type inference based on the selected list component**, ensuring accurate autocompletion and type safety in your IDE.
    */
   listProps?: Partial<ConditionalListProps<LC>>;
   /**
@@ -108,25 +142,25 @@ export interface GestureViewerProps<T = any, LC = typeof RNFlatList> {
   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.
+   * @remarks When `false`, this animation is disabled.
    * @defaultValue true
    */
   animateBackdrop?: boolean;
   /**
    * Only works when zoom is active, allows moving item position when zoomed.
-   * @remark When `false`, gesture movement is disabled during zoom.
+   * @remarks When `false`, gesture movement is disabled during zoom.
    * @defaultValue true
    */
   enableZoomPanGesture?: boolean;
   /**
    * Controls two-finger pinch gestures.
-   * @remark When `false`, two-finger zoom gestures are disabled.
+   * @remarks When `false`, two-finger zoom gestures are disabled.
    * @defaultValue true
    */
   enableZoomGesture?: boolean;
   /**
    * Controls double-tap zoom gestures.
-   * @remark When `false`, double-tap zoom gestures are disabled.
+   * @remarks When `false`, double-tap zoom gestures are disabled.
    * @defaultValue true
    */
   enableDoubleTapGesture?: boolean;
@@ -142,10 +176,29 @@ export interface GestureViewerProps<T = any, LC = typeof RNFlatList> {
   maxZoomScale?: number;
   /**
    * The spacing between items in pixels.
-   * @remark Only applied when `useSnap` is `true`.
+   * @remarks Only applied when `useSnap` is `true`.
    * @defaultValue 0
    */
   itemSpacing?: number;
+  /**
+   * Trigger-based animation settings
+   * @remarks You can customize animation duration, easing, and system reduce-motion behavior.
+   *
+   * @example
+   * ```tsx
+   * <GestureViewer
+   *   triggerAnimation={{
+   *     duration: 250,
+   *     easing: Easing.out(Easing.cubic),
+   *     reduceMotion: 'system',
+   *     onAnimationComplete: () => {
+   *       console.log('Animation complete');
+   *     },
+   *   }}
+   * />
+   * ```
+   */
+  triggerAnimation?: TriggerAnimationConfig;
 }
 
 /**

package/src/useGestureViewer.ts

@@ -18,7 +18,7 @@ import {
 } from 'react-native-reanimated';
 import type GestureViewerManager from './GestureViewerManager';
 import { registry } from './GestureViewerRegistry';
-import type { GestureViewerProps } from './types';
+import type { GestureViewerProps, TriggerRect } from './types';
 import { createBoundsConstraint, createScrollAction, getLoopAdjustedIndex } from './utils';
 
 type UseGestureViewerProps<T = any> = Omit<
@@ -34,8 +34,6 @@ export const useGestureViewer = <T = any>({
   width: customWidth,
   dismissThreshold = 80,
   resistance = 2,
-  // swipeThreshold = 0.5,
-  // velocityThreshold = 200,
   animateBackdrop = true,
   enableDismissGesture = true,
   enableSwipeGesture = true,
@@ -47,6 +45,8 @@ export const useGestureViewer = <T = any>({
   itemSpacing = 0,
   useSnap = false,
   id = 'default',
+  onDismissStart,
+  triggerAnimation,
 }: UseGestureViewerProps<T>) => {
   const { width: screenWidth, height: screenHeight } = useWindowDimensions();
   const width = useSnap ? customWidth || screenWidth : screenWidth;
@@ -54,11 +54,14 @@ export const useGestureViewer = <T = any>({
   const [isZoomed, setIsZoomed] = useState(false);
   const [isRotated, setIsRotated] = useState(false);
   const [manager, setManager] = useState<GestureViewerManager | null>(null);
+  const [shouldStartTriggerAnimation, setShouldStartTriggerAnimation] = useState(false);
 
   const listRef = useRef<any>(null);
   const unsubscribeRef = useRef<(() => void) | null>(null);
   const onIndexChangeRef = useRef<((index: number) => void) | null>(null);
   const lastEmittedIndexRef = useRef<number>(null);
+  const triggerRectRef = useRef<TriggerRect | null>(null);
+  const onAnimationCompleteRef = useRef(triggerAnimation?.onAnimationComplete);
 
   const initialTranslateY = useSharedValue(0);
   const initialTranslateX = useSharedValue(0);
@@ -70,8 +73,22 @@ export const useGestureViewer = <T = any>({
   const backdropOpacity = useSharedValue(1);
   const rotation = useSharedValue(0);
 
+  const triggerScale = useSharedValue(1);
+  const triggerTranslateX = useSharedValue(0);
+  const triggerTranslateY = useSharedValue(0);
+  const triggerOpacity = useSharedValue(1);
+
   const dataLength = data?.length || 0;
 
+  const animationConfig = useMemo(
+    () => ({
+      duration: triggerAnimation?.duration ?? 300,
+      easing: triggerAnimation?.easing ?? Easing.bezier(0.25, 0.1, 0.25, 1.0),
+      reduceMotion: triggerAnimation?.reduceMotion,
+    }),
+    [triggerAnimation?.duration, triggerAnimation?.easing, triggerAnimation?.reduceMotion],
+  );
+
   const adjustedInitialIndex = useMemo(() => {
     if (enableLoop && data.length > 1) {
       return initialIndex + 1;
@@ -85,6 +102,10 @@ export const useGestureViewer = <T = any>({
     [width, screenHeight],
   );
 
+  const onAnimationComplete = useCallback(() => {
+    onAnimationCompleteRef.current?.();
+  }, []);
+
   const scrollTo = useCallback(
     (index: number, animated: boolean) => {
       const scrollAction = createScrollAction(listRef.current, width + itemSpacing);
@@ -140,6 +161,68 @@ export const useGestureViewer = <T = any>({
     };
   }, []);
 
+  useEffect(() => {
+    onAnimationCompleteRef.current = triggerAnimation?.onAnimationComplete;
+  }, [triggerAnimation?.onAnimationComplete]);
+
+  useEffect(() => {
+    if (shouldStartTriggerAnimation && triggerRectRef.current) {
+      const startX = triggerRectRef.current.x + triggerRectRef.current.width / 2 - screenWidth / 2;
+      const startY = triggerRectRef.current.y + triggerRectRef.current.height / 2 - screenHeight / 2;
+      const initialScaleFromTrigger = Math.min(
+        triggerRectRef.current.width / screenWidth,
+        triggerRectRef.current.height / screenHeight,
+      );
+
+      triggerScale.value = initialScaleFromTrigger;
+      triggerTranslateX.value = startX;
+      triggerTranslateY.value = startY;
+      triggerOpacity.value = 0;
+
+      triggerScale.value = withTiming(1, animationConfig, (finished) => {
+        if (finished) {
+          runOnJS(onAnimationComplete)();
+        }
+      });
+      triggerTranslateX.value = withTiming(0, animationConfig);
+      triggerTranslateY.value = withTiming(0, animationConfig);
+      triggerOpacity.value = withTiming(1, {
+        duration: animationConfig.duration / 2,
+        easing: animationConfig.easing,
+        reduceMotion: animationConfig.reduceMotion,
+      });
+
+      setShouldStartTriggerAnimation(false);
+    }
+  }, [
+    shouldStartTriggerAnimation,
+    animationConfig,
+    screenWidth,
+    screenHeight,
+    triggerOpacity,
+    triggerScale,
+    triggerTranslateX,
+    triggerTranslateY,
+    onAnimationComplete,
+  ]);
+
+  useEffect(() => {
+    const node = registry.getTriggerNode(id);
+
+    if (node && typeof node.measure === 'function') {
+      node.measure((_x, _y, width, height, pageX, pageY) => {
+        triggerRectRef.current = { x: pageX, y: pageY, width, height };
+        triggerOpacity.value = 0;
+        setShouldStartTriggerAnimation(true);
+        registry.clearTriggerNode(id);
+      });
+    }
+
+    return () => {
+      triggerRectRef.current = null;
+    };
+  }, [id, triggerOpacity]);
+
   useEffect(() => {
     const handleManagerChange = (manager: GestureViewerManager | null) => {
       unsubscribeRef.current?.();
@@ -227,6 +310,43 @@ export const useGestureViewer = <T = any>({
     };
   }, [adjustedInitialIndex, translateY, backdropOpacity, translateX, scale, startScale, rotation, scrollTo]);
 
+  const handleDismiss = useCallback(() => {
+    onDismissStart?.();
+
+    if (triggerRectRef.current) {
+      const endX = triggerRectRef.current.x + triggerRectRef.current.width / 2 - screenWidth / 2;
+      const endY = triggerRectRef.current.y + triggerRectRef.current.height / 2 - screenHeight / 2;
+      const endScale = Math.min(
+        triggerRectRef.current.width / screenWidth,
+        triggerRectRef.current.height / screenHeight,
+      );
+
+      triggerScale.value = withTiming(endScale, animationConfig);
+      triggerTranslateX.value = withTiming(endX, animationConfig);
+      triggerTranslateY.value = withTiming(endY, animationConfig);
+      triggerOpacity.value = withTiming(0, animationConfig, (finished) => {
+        if (finished && onDismiss) {
+          runOnJS(onDismiss)();
+        }
+      });
+      return;
+    }
+
+    if (onDismiss) {
+      runOnJS(onDismiss)();
+    }
+  }, [
+    animationConfig,
+    onDismiss,
+    onDismissStart,
+    screenWidth,
+    screenHeight,
+    triggerTranslateX,
+    triggerScale,
+    triggerTranslateY,
+    triggerOpacity,
+  ]);
+
   const onMomentumScrollEnd = useCallback(
     (event: NativeSyntheticEvent<NativeScrollEvent>) => {
       if (!enableSwipeGesture) {
@@ -248,7 +368,7 @@ export const useGestureViewer = <T = any>({
         scrollTo(jumpToIndex, false);
       }
 
-      const currentIndex = manager?.getState() ?? 0;
+      const currentIndex = manager?.getState().currentIndex;
 
       if (realIndex !== currentIndex && realIndex >= 0 && realIndex < dataLength) {
         if (manager) {
@@ -297,8 +417,8 @@ export const useGestureViewer = <T = any>({
         translateY.value = event.translationY / resistance;
       })
       .onEnd((event) => {
-        if (canDismiss && event.translationY > dismissThreshold && onDismiss) {
-          runOnJS(onDismiss)();
+        if (canDismiss && event.translationY > dismissThreshold && handleDismiss) {
+          runOnJS(handleDismiss)();
           return;
         }
 
@@ -307,7 +427,7 @@ export const useGestureViewer = <T = any>({
           stiffness: 150,
         });
       });
-  }, [translateY, dismissThreshold, enableDismissGesture, onDismiss, resistance, isZoomed]);
+  }, [translateY, dismissThreshold, enableDismissGesture, handleDismiss, resistance, isZoomed]);
 
   const zoomPinchGesture = useMemo(() => {
     return Gesture.Pinch()
@@ -478,7 +598,12 @@ export const useGestureViewer = <T = any>({
 
   const animatedStyle = useAnimatedStyle(() => {
     return {
+      opacity: triggerOpacity.value,
       transform: [
+        { translateX: triggerTranslateX.value },
+        { translateY: triggerTranslateY.value },
+        { scale: triggerScale.value },
+
         { translateY: translateY.value },
         { translateX: translateX.value },
         { scale: scale.value },
@@ -488,13 +613,15 @@ export const useGestureViewer = <T = any>({
   });
 
   const backdropStyle = useAnimatedStyle(() => {
+    const baseOpacity = triggerOpacity.value;
+
     if (!animateBackdrop || scale.value !== 1) {
-      return { opacity: 1 };
+      return { opacity: baseOpacity };
     }
 
-    const opacity = interpolate(translateY.value, [0, 200], [1, 0], 'clamp');
+    const dismissOpacity = interpolate(translateY.value, [0, 200], [1, 0], 'clamp');
 
-    return { opacity };
+    return { opacity: dismissOpacity * baseOpacity };
   }, [animateBackdrop]);
 
   const onScrollBeginDrag = useCallback(() => {
@@ -503,7 +630,6 @@ export const useGestureViewer = <T = any>({
 
   return {
     dataLength,
-    translateY,
     listRef,
     isZoomed,
     isRotated,
@@ -512,6 +638,7 @@ export const useGestureViewer = <T = any>({
 
     onMomentumScrollEnd,
     onScrollBeginDrag,
+    handleDismiss,
 
     animatedStyle,
     backdropStyle,