feat($animate): allow $animate to pass custom styles into animations

$animate now supports an optional parameter which provides CSS styling
which will be provided into the CSS-based animations as well as any
custom animation functions. Once the animation is complete then the
styles will be applied directly to the element. If no animation is
detected or the `ngAnimate` module is not active then the styles
will be applied immediately.

BREAKING CHANGE: staggering animations that use transitions will now
always block the transition from starting (via `transition: 0s none`)
up until the stagger step kicks in. The former behaviour was that the
block was removed as soon as the pending class was added. This fix
allows for styles to be applied in the pending class without causing
an animation to trigger prematurely.

Author: matsko

src/ng/animate.js

@@ -122,7 +122,8 @@ var $AnimateProvider = ['$provide', function($provide) {
         }
       });
 
-      return (toAdd.length + toRemove.length) > 0 && [toAdd.length && toAdd, toRemove.length && toRemove];
+      return (toAdd.length + toRemove.length) > 0 &&
+        [toAdd.length ? toAdd : null, toRemove.length ? toRemove : null];
     }
 
     function cachedClassManipulation(cache, classes, op) {
@@ -144,6 +145,17 @@ var $AnimateProvider = ['$provide', function($provide) {
       return currentDefer.promise;
     }
 
+    function applyStyles(element, options) {
+      if (angular.isObject(options)) {
+        if (options.from || options.to) {
+          options = extend(options.from || {}, options.to || {});
+        } else {
+          delete options.tempClasses;
+        }
+        element.css(options);
+      }
+    }
+
     /**
      *
      * @ngdoc service
@@ -176,9 +188,11 @@ var $AnimateProvider = ['$provide', function($provide) {
        *   a child (if the after element is not present)
        * @param {DOMElement} after the sibling element which will append the element
        *   after itself
+       * @param {object=} options an optional collection of styles that will be applied to the element.
        * @return {Promise} the animation callback promise
        */
-      enter : function(element, parent, after) {
+      enter : function(element, parent, after, options) {
+        applyStyles(element, options);
         after ? after.after(element)
               : parent.prepend(element);
         return asyncPromise();
@@ -192,9 +206,10 @@ var $AnimateProvider = ['$provide', function($provide) {
        * @description Removes the element from the DOM. When the function is called a promise
        * is returned that will be resolved at a later time.
        * @param {DOMElement} element the element which will be removed from the DOM
+       * @param {object=} options an optional collection of options that will be applied to the element.
        * @return {Promise} the animation callback promise
        */
-      leave : function(element) {
+      leave : function(element, options) {
         element.remove();
         return asyncPromise();
       },
@@ -214,12 +229,13 @@ var $AnimateProvider = ['$provide', function($provide) {
        *   inserted into (if the after element is not present)
        * @param {DOMElement} after the sibling element where the element will be
        *   positioned next to
+       * @param {object=} options an optional collection of options that will be applied to the element.
        * @return {Promise} the animation callback promise
        */
-      move : function(element, parent, after) {
+      move : function(element, parent, after, options) {
         // Do not remove element before insert. Removing will cause data associated with the
         // element to be dropped. Insert will implicitly do the remove.
-        return this.enter(element, parent, after);
+        return this.enter(element, parent, after, options);
       },
 
       /**
@@ -232,20 +248,23 @@ var $AnimateProvider = ['$provide', function($provide) {
        * @param {DOMElement} element the element which will have the className value
        *   added to it
        * @param {string} className the CSS class which will be added to the element
+       * @param {object=} options an optional collection of options that will be applied to the element.
        * @return {Promise} the animation callback promise
        */
-      addClass : function(element, className) {
-        return this.setClass(element, className, []);
+      addClass : function(element, className, options) {
+        return this.setClass(element, className, [], options);
       },
 
-      $$addClassImmediately : function(element, className) {
+      $$addClassImmediately : function(element, className, options) {
         element = jqLite(element);
         className = !isString(className)
                         ? (isArray(className) ? className.join(' ') : '')
                         : className;
         forEach(element, function (element) {
           jqLiteAddClass(element, className);
         });
+        applyStyles(element, options);
+        return asyncPromise();
       },
 
       /**
@@ -258,20 +277,22 @@ var $AnimateProvider = ['$provide', function($provide) {
        * @param {DOMElement} element the element which will have the className value
        *   removed from it
        * @param {string} className the CSS class which will be removed from the element
+       * @param {object=} options an optional collection of options that will be applied to the element.
        * @return {Promise} the animation callback promise
        */
-      removeClass : function(element, className) {
-        return this.setClass(element, [], className);
+      removeClass : function(element, className, options) {
+        return this.setClass(element, [], className, options);
       },
 
-      $$removeClassImmediately : function(element, className) {
+      $$removeClassImmediately : function(element, className, options) {
         element = jqLite(element);
         className = !isString(className)
                         ? (isArray(className) ? className.join(' ') : '')
                         : className;
         forEach(element, function (element) {
           jqLiteRemoveClass(element, className);
         });
+        applyStyles(element, options);
         return asyncPromise();
       },
 
@@ -286,9 +307,10 @@ var $AnimateProvider = ['$provide', function($provide) {
        *   removed from it
        * @param {string} add the CSS classes which will be added to the element
        * @param {string} remove the CSS class which will be removed from the element
+       * @param {object=} options an optional collection of options that will be applied to the element.
        * @return {Promise} the animation callback promise
        */
-      setClass : function(element, add, remove) {
+      setClass : function(element, add, remove, options) {
         var self = this;
         var STORAGE_KEY = '$$animateClasses';
         var createdCache = false;
@@ -297,9 +319,12 @@ var $AnimateProvider = ['$provide', function($provide) {
         var cache = element.data(STORAGE_KEY);
         if (!cache) {
           cache = {
-            classes: {}
+            classes: {},
+            options : options
           };
           createdCache = true;
+        } else if (options && cache.options) {
+          cache.options = angular.extend(cache.options || {}, options);
         }
 
         var classes = cache.classes;
@@ -320,7 +345,7 @@ var $AnimateProvider = ['$provide', function($provide) {
             if (cache) {
               var classes = resolveElementClasses(element, cache.classes);
               if (classes) {
-                self.$$setClassImmediately(element, classes[0], classes[1]);
+                self.$$setClassImmediately(element, classes[0], classes[1], cache.options);
               }
             }
 
@@ -332,9 +357,10 @@ var $AnimateProvider = ['$provide', function($provide) {
         return cache.promise;
       },
 
-      $$setClassImmediately : function(element, add, remove) {
+      $$setClassImmediately : function(element, add, remove, options) {
         add && this.$$addClassImmediately(element, add);
         remove && this.$$removeClassImmediately(element, remove);
+        applyStyles(element, options);
         return asyncPromise();
       },