feat(panel): configurable animation duration

* 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,14 @@ <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>Animation duration</label>
+        <input type="number" ng-model="ctrl.duration">
+      </md-input-container>
+    </div>
   </div>
 
   <div class="demo-md-panel-content">

src/components/panel/demoPanelAnimations/script.js

@@ -11,6 +11,7 @@ function AnimationCtrl($mdPanel) {
   this.openFrom = 'button';
   this.closeTo = 'button';
   this.animationType = 'none';
+  this.duration = 300;
 }
 
 
@@ -22,6 +23,8 @@ AnimationCtrl.prototype.showDialog = function() {
 
   var animation = this._mdPanel.newPanelAnimation();
 
+  animation.duration(this.duration);
+
   switch(this.openFrom) {
     case 'button':
       animation.openFrom('.animation-target');

src/components/panel/panel.js

@@ -592,24 +592,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>
  */
 
 /**
@@ -658,6 +661,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                             *
@@ -2279,6 +2294,12 @@ function MdPanelAnimation($injector) {
 
   /** @private {string|{open: string, close: string}} */
   this._animationClass = '';
+
+  /** @private {number} */
+  this._openDuration;
+
+  /** @private {number} */
+  this._closeDuration;
 }
 
 
@@ -2326,6 +2347,27 @@ 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);
+    }
+  }
+
+  return this;
+
+  function toSeconds(value) {
+    if (angular.isNumber(value)) return value / 1000;
+  }
+};
 
 /**
  * Returns the element and bounds for the animation target.
@@ -2428,6 +2470,8 @@ MdPanelAnimation.prototype.animateOpen = function(panelEl) {
       }
   }
 
+  animationOptions.duration = this._openDuration;
+
   return animator
       .translate3d(panelEl, openFrom, openTo, animationOptions);
 };
@@ -2491,6 +2535,8 @@ MdPanelAnimation.prototype.animateClose = function(panelEl) {
       }
   }
 
+  reverseAnimationOptions.duration = this._closeDuration;
+
   return animator
       .translate3d(panelEl, closeFrom, closeTo, reverseAnimationOptions);
 };

src/components/panel/panel.spec.js

@@ -2149,6 +2149,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();
+      });
+    });
   });
 
   /**

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();
 
       }