Delay scroll zoom anchoring until image fills viewport

Author: VanshajPoonia

frontend/src/components/Media/ZoomableImage.tsx

@@ -17,6 +17,7 @@ const ZOOM_FACTOR = 0.001;
 const LINE_HEIGHT_MULTIPLIER = 33;
 const MAX_SCALE = 8;
 const MIN_SCALE = 1;
+const SCALE_EPSILON = 0.0001;
 
 type Size = {
   width: number;
@@ -87,6 +88,23 @@ const getAxisPosition = (
     : centeredPosition;
 };
 
+const axisTouchesViewport = (scaledSize: number, viewportSize: number) =>
+  scaledSize >= viewportSize - SCALE_EPSILON;
+
+const getFirstViewportEdgeScale = (
+  baseDimensions: Size,
+  viewportWidth: number,
+  viewportHeight: number,
+) =>
+  Math.max(
+    MIN_SCALE,
+    Math.min(
+      MAX_SCALE,
+      viewportWidth / baseDimensions.width,
+      viewportHeight / baseDimensions.height,
+    ),
+  );
+
 export const ZoomableImage = forwardRef<ZoomableImageRef, ZoomableImageProps>(
   ({ imagePath, alt, rotation, resetSignal }, ref) => {
     const transformRef = useRef<ReactZoomPanPinchRef>(null);
@@ -111,26 +129,29 @@ export const ZoomableImage = forwardRef<ZoomableImageRef, ZoomableImageProps>(
       [],
     );
 
-    const getScaledDimensions = useCallback(
-      (scale: number): Size | null => {
-        if (!imageRef.current) return null;
+    const getBaseDimensions = useCallback((): Size | null => {
+      if (!imageRef.current) return null;
 
-        const renderedWidth = imageRef.current.clientWidth;
-        const renderedHeight = imageRef.current.clientHeight;
+      const renderedWidth = imageRef.current.clientWidth;
+      const renderedHeight = imageRef.current.clientHeight;
 
-        if (!renderedWidth || !renderedHeight) return null;
+      if (!renderedWidth || !renderedHeight) return null;
 
-        const effectiveDims = getEffectiveDimensions(
-          renderedWidth,
-          renderedHeight,
-        );
+      return getEffectiveDimensions(renderedWidth, renderedHeight);
+    }, [getEffectiveDimensions]);
+
+    const getScaledDimensions = useCallback(
+      (scale: number): Size | null => {
+        const baseDimensions = getBaseDimensions();
+
+        if (!baseDimensions) return null;
 
         return {
-          width: effectiveDims.width * scale,
-          height: effectiveDims.height * scale,
+          width: baseDimensions.width * scale,
+          height: baseDimensions.height * scale,
         };
       },
-      [getEffectiveDimensions],
+      [getBaseDimensions],
     );
 
     const getOverflowState = useCallback(
@@ -286,10 +307,42 @@ export const ZoomableImage = forwardRef<ZoomableImageRef, ZoomableImageProps>(
         const zoomChange = -e.deltaY * multiplier * factor;
 
         const currentScale = transformState.scale;
-        const newScale = Math.max(
+        const desiredScale = Math.max(
           MIN_SCALE,
           Math.min(MAX_SCALE, currentScale + zoomChange),
         );
+        const baseDimensions = getBaseDimensions();
+        if (!baseDimensions) return;
+
+        const currentDimensions = {
+          width: baseDimensions.width * currentScale,
+          height: baseDimensions.height * currentScale,
+        };
+        const currentTouchesViewport = {
+          width: axisTouchesViewport(
+            currentDimensions.width,
+            viewportRect.width,
+          ),
+          height: axisTouchesViewport(
+            currentDimensions.height,
+            viewportRect.height,
+          ),
+        };
+        const isZoomingIn = desiredScale > currentScale;
+
+        const shouldFitFirst =
+          isZoomingIn &&
+          !currentTouchesViewport.width &&
+          !currentTouchesViewport.height;
+        const firstViewportEdgeScale = getFirstViewportEdgeScale(
+          baseDimensions,
+          viewportRect.width,
+          viewportRect.height,
+        );
+        const newScale =
+          shouldFitFirst && desiredScale > firstViewportEdgeScale
+            ? firstViewportEdgeScale
+            : desiredScale;
 
         const scaledDimensions = getScaledDimensions(newScale);
         if (!scaledDimensions) return;
@@ -318,19 +371,23 @@ export const ZoomableImage = forwardRef<ZoomableImageRef, ZoomableImageProps>(
           mouseViewportX - (mouseViewportX - transformState.positionX) * ratio;
         const anchoredY =
           mouseViewportY - (mouseViewportY - transformState.positionY) * ratio;
+        const shouldAnchorX =
+          isOverImage && currentTouchesViewport.width && newOverflow.width;
+        const shouldAnchorY =
+          isOverImage && currentTouchesViewport.height && newOverflow.height;
 
         const targetX = shouldRecenter
           ? centeredX
           : getAxisPosition(
-              isOverImage ? anchoredX : centeredX,
+              shouldAnchorX ? anchoredX : centeredX,
               viewportRect.width,
               scaledDimensions.width,
               newOverflow.width,
             );
         const targetY = shouldRecenter
           ? centeredY
           : getAxisPosition(
-              isOverImage ? anchoredY : centeredY,
+              shouldAnchorY ? anchoredY : centeredY,
               viewportRect.height,
               scaledDimensions.height,
               newOverflow.height,
@@ -349,7 +406,12 @@ export const ZoomableImage = forwardRef<ZoomableImageRef, ZoomableImageProps>(
         resizeObserver.disconnect();
         wheelElement.removeEventListener('wheel', handleWheelInterceptor, true);
       };
-    }, [getOverflowState, getScaledDimensions, getViewportElement]);
+    }, [
+      getBaseDimensions,
+      getOverflowState,
+      getScaledDimensions,
+      getViewportElement,
+    ]);
 
     return (
       <div ref={wheelAreaRef} className="h-full w-full">

frontend/src/components/Media/__tests__/ZoomableImage.test.tsx

@@ -182,7 +182,7 @@ describe('ZoomableImage wheel behavior', () => {
     expectLatestTransform(290, 245, 1.1);
   });
 
-  test('anchors horizontally and keeps the vertical axis centered when only width overflows', () => {
+  test('centers and stops at the viewport edge before mouse anchoring begins', () => {
     const { wheelArea } = setupWheelScene({
       wrapperSize: { width: 800, height: 600 },
       imageSize: { width: 760, height: 300 },
@@ -194,10 +194,33 @@ describe('ZoomableImage wheel behavior', () => {
       clientY: 300,
     });
 
-    expectLatestTransform(-36, 135, 1.1);
+    expectLatestTransform(0, 142.10526315789474, 1.0526315789473684);
   });
 
-  test('anchors vertically and keeps the horizontal axis centered when only height overflows', () => {
+  test('anchors horizontally after the width has reached the viewport edge', () => {
+    mockTransformState.scale = 1.1;
+    mockTransformState.positionX = -18;
+    mockTransformState.positionY = 135;
+
+    const { wheelArea } = setupWheelScene({
+      wrapperSize: { width: 800, height: 600 },
+      imageSize: { width: 760, height: 300 },
+    });
+
+    fireEvent.wheel(wheelArea, {
+      deltaY: -100,
+      clientX: 750,
+      clientY: 300,
+    });
+
+    expectLatestTransform(-87.81818181818176, 120, 1.2000000000000002);
+  });
+
+  test('anchors vertically after the height has reached the viewport edge', () => {
+    mockTransformState.scale = 1.1;
+    mockTransformState.positionX = 235;
+    mockTransformState.positionY = -8;
+
     const { wheelArea } = setupWheelScene({
       wrapperSize: { width: 800, height: 600 },
       imageSize: { width: 300, height: 560 },
@@ -209,7 +232,7 @@ describe('ZoomableImage wheel behavior', () => {
       clientY: 550,
     });
 
-    expectLatestTransform(235, -16, 1.1);
+    expectLatestTransform(220, -58.72727272727275, 1.2000000000000002);
   });
 
   test('anchors both axes when width and height overflow', () => {