feat: add GestureViewerController types and enhance TSDoc documentation (#43)

- Add GestureViewerController type definition
- Mark state properties as readonly for immutability
- Enhance TSDoc with comprehensive parameter descriptions and examples
- Improve useGestureViewerController hook docs for destructuring usage

Author: saseungmin

.changeset/brown-ways-share.md

@@ -0,0 +1,10 @@
+---
+"react-native-gesture-image-viewer": patch
+---
+
+feat: add GestureViewerController types and enhance TSDoc documentation
+
+- Add GestureViewerController type definition
+- Mark state properties as readonly for immutability
+- Enhance TSDoc with comprehensive parameter descriptions and examples
+- Improve useGestureViewerController hook docs for destructuring usage

src/GestureViewerManager.ts

@@ -1,11 +1,7 @@
 import { type SharedValue, withTiming } from 'react-native-reanimated';
+import type { GestureViewerControllerState } from './types';
 import { createBoundsConstraint } from './utils';
 
-export type GestureViewerManagerState = {
-  currentIndex: number;
-  dataLength: number;
-};
-
 class GestureViewerManager {
   private currentIndex = 0;
   private dataLength = 0;
@@ -17,7 +13,7 @@ class GestureViewerManager {
   private maxZoomScale = 2;
   private listRef: any | null = null;
   private enableSwipeGesture = true;
-  private listeners = new Set<(state: GestureViewerManagerState) => void>();
+  private listeners = new Set<(state: GestureViewerControllerState) => void>();
   private rotation: SharedValue<number> | null = null;
 
   private notifyListeners() {
@@ -26,7 +22,7 @@ class GestureViewerManager {
     this.listeners.forEach((listener) => listener(state));
   }
 
-  subscribe(listener: (state: GestureViewerManagerState) => void) {
+  subscribe(listener: (state: GestureViewerControllerState) => void) {
     this.listeners.add(listener);
 
     return () => {
@@ -37,7 +33,7 @@ class GestureViewerManager {
   getState() {
     return {
       currentIndex: this.currentIndex,
-      dataLength: this.dataLength,
+      totalCount: this.dataLength,
     };
   }
 
@@ -87,20 +83,6 @@ class GestureViewerManager {
     this.rotation = rotation;
   }
 
-  /**
-   * @param angle - The angle to rotate.
-   * @default 90 (0, 90, 180, 270, 360)
-   * @param clockwise - The direction to rotate.
-   * @default true (clockwise)
-   *
-   * @example
-   * rotate(0) // reset rotation
-   * rotate(number, false) // rotate {number} degrees counter-clockwise
-   * rotate(90) // rotate 90 degrees clockwise
-   * rotate(180) // rotate 180 degrees clockwise
-   * rotate(270) // rotate 270 degrees clockwise
-   * rotate(360) // rotate 360 degrees clockwise
-   */
   rotate = (angle: 0 | 90 | 180 | 270 | 360 = 90, clockwise = true) => {
     const MAX_ANGLE = 360;
 
@@ -130,11 +112,6 @@ class GestureViewerManager {
     this.rotation.value = withTiming(nextAngle);
   };
 
-  /**
-   * @param multiplier - The multiplier to zoom in.
-   * @range 0.01 - 1
-   * @default 0.25
-   */
   zoomIn = (multiplier = 0.25) => {
     if (!this.scale || !this.translateX || !this.translateY || multiplier < 0.01 || multiplier > 1) {
       return;
@@ -157,11 +134,6 @@ class GestureViewerManager {
     this.translateY.value = withTiming(translateY);
   };
 
-  /**
-   * @param multiplier - The multiplier to zoom out.
-   * @range 0.01 - 1
-   * @default 0.25
-   */
   zoomOut = (multiplier = 0.25) => {
     if (!this.scale || !this.translateX || !this.translateY || multiplier < 0.01 || multiplier > 1) {
       return;
@@ -190,10 +162,6 @@ class GestureViewerManager {
     this.translateY.value = withTiming(translateY);
   };
 
-  /**
-   * @param scale - The scale to reset to.
-   * @default 1
-   */
   resetZoom = (scale = 1) => {
     if (!this.scale || !this.translateX || !this.translateY || scale <= 0 || scale > this.maxZoomScale) {
       return;

src/index.tsx

@@ -1,3 +1,3 @@
 export { GestureViewer } from './GestureViewer';
-export type { GestureViewerProps } from './types';
+export type { GestureViewerController, GestureViewerProps } from './types';
 export { useGestureViewerController } from './useGestureViewerController';

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,32 +65,32 @@ 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;
   // velocityThreshold?: number;
   /**
    * 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;
+};