Add useScaleCanvas: Web Animations API for zoom in/out animation

packages/block-editor/src/components/iframe/use-scale-canvas.js

@@ -4,15 +4,24 @@
 import { useEffect, useRef, useCallback } from '@wordpress/element';
 import { useReducedMotion, useResizeObserver } from '@wordpress/compose';
 
+/**
+ * @typedef {Object} TransitionState
+ * @property {number} scaleValue   Scale of the canvas.
+ * @property {number} frameSize    Size of the frame/offset around the canvas.
+ * @property {number} clientHeight ClientHeight of the iframe.
+ * @property {number} scrollTop    ScrollTop of the iframe.
+ * @property {number} scrollHeight ScrollHeight of the iframe.
+ */
+
 /**
  * Calculate the scale of the canvas.
  *
- * @param {Object} root0                     Object of options
- * @param {number} root0.frameSize           The size of the frame/offset around the canvas
- * @param {number} root0.containerWidth      Actual width of the canvas container
- * @param {number} root0.maxContainerWidth   Maximum width of the container to use for the scale calculation. This locks the canvas to a maximum width when zooming out.
- * @param {number} root0.scaleContainerWidth Width the of the container wrapping the canvas container
- * @return {number} scale value between 0 and/or equal to 1
+ * @param {Object} options                     Object of options
+ * @param {number} options.frameSize           Size of the frame/offset around the canvas
+ * @param {number} options.containerWidth      Actual width of the canvas container
+ * @param {number} options.maxContainerWidth   Maximum width of the container to use for the scale calculation. This locks the canvas to a maximum width when zooming out.
+ * @param {number} options.scaleContainerWidth Width the of the container wrapping the canvas container
+ * @return {number} Scale value between 0 and/or equal to 1
  */
 function calculateScale( {
 	frameSize,
@@ -29,17 +38,17 @@ function calculateScale( {
 /**
  * Compute the next scrollTop position after scaling the iframe content.
  *
- * @param {number} scrollHeight   Scaled height of the current iframe content.
- * @param {Object} transitionFrom The starting point of the transition
- * @param {Object} transitionTo   The ending state of the transition
- * @return {number} The next scrollTop position after scaling the iframe content.
+ * @param {TransitionState} transitionFrom Starting point of the transition
+ * @param {TransitionState} transitionTo   Ending state of the transition
+ * @return {number} Next scrollTop position after scaling the iframe content.
  */
-function computeScrollTopNext( scrollHeight, transitionFrom, transitionTo ) {
+function computeScrollTopNext( transitionFrom, transitionTo ) {
 	const {
 		clientHeight: prevClientHeight,
 		frameSize: prevFrameSize,
 		scaleValue: prevScale,
-		scrollTop: scrollTop,
+		scrollTop,
+		scrollHeight,
 	} = transitionFrom;
 	const { clientHeight, frameSize, scaleValue } = transitionTo;
 	// Step 0: Start with the current scrollTop.
@@ -82,9 +91,9 @@ function computeScrollTopNext( scrollHeight, transitionFrom, transitionTo ) {
 /**
  * Generate the keyframes to use for the zoom out animation.
  *
- * @param {Object} transitionFrom Object of the starting transition state
- * @param {Object} transitionTo   Object of the ending transition state
- * @return {Object[]} An array of keyframes to use for the animation
+ * @param {TransitionState} transitionFrom Starting transition state.
+ * @param {TransitionState} transitionTo   Ending transition state.
+ * @return {Object[]} An array of keyframes to use for the animation.
  */
 function getAnimationKeyframes( transitionFrom, transitionTo ) {
 	const {
@@ -110,20 +119,24 @@ function getAnimationKeyframes( transitionFrom, transitionTo ) {
 	];
 }
 
+/**
+ * @typedef {Object} ScaleCanvasResult
+ * @property {boolean} isZoomedOut             A boolean indicating if the canvas is zoomed out.
+ * @property {number}  scaleContainerWidth     The width of the container used to calculate the scale.
+ * @property {Object}  contentResizeListener   A resize observer for the content.
+ * @property {Object}  containerResizeListener A resize observer for the container.
+ */
+
 /**
  * Handles scaling the canvas for the zoom out mode and animating between
  * the states.
  *
- * @param {Object}        root0
- * @param {number}        root0.frameSize         The size of the frame around the content.
- * @param {Document}      root0.iframeDocument    The document of the iframe.
- * @param {number}        root0.maxContainerWidth The max width of the canvas to use as the starting scale point. Defaults to 750.
- * @param {number|string} root0.scale             The scale of the canvas. Can be an decimal between 0 and 1, 1, or 'auto-scaled'.
- * @return {Object} An object containing the following properties:
- *                  isZoomedOut: A boolean indicating if the canvas is zoomed out.
- *                  scaleContainerWidth: The width of the container used to calculate the scale.
- *                  contentResizeListener: A resize observer for the content.
- *                  containerResizeListener: A resize observer for the container.
+ * @param {Object}        options                   Object of options.
+ * @param {number}        options.frameSize         Size of the frame around the content.
+ * @param {Document}      options.iframeDocument    Document of the iframe.
+ * @param {number}        options.maxContainerWidth Max width of the canvas to use as the starting scale point. Defaults to 750.
+ * @param {number|string} options.scale             Scale of the canvas. Can be an decimal between 0 and 1, 1, or 'auto-scaled'.
+ * @return {ScaleCanvasResult} Properties of the result.
  */
 export function useScaleCanvas( {
 	frameSize,
@@ -168,22 +181,26 @@ export function useScaleCanvas( {
 
 	/**
 	 * The starting transition state for the zoom out animation.
+	 * @type {import('react').RefObject<TransitionState>}
 	 */
 	const transitionFrom = useRef( {
 		scaleValue,
 		frameSize,
 		clientHeight: 0,
 		scrollTop: 0,
+		scrollHeight: 0,
 	} );
 
 	/**
 	 * The ending transition state for the zoom out animation.
+	 * @type {import('react').RefObject<TransitionState>}
 	 */
 	const transitionTo = useRef( {
 		scaleValue,
 		frameSize,
 		clientHeight: 0,
 		scrollTop: 0,
+		scrollHeight: 0,
 	} );
 
 	/**
@@ -246,6 +263,9 @@ export function useScaleCanvas( {
 		iframeDocument.documentElement.classList.remove( 'zoom-out-animation' );
 
 		// Set the final scroll position that was just animated to.
+		// Disable reason: Eslint isn't smart enough to know that this is a
+		// DOM element. https://github.com/facebook/react/issues/31483
+		// eslint-disable-next-line react-compiler/react-compiler
 		iframeDocument.documentElement.scrollTop =
 			transitionTo.current.scrollTop;
 
@@ -381,14 +401,15 @@ export function useScaleCanvas( {
 					transitionFrom.current.clientHeight ?? clientHeight;
 				transitionFrom.current.scrollTop =
 					iframeDocument.documentElement.scrollTop;
+				transitionFrom.current.scrollHeight =
+					iframeDocument.documentElement.scrollHeight;
 
 				transitionTo.current = {
 					scaleValue,
 					frameSize,
 					clientHeight,
 				};
 				transitionTo.current.scrollTop = computeScrollTopNext(
-					iframeDocument.documentElement.scrollHeight,
 					transitionFrom.current,
 					transitionTo.current
 				);