feat(ngAnimate): introduce ngAnimateSwap directive

Author: matsko

angularFiles.js

@@ -101,6 +101,7 @@ var angularFiles = {
       'src/ngAnimate/animateQueue.js',
       'src/ngAnimate/animateRunner.js',
       'src/ngAnimate/animation.js',
+      'src/ngAnimate/ngAnimateSwap.js',
       'src/ngAnimate/module.js'
     ],
     'ngCookies': [

src/ngAnimate/module.js

@@ -2,6 +2,7 @@
 
 /* global angularAnimateModule: true,
 
+   ngAnimateSwapDirective,
    $$AnimateAsyncRunFactory,
    $$rAFSchedulerFactory,
    $$AnimateChildrenDirective,
@@ -738,6 +739,8 @@
  * Click here {@link ng.$animate to learn more about animations with `$animate`}.
  */
 angular.module('ngAnimate', [])
+  .directive('ngAnimateSwap', ngAnimateSwapDirective)
+
   .directive('ngAnimateChildren', $$AnimateChildrenDirective)
   .factory('$$rAFScheduler', $$rAFSchedulerFactory)
 

src/ngAnimate/ngAnimateSwap.js

@@ -0,0 +1,110 @@
+'use strict';
+
+/**
+ * @ngdoc directive
+ * @name ngAnimateSwap
+ * @restrict A
+ * @scope
+ *
+ * @description
+ *
+ * ngAnimateSwap is a animation-oriented directive that allows for the container to
+ * be removed and entered in whenever the associated expression changes. A
+ * common usecase for this directive is a rotating banner component which
+ * contains one image being present at a time. When the active image changes
+ * then the old image will perform a `leave` animation and the new element
+ * will be inserted via an `enter` animation.
+ *
+ * @example
+ * <example name="ngAnimateSwap-directive" module="ngAnimateSwapExample"
+ *          deps="angular-animate.js"
+ *          animations="true" fixBase="true">
+ *   <file name="index.html">
+ *     <div class="container" ng-controller="AppCtrl">
+ *       <div ng-animate-swap="number" class="cell swap-animation" ng-class="colorClass(number)">
+ *         {{ number }}
+ *       </div>
+ *     </div>
+ *   </file>
+ *   <file name="script.js">
+ *     angular.module('ngAnimateSwapExample', ['ngAnimate'])
+ *       .controller('AppCtrl', ['$scope', '$interval', function($scope, $interval) {
+ *         $scope.number = 0;
+ *         $interval(function() {
+ *           $scope.number++;
+ *         }, 1000);
+ *
+ *         var colors = ['red','blue','green','yellow','orange'];
+ *         $scope.colorClass = function(number) {
+ *           return colors[number % colors.length];
+ *         };
+ *       }]);
+ *   </file>
+ *  <file name="animations.css">
+ *  .container {
+ *    height:250px;
+ *    width:250px;
+ *    position:relative;
+ *    overflow:hidden;
+ *    border:2px solid black;
+ *  }
+ *  .container .cell {
+ *    font-size:150px;
+ *    text-align:center;
+ *    line-height:250px;
+ *    position:absolute;
+ *    top:0;
+ *    left:0;
+ *    right:0;
+ *    border-bottom:2px solid black;
+ *  }
+ *  .swap-animation.ng-enter, .swap-animation.ng-leave {
+ *    transition:0.5s linear all;
+ *  }
+ *  .swap-animation.ng-enter {
+ *    top:-250px;
+ *  }
+ *  .swap-animation.ng-enter-active {
+ *    top:0px;
+ *  }
+ *  .swap-animation.ng-leave {
+ *    top:0px;
+ *  }
+ *  .swap-animation.ng-leave-active {
+ *    top:250px;
+ *  }
+ *  .red { background:red; }
+ *  .green { background:green; }
+ *  .blue { background:blue; }
+ *  .yellow { background:yellow; }
+ *  .orange { background:orange; }
+ *  </file>
+ * </example>
+ */
+var ngAnimateSwapDirective = ['$animate', '$rootScope', function($animate, $rootScope) {
+  return {
+    restrict: 'A',
+    transclude: 'element',
+    terminal: true,
+    priority: 600, // we use 600 here to ensure that the directive is caught before others
+    link: function(scope, $element, attrs, ctrl, $transclude) {
+      var previousElement, previousScope;
+      scope.$watchCollection(attrs.ngAnimateSwap || attrs['for'], function(value) {
+        if (previousElement) {
+          $animate.leave(previousElement);
+        }
+        if (previousScope) {
+          previousScope.$destroy();
+          previousScope = null;
+        }
+        if (value || value === 0) {
+          previousScope = scope.$new();
+          $transclude(previousScope, function(element) {
+            previousElement = element;
+            $animate.enter(element, null, $element);
+          });
+        }
+      });
+    }
+  };
+}];

test/ngAnimate/ngAnimateSwapSpec.js

@@ -0,0 +1,166 @@
+'use strict';
+
+describe("ngAnimateSwap", function() {
+
+  beforeEach(module('ngAnimate'));
+  beforeEach(module('ngAnimateMock'));
+
+  var element;
+  afterEach(function() {
+    dealoc(element);
+  });
+
+  var $rootScope, $compile, $animate;
+  beforeEach(inject(function(_$rootScope_, _$animate_, _$compile_) {
+    $rootScope = _$rootScope_;
+    $animate = _$animate_;
+    $compile = _$compile_;
+
+    $animate.enabled(false);
+  }));
+
+
+  it('should render a new container when the expression changes', inject(function() {
+    element = $compile('<div><div ng-animate-swap="exp">{{ exp }}</div></div>')($rootScope);
+    $rootScope.$digest();
+
+    var first = element.find('div')[0];
+    expect(first).toBeFalsy();
+
+    $rootScope.exp = 'yes';
+    $rootScope.$digest();
+
+    var second = element.find('div')[0];
+    expect(second.textContent).toBe('yes');
+
+    $rootScope.exp = 'super';
+    $rootScope.$digest();
+
+    var third = element.find('div')[0];
+    expect(third.textContent).toBe('super');
+    expect(third).not.toEqual(second);
+    expect(second.parentNode).toBeFalsy();
+  }));
+
+  it('should render a new container only when the expression property changes', inject(function() {
+    element = $compile('<div><div ng-animate-swap="exp.prop">{{ exp.value }}</div></div>')($rootScope);
+    $rootScope.exp = {
+      prop: 'hello',
+      value: 'world'
+    };
+    $rootScope.$digest();
+
+    var one = element.find('div')[0];
+    expect(one.textContent).toBe('world');
+
+    $rootScope.exp.value = 'planet';
+    $rootScope.$digest();
+
+    var two = element.find('div')[0];
+    expect(two.textContent).toBe('planet');
+    expect(two).toBe(one);
+
+    $rootScope.exp.prop = 'goodbye';
+    $rootScope.$digest();
+
+    var three = element.find('div')[0];
+    expect(three.textContent).toBe('planet');
+    expect(three).not.toBe(two);
+  }));
+
+  it('should watch the expression as a collection', inject(function() {
+    element = $compile('<div><div ng-animate-swap="exp">{{ exp.a }} {{ exp.b }} {{ exp.c }}</div></div>')($rootScope);
+    $rootScope.exp = {
+      a: 1,
+      b: 2
+    };
+    $rootScope.$digest();
+
+    var one = element.find('div')[0];
+    expect(one.textContent.trim()).toBe('1 2');
+
+    $rootScope.exp.a++;
+    $rootScope.$digest();
+
+    var two = element.find('div')[0];
+    expect(two.textContent.trim()).toBe('2 2');
+    expect(two).not.toEqual(one);
+
+    $rootScope.exp.c = 3;
+    $rootScope.$digest();
+
+    var three = element.find('div')[0];
+    expect(three.textContent.trim()).toBe('2 2 3');
+    expect(three).not.toEqual(two);
+
+    $rootScope.exp = { c: 4 };
+    $rootScope.$digest();
+
+    var four = element.find('div')[0];
+    expect(four.textContent.trim()).toBe('4');
+    expect(four).not.toEqual(three);
+  }));
+
+  they('should consider $prop as a falsy value', [false, undefined, null], function(value) {
+    inject(function() {
+      element = $compile('<div><div ng-animate-swap="value">{{ value }}</div></div>')($rootScope);
+      $rootScope.value = true;
+      $rootScope.$digest();
+
+      var one = element.find('div')[0];
+      expect(one).toBeTruthy();
+
+      $rootScope.value = value;
+      $rootScope.$digest();
+
+      var two = element.find('div')[0];
+      expect(two).toBeFalsy();
+    });
+  });
+
+  it('should consider "0" as a truthy value', inject(function() {
+    element = $compile('<div><div ng-animate-swap="value">{{ value }}</div></div>')($rootScope);
+    $rootScope.$digest();
+
+    var one = element.find('div')[0];
+    expect(one).toBeFalsy();
+
+    $rootScope.value = 0;
+    $rootScope.$digest();
+
+    var two = element.find('div')[0];
+    expect(two).toBeTruthy();
+  }));
+
+
+  describe("animations", function() {
+    it('should trigger a leave animation followed by an enter animation upon swap',
+      inject(function() {
+
+      element = $compile('<div><div ng-animate-swap="exp">{{ exp }}</div></div>')($rootScope);
+      $rootScope.exp = 1;
+      $rootScope.$digest();
+
+      var first = $animate.queue.shift();
+      expect(first.event).toBe('enter');
+      expect($animate.queue.length).toBe(0);
+
+      $rootScope.exp = 2;
+      $rootScope.$digest();
+
+      var second = $animate.queue.shift();
+      expect(second.event).toBe('leave');
+
+      var third = $animate.queue.shift();
+      expect(third.event).toBe('enter');
+      expect($animate.queue.length).toBe(0);
+
+      $rootScope.exp = false;
+      $rootScope.$digest();
+
+      var forth = $animate.queue.shift();
+      expect(forth.event).toBe('leave');
+      expect($animate.queue.length).toBe(0);
+    }));
+  });
+});