react-native-gesture-image-viewer 1.4.0 → 1.5.0

package/src/types.ts

@@ -17,7 +17,7 @@ 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'
+   * @defaultValue 'default'
    */
   id?: string;
   /**
@@ -26,7 +26,7 @@ export interface GestureViewerProps<T = any, LC = typeof RNFlatList> {
   data: T[];
   /**
    * The index of the item to display in the `GestureViewer` when the component is mounted.
-   * @default 0
+   * @defaultValue 0
    */
   initialIndex?: number;
   /**
@@ -52,7 +52,7 @@ export interface GestureViewerProps<T = any, LC = typeof RNFlatList> {
   /**
    * 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
+   * @defaultValue screen width
    */
   width?: number;
   /**
@@ -65,13 +65,13 @@ export interface GestureViewerProps<T = any, LC = typeof RNFlatList> {
    * **`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
+   * @defaultValue false
    *
    */
   useSnap?: boolean;
   /**
    * `dismissThreshold` controls when `onDismiss` is called by applying a threshold value during vertical gestures.
-   * @default 80
+   * @defaultValue 80
    */
   dismissThreshold?: number;
   // swipeThreshold?: number;
@@ -79,18 +79,18 @@ export interface GestureViewerProps<T = any, LC = typeof RNFlatList> {
   /**
    * Calls `onDismiss` function when swiping down.
    * @remark Useful for closing modals with downward swipe gestures.
-   * @default true
+   * @defaultValue true
    */
   enableDismissGesture?: boolean;
   /**
    * Controls left/right swipe gestures.
    * @remark When `false`, horizontal gestures are disabled.
-   * @default true
+   * @defaultValue true
    */
   enableSwipeGesture?: boolean;
   /**
    * `resistance` controls the range of vertical movement by applying resistance during vertical gestures.
-   * @default 2
+   * @defaultValue 2
    */
   resistance?: number;
   /**
@@ -109,36 +109,184 @@ export interface GestureViewerProps<T = any, LC = typeof RNFlatList> {
   /**
    * By default, the background `opacity` gradually decreases from 1 to 0 during downward swipe gestures.
    * @remark When `false`, this animation is disabled.
-   * @default true
+   * @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.
-   * @default true
+   * @defaultValue true
    */
   enableZoomPanGesture?: boolean;
   /**
    * Controls two-finger pinch gestures.
    * @remark When `false`, two-finger zoom gestures are disabled.
-   * @default true
+   * @defaultValue true
    */
   enableZoomGesture?: boolean;
   /**
    * Controls double-tap zoom gestures.
    * @remark When `false`, double-tap zoom gestures are disabled.
-   * @default true
+   * @defaultValue true
    */
   enableDoubleTapGesture?: boolean;
   /**
    * The maximum zoom scale.
-   * @default 2
+   * @defaultValue 2
    */
   maxZoomScale?: number;
   /**
    * The spacing between items in pixels.
    * @remark Only applied when `useSnap` is `true`.
-   * @default 0
+   * @defaultValue 0
    */
   itemSpacing?: number;
 }
+
+/**
+ * Supported rotation angles in degrees.
+ */
+export type RotationAngle = 0 | 90 | 180 | 270 | 360;
+
+/**
+ * Controller for managing gesture-based image/content viewer interactions.
+ * Provides navigation, zoom, and rotation capabilities with state management.
+ */
+export type GestureViewerController = {
+  /**
+   * Navigates to the specified index in the viewer.
+   * Updates the currentIndex in the controller state.
+   *
+   * @param index - The target index (must be between 0 and totalCount - 1)
+   * @throws Will throw an error if index is out of bounds
+   *
+   * @example
+   * ```typescript
+   * controller.goToIndex(0); // Go to first item
+   * controller.goToIndex(controller.totalCount - 1); // Go to last item
+   * ```
+   */
+  goToIndex: (index: number) => void;
+
+  /**
+   * Navigates to the previous item in the sequence.
+   * If already at the first item, behavior depends on implementation (may wrap or do nothing).
+   * Updates currentIndex in the controller state.
+   */
+  goToPrevious: () => void;
+
+  /**
+   * Navigates to the next item in the sequence.
+   * If already at the last item, behavior depends on implementation (may wrap or do nothing).
+   * Updates currentIndex in the controller state.
+   */
+  goToNext: () => void;
+
+  /**
+   * Zooms in by the specified multiplier.
+   *
+   * @param multiplier - The zoom multiplier (0.01 - 1.0). Higher values zoom in more.
+   * @defaultValue 0.25
+   *
+   * @example
+   * ```typescript
+   * controller.zoomIn(); // Zoom in by 25%
+   * controller.zoomIn(0.5); // Zoom in by 50%
+   * ```
+   */
+  zoomIn: (multiplier?: number) => void;
+
+  /**
+   * Zooms out by the specified multiplier.
+   *
+   * @param multiplier - The zoom multiplier (0.01 - 1.0). Higher values zoom out more.
+   * @defaultValue 0.25
+   *
+   * @example
+   * ```typescript
+   * controller.zoomOut(); // Zoom out by 25%
+   * controller.zoomOut(0.1); // Zoom out by 10%
+   * ```
+   */
+  zoomOut: (multiplier?: number) => void;
+
+  /**
+   * Resets the zoom level to the specified scale.
+   *
+   * @param scale - The scale to reset to (1.0 = original size)
+   * @defaultValue 1.0
+   *
+   * @example
+   * ```typescript
+   * controller.resetZoom(); // Reset to original size
+   * controller.resetZoom(0.5); // Reset to 50% of original size
+   * ```
+   */
+  resetZoom: (scale?: number) => void;
+
+  /**
+   * Rotates the content by the specified angle.
+   *
+   * @param angle - Rotation angle in degrees. Must be one of: 0, 90, 180, 270, 360
+   * @param clockwise - Direction of rotation when angle is not 0 or 360
+   * @defaultValue angle: `90`, clockwise: `true`
+   *
+   * @remarks
+   * - Angle 0 or 360 resets rotation regardless of clockwise parameter
+   * - The clockwise parameter only affects rotation when angle is 90, 180, or 270
+   * - Rotation is cumulative and affects the current orientation
+   *
+   * @example
+   * ```typescript
+   * controller.rotate(); // Rotate 90 degrees clockwise
+   * controller.rotate(0); // Reset rotation
+   * controller.rotate(90, false); // Rotate 90 degrees counter-clockwise
+   * controller.rotate(180); // Rotate 180 degrees (clockwise by default)
+   * controller.rotate(270, false); // Rotate 270 degrees counter-clockwise
+   * controller.rotate(360); // Reset rotation (same as 0)
+   * ```
+   */
+  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 = {
+  /**
+   * The current index of the active item in the viewer.
+   *
+   * @remarks
+   * This value is automatically updated when navigation methods are called.
+   *
+   * @example
+   * ```typescript
+   * console.log(`Currently viewing item ${controller.currentIndex + 1} of ${controller.totalCount}`);
+   * ```
+   */
+  readonly currentIndex: number;
+
+  /**
+   * The total number of items available in the viewer.
+   *
+   * @remarks
+   * This value determines the valid range for currentIndex (0 to totalCount - 1).
+   *
+   * @example
+   * ```typescript
+   * const hasNext = controller.currentIndex < controller.totalCount - 1;
+   * const hasPrevious = controller.currentIndex > 0;
+   * ```
+   */
+  readonly totalCount: number;
+};
+
+export type GestureViewerEventType = 'zoomChange' | 'rotationChange';
+
+export type GestureViewerEventData = {
+  zoomChange: { scale: number; previousScale: number | null };
+  rotationChange: { rotation: number; previousRotation: number | null };
+};
+
+export type GestureViewerEventCallback<T extends GestureViewerEventType> = (data: GestureViewerEventData[T]) => void;

package/src/useGestureViewer.ts

@@ -76,16 +76,38 @@ export const useGestureViewer = <T = any>({
     [width, screenHeight],
   );
 
+  const emitZoomChange = useCallback(
+    (currentScale: number, prevScale: number | null) => {
+      manager?.emitZoomChange(currentScale, prevScale);
+    },
+    [manager],
+  );
+
+  const emitRotationChange = useCallback(
+    (currentRotation: number, prevRotation: number | null) => {
+      manager?.emitRotationChange(currentRotation, prevRotation);
+    },
+    [manager],
+  );
+
   useAnimatedReaction(
     () => scale.value,
-    (currentScale) => {
+    (currentScale, previousScale) => {
+      if (manager && currentScale !== previousScale) {
+        runOnJS(emitZoomChange)(currentScale, previousScale);
+      }
+
       runOnJS(setIsZoomed)(currentScale > 1);
     },
   );
 
   useAnimatedReaction(
     () => rotation.value,
-    (currentRotation) => {
+    (currentRotation, previousRotation) => {
+      if (manager && currentRotation !== previousRotation) {
+        runOnJS(emitRotationChange)(currentRotation, previousRotation);
+      }
+
       runOnJS(setIsRotated)(currentRotation % 360 !== 0);
     },
   );

package/src/useGestureViewerController.ts

@@ -1,12 +1,64 @@
 import { useEffect, useMemo, useRef, useState } from 'react';
 import type GestureViewerManager from './GestureViewerManager';
-import type { GestureViewerManagerState } from './GestureViewerManager';
 import { registry } from './GestureViewerRegistry';
+import type { GestureViewerController, GestureViewerControllerState } from './types';
 
-export const useGestureViewerController = (id = 'default') => {
-  const [state, setState] = useState<GestureViewerManagerState>({
+/**
+ * Hook to control the gesture viewer programmatically.
+ *
+ * @param id - Viewer instance identifier (default: 'default')
+ * @returns Methods and state for controlling the viewer
+ *
+ * **Available methods:**
+ * - `goToIndex(index: number)` - Navigate to specific index (0 to totalCount-1)
+ * - `goToPrevious()` - Navigate to previous item
+ * - `goToNext()` - Navigate to next item
+ * - `zoomIn(multiplier?: number)` - Zoom in (default: 0.25)
+ * - `zoomOut(multiplier?: number)` - Zoom out (default: 0.25)
+ * - `resetZoom(scale?: number)` - Reset zoom level (default: 1.0)
+ * - `rotate(angle?: 0|90|180|270|360, clockwise?: boolean)` - Rotate content (default: 90° clockwise)
+ *
+ * **Available state:**
+ * - `currentIndex: number` - Current active index (read-only)
+ * - `totalCount: number` - Total number of items (read-only)
+ *
+ * @example
+ * ```tsx
+ * const { goToIndex, goToNext, goToPrevious, zoomIn, zoomOut, resetZoom, rotate, currentIndex, totalCount } = useGestureViewerController();
+ *
+ * // Navigate to specific index
+ * goToIndex(2);
+ *
+ * // Go to next image
+ * goToNext();
+ *
+ * // Zoom in by 25%
+ * zoomIn();
+ *
+ * // Zoom out by 50%
+ * zoomOut(0.5);
+ *
+ * // Reset to original size
+ * resetZoom();
+ *
+ * // Rotate 90 degrees clockwise
+ * rotate();
+ *
+ * // Rotate 180 degrees
+ * rotate(180);
+ *
+ * // Check current state
+ * console.log(`Image ${currentIndex + 1} of ${totalCount}`);
+ *
+ * // Check navigation availability
+ * const canGoNext = currentIndex < totalCount - 1;
+ * const canGoPrevious = currentIndex > 0;
+ * ```
+ */
+export const useGestureViewerController = (id = 'default'): GestureViewerController => {
+  const [state, setState] = useState<GestureViewerControllerState>({
     currentIndex: 0,
-    dataLength: 0,
+    totalCount: 0,
   });
 
   const [manager, setManager] = useState<GestureViewerManager | null>(null);
@@ -25,7 +77,7 @@ export const useGestureViewerController = (id = 'default') => {
         return;
       }
 
-      setState({ currentIndex: 0, dataLength: 0 });
+      setState({ currentIndex: 0, totalCount: 0 });
     };
 
     const unsubscribeFromRegistry = registry.subscribeToManager(id, handleManagerChange);
@@ -46,7 +98,6 @@ export const useGestureViewerController = (id = 'default') => {
     zoomOut: manager?.zoomOut || noopFunction,
     resetZoom: manager?.resetZoom || noopFunction,
     rotate: manager?.rotate || noopFunction,
-    currentIndex: state.currentIndex,
-    totalCount: state.dataLength,
+    ...state,
   };
 };

package/src/useGestureViewerEvent.ts

@@ -0,0 +1,96 @@
+import { useEffect } from 'react';
+import type GestureViewerManager from './GestureViewerManager';
+import { registry } from './GestureViewerRegistry';
+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
+ * throttled to prevent excessive callback invocations during gestures.
+ *
+ * @param eventType - The type of event to listen for
+ * @param callback - Function to call when the event occurs
+ *
+ * @example
+ * ```tsx
+ * // Listen to zoom changes on the default instance (ID: 'default')
+ * useGestureViewerEvent('zoomChange', (data) => {
+ *   console.log(`Zoom changed from ${data.previousScale} to ${data.scale}`);
+ * });
+ *
+ * // Listen to rotation changes on the default instance (ID: 'default')
+ * useGestureViewerEvent('rotationChange', (data) => {
+ *   console.log(`Rotation changed from ${data.previousRotation}° to ${data.rotation}°`);
+ * });
+ * ```
+ */
+export function useGestureViewerEvent<T extends GestureViewerEventType>(
+  eventType: T,
+  callback: GestureViewerEventCallback<T>,
+): void;
+
+/**
+ * Hook for subscribing to GestureViewer events with a specific instance ID.
+ *
+ * Use this overload when you have multiple GestureViewer instances and need
+ * to listen to events from a specific one.
+ *
+ * @param id - The unique identifier of the GestureViewer instance
+ * @param eventType - The type of event to listen for
+ * @param callback - Function to call when the event occurs
+ *
+ * @example
+ * ```tsx
+ * // Listen to zoom changes on a specific instance
+ * useGestureViewerEvent('gallery', 'zoomChange', (data) => {
+ *   console.log(`Gallery zoom: ${data.scale}x`);
+ * });
+ *
+ * // Listen to rotation changes on a modal viewer
+ * useGestureViewerEvent('modal-viewer', 'rotationChange', (data) => {
+ *   updateRotationIndicator(data.rotation);
+ * });
+ * ```
+ */
+export function useGestureViewerEvent<T extends GestureViewerEventType>(
+  id: string,
+  eventType: T,
+  callback: GestureViewerEventCallback<T>,
+): void;
+
+/**
+ * Implementation of the useGestureViewerEvent hook.
+ *
+ * @internal
+ */
+export function useGestureViewerEvent<T extends GestureViewerEventType>(
+  idOrEventType: string | T,
+  eventTypeOrCallback: T | GestureViewerEventCallback<T>,
+  callback?: GestureViewerEventCallback<T>,
+) {
+  const id = typeof idOrEventType === 'string' && callback ? idOrEventType : 'default';
+  const eventType = typeof idOrEventType === 'string' && callback ? (eventTypeOrCallback as T) : (idOrEventType as T);
+  const finalCallback = callback || (eventTypeOrCallback as GestureViewerEventCallback<T>);
+
+  useEffect(() => {
+    let unsubscribeFromManager: (() => void) | null = null;
+
+    const handleManagerChange = (manager: GestureViewerManager | null) => {
+      unsubscribeFromManager?.();
+      unsubscribeFromManager = null;
+
+      if (manager) {
+        unsubscribeFromManager = manager.addEventListener(eventType, finalCallback);
+      }
+    };
+
+    const unsubscribeFromRegistry = registry.subscribeToManager(id, handleManagerChange);
+
+    return () => {
+      unsubscribeFromRegistry();
+      unsubscribeFromManager?.();
+    };
+  }, [id, eventType, finalCallback]);
+}