react-native-gesture-image-viewer 1.3.0 → 1.4.1

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,175 @@ 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;
+};

package/src/useGestureViewer.ts

@@ -51,7 +51,7 @@ export const useGestureViewer = <T = any>({
   const width = useSnap ? customWidth || screenWidth : screenWidth;
 
   const [isZoomed, setIsZoomed] = useState(false);
-
+  const [isRotated, setIsRotated] = useState(false);
   const [currentIndex, setCurrentIndex] = useState(initialIndex);
   const [manager, setManager] = useState<GestureViewerManager | null>(null);
 
@@ -65,6 +65,7 @@ export const useGestureViewer = <T = any>({
   const translateX = useSharedValue(0);
   const scale = useSharedValue(1);
   const backdropOpacity = useSharedValue(1);
+  const rotation = useSharedValue(0);
 
   const listRef = useRef<any>(null);
 
@@ -82,6 +83,13 @@ export const useGestureViewer = <T = any>({
     },
   );
 
+  useAnimatedReaction(
+    () => rotation.value,
+    (currentRotation) => {
+      runOnJS(setIsRotated)(currentRotation % 360 !== 0);
+    },
+  );
+
   useEffect(() => {
     const handleManagerChange = (manager: GestureViewerManager | null) => {
       unsubscribeRef.current?.();
@@ -119,6 +127,7 @@ export const useGestureViewer = <T = any>({
     manager.setWidth(width + itemSpacing);
     manager.setHeight(screenHeight);
     manager.setZoomSharedValues(scale, translateX, translateY, maxZoomScale);
+    manager.setRotation(rotation);
     manager.notifyStateChange();
   }, [
     dataLength,
@@ -132,6 +141,7 @@ export const useGestureViewer = <T = any>({
     screenHeight,
     translateX,
     translateY,
+    rotation,
   ]);
 
   useEffect(() => {
@@ -152,6 +162,7 @@ export const useGestureViewer = <T = any>({
     scale.value = 1;
     backdropOpacity.value = 1;
     startScale.value = 1;
+    rotation.value = 0;
 
     if (initialIndex <= 0 || !listRef.current) {
       return;
@@ -174,7 +185,7 @@ export const useGestureViewer = <T = any>({
     return () => {
       runAfterInteractions?.cancel();
     };
-  }, [initialIndex, translateY, backdropOpacity, translateX, scale, startScale, width, itemSpacing]);
+  }, [initialIndex, translateY, backdropOpacity, translateX, scale, startScale, width, itemSpacing, rotation]);
 
   const onMomentumScrollEnd = useCallback(
     (event: NativeSyntheticEvent<NativeScrollEvent>) => {
@@ -198,6 +209,7 @@ export const useGestureViewer = <T = any>({
         initialTranslateY.value = withTiming(0);
         startScale.value = withTiming(1);
         scale.value = withTiming(1);
+        rotation.value = 0;
       }
     },
     [
@@ -213,6 +225,7 @@ export const useGestureViewer = <T = any>({
       initialTranslateX,
       initialTranslateY,
       startScale,
+      rotation,
     ],
   );
 
@@ -409,7 +422,12 @@ export const useGestureViewer = <T = any>({
 
   const animatedStyle = useAnimatedStyle(() => {
     return {
-      transform: [{ translateY: translateY.value }, { translateX: translateX.value }, { scale: scale.value }],
+      transform: [
+        { translateY: translateY.value },
+        { translateX: translateX.value },
+        { scale: scale.value },
+        { rotate: `${rotation.value}deg` },
+      ],
     };
   });
 
@@ -429,7 +447,7 @@ export const useGestureViewer = <T = any>({
     translateY,
     listRef,
     isZoomed,
-
+    isRotated,
     dismissGesture,
     zoomGesture,
 

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);
@@ -45,7 +97,7 @@ export const useGestureViewerController = (id = 'default') => {
     zoomIn: manager?.zoomIn || noopFunction,
     zoomOut: manager?.zoomOut || noopFunction,
     resetZoom: manager?.resetZoom || noopFunction,
-    currentIndex: state.currentIndex,
-    totalCount: state.dataLength,
+    rotate: manager?.rotate || noopFunction,
+    ...state,
   };
 };