Add some more function/file comments.

Author: Sepand Parhami

src/bezier-curve-utils.ts

@@ -24,15 +24,23 @@ export interface Curve {
 /**
  * A string representation of the curve that can be used as an
  * `animation-timing-function`.
+ * @param curve The curve to conver.
+ * @return A string in the form of 'cubic-bezier(x1, y1, x2, y2)'.
  */
 export function curveToString(curve: Curve): string {
   return `cubic-bezier(${curve.x1}, ${curve.y1}, ${curve.x2}, ${curve.y2})`;
 }
 
 /**
- * Gets the x/y value for the given control points for a given value of t.
+ * Gets the x/y value for the given control points for a given value of t. The
+ * first control point is always zero and the fourth is always one.
+ * @param c1 The second control point.
+ * @param c2 The third control point. 
+ * @param t
+ * @return The value at t.
  */
-export function getBezierCurveValue(c1: number, c2: number, t: number): number {
+export function getCubicBezierCurveValue(
+    c1: number, c2: number, t: number): number {
   const t_2 = t * t;
   const t_3 = t_2 * t;
   // Formula for 4 point bezier curve with c0 = 0 and c3 = 1.

src/img-dimensions.ts

@@ -30,7 +30,7 @@
  * @see https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit
  */
 
- interface Size {
+ export interface Size {
     width: number,
     height: number,
  }

src/imitation-img.ts

@@ -14,34 +14,31 @@
  * limitations under the License.
  */
 
-import {getRenderedDimensions} from './img-dimensions.js';
+import {Size, getRenderedDimensions} from './img-dimensions.js';
 
 /**
  * Creates a replacement for a given img, which should render the same as the
  * source img, but implemented with a cropping container and and img using
  * `object-fit: fill`. This can be used to implement a transition of the image.
  * The crop can be transitioned by scaling up the container while scaling down
  * the image by the inverse amount.
- * @param srcImg
- * @param srcImgRect
+ * @param srcImg The source img.
+ * @param srcImgRect The rect for `srcImg`. Can be provided if already
+ *    measured.
+ * @param imageDimensions The dimensions for the rendered image. Can be
+ *    provided if already measured.
  * @return The replacement container along with structural information.
  */
 export function createImitationImg(
   srcImg: HTMLImageElement,
   srcImgRect: ClientRect = srcImg.getBoundingClientRect(),
+  imageDimensions: Size = getRenderedDimensions(srcImg, srcImgRect),
 ): {
   translateElement: HTMLElement,
   scaleElement: HTMLElement,
   counterScaleElement: HTMLElement,
   img: HTMLImageElement,
-  imgWidth: number,
-  imgHeight: number,
 } {
-  const {
-    width: imgWidth,
-    height: imgHeight
-  } = getRenderedDimensions(srcImg, srcImgRect);
-
   const translateElement = document.createElement('div');
   const scaleElement = document.createElement('div');
   const counterScaleElement = document.createElement('div');
@@ -65,16 +62,14 @@ export function createImitationImg(
 
   Object.assign(img.style, {
     display: 'block',
-    width: `${imgWidth}px`,
-    height: `${imgHeight}px`,
+    width: `${imageDimensions.width}px`,
+    height: `${imageDimensions.height}px`,
   });
 
   return {
     translateElement,
     scaleElement,
     counterScaleElement,
     img,
-    imgWidth,
-    imgHeight,
   };
 }

src/testing/animation-test-controller.ts

@@ -14,6 +14,20 @@
  * limitations under the License.
  */
 
+/**
+ * @fileoverview Helpers for controlling animations within a test. This
+ * supports pausing all CSS-based animations on the page and then controlling
+ * them by manually moving the time offset within the animation.
+ * 
+ * During the test setup, you should call `setup()` and during the test tear
+ * down, you should call `tearDown()`. During a test case, you can call
+ * `offset(time)` to move all animations to a specific time. Note that this
+ * does not move them forward by `time` but rather to `time`.
+ * 
+ * Note: for animationend events to fire, you will need to wait for the browser
+ * to render (e.g. using requestAnimationFrame + setTimeout).
+ */
+
 /**
  * Sets all animations in a DOM subtree to a certain time into the animation.
  * This is done by adding CSS rules to target the Elements and their pseudo

src/transform-img/crop-animation.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import {Curve, getBezierCurveValue} from '../bezier-curve-utils.js';
+import {Curve, getCubicBezierCurveValue} from '../bezier-curve-utils.js';
 
 interface Scale {
   x: number,
@@ -36,13 +36,25 @@ const numSamples = 20;
 
 /**
  * Interpolates a value x% between a and b.
+ * @param a The start point.
+ * @param b The end point.
+ * @param x A percentage of the way between `a` to `b`.
  */
 function interpolate(a: number, b: number, x: number): number {
   return a + x * (b - a);
 }
 
 /**
  * Generates a CSS stylesheet for animating between two images.
+ * @param options
+ * @param options.startScale The starting scale for the animation.
+ * @param options.endScale The ending scale for the animation.
+ * @param options.curve The timing curve for how the crop should expand or
+ *    contract.
+ * @param options.scaleKeyframesName The names for the scaling keyframes.
+ * @param options.counterScaleKeyframesName The names for the counter-scaling
+ *    keyframes.
+ * @return CSS style text to perform the aniamtion.
  */
 function generateCropKeyframes({
   startScale,
@@ -71,9 +83,9 @@ function generateCropKeyframes({
   for (let i = 0; i <= numSamples; i++) {
     const t = i * (1 / numSamples);
     // The progress through the animation at this point.
-    const px = getBezierCurveValue(curve.x1, curve.x2, t);
+    const px = getCubicBezierCurveValue(curve.x1, curve.x2, t);
     // The output percentage at this point.
-    const py = getBezierCurveValue(curve.y1, curve.y2, t);
+    const py = getCubicBezierCurveValue(curve.y1, curve.y2, t);
     const keyframePercentage = px * 100;
     const scaleX = interpolate(startScale.x, endScale.x, py);
     const scaleY = interpolate(startScale.y, endScale.y, py);
@@ -106,6 +118,21 @@ function generateCropKeyframes({
  * content. This function sets up the animation by setting the appropriate
  * style properties on the desired Elements. The returned style text needs
  * to be inserted for the animation to run.
+ * @param options
+ * @param options.scaleElement The element to apply the scaling to. This should
+ *    have `overflow: hidden`,
+ * @param options.counterScaleElement The element to counteract the scaling.
+ *    This should be a child of `scaleElement`.
+ * @param options.largerRect The larger of the start/end cropping rects.
+ * @param options.smallerRect The smaller of the start/end cropping rects.
+ * @param options.curve The timing curve for how the crop should expand or
+ *    contract.
+ * @param options.style The styles to apply to both the `scaleElement` and
+ *    `counterScaleElement`.
+ * @param options.keyframesPrefix A prefix to use for the generated
+ *    keyframes to ensure they do not clash with existing keyframes.
+ * @param options.toLarger Whether or not `largerRect` is the rect we are
+ *    animating to.
  * @return CSS style text to perform the aniamtion.
  */
 export function prepareCropAnimation({

src/transform-img/scale-animation.ts

@@ -15,30 +15,36 @@
  */
 
 import {Curve, curveToString} from '../bezier-curve-utils.js';
-
+import {Size} from '../img-dimensions';
 
 /**
  * Prepares a scale animation. This function sets up the animation by setting 
  * the appropriate style properties on the desired Element. The returned style
  * text needs to be inserted for the animation to run.
+ * @param options
+ * @param options.element The element to apply the scaling to.
+ * @param options.largerImgDimensions The larger of the start/end image dimensions,
+ * @param options.smallerImgDimensions The smaller of the start/end cropping rects.
+ * @param options.curve The timing curve for the scaling.
+ * @param options.style The styles to apply to `element`.
+ * @param options.keyframesPrefix A prefix to use for the generated
+ *    keyframes to ensure they do not clash with existing keyframes.
+ * @param options.toLarger Whether or not `largerImgDimensions` are the
+ *    dimensions are we are animating to.
  * @return CSS style text to perform the aniamtion.
  */
 export function prepareScaleAnimation({
   element,
-  largerImgWidth,
-  largerImgHeight,
-  smallerImgWidth,
-  smallerImgHeight,
+  largerDimensions,
+  smallerDimensions,
   curve,
   styles,
   keyframesPrefix,
   toLarger,
 } : {
   element: HTMLElement,
-  largerImgWidth: number,
-  largerImgHeight: number,
-  smallerImgWidth: number,
-  smallerImgHeight: number,
+  largerDimensions: Size,
+  smallerDimensions: Size,
   curve: Curve,
   styles: Object,
   keyframesPrefix: string,
@@ -47,8 +53,8 @@ export function prepareScaleAnimation({
   const keyframesName = `${keyframesPrefix}-scale`;
 
   const scaleImgDown = {
-    x: smallerImgWidth / largerImgWidth,
-    y: smallerImgHeight / largerImgHeight,
+    x: smallerDimensions.width / largerDimensions.width,
+    y: smallerDimensions.height / largerDimensions.height,
   };
   const neutralScale = {x: 1, y: 1};
   const startImgScale = toLarger ? scaleImgDown : neutralScale;

src/transform-img/transform-img.ts

@@ -109,18 +109,14 @@ export function prepareImageAnimation({
   const keyframesPrefix = getKeyframesPrefix(keyframesNamespace);
   const toLarger = largerImg == targetImg;
 
+  const smallerImageDimensions = getRenderedDimensions(smallerImg, smallerRect);
+  const largerImageDimensions = getRenderedDimensions(largerImg, largerRect);
   const {
     translateElement,
     scaleElement,
     counterScaleElement,
     img,
-    imgWidth: largerImgWidth,
-    imgHeight: largerImgHeight,
-  } = createImitationImg(largerImg, largerRect);
-  const {
-    width: smallerImgWidth,
-    height: smallerImgHeight,
-  } = getRenderedDimensions(smallerImg, smallerRect);
+  } = createImitationImg(largerImg, largerRect, largerImageDimensions);
 
   const cropStyleText = prepareCropAnimation({
     scaleElement,
@@ -143,10 +139,8 @@ export function prepareImageAnimation({
   });
   const scaleStyleText = prepareScaleAnimation({
     element: img,
-    largerImgWidth,
-    largerImgHeight,
-    smallerImgWidth,
-    smallerImgHeight,
+    largerDimensions: largerImageDimensions,
+    smallerDimensions: smallerImageDimensions,
     curve,
     styles,
     keyframesPrefix,

src/transform-img/translate-animation.ts

@@ -22,6 +22,16 @@ import {Curve, curveToString} from '../bezier-curve-utils.js';
  * This function sets up the animation by setting the appropriate style
  * properties on the desired Element. The returned style text needs to be
  * inserted for the animation to run.
+ * @param options
+ * @param options.element The element to apply the scaling to.
+ * @param options.largerRect The larger of the start/end scaling rects.
+ * @param options.smallerRect The smaller of the start/end scaling rects.
+ * @param options.curve The timing curve for the scaling.
+ * @param options.style The styles to apply to `element`.
+ * @param options.keyframesPrefix A prefix to use for the generated
+ *    keyframes to ensure they do not clash with existing keyframes.
+ * @param options.toLarger Whether or not `largerRect` is the rect we are
+ *    animating to.
  * @return CSS style text to perform the aniamtion.
  */
 export function prepareTranslateAnimation({