From 005dc8f68b9d09f2a4db46bdbfae3e05d3604818 Mon Sep 17 00:00:00 2001 From: Pete Bacon Darwin Date: Thu, 3 May 2018 10:30:58 +0100 Subject: [PATCH] docs(animations): fix content errors (#23668) PR Close #23668 --- packages/animations/src/animation_metadata.ts | 120 ++++++++++-------- 1 file changed, 67 insertions(+), 53 deletions(-) diff --git a/packages/animations/src/animation_metadata.ts b/packages/animations/src/animation_metadata.ts index cd0e463c06..a139972f21 100755 --- a/packages/animations/src/animation_metadata.ts +++ b/packages/animations/src/animation_metadata.ts @@ -236,8 +236,8 @@ export declare interface AnimationQueryOptions extends AnimationOptions { * Metadata representing the entry of animations. Instances of this interface are provided via the * animation DSL when the {@link stagger stagger animation function} is called. * -* @experimental Animation support is experimental. -*/ + * @experimental Animation support is experimental. + */ export interface AnimationStaggerMetadata extends AnimationMetadata { timings: string|number; animation: AnimationMetadata|AnimationMetadata[]; @@ -256,15 +256,14 @@ export interface AnimationStaggerMetadata extends AnimationMetadata { * Triggers are registered within the component annotation data under the * {@link Component#animations 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"`. + * the trigger is bound to (in the form of `[@triggerName]="expression"`. * * Animation trigger bindings strigify values and then match the previous and current values against * any linked transitions. If a boolean value is provided into the trigger binding then it will both * be represented as `1` or `true` and `0` or `false` for a true and false boolean values * respectively. * - * ### Usage + * **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 @@ -289,22 +288,27 @@ export interface AnimationStaggerMetadata extends AnimationMetadata { * ``` * * The template associated with this component will make use of the `myAnimationTrigger` animation - trigger by binding to an element within its template code. + * trigger by binding to an element within its template code. * * ```html * *
...
* ``` * - * ### Using an inline function + * **Using an inline function** + * * The `transition` animation method also supports reading an inline function which can decide * if its associated animation should be run. * * ``` * // this method will be run each time the `myAnimationTrigger` * // trigger value changes... - * function myInlineMatcherFn(fromState: string, toState: string, element: any, params: {[key: - string]: any}): boolean { + * function myInlineMatcherFn( + * fromState: string, + * toState: string, + * element: any, + * params: {[key: string]: any} + * ): boolean { * // notice that `element` and `params` are also available here * return toState == 'yes-please-animate'; * } @@ -328,13 +332,14 @@ export interface AnimationStaggerMetadata extends AnimationMetadata { * The inline method will be run each time the trigger * value changes * - * ## Disable Animations + * **Disable Animations** + * * A special animation control binding called `@.disabled` can be placed on an element which will - then disable animations for any inner animation triggers situated within the element as well as - any animations on the element itself. + * then disable animations for any inner animation triggers situated within the element as well as + * any animations on the element itself. * * When true, the `@.disabled` binding will prevent all animations from rendering. The example - below shows how to use this feature: + * below shows how to use this feature: * * ```ts * @Component({ @@ -357,16 +362,17 @@ export interface AnimationStaggerMetadata extends AnimationMetadata { * ``` * * The `@childAnimation` trigger will not animate because `@.disabled` prevents it from happening - (when true). + * (when true). * * Note that `@.disabled` will only disable all animations (this means any animations running on * the same element will also be disabled). * - * ### Disabling Animations Application-wide + * **Disabling Animations Application-wide** + * * When an area of the template is set to have animations disabled, **all** inner components will - also have their animations disabled as well. This means that all animations for an angular - application can be disabled by placing a host binding set on `@.disabled` on the topmost Angular - component. + * also have their animations disabled as well. This means that all animations for an angular + * application can be disabled by placing a host binding set on `@.disabled` on the topmost Angular + * component. * * ```ts * import {Component, HostBinding} from '@angular/core'; @@ -381,19 +387,20 @@ export interface AnimationStaggerMetadata extends AnimationMetadata { * } * ``` * - * ### What about animations that us `query()` and `animateChild()`? - * Despite inner animations being disabled, a parent animation can {@link query query} for inner - elements located in disabled areas of the template and still animate them as it sees fit. This is - also the case for when a sub animation is queried by a parent and then later animated using {@link - animateChild animateChild}. - - * ### Detecting when an animation is disabled + * **What about animations that use `query()` and `animateChild()`?** + * + * Despite inner animations being disabled, a parent animation can `query` for inner + * elements located in disabled areas of the template and still animate them as it sees fit. This is + * also the case for when a sub animation is queried by a parent and then later animated using + * animateChild`. + * + * **Detecting when an animation is disabled** + * * If a region of the DOM (or the entire application) has its animations disabled, then animation * trigger callbacks will still fire just as normal (only for zero seconds). * * When a trigger callback fires it will provide an instance of an {@link AnimationEvent}. If - animations - * are disabled then the `.disabled` flag on the event will be true. + * animations are disabled then the `.disabled` flag on the event will be true. * * @experimental Animation support is experimental. */ @@ -403,8 +410,8 @@ export function trigger(name: string, definitions: AnimationMetadata[]): Animati /** * `animate` is an animation-specific function that is designed to be used inside of Angular's - * animation DSL language. If this information is new, please navigate to the {@link - * Component#animations component animations metadata page} to gain a better understanding of + * animation DSL language. If this information is new, please navigate to the + * {@link Component#animations component animations metadata page} to gain a better understanding of * how animations in Angular are used. * * `animate` specifies an animation step that will apply the provided `styles` data for a given @@ -412,7 +419,8 @@ export function trigger(name: string, definitions: AnimationMetadata[]): Animati * to be used within {@link sequence an animation sequence}, {@link group group}, or {@link * transition transition}. * - * ### Usage + * {@a usage} + * **Usage** * * The `animate` function accepts two input parameters: `timing` and `styles`: * @@ -465,7 +473,7 @@ export function animate( * transition} and it will only continue to the next instruction once all of the inner animation * steps have completed. * - * ### Usage + * **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()` @@ -504,7 +512,7 @@ export function group( * To perform animation styling in parallel with other animation steps then have a look at the * {@link group group} animation function. * - * ### Usage + * **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 @@ -529,15 +537,15 @@ export function sequence(steps: AnimationMetadata[], options: AnimationOptions | /** * `style` is an animation-specific function that is designed to be used inside of Angular's - * animation DSL language. If this information is new, please navigate to the {@link - * Component#animations component animations metadata page} to gain a better understanding of + * animation DSL language. If this information is new, please navigate to the + * {@link Component#animations component animations metadata page} to gain a better understanding of * how animations in Angular 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 + * **Usage** * * `style` takes in a key/value string map as data and expects one or more CSS property/value pairs * to be defined. @@ -550,7 +558,7 @@ export function sequence(steps: AnimationMetadata[], options: AnimationOptions | * style({ width: 100, height: 0 }) * ``` * - * #### Auto-styles (using `*`) + * **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. @@ -589,18 +597,18 @@ export function style( * function. To register states to an animation trigger please have a look at the {@link trigger * trigger} function. * - * #### The `void` state + * **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 `*` (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 + * **Usage** * * `state` will declare an animation state with its associated styles * within the given trigger. @@ -631,14 +639,14 @@ export function state( /** * `keyframes` is an animation-specific function that is designed to be used inside of Angular's - * animation DSL language. If this information is new, please navigate to the {@link - * Component#animations component animations metadata page} to gain a better understanding of - * how animations in Angular are used. + * animation DSL language. If this information is new, please navigate to the + * {@link Component#animations component animations metadata page} to gain a better understanding + * of how animations in Angular are used. * * `keyframes` specifies a collection of {@link style style} entries each optionally characterized * by an `offset` value. * - * ### Usage + * **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 @@ -697,7 +705,7 @@ export function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSe * to animate to a state value and persist its styles then one or more {@link state animation * states} is expected to be defined. * - * ### Usage + * **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 @@ -748,7 +756,8 @@ export function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSe *
...
* ``` * - * #### The final `animate` call + * {@a the-final-animate-call} + * **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 @@ -765,7 +774,7 @@ export function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSe * ]) * ``` * - * ### Using :enter and :leave + * **Using :enter and :leave** * * Given that enter (insertion) and leave (removal) animations are so common, the `transition` * function accepts both `:enter` and `:leave` values which are aliases for the `void => *` and `* @@ -781,7 +790,8 @@ export function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSe * ]) * ``` * - * ### Boolean values + * **Boolean values** + * * if a trigger binding value is a boolean value then it can be matched using a transition * expression that compares `true` and `false` or `1` and `0`. * @@ -797,7 +807,8 @@ export function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSe * ]) * ``` * - * ### Using :increment and :decrement + * **Using :increment and :decrement** + * * In addition to the :enter and :leave transition aliases, the :increment and :decrement aliases * can be used to kick off a transition when a numeric value has increased or decreased in value. * @@ -1006,7 +1017,8 @@ export function animation( * * Now each of the sub animations start off with respect to the `100ms` staggering step. * - * ## The first frame of child animations + * **The first frame of child animations** + * * When sub animations are executed using `animateChild` the animation engine will always apply the * first frame of every sub animation immediately at the start of the animation sequence. This way * the parent animation does not need to set any initial styling data on the sub elements before the @@ -1050,7 +1062,7 @@ export function useAnimation( * to the queried element (by default, an array is provided, then this will be * treated as an animation sequence). * - * ### Usage + * **Usage** * * query() is designed to collect multiple elements and works internally by using * `element.querySelectorAll`. An additional options object can be provided which @@ -1073,7 +1085,8 @@ export function useAnimation( * ], { optional: true }) * ``` * - * ### Special Selector Values + * **Special Selector Values** + * * * The selector value within a query can collect elements that contain angular-specific * characteristics @@ -1095,7 +1108,8 @@ export function useAnimation( * query(':self, .record:enter, .record:leave, @subTrigger', [...]) * ``` * - * ### Demo + * **Demo** + * * * ``` * @Component({ @@ -1144,7 +1158,7 @@ export function query( * animation DSL language. It is designed to be used inside of an animation {@link query query()} * and works by issuing a timing gap between after each queried item is animated. * - * ### Usage + * **Usage** * * In the example below there is a container element that wraps a list of items stamped out * by an ngFor. The container element contains an animation trigger that will later be set