react-native-gesture-image-viewer 2.0.0-beta.3 → 2.0.0-beta.5

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,7 +14,31 @@ type ConditionalListProps<LC> = LC extends FlatListComponent
     ? React.ComponentProps<LC>
     : GetComponentProps<LC>;
 
-export interface GestureViewerProps<T = any, LC = typeof RNFlatList> {
+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.
@@ -29,22 +54,29 @@ export interface GestureViewerProps<T = any, LC = typeof RNFlatList> {
    * @defaultValue 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 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.
    */
@@ -55,44 +87,6 @@ export interface GestureViewerProps<T = any, LC = typeof RNFlatList> {
    * @defaultValue 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
-   * @defaultValue false
-   *
-   */
-  useSnap?: boolean;
-  /**
-   * `dismissThreshold` controls when `onDismiss` is called by applying a threshold value during vertical gestures.
-   * @defaultValue 80
-   */
-  dismissThreshold?: number;
-  // swipeThreshold?: number;
-  // velocityThreshold?: number;
-  /**
-   * Calls `onDismiss` function when swiping down.
-   * @remark Useful for closing modals with downward swipe gestures.
-   * @defaultValue true
-   */
-  enableDismissGesture?: boolean;
-  /**
-   * Controls left/right swipe gestures.
-   * @remark When `false`, horizontal gestures are disabled.
-   * @defaultValue true
-   */
-  enableSwipeGesture?: boolean;
-  /**
-   * `resistance` controls the range of vertical movement by applying resistance during vertical gestures.
-   * @defaultValue 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.
@@ -107,45 +101,105 @@ 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.
+   * Dismiss gesture options. Calls `onDismiss` function when swiping down.
+   * @remark Useful for closing modals with downward swipe gestures.
+   */
+  dismiss?: {
+    /**
+     * When `false`, dismiss gesture is disabled.
+     * @defaultValue true
+     */
+    enabled?: boolean;
+    /**
+     * `threshold` controls when `onDismiss` is called by applying a threshold value during vertical gestures.
+     * @defaultValue 80
+     */
+    threshold?: number;
+    /**
+     * `resistance` controls the range of vertical movement by applying resistance during dismiss gestures.
+     * @defaultValue 2
+     */
+    resistance?: number;
+    /**
+     * By default, the background `opacity` gradually decreases from 1 to 0 during downward swipe gestures.
+     * @remark When `false`, this animation is disabled.
+     * @defaultValue true
+     */
+    fadeBackdrop?: boolean;
+  };
+  /**
+   * Controls left/right swipe gestures.
+   * @remark When `false`, horizontal gestures are disabled.
    * @defaultValue true
    */
-  animateBackdrop?: boolean;
+  enableHorizontalSwipe?: boolean;
   /**
    * Only works when zoom is active, allows moving item position when zoomed.
    * @remark When `false`, gesture movement is disabled during zoom.
    * @defaultValue true
    */
-  enableZoomPanGesture?: boolean;
+  enablePanWhenZoomed?: boolean;
   /**
    * Controls two-finger pinch gestures.
    * @remark When `false`, two-finger zoom gestures are disabled.
    * @defaultValue true
    */
-  enableZoomGesture?: boolean;
+  enablePinchZoom?: boolean;
   /**
    * Controls double-tap zoom gestures.
    * @remark When `false`, double-tap zoom gestures are disabled.
    * @defaultValue true
    */
-  enableDoubleTapGesture?: boolean;
+  enableDoubleTapZoom?: boolean;
   /**
    * Enables infinite loop navigation.
    * @defaultValue false
    */
   enableLoop?: boolean;
   /**
-   * The maximum zoom scale.
-   * @defaultValue 2
+   * 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
+   * @defaultValue false
+   *
    */
-  maxZoomScale?: number;
+  enableSnapMode?: boolean;
   /**
    * The spacing between items in pixels.
-   * @remark Only applied when `useSnap` is `true`.
+   * @remark Only applied when `enableSnapMode` is `true`.
    * @defaultValue 0
    */
   itemSpacing?: number;
+  /**
+   * The maximum zoom scale.
+   * @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;
 }
 
 /**
@@ -167,8 +221,10 @@ export type GestureViewerController = {
    *
    * @example
    * ```typescript
+   * const { totalCount } = useGestureViewerState();
+   *
    * controller.goToIndex(0); // Go to first item
-   * controller.goToIndex(controller.totalCount - 1); // Go to last item
+   * controller.goToIndex(totalCount - 1); // Go to last item
    * ```
    */
   goToIndex: (index: number) => void;
@@ -252,13 +308,13 @@ export type GestureViewerController = {
    * ```
    */
   rotate: (angle?: RotationAngle, clockwise?: boolean) => void;
-} & GestureViewerControllerState;
+};
 
 /**
  * State information for the gesture viewer controller.
  * Contains read-only properties that reflect the current state.
  */
-export type GestureViewerControllerState = {
+export type GestureViewerState = {
   /**
    * The current index of the active item in the viewer.
    *
@@ -267,7 +323,7 @@ export type GestureViewerControllerState = {
    *
    * @example
    * ```typescript
-   * console.log(`Currently viewing item ${controller.currentIndex + 1} of ${controller.totalCount}`);
+   * console.log(`Currently viewing item ${currentIndex + 1} of ${totalCount}`);
    * ```
    */
   readonly currentIndex: number;
@@ -280,8 +336,8 @@ export type GestureViewerControllerState = {
    *
    * @example
    * ```typescript
-   * const hasNext = controller.currentIndex < controller.totalCount - 1;
-   * const hasPrevious = controller.currentIndex > 0;
+   * const hasNext = currentIndex < totalCount - 1;
+   * const hasPrevious = currentIndex > 0;
    * ```
    */
   readonly totalCount: number;