From fb16c4ff88ca39f355aab98759013dcdbf3eaeb4 Mon Sep 17 00:00:00 2001 From: Alex Lende Date: Mon, 25 Nov 2024 14:32:12 -0600 Subject: [PATCH] Update JSDoc --- .../src/components/iframe/use-scale-canvas.js | 59 ++++++++++++------- 1 file changed, 37 insertions(+), 22 deletions(-) diff --git a/packages/block-editor/src/components/iframe/use-scale-canvas.js b/packages/block-editor/src/components/iframe/use-scale-canvas.js index 4d6853f17a584..7fc73f148f5b2 100644 --- a/packages/block-editor/src/components/iframe/use-scale-canvas.js +++ b/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,9 +38,9 @@ function calculateScale( { /** * Compute the next scrollTop position after scaling the 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( transitionFrom, transitionTo ) { const { @@ -82,9 +91,9 @@ function computeScrollTopNext( 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,6 +181,7 @@ export function useScaleCanvas( { /** * The starting transition state for the zoom out animation. + * @type {import('react').RefObject} */ const transitionFrom = useRef( { scaleValue, @@ -179,6 +193,7 @@ export function useScaleCanvas( { /** * The ending transition state for the zoom out animation. + * @type {import('react').RefObject} */ const transitionTo = useRef( { scaleValue,