react-native-gesture-image-viewer 2.0.0-beta.4 → 2.0.0-beta.6

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 RNScrollView> {
   /**
    * 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;
@@ -33,27 +58,38 @@ export interface GestureViewerProps<T = any, LC = typeof RNScrollView> {
    * 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;
   /**
    * 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>>;
   /**
@@ -66,7 +102,7 @@ export interface GestureViewerProps<T = any, LC = typeof RNScrollView> {
   containerStyle?: StyleProp<ViewStyle>;
   /**
    * Dismiss gesture options. Calls `onDismiss` function when swiping down.
-   * @remark Useful for closing modals with downward swipe gestures.
+   * @remarks Useful for closing modals with downward swipe gestures.
    */
   dismiss?: {
     /**
@@ -86,32 +122,32 @@ export interface GestureViewerProps<T = any, LC = typeof RNScrollView> {
     resistance?: number;
     /**
      * 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
      */
     fadeBackdrop?: boolean;
   };
   /**
    * Controls left/right swipe gestures.
-   * @remark When `false`, horizontal gestures are disabled.
+   * @remarks When `false`, horizontal gestures are disabled.
    * @defaultValue true
    */
   enableHorizontalSwipe?: 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
    */
   enablePanWhenZoomed?: 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
    */
   enablePinchZoom?: 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
    */
   enableDoubleTapZoom?: boolean;
@@ -123,7 +159,7 @@ export interface GestureViewerProps<T = any, LC = typeof RNScrollView> {
   /**
    * Enables snap scrolling mode.
    *
-   * @remark
+   * @remarks
    * **`false` (default)**: Paging mode (`pagingEnabled: true`)
    * - Scrolls by full screen size increments
    *
@@ -136,7 +172,7 @@ export interface GestureViewerProps<T = any, LC = typeof RNScrollView> {
   enableSnapMode?: boolean;
   /**
    * The spacing between items in pixels.
-   * @remark Only applied when `enableSnapMode` is `true`.
+   * @remarks Only applied when `enableSnapMode` is `true`.
    * @defaultValue 0
    */
   itemSpacing?: number;
@@ -145,6 +181,25 @@ export interface GestureViewerProps<T = any, LC = typeof RNScrollView> {
    * @defaultValue 2
    */
   maxZoomScale?: 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 {
 import { runOnJS } from 'react-native-worklets';
 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<
@@ -41,15 +41,20 @@ export const useGestureViewer = <T = any>({
   itemSpacing = 0,
   enableSnapMode = false,
   id = 'default',
+  onDismissStart,
+  triggerAnimation,
 }: UseGestureViewerProps<T>) => {
   const { width: screenWidth, height: screenHeight } = useWindowDimensions();
   const width = enableSnapMode ? customWidth || screenWidth : screenWidth;
 
   const [isZoomed, setIsZoomed] = useState(false);
   const [isRotated, setIsRotated] = useState(false);
+  const [shouldStartTriggerAnimation, setShouldStartTriggerAnimation] = useState(false);
   const [manager, setManager] = useState<GestureViewerManager | null>(null);
 
   const listRef = useRef<any>(null);
+  const triggerRectRef = useRef<TriggerRect | null>(null);
+  const onAnimationCompleteRef = useRef(triggerAnimation?.onAnimationComplete);
 
   const initialTranslateY = useSharedValue(0);
   const initialTranslateX = useSharedValue(0);
@@ -61,8 +66,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 dismissOptions = useMemo(() => {
     return {
       enabled: dismiss?.enabled ?? true,
@@ -112,6 +131,10 @@ export const useGestureViewer = <T = any>({
     [manager],
   );
 
+  const onAnimationComplete = useCallback(() => {
+    onAnimationCompleteRef.current?.();
+  }, []);
+
   useAnimatedReaction(
     () => scale.value,
     (currentScale, previousScale) => {
@@ -199,6 +222,105 @@ export const useGestureViewer = <T = any>({
     };
   }, [adjustedInitialIndex, translateY, backdropOpacity, translateX, scale, startScale, rotation, scrollTo]);
 
+  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]);
+
+  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 (!enableHorizontalSwipe) {
@@ -220,7 +342,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) {
@@ -256,19 +378,21 @@ export const useGestureViewer = <T = any>({
   );
 
   const dismissGesture = useMemo(() => {
+    const canDismiss = !isZoomed && dismissOptions.enabled;
+
     return Gesture.Pan()
       .minDistance(10)
       .averageTouches(true)
       .activeCursor('grabbing')
       .activeOffsetY([-10, 10])
       .failOffsetX([-10, 10])
-      .enabled(!isZoomed)
+      .enabled(canDismiss)
       .onUpdate((event) => {
         translateY.value = event.translationY / dismissOptions.resistance;
       })
       .onEnd((event) => {
-        if (event.translationY > dismissOptions.threshold && dismissOptions.enabled && onDismiss) {
-          runOnJS(onDismiss)();
+        if (canDismiss && event.translationY > dismissOptions.threshold) {
+          runOnJS(handleDismiss)();
           return;
         }
 
@@ -280,7 +404,7 @@ export const useGestureViewer = <T = any>({
           energyThreshold: 6e-9,
         });
       });
-  }, [translateY, dismissOptions.threshold, dismissOptions.enabled, onDismiss, dismissOptions.resistance, isZoomed]);
+  }, [translateY, dismissOptions, handleDismiss, isZoomed]);
 
   const zoomPinchGesture = useMemo(() => {
     return Gesture.Pinch()
@@ -451,7 +575,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 },
@@ -461,13 +590,15 @@ export const useGestureViewer = <T = any>({
   });
 
   const backdropStyle = useAnimatedStyle(() => {
+    const baseOpacity = triggerOpacity.value;
+
     if (!dismissOptions.fadeBackdrop || 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: baseOpacity * dismissOpacity };
   }, [dismissOptions.fadeBackdrop]);
 
   const onScrollBeginDrag = useCallback(() => {
@@ -476,7 +607,6 @@ export const useGestureViewer = <T = any>({
 
   return {
     dataLength,
-    translateY,
     listRef,
     isZoomed,
     isRotated,
@@ -485,6 +615,7 @@ export const useGestureViewer = <T = any>({
 
     onMomentumScrollEnd,
     onScrollBeginDrag,
+    handleDismiss,
 
     animatedStyle,
     backdropStyle,