react-native-gesture-image-viewer 3.0.0-beta.1 → 3.0.0-beta.3

package/src/types.ts

@@ -16,12 +16,40 @@ 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 or event callback, or from a passive `useEffect` after commit. Do not call it during render or from a descendant layout effect.
+   */
+  readonly setItemDimensions: (dimensions: GestureViewerItemDimensions) => void;
 };
 
 export type GestureViewerDismissDirection = 'down' | 'up' | 'both';
@@ -83,6 +111,16 @@ export interface GestureViewerProps<ItemT> {
    * - 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 logical key for an item when the same logical item may be recreated as a new object.
+   * @remarks Use this when item identity is not object-stable across rerenders. The key must identify the same rendered content and change when the rendered source or natural dimensions change. Do not return the array index alone. When omitted, runtime dimensions are only reused for the exact same item object.
+   */
+  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

@@ -22,6 +22,12 @@ import type GestureViewerManager from './GestureViewerManager';
 import { normalizeHorizontalSwipeThreshold } from './gestureViewerPaging';
 import { registry } from './GestureViewerRegistry';
 import { resolveGestureViewerRenderWindow } from './gestureViewerRenderWindow';
+import {
+  type ItemDimensionsRegistry,
+  pruneItemDimensionsRegistry,
+  registerItemDimensions,
+  resolveItemDimensions,
+} from './itemDimensions';
 import { enableNativeTapGestures } from './platformTapGestures';
 import {
   type NavigationOptions,
@@ -33,12 +39,12 @@ import {
   resolveNavigation,
   shouldRunNavigationDuringTransition,
 } from './renderWindow';
-import type { GestureViewerProps, TriggerRect } from './types';
+import type { GestureViewerItemDimensions, GestureViewerProps, TriggerRect } from './types';
 import { useGestureViewerManagerBridge } from './useGestureViewerManagerBridge';
 import { useGestureViewerPaging } from './useGestureViewerPaging';
 import { type EmitSingleTap, useWebClickHandler } from './useWebClickHandler';
 import { useWebSingleTapTimer } from './useWebSingleTapTimer';
-import { createBoundsConstraint } from './utils';
+import { clampTranslationToBounds, resolveGeometrySyncTranslationMode } from './utils';
 import { getDismissDistance, shouldDismissByDirection } from './utils/dismiss';
 import { applyTapZoomAtPoint } from './utils/tapZoom';
 import { calculateFocalPointTranslation, shouldAcceptFocalPoint } from './utils/zoom';
@@ -54,6 +60,23 @@ type UseGestureViewerProps<ItemT> = Omit<
   'renderItem' | 'renderContainer' | 'containerStyle' | 'backdropStyle'
 >;
 
+type ContentViewport = Readonly<{
+  height: number;
+  width: number;
+}>;
+
+function fitItemDimensions(
+  dimensions: GestureViewerItemDimensions | undefined,
+  viewport: ContentViewport,
+): GestureViewerItemDimensions {
+  if (!dimensions) {
+    return viewport;
+  }
+
+  const fit = Math.min(viewport.width / dimensions.width, viewport.height / dimensions.height);
+  return { height: dimensions.height * fit, width: dimensions.width * fit };
+}
+
 export const useGestureViewer = <ItemT>({
   data,
   initialIndex = 0,
@@ -75,6 +98,8 @@ export const useGestureViewer = <ItemT>({
   triggerAnimation,
   autoPlay = false,
   autoPlayInterval = 3000,
+  getItemDimensions,
+  getItemKey,
 }: UseGestureViewerProps<ItemT>) => {
   const { width: screenWidth, height: screenHeight } = useWindowDimensions();
   const width = customWidth || screenWidth;
@@ -117,12 +142,23 @@ export const useGestureViewer = <ItemT>({
   const onAnimationCompleteRef = useRef(triggerAnimation?.onAnimationComplete);
   const onSingleTapRef = useRef(onSingleTap);
   const dataRef = useRef(data);
+  const getItemDimensionsRef = useRef(getItemDimensions);
+  const getItemKeyRef = useRef(getItemKey);
   const dataLengthRef = useRef(dataLength);
   const enableLoopRef = useRef(enableLoop);
   const managerRef = useRef<GestureViewerManager | null>(null);
   const isZoomedRef = useRef(isZoomed);
   const isRotatedRef = useRef(isRotated);
   const isPinchingRef = useRef(isPinching);
+  const itemDimensionsRef = useRef<ItemDimensionsRegistry<ItemT>>(new Map());
+  const viewportRef = useRef({ height, width });
+  const activeGeometryRef = useRef<{
+    contentHeight: number;
+    contentWidth: number;
+    height: number;
+    width: number;
+  } | null>(null);
+  const activeGeometryIndexRef = useRef<number | null>(null);
 
   const initialTranslateY = useSharedValue(0);
   const initialTranslateX = useSharedValue(0);
@@ -132,6 +168,8 @@ export const useGestureViewer = <ItemT>({
   const translateX = useSharedValue(0);
   const scale = useSharedValue(1);
   const rotation = useSharedValue(0);
+  const contentWidth = useSharedValue(width);
+  const contentHeight = useSharedValue(height);
 
   const triggerScale = useSharedValue(1);
   const triggerTranslateX = useSharedValue(0);
@@ -189,9 +227,121 @@ export const useGestureViewer = <ItemT>({
     windowSize,
   });
 
-  const constrainTranslation = useMemo(
-    () => createBoundsConstraint({ height, width }),
-    [width, height],
+  const syncActiveContentDimensions = useCallback(
+    (index = pendingIndexRef.current) => {
+      const viewport = viewportRef.current;
+      const fitted = fitItemDimensions(
+        resolveItemDimensions({
+          data: dataRef.current,
+          getItemKey: getItemKeyRef.current,
+          getItemDimensions: getItemDimensionsRef.current,
+          index,
+          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 = index;
+
+      const currentScale = scale.get();
+      const translationMode = resolveGeometrySyncTranslationMode(
+        previousGeometryIndex,
+        index,
+        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 constrained = clampTranslationToBounds({
+        contentHeight: fitted.height,
+        contentWidth: fitted.width,
+        height: viewport.height,
+        width: viewport.width,
+        scale: currentScale,
+        translateX: translateX.get(),
+        translateY: translateY.get(),
+      });
+      translateX.set(withTiming(constrained.translateX));
+      translateY.set(withTiming(constrained.translateY));
+    },
+    [contentHeight, contentWidth, scale, translateX, translateY],
+  );
+
+  const setItemDimensions = useCallback(
+    (index: number, item: ItemT, dimensions: GestureViewerItemDimensions) => {
+      if (
+        registerItemDimensions({
+          data: dataRef.current,
+          dimensions,
+          getItemKey: getItemKeyRef.current,
+          index,
+          item,
+          registry: itemDimensionsRef.current,
+        }) === 'updated' &&
+        index === pendingIndexRef.current
+      ) {
+        syncActiveContentDimensions(index);
+      }
+    },
+    [syncActiveContentDimensions],
+  );
+
+  const constrainTranslation = useCallback(
+    ({
+      scale: targetScale,
+      translateX: targetX,
+      translateY: targetY,
+    }: {
+      scale: number;
+      translateX: number;
+      translateY: number;
+    }) => {
+      'worklet';
+      return clampTranslationToBounds({
+        contentHeight: contentHeight.get(),
+        contentWidth: contentWidth.get(),
+        height,
+        scale: targetScale,
+        translateX: targetX,
+        translateY: targetY,
+        width,
+      });
+    },
+    [contentHeight, contentWidth, height, width],
   );
 
   const resetTransformState = useCallback(() => {
@@ -221,12 +371,16 @@ export const useGestureViewer = <ItemT>({
     rotation.set(0);
   }, [initialTranslateX, initialTranslateY, rotation, scale, startScale, translateX, translateY]);
 
-  const commitCurrentIndex = useCallback((nextIndex: number) => {
-    pendingIndexRef.current = nextIndex;
-    currentIndexRef.current = nextIndex;
-    setCurrentIndex(nextIndex);
-    managerRef.current?.notifyStateChange();
-  }, []);
+  const commitCurrentIndex = useCallback(
+    (nextIndex: number) => {
+      pendingIndexRef.current = nextIndex;
+      currentIndexRef.current = nextIndex;
+      syncActiveContentDimensions(nextIndex);
+      setCurrentIndex(nextIndex);
+      managerRef.current?.notifyStateChange();
+    },
+    [syncActiveContentDimensions],
+  );
 
   const commitVirtualIndexOnly = useCallback(
     (nextVirtualIndex: number) => {
@@ -360,6 +514,8 @@ export const useGestureViewer = <ItemT>({
   }, [navigateByDirection]);
 
   useGestureViewerManagerBridge({
+    contentHeight,
+    contentWidth,
     currentIndexRef,
     dataLengthRef,
     goToIndex: navigateToIndex,
@@ -433,9 +589,17 @@ export const useGestureViewer = <ItemT>({
     });
   }, [id]);
 
-  useEffect(() => {
+  useLayoutEffect(() => {
     dataRef.current = data;
-  }, [data]);
+    getItemDimensionsRef.current = getItemDimensions;
+    getItemKeyRef.current = getItemKey;
+    viewportRef.current = { height, width };
+    syncActiveContentDimensions();
+  }, [data, dataLength, getItemDimensions, getItemKey, height, syncActiveContentDimensions, width]);
+
+  useEffect(() => {
+    pruneItemDimensionsRegistry(itemDimensionsRef.current, dataLength);
+  }, [dataLength]);
 
   useEffect(() => {
     isZoomedRef.current = isZoomed;
@@ -910,6 +1074,8 @@ export const useGestureViewer = <ItemT>({
           }
 
           applyTapZoomAtPoint({
+            contentHeight: contentHeight.get(),
+            contentWidth: contentWidth.get(),
             x: event.x,
             y: event.y,
             width,
@@ -921,6 +1087,8 @@ export const useGestureViewer = <ItemT>({
           });
         }),
     [
+      contentHeight,
+      contentWidth,
       enableDoubleTapZoom,
       height,
       maxZoomScale,
@@ -1199,6 +1367,8 @@ export const useGestureViewer = <ItemT>({
 
   const onWebClick = useWebClickHandler({
     clearPendingWebSingleTap,
+    contentHeight,
+    contentWidth,
     emitSingleTap,
     enableDoubleTapZoom,
     getCurrentTapTarget,
@@ -1255,6 +1425,7 @@ export const useGestureViewer = <ItemT>({
     pageStride,
     renderWindowSlots,
     visualPage,
+    setItemDimensions,
     zoomGesture,
     zoomPinchGesture,
   };

package/src/useGestureViewerManagerBridge.ts

@@ -7,6 +7,8 @@ import { registry } from './GestureViewerRegistry';
 
 type UseGestureViewerManagerBridgeOptions = {
   currentIndexRef: RefObject<number>;
+  contentHeight: SharedValue<number>;
+  contentWidth: SharedValue<number>;
   dataLengthRef: RefObject<number>;
   goToIndex: (index: number, options?: GestureViewerNavigationOptions) => void;
   goToNext: () => void;
@@ -29,6 +31,8 @@ type UseGestureViewerManagerBridgeOptions = {
  */
 export function useGestureViewerManagerBridge({
   currentIndexRef,
+  contentHeight,
+  contentWidth,
   dataLengthRef,
   goToIndex,
   goToNext,
@@ -61,9 +65,27 @@ export function useGestureViewerManagerBridge({
 
     manager.setWidth(width);
     manager.setHeight(height);
-    manager.setZoomSharedValues(scale, translateX, translateY, maxZoomScale);
+    manager.setZoomSharedValues({
+      scale,
+      translateX,
+      translateY,
+      maxZoomScale,
+      contentWidth,
+      contentHeight,
+    });
     manager.setRotation(rotation);
-  }, [height, manager, maxZoomScale, rotation, scale, translateX, translateY, width]);
+  }, [
+    contentHeight,
+    contentWidth,
+    height,
+    manager,
+    maxZoomScale,
+    rotation,
+    scale,
+    translateX,
+    translateY,
+    width,
+  ]);
 
   useEffect(() => {
     if (!manager) {

package/src/useGestureViewerPaging.ts

@@ -184,7 +184,7 @@ export function useGestureViewerPaging({
       pagingAnimationActive.set(false);
       pagingGestureActive.set(false);
       pageTransitionLocked.set(false);
-      visualPage.set(withSpring(centerVirtualIndex, PAGE_SPRING_CONFIG));
+      visualPage.set(centerVirtualIndex);
       scheduleOnRN(setPageTransitioning, false);
     };
 

package/src/useWebClickHandler.ts

@@ -26,6 +26,8 @@ export type EmitSingleTap<ItemT> = (x: number, y: number, tapTarget?: WebTapTarg
 
 export type WebClickHandlerConfig<ItemT> = {
   clearPendingWebSingleTap: () => void;
+  contentHeight: SharedValue<number>;
+  contentWidth: SharedValue<number>;
   emitSingleTap: EmitSingleTap<ItemT>;
   enableDoubleTapZoom: boolean;
   getCurrentTapTarget: () => WebTapTarget<ItemT> | null;

package/src/useWebClickHandler.web.ts

@@ -27,6 +27,8 @@ export type EmitSingleTap<ItemT> = (x: number, y: number, tapTarget?: WebTapTarg
 
 export type WebClickHandlerConfig<ItemT> = {
   clearPendingWebSingleTap: () => void;
+  contentHeight: SharedValue<number>;
+  contentWidth: SharedValue<number>;
   emitSingleTap: EmitSingleTap<ItemT>;
   enableDoubleTapZoom: boolean;
   getCurrentTapTarget: () => WebTapTarget<ItemT> | null;
@@ -42,6 +44,8 @@ export type WebClickHandlerConfig<ItemT> = {
 
 export function createWebClickHandler<ItemT>({
   clearPendingWebSingleTap,
+  contentHeight,
+  contentWidth,
   emitSingleTap,
   enableDoubleTapZoom,
   getCurrentTapTarget,
@@ -78,6 +82,8 @@ export function createWebClickHandler<ItemT>({
     if (event.detail === 2) {
       clearPendingWebSingleTap();
       applyTapZoomAtPoint({
+        contentHeight: contentHeight.get(),
+        contentWidth: contentWidth.get(),
         x,
         y,
         width,
@@ -100,6 +106,8 @@ export function createWebClickHandler<ItemT>({
 
 export function useWebClickHandler<ItemT>({
   clearPendingWebSingleTap,
+  contentHeight,
+  contentWidth,
   emitSingleTap,
   enableDoubleTapZoom,
   getCurrentTapTarget,
@@ -116,6 +124,8 @@ export function useWebClickHandler<ItemT>({
     () =>
       createWebClickHandler({
         clearPendingWebSingleTap,
+        contentHeight,
+        contentWidth,
         emitSingleTap,
         enableDoubleTapZoom,
         getCurrentTapTarget,
@@ -130,6 +140,8 @@ export function useWebClickHandler<ItemT>({
       }),
     [
       clearPendingWebSingleTap,
+      contentHeight,
+      contentWidth,
       emitSingleTap,
       enableDoubleTapZoom,
       getCurrentTapTarget,

package/src/utils/index.ts

@@ -1,28 +1,61 @@
-export const createBoundsConstraint =
-  ({ width, height }: { width: number; height: number }) =>
-  ({
-    scale,
-    translateX,
-    translateY,
-  }: {
-    translateX: number;
-    translateY: number;
-    scale: number;
-  }) => {
-    'worklet';
+const isValidDimension = (value: number): boolean => {
+  'worklet';
+  return Number.isFinite(value) && value > 0;
+};
 
-    if (scale <= 1) {
-      return {
-        translateX,
-        translateY,
-      };
-    }
+export const resolveGeometrySyncTranslationMode = (
+  previousIndex: number | null,
+  nextIndex: number,
+  scale: number,
+): 'constrain' | 'none' | 'reset' => {
+  if (previousIndex !== null && previousIndex !== nextIndex) {
+    return 'reset';
+  }
 
-    const maxTranslateX = (width * scale - width) / 2;
-    const maxTranslateY = (height * scale - height) / 2;
+  return scale > 1 ? 'constrain' : 'none';
+};
 
+const clampTranslation = (value: number, max: number): number => {
+  'worklet';
+  const result = Math.max(-max, Math.min(max, value));
+  return result === 0 ? 0 : result;
+};
+
+export const clampTranslationToBounds = ({
+  width,
+  height,
+  contentWidth,
+  contentHeight,
+  scale,
+  translateX,
+  translateY,
+}: {
+  width: number;
+  height: number;
+  contentWidth?: number;
+  contentHeight?: number;
+  translateX: number;
+  translateY: number;
+  scale: number;
+}) => {
+  'worklet';
+
+  if (scale <= 1) {
     return {
-      translateX: Math.max(-maxTranslateX, Math.min(maxTranslateX, translateX)),
-      translateY: Math.max(-maxTranslateY, Math.min(maxTranslateY, translateY)),
+      translateX,
+      translateY,
     };
+  }
+
+  const baseWidth =
+    contentWidth !== undefined && isValidDimension(contentWidth) ? contentWidth : width;
+  const baseHeight =
+    contentHeight !== undefined && isValidDimension(contentHeight) ? contentHeight : height;
+  const maxTranslateX = Math.max(0, (baseWidth * scale - width) / 2);
+  const maxTranslateY = Math.max(0, (baseHeight * scale - height) / 2);
+
+  return {
+    translateX: clampTranslation(translateX, maxTranslateX),
+    translateY: clampTranslation(translateY, maxTranslateY),
   };
+};

package/src/utils/tapZoom.ts

@@ -1,11 +1,51 @@
 import type { SharedValue } from 'react-native-reanimated';
 import { Easing, withTiming } from 'react-native-reanimated';
 
+import { clampTranslationToBounds } from '.';
+
+export const getTapZoomTarget = ({
+  x,
+  y,
+  width,
+  height,
+  contentWidth,
+  contentHeight,
+  maxZoomScale,
+  scale,
+}: {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  contentWidth?: number;
+  contentHeight?: number;
+  maxZoomScale: number;
+  scale: number;
+}) => {
+  'worklet';
+  const nextScale = scale > 1 ? 1 : maxZoomScale;
+  if (nextScale <= 1) return { scale: nextScale, translateX: 0, translateY: 0 };
+  return {
+    scale: nextScale,
+    ...clampTranslationToBounds({
+      contentHeight,
+      contentWidth,
+      height,
+      scale: nextScale,
+      translateX: -(x - width / 2) * (nextScale - 1),
+      translateY: -(y - height / 2) * (nextScale - 1),
+      width,
+    }),
+  };
+};
+
 export const applyTapZoomAtPoint = ({
   x,
   y,
   width,
   height,
+  contentWidth,
+  contentHeight,
   maxZoomScale,
   scale,
   translateX,
@@ -15,6 +55,8 @@ export const applyTapZoomAtPoint = ({
   y: number;
   width: number;
   height: number;
+  contentWidth?: number;
+  contentHeight?: number;
   maxZoomScale: number;
   scale: SharedValue<number>;
   translateX: SharedValue<number>;
@@ -22,24 +64,22 @@ export const applyTapZoomAtPoint = ({
 }) => {
   'worklet';
 
-  const nextScale = scale.get() > 1 ? 1 : maxZoomScale;
+  const target = getTapZoomTarget({
+    contentHeight,
+    contentWidth,
+    height,
+    maxZoomScale,
+    scale: scale.get(),
+    width,
+    x,
+    y,
+  });
   const timingConfig = {
     duration: 300,
     easing: Easing.bezier(0.25, 0.1, 0.25, 1),
   };
 
-  if (nextScale > 1) {
-    const centerX = x - width / 2;
-    const centerY = y - height / 2;
-
-    // NOTE 확대로 밀려난 거리만큼 반대로 이동해서 탭 지점을 제자리에 유지
-    translateX.set(withTiming(-centerX * (nextScale - 1), timingConfig));
-    translateY.set(withTiming(-centerY * (nextScale - 1), timingConfig));
-    scale.set(withTiming(nextScale, timingConfig));
-    return;
-  }
-
-  translateX.set(withTiming(0, timingConfig));
-  translateY.set(withTiming(0, timingConfig));
-  scale.set(withTiming(nextScale, timingConfig));
+  translateX.set(withTiming(target.translateX, timingConfig));
+  translateY.set(withTiming(target.translateY, timingConfig));
+  scale.set(withTiming(target.scale, timingConfig));
 };