feat(panel): configurable animation duration (#9570)

* Adds the ability to specify the duration of an animation the panel.
* Fixes the `MdPanelAnimation` not showing up in the docs.

Fixes #9177.

Author: crisbeto

src/components/panel/demoPanelAnimations/index.html

@@ -1,26 +1,26 @@
 <div class="demo-md-panel-animation md-padding" ng-controller="AnimationCtrl as ctrl">
   <h2>Animations</h2>
   <div layout="row">
-    <div flex="33">
-      OpenFrom:
+    <div flex="25">
+      <h3>OpenFrom:</h3>
       <md-radio-group ng-model="ctrl.openFrom">
         <md-radio-button value="button">Button</md-radio-button>
         <md-radio-button value="corner">Top/Left Corner</md-radio-button>
         <md-radio-button value="bottom">Bottom Center</md-radio-button>
       </md-radio-group>
     </div>
 
-    <div flex="33">
-      CloseTo:
+    <div flex="25">
+      <h3>CloseTo:</h3>
       <md-radio-group ng-model="ctrl.closeTo">
         <md-radio-button value="button">Button</md-radio-button>
         <md-radio-button value="corner">Top/Left Corner</md-radio-button>
         <md-radio-button value="bottom">Bottom Center</md-radio-button>
       </md-radio-group>
     </div>
 
-    <div flex="33">
-      AnimationType:
+    <div flex="25">
+      <h3>AnimationType:</h3>
       <md-radio-group ng-model="ctrl.animationType">
         <md-radio-button value="none">None</md-radio-button>
         <md-radio-button value="slide">Slide</md-radio-button>
@@ -29,6 +29,33 @@ <h2>Animations</h2>
         <md-radio-button value="custom">Custom</md-radio-button>
       </md-radio-group>
     </div>
+
+    <div flex="25">
+      <h3>Duration:</h3>
+      <md-input-container>
+        <label>All animations</label>
+        <input
+          type="number"
+          ng-model="ctrl.duration"
+          ng-change="ctrl.separateDurations.open = ctrl.separateDurations.close = ctrl.duration">
+      </md-input-container>
+
+      <md-input-container>
+        <label>Open animation</label>
+        <input
+          type="number"
+          ng-model="ctrl.separateDurations.open"
+          ng-change="ctrl.duration = null">
+      </md-input-container>
+
+      <md-input-container>
+        <label>Close animation</label>
+        <input
+          type="number"
+          ng-model="ctrl.separateDurations.close"
+          ng-change="ctrl.duration = null">
+      </md-input-container>
+    </div>
   </div>
 
   <div class="demo-md-panel-content">

src/components/panel/demoPanelAnimations/script.js

@@ -10,7 +10,12 @@ function AnimationCtrl($mdPanel) {
   this._mdPanel = $mdPanel;
   this.openFrom = 'button';
   this.closeTo = 'button';
-  this.animationType = 'none';
+  this.animationType = 'scale';
+  this.duration = 300;
+  this.separateDurations = {
+    open: this.duration,
+    close: this.duration
+  };
 }
 
 
@@ -22,6 +27,8 @@ AnimationCtrl.prototype.showDialog = function() {
 
   var animation = this._mdPanel.newPanelAnimation();
 
+  animation.duration(this.duration || this.separateDurations);
+
   switch(this.openFrom) {
     case 'button':
       animation.openFrom('.animation-target');

src/components/panel/panel.js

@@ -636,24 +636,27 @@ angular
  *                               MdPanelAnimation                            *
  *****************************************************************************/
 
-
 /**
  * @ngdoc type
  * @name MdPanelAnimation
+ * @module material.components.panel
  * @description
  * Animation configuration object. To use, create an MdPanelAnimation with the
  * desired properties, then pass the object as part of $mdPanel creation.
  *
- * Example:
+ * @usage
  *
+ * <hljs lang="js">
  * var panelAnimation = new MdPanelAnimation()
  *     .openFrom(myButtonEl)
+ *     .duration(1337)
  *     .closeTo('.my-button')
  *     .withAnimation($mdPanel.animation.SCALE);
  *
  * $mdPanel.create({
  *   animation: panelAnimation
  * });
+ * </hljs>
  */
 
 /**
@@ -702,6 +705,18 @@ angular
  * @returns {!MdPanelAnimation}
  */
 
+/**
+ * @ngdoc method
+ * @name MdPanelAnimation#duration
+ * @description
+ * Specifies the duration of the animation in milliseconds. The `duration`
+ * method accepts either a number or an object with separate open and close
+ * durations.
+ *
+ * @param {number|{open: number, close: number}} duration
+ * @returns {!MdPanelAnimation}
+ */
+
 
 /*****************************************************************************
  *                                IMPLEMENTATION                             *
@@ -1466,13 +1481,19 @@ MdPanelRef.prototype._createBackdrop = function() {
             open: '_md-opaque-enter',
             close: '_md-opaque-leave'
           });
+
+      if (this.config.animation) {
+        backdropAnimation.duration(this.config.animation._rawDuration);
+      }
+
       var backdropConfig = {
         animation: backdropAnimation,
         attachTo: this.config.attachTo,
         focusOnOpen: false,
         panelClass: '_md-panel-backdrop',
         zIndex: this.config.zIndex - 1
       };
+
       this._backdropRef = this._$mdPanel.create(backdropConfig);
     }
     if (!this._backdropRef.isAttached) {
@@ -1610,7 +1631,7 @@ MdPanelRef.prototype._configureScrollListener = function() {
  * @private
  */
 MdPanelRef.prototype._configureTrapFocus = function() {
-  // Focus doesn't remain instead of the panel without this.
+  // Focus doesn't remain inside of the panel without this.
   this.panelEl.attr('tabIndex', '-1');
   if (this.config['trapFocus']) {
     var element = this.panelEl;
@@ -2449,6 +2470,15 @@ function MdPanelAnimation($injector) {
 
   /** @private {string|{open: string, close: string}} */
   this._animationClass = '';
+
+  /** @private {number} */
+  this._openDuration;
+
+  /** @private {number} */
+  this._closeDuration;
+
+  /** @private {number|{open: number, close: number}} */
+  this._rawDuration;
 }
 
 
@@ -2496,6 +2526,30 @@ MdPanelAnimation.prototype.closeTo = function(closeTo) {
   return this;
 };
 
+/**
+ * Specifies the duration of the animation in milliseconds.
+ * @param {number|{open: number, close: number}} duration
+ * @returns {!MdPanelAnimation}
+ */
+MdPanelAnimation.prototype.duration = function(duration) {
+  if (duration) {
+    if (angular.isNumber(duration)) {
+      this._openDuration = this._closeDuration = toSeconds(duration);
+    } else if (angular.isObject(duration)) {
+      this._openDuration = toSeconds(duration.open);
+      this._closeDuration = toSeconds(duration.close);
+    }
+  }
+
+  // Save the original value so it can be passed to the backdrop.
+  this._rawDuration = duration;
+
+  return this;
+
+  function toSeconds(value) {
+    if (angular.isNumber(value)) return value / 1000;
+  }
+};
 
 /**
  * Returns the element and bounds for the animation target.
@@ -2598,6 +2652,8 @@ MdPanelAnimation.prototype.animateOpen = function(panelEl) {
       }
   }
 
+  animationOptions.duration = this._openDuration;
+
   return animator
       .translate3d(panelEl, openFrom, openTo, animationOptions);
 };
@@ -2661,6 +2717,8 @@ MdPanelAnimation.prototype.animateClose = function(panelEl) {
       }
   }
 
+  reverseAnimationOptions.duration = this._closeDuration;
+
   return animator
       .translate3d(panelEl, closeFrom, closeTo, reverseAnimationOptions);
 };

src/components/panel/panel.spec.js

@@ -2211,6 +2211,38 @@ describe('$mdPanel', function() {
         expect(animation._closeTo.bounds).toEqual(inputRect);
       });
     });
+
+    describe('should determine the animation duration when', function() {
+      it('provided a value in milliseconds', function() {
+        var animation = mdPanelAnimation.duration(1300);
+
+        expect(animation._openDuration).toBe(1.3);
+      });
+
+      it('provided a number', function() {
+        var animation = mdPanelAnimation.duration(2000);
+
+        expect(animation._openDuration).toEqual(animation._closeDuration);
+        expect(animation._openDuration).toBe(2);
+      });
+
+      it('provided an object', function() {
+        var animation = mdPanelAnimation.duration({
+          open: 1200,
+          close: 600
+        });
+
+        expect(animation._openDuration).toBe(1.2);
+        expect(animation._closeDuration).toBe(0.6);
+      });
+
+      it('provided an invalid value', function() {
+        var animation = mdPanelAnimation.duration('very fast');
+
+        expect(animation._openDuration).toBeFalsy();
+        expect(animation._closeDuration).toBeFalsy();
+      });
+    });
   });
 
   describe('interceptor logic: ', function() {

src/core/util/animation/animate.js

@@ -21,11 +21,12 @@ function AnimateDomUtils($mdUtil, $q, $timeout, $mdConstant, $animateCss) {
      *
      */
     translate3d : function( target, from, to, options ) {
-      return $animateCss(target,{
-        from:from,
-        to:to,
-        addClass:options.transitionInClass,
-        removeClass:options.transitionOutClass
+      return $animateCss(target, {
+        from: from,
+        to: to,
+        addClass: options.transitionInClass,
+        removeClass: options.transitionOutClass,
+        duration: options.duration
       })
       .start()
       .then(function(){
@@ -40,7 +41,8 @@ function AnimateDomUtils($mdUtil, $q, $timeout, $mdConstant, $animateCss) {
         return $animateCss(target, {
            to: newFrom || from,
            addClass: options.transitionOutClass,
-           removeClass: options.transitionInClass
+           removeClass: options.transitionInClass,
+           duration: options.duration
         }).start();
 
       }