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

package/lib/typescript/src/useGestureViewerPaging.web.d.ts

@@ -1,3 +1,3 @@
 import type { UseGestureViewerPagingArgs, UseGestureViewerPagingResult } from './useGestureViewerPaging.types';
-export declare function useGestureViewerPaging({ adjustedInitialIndex, autoPlay, autoPlayInterval, currentIndex, dataLength, enableDoubleTapZoom, enableHorizontalSwipe, enableLoop, height, onSingleTap, isRotated, isZoomed, itemSpacing, manager, maxZoomScale, scale, scrollTo, syncCurrentIndex, syncPendingIndex, translateX, translateY, width, }: UseGestureViewerPagingArgs): UseGestureViewerPagingResult;
+export declare function useGestureViewerPaging({ adjustedInitialIndex, autoPlay, autoPlayInterval, contentHeight, contentWidth, currentIndex, dataLength, enableDoubleTapZoom, enableHorizontalSwipe, enableLoop, height, onSingleTap, isRotated, isZoomed, itemSpacing, manager, maxZoomScale, scale, scrollTo, syncCurrentIndex, syncPendingIndex, translateX, translateY, width, }: UseGestureViewerPagingArgs): UseGestureViewerPagingResult;
 //# sourceMappingURL=useGestureViewerPaging.web.d.ts.map

package/lib/typescript/src/useGestureViewerPaging.web.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useGestureViewerPaging.web.d.ts","sourceRoot":"","sources":["../../../src/useGestureViewerPaging.web.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,0BAA0B,EAC1B,4BAA4B,EAE7B,MAAM,gCAAgC,CAAC;AAqBxC,wBAAgB,sBAAsB,CAAC,EACrC,oBAAoB,EACpB,QAAQ,EACR,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,mBAAmB,EACnB,qBAAqB,EACrB,UAAU,EACV,MAAM,EACN,WAAW,EACX,SAAS,EACT,QAAQ,EACR,WAAW,EACX,OAAO,EACP,YAAY,EACZ,KAAK,EACL,QAAQ,EACR,gBAAgB,EAChB,gBAAgB,EAChB,UAAU,EACV,UAAU,EACV,KAAK,GACN,EAAE,0BAA0B,GAAG,4BAA4B,CAiZ3D"}
+{"version":3,"file":"useGestureViewerPaging.web.d.ts","sourceRoot":"","sources":["../../../src/useGestureViewerPaging.web.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,0BAA0B,EAC1B,4BAA4B,EAE7B,MAAM,gCAAgC,CAAC;AAqBxC,wBAAgB,sBAAsB,CAAC,EACrC,oBAAoB,EACpB,QAAQ,EACR,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,mBAAmB,EACnB,qBAAqB,EACrB,UAAU,EACV,MAAM,EACN,WAAW,EACX,SAAS,EACT,QAAQ,EACR,WAAW,EACX,OAAO,EACP,YAAY,EACZ,KAAK,EACL,QAAQ,EACR,gBAAgB,EAChB,gBAAgB,EAChB,UAAU,EACV,UAAU,EACV,KAAK,GACN,EAAE,0BAA0B,GAAG,4BAA4B,CAma3D"}

package/lib/typescript/src/utils/index.d.ts

@@ -9,10 +9,13 @@ export declare const isFlashListLike: (component: React.ComponentType<any>) => b
  * and we also avoid wrapping RNGH-provided scrollables to prevent double-applying Gesture.Native() to components that already participate in RNGH.
  */
 export declare const shouldUseNativeScrollGesture: (platformOS: PlatformOSType, component: React.ComponentType<any>) => boolean;
-export declare const createBoundsConstraint: ({ width, height }: {
+export declare const clampIndex: (index: number | undefined, dataLength: number) => number;
+export declare const resolveGeometrySyncTranslationMode: (previousIndex: number | null, nextIndex: number, scale: number) => "constrain" | "none" | "reset";
+export declare const clampTranslationToBounds: ({ width, height, contentWidth, contentHeight, scale, translateX, translateY, }: {
     width: number;
     height: number;
-}) => ({ scale, translateX, translateY, }: {
+    contentWidth?: number;
+    contentHeight?: number;
     translateX: number;
     translateY: number;
     scale: number;
@@ -20,7 +23,8 @@ export declare const createBoundsConstraint: ({ width, height }: {
     translateX: number;
     translateY: number;
 };
-export declare const createLoopData: <T>(dataRef: React.RefObject<T[]>, enableLoop: boolean) => T[];
+export declare const createLoopData: <T>(data: T[], enableLoop: boolean) => T[];
+export declare const getLoopPhysicalIndex: (logicalIndex: number, dataLength: number, enableLoop: boolean) => number;
 export declare const getLoopAdjustedIndex: (scrollIndex: number, originalDataLength: number, enableLoop: boolean) => {
     realIndex: number;
     needsJump: boolean;

package/lib/typescript/src/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,cAAc,CAAC;AAMtB,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAIvE,eAAO,MAAM,gBAAgB,GAC3B,WAAW,KAAK,CAAC,aAAa,CAAC,GAAG,CAAC,KAClC,SAAS,IAAI,mBAC+C,CAAC;AAEhE,eAAO,MAAM,cAAc,GACzB,WAAW,KAAK,CAAC,aAAa,CAAC,GAAG,CAAC,KAClC,SAAS,IAAI,iBAAiB,CAAC,GAAG,CAMpC,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,WAAW,KAAK,CAAC,aAAa,CAAC,GAAG,CAAC,KAAG,OAMrE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,GACvC,YAAY,cAAc,EAC1B,WAAW,KAAK,CAAC,aAAa,CAAC,GAAG,CAAC,KAClC,OAEF,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAChC,mBAAmB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,MACpD,oCAIE;IACD,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;;;CAiBA,CAAC;AAEJ,eAAO,MAAM,cAAc,GAAI,CAAC,EAAE,SAAS,KAAK,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,YAAY,OAAO,KAAG,CAAC,EAevF,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAC/B,aAAa,MAAM,EACnB,oBAAoB,MAAM,EAC1B,YAAY,OAAO,KAClB;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAoB/D,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,SAAS,GAAG,EAAE,OAAO,MAAM;sBAC1C,MAAM,YAAY,OAAO;CAO3C,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,cAAc,CAAC;AAMtB,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAIvE,eAAO,MAAM,gBAAgB,GAC3B,WAAW,KAAK,CAAC,aAAa,CAAC,GAAG,CAAC,KAClC,SAAS,IAAI,mBAC+C,CAAC;AAEhE,eAAO,MAAM,cAAc,GACzB,WAAW,KAAK,CAAC,aAAa,CAAC,GAAG,CAAC,KAClC,SAAS,IAAI,iBAAiB,CAAC,GAAG,CAMpC,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,WAAW,KAAK,CAAC,aAAa,CAAC,GAAG,CAAC,KAAG,OAMrE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,GACvC,YAAY,cAAc,EAC1B,WAAW,KAAK,CAAC,aAAa,CAAC,GAAG,CAAC,KAClC,OAEF,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,OAAO,MAAM,GAAG,SAAS,EAAE,YAAY,MAAM,KAAG,MAY1E,CAAC;AAEF,eAAO,MAAM,kCAAkC,GAC7C,eAAe,MAAM,GAAG,IAAI,EAC5B,WAAW,MAAM,EACjB,OAAO,MAAM,KACZ,WAAW,GAAG,MAAM,GAAG,OAMzB,CAAC;AAoBF,eAAO,MAAM,wBAAwB,GAAI,gFAQtC;IACD,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;;;CAsBA,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,CAAC,EAAE,MAAM,CAAC,EAAE,EAAE,YAAY,OAAO,KAAG,CAAC,EAanE,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAC/B,cAAc,MAAM,EACpB,YAAY,MAAM,EAClB,YAAY,OAAO,KAClB,MAA0E,CAAC;AAE9E,eAAO,MAAM,oBAAoB,GAC/B,aAAa,MAAM,EACnB,oBAAoB,MAAM,EAC1B,YAAY,OAAO,KAClB;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAoB/D,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,SAAS,GAAG,EAAE,OAAO,MAAM;sBAC1C,MAAM,YAAY,OAAO;CAO3C,CAAC"}

package/lib/typescript/src/utils/tapZoom.d.ts

@@ -1,9 +1,25 @@
 import type { SharedValue } from 'react-native-reanimated';
-export declare const applyTapZoomAtPoint: ({ x, y, width, height, maxZoomScale, scale, translateX, translateY, }: {
+export declare 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;
+}) => {
+    scale: number;
+    translateX: number;
+    translateY: number;
+};
+export declare const applyTapZoomAtPoint: ({ x, y, width, height, contentWidth, contentHeight, maxZoomScale, scale, translateX, translateY, }: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    contentWidth?: number;
+    contentHeight?: number;
     maxZoomScale: number;
     scale: SharedValue<number>;
     translateX: SharedValue<number>;

package/lib/typescript/src/utils/tapZoom.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tapZoom.d.ts","sourceRoot":"","sources":["../../../../src/utils/tapZoom.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAG3D,eAAO,MAAM,mBAAmB,GAAI,uEASjC;IACD,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC3B,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAChC,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACjC,SAsBA,CAAC"}
+{"version":3,"file":"tapZoom.d.ts","sourceRoot":"","sources":["../../../../src/utils/tapZoom.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAK3D,eAAO,MAAM,gBAAgB,GAAI,4EAS9B;IACD,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;;;;CA2BA,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAAI,oGAWjC;IACD,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC3B,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAChC,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACjC,SAsBA,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-gesture-image-viewer",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "🖼️ React Native Image Viewer - Reanimated-powered image gestures with full control",
   "keywords": [
     "android",

package/src/GestureViewer.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useMemo, useRef } from 'react';
+import { useCallback, useEffect, useMemo, type ReactElement } from 'react';
 import {
   Platform,
   type ScrollViewProps,
@@ -10,10 +10,16 @@ import { Gesture, GestureDetector, GestureHandlerRootView } from 'react-native-g
 import Animated from 'react-native-reanimated';
 
 import { registry } from './GestureViewerRegistry';
-import type { GestureViewerProps } from './types';
+import type {
+  GestureViewerItemDimensions,
+  GestureViewerProps,
+  GestureViewerRenderItemInfo,
+} from './types';
 import { useGestureViewer } from './useGestureViewer';
 import {
+  clampIndex,
   createLoopData,
+  getLoopPhysicalIndex,
   isFlashListLike,
   isFlatListLike,
   isScrollViewLike,
@@ -21,6 +27,31 @@ import {
 } from './utils';
 import WebPagingFixStyle from './WebPagingFixStyle';
 
+type GestureViewerItemCellProps<ItemT> = {
+  item: ItemT;
+  index: number;
+  isActive: boolean;
+  renderItem: (item: ItemT, index: number, info: GestureViewerRenderItemInfo) => ReactElement;
+  setItemDimensions: (index: number, item: ItemT, dimensions: GestureViewerItemDimensions) => void;
+};
+
+function GestureViewerItemCell<ItemT>({
+  item,
+  index,
+  isActive,
+  renderItem,
+  setItemDimensions,
+}: GestureViewerItemCellProps<ItemT>) {
+  const registerItemDimensions = (dimensions: GestureViewerItemDimensions) => {
+    setItemDimensions(index, item, dimensions);
+  };
+
+  return renderItem(item, index, {
+    isActive,
+    setItemDimensions: registerItemDimensions,
+  });
+}
+
 export function GestureViewer<ItemT, LC>({
   id = 'default',
   data,
@@ -40,14 +71,14 @@ export function GestureViewer<ItemT, LC>({
 }: GestureViewerProps<ItemT, LC>) {
   const Component = ListComponent as React.ComponentType<any>;
 
-  const dataRef = useRef(data);
-
   const { width: screenWidth, height: screenHeight } = useWindowDimensions();
 
   const width = customWidth || screenWidth;
   const height = customHeight || screenHeight;
+  const normalizedInitialIndex = clampIndex(initialIndex, data.length);
+  const initialListIndex = getLoopPhysicalIndex(normalizedInitialIndex, data.length, enableLoop);
 
-  const loopData = useMemo(() => createLoopData(dataRef, enableLoop), [enableLoop]);
+  const loopData = useMemo(() => createLoopData(data, enableLoop), [data, enableLoop]);
 
   const isScrollView = isScrollViewLike(Component);
   const isFlashList = isFlashListLike(Component);
@@ -68,12 +99,13 @@ export function GestureViewer<ItemT, LC>({
     animatedStyle,
     backdropStyle,
     handleDismiss,
+    setItemDimensions,
   } = useGestureViewer({
     id,
     data,
     width,
     height,
-    initialIndex,
+    initialIndex: normalizedInitialIndex,
     itemSpacing,
     enableLoop,
     ...props,
@@ -106,9 +138,13 @@ export function GestureViewer<ItemT, LC>({
             styles.item,
           ]}
         >
-          {renderItemProp(item, index, {
-            isActive: index === activeListIndex && isFlashListCell,
-          })}
+          <GestureViewerItemCell
+            index={index}
+            isActive={index === activeListIndex && isFlashListCell}
+            item={item}
+            renderItem={renderItemProp}
+            setItemDimensions={setItemDimensions}
+          />
         </View>
       );
     },
@@ -121,6 +157,7 @@ export function GestureViewer<ItemT, LC>({
       isScrollView,
       isFlashList,
       height,
+      setItemDimensions,
     ],
   );
 
@@ -137,10 +174,6 @@ export function GestureViewer<ItemT, LC>({
     return Gesture.Race(dismissGesture, zoomGesture);
   }, [zoomGesture, dismissGesture]);
 
-  useEffect(() => {
-    dataRef.current = data;
-  }, [data]);
-
   useEffect(() => {
     registry.createManager(id);
 
@@ -225,9 +258,7 @@ export function GestureViewer<ItemT, LC>({
                     {...commonProps}
                     data={loopData}
                     renderItem={renderItem}
-                    initialScrollIndex={
-                      enableLoop && data.length > 1 ? initialIndex + 1 : initialIndex
-                    }
+                    initialScrollIndex={initialListIndex}
                     keyExtractor={keyExtractor}
                     {...(isFlashList
                       ? // NOTE - Deprecated estimatedItemSize for FlashList V2 (https://shopify.github.io/flash-list/docs/v2-changes#deprecated)

package/src/GestureViewerManager.ts

@@ -6,12 +6,22 @@ import type {
   GestureViewerEventType,
   GestureViewerState,
 } from './types';
-import { createBoundsConstraint, createScrollAction } from './utils';
+import { clampTranslationToBounds, createScrollAction } from './utils';
+
+type ZoomSharedValuesOptions = {
+  scale: SharedValue<number>;
+  translateX: SharedValue<number>;
+  translateY: SharedValue<number>;
+  maxZoomScale: number;
+  contentWidth?: SharedValue<number>;
+  contentHeight?: SharedValue<number>;
+};
 
 class GestureViewerManager {
   private currentIndex = 0;
   private dataLength = 0;
-  private width = 0;
+  private pagingStride = 0;
+  private viewportWidth = 0;
   private height = 0;
   private maxZoomScale = 2;
   private enableHorizontalSwipe = true;
@@ -22,6 +32,8 @@ class GestureViewerManager {
   private rotation: SharedValue<number> | null = null;
   private translateX: SharedValue<number> | null = null;
   private translateY: SharedValue<number> | null = null;
+  private contentWidth: SharedValue<number> | null = null;
+  private contentHeight: SharedValue<number> | null = null;
   private resetTransformCallback: (() => void) | null = null;
 
   private loopCallback: (() => void) | null = null;
@@ -105,8 +117,12 @@ class GestureViewerManager {
     this.enableLoop = enabled;
   }
 
-  setWidth(width: number) {
-    this.width = width;
+  setPagingStride(pagingStride: number) {
+    this.pagingStride = pagingStride;
+  }
+
+  setViewportWidth(width: number) {
+    this.viewportWidth = width;
   }
 
   setHeight(height: number) {
@@ -131,16 +147,20 @@ class GestureViewerManager {
     }
   }
 
-  setZoomSharedValues(
-    scale: SharedValue<number>,
-    translateX: SharedValue<number>,
-    translateY: SharedValue<number>,
-    maxZoomScale: number,
-  ) {
+  setZoomSharedValues({
+    scale,
+    translateX,
+    translateY,
+    maxZoomScale,
+    contentWidth,
+    contentHeight,
+  }: ZoomSharedValuesOptions) {
     this.scale = scale;
     this.translateX = translateX;
     this.translateY = translateY;
     this.maxZoomScale = maxZoomScale;
+    this.contentWidth = contentWidth ?? null;
+    this.contentHeight = contentHeight ?? null;
   }
 
   setResetTransformCallback(callback: (() => void) | null) {
@@ -203,10 +223,7 @@ class GestureViewerManager {
 
     this.scale.set(withTiming(nextScale));
 
-    const { translateX, translateY } = createBoundsConstraint({
-      width: this.width,
-      height: this.height,
-    })({
+    const { translateX, translateY } = this.constrainZoomTranslation({
       translateX: this.translateX.get(),
       translateY: this.translateY.get(),
       scale: nextScale,
@@ -237,10 +254,7 @@ class GestureViewerManager {
       return;
     }
 
-    const { translateX, translateY } = createBoundsConstraint({
-      width: this.width,
-      height: this.height,
-    })({
+    const { translateX, translateY } = this.constrainZoomTranslation({
       translateX: this.translateX.get(),
       translateY: this.translateY.get(),
       scale: nextScale,
@@ -273,7 +287,7 @@ class GestureViewerManager {
 
     this.cancelPendingLoopTransition();
 
-    const { scrollTo } = createScrollAction(this.listRef, this.width);
+    const { scrollTo } = createScrollAction(this.listRef, this.pagingStride || this.viewportWidth);
 
     if (this.enableLoop && this.dataLength > 1) {
       if (index < 0) {
@@ -358,9 +372,14 @@ class GestureViewerManager {
     this.currentIndex = 0;
     this.dataLength = 0;
     this.maxZoomScale = 2;
+    this.pagingStride = 0;
+    this.viewportWidth = 0;
+    this.height = 0;
     this.scale = null;
     this.translateX = null;
     this.translateY = null;
+    this.contentWidth = null;
+    this.contentHeight = null;
     this.rotation = null;
     this.resetTransformCallback = null;
     this.eventListeners.clear();
@@ -370,6 +389,26 @@ class GestureViewerManager {
     this.currentIndex = targetIndex;
     this.notifyListeners();
   };
+
+  private constrainZoomTranslation = ({
+    scale,
+    translateX,
+    translateY,
+  }: {
+    scale: number;
+    translateX: number;
+    translateY: number;
+  }) => {
+    return clampTranslationToBounds({
+      contentHeight: this.contentHeight?.get(),
+      contentWidth: this.contentWidth?.get(),
+      height: this.height,
+      scale,
+      translateX,
+      translateY,
+      width: this.viewportWidth || this.pagingStride,
+    });
+  };
 }
 
 export default GestureViewerManager;

package/src/index.tsx

@@ -6,6 +6,10 @@ export type {
   GestureViewerEventCallback,
   GestureViewerEventData,
   GestureViewerEventType,
+  GestureViewerItemDimensions,
+  GestureViewerItemDimensionsResolver,
+  GestureViewerItemKey,
+  GestureViewerItemKeyResolver,
   GestureViewerProps,
   GestureViewerRenderItemInfo,
   GestureViewerState,

package/src/itemDimensions.ts

@@ -0,0 +1,162 @@
+import type {
+  GestureViewerItemDimensions,
+  GestureViewerItemDimensionsResolver,
+  GestureViewerItemKey,
+  GestureViewerItemKeyResolver,
+} from './types';
+
+type ItemDimensionsRegistryEntry<ItemT> = Readonly<{
+  item: ItemT;
+  itemKey?: GestureViewerItemKey;
+  dimensions: GestureViewerItemDimensions;
+}>;
+
+export type ItemDimensionsRegistry<ItemT> = Map<number, ItemDimensionsRegistryEntry<ItemT>>;
+
+export const isValidItemDimensions = (
+  dimensions: GestureViewerItemDimensions | null | undefined,
+): dimensions is GestureViewerItemDimensions => {
+  return (
+    dimensions !== null &&
+    dimensions !== undefined &&
+    Number.isFinite(dimensions.width) &&
+    Number.isFinite(dimensions.height) &&
+    dimensions.width > 0 &&
+    dimensions.height > 0
+  );
+};
+
+const resolveItemKey = <ItemT>(
+  getItemKey: GestureViewerItemKeyResolver<ItemT> | undefined,
+  item: ItemT,
+  index: number,
+): GestureViewerItemKey | undefined => {
+  const itemKey = getItemKey?.(item, index);
+
+  if (typeof itemKey === 'string') {
+    return itemKey;
+  }
+
+  return typeof itemKey === 'number' && Number.isFinite(itemKey) ? itemKey : undefined;
+};
+
+const doesEntryMatchItem = <ItemT>(
+  entry: ItemDimensionsRegistryEntry<ItemT>,
+  item: ItemT,
+  itemKey: GestureViewerItemKey | undefined,
+): boolean => {
+  if (itemKey !== undefined && entry.itemKey !== undefined) {
+    return entry.itemKey === itemKey;
+  }
+
+  return Object.is(entry.item, item);
+};
+
+export const pruneItemDimensionsRegistry = <ItemT>(
+  registry: ItemDimensionsRegistry<ItemT>,
+  dataLength: number,
+): void => {
+  for (const index of registry.keys()) {
+    if (index < 0 || index >= dataLength) {
+      registry.delete(index);
+    }
+  }
+};
+
+export const resolveItemDimensions = <ItemT>({
+  registry,
+  data,
+  index,
+  getItemDimensions,
+  getItemKey,
+}: {
+  registry: ItemDimensionsRegistry<ItemT>;
+  data: readonly ItemT[];
+  index: number;
+  getItemDimensions?: GestureViewerItemDimensionsResolver<ItemT>;
+  getItemKey?: GestureViewerItemKeyResolver<ItemT>;
+}): GestureViewerItemDimensions | undefined => {
+  if (index < 0 || index >= data.length) {
+    return undefined;
+  }
+
+  // `as ItemT` restores the viewer's dense-list invariant, which TypeScript cannot infer from
+  // generic indexed access when `noUncheckedIndexedAccess` is enabled.
+  const item = data[index] as ItemT;
+  const registered = registry.get(index);
+  const itemKey = registered ? resolveItemKey(getItemKey, item, index) : undefined;
+
+  if (
+    registered &&
+    doesEntryMatchItem(registered, item, itemKey) &&
+    isValidItemDimensions(registered.dimensions)
+  ) {
+    return registered.dimensions;
+  }
+
+  const resolved = getItemDimensions?.(item, index);
+
+  if (isValidItemDimensions(resolved)) {
+    return resolved;
+  }
+
+  return undefined;
+};
+
+export const registerItemDimensions = <ItemT>({
+  registry,
+  data,
+  index,
+  item,
+  dimensions,
+  getItemKey,
+}: {
+  registry: ItemDimensionsRegistry<ItemT>;
+  data: readonly ItemT[];
+  index: number;
+  item: ItemT;
+  dimensions: GestureViewerItemDimensions;
+  getItemKey?: GestureViewerItemKeyResolver<ItemT>;
+}): boolean => {
+  if (index < 0 || index >= data.length || !isValidItemDimensions(dimensions)) {
+    return false;
+  }
+
+  // `as ItemT` restores the viewer's dense-list invariant, which TypeScript cannot infer from
+  // generic indexed access when `noUncheckedIndexedAccess` is enabled.
+  const currentItem = data[index] as ItemT;
+  const currentItemKey = resolveItemKey(getItemKey, currentItem, index);
+  const reportedItemKey = Object.is(currentItem, item)
+    ? currentItemKey
+    : resolveItemKey(getItemKey, item, index);
+  const hasMatchingKey =
+    currentItemKey !== undefined &&
+    reportedItemKey !== undefined &&
+    currentItemKey === reportedItemKey;
+
+  if (!Object.is(currentItem, item) && !hasMatchingKey) {
+    return false;
+  }
+
+  const registered = registry.get(index);
+
+  if (
+    registered &&
+    doesEntryMatchItem(registered, currentItem, currentItemKey) &&
+    registered.dimensions.width === dimensions.width &&
+    registered.dimensions.height === dimensions.height
+  ) {
+    return false;
+  }
+
+  registry.set(index, {
+    item: currentItem,
+    itemKey: currentItemKey,
+    dimensions: {
+      height: dimensions.height,
+      width: dimensions.width,
+    },
+  });
+
+  return true;
+};

package/src/types.ts

@@ -82,12 +82,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/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';
@@ -122,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;
@@ -149,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.