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

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_STATIC_SCALE_ATTRIBUTE_NAME = 'pan-static-scale';
+/** @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_STATIC_SCALE_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_STATIC_SCALE_ATTRIBUTE_NAME]
+        ? options[PAN_STATIC_SCALE_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_STATIC_SCALE_ATTRIBUTE_NAME]
+        ? options[PAN_STATIC_SCALE_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_STATIC_SCALE_ATTRIBUTE_NAME]
+        ? options[PAN_STATIC_SCALE_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_STATIC_SCALE_ATTRIBUTE_NAME]
+        ? options[PAN_STATIC_SCALE_ATTRIBUTE_NAME]
+        : calculateTargetScalingFactor(dimensions);
       dimensions.targetWidth *= scalingFactor;
       dimensions.targetHeight *= scalingFactor;
 

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

@@ -228,8 +228,7 @@ describes.realWin(
       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 +247,45 @@ 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 = 380 / 360;
+        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 static scale is set for ${panAnimation}.`, () => {
+        const staticFactor = 2;
+
+        const dimensions = setDimensions(380, 580, 360, 580);
+        expect(targetFitsWithinPage(dimensions)).to.be.true;
+
+        const calculatedKeyframes = presets[panAnimation].keyframes(
+          dimensions,
+          /* options */ {'pan-static-scale': staticFactor}
+        );
+
+        const expectedScaleFactorStr = `scale(${staticFactor})`;
+        calculatedKeyframes.forEach((keyframe) => {
+          expect(keyframe.transform).to.contain(expectedScaleFactorStr);
+        });
+      });
     });
   }
 );

extensions/amp-story/amp-story.md

@@ -729,6 +729,27 @@ _Example_: An image panning 50px down over 15 seconds.
 </amp-img>
 ```
 
+#### pan-static-scale [optional, only works with `pan-left`, `pan-right`, `pan-up`, & `pan-down` animations]
+
+The target scales to at least 25% larger than the page 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 sclaing factor calculation, and specify the 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-static-scale="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,10 @@ tags: {
     name: "translate-y"
     value_regex_casei: "[0-9]+px"
   }
+  attrs: {
+    name: "pan-static-scale"
+    value_regex_casei: "[0-9]+([.][0-9]+)?"
+  }
   attrs: {
     name: "justify-content"
     value: "center"