✨ [amp-animation] Adds a new attr that allows to override pan scaling factor. (#37965)

* Adds a new attr that allows amp-animation to override pan scaling factor.

* Update pan static scale attr variable name.

* Update the animation scaling factor test to cover all pan animations.

* Add the new attr into validation rule.

* Update attr regex and the nullish operator syntax.

* Add example in animateion-presets.html with pan-static-scale attr.

* Update the pan-static-scale validation rules and tests.

* Update pan-static-scale doc.

* Update attr name to pan-scaling-factor, and minor updates on test variables.

Author: jingfei

examples/amp-story/animations-presets.html

@@ -234,6 +234,23 @@ <h1>pan-up</h1>
         <h1>pan-down</h1>
       </amp-story-grid-layer>
     </amp-story-page>
+
+    <!-- ## Pan-Right with pan-scaling-factor attr -->
+    <amp-story-page id="pan-right-with-static-scale">
+      <amp-story-grid-layer template="vertical">
+        <h1>pan-right</h1>
+        <p>with pan-scaling-factor attr</p>
+        <div class="img-container" style="width: 120%">
+          <amp-img
+            animate-in="pan-right" animate-in-timing-function="ease-out"
+            pan-scaling-factor=".9"
+            translate-x="35px" animate-in-duration="3.5s"
+            id="img-pan-right" layout="responsive" src="https://picsum.photos/720/320?image=1026"
+            width="720" height="320">
+          </amp-img>
+        </div>
+      </amp-story-grid-layer>
+    </amp-story-page>
   </amp-story>
 </body>
 

extensions/amp-story/1.0/animation-presets.js

@@ -23,6 +23,8 @@ const SCALE_START_ATTRIBUTE_NAME = 'scale-start';
 /** @const {string} */
 const SCALE_END_ATTRIBUTE_NAME = 'scale-end';
 /** @const {string} */
+const PAN_SCALING_FACTOR_ATTRIBUTE_NAME = 'pan-scaling-factor';
+/** @const {string} */
 const TRANSLATE_X_ATTRIBUTE_NAME = 'translate-x';
 /** @const {string} */
 const TRANSLATE_Y_ATTRIBUTE_NAME = 'translate-y';
@@ -33,6 +35,7 @@ const DEFAULT_CURVE = '0.4, 0.4, 0.0, 1';
 export const PRESET_OPTION_ATTRIBUTES = [
   SCALE_START_ATTRIBUTE_NAME,
   SCALE_END_ATTRIBUTE_NAME,
+  PAN_SCALING_FACTOR_ATTRIBUTE_NAME,
   TRANSLATE_X_ATTRIBUTE_NAME,
   TRANSLATE_Y_ATTRIBUTE_NAME,
 ];
@@ -285,7 +288,9 @@ export const presets = {
     easing: 'linear',
     keyframes(dimensions, options) {
       const translateX = options[TRANSLATE_X_ATTRIBUTE_NAME];
-      const scalingFactor = calculateTargetScalingFactor(dimensions);
+      const scalingFactor =
+        options[PAN_SCALING_FACTOR_ATTRIBUTE_NAME] ??
+        calculateTargetScalingFactor(dimensions);
       dimensions.targetWidth *= scalingFactor;
       dimensions.targetHeight *= scalingFactor;
 
@@ -306,8 +311,9 @@ export const presets = {
     easing: 'linear',
     keyframes(dimensions, options) {
       const translateX = options[TRANSLATE_X_ATTRIBUTE_NAME];
-
-      const scalingFactor = calculateTargetScalingFactor(dimensions);
+      const scalingFactor =
+        options[PAN_SCALING_FACTOR_ATTRIBUTE_NAME] ??
+        calculateTargetScalingFactor(dimensions);
       dimensions.targetWidth *= scalingFactor;
       dimensions.targetHeight *= scalingFactor;
 
@@ -328,7 +334,9 @@ export const presets = {
     easing: 'linear',
     keyframes(dimensions, options) {
       const translateY = options[TRANSLATE_Y_ATTRIBUTE_NAME];
-      const scalingFactor = calculateTargetScalingFactor(dimensions);
+      const scalingFactor =
+        options[PAN_SCALING_FACTOR_ATTRIBUTE_NAME] ??
+        calculateTargetScalingFactor(dimensions);
       dimensions.targetWidth *= scalingFactor;
       dimensions.targetHeight *= scalingFactor;
 
@@ -349,7 +357,9 @@ export const presets = {
     easing: 'linear',
     keyframes(dimensions, options) {
       const translateY = options[TRANSLATE_Y_ATTRIBUTE_NAME];
-      const scalingFactor = calculateTargetScalingFactor(dimensions);
+      const scalingFactor =
+        options[PAN_SCALING_FACTOR_ATTRIBUTE_NAME] ??
+        calculateTargetScalingFactor(dimensions);
       dimensions.targetWidth *= scalingFactor;
       dimensions.targetHeight *= scalingFactor;
 

extensions/amp-story/1.0/test/test-full-bleed-animations.js

@@ -224,12 +224,12 @@ describes.realWin(
       const dimensions = setDimensions(380, 580, 360, 580);
       expect(targetFitsWithinPage(dimensions)).to.be.true;
 
-      const factorThatWillMakeTargetFitPage = 380 / 360;
+      const factorThatWillMakeTargetFitPage =
+        dimensions.pageWidth / dimensions.targetWidth;
       const factor = factorThatWillMakeTargetFitPage * 1.25;
       expect(calculateTargetScalingFactor(dimensions)).to.equal(factor);
 
-      const calculatedKeyframes = presets['pan-up'];
-      calculatedKeyframes.keyframes = calculatedKeyframes.keyframes(
+      const calculatedKeyframes = presets['pan-up'].keyframes(
         dimensions,
         /* options */ {}
       );
@@ -248,7 +248,46 @@ describes.realWin(
         },
       ];
 
-      expect(calculatedKeyframes.keyframes).to.deep.equal(expectedKeyframes);
+      expect(calculatedKeyframes).to.deep.equal(expectedKeyframes);
+    });
+
+    ['pan-up', 'pan-down', 'pan-right', 'pan-left'].forEach((panAnimation) => {
+      it(`Should scale the target for ${panAnimation}.`, () => {
+        const dimensions = setDimensions(380, 580, 360, 580);
+        expect(targetFitsWithinPage(dimensions)).to.be.true;
+
+        const factorThatWillMakeTargetFitPage =
+          dimensions.pageWidth / dimensions.targetWidth;
+        const factor = factorThatWillMakeTargetFitPage * 1.25;
+        expect(calculateTargetScalingFactor(dimensions)).to.equal(factor);
+
+        const calculatedKeyframes = presets[panAnimation].keyframes(
+          dimensions,
+          /* options */ {}
+        );
+
+        const expectedScaleFactorStr = `scale(${factor})`;
+        calculatedKeyframes.forEach((keyframe) => {
+          expect(keyframe.transform).to.contain(expectedScaleFactorStr);
+        });
+      });
+
+      it(`Should not scale the target if scaling factor is set for ${panAnimation}.`, () => {
+        const scalingFactor = 2;
+
+        const dimensions = setDimensions(380, 580, 360, 580);
+        expect(targetFitsWithinPage(dimensions)).to.be.true;
+
+        const calculatedKeyframes = presets[panAnimation].keyframes(
+          dimensions,
+          /* options */ {'pan-scaling-factor': scalingFactor}
+        );
+
+        const expectedScaleFactorStr = `scale(${scalingFactor})`;
+        calculatedKeyframes.forEach((keyframe) => {
+          expect(keyframe.transform).to.contain(expectedScaleFactorStr);
+        });
+      });
     });
   }
 );

extensions/amp-story/1.0/test/validator-amp-story-animations.html

@@ -37,6 +37,7 @@ <h1>ken-burns-effect</h1>
                src="https://picsum.photos/1024/768?image=1077"
                animate-in="pan-left"
                animate-in-duration="30s"
+               pan-scaling-factor=".9"
                layout="fixed"
                width="1024"
                height="768">

extensions/amp-story/1.0/test/validator-amp-story-animations.out

@@ -38,6 +38,7 @@ PASS
 |                 src="https://picsum.photos/1024/768?image=1077"
 |                 animate-in="pan-left"
 |                 animate-in-duration="30s"
+|                 pan-scaling-factor=".9"
 |                 layout="fixed"
 |                 width="1024"
 |                 height="768">

extensions/amp-story/amp-story.md

@@ -729,6 +729,27 @@ _Example_: An image panning 50px down over 15 seconds.
 </amp-img>
 ```
 
+#### pan-scaling-factor [optional, only works with `pan-left`, `pan-right`, `pan-up`, & `pan-down` animations]
+
+The target scales automatically in a pan-left/pan-right/pan-up/pan-down animation to ensure it does not go out of the target boundary when panning.
+
+Use this attribute to override the default scaling factor calculation, and specify a static scaling factor. The value must be greater than 0, and decimals are allowed.
+
+_Example_: An image scales 1.3x when panning.
+
+```html
+<amp-img
+  animate-in="pan-left"
+  pan-scaling-factor="1.3"
+  layout="fixed"
+  src="https://picsum.photos/720/320?image=1026"
+  width="720"
+  height="320"
+  alt="..."
+>
+</amp-img>
+```
+
 ### Sequencing animations
 
 To chain animations in sequence, use the `animate-in-after` attribute. All elements in a given chain must be present in the same `<amp-story-page>`. Elements without the `animate-in-after` attribute do not belong to a sequence chain, and will start independently on page entrance.

extensions/amp-story/validator-amp-story.protoascii

@@ -267,6 +267,12 @@ tags: {
     name: "translate-y"
     value_regex_casei: "[0-9]+px"
   }
+  attrs: {
+    name: "pan-scaling-factor"
+    # Allow float number such as "12.3", ".1", or "5."
+    # Note that string with only decimal point such as "." is not allowed.
+    value_regex_casei: "^([0-9]*[.]?[0-9]+)|([0-9]+[.]?[0-9]*)$"
+  }
   attrs: {
     name: "justify-content"
     value: "center"
@@ -362,6 +368,12 @@ tags: {
     name: "translate-y"
     value_regex_casei: "[0-9]+px"
   }
+  attrs: {
+    name: "pan-scaling-factor"
+    # Allow float number such as "12.3", ".1", or "5."
+    # Note that string with only decimal point such as "." is not allowed.
+    value_regex_casei: "^([0-9]*[.]?[0-9]+)|([0-9]+[.]?[0-9]*)$"
+  }
   reference_points: {
     tag_spec_name: "AMP-STORY-GRID-LAYER animate-in"
   }
@@ -566,6 +578,12 @@ tags: {
     name: "translate-y"
     value_regex_casei: "[0-9]+px"
   }
+  attrs: {
+    name: "pan-scaling-factor"
+    # Allow float number such as "12.3", ".1", or "5."
+    # Note that string with only decimal point such as "." is not allowed.
+    value_regex_casei: "^([0-9]*[.]?[0-9]+)|([0-9]+[.]?[0-9]*)$"
+  }
   reference_points: {
     tag_spec_name: "AMP-STORY-CTA-LAYER animate-in"
   }