@angular/core 2.0.0-rc.1 → 2.0.0-rc.2

package/src/animation/metadata.js

@@ -0,0 +1,627 @@
+"use strict";
+var __extends = (this && this.__extends) || function (d, b) {
+    for (var p in b) if (b.hasOwnProperty(p)) d[p] = b[p];
+    function __() { this.constructor = d; }
+    d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+};
+var exceptions_1 = require('../facade/exceptions');
+var lang_1 = require('../facade/lang');
+exports.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.
+ */
+var AnimationEntryMetadata = (function () {
+    function AnimationEntryMetadata(name, definitions) {
+        this.name = name;
+        this.definitions = definitions;
+    }
+    return AnimationEntryMetadata;
+}());
+exports.AnimationEntryMetadata = AnimationEntryMetadata;
+var AnimationStateMetadata = (function () {
+    function AnimationStateMetadata() {
+    }
+    return AnimationStateMetadata;
+}());
+exports.AnimationStateMetadata = 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.
+ */
+var AnimationStateDeclarationMetadata = (function (_super) {
+    __extends(AnimationStateDeclarationMetadata, _super);
+    function AnimationStateDeclarationMetadata(stateNameExpr, styles) {
+        _super.call(this);
+        this.stateNameExpr = stateNameExpr;
+        this.styles = styles;
+    }
+    return AnimationStateDeclarationMetadata;
+}(AnimationStateMetadata));
+exports.AnimationStateDeclarationMetadata = AnimationStateDeclarationMetadata;
+/**
+ * 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.
+ */
+var AnimationStateTransitionMetadata = (function (_super) {
+    __extends(AnimationStateTransitionMetadata, _super);
+    function AnimationStateTransitionMetadata(stateChangeExpr, steps) {
+        _super.call(this);
+        this.stateChangeExpr = stateChangeExpr;
+        this.steps = steps;
+    }
+    return AnimationStateTransitionMetadata;
+}(AnimationStateMetadata));
+exports.AnimationStateTransitionMetadata = AnimationStateTransitionMetadata;
+var AnimationMetadata = (function () {
+    function AnimationMetadata() {
+    }
+    return AnimationMetadata;
+}());
+exports.AnimationMetadata = 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.
+ */
+var AnimationKeyframesSequenceMetadata = (function (_super) {
+    __extends(AnimationKeyframesSequenceMetadata, _super);
+    function AnimationKeyframesSequenceMetadata(steps) {
+        _super.call(this);
+        this.steps = steps;
+    }
+    return AnimationKeyframesSequenceMetadata;
+}(AnimationMetadata));
+exports.AnimationKeyframesSequenceMetadata = AnimationKeyframesSequenceMetadata;
+/**
+ * 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.
+ */
+var AnimationStyleMetadata = (function (_super) {
+    __extends(AnimationStyleMetadata, _super);
+    function AnimationStyleMetadata(styles, offset) {
+        if (offset === void 0) { offset = null; }
+        _super.call(this);
+        this.styles = styles;
+        this.offset = offset;
+    }
+    return AnimationStyleMetadata;
+}(AnimationMetadata));
+exports.AnimationStyleMetadata = AnimationStyleMetadata;
+/**
+ * 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.
+ */
+var AnimationAnimateMetadata = (function (_super) {
+    __extends(AnimationAnimateMetadata, _super);
+    function AnimationAnimateMetadata(timings, styles) {
+        _super.call(this);
+        this.timings = timings;
+        this.styles = styles;
+    }
+    return AnimationAnimateMetadata;
+}(AnimationMetadata));
+exports.AnimationAnimateMetadata = AnimationAnimateMetadata;
+var AnimationWithStepsMetadata = (function (_super) {
+    __extends(AnimationWithStepsMetadata, _super);
+    function AnimationWithStepsMetadata() {
+        _super.call(this);
+    }
+    Object.defineProperty(AnimationWithStepsMetadata.prototype, "steps", {
+        get: function () { throw new exceptions_1.BaseException('NOT IMPLEMENTED: Base Class'); },
+        enumerable: true,
+        configurable: true
+    });
+    return AnimationWithStepsMetadata;
+}(AnimationMetadata));
+exports.AnimationWithStepsMetadata = AnimationWithStepsMetadata;
+/**
+ * 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.
+ */
+var AnimationSequenceMetadata = (function (_super) {
+    __extends(AnimationSequenceMetadata, _super);
+    function AnimationSequenceMetadata(_steps) {
+        _super.call(this);
+        this._steps = _steps;
+    }
+    Object.defineProperty(AnimationSequenceMetadata.prototype, "steps", {
+        get: function () { return this._steps; },
+        enumerable: true,
+        configurable: true
+    });
+    return AnimationSequenceMetadata;
+}(AnimationWithStepsMetadata));
+exports.AnimationSequenceMetadata = AnimationSequenceMetadata;
+/**
+ * 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.
+ */
+var AnimationGroupMetadata = (function (_super) {
+    __extends(AnimationGroupMetadata, _super);
+    function AnimationGroupMetadata(_steps) {
+        _super.call(this);
+        this._steps = _steps;
+    }
+    Object.defineProperty(AnimationGroupMetadata.prototype, "steps", {
+        get: function () { return this._steps; },
+        enumerable: true,
+        configurable: true
+    });
+    return AnimationGroupMetadata;
+}(AnimationWithStepsMetadata));
+exports.AnimationGroupMetadata = AnimationGroupMetadata;
+/**
+ * `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'}
+ */
+function animate(timing, styles) {
+    if (styles === void 0) { styles = null; }
+    var stylesEntry = styles;
+    if (!lang_1.isPresent(stylesEntry)) {
+        var EMPTY_STYLE = {};
+        stylesEntry = new AnimationStyleMetadata([EMPTY_STYLE], 1);
+    }
+    return new AnimationAnimateMetadata(timing, stylesEntry);
+}
+exports.animate = animate;
+/**
+ * `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'}
+ */
+function group(steps) {
+    return new AnimationGroupMetadata(steps);
+}
+exports.group = group;
+/**
+ * `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'}
+ */
+function sequence(steps) {
+    return new AnimationSequenceMetadata(steps);
+}
+exports.sequence = sequence;
+/**
+ * `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'}
+ */
+function style(tokens) {
+    var input;
+    var offset = null;
+    if (lang_1.isString(tokens)) {
+        input = [tokens];
+    }
+    else {
+        if (lang_1.isArray(tokens)) {
+            input = tokens;
+        }
+        else {
+            input = [tokens];
+        }
+        input.forEach(function (entry) {
+            var entryOffset = entry['offset'];
+            if (lang_1.isPresent(entryOffset)) {
+                offset = offset == null ? lang_1.NumberWrapper.parseFloat(entryOffset) : offset;
+            }
+        });
+    }
+    return new AnimationStyleMetadata(input, offset);
+}
+exports.style = style;
+/**
+ * `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).
+ *
+ * #### The `*` (default) state
+ *
+ * The `*` state (when styled) is a fallback state that will be used if
+ * the state that is being animated is not declared within the trigger.
+ *
+ * ### 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'}
+ */
+function state(stateNameExpr, styles) {
+    return new AnimationStateDeclarationMetadata(stateNameExpr, styles);
+}
+exports.state = state;
+/**
+ * `keyframes` 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.
+ *
+ * `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'}
+ */
+function keyframes(steps) {
+    return new AnimationKeyframesSequenceMetadata(steps);
+}
+exports.keyframes = keyframes;
+/**
+ * `transition` 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.
+ *
+ * `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'}
+ */
+function transition(stateChangeExpr, steps) {
+    var animationData = lang_1.isArray(steps) ? new AnimationSequenceMetadata(steps) :
+        steps;
+    return new AnimationStateTransitionMetadata(stateChangeExpr, animationData);
+}
+exports.transition = transition;
+/**
+ * `trigger` 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.
+ *
+ * `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'}
+ */
+function trigger(name, animation) {
+    return new AnimationEntryMetadata(name, animation);
+}
+exports.trigger = trigger;
+//# sourceMappingURL=metadata.js.map