docs(animations): provide API docs for the animation DSL

Closes #8970

modules/@angular/compiler/src/animation/animation_parser.ts

@@ -105,7 +105,7 @@ function _parseAnimationStateTransition(transitionStateMetadata: CompileAnimatio
       transitionExprs.push(transExpr);
     });
   });
-  var entry = _normalizeAnimationEntry(transitionStateMetadata.animation);
+  var entry = _normalizeAnimationEntry(transitionStateMetadata.steps);
   var animation = _normalizeStyleSteps(entry, stateStyles, errors);
   var animationAst = _parseTransitionAnimation(animation, 0, styles, stateStyles, errors);
   if (errors.length == 0) {

modules/@angular/compiler/src/compile_metadata.ts

@@ -94,18 +94,18 @@ export class CompileAnimationStateDeclarationMetadata extends CompileAnimationSt
 export class CompileAnimationStateTransitionMetadata extends CompileAnimationStateMetadata {
   static fromJson(data: {[key: string]: any}): CompileAnimationStateTransitionMetadata {
     var value = data['value'];
-    var animation = _objFromJson(value['animation'], metadataFromJson);
+    var steps = _objFromJson(value['steps'], metadataFromJson);
-    return new CompileAnimationStateTransitionMetadata(value['stateChangeExpr'], animation);
+    return new CompileAnimationStateTransitionMetadata(value['stateChangeExpr'], steps);
   }
 
-  constructor(public stateChangeExpr: string, public animation: CompileAnimationMetadata) { super(); }
+  constructor(public stateChangeExpr: string, public steps: CompileAnimationMetadata) { super(); }
 
   toJson(): {[key: string]: any} {
     return {
       'class': 'AnimationStateTransitionMetadata',
       'value': {
         'stateChangeExpr': this.stateChangeExpr,
-        'animation': this.animation.toJson()
+        'steps': this.steps.toJson()
       }
     };
   }

modules/@angular/compiler/src/metadata_resolver.ts

@@ -94,7 +94,7 @@ export class CompileMetadataResolver {
       var styles = this.getAnimationStyleMetadata(value.styles);
       return new cpl.CompileAnimationStateDeclarationMetadata(value.stateNameExpr, styles);
     } else if (value instanceof AnimationStateTransitionMetadata) {
-      return new cpl.CompileAnimationStateTransitionMetadata(value.stateChangeExpr, this.getAnimationMetadata(value.animation));
+      return new cpl.CompileAnimationStateTransitionMetadata(value.stateChangeExpr, this.getAnimationMetadata(value.steps));
     }
     return null;
   }

modules/@angular/core/src/animation/metadata.ts

@@ -3,32 +3,57 @@ import {BaseException} from '../facade/exceptions';
 
 export const AUTO_STYLE = "*";
 
+/**
+ * Metadata representing the entry of animations.
+ * Instances of this class are provided via the animation DSL when the {@link trigger trigger animation function} is called.
+ */
 export class AnimationEntryMetadata {
   constructor(public name: string, public definitions: AnimationStateMetadata[]) {}
 }
 
 export abstract class AnimationStateMetadata {}
 
+/**
+ * Metadata representing the entry of animations.
+ * Instances of this class are provided via the animation DSL when the {@link state state animation function} is called.
+ */
 export class AnimationStateDeclarationMetadata extends AnimationStateMetadata {
   constructor(public stateNameExpr: string, public styles: AnimationStyleMetadata) { super(); }
 }
 
+/**
+ * Metadata representing the entry of animations.
+ * Instances of this class are provided via the animation DSL when the
+ * {@link transition transition animation function} is called.
+ */
 export class AnimationStateTransitionMetadata extends AnimationStateMetadata {
-  constructor(public stateChangeExpr: string, public animation: AnimationMetadata) { super(); }
+  constructor(public stateChangeExpr: string, public steps: AnimationMetadata) { super(); }
 }
 
 export abstract class AnimationMetadata {}
 
+/**
+ * Metadata representing the entry of animations.
+ * Instances of this class are provided via the animation DSL when the {@link keyframes keyframes animation function} is called.
+ */
 export class AnimationKeyframesSequenceMetadata extends AnimationMetadata {
   constructor(public steps: AnimationStyleMetadata[]) {
     super();
   }
 }
 
+/**
+ * Metadata representing the entry of animations.
+ * Instances of this class are provided via the animation DSL when the {@link style style animation function} is called.
+ */
 export class AnimationStyleMetadata extends AnimationMetadata {
   constructor(public styles: Array<string|{[key: string]: string | number}>, public offset: number = null) { super(); }
 }
 
+/**
+ * Metadata representing the entry of animations.
+ * Instances of this class are provided via the animation DSL when the {@link animate animate animation function} is called.
+ */
 export class AnimationAnimateMetadata extends AnimationMetadata {
   constructor(public timings: string | number,
               public styles: AnimationStyleMetadata|AnimationKeyframesSequenceMetadata) {
@@ -41,16 +66,66 @@ export abstract class AnimationWithStepsMetadata extends AnimationMetadata {
   get steps(): AnimationMetadata[] { throw new BaseException('NOT IMPLEMENTED: Base Class'); }
 }
 
+/**
+ * Metadata representing the entry of animations.
+ * Instances of this class are provided via the animation DSL when the {@link sequence sequence animation function} is called.
+ */
 export class AnimationSequenceMetadata extends AnimationWithStepsMetadata {
   constructor(private _steps: AnimationMetadata[]) { super(); }
   get steps(): AnimationMetadata[] { return this._steps; }
 }
 
+/**
+ * Metadata representing the entry of animations.
+ * Instances of this class are provided via the animation DSL when the {@link group group animation function} is called.
+ */
 export class AnimationGroupMetadata extends AnimationWithStepsMetadata {
   constructor(private _steps: AnimationMetadata[]) { super(); }
   get steps(): AnimationMetadata[] { return this._steps; }
 }
 
+/**
+ * `animate` is an animation-specific function that is designed to be used inside of Angular2's animation
+ * DSL language. If this information is new, please navigate to the
+ * {@link ComponentMetadata#animations-anchor component animations metadata
+ * page} to gain a better understanding of how animations in Angular2 are used.
+ *
+ * `animate` specifies an animation step that will apply the provided `styles` data for a given amount of
+ * time based on the provided `timing` expression value. Calls to `animate` are expected to be
+ * used within {@link sequence an animation sequence}, {@link group group}, or {@link transition transition}.
+ *
+ * ### Usage
+ *
+ * The `animate` function accepts two input parameters: `timing` and `styles`:
+ *
+ * - `timing` is a string based value that can be a combination of a duration with optional
+ * delay and easing values. The format for the expression breaks down to `duration delay easing`
+ * (therefore a value such as `1s 100ms ease-out` will be parse itself into `duration=1000, delay=100, easing=ease-out`.
+ * If a numeric value is provided then that will be used as the `duration` value in millisecond form.
+ * - `styles` is the style input data which can either be a call to {@link style style} or {@link keyframes keyframes}.
+ * If left empty then the styles from the destination state will be collected and used (this is useful when
+ * describing an animation step that will complete an animation by {@link transition#the-final-animate-call animating to the final state}).
+ *
+ * ```typescript
+ * // various functions for specifying timing data
+ * animate(500, style(...))
+ * animate("1s", style(...))
+ * animate("100ms 0.5s", style(...))
+ * animate("5s ease", style(...))
+ * animate("5s 10ms cubic-bezier(.17,.67,.88,.1)", style(...))
+ *
+ * // either style() of keyframes() can be used
+ * animate(500, style({ background: "red" }))
+ * animate(500, keyframes([
+ *   style({ background: "blue" })),
+ *   style({ background: "red" }))
+ * ])
+ * ```
+ *
+ * ### Example ([live demo](http://plnkr.co/edit/Kez8XGWBxWue7qP7nNvF?p=preview))
+ *
+ * {@example core/animation/ts/dsl/animation_example.ts region='Component'}
+ */
 export function animate(timing: string | number,
                         styles: AnimationStyleMetadata|AnimationKeyframesSequenceMetadata = null): AnimationAnimateMetadata {
   var stylesEntry = styles;
@@ -61,14 +136,121 @@ export function animate(timing: string | number,
   return new AnimationAnimateMetadata(timing, stylesEntry);
 }
 
+/**
+ * `group` is an animation-specific function that is designed to be used inside of Angular2's animation
+ * DSL language. If this information is new, please navigate to the
+ * {@link ComponentMetadata#animations-anchor component animations metadata
+ * page} to gain a better understanding of how animations in Angular2 are used.
+ *
+ * `group` specifies a list of animation steps that are all run in parallel. Grouped animations
+ * are useful when a series of styles must be animated/closed off
+ * at different statrting/ending times.
+ *
+ * The `group` function can either be used within a {@link sequence sequence} or a {@link transition transition}
+ * and it will only continue to the next instruction once all of the inner animation steps
+ * have completed.
+ *
+ * ### Usage
+ *
+ * The `steps` data that is passed into the `group` animation function can either consist
+ * of {@link style style} or {@link animate animate} function calls. Each call to `style()` or `animate()`
+ * within a group will be executed instantly (use {@link keyframes keyframes} or a
+ * {@link animate#usage animate() with a delay value} to offset styles to be applied at a later time).
+ *
+ * ```typescript
+ * group([
+ *   animate("1s", { background: "black" }))
+ *   animate("2s", { color: "white" }))
+ * ])
+ * ```
+ *
+ * ### Example ([live demo](http://plnkr.co/edit/Kez8XGWBxWue7qP7nNvF?p=preview))
+ *
+ * {@example core/animation/ts/dsl/animation_example.ts region='Component'}
+ */
 export function group(steps: AnimationMetadata[]): AnimationGroupMetadata {
   return new AnimationGroupMetadata(steps);
 }
 
+/**
+ * `sequence` is an animation-specific function that is designed to be used inside of Angular2's animation
+ * DSL language. If this information is new, please navigate to the
+ * {@link ComponentMetadata#animations-anchor component animations metadata
+ * page} to gain a better understanding of how animations in Angular2 are used.
+ *
+ * `sequence` Specifies a list of animation steps that are run one by one. (`sequence` is used
+ * by default when an array is passed as animation data into {@link transition transition}.)
+ *
+ * The `sequence` function can either be used within a {@link group group} or a {@link transition transition}
+ * and it will only continue to the next instruction once each of the inner animation steps
+ * have completed.
+ *
+ * To perform animation styling in parallel with other animation steps then
+ * have a look at the {@link group group} animation function.
+ *
+ * ### Usage
+ *
+ * The `steps` data that is passed into the `sequence` animation function can either consist
+ * of {@link style style} or {@link animate animate} function calls. A call to `style()` will apply the
+ * provided styling data immediately while a call to `animate()` will apply its styling
+ * data over a given time depending on its timing data.
+ *
+ * ```typescript
+ * sequence([
+ *   style({ opacity: 0 })),
+ *   animate("1s", { opacity: 1 }))
+ * ])
+ * ```
+ *
+ * ### Example ([live demo](http://plnkr.co/edit/Kez8XGWBxWue7qP7nNvF?p=preview))
+ *
+ * {@example core/animation/ts/dsl/animation_example.ts region='Component'}
+ */
 export function sequence(steps: AnimationMetadata[]): AnimationSequenceMetadata {
   return new AnimationSequenceMetadata(steps);
 }
 
+/**
+ * `style` is an animation-specific function that is designed to be used inside of Angular2's animation
+ * DSL language. If this information is new, please navigate to the
+ * {@link ComponentMetadata#animations-anchor component animations metadata
+ * page} to gain a better understanding of how animations in Angular2 are used.
+ *
+ * `style` declares a key/value object containing CSS properties/styles that can then
+ * be used for {@link state animation states}, within an {@link sequence animation sequence}, or as styling data for both {@link animate animate} and {@link keyframes keyframes}.
+ *
+ * ### Usage
+ *
+ * `style` takes in a key/value string map as data and expects one or more CSS property/value
+ * pairs to be defined.
+ *
+ * ```typescript
+ * // string values are used for css properties
+ * style({ background: "red", color: "blue" })
+ *
+ * // numerical (pixel) values are also supported
+ * style({ width: 100, height: 0 })
+ * ```
+ *
+ * #### Auto-styles (using `*`)
+ *
+ * When an asterix (`*`) character is used as a value then it will be detected from the element being animated
+ * and applied as animation data when the animation starts.
+ *
+ * This feature proves useful for a state depending on layout and/or environment factors; in such cases
+ * the styles are calculated just before the animation starts.
+ *
+ * ```typescript
+ * // the steps below will animate from 0 to the
+ * // actual height of the element
+ * style({ height: 0 }),
+ * animate("1s", style({ height: "*" }))
+ * ```
+ *
+ * ### Example ([live demo](http://plnkr.co/edit/Kez8XGWBxWue7qP7nNvF?p=preview))
+ *
+ * {@example core/animation/ts/dsl/animation_example.ts region='Component'}
+ */
 export function style(tokens: string|{[key: string]: string | number}|Array<string|{[key: string]: string | number}>): AnimationStyleMetadata {
   var input: Array<{[key: string]: string | number}|string>;
   var offset: number = null;
@@ -90,27 +272,238 @@ export function style(tokens: string|{[key: string]: string | number}|Array<stri
   return new AnimationStyleMetadata(input, offset);
 }
 
+/**
+ * `state` is an animation-specific function that is designed to be used inside of Angular2's animation
+ * DSL language. If this information is new, please navigate to the
+ * {@link ComponentMetadata#animations-anchor component animations metadata
+ * page} to gain a better understanding of how animations in Angular2 are used.
+ *
+ * `state` declares an animation state within the given trigger. When a state is
+ * active within a component then its associated styles will persist on
+ * the element that the trigger is attached to (even when the animation ends).
+ *
+ * To animate between states, have a look at the animation {@link transition transition}
+ * DSL function. To register states to an animation trigger please have a look
+ * at the {@link trigger trigger} function.
+ *
+ * #### The `void` state
+ *
+ * The `void` state value is a reserved word that angular uses to determine when the element is not apart
+ * of the application anymore (e.g. when an `ngIf` evaluates to false then the state of the associated element
+ * is void).
+ *
+ *
+ * ### Usage
+ *
+ * `state` will declare an animation state with its associated styles
+ * within the given trigger.
+ *
+ * - `stateNameExpr` can be one or more state names separated by commas.
+ * - `styles` refers to the {@link style styling data} that will be persisted on the element once the state
+ * has been reached.
+ *
+ * ```typescript
+ * // "void" is a reserved name for a state and is used to represent
+ * // the state in which an element is detached from from the application.
+ * state("void", style({ height: 0 }))
+ *
+ * // user-defined states
+ * state("closed", style({ height: 0 }))
+ * state("open, visible", style({ height: "*" }))
+ * ```
+ *
+ * ### Example ([live demo](http://plnkr.co/edit/Kez8XGWBxWue7qP7nNvF?p=preview))
+ *
+ * {@example core/animation/ts/dsl/animation_example.ts region='Component'}
+ */
 export function state(stateNameExpr: string, styles: AnimationStyleMetadata): AnimationStateDeclarationMetadata {
   return new AnimationStateDeclarationMetadata(stateNameExpr, styles);
 }
 
-export function keyframes(steps: AnimationStyleMetadata|AnimationStyleMetadata[]): AnimationKeyframesSequenceMetadata {
+/**
-  var stepData = isArray(steps)
+ * `keyframes` is an animation-specific function that is designed to be used inside of Angular2's animation
-      ? <AnimationStyleMetadata[]>steps
+ * DSL language. If this information is new, please navigate to the
-      : [<AnimationStyleMetadata>steps];
+ * {@link ComponentMetadata#animations-anchor component animations metadata
-  return new AnimationKeyframesSequenceMetadata(stepData);
+ * page} to gain a better understanding of how animations in Angular2 are used.
+ *
+ * `keyframes` specifies a collection of {@link style style} entries each optionally characterized by an `offset` value.
+ *
+ * ### Usage
+ *
+ * The `keyframes` animation function is designed to be used alongside the {@link animate animate}
+ * animation function. Instead of applying animations from where they are
+ * currently to their destination, keyframes can describe how each style entry is applied
+ * and at what point within the animation arc (much like CSS Keyframe Animations do).
+ *
+ * For each `style()` entry an `offset` value can be set. Doing so allows to specifiy at
+ * what percentage of the animate time the styles will be applied.
+ *
+ * ```typescript
+ * // the provided offset values describe when each backgroundColor value is applied.
+ * animate("5s", keyframes([
+ *   style({ backgroundColor: "red", offset: 0 }),
+ *   style({ backgroundColor: "blue", offset: 0.2 }),
+ *   style({ backgroundColor: "orange", offset: 0.3 }),
+ *   style({ backgroundColor: "black", offset: 1 })
+ * ]))
+ * ```
+ *
+ * Alternatively, if there are no `offset` values used within the style entries then the offsets will
+ * be calculated automatically.
+ *
+ * ```typescript
+ * animate("5s", keyframes([
+ *   style({ backgroundColor: "red" }) // offset = 0
+ *   style({ backgroundColor: "blue" }) // offset = 0.33
+ *   style({ backgroundColor: "orange" }) // offset = 0.66
+ *   style({ backgroundColor: "black" }) // offset = 1
+ * ]))
+ * ```
+ *
+ * ### Example ([live demo](http://plnkr.co/edit/Kez8XGWBxWue7qP7nNvF?p=preview))
+ *
+ * {@example core/animation/ts/dsl/animation_example.ts region='Component'}
+ */
+export function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSequenceMetadata {
+  return new AnimationKeyframesSequenceMetadata(steps);
 }
 
-export function transition(stateChangeExpr: string, animationData: AnimationMetadata|AnimationMetadata[]): AnimationStateTransitionMetadata {
+/**
-  var animation = isArray(animationData)
+ * `transition` is an animation-specific function that is designed to be used inside of Angular2's animation
-      ? new AnimationSequenceMetadata(<AnimationMetadata[]>animationData)
+ * DSL language. If this information is new, please navigate to the
-      : <AnimationMetadata>animationData;
+ * {@link ComponentMetadata#animations-anchor component animations metadata
-  return new AnimationStateTransitionMetadata(stateChangeExpr, animation);
+ * page} to gain a better understanding of how animations in Angular2 are used.
+ *
+ * `transition` declares the {@link sequence sequence of animation steps} that will be run when the provided
+ * `stateChangeExpr` value is satisfied. The `stateChangeExpr` consists of a `state1 => state2` which consists
+ * of two known states (use an asterix (`*`) to refer to a dynamic starting and/or ending state).
+ *
+ * Animation transitions are placed within an {@link trigger animation trigger}. For an transition to animate to
+ * a state value and persist its styles then one or more {@link state animation states} is expected to be defined.
+ *
+ * ### Usage
+ *
+ * An animation transition is kicked off the `stateChangeExpr` predicate evaluates to true based on what the
+ * previous state is and what the current state has become. In other words, if a transition is defined that
+ * matches the old/current state criteria then the associated animation will be triggered.
+ *
+ * ```typescript
+ * // all transition/state changes are defined within an animation trigger
+ * trigger("myAnimationTrigger", [
+ *   // if a state is defined then its styles will be persisted when the
+ *   // animation has fully completed itself
+ *   state("on", style({ background: "green" })),
+ *   state("off", style({ background: "grey" })),
+ *
+ *   // a transition animation that will be kicked off when the state value
+ *   // bound to "myAnimationTrigger" changes from "on" to "off"
+ *   transition("on => off", animate(500)),
+ *
+ *   // it is also possible to do run the same animation for both directions
+ *   transition("on <=> off", animate(500)),
+ *
+ *   // or to define multiple states pairs separated by commas
+ *   transition("on => off, off => void", animate(500)),
+ *
+ *   // this is a catch-all state change for when an element is inserted into
+ *   // the page and the destination state is unknown
+ *   transition("void => *", [
+ *     style({ opacity: 0 }),
+ *     animate(500)
+ *   ]),
+ *
+ *   // this will capture a state change between any states
+ *   transition("* => *", animate("1s 0s")),
+ * ])
+ * ```
+ *
+ * The template associated with this component will make use of the `myAnimationTrigger`
+ * animation trigger by binding to an element within its template code.
+ *
+ * ```html
+ * <!-- somewhere inside of my-component-tpl.html -->
+ * <div @myAnimationTrigger="myStatusExp">...</div>
+ * ```
+ *
+ * #### The final `animate` call
+ *
+ * If the final step within the transition steps is a call to `animate()` that **only**
+ * uses a timing value with **no style data** then it will be automatically used as the final animation
+ * arc for the element to animate itself to the final state. This involves an automatic mix of
+ * adding/removing CSS styles so that the element will be in the exact state it should be for the
+ * applied state to be presented correctly.
+ *
+ * ```
+ * // start off by hiding the element, but make sure that it animates properly to whatever state
+ * // is currently active for "myAnimationTrigger"
+ * transition("void => *", [
+ *   style({ opacity: 0 }),
+ *   animate(500)
+ * ])
+ * ```
+ *
+ * ### Example ([live demo](http://plnkr.co/edit/Kez8XGWBxWue7qP7nNvF?p=preview))
+ *
+ * {@example core/animation/ts/dsl/animation_example.ts region='Component'}
+ */
+export function transition(stateChangeExpr: string, steps: AnimationMetadata|AnimationMetadata[]): AnimationStateTransitionMetadata {
+  var animationData = isArray(steps)
+      ? new AnimationSequenceMetadata(<AnimationMetadata[]>steps)
+      : <AnimationMetadata>steps;
+  return new AnimationStateTransitionMetadata(stateChangeExpr, animationData);
 }
 
-export function trigger(name: string, animation: AnimationMetadata|AnimationMetadata[]): AnimationEntryMetadata {
+/**
-  var entry = isArray(animation)
+ * `trigger` is an animation-specific function that is designed to be used inside of Angular2's animation
-    ? <AnimationMetadata[]>animation
+ * DSL language. If this information is new, please navigate to the
-    : [<AnimationMetadata>animation];
+ * {@link ComponentMetadata#animations-anchor component animations metadata
-  return new AnimationEntryMetadata(name, entry);
+ * page} to gain a better understanding of how animations in Angular2 are used.
+ *
+ * `trigger` Creates an animation trigger which will a list of {@link state state} and {@link transition transition}
+ * entries that will be evaluated when the expression bound to the trigger changes.
+ *
+ * Triggers are registered within the component annotation data under the
+ * {@link ComponentMetadata#animations-anchor animations section}. An animation trigger can
+ * be placed on an element within a template by referencing the name of the
+ * trigger followed by the expression value that the trigger is bound to
+ * (in the form of `@triggerName="expression"`.
+ *
+ * ### Usage
+ *
+ * `trigger` will create an animation trigger reference based on the provided `name` value.
+ * The provided `animation` value is expected to be an array consisting of {@link state state} and {@link transition transition}
+ * declarations.
+ *
+ * ```typescript
+ * @Component({
+ *   selector: 'my-component',
+ *   templateUrl: 'my-component-tpl.html',
+ *   animations: [
+ *     trigger("myAnimationTrigger", [
+ *       state(...),
+ *       state(...),
+ *       transition(...),
+ *       transition(...)
+ *     ])
+ *   ]
+ * })
+ * class MyComponent {
+ *   myStatusExp = "something";
+ * }
+ * ```
+ *
+ * The template associated with this component will make use of the `myAnimationTrigger`
+ * animation trigger by binding to an element within its template code.
+ *
+ * ```html
+ * <!-- somewhere inside of my-component-tpl.html -->
+ * <div @myAnimationTrigger="myStatusExp">...</div>
+ * ```
+ *
+ * ### Example ([live demo](http://plnkr.co/edit/Kez8XGWBxWue7qP7nNvF?p=preview))
+ *
+ * {@example core/animation/ts/dsl/animation_example.ts region='Component'}
+ */
+export function trigger(name: string, animation: AnimationMetadata[]): AnimationEntryMetadata {
+  return new AnimationEntryMetadata(name, animation);
 }

modules/@angular/core/src/metadata/directives.ts

@@ -878,6 +878,75 @@ export class ComponentMetadata extends DirectiveMetadata {
 
   styles: string[];
 
+  /**
+   * Animations are defined on components via an animation-like DSL. This DSL approach to describing
+   * animations allows for a flexibility that both benefits developers and the framework.
+   *
+   * Animations work by listening on state changes that occur on an element within
+   * the template. When a state change occurs, Angular can then take advantage and animate the
+   * arc in between. This works similar to how CSS transitions work, however, by having a
+   * programmatic DSL, animations are not limited to environments that are DOM-specific.
+   * (Angular can also perform optimizations behind the scenes to make animations more performant.)
+   *
+   * For animations to be available for use, animation state changes are placed within
+   * {@link trigger animation triggers} which are housed inside of the `animations` annotation
+   * metadata. Within a trigger both {@link state state} and {@link transition transition} entries
+   * can be placed.
+   *
+   * ```typescript
+   * @Component({
+   *   selector: 'animation-cmp',
+   *   templateUrl: 'animation-cmp.html',
+   *   animations: [
+   *     // this here is our animation trigger that
+   *     // will contain our state change animations.
+   *     trigger('myTriggerName', [
+   *       // the styles defined for the `on` and `off`
+   *       // states declared below are persisted on the
+   *       // element once the animation completes.
+   *       state('on', style({ opacity: 1 }),
+   *       state('off', style({ opacity: 0 }),
+   *
+   *       // this here is our animation that kicks off when
+   *       // this state change jump is true
+   *       transition('on => off', [
+   *         animate("1s")
+   *       ])
+   *     ])
+   *   ]
+   * })
+   * ```
+   *
+   * As depicted in the code above, a group of related animation states are all contained within
+   * an animation `trigger` (the code example above called the trigger `myTriggerName`).
+   * When a trigger is created then it can be bound onto an element within the component's
+   * template via a property prefixed by an `@` symbol followed by trigger name and an expression that
+   * is used to determine the state value for that trigger.
+   *
+   * ```html
+   * <!-- animation-cmp.html -->
+   * <div @myTriggerName="expression">...</div>
+   * ```
+   *
+   * For state changes to be executed, the `expression` value must change value from its existing value
+   * to something that we have set an animation to animate on (in the example above we are listening
+   * to a change of state between `on` and `off`). The `expression` value attached to the trigger
+   * must be something that can be evaluated with the template/component context.
+   *
+   * ### DSL Animation Functions
+   *
+   * Please visit each of the animation DSL functions listed below to gain a better understanding
+   * of how and why they are used for crafting animations in Angular2:
+   *
+   * - {@link trigger trigger()}
+   * - {@link state state()}
+   * - {@link transition transition()}
+   * - {@link group group()}
+   * - {@link sequence sequence()}
+   * - {@link style style()}
+   * - {@link animate animate()}
+   * - {@link keyframes keyframes()}
+   */
   animations: AnimationEntryMetadata[];
 
   directives: Array<Type | any[]>;

modules/@angular/examples/core/animation/ts/dsl/animation_example.ts

@@ -0,0 +1,51 @@
+// #docregion Component
+import {Component, trigger, state, animate, transition, style} from '@angular/core';
+
+@Component({
+  selector: "my-expando",
+  styles: [`
+    .toggle-container {
+      background-color:white;
+      border:10px solid black;
+      width:200px;
+      text-align:center;
+      line-height:100px;
+      font-size:50px;
+      box-sizing:border-box;
+      overflow:hidden;
+    }
+  `],
+  animations: [
+    trigger('openClose', [
+      state('collapsed, void',
+        style({ height:"0px", color: "maroon", borderColor: "maroon" })),
+      state('expanded',
+        style({ height:"*", borderColor:"green", color:"green" })),
+      transition("collapsed <=> expanded", [
+        animate(500, style({ height: '250px'})),
+        animate(500)
+      ])
+    ])
+  ],
+  template: `
+    <button (click)="expand()">Open</button>
+    <button (click)="collapse()">Closed</button>
+    <hr />
+    <div class="toggle-container" @openClose="stateExpression">
+      Look at this box
+    </div>
+  `
+})
+export class MyExpandoCmp {
+  stateExpression:string;
+  constructor() {
+    this.collapse();
+  }
+  expand() {
+    this.stateExpression = 'expanded';
+  }
+  collapse() {
+    this.stateExpression = 'collapsed';
+  }
+}
+// #enddocregion

tools/public_api_guard/public_api_spec.ts

@@ -63,9 +63,9 @@ const CORE = [
   'AnimationStateDeclarationMetadata.styles:AnimationStyleMetadata',
   'AnimationStateMetadata',
   'AnimationStateTransitionMetadata',
-  'AnimationStateTransitionMetadata.animation:AnimationMetadata',
+  'AnimationStateTransitionMetadata.constructor(stateChangeExpr:string, steps:AnimationMetadata)',
-  'AnimationStateTransitionMetadata.constructor(stateChangeExpr:string, animation:AnimationMetadata)',
   'AnimationStateTransitionMetadata.stateChangeExpr:string',
+  'AnimationStateTransitionMetadata.steps:AnimationMetadata',
   'AnimationStyleMetadata',
   'AnimationStyleMetadata.constructor(styles:Array<string|{[key:string]:string|number}>, offset:number=null)',
   'AnimationStyleMetadata.offset:number=null',
@@ -588,15 +588,15 @@ const CORE = [
   'getDebugNode(nativeNode:any):DebugNode',
   'getPlatform():PlatformRef',
   'group(steps:AnimationMetadata[]):AnimationGroupMetadata',
-  'keyframes(steps:AnimationStyleMetadata|AnimationStyleMetadata[]):AnimationKeyframesSequenceMetadata',
+  'keyframes(steps:AnimationStyleMetadata[]):AnimationKeyframesSequenceMetadata',
   'provide(token:any, {useClass,useValue,useExisting,useFactory,deps,multi}:{useClass?:Type, useValue?:any, useExisting?:any, useFactory?:Function, deps?:Object[], multi?:boolean}):Provider',
   'resolveForwardRef(type:any):any',
   'sequence(steps:AnimationMetadata[]):AnimationSequenceMetadata',
   'setTestabilityGetter(getter:GetTestability):void',
   'state(stateNameExpr:string, styles:AnimationStyleMetadata):AnimationStateDeclarationMetadata',
   'style(tokens:string|{[key:string]:string|number}|Array<string|{[key:string]:string|number}>):AnimationStyleMetadata',
-  'transition(stateChangeExpr:string, animationData:AnimationMetadata|AnimationMetadata[]):AnimationStateTransitionMetadata',
+  'transition(stateChangeExpr:string, steps:AnimationMetadata|AnimationMetadata[]):AnimationStateTransitionMetadata',
-  'trigger(name:string, animation:AnimationMetadata|AnimationMetadata[]):AnimationEntryMetadata',
+  'trigger(name:string, animation:AnimationMetadata[]):AnimationEntryMetadata',
   'var Attribute:AttributeMetadataFactory',
   'var Component:ComponentMetadataFactory',
   'var ContentChild:ContentChildMetadataFactory',