@angular/animations 13.1.0-next.3 → 13.2.0-next.1

package/animations.d.ts

@@ -1,5 +1,5 @@
 /**
- * @license Angular v13.1.0-next.3
+ * @license Angular v13.2.0-next.1
  * (c) 2010-2021 Google LLC. https://angular.io/
  * License: MIT
  */
@@ -936,7 +936,9 @@ export declare class NoopAnimationPlayer implements AnimationPlayer {
  *
  * @param selector The element to query, or a set of elements that contain Angular-specific
  * characteristics, specified with one or more of the following tokens.
- *  - `query(":enter")` or `query(":leave")` : Query for newly inserted/removed elements.
+ *  - `query(":enter")` or `query(":leave")` : Query for newly inserted/removed elements (not
+ *     all elements can be queried via these tokens, see
+ *     [Entering and Leaving Elements](#entering-and-leaving-elements))
  *  - `query(":animating")` : Query all currently animating elements.
  *  - `query("@triggerName")` : Query elements that contain an animation trigger.
  *  - `query("@*")` : Query all elements that contain an animation triggers.
@@ -949,6 +951,9 @@ export declare class NoopAnimationPlayer implements AnimationPlayer {
  * @return An object that encapsulates the query data.
  *
  * @usageNotes
+ *
+ * ### Multiple Tokens
+ *
  * Tokens can be merged into a combined query selector string. For example:
  *
  * ```typescript
@@ -976,6 +981,26 @@ export declare class NoopAnimationPlayer implements AnimationPlayer {
  * ], { optional: true })
  * ```
  *
+ * ### Entering and Leaving Elements
+ *
+ * Not all elements can be queried via the `:enter` and `:leave` tokens, the only ones
+ * that can are those that Angular assumes can enter/leave based on their own logic
+ * (if their insertion/removal is simply a consequence of that of their parent they
+ * should be queried via a different token in their parent's `:enter`/`:leave` transitions).
+ *
+ * The only elements Angular assumes can enter/leave on their own logic (thus the only
+ * ones that can be queried via the `:enter` and `:leave` tokens) are:
+ *  - Those inserted dynamically (via `ViewContainerRef`)
+ *  - Those that have a structural directive (which, under the hood, are a subset of the above ones)
+ *
+ * <div class="alert is-helpful">
+ *
+ *  Note that elements will be successfully queried via `:enter`/`:leave` even if their
+ *  insertion/removal is not done manually via `ViewContainerRef`or caused by their structural
+ *  directive (e.g. they enter/exit alongside their parent).
+ *
+ * </div>
+ *
  * ### Usage Example
  *
  * The following example queries for inner elements and animates them
@@ -1217,170 +1242,148 @@ export declare function style(tokens: '*' | {
 }>): AnimationStyleMetadata;
 
 /**
- * Declares an animation transition as a sequence of animation steps to run when a given
- * condition is satisfied. The condition is a Boolean expression or function that compares
- * the previous and current animation states, and returns true if this transition should occur.
- * When the state criteria of a defined transition are met, the associated animation is
- * triggered.
- *
- * @param stateChangeExpr A Boolean expression or function that compares the previous and current
- * animation states, and returns true if this transition should occur. Note that  "true" and "false"
- * match 1 and 0, respectively. An expression is evaluated each time a state change occurs in the
- * animation trigger element.
- * The animation steps run when the expression evaluates to true.
- *
- * - A state-change string takes the form "state1 => state2", where each side is a defined animation
- * state, or an asterisk (*) to refer to a dynamic start or end state.
- *   - The expression string can contain multiple comma-separated statements;
- * for example "state1 => state2, state3 => state4".
- *   - Special values `:enter` and `:leave` initiate a transition on the entry and exit states,
- * equivalent to  "void => *"  and "* => void".
- *   - Special values `:increment` and `:decrement` initiate a transition when a numeric value has
- * increased or decreased in value.
- * - A function is executed each time a state change occurs in the animation trigger element.
- * The animation steps run when the function returns true.
- *
- * @param steps One or more animation objects, as returned by the `animate()` or
- * `sequence()` function, that form a transformation from one state to another.
- * A sequence is used by default when you pass an array.
- * @param options An options object that can contain a delay value for the start of the animation,
- * and additional developer-defined parameters. Provided values for additional parameters are used
- * as defaults, and override values can be passed to the caller on invocation.
- * @returns An object that encapsulates the transition data.
+ * Declares an animation transition which is played when a certain specified condition is met.
  *
- * @usageNotes
- * The template associated with a component binds an animation trigger to an element.
+ * @param stateChangeExpr A string with a specific format or a function that specifies when the
+ * animation transition should occur (see [State Change Expression](#state-change-expression)).
  *
- * ```HTML
- * <!-- somewhere inside of my-component-tpl.html -->
- * <div [@myAnimationTrigger]="myStatusExp">...</div>
- * ```
+ * @param steps One or more animation objects that represent the animation's instructions.
  *
- * All transitions are defined within an animation trigger,
- * along with named states that the transitions change to and from.
+ * @param options An options object that can be used to specify a delay for the animation or provide
+ * custom parameters for it.
  *
- * ```typescript
- * trigger("myAnimationTrigger", [
- *  // define states
- *  state("on", style({ background: "green" })),
- *  state("off", style({ background: "grey" })),
- *  ...]
- * ```
+ * @returns An object that encapsulates the transition data.
  *
- * Note that when you call the `sequence()` function within a `{@link animations/group group()}`
- * or a `transition()` call, execution does not continue to the next instruction
- * until each of the inner animation steps have completed.
+ * @usageNotes
  *
- * ### Syntax examples
+ * ### State Change Expression
+ *
+ * The State Change Expression instructs Angular when to run the transition's animations, it can
+ *either be
+ *  - a string with a specific syntax
+ *  - or a function that compares the previous and current state (value of the expression bound to
+ *    the element's trigger) and returns `true` if the transition should occur or `false` otherwise
+ *
+ * The string format can be:
+ *  - `fromState => toState`, which indicates that the transition's animations should occur then the
+ *    expression bound to the trigger's element goes from `fromState` to `toState`
+ *
+ *    _Example:_
+ *      ```typescript
+ *        transition('open => closed', animate('.5s ease-out', style({ height: 0 }) ))
+ *      ```
+ *
+ *  - `fromState <=> toState`, which indicates that the transition's animations should occur then
+ *    the expression bound to the trigger's element goes from `fromState` to `toState` or vice versa
+ *
+ *    _Example:_
+ *      ```typescript
+ *        transition('enabled <=> disabled', animate('1s cubic-bezier(0.8,0.3,0,1)'))
+ *      ```
+ *
+ *  - `:enter`/`:leave`, which indicates that the transition's animations should occur when the
+ *    element enters or exists the DOM
+ *
+ *    _Example:_
+ *      ```typescript
+ *        transition(':enter', [
+ *          style({ opacity: 0 }),
+ *          animate('500ms', style({ opacity: 1 }))
+ *        ])
+ *      ```
+ *
+ *  - `:increment`/`:decrement`, which indicates that the transition's animations should occur when
+ *    the numerical expression bound to the trigger's element has increased in value or decreased
+ *
+ *    _Example:_
+ *      ```typescript
+ *        transition(':increment', query('@counter', animateChild()))
+ *      ```
+ *
+ *  - a sequence of any of the above divided by commas, which indicates that transition's animations
+ *    should occur whenever one of the state change expressions matches
+ *
+ *    _Example:_
+ *      ```typescript
+ *        transition(':increment, * => enabled, :enter', animate('1s ease', keyframes([
+ *          style({ transform: 'scale(1)', offset: 0}),
+ *          style({ transform: 'scale(1.1)', offset: 0.7}),
+ *          style({ transform: 'scale(1)', offset: 1})
+ *        ]))),
+ *      ```
+ *
+ * Also note that in such context:
+ *  - `void` can be used to indicate the absence of the element
+ *  - asterisks can be used as wildcards that match any state
+ *  - (as a consequence of the above, `void => *` is equivalent to `:enter` and `* => void` is
+ *    equivalent to `:leave`)
+ *  - `true` and `false` also match expression values of `1` and `0` respectively (but do not match
+ *    _truthy_ and _falsy_ values)
+ *
+ * <div class="alert is-helpful">
+ *
+ *  Be careful about entering end leaving elements as their transitions present a common
+ *  pitfall for developers.
+ *
+ *  Note that when an element with a trigger enters the DOM its `:enter` transition always
+ *  gets executed, but its `:leave` transition will not be executed if the element is removed
+ *  alongside its parent (as it will be removed "without warning" before its transition has
+ *  a chance to be executed, the only way that such transition can occur is if the element
+ *  is exiting the DOM on its own).
  *
- * The following examples define transitions between the two defined states (and default states),
- * using various options:
  *
- * ```typescript
- * // Transition occurs when the state value
- * // bound to "myAnimationTrigger" changes from "on" to "off"
- * transition("on => off", animate(500))
- * // Run the same animation for both directions
- * transition("on <=> off", animate(500))
- * // Define multiple state-change pairs separated by commas
- * transition("on => off, off => void", animate(500))
- * ```
+ * </div>
  *
- * ### Special values for state-change expressions
+ * ### Animating to a Final State
  *
- * - Catch-all state change for when an element is inserted into the page and the
- * destination state is unknown:
+ * If the final step in a transition is a call to `animate()` that uses a timing value
+ * with no `style` data, that step is automatically considered the final animation arc,
+ * for the element to reach the final state, in such case Angular automatically adds or removes
+ * CSS styles to ensure that the element is in the correct final state.
  *
- * ```typescript
- * transition("void => *", [
- *  style({ opacity: 0 }),
- *  animate(500)
- *  ])
- * ```
  *
- * - Capture a state change between any states:
+ * ### Usage Examples
  *
- *  `transition("* => *", animate("1s 0s"))`
+ *  - Transition animations applied based on
+ *    the trigger's expression value
  *
- * - Entry and exit transitions:
+ *   ```HTML
+ *   <div [@myAnimationTrigger]="myStatusExp">
+ *    ...
+ *   </div>
+ *   ```
  *
- * ```typescript
- * transition(":enter", [
- *   style({ opacity: 0 }),
- *   animate(500, style({ opacity: 1 }))
- *   ]),
- * transition(":leave", [
- *   animate(500, style({ opacity: 0 }))
+ *   ```typescript
+ *   trigger("myAnimationTrigger", [
+ *     ..., // states
+ *     transition("on => off, open => closed", animate(500)),
+ *     transition("* <=> error", query('.indicator', animateChild()))
  *   ])
- * ```
- *
- * - Use `:increment` and `:decrement` to initiate transitions:
- *
- * ```typescript
- * transition(":increment", group([
- *  query(':enter', [
- *     style({ left: '100%' }),
- *     animate('0.5s ease-out', style('*'))
- *   ]),
- *  query(':leave', [
- *     animate('0.5s ease-out', style({ left: '-100%' }))
- *  ])
- * ]))
- *
- * transition(":decrement", group([
- *  query(':enter', [
- *     style({ left: '100%' }),
- *     animate('0.5s ease-out', style('*'))
- *   ]),
- *  query(':leave', [
- *     animate('0.5s ease-out', style({ left: '-100%' }))
- *  ])
- * ]))
- * ```
- *
- * ### State-change functions
- *
- * Here is an example of a `fromState` specified as a state-change function that invokes an
- * animation when true:
- *
- * ```typescript
- * transition((fromState, toState) =>
- *  {
- *   return fromState == "off" && toState == "on";
- *  },
- *  animate("1s 0s"))
- * ```
+ *   ```
  *
- * ### Animating to the final state
+ *  - Transition animations applied based on custom logic dependent
+ *    on the trigger's expression value and provided parameters
  *
- * If the final step in a transition is a call to `animate()` that uses a timing value
- * with no style data, that step is automatically considered the final animation arc,
- * for the element to reach the final state. Angular automatically adds or removes
- * CSS styles to ensure that the element is in the correct final state.
- *
- * The following example defines a transition that starts by hiding the element,
- * then makes sure that it animates properly to whatever state is currently active for trigger:
- *
- * ```typescript
- * transition("void => *", [
- *   style({ opacity: 0 }),
- *   animate(500)
- *  ])
- * ```
- * ### Boolean value matching
- * If a trigger binding value is a Boolean, it can be matched using a transition expression
- * that compares true and false or 1 and 0. For example:
- *
- * ```
- * // in the template
- * <div [@openClose]="open ? true : false">...</div>
- * // in the component metadata
- * trigger('openClose', [
- *   state('true', style({ height: '*' })),
- *   state('false', style({ height: '0px' })),
- *   transition('false <=> true', animate(500))
- * ])
- * ```
+ *    ```HTML
+ *    <div [@myAnimationTrigger]="{
+ *     value: stepName,
+ *     params: { target: currentTarget }
+ *    }">
+ *     ...
+ *    </div>
+ *    ```
+ *
+ *    ```typescript
+ *    trigger("myAnimationTrigger", [
+ *      ..., // states
+ *      transition(
+ *        (fromState, toState, _element, params) =>
+ *          ['firststep', 'laststep'].includes(fromState.toLowerCase())
+ *          && toState === params?.['target'],
+ *        animate('1s')
+ *      )
+ *    ])
+ *    ```
  *
  * @publicApi
  **/

package/browser/browser.d.ts

@@ -1,5 +1,5 @@
 /**
- * @license Angular v13.1.0-next.3
+ * @license Angular v13.2.0-next.1
  * (c) 2010-2021 Google LLC. https://angular.io/
  * License: MIT
  */
@@ -17,6 +17,9 @@ import { ɵStyleData } from '@angular/animations';
 export declare abstract class AnimationDriver {
     static NOOP: AnimationDriver;
     abstract validateStyleProperty(prop: string): boolean;
+    /**
+     * @deprecated No longer in use. Will be removed.
+     */
     abstract matchesElement(element: any, selector: string): boolean;
     abstract containsElement(elm1: any, elm2: any): boolean;
     abstract query(element: any, selector: string, multi: boolean): any[];
@@ -72,7 +75,7 @@ declare interface DOMAnimation {
 
 declare class ElementInstructionMap {
     private _map;
-    consume(element: any): AnimationTimelineInstruction[];
+    get(element: any): AnimationTimelineInstruction[];
     append(element: any, instructions: AnimationTimelineInstruction[]): void;
     has(element: any): boolean;
     clear(): void;
@@ -150,7 +153,7 @@ export declare const ɵcontainsElement: (elm1: any, elm2: any) => boolean;
 export declare class ɵCssKeyframesDriver implements AnimationDriver {
     private _count;
     validateStyleProperty(prop: string): boolean;
-    matchesElement(element: any, selector: string): boolean;
+    matchesElement(_element: any, _selector: string): boolean;
     containsElement(elm1: any, elm2: any): boolean;
     query(element: any, selector: string, multi: boolean): any[];
     computeStyle(element: any, prop: string, defaultValue?: string): string;
@@ -207,14 +210,12 @@ export declare class ɵCssKeyframesPlayer implements AnimationPlayer {
 
 export declare const ɵinvokeQuery: (element: any, selector: string, multi: boolean) => any[];
 
-export declare const ɵmatchesElement: (element: any, selector: string) => boolean;
-
 /**
  * @publicApi
  */
 export declare class ɵNoopAnimationDriver implements AnimationDriver {
     validateStyleProperty(prop: string): boolean;
-    matchesElement(element: any, selector: string): boolean;
+    matchesElement(_element: any, _selector: string): boolean;
     containsElement(elm1: any, elm2: any): boolean;
     query(element: any, selector: string, multi: boolean): any[];
     computeStyle(element: any, prop: string, defaultValue?: string): string;
@@ -241,7 +242,7 @@ export declare class ɵWebAnimationsDriver implements AnimationDriver {
     private _isNativeImpl;
     private _cssKeyframesDriver;
     validateStyleProperty(prop: string): boolean;
-    matchesElement(element: any, selector: string): boolean;
+    matchesElement(_element: any, _selector: string): boolean;
     containsElement(elm1: any, elm2: any): boolean;
     query(element: any, selector: string, multi: boolean): any[];
     computeStyle(element: any, prop: string, defaultValue?: string): string;
@@ -267,7 +268,7 @@ export declare class ɵWebAnimationsPlayer implements AnimationPlayer {
     private _finished;
     private _started;
     private _destroyed;
-    private _finalKeyframe;
+    private _finalKeyframe?;
     readonly domPlayer: DOMAnimation;
     time: number;
     parentPlayer: AnimationPlayer | null;

package/browser/testing/testing.d.ts

@@ -1,5 +1,5 @@
 /**
- * @license Angular v13.1.0-next.3
+ * @license Angular v13.2.0-next.1
  * (c) 2010-2021 Google LLC. https://angular.io/
  * License: MIT
  */
@@ -15,7 +15,7 @@ import { ɵStyleData } from '@angular/animations';
 export declare class MockAnimationDriver implements AnimationDriver {
     static log: AnimationPlayer[];
     validateStyleProperty(prop: string): boolean;
-    matchesElement(element: any, selector: string): boolean;
+    matchesElement(_element: any, _selector: string): boolean;
     containsElement(elm1: any, elm2: any): boolean;
     query(element: any, selector: string, multi: boolean): any[];
     computeStyle(element: any, prop: string, defaultValue?: string): string;