react-native-gesture-image-viewer 2.3.3 → 3.0.0-beta.0

package/src/gestureViewerPaging.ts

@@ -0,0 +1,116 @@
+export type HorizontalSwipeDirection = -1 | 0 | 1;
+
+export type HorizontalPagingTarget =
+  | {
+      kind: 'move';
+      targetVirtualIndex: number;
+    }
+  | {
+      kind: 'settle';
+    };
+
+export function normalizeHorizontalSwipeThreshold(
+  value: number | undefined,
+  fallback: number,
+): number {
+  if (value === undefined) {
+    return fallback;
+  }
+
+  if (Number.isFinite(value) && value >= 0) {
+    return value;
+  }
+
+  return fallback;
+}
+
+export function resolveHorizontalSwipeDirection(
+  translationX: number,
+  velocityX: number,
+  width: number,
+  thresholdRatio: number,
+  velocityThreshold: number,
+): HorizontalSwipeDirection {
+  'worklet';
+
+  const translationThreshold = width * thresholdRatio;
+
+  if (-translationX > translationThreshold || velocityX < -velocityThreshold) {
+    return 1;
+  }
+
+  if (translationX > translationThreshold || velocityX > velocityThreshold) {
+    return -1;
+  }
+
+  return 0;
+}
+
+export function applyHorizontalEdgeResistance(
+  nextPage: number,
+  currentIndex: number,
+  dataLength: number,
+  centerVirtualIndex: number,
+  enableLoop: boolean,
+  resistance: number,
+): number {
+  'worklet';
+
+  if (dataLength <= 1) {
+    return centerVirtualIndex;
+  }
+
+  if (enableLoop) {
+    return nextPage;
+  }
+
+  if (currentIndex <= 0 && nextPage < centerVirtualIndex) {
+    return centerVirtualIndex + (nextPage - centerVirtualIndex) * resistance;
+  }
+
+  if (currentIndex >= dataLength - 1 && nextPage > centerVirtualIndex) {
+    return centerVirtualIndex + (nextPage - centerVirtualIndex) * resistance;
+  }
+
+  return nextPage;
+}
+
+export function canMoveHorizontalPage(
+  currentIndex: number,
+  dataLength: number,
+  direction: HorizontalSwipeDirection,
+  enableLoop: boolean,
+): boolean {
+  'worklet';
+
+  if (direction === 0 || dataLength <= 1) {
+    return false;
+  }
+
+  if (enableLoop) {
+    return true;
+  }
+
+  const nextIndex = currentIndex + direction;
+
+  return nextIndex >= 0 && nextIndex < dataLength;
+}
+
+export function resolveHorizontalPagingTarget(
+  centerVirtualIndex: number,
+  currentIndex: number,
+  dataLength: number,
+  direction: HorizontalSwipeDirection,
+  enableLoop: boolean,
+): HorizontalPagingTarget {
+  'worklet';
+
+  if (!canMoveHorizontalPage(currentIndex, dataLength, direction, enableLoop)) {
+    return { kind: 'settle' };
+  }
+
+  return {
+    kind: 'move',
+    targetVirtualIndex: centerVirtualIndex + direction,
+  };
+}

package/src/gestureViewerRenderWindow.ts

@@ -0,0 +1,56 @@
+import {
+  type RenderWindowSlot,
+  clampIndex,
+  createRenderWindow,
+  getVirtualIndexForLogicalIndex,
+  normalizeWindowSize,
+} from './renderWindow';
+
+export type GestureViewerRenderWindowState<ItemT> = {
+  centerVirtualIndex: number;
+  currentIndex: number;
+  slots: RenderWindowSlot<ItemT>[];
+};
+
+export function resolveGestureViewerRenderWindow<ItemT>({
+  centerVirtualIndex,
+  currentIndex,
+  data,
+  enableLoop,
+  isTriggerOpening,
+  windowSize,
+}: {
+  centerVirtualIndex: number;
+  currentIndex: number;
+  data: ItemT[];
+  enableLoop: boolean;
+  isTriggerOpening: boolean;
+  windowSize?: number;
+}): GestureViewerRenderWindowState<ItemT> {
+  const dataLength = data.length;
+  const normalizedWindowSize = normalizeWindowSize(windowSize);
+  const renderCurrentIndex = clampIndex(currentIndex, dataLength);
+  const renderCenterVirtualIndex =
+    getVirtualIndexForLogicalIndex(
+      renderCurrentIndex,
+      centerVirtualIndex,
+      dataLength,
+      enableLoop,
+    ) ?? renderCurrentIndex;
+
+  const fullSlots = createRenderWindow({
+    centerVirtualIndex: renderCenterVirtualIndex,
+    data,
+    enableLoop,
+    windowSize: normalizedWindowSize,
+  });
+  const slots = isTriggerOpening
+    ? fullSlots.filter((slot) => slot.virtualIndex === renderCenterVirtualIndex)
+    : fullSlots;
+
+  return {
+    centerVirtualIndex: renderCenterVirtualIndex,
+    currentIndex: renderCurrentIndex,
+    slots,
+  };
+}

package/src/getWebContentProps.ts

@@ -0,0 +1,5 @@
+import type { WebClickHandler } from './useWebClickHandler';
+
+export function getWebContentProps(_onWebClick: WebClickHandler) {
+  return {};
+}

package/src/getWebContentProps.web.ts

@@ -0,0 +1,5 @@
+import type { WebClickHandler } from './useWebClickHandler';
+
+export function getWebContentProps(onWebClick: WebClickHandler) {
+  return { onClick: onWebClick };
+}

package/src/index.tsx

@@ -7,6 +7,7 @@ export type {
   GestureViewerEventData,
   GestureViewerEventType,
   GestureViewerProps,
+  GestureViewerRenderItemInfo,
   GestureViewerState,
   GestureViewerSingleTapEvent,
 } from './types';

package/src/platformTapGestures.ts

@@ -0,0 +1 @@
+export const enableNativeTapGestures = true;

package/src/platformTapGestures.web.ts

@@ -0,0 +1 @@
+export const enableNativeTapGestures = false;

package/src/renderWindow.ts

@@ -0,0 +1,253 @@
+export const DEFAULT_WINDOW_SIZE = 3;
+export const MIN_WINDOW_SIZE = 3;
+
+type NavigationDirection = -1 | 1;
+
+export type RenderWindowSlot<ItemT> = {
+  item: ItemT;
+  logicalIndex: number;
+  slotKey: string;
+  virtualIndex: number;
+};
+
+export type NavigationResolution =
+  | {
+      kind: 'noop';
+    }
+  | {
+      direction: NavigationDirection;
+      kind: 'step';
+      targetIndex: number;
+    }
+  | {
+      kind: 'jump';
+      targetIndex: number;
+    };
+
+export type NavigationOptions = {
+  animated?: boolean;
+};
+
+const positiveModulo = (value: number, divisor: number) => ((value % divisor) + divisor) % divisor;
+
+const getStepTargetIndex = (
+  currentIndex: number,
+  dataLength: number,
+  enableLoop: boolean,
+  direction: NavigationDirection,
+) => {
+  const adjacentIndex = currentIndex + direction;
+
+  if (adjacentIndex >= 0 && adjacentIndex < dataLength) {
+    return adjacentIndex;
+  }
+
+  if (!enableLoop || dataLength <= 1) {
+    return null;
+  }
+
+  if (direction === 1 && currentIndex === dataLength - 1) {
+    return 0;
+  }
+
+  if (direction === -1 && currentIndex === 0) {
+    return dataLength - 1;
+  }
+
+  return null;
+};
+
+export function normalizeWindowSize(windowSize?: number): number {
+  const candidateWindowSize = windowSize ?? DEFAULT_WINDOW_SIZE;
+
+  if (!Number.isFinite(candidateWindowSize)) {
+    return DEFAULT_WINDOW_SIZE;
+  }
+
+  const integerWindowSize = Math.floor(candidateWindowSize);
+  const boundedWindowSize = Math.max(MIN_WINDOW_SIZE, integerWindowSize);
+
+  return boundedWindowSize % 2 === 0 ? boundedWindowSize + 1 : boundedWindowSize;
+}
+
+export function normalizePageSpacing(pageSpacing?: number): number {
+  const candidatePageSpacing = pageSpacing ?? 0;
+
+  if (!Number.isFinite(candidatePageSpacing) || candidatePageSpacing < 0) {
+    return 0;
+  }
+
+  return candidatePageSpacing;
+}
+
+export function getPageStride(width: number, pageSpacing?: number): number {
+  return width + normalizePageSpacing(pageSpacing);
+}
+
+export function clampIndex(index: number | undefined, dataLength: number): number {
+  if (dataLength <= 0) {
+    return 0;
+  }
+
+  const candidateIndex = index ?? 0;
+
+  if (!Number.isFinite(candidateIndex)) {
+    return 0;
+  }
+
+  return Math.min(Math.max(Math.trunc(candidateIndex), 0), dataLength - 1);
+}
+
+export function getLogicalIndex(
+  virtualIndex: number,
+  dataLength: number,
+  enableLoop: boolean,
+): number | null {
+  if (dataLength <= 0 || !Number.isFinite(virtualIndex)) {
+    return null;
+  }
+
+  if (enableLoop) {
+    return positiveModulo(Math.trunc(virtualIndex), dataLength);
+  }
+
+  if (virtualIndex < 0 || virtualIndex >= dataLength) {
+    return null;
+  }
+
+  return Math.trunc(virtualIndex);
+}
+
+export function getVirtualIndexForLogicalIndex(
+  logicalIndex: number,
+  centerVirtualIndex: number,
+  dataLength: number,
+  enableLoop: boolean,
+): number | null {
+  if (dataLength <= 0 || logicalIndex < 0 || logicalIndex >= dataLength) {
+    return null;
+  }
+
+  if (!enableLoop) {
+    return logicalIndex;
+  }
+
+  const currentLogicalIndex = getLogicalIndex(centerVirtualIndex, dataLength, true);
+
+  if (currentLogicalIndex === null) {
+    return logicalIndex;
+  }
+
+  const forwardDistance = positiveModulo(logicalIndex - currentLogicalIndex, dataLength);
+  const backwardDistance = positiveModulo(currentLogicalIndex - logicalIndex, dataLength);
+
+  return forwardDistance <= backwardDistance
+    ? centerVirtualIndex + forwardDistance
+    : centerVirtualIndex - backwardDistance;
+}
+
+export function createRenderWindow<ItemT>({
+  centerVirtualIndex,
+  data,
+  enableLoop,
+  windowSize,
+}: {
+  centerVirtualIndex: number;
+  data: ItemT[];
+  enableLoop: boolean;
+  windowSize?: number;
+}): RenderWindowSlot<ItemT>[] {
+  const dataLength = data.length;
+
+  if (dataLength === 0) {
+    return [];
+  }
+
+  const normalizedWindowSize = normalizeWindowSize(windowSize);
+  const halfWindowSize = enableLoop && dataLength === 1 ? 0 : Math.floor(normalizedWindowSize / 2);
+  const slots: RenderWindowSlot<ItemT>[] = [];
+
+  for (let offset = -halfWindowSize; offset <= halfWindowSize; offset += 1) {
+    const virtualIndex = centerVirtualIndex + offset;
+    const logicalIndex = getLogicalIndex(virtualIndex, dataLength, enableLoop);
+
+    if (logicalIndex === null || !(logicalIndex in data)) {
+      continue;
+    }
+
+    slots.push({
+      item: data[logicalIndex] as ItemT,
+      logicalIndex,
+      slotKey: `slot-${virtualIndex}`,
+      virtualIndex,
+    });
+  }
+
+  return slots;
+}
+
+export function resolveNavigation({
+  currentIndex,
+  dataLength,
+  enableLoop,
+  preferredDirection,
+  targetIndex,
+}: {
+  currentIndex: number;
+  dataLength: number;
+  enableLoop: boolean;
+  preferredDirection?: NavigationDirection;
+  targetIndex: number;
+}): NavigationResolution {
+  if (
+    dataLength <= 0 ||
+    targetIndex < 0 ||
+    targetIndex >= dataLength ||
+    currentIndex < 0 ||
+    currentIndex >= dataLength
+  ) {
+    return { kind: 'noop' };
+  }
+
+  if (targetIndex === currentIndex) {
+    return { kind: 'noop' };
+  }
+
+  if (preferredDirection !== undefined) {
+    const preferredTargetIndex = getStepTargetIndex(
+      currentIndex,
+      dataLength,
+      enableLoop,
+      preferredDirection,
+    );
+
+    if (preferredTargetIndex === targetIndex) {
+      return { direction: preferredDirection, kind: 'step', targetIndex };
+    }
+  }
+
+  const forwardTargetIndex = getStepTargetIndex(currentIndex, dataLength, enableLoop, 1);
+
+  if (forwardTargetIndex === targetIndex) {
+    return { direction: 1, kind: 'step', targetIndex };
+  }
+
+  const backwardTargetIndex = getStepTargetIndex(currentIndex, dataLength, enableLoop, -1);
+
+  if (backwardTargetIndex === targetIndex) {
+    return { direction: -1, kind: 'step', targetIndex };
+  }
+
+  return { kind: 'jump', targetIndex };
+}
+
+export function shouldRunNavigationDuringTransition(
+  resolution: NavigationResolution,
+  options?: NavigationOptions,
+): boolean {
+  if (resolution.kind === 'noop') {
+    return false;
+  }
+
+  return resolution.kind === 'jump' || options?.animated === false;
+}

package/src/types.ts

@@ -1,73 +1,7 @@
 import type React from 'react';
-import type {
-  FlatListProps,
-  ListRenderItem,
-  FlatList as RNFlatList,
-  ScrollView as RNScrollView,
-  StyleProp,
-  ViewabilityConfig,
-  ViewStyle,
-  ViewToken,
-} from 'react-native';
-import type {
-  FlatList as GHFlatList,
-  ScrollView as GHScrollView,
-} from 'react-native-gesture-handler';
+import type { StyleProp, ViewStyle } from 'react-native';
 import type { WithTimingConfig } from 'react-native-reanimated';
 
-export type FlatListComponent<ItemT> = typeof RNFlatList<ItemT> | typeof GHFlatList<ItemT>;
-export type ScrollViewComponent = typeof RNScrollView | typeof GHScrollView;
-
-interface ViewabilityConfigCallbackPair<TItem> {
-  viewabilityConfig: ViewabilityConfig;
-  onViewableItemsChanged:
-    | ((info: { viewableItems: ViewToken<TItem>[]; changed: ViewToken<TItem>[] }) => void)
-    | null;
-}
-
-// Helper type to instantiate generic components with specific type parameter
-export type InstantiateGeneric<ItemT, LC> =
-  LC extends React.ComponentType<infer P>
-    ? P extends Record<string, any>
-      ? {
-          [K in keyof P]: K extends 'data'
-            ? ArrayLike<ItemT> | null | undefined
-            : K extends 'renderItem'
-              ? ListRenderItem<ItemT>
-              : K extends 'keyExtractor'
-                ? (item: ItemT, index: number) => string
-                : K extends 'getItemType'
-                  ? (item: ItemT, index: number, extraData?: any) => string | number | undefined
-                  : K extends 'overrideItemLayout'
-                    ? (
-                        layout: { span?: number; size?: number },
-                        item: ItemT,
-                        index: number,
-                        maxColumns?: number,
-                        extraData?: any,
-                      ) => void
-                    : K extends 'onViewableItemsChanged'
-                      ? FlatListProps<ItemT>['onViewableItemsChanged']
-                      : K extends 'viewabilityConfigCallbackPairs'
-                        ? ViewabilityConfigCallbackPair<ItemT>[]
-                        : P[K];
-        }
-      : P
-    : never;
-
-export type GetComponentProps<ItemT, LC> =
-  LC extends React.ComponentType<any> ? InstantiateGeneric<ItemT, LC> : never;
-
-type ConditionalListProps<ItemT, LC> = LC extends typeof RNFlatList<ItemT>
-  ? React.ComponentProps<typeof RNFlatList<ItemT>>
-  : LC extends typeof GHFlatList<ItemT>
-    ? React.ComponentProps<typeof GHFlatList<ItemT>>
-    : LC extends typeof RNScrollView
-      ? React.ComponentProps<typeof RNScrollView>
-      : LC extends typeof GHScrollView
-        ? React.ComponentProps<typeof GHScrollView>
-        : GetComponentProps<ItemT, LC>;
-
 export type TriggerRect = {
   x: number;
   y: number;
@@ -82,6 +16,14 @@ export type GestureViewerSingleTapEvent<ItemT> = {
   item: ItemT;
 };
 
+export type GestureViewerRenderItemInfo = {
+  /**
+   * Whether the rendered item is currently active.
+   * @remarks The current item remains active during a page transition. When the transition finishes on another item, that item becomes active.
+   */
+  readonly isActive: boolean;
+};
+
 export type GestureViewerDismissDirection = 'down' | 'up' | 'both';
 
 export interface TriggerAnimationConfig extends WithTimingConfig {
@@ -101,7 +43,7 @@ export interface TriggerAnimationConfig extends WithTimingConfig {
   onAnimationComplete?: () => void;
 }
 
-export interface GestureViewerProps<ItemT, LC> {
+export interface GestureViewerProps<ItemT> {
   /**
    * When you want to efficiently manage multiple `GestureViewer` instances, you can use the `id` prop to use multiple `GestureViewer` components.
    * @remarks `GestureViewer` automatically removes instances from memory when components are unmounted, so no manual memory management is required.
@@ -128,8 +70,11 @@ export interface GestureViewerProps<ItemT, LC> {
   onDismissStart?: () => void;
   /**
    * A callback function that is called to render the item.
+   * @param item - The item to render.
+   * @param index - The index of the item in `data`.
+   * @param info - Render state for this mounted slot.
    */
-  renderItem: (item: ItemT, index: number) => React.ReactElement;
+  renderItem: (item: ItemT, index: number, info: GestureViewerRenderItemInfo) => React.ReactElement;
   /**
    * A callback function that is called when a single tap is confirmed on the viewer content.
    * @remarks
@@ -152,10 +97,6 @@ export interface GestureViewerProps<ItemT, LC> {
     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`.
    * @remarks If you don't set this prop, the width of the `GestureViewer` will be the same as the width of the screen.
@@ -168,11 +109,6 @@ export interface GestureViewerProps<ItemT, LC> {
    * @defaultValue screen height
    */
   height?: number;
-  /**
-   * The props to pass to the list component.
-   * @remarks The `listProps` provides **type inference based on the selected list component**, ensuring accurate autocompletion and type safety in your IDE.
-   */
-  listProps?: Partial<ConditionalListProps<ItemT, LC>>;
   /**
    * The style of the backdrop.
    */
@@ -234,11 +170,28 @@ export interface GestureViewerProps<ItemT, LC> {
     fadeBackdrop?: boolean;
   };
   /**
-   * Controls left/right swipe gestures.
-   * @remarks When `false`, horizontal gestures are disabled.
-   * @defaultValue true
+   * Horizontal swipe gesture options.
+   * @remarks Controls user-driven left/right page swipe gestures. Controller navigation and autoplay remain available when disabled.
    */
-  enableHorizontalSwipe?: boolean;
+  horizontalSwipe?: {
+    /**
+     * When `false`, user-driven horizontal page swipe gestures are disabled.
+     * @defaultValue true
+     */
+    enabled?: boolean;
+    /**
+     * Distance threshold as a ratio of viewer width.
+     * @remarks A page commits when absolute horizontal translation is strictly greater than `width * distanceThresholdRatio`, or when velocity passes `velocityThreshold`. Zero and finite values greater than `1` are accepted; negative and non-finite values fall back to the default.
+     * @defaultValue 0.25
+     */
+    distanceThresholdRatio?: number;
+    /**
+     * Horizontal velocity threshold in points per second.
+     * @remarks A page commits when absolute horizontal velocity is strictly greater than `velocityThreshold`, or when distance passes `distanceThresholdRatio`. Zero and every finite non-negative value are accepted; negative and non-finite values fall back to the default.
+     * @defaultValue 800
+     */
+    velocityThreshold?: number;
+  };
   /**
    * Only works when zoom is active, allows moving item position when zoomed.
    * @remarks When `false`, gesture movement is disabled during zoom.
@@ -263,25 +216,17 @@ export interface GestureViewerProps<ItemT, LC> {
    */
   enableLoop?: boolean;
   /**
-   * Enables snap scrolling mode.
-   *
-   * @remarks
-   * **`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
-   *
+   * Number of mounted render-window slots including the current item.
+   * @remarks Values are normalized to an odd number of at least 3. For example, `4` becomes `5`.
+   * @defaultValue 3
    */
-  enableSnapMode?: boolean;
+  windowSize?: number;
   /**
-   * The spacing between items in pixels.
-   * @remarks Only applied when `enableSnapMode` is `true`.
+   * Horizontal visual space between pages.
+   * @remarks Page stride is `width + pageSpacing`; zoom bounds still use `width` and `height`.
    * @defaultValue 0
    */
-  itemSpacing?: number;
+  pageSpacing?: number;
   /**
    * The maximum zoom scale.
    * @defaultValue 2
@@ -323,7 +268,7 @@ export type GestureViewerController = {
    * 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
+   * Out-of-range indexes are ignored.
    *
    * @example
    * ```typescript
@@ -333,7 +278,7 @@ export type GestureViewerController = {
    * controller.goToIndex(totalCount - 1); // Go to last item
    * ```
    */
-  goToIndex: (index: number) => void;
+  goToIndex: (index: number, options?: { animated?: boolean }) => void;
 
   /**
    * Navigates to the previous item in the sequence.