react-native-gesture-image-viewer 2.3.3 → 2.5.0

package/src/types.ts

@@ -82,6 +82,42 @@ export type GestureViewerSingleTapEvent<ItemT> = {
   item: ItemT;
 };
 
+export type GestureViewerItemDimensions = Readonly<{
+  /**
+   * Natural/source content width. Must be finite and greater than zero.
+   */
+  width: number;
+  /**
+   * Natural/source content height. Must be finite and greater than zero.
+   */
+  height: number;
+}>;
+
+export type GestureViewerItemDimensionsResolver<ItemT> = (
+  item: ItemT,
+  index: number,
+) => GestureViewerItemDimensions | undefined;
+
+export type GestureViewerItemKey = string | number;
+
+export type GestureViewerItemKeyResolver<ItemT> = (
+  item: ItemT,
+  index: number,
+) => GestureViewerItemKey;
+
+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;
+  /**
+   * Registers natural/source dimensions for the rendered item after they become available.
+   * @remarks Call this from an image load/event callback or a passive effect after commit. Do not call it directly while rendering or from descendant layout effects.
+   */
+  readonly setItemDimensions: (dimensions: GestureViewerItemDimensions) => void;
+};
+
 export type GestureViewerDismissDirection = 'down' | 'up' | 'both';
 
 export interface TriggerAnimationConfig extends WithTimingConfig {
@@ -114,6 +150,7 @@ export interface GestureViewerProps<ItemT, LC> {
   data: ItemT[];
   /**
    * The index of the item to display in the `GestureViewer` when the component is mounted.
+   * @remarks The value is normalized to the current data: non-finite or negative values use `0`, values above the available range use the last index, and empty data uses `0`. Updating this prop repositions a mounted viewer.
    * @defaultValue 0
    */
   initialIndex?: number;
@@ -128,8 +165,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 list index of the rendered item.
+   * @param info - Render state for this list cell.
    */
-  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
@@ -138,6 +178,16 @@ export interface GestureViewerProps<ItemT, LC> {
    * - Prefer this callback over overlaying a pressable in `renderContainer` for fullscreen tap handling.
    */
   onSingleTap?: (event: GestureViewerSingleTapEvent<ItemT>) => void;
+  /**
+   * Returns natural/source dimensions for an item when they are already known.
+   * @remarks Return `undefined` while dimensions are unavailable. Invalid dimensions fall back to the viewer cell size.
+   */
+  getItemDimensions?: GestureViewerItemDimensionsResolver<ItemT>;
+  /**
+   * Returns a stable key used to retain loaded dimensions when equivalent item objects are recreated at the same index.
+   * @remarks Keys must be unique within `data` and change when the rendered content's natural dimensions can change. Do not use the index by itself. This is only needed when object items are recreated and dimensions are reported through `setItemDimensions`.
+   */
+  getItemKey?: GestureViewerItemKeyResolver<ItemT>;
   /**
    * A callback function that is called to render the container.
    * @remarks Useful for composing additional UI (e.g., close button, toolbars) around the viewer.

package/src/useGestureViewer.ts

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import { Platform, type View, useWindowDimensions } from 'react-native';
 import { Gesture, type GestureType } from 'react-native-gesture-handler';
 import {
@@ -14,10 +14,23 @@ import { scheduleOnRN } from 'react-native-worklets';
 
 import type GestureViewerManager from './GestureViewerManager';
 import { registry } from './GestureViewerRegistry';
+import {
+  type ItemDimensionsRegistry,
+  pruneItemDimensionsRegistry,
+  registerItemDimensions,
+  resolveItemDimensions,
+} from './itemDimensions';
 import { scheduleInitialScroll } from './scheduleInitialScroll';
-import type { GestureViewerProps, TriggerRect } from './types';
+import type { GestureViewerItemDimensions, GestureViewerProps, TriggerRect } from './types';
 import { useGestureViewerPaging } from './useGestureViewerPaging';
-import { createBoundsConstraint, createScrollAction } from './utils';
+import {
+  clampIndex,
+  clampTranslationToBounds,
+  createScrollAction,
+  getLoopAdjustedIndex,
+  getLoopPhysicalIndex,
+  resolveGeometrySyncTranslationMode,
+} from './utils';
 import { getDismissDistance, shouldDismissByDirection } from './utils/dismiss';
 import { applyTapZoomAtPoint } from './utils/tapZoom';
 import { calculateFocalPointTranslation, shouldAcceptFocalPoint } from './utils/zoom';
@@ -33,6 +46,43 @@ type UseGestureViewerProps<ItemT, LC> = Omit<
   | 'enableSnapMode'
 >;
 
+type ViewerPositionSnapshot = Readonly<{
+  dataLength: number;
+  initialIndex: number;
+  pageStride: number;
+  usesLoopSentinels: boolean;
+}>;
+
+function getViewerPositionChanges(
+  previous: ViewerPositionSnapshot | null,
+  current: ViewerPositionSnapshot,
+) {
+  return {
+    isInitial: previous === null,
+    didDataLengthChange: previous !== null && previous.dataLength !== current.dataLength,
+    didInitialIndexChange: previous !== null && previous.initialIndex !== current.initialIndex,
+    didLoopLayoutChange:
+      previous !== null && previous.usesLoopSentinels !== current.usesLoopSentinels,
+    didPageStrideChange: previous !== null && previous.pageStride !== current.pageStride,
+  };
+}
+
+function fitItemDimensions(
+  dimensions: GestureViewerItemDimensions | undefined,
+  viewport: GestureViewerItemDimensions,
+): GestureViewerItemDimensions {
+  if (!dimensions) {
+    return viewport;
+  }
+
+  const fitScale = Math.min(viewport.width / dimensions.width, viewport.height / dimensions.height);
+
+  return {
+    width: dimensions.width * fitScale,
+    height: dimensions.height * fitScale,
+  };
+}
+
 export const useGestureViewer = <ItemT, LC>({
   data,
   initialIndex = 0,
@@ -53,6 +103,8 @@ export const useGestureViewer = <ItemT, LC>({
   triggerAnimation,
   autoPlay = false,
   autoPlayInterval = 3000,
+  getItemDimensions,
+  getItemKey,
 }: UseGestureViewerProps<ItemT, LC>) => {
   const { width: screenWidth, height: screenHeight } = useWindowDimensions();
   const width = customWidth || screenWidth;
@@ -74,7 +126,11 @@ export const useGestureViewer = <ItemT, LC>({
   const onAnimationCompleteRef = useRef(triggerAnimation?.onAnimationComplete);
   const onSingleTapRef = useRef(onSingleTap);
   const dataRef = useRef(data);
+  const getItemDimensionsRef = useRef(getItemDimensions);
+  const getItemKeyRef = useRef(getItemKey);
   const managerRef = useRef(manager);
+  const configuredManagerRef = useRef<GestureViewerManager | null>(null);
+  const itemDimensionsRef = useRef<ItemDimensionsRegistry<ItemT>>(new Map());
 
   const isValidTriggerRect = useCallback((rect: TriggerRect | null): rect is TriggerRect => {
     return !!rect && rect.width > 0 && rect.height > 0;
@@ -89,6 +145,8 @@ export const useGestureViewer = <ItemT, LC>({
   const scale = useSharedValue(1);
   const backdropOpacity = useSharedValue(1);
   const rotation = useSharedValue(0);
+  const contentWidth = useSharedValue(width);
+  const contentHeight = useSharedValue(height);
 
   const triggerScale = useSharedValue(1);
   const triggerTranslateX = useSharedValue(0);
@@ -102,6 +160,122 @@ export const useGestureViewer = <ItemT, LC>({
   const hasActiveFocal = useSharedValue(false);
 
   const dataLength = data?.length || 0;
+  const usesLoopSentinels = enableLoop && dataLength > 1;
+  const pageStride = width + itemSpacing;
+  const adjustedInitialIndex = getLoopPhysicalIndex(initialIndex, dataLength, enableLoop);
+  // Manager setup can rerender before a deferred list scroll runs, so each consumer tracks
+  // the last committed position inputs independently.
+  const managerPositionSnapshotRef = useRef<ViewerPositionSnapshot | null>(null);
+  const listPositionSnapshotRef = useRef<ViewerPositionSnapshot | null>(null);
+  const viewportRef = useRef({ height, width });
+  const loopConfigRef = useRef({ dataLength, enableLoop });
+  const activeGeometryRef = useRef<{
+    contentHeight: number;
+    contentWidth: number;
+    height: number;
+    width: number;
+  } | null>(null);
+  const activeGeometryIndexRef = useRef<number | null>(null);
+
+  const syncActiveContentDimensions = useCallback(
+    (logicalIndex = pendingIndexRef.current) => {
+      const viewport = viewportRef.current;
+      const fitted = fitItemDimensions(
+        resolveItemDimensions({
+          data: dataRef.current,
+          getItemDimensions: getItemDimensionsRef.current,
+          getItemKey: getItemKeyRef.current,
+          index: logicalIndex,
+          registry: itemDimensionsRef.current,
+        }),
+        viewport,
+      );
+      const nextGeometry = {
+        contentHeight: fitted.height,
+        contentWidth: fitted.width,
+        height: viewport.height,
+        width: viewport.width,
+      };
+      const previousGeometry = activeGeometryRef.current;
+      const previousGeometryIndex = activeGeometryIndexRef.current;
+
+      activeGeometryIndexRef.current = logicalIndex;
+
+      const currentScale = scale.get();
+      const translationMode = resolveGeometrySyncTranslationMode(
+        previousGeometryIndex,
+        logicalIndex,
+        currentScale,
+      );
+
+      if (translationMode === 'reset') {
+        // Complete the page-owned reset before the next item's geometry can reuse the old offset.
+        translateX.set(0);
+        translateY.set(0);
+      }
+
+      if (
+        previousGeometry?.contentHeight === nextGeometry.contentHeight &&
+        previousGeometry.contentWidth === nextGeometry.contentWidth &&
+        previousGeometry.height === nextGeometry.height &&
+        previousGeometry.width === nextGeometry.width
+      ) {
+        return;
+      }
+
+      activeGeometryRef.current = nextGeometry;
+
+      if (contentWidth.get() !== fitted.width) {
+        contentWidth.set(fitted.width);
+      }
+      if (contentHeight.get() !== fitted.height) {
+        contentHeight.set(fitted.height);
+      }
+
+      if (translationMode !== 'constrain') {
+        return;
+      }
+
+      const { translateX: constrainedTranslateX, translateY: constrainedTranslateY } =
+        clampTranslationToBounds({
+          contentHeight: fitted.height,
+          contentWidth: fitted.width,
+          height: viewport.height,
+          scale: currentScale,
+          translateX: translateX.get(),
+          translateY: translateY.get(),
+          width: viewport.width,
+        });
+
+      translateX.set(withTiming(constrainedTranslateX));
+      translateY.set(withTiming(constrainedTranslateY));
+    },
+    [contentHeight, contentWidth, scale, translateX, translateY],
+  );
+
+  const setItemDimensions = useCallback(
+    (listIndex: number, item: ItemT, dimensions: GestureViewerItemDimensions) => {
+      const { dataLength: currentDataLength, enableLoop: currentEnableLoop } =
+        loopConfigRef.current;
+      const logicalIndex =
+        currentDataLength <= 0
+          ? listIndex
+          : getLoopAdjustedIndex(listIndex, currentDataLength, currentEnableLoop).realIndex;
+      const didUpdateDimensions = registerItemDimensions({
+        data: dataRef.current,
+        dimensions,
+        getItemKey: getItemKeyRef.current,
+        index: logicalIndex,
+        item,
+        registry: itemDimensionsRef.current,
+      });
+
+      if (didUpdateDimensions && logicalIndex === pendingIndexRef.current) {
+        syncActiveContentDimensions(logicalIndex);
+      }
+    },
+    [syncActiveContentDimensions],
+  );
 
   const animationConfig = useMemo(
     () => ({
@@ -129,26 +303,38 @@ export const useGestureViewer = <ItemT, LC>({
     ],
   );
 
-  const adjustedInitialIndex = useMemo(() => {
-    if (enableLoop && dataLength > 1) {
-      return initialIndex + 1;
-    }
-
-    return initialIndex;
-  }, [enableLoop, dataLength, initialIndex]);
-
-  const constrainTranslation = useMemo(
-    () => createBoundsConstraint({ height, width }),
-    [width, height],
+  const constrainTranslation = useCallback(
+    ({
+      scale: targetScale,
+      translateX: targetTranslateX,
+      translateY: targetTranslateY,
+    }: {
+      translateX: number;
+      translateY: number;
+      scale: number;
+    }) => {
+      'worklet';
+
+      return clampTranslationToBounds({
+        contentHeight: contentHeight.get(),
+        contentWidth: contentWidth.get(),
+        height,
+        scale: targetScale,
+        translateX: targetTranslateX,
+        translateY: targetTranslateY,
+        width,
+      });
+    },
+    [contentHeight, contentWidth, height, width],
   );
 
   const scrollTo = useCallback(
     (index: number, animated: boolean) => {
-      const scrollAction = createScrollAction(listRef.current, width + itemSpacing);
+      const scrollAction = createScrollAction(listRef.current, pageStride);
 
       return scrollAction.scrollTo(index, animated);
     },
-    [width, itemSpacing],
+    [pageStride],
   );
 
   const resetTransformState = useCallback(() => {
@@ -167,9 +353,14 @@ export const useGestureViewer = <ItemT, LC>({
         return;
       }
 
+      if (nextIndex === pendingIndexRef.current) {
+        return;
+      }
+
       pendingIndexRef.current = nextIndex;
+      syncActiveContentDimensions(nextIndex);
     },
-    [dataLength],
+    [dataLength, syncActiveContentDimensions],
   );
 
   const syncCurrentIndex = useCallback(
@@ -179,6 +370,7 @@ export const useGestureViewer = <ItemT, LC>({
       }
 
       pendingIndexRef.current = nextIndex;
+      syncActiveContentDimensions(nextIndex);
 
       const managerCurrentIndex = manager.getState().currentIndex;
 
@@ -190,7 +382,7 @@ export const useGestureViewer = <ItemT, LC>({
       manager.notifyStateChange();
       resetTransformState();
     },
-    [dataLength, manager, resetTransformState],
+    [dataLength, manager, resetTransformState, syncActiveContentDimensions],
   );
 
   const emitZoomChange = useCallback((currentScale: number, prevScale: number | null) => {
@@ -249,37 +441,78 @@ export const useGestureViewer = <ItemT, LC>({
   }, [id]);
 
   useEffect(() => {
-    pendingIndexRef.current = initialIndex;
+    const currentPositionSnapshot = {
+      dataLength,
+      initialIndex,
+      pageStride,
+      usesLoopSentinels,
+    };
+    const { didDataLengthChange, didInitialIndexChange, didLoopLayoutChange } =
+      getViewerPositionChanges(managerPositionSnapshotRef.current, currentPositionSnapshot);
+
+    managerPositionSnapshotRef.current = currentPositionSnapshot;
 
     if (!manager) {
+      configuredManagerRef.current = null;
       return;
     }
 
+    const isNewManager = configuredManagerRef.current !== manager;
+    const shouldApplyInitialIndex =
+      isNewManager || didInitialIndexChange || didDataLengthChange || didLoopLayoutChange;
+    const shouldSyncInitialIndex =
+      didInitialIndexChange ||
+      didDataLengthChange ||
+      didLoopLayoutChange ||
+      activeGeometryIndexRef.current !== initialIndex;
+
     manager.setDataLength(dataLength);
     manager.setEnableHorizontalSwipe(enableHorizontalSwipe);
-    manager.setCurrentIndex(initialIndex);
-    manager.setWidth(width + itemSpacing);
+    manager.setPagingStride(pageStride);
+    manager.setViewportWidth(width);
     manager.setHeight(height);
-    manager.setZoomSharedValues(scale, translateX, translateY, maxZoomScale);
+    manager.setZoomSharedValues({
+      contentHeight,
+      contentWidth,
+      maxZoomScale,
+      scale,
+      translateX,
+      translateY,
+    });
     manager.setResetTransformCallback(resetTransformState);
     manager.setRotation(rotation);
     manager.setEnableLoop(enableLoop);
+
+    if (shouldApplyInitialIndex) {
+      pendingIndexRef.current = initialIndex;
+      manager.setCurrentIndex(initialIndex);
+
+      if (shouldSyncInitialIndex) {
+        syncActiveContentDimensions(initialIndex);
+      }
+    }
+
+    configuredManagerRef.current = manager;
     manager.notifyStateChange();
   }, [
     dataLength,
     enableHorizontalSwipe,
     initialIndex,
     manager,
+    pageStride,
     width,
-    itemSpacing,
     maxZoomScale,
     enableLoop,
     scale,
     height,
+    contentWidth,
+    contentHeight,
     resetTransformState,
+    syncActiveContentDimensions,
     translateX,
     translateY,
     rotation,
+    usesLoopSentinels,
   ]);
 
   useEffect(() => {
@@ -291,6 +524,35 @@ export const useGestureViewer = <ItemT, LC>({
   }, [manager]);
 
   useEffect(() => {
+    const currentPositionSnapshot = {
+      dataLength,
+      initialIndex,
+      pageStride,
+      usesLoopSentinels,
+    };
+    const {
+      didDataLengthChange,
+      didInitialIndexChange,
+      didLoopLayoutChange,
+      didPageStrideChange,
+      isInitial: isInitialPositionRender,
+    } = getViewerPositionChanges(listPositionSnapshotRef.current, currentPositionSnapshot);
+    const commitPositionSnapshot = () => {
+      listPositionSnapshotRef.current = currentPositionSnapshot;
+    };
+
+    const shouldResetToInitialIndex =
+      isInitialPositionRender ||
+      didInitialIndexChange ||
+      didDataLengthChange ||
+      didLoopLayoutChange;
+    const shouldRealignCurrentIndex = didPageStrideChange && !shouldResetToInitialIndex;
+
+    if (!shouldResetToInitialIndex && !shouldRealignCurrentIndex) {
+      commitPositionSnapshot();
+      return;
+    }
+
     translateY.set(0);
     translateX.set(0);
     scale.set(1);
@@ -298,15 +560,44 @@ export const useGestureViewer = <ItemT, LC>({
     startScale.set(1);
     rotation.set(0);
 
-    if (adjustedInitialIndex <= 0 || !listRef.current) {
+    if (dataLength === 0 || !listRef.current) {
+      commitPositionSnapshot();
+      return;
+    }
+
+    if (isInitialPositionRender && adjustedInitialIndex === 0) {
+      commitPositionSnapshot();
+      return;
+    }
+
+    const logicalIndex = shouldResetToInitialIndex
+      ? initialIndex
+      : clampIndex(
+          managerRef.current?.getState().currentIndex ?? pendingIndexRef.current,
+          dataLength,
+        );
+    const physicalIndex = getLoopPhysicalIndex(logicalIndex, dataLength, enableLoop);
+
+    if (shouldRealignCurrentIndex) {
+      pendingIndexRef.current = logicalIndex;
+      syncActiveContentDimensions(logicalIndex);
+    }
+
+    if (shouldRealignCurrentIndex && physicalIndex === 0) {
+      commitPositionSnapshot();
       return;
     }
 
     return scheduleInitialScroll(() => {
-      scrollTo(adjustedInitialIndex, false);
+      scrollTo(physicalIndex, false);
+      commitPositionSnapshot();
     });
   }, [
     adjustedInitialIndex,
+    dataLength,
+    enableLoop,
+    initialIndex,
+    pageStride,
     translateY,
     backdropOpacity,
     translateX,
@@ -314,15 +605,36 @@ export const useGestureViewer = <ItemT, LC>({
     startScale,
     rotation,
     scrollTo,
+    syncActiveContentDimensions,
+    usesLoopSentinels,
   ]);
 
   useEffect(() => {
     onAnimationCompleteRef.current = triggerAnimation?.onAnimationComplete;
   }, [triggerAnimation?.onAnimationComplete]);
 
-  useEffect(() => {
+  useLayoutEffect(() => {
+    // Retained virtualized-cell callbacks read only the most recently committed props.
     dataRef.current = data;
-  }, [data]);
+    getItemDimensionsRef.current = getItemDimensions;
+    getItemKeyRef.current = getItemKey;
+    viewportRef.current = { height, width };
+    loopConfigRef.current = { dataLength, enableLoop };
+    syncActiveContentDimensions();
+  }, [
+    data,
+    dataLength,
+    enableLoop,
+    getItemDimensions,
+    getItemKey,
+    height,
+    syncActiveContentDimensions,
+    width,
+  ]);
+
+  useEffect(() => {
+    pruneItemDimensionsRegistry(itemDimensionsRef.current, dataLength);
+  }, [dataLength]);
 
   useEffect(() => {
     managerRef.current = manager;
@@ -757,6 +1069,8 @@ export const useGestureViewer = <ItemT, LC>({
         .numberOfTaps(2)
         .onEnd((event) => {
           applyTapZoomAtPoint({
+            contentHeight: contentHeight.get(),
+            contentWidth: contentWidth.get(),
             x: event.x,
             y: event.y,
             width,
@@ -767,7 +1081,17 @@ export const useGestureViewer = <ItemT, LC>({
             translateY,
           });
         }),
-    [enableDoubleTapZoom, height, maxZoomScale, scale, translateX, translateY, width],
+    [
+      contentHeight,
+      contentWidth,
+      enableDoubleTapZoom,
+      height,
+      maxZoomScale,
+      scale,
+      translateX,
+      translateY,
+      width,
+    ],
   );
 
   const tapGesture = useMemo(
@@ -811,32 +1135,36 @@ export const useGestureViewer = <ItemT, LC>({
     return Gesture.Native().requireExternalGestureToFail(dismissGestureRef);
   }, []);
 
-  const { onMomentumScrollEnd, onScroll, onScrollBeginDrag, onWebClick } = useGestureViewerPaging({
-    adjustedInitialIndex,
-    autoPlay,
-    autoPlayInterval,
-    currentIndex,
-    dataLength,
-    enableDoubleTapZoom,
-    enableHorizontalSwipe,
-    enableLoop,
-    height,
-    isRotated,
-    isZoomed,
-    itemSpacing,
-    manager,
-    maxZoomScale,
-    onSingleTap: emitSingleTap,
-    scale,
-    scrollTo,
-    syncCurrentIndex,
-    syncPendingIndex,
-    translateX,
-    translateY,
-    width,
-  });
+  const { activeListIndex, onMomentumScrollEnd, onScroll, onScrollBeginDrag, onWebClick } =
+    useGestureViewerPaging({
+      adjustedInitialIndex,
+      autoPlay,
+      autoPlayInterval,
+      contentHeight,
+      contentWidth,
+      currentIndex,
+      dataLength,
+      enableDoubleTapZoom,
+      enableHorizontalSwipe,
+      enableLoop,
+      height,
+      isRotated,
+      isZoomed,
+      itemSpacing,
+      manager,
+      maxZoomScale,
+      onSingleTap: emitSingleTap,
+      scale,
+      scrollTo,
+      syncCurrentIndex,
+      syncPendingIndex,
+      translateX,
+      translateY,
+      width,
+    });
 
   return {
+    activeListIndex,
     animatedStyle,
     backdropStyle,
     dataLength,
@@ -853,6 +1181,7 @@ export const useGestureViewer = <ItemT, LC>({
     onScroll,
 
     onScrollBeginDrag,
+    setItemDimensions,
     zoomGesture,
   };
 };