Reorganize files, update code documentation a bit.

Author: Sepand Parhami

index.ts

@@ -0,0 +1 @@
+export {prepareImageAnimation} from './src/transform-img/index.js';

src/img-dimensions.ts

@@ -15,9 +15,18 @@
  */
 
 /**
- * @fileoverview Provides a function the dimensions of the rendered image
- * inside of an <img> tag.
- *
+ * @fileoverview Provides a function to calculate the dimensions of the
+ * rendered image  inside of an `<img>` Element. For example, if you have an
+ * `<img>` with `object-fit: contain` and an image that is portrait inside of
+ * an `<img>` with landscape dimensions, you will have something looks like:
+ *  _____________
+ * |   |     |   |
+ * | i |  r  | i |
+ * |___|_____|___|
+ * 
+ * Where the area denoted by `r` is the rendered image and the areas denoted
+ * by `i` are extra spacing on either side of the rendered image to center it
+ * within the containing `<img>` Element.
  * @see https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit
  */
 

src/replacement-img.ts

@@ -20,7 +20,7 @@ import {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 scaping down
+ * The crop can be transitioned by scaling up the container while scaling down
  * the image by the inverse amount.
  * @param srcImg
  * @param srcImgRect

src/test-img-dimensions.ts

@@ -15,7 +15,7 @@
  */
 
 import {getRenderedDimensions} from './img-dimensions';
-import {imgLoadPromise} from './utils';
+import {imgLoadPromise} from './testing/utils';
 
 const {expect} = chai;
 const fourByThreeUri = 'data:image/gif;base64,R0lGODdhBAADAIAAAP///////ywAAAAABAADAAACA4SPVgA7';

src/test-replacement-img.ts

@@ -15,7 +15,7 @@
  */
 
 import {createReplacement} from './replacement-img';
-import {imgLoadPromise} from './utils';
+import {imgLoadPromise} from './testing/utils';
 
 const {expect} = chai;
 const fourByThreeUri = 'data:image/gif;base64,R0lGODdhBAADAIAAAP///////ywAAAAABAADAAACA4SPVgA7';

src/animation-test-controller.ts renamed to src/testing/animation-test-controller.ts

@@ -0,0 +1,30 @@
+# Transform Img
+
+## Overview
+
+This directory contains logic for transforming an image from one location to
+another. The animation is comprised of 3 parts:
+
+* Scaling up the image in the x and y directions to the final scale
+* Translating the image in the x and y directions to the final location
+* Changing the crop in the x and y directions to the final crop
+
+Each of these are implemented in seprate file.
+
+## Implementation
+
+In order to have the animation perform well, including on older devices, only
+CPU accelrated animatable properties. As a result, the 'crop' portion of the
+animation is implemented by scaling up a cropping container (with 
+`overflow: hidden`) and counteracting the scaling with an inverse scale on a
+child container.
+
+The animations are implemented by taking the larger size and animating using
+that as a reference point for scaling. That is, when the transition is where
+the larger image is (whether that is the starting state or ending state), the
+scale values will all be `1.0`. This is done to avoid rounding errors from
+the various scale animations from having a user perceivable impact. The errors
+are much less or not at all noticable for the smaller image. When we are going
+from a small image to a large image (say scaling by 5x), we will animate the
+scale from `0.2` to `1.0`. If we were to run the reverse operation, we would
+scale from `1.0` to `0.2`.

src/test-animation-test-controller.ts renamed to src/testing/test-animation-test-controller.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import {Curve, getBezierCurveValue} from './bezier-curve-utils.js';
+import {Curve, getBezierCurveValue} from '../bezier-curve-utils.js';
 
 interface Scale {
   x: number,
@@ -60,9 +60,14 @@ function generateCropKeyframes({
   let scaleElementKeyframes = '';
   let counterScaleKeyframes = '';
 
-  // Generates one step for each frame. This is just a guide, the actual values
-  // will be interoplated from these, but just to make sure we have enough
-  // steps for the browser to work with to make it smooth.
+  /*
+   * Generates keyframes for the browser to interpolate from. We simply need to
+   * make sure there are enough for this to be smooth. Note: we are generating
+   * keyframes as a function of `t` in the Bezier curve formula and not time.
+   * The keyframes generated will be more clustered when the output (y) value
+   * is more rapidly changing, so we should not have too much error no matter
+   * which two keyframes the browser interpolates between.
+   */ 
   for (let i = 0; i <= numSamples; i++) {
     const t = i * (1 / numSamples);
     // The progress through the animation at this point.
@@ -95,6 +100,14 @@ function generateCropKeyframes({
   `;
 }
 
+/**
+ * Prepares a crop animation. This is done by scaling up the croping container
+ * while scaling down a nested container to preserve the scale of the inner
+ * 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.
+ * @return CSS style text to perform the aniamtion.
+ */
 export function prepareCropAnimation({
   scaleElement,
   counterScaleElement,