docs(animation): add callbacks documentation (#2271)

public/docs/_examples/animations/e2e-spec.ts

@@ -289,6 +289,19 @@ describe('Animation Tests', () => {
     });
   });
 
+  describe('callbacks', () => {
+    it('fires a callback on start and done', () => {
+      addActiveHero();
+      browser.manage().logs().get('browser').then((logs) => {
+        const animationMessages = logs.filter((log) => {
+          return log.message.indexOf('Animation') !== -1 ? true : false;
+        });
+
+        expect(animationMessages.length).toBeGreaterThan(0);
+      });
+    });
+  });
+
   function addActiveHero(sleep?: number) {
     sleep = sleep || 500;
     element(by.buttonText('Add active hero')).click();

public/docs/_examples/animations/ts/app/hero-list-multistep.component.ts

@@ -6,7 +6,8 @@ import {
   style,
   animate,
   transition,
-  keyframes
+  keyframes,
+  AnimationTransitionEvent
 } from '@angular/core';
 
 import { Heroes } from './hero.service';
@@ -14,14 +15,18 @@ import { Heroes } from './hero.service';
 @Component({
   moduleId: module.id,
   selector: 'hero-list-multistep',
+  // #docregion template
   template: `
     <ul>
       <li *ngFor="let hero of heroes"
+          (@flyInOut.start)="animationStarted($event)"
+          (@flyInOut.done)="animationDone($event)"
           [@flyInOut]="'in'">
         {{hero.name}}
       </li>
     </ul>
   `,
+  // #enddocregion template
   styleUrls: ['hero-list.component.css'],
   /* The element here always has the state "in" when it
    * is present. We animate two transitions: From void
@@ -54,4 +59,12 @@ import { Heroes } from './hero.service';
 })
 export class HeroListMultistepComponent {
   @Input() heroes: Heroes;
+
+  animationStarted(event: AnimationTransitionEvent) {
+    console.warn('Animation started: ', event);
+  }
+
+  animationDone(event: AnimationTransitionEvent) {
+    console.warn('Animation done: ', event);
+  }
 }

public/docs/ts/latest/guide/animations.jade

@@ -34,6 +34,7 @@ include ../_util-fns
   * [Animation Timing](#animation-timing)
   * [Multi-Step Animations with Keyframes](#multi-step-animations-with-keyframes)
   * [Parallel Animation Groups](#parallel-animation-groups)
+  * [Animation callbacks](#animation-callbacks)
 
 .l-sub-section
   :marked
@@ -337,3 +338,19 @@ figure
 
 :marked
   One group animates the element transform and width. The other animates the opacity.
+
+:marked
+  ## Animation callbacks
+
+  A callback is fired when an animation is started and also when it is done.
+
+  In the keyframes example, we have a `trigger` called `@flyInOut`. There we can hook
+  those callbacks like:
+
++makeExample('animations/ts/app/hero-list-multistep.component.ts', 'template')(format=".")
+
+:marked
+  The callbacks receive an `AnimationTransitionEvent` which contains useful properties such as `fromState`,
+  `toState` and `totalTime`.
+
+  Those callbacks will fire whether or not an animation is picked up.