@angular/animations 14.0.0-next.13 → 14.0.0-next.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,1622 +1,1623 @@
1
1
  /**
2
- * @license Angular v14.0.0-next.13
2
+ * @license Angular v14.0.0-next.16
3
3
  * (c) 2010-2022 Google LLC. https://angular.io/
4
4
  * License: MIT
5
5
  */
6
6
 
7
- /**
8
- * Defines an animation step that combines styling information with timing information.
9
- *
10
- * @param timings Sets `AnimateTimings` for the parent animation.
11
- * A string in the format "duration [delay] [easing]".
12
- * - Duration and delay are expressed as a number and optional time unit,
13
- * such as "1s" or "10ms" for one second and 10 milliseconds, respectively.
14
- * The default unit is milliseconds.
15
- * - The easing value controls how the animation accelerates and decelerates
16
- * during its runtime. Value is one of `ease`, `ease-in`, `ease-out`,
17
- * `ease-in-out`, or a `cubic-bezier()` function call.
18
- * If not supplied, no easing is applied.
19
- *
20
- * For example, the string "1s 100ms ease-out" specifies a duration of
21
- * 1000 milliseconds, and delay of 100 ms, and the "ease-out" easing style,
22
- * which decelerates near the end of the duration.
23
- * @param styles Sets AnimationStyles for the parent animation.
24
- * A function call to either `style()` or `keyframes()`
25
- * that returns a collection of CSS style entries to be applied to the parent animation.
26
- * When null, uses the styles from the destination state.
27
- * This is useful when describing an animation step that will complete an animation;
28
- * see "Animating to the final state" in `transitions()`.
29
- * @returns An object that encapsulates the animation step.
30
- *
31
- * @usageNotes
32
- * Call within an animation `sequence()`, `{@link animations/group group()}`, or
33
- * `transition()` call to specify an animation step
34
- * that applies given style data to the parent animation for a given amount of time.
35
- *
36
- * ### Syntax Examples
37
- * **Timing examples**
38
- *
39
- * The following examples show various `timings` specifications.
40
- * - `animate(500)` : Duration is 500 milliseconds.
41
- * - `animate("1s")` : Duration is 1000 milliseconds.
42
- * - `animate("100ms 0.5s")` : Duration is 100 milliseconds, delay is 500 milliseconds.
43
- * - `animate("5s ease-in")` : Duration is 5000 milliseconds, easing in.
44
- * - `animate("5s 10ms cubic-bezier(.17,.67,.88,.1)")` : Duration is 5000 milliseconds, delay is 10
45
- * milliseconds, easing according to a bezier curve.
46
- *
47
- * **Style examples**
48
- *
49
- * The following example calls `style()` to set a single CSS style.
50
- * ```typescript
51
- * animate(500, style({ background: "red" }))
52
- * ```
53
- * The following example calls `keyframes()` to set a CSS style
54
- * to different values for successive keyframes.
55
- * ```typescript
56
- * animate(500, keyframes(
57
- * [
58
- * style({ background: "blue" }),
59
- * style({ background: "red" })
60
- * ])
61
- * ```
62
- *
63
- * @publicApi
64
- */
65
- export declare function animate(timings: string | number, styles?: AnimationStyleMetadata | AnimationKeyframesSequenceMetadata | null): AnimationAnimateMetadata;
66
-
67
- /**
68
- * Executes a queried inner animation element within an animation sequence.
69
- *
70
- * @param options An options object that can contain a delay value for the start of the
71
- * animation, and additional override values for developer-defined parameters.
72
- * @return An object that encapsulates the child animation data.
73
- *
74
- * @usageNotes
75
- * Each time an animation is triggered in Angular, the parent animation
76
- * has priority and any child animations are blocked. In order
77
- * for a child animation to run, the parent animation must query each of the elements
78
- * containing child animations, and run them using this function.
79
- *
80
- * Note that this feature is designed to be used with `query()` and it will only work
81
- * with animations that are assigned using the Angular animation library. CSS keyframes
82
- * and transitions are not handled by this API.
83
- *
84
- * @publicApi
85
- */
86
- export declare function animateChild(options?: AnimateChildOptions | null): AnimationAnimateChildMetadata;
87
-
88
- /**
89
- * Adds duration options to control animation styling and timing for a child animation.
90
- *
91
- * @see `animateChild()`
92
- *
93
- * @publicApi
94
- */
95
- export declare interface AnimateChildOptions extends AnimationOptions {
96
- duration?: number | string;
97
- }
98
-
99
- /**
100
- * Represents animation-step timing parameters for an animation step.
101
- * @see `animate()`
102
- *
103
- * @publicApi
104
- */
105
- export declare type AnimateTimings = {
106
- /**
107
- * The full duration of an animation step. A number and optional time unit,
108
- * such as "1s" or "10ms" for one second and 10 milliseconds, respectively.
109
- * The default unit is milliseconds.
110
- */
111
- duration: number;
112
- /**
113
- * The delay in applying an animation step. A number and optional time unit.
114
- * The default unit is milliseconds.
115
- */
116
- delay: number;
117
- /**
118
- * An easing style that controls how an animations step accelerates
119
- * and decelerates during its run time. An easing function such as `cubic-bezier()`,
120
- * or one of the following constants:
121
- * - `ease-in`
122
- * - `ease-out`
123
- * - `ease-in-and-out`
124
- */
125
- easing: string | null;
126
- };
127
-
128
- /**
129
- * Produces a reusable animation that can be invoked in another animation or sequence,
130
- * by calling the `useAnimation()` function.
131
- *
132
- * @param steps One or more animation objects, as returned by the `animate()`
133
- * or `sequence()` function, that form a transformation from one state to another.
134
- * A sequence is used by default when you pass an array.
135
- * @param options An options object that can contain a delay value for the start of the
136
- * animation, and additional developer-defined parameters.
137
- * Provided values for additional parameters are used as defaults,
138
- * and override values can be passed to the caller on invocation.
139
- * @returns An object that encapsulates the animation data.
140
- *
141
- * @usageNotes
142
- * The following example defines a reusable animation, providing some default parameter
143
- * values.
144
- *
145
- * ```typescript
146
- * var fadeAnimation = animation([
147
- * style({ opacity: '{{ start }}' }),
148
- * animate('{{ time }}',
149
- * style({ opacity: '{{ end }}'}))
150
- * ],
151
- * { params: { time: '1000ms', start: 0, end: 1 }});
152
- * ```
153
- *
154
- * The following invokes the defined animation with a call to `useAnimation()`,
155
- * passing in override parameter values.
156
- *
157
- * ```js
158
- * useAnimation(fadeAnimation, {
159
- * params: {
160
- * time: '2s',
161
- * start: 1,
162
- * end: 0
163
- * }
164
- * })
165
- * ```
166
- *
167
- * If any of the passed-in parameter values are missing from this call,
168
- * the default values are used. If one or more parameter values are missing before a step is
169
- * animated, `useAnimation()` throws an error.
170
- *
171
- * @publicApi
172
- */
173
- export declare function animation(steps: AnimationMetadata | AnimationMetadata[], options?: AnimationOptions | null): AnimationReferenceMetadata;
174
-
175
- /**
176
- * Encapsulates a child animation, that can be run explicitly when the parent is run.
177
- * Instantiated and returned by the `animateChild` function.
178
- *
179
- * @publicApi
180
- */
181
- export declare interface AnimationAnimateChildMetadata extends AnimationMetadata {
182
- /**
183
- * An options object containing a delay and
184
- * developer-defined parameters that provide styling defaults and
185
- * can be overridden on invocation. Default delay is 0.
186
- */
187
- options: AnimationOptions | null;
188
- }
189
-
190
- /**
191
- * Encapsulates an animation step. Instantiated and returned by
192
- * the `animate()` function.
193
- *
194
- * @publicApi
195
- */
196
- export declare interface AnimationAnimateMetadata extends AnimationMetadata {
197
- /**
198
- * The timing data for the step.
199
- */
200
- timings: string | number | AnimateTimings;
201
- /**
202
- * A set of styles used in the step.
203
- */
204
- styles: AnimationStyleMetadata | AnimationKeyframesSequenceMetadata | null;
205
- }
206
-
207
- /**
208
- * Encapsulates a reusable animation.
209
- * Instantiated and returned by the `useAnimation()` function.
210
- *
211
- * @publicApi
212
- */
213
- export declare interface AnimationAnimateRefMetadata extends AnimationMetadata {
214
- /**
215
- * An animation reference object.
216
- */
217
- animation: AnimationReferenceMetadata;
218
- /**
219
- * An options object containing a delay and
220
- * developer-defined parameters that provide styling defaults and
221
- * can be overridden on invocation. Default delay is 0.
222
- */
223
- options: AnimationOptions | null;
224
- }
225
-
226
- /**
227
- * An injectable service that produces an animation sequence programmatically within an
228
- * Angular component or directive.
229
- * Provided by the `BrowserAnimationsModule` or `NoopAnimationsModule`.
230
- *
231
- * @usageNotes
232
- *
233
- * To use this service, add it to your component or directive as a dependency.
234
- * The service is instantiated along with your component.
235
- *
236
- * Apps do not typically need to create their own animation players, but if you
237
- * do need to, follow these steps:
238
- *
239
- * 1. Use the <code>[AnimationBuilder.build](api/animations/AnimationBuilder#build)()</code> method
240
- * to create a programmatic animation. The method returns an `AnimationFactory` instance.
241
- *
242
- * 2. Use the factory object to create an `AnimationPlayer` and attach it to a DOM element.
243
- *
244
- * 3. Use the player object to control the animation programmatically.
245
- *
246
- * For example:
247
- *
248
- * ```ts
249
- * // import the service from BrowserAnimationsModule
250
- * import {AnimationBuilder} from '@angular/animations';
251
- * // require the service as a dependency
252
- * class MyCmp {
253
- * constructor(private _builder: AnimationBuilder) {}
254
- *
255
- * makeAnimation(element: any) {
256
- * // first define a reusable animation
257
- * const myAnimation = this._builder.build([
258
- * style({ width: 0 }),
259
- * animate(1000, style({ width: '100px' }))
260
- * ]);
261
- *
262
- * // use the returned factory object to create a player
263
- * const player = myAnimation.create(element);
264
- *
265
- * player.play();
266
- * }
267
- * }
268
- * ```
269
- *
270
- * @publicApi
271
- */
272
- export declare abstract class AnimationBuilder {
273
- /**
274
- * Builds a factory for producing a defined animation.
275
- * @param animation A reusable animation definition.
276
- * @returns A factory object that can create a player for the defined animation.
277
- * @see `animate()`
278
- */
279
- abstract build(animation: AnimationMetadata | AnimationMetadata[]): AnimationFactory;
280
- }
281
-
282
-
283
- /**
284
- * An instance of this class is returned as an event parameter when an animation
285
- * callback is captured for an animation either during the start or done phase.
286
- *
287
- * ```typescript
288
- * @Component({
289
- * host: {
290
- * '[@myAnimationTrigger]': 'someExpression',
291
- * '(@myAnimationTrigger.start)': 'captureStartEvent($event)',
292
- * '(@myAnimationTrigger.done)': 'captureDoneEvent($event)',
293
- * },
294
- * animations: [
295
- * trigger("myAnimationTrigger", [
296
- * // ...
297
- * ])
298
- * ]
299
- * })
300
- * class MyComponent {
301
- * someExpression: any = false;
302
- * captureStartEvent(event: AnimationEvent) {
303
- * // the toState, fromState and totalTime data is accessible from the event variable
304
- * }
305
- *
306
- * captureDoneEvent(event: AnimationEvent) {
307
- * // the toState, fromState and totalTime data is accessible from the event variable
308
- * }
309
- * }
310
- * ```
311
- *
312
- * @publicApi
313
- */
314
- declare interface AnimationEvent_2 {
315
- /**
316
- * The name of the state from which the animation is triggered.
317
- */
318
- fromState: string;
319
- /**
320
- * The name of the state in which the animation completes.
321
- */
322
- toState: string;
323
- /**
324
- * The time it takes the animation to complete, in milliseconds.
325
- */
326
- totalTime: number;
327
- /**
328
- * The animation phase in which the callback was invoked, one of
329
- * "start" or "done".
330
- */
331
- phaseName: string;
332
- /**
333
- * The element to which the animation is attached.
334
- */
335
- element: any;
336
- /**
337
- * Internal.
338
- */
339
- triggerName: string;
340
- /**
341
- * Internal.
342
- */
343
- disabled: boolean;
344
- }
345
- export { AnimationEvent_2 as AnimationEvent }
346
-
347
- /**
348
- * A factory object returned from the
349
- * <code>[AnimationBuilder.build](api/animations/AnimationBuilder#build)()</code>
350
- * method.
351
- *
352
- * @publicApi
353
- */
354
- export declare abstract class AnimationFactory {
355
- /**
356
- * Creates an `AnimationPlayer` instance for the reusable animation defined by
357
- * the <code>[AnimationBuilder.build](api/animations/AnimationBuilder#build)()</code>
358
- * method that created this factory and attaches the new player a DOM element.
359
- *
360
- * @param element The DOM element to which to attach the player.
361
- * @param options A set of options that can include a time delay and
362
- * additional developer-defined parameters.
363
- */
364
- abstract create(element: any, options?: AnimationOptions): AnimationPlayer;
365
- }
366
-
367
- /**
368
- * Encapsulates an animation group.
369
- * Instantiated and returned by the `{@link animations/group group()}` function.
370
- *
371
- * @publicApi
372
- */
373
- export declare interface AnimationGroupMetadata extends AnimationMetadata {
374
- /**
375
- * One or more animation or style steps that form this group.
376
- */
377
- steps: AnimationMetadata[];
378
- /**
379
- * An options object containing a delay and
380
- * developer-defined parameters that provide styling defaults and
381
- * can be overridden on invocation. Default delay is 0.
382
- */
383
- options: AnimationOptions | null;
384
- }
385
-
386
- /**
387
- * Encapsulates a keyframes sequence. Instantiated and returned by
388
- * the `keyframes()` function.
389
- *
390
- * @publicApi
391
- */
392
- export declare interface AnimationKeyframesSequenceMetadata extends AnimationMetadata {
393
- /**
394
- * An array of animation styles.
395
- */
396
- steps: AnimationStyleMetadata[];
397
- }
398
-
399
- /**
400
- * Base for animation data structures.
401
- *
402
- * @publicApi
403
- */
404
- export declare interface AnimationMetadata {
405
- type: AnimationMetadataType;
406
- }
407
-
408
- /**
409
- * @description Constants for the categories of parameters that can be defined for animations.
410
- *
411
- * A corresponding function defines a set of parameters for each category, and
412
- * collects them into a corresponding `AnimationMetadata` object.
413
- *
414
- * @publicApi
415
- */
416
- export declare const enum AnimationMetadataType {
417
- /**
418
- * Associates a named animation state with a set of CSS styles.
419
- * See [`state()`](api/animations/state)
420
- */
421
- State = 0,
422
- /**
423
- * Data for a transition from one animation state to another.
424
- * See `transition()`
425
- */
426
- Transition = 1,
427
- /**
428
- * Contains a set of animation steps.
429
- * See `sequence()`
430
- */
431
- Sequence = 2,
432
- /**
433
- * Contains a set of animation steps.
434
- * See `{@link animations/group group()}`
435
- */
436
- Group = 3,
437
- /**
438
- * Contains an animation step.
439
- * See `animate()`
440
- */
441
- Animate = 4,
442
- /**
443
- * Contains a set of animation steps.
444
- * See `keyframes()`
445
- */
446
- Keyframes = 5,
447
- /**
448
- * Contains a set of CSS property-value pairs into a named style.
449
- * See `style()`
450
- */
451
- Style = 6,
452
- /**
453
- * Associates an animation with an entry trigger that can be attached to an element.
454
- * See `trigger()`
455
- */
456
- Trigger = 7,
457
- /**
458
- * Contains a re-usable animation.
459
- * See `animation()`
460
- */
461
- Reference = 8,
462
- /**
463
- * Contains data to use in executing child animations returned by a query.
464
- * See `animateChild()`
465
- */
466
- AnimateChild = 9,
467
- /**
468
- * Contains animation parameters for a re-usable animation.
469
- * See `useAnimation()`
470
- */
471
- AnimateRef = 10,
472
- /**
473
- * Contains child-animation query data.
474
- * See `query()`
475
- */
476
- Query = 11,
477
- /**
478
- * Contains data for staggering an animation sequence.
479
- * See `stagger()`
480
- */
481
- Stagger = 12
482
- }
483
-
484
- /**
485
- * @description Options that control animation styling and timing.
486
- *
487
- * The following animation functions accept `AnimationOptions` data:
488
- *
489
- * - `transition()`
490
- * - `sequence()`
491
- * - `{@link animations/group group()}`
492
- * - `query()`
493
- * - `animation()`
494
- * - `useAnimation()`
495
- * - `animateChild()`
496
- *
497
- * Programmatic animations built using the `AnimationBuilder` service also
498
- * make use of `AnimationOptions`.
499
- *
500
- * @publicApi
501
- */
502
- export declare interface AnimationOptions {
503
- /**
504
- * Sets a time-delay for initiating an animation action.
505
- * A number and optional time unit, such as "1s" or "10ms" for one second
506
- * and 10 milliseconds, respectively.The default unit is milliseconds.
507
- * Default value is 0, meaning no delay.
508
- */
509
- delay?: number | string;
510
- /**
511
- * A set of developer-defined parameters that modify styling and timing
512
- * when an animation action starts. An array of key-value pairs, where the provided value
513
- * is used as a default.
514
- */
515
- params?: {
516
- [name: string]: any;
517
- };
518
- }
519
-
520
- /**
521
- * Provides programmatic control of a reusable animation sequence,
522
- * built using the <code>[AnimationBuilder.build](api/animations/AnimationBuilder#build)()</code>
523
- * method which returns an `AnimationFactory`, whose
524
- * <code>[create](api/animations/AnimationFactory#create)()</code> method instantiates and
525
- * initializes this interface.
526
- *
527
- * @see `AnimationBuilder`
528
- * @see `AnimationFactory`
529
- * @see `animate()`
530
- *
531
- * @publicApi
532
- */
533
- export declare interface AnimationPlayer {
534
- /**
535
- * Provides a callback to invoke when the animation finishes.
536
- * @param fn The callback function.
537
- * @see `finish()`
538
- */
539
- onDone(fn: () => void): void;
540
- /**
541
- * Provides a callback to invoke when the animation starts.
542
- * @param fn The callback function.
543
- * @see `run()`
544
- */
545
- onStart(fn: () => void): void;
546
- /**
547
- * Provides a callback to invoke after the animation is destroyed.
548
- * @param fn The callback function.
549
- * @see `destroy()`
550
- * @see `beforeDestroy()`
551
- */
552
- onDestroy(fn: () => void): void;
553
- /**
554
- * Initializes the animation.
555
- */
556
- init(): void;
557
- /**
558
- * Reports whether the animation has started.
559
- * @returns True if the animation has started, false otherwise.
560
- */
561
- hasStarted(): boolean;
562
- /**
563
- * Runs the animation, invoking the `onStart()` callback.
564
- */
565
- play(): void;
566
- /**
567
- * Pauses the animation.
568
- */
569
- pause(): void;
570
- /**
571
- * Restarts the paused animation.
572
- */
573
- restart(): void;
574
- /**
575
- * Ends the animation, invoking the `onDone()` callback.
576
- */
577
- finish(): void;
578
- /**
579
- * Destroys the animation, after invoking the `beforeDestroy()` callback.
580
- * Calls the `onDestroy()` callback when destruction is completed.
581
- */
582
- destroy(): void;
583
- /**
584
- * Resets the animation to its initial state.
585
- */
586
- reset(): void;
587
- /**
588
- * Sets the position of the animation.
589
- * @param position A 0-based offset into the duration, in milliseconds.
590
- */
591
- setPosition(position: any /** TODO #9100 */): void;
592
- /**
593
- * Reports the current position of the animation.
594
- * @returns A 0-based offset into the duration, in milliseconds.
595
- */
596
- getPosition(): number;
597
- /**
598
- * The parent of this player, if any.
599
- */
600
- parentPlayer: AnimationPlayer | null;
601
- /**
602
- * The total run time of the animation, in milliseconds.
603
- */
604
- readonly totalTime: number;
605
- /**
606
- * Provides a callback to invoke before the animation is destroyed.
607
- */
608
- beforeDestroy?: () => any;
609
- }
610
-
611
- /**
612
- * Encapsulates an animation query. Instantiated and returned by
613
- * the `query()` function.
614
- *
615
- * @publicApi
616
- */
617
- export declare interface AnimationQueryMetadata extends AnimationMetadata {
618
- /**
619
- * The CSS selector for this query.
620
- */
621
- selector: string;
622
- /**
623
- * One or more animation step objects.
624
- */
625
- animation: AnimationMetadata | AnimationMetadata[];
626
- /**
627
- * A query options object.
628
- */
629
- options: AnimationQueryOptions | null;
630
- }
631
-
632
- /**
633
- * Encapsulates animation query options.
634
- * Passed to the `query()` function.
635
- *
636
- * @publicApi
637
- */
638
- export declare interface AnimationQueryOptions extends AnimationOptions {
639
- /**
640
- * True if this query is optional, false if it is required. Default is false.
641
- * A required query throws an error if no elements are retrieved when
642
- * the query is executed. An optional query does not.
643
- *
644
- */
645
- optional?: boolean;
646
- /**
647
- * A maximum total number of results to return from the query.
648
- * If negative, results are limited from the end of the query list towards the beginning.
649
- * By default, results are not limited.
650
- */
651
- limit?: number;
652
- }
653
-
654
- /**
655
- * Encapsulates a reusable animation, which is a collection of individual animation steps.
656
- * Instantiated and returned by the `animation()` function, and
657
- * passed to the `useAnimation()` function.
658
- *
659
- * @publicApi
660
- */
661
- export declare interface AnimationReferenceMetadata extends AnimationMetadata {
662
- /**
663
- * One or more animation step objects.
664
- */
665
- animation: AnimationMetadata | AnimationMetadata[];
666
- /**
667
- * An options object containing a delay and
668
- * developer-defined parameters that provide styling defaults and
669
- * can be overridden on invocation. Default delay is 0.
670
- */
671
- options: AnimationOptions | null;
672
- }
673
-
674
- /**
675
- * Encapsulates an animation sequence.
676
- * Instantiated and returned by the `sequence()` function.
677
- *
678
- * @publicApi
679
- */
680
- export declare interface AnimationSequenceMetadata extends AnimationMetadata {
681
- /**
682
- * An array of animation step objects.
683
- */
684
- steps: AnimationMetadata[];
685
- /**
686
- * An options object containing a delay and
687
- * developer-defined parameters that provide styling defaults and
688
- * can be overridden on invocation. Default delay is 0.
689
- */
690
- options: AnimationOptions | null;
691
- }
692
-
693
- /**
694
- * Encapsulates parameters for staggering the start times of a set of animation steps.
695
- * Instantiated and returned by the `stagger()` function.
696
- *
697
- * @publicApi
698
- **/
699
- export declare interface AnimationStaggerMetadata extends AnimationMetadata {
700
- /**
701
- * The timing data for the steps.
702
- */
703
- timings: string | number;
704
- /**
705
- * One or more animation steps.
706
- */
707
- animation: AnimationMetadata | AnimationMetadata[];
708
- }
709
-
710
- /**
711
- * Encapsulates an animation state by associating a state name with a set of CSS styles.
712
- * Instantiated and returned by the [`state()`](api/animations/state) function.
713
- *
714
- * @publicApi
715
- */
716
- export declare interface AnimationStateMetadata extends AnimationMetadata {
717
- /**
718
- * The state name, unique within the component.
719
- */
720
- name: string;
721
- /**
722
- * The CSS styles associated with this state.
723
- */
724
- styles: AnimationStyleMetadata;
725
- /**
726
- * An options object containing
727
- * developer-defined parameters that provide styling defaults and
728
- * can be overridden on invocation.
729
- */
730
- options?: {
731
- params: {
732
- [name: string]: any;
733
- };
734
- };
735
- }
736
-
737
- /**
738
- * Encapsulates an animation style. Instantiated and returned by
739
- * the `style()` function.
740
- *
741
- * @publicApi
742
- */
743
- export declare interface AnimationStyleMetadata extends AnimationMetadata {
744
- /**
745
- * A set of CSS style properties.
746
- */
747
- styles: '*' | {
748
- [key: string]: string | number;
749
- } | Array<{
750
- [key: string]: string | number;
751
- } | '*'>;
752
- /**
753
- * A percentage of the total animate time at which the style is to be applied.
754
- */
755
- offset: number | null;
756
- }
757
-
758
- /**
759
- * Encapsulates an animation transition. Instantiated and returned by the
760
- * `transition()` function.
761
- *
762
- * @publicApi
763
- */
764
- export declare interface AnimationTransitionMetadata extends AnimationMetadata {
765
- /**
766
- * An expression that describes a state change.
767
- */
768
- expr: string | ((fromState: string, toState: string, element?: any, params?: {
769
- [key: string]: any;
770
- }) => boolean);
771
- /**
772
- * One or more animation objects to which this transition applies.
773
- */
774
- animation: AnimationMetadata | AnimationMetadata[];
775
- /**
776
- * An options object containing a delay and
777
- * developer-defined parameters that provide styling defaults and
778
- * can be overridden on invocation. Default delay is 0.
779
- */
780
- options: AnimationOptions | null;
781
- }
782
-
783
- /**
784
- * Contains an animation trigger. Instantiated and returned by the
785
- * `trigger()` function.
786
- *
787
- * @publicApi
788
- */
789
- export declare interface AnimationTriggerMetadata extends AnimationMetadata {
790
- /**
791
- * The trigger name, used to associate it with an element. Unique within the component.
792
- */
793
- name: string;
794
- /**
795
- * An animation definition object, containing an array of state and transition declarations.
796
- */
797
- definitions: AnimationMetadata[];
798
- /**
799
- * An options object containing a delay and
800
- * developer-defined parameters that provide styling defaults and
801
- * can be overridden on invocation. Default delay is 0.
802
- */
803
- options: {
804
- params?: {
805
- [name: string]: any;
806
- };
807
- } | null;
808
- }
809
-
810
- /**
811
- * Specifies automatic styling.
812
- *
813
- * @publicApi
814
- */
815
- export declare const AUTO_STYLE = "*";
816
-
817
- /**
818
- * @description Defines a list of animation steps to be run in parallel.
819
- *
820
- * @param steps An array of animation step objects.
821
- * - When steps are defined by `style()` or `animate()`
822
- * function calls, each call within the group is executed instantly.
823
- * - To specify offset styles to be applied at a later time, define steps with
824
- * `keyframes()`, or use `animate()` calls with a delay value.
825
- * For example:
826
- *
827
- * ```typescript
828
- * group([
829
- * animate("1s", style({ background: "black" })),
830
- * animate("2s", style({ color: "white" }))
831
- * ])
832
- * ```
833
- *
834
- * @param options An options object containing a delay and
835
- * developer-defined parameters that provide styling defaults and
836
- * can be overridden on invocation.
837
- *
838
- * @return An object that encapsulates the group data.
839
- *
840
- * @usageNotes
841
- * Grouped animations are useful when a series of styles must be
842
- * animated at different starting times and closed off at different ending times.
843
- *
844
- * When called within a `sequence()` or a
845
- * `transition()` call, does not continue to the next
846
- * instruction until all of the inner animation steps have completed.
847
- *
848
- * @publicApi
849
- */
850
- export declare function group(steps: AnimationMetadata[], options?: AnimationOptions | null): AnimationGroupMetadata;
851
-
852
- /**
853
- * Defines a set of animation styles, associating each style with an optional `offset` value.
854
- *
855
- * @param steps A set of animation styles with optional offset data.
856
- * The optional `offset` value for a style specifies a percentage of the total animation
857
- * time at which that style is applied.
858
- * @returns An object that encapsulates the keyframes data.
859
- *
860
- * @usageNotes
861
- * Use with the `animate()` call. Instead of applying animations
862
- * from the current state
863
- * to the destination state, keyframes describe how each style entry is applied and at what point
864
- * within the animation arc.
865
- * Compare [CSS Keyframe Animations](https://www.w3schools.com/css/css3_animations.asp).
866
- *
867
- * ### Usage
868
- *
869
- * In the following example, the offset values describe
870
- * when each `backgroundColor` value is applied. The color is red at the start, and changes to
871
- * blue when 20% of the total time has elapsed.
872
- *
873
- * ```typescript
874
- * // the provided offset values
875
- * animate("5s", keyframes([
876
- * style({ backgroundColor: "red", offset: 0 }),
877
- * style({ backgroundColor: "blue", offset: 0.2 }),
878
- * style({ backgroundColor: "orange", offset: 0.3 }),
879
- * style({ backgroundColor: "black", offset: 1 })
880
- * ]))
881
- * ```
882
- *
883
- * If there are no `offset` values specified in the style entries, the offsets
884
- * are calculated automatically.
885
- *
886
- * ```typescript
887
- * animate("5s", keyframes([
888
- * style({ backgroundColor: "red" }) // offset = 0
889
- * style({ backgroundColor: "blue" }) // offset = 0.33
890
- * style({ backgroundColor: "orange" }) // offset = 0.66
891
- * style({ backgroundColor: "black" }) // offset = 1
892
- * ]))
893
- *```
894
-
895
- * @publicApi
896
- */
897
- export declare function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSequenceMetadata;
898
-
899
- /**
900
- * An empty programmatic controller for reusable animations.
901
- * Used internally when animations are disabled, to avoid
902
- * checking for the null case when an animation player is expected.
903
- *
904
- * @see `animate()`
905
- * @see `AnimationPlayer`
906
- * @see `GroupPlayer`
907
- *
908
- * @publicApi
909
- */
910
- export declare class NoopAnimationPlayer implements AnimationPlayer {
911
- private _onDoneFns;
912
- private _onStartFns;
913
- private _onDestroyFns;
914
- private _started;
915
- private _destroyed;
916
- private _finished;
917
- private _position;
918
- parentPlayer: AnimationPlayer | null;
919
- readonly totalTime: number;
920
- constructor(duration?: number, delay?: number);
921
- private _onFinish;
922
- onStart(fn: () => void): void;
923
- onDone(fn: () => void): void;
924
- onDestroy(fn: () => void): void;
925
- hasStarted(): boolean;
926
- init(): void;
927
- play(): void;
928
- private _onStart;
929
- pause(): void;
930
- restart(): void;
931
- finish(): void;
932
- destroy(): void;
933
- reset(): void;
934
- setPosition(position: number): void;
935
- getPosition(): number;
936
- }
937
-
938
- /**
939
- * Finds one or more inner elements within the current element that is
940
- * being animated within a sequence. Use with `animate()`.
941
- *
942
- * @param selector The element to query, or a set of elements that contain Angular-specific
943
- * characteristics, specified with one or more of the following tokens.
944
- * - `query(":enter")` or `query(":leave")` : Query for newly inserted/removed elements (not
945
- * all elements can be queried via these tokens, see
946
- * [Entering and Leaving Elements](#entering-and-leaving-elements))
947
- * - `query(":animating")` : Query all currently animating elements.
948
- * - `query("@triggerName")` : Query elements that contain an animation trigger.
949
- * - `query("@*")` : Query all elements that contain an animation triggers.
950
- * - `query(":self")` : Include the current element into the animation sequence.
951
- *
952
- * @param animation One or more animation steps to apply to the queried element or elements.
953
- * An array is treated as an animation sequence.
954
- * @param options An options object. Use the 'limit' field to limit the total number of
955
- * items to collect.
956
- * @return An object that encapsulates the query data.
957
- *
958
- * @usageNotes
959
- *
960
- * ### Multiple Tokens
961
- *
962
- * Tokens can be merged into a combined query selector string. For example:
963
- *
964
- * ```typescript
965
- * query(':self, .record:enter, .record:leave, @subTrigger', [...])
966
- * ```
967
- *
968
- * The `query()` function collects multiple elements and works internally by using
969
- * `element.querySelectorAll`. Use the `limit` field of an options object to limit
970
- * the total number of items to be collected. For example:
971
- *
972
- * ```js
973
- * query('div', [
974
- * animate(...),
975
- * animate(...)
976
- * ], { limit: 1 })
977
- * ```
978
- *
979
- * By default, throws an error when zero items are found. Set the
980
- * `optional` flag to ignore this error. For example:
981
- *
982
- * ```js
983
- * query('.some-element-that-may-not-be-there', [
984
- * animate(...),
985
- * animate(...)
986
- * ], { optional: true })
987
- * ```
988
- *
989
- * ### Entering and Leaving Elements
990
- *
991
- * Not all elements can be queried via the `:enter` and `:leave` tokens, the only ones
992
- * that can are those that Angular assumes can enter/leave based on their own logic
993
- * (if their insertion/removal is simply a consequence of that of their parent they
994
- * should be queried via a different token in their parent's `:enter`/`:leave` transitions).
995
- *
996
- * The only elements Angular assumes can enter/leave based on their own logic (thus the only
997
- * ones that can be queried via the `:enter` and `:leave` tokens) are:
998
- * - Those inserted dynamically (via `ViewContainerRef`)
999
- * - Those that have a structural directive (which, under the hood, are a subset of the above ones)
1000
- *
1001
- * <div class="alert is-helpful">
1002
- *
1003
- * Note that elements will be successfully queried via `:enter`/`:leave` even if their
1004
- * insertion/removal is not done manually via `ViewContainerRef`or caused by their structural
1005
- * directive (e.g. they enter/exit alongside their parent).
1006
- *
1007
- * </div>
1008
- *
1009
- * <div class="alert is-important">
1010
- *
1011
- * There is an exception to what previously mentioned, besides elements entering/leaving based on
1012
- * their own logic, elements with an animation trigger can always be queried via `:leave` when
1013
- * their parent is also leaving.
1014
- *
1015
- * </div>
1016
- *
1017
- * ### Usage Example
1018
- *
1019
- * The following example queries for inner elements and animates them
1020
- * individually using `animate()`.
1021
- *
1022
- * ```typescript
1023
- * @Component({
1024
- * selector: 'inner',
1025
- * template: `
1026
- * <div [@queryAnimation]="exp">
1027
- * <h1>Title</h1>
1028
- * <div class="content">
1029
- * Blah blah blah
1030
- * </div>
1031
- * </div>
1032
- * `,
1033
- * animations: [
1034
- * trigger('queryAnimation', [
1035
- * transition('* => goAnimate', [
1036
- * // hide the inner elements
1037
- * query('h1', style({ opacity: 0 })),
1038
- * query('.content', style({ opacity: 0 })),
1039
- *
1040
- * // animate the inner elements in, one by one
1041
- * query('h1', animate(1000, style({ opacity: 1 }))),
1042
- * query('.content', animate(1000, style({ opacity: 1 }))),
1043
- * ])
1044
- * ])
1045
- * ]
1046
- * })
1047
- * class Cmp {
1048
- * exp = '';
1049
- *
1050
- * goAnimate() {
1051
- * this.exp = 'goAnimate';
1052
- * }
1053
- * }
1054
- * ```
1055
- *
1056
- * @publicApi
1057
- */
1058
- export declare function query(selector: string, animation: AnimationMetadata | AnimationMetadata[], options?: AnimationQueryOptions | null): AnimationQueryMetadata;
1059
-
1060
- /**
1061
- * Defines a list of animation steps to be run sequentially, one by one.
1062
- *
1063
- * @param steps An array of animation step objects.
1064
- * - Steps defined by `style()` calls apply the styling data immediately.
1065
- * - Steps defined by `animate()` calls apply the styling data over time
1066
- * as specified by the timing data.
1067
- *
1068
- * ```typescript
1069
- * sequence([
1070
- * style({ opacity: 0 }),
1071
- * animate("1s", style({ opacity: 1 }))
1072
- * ])
1073
- * ```
1074
- *
1075
- * @param options An options object containing a delay and
1076
- * developer-defined parameters that provide styling defaults and
1077
- * can be overridden on invocation.
1078
- *
1079
- * @return An object that encapsulates the sequence data.
1080
- *
1081
- * @usageNotes
1082
- * When you pass an array of steps to a
1083
- * `transition()` call, the steps run sequentially by default.
1084
- * Compare this to the `{@link animations/group group()}` call, which runs animation steps in
1085
- *parallel.
1086
- *
1087
- * When a sequence is used within a `{@link animations/group group()}` or a `transition()` call,
1088
- * execution continues to the next instruction only after each of the inner animation
1089
- * steps have completed.
1090
- *
1091
- * @publicApi
1092
- **/
1093
- export declare function sequence(steps: AnimationMetadata[], options?: AnimationOptions | null): AnimationSequenceMetadata;
1094
-
1095
- /**
1096
- * Use within an animation `query()` call to issue a timing gap after
1097
- * each queried item is animated.
1098
- *
1099
- * @param timings A delay value.
1100
- * @param animation One ore more animation steps.
1101
- * @returns An object that encapsulates the stagger data.
1102
- *
1103
- * @usageNotes
1104
- * In the following example, a container element wraps a list of items stamped out
1105
- * by an `ngFor`. The container element contains an animation trigger that will later be set
1106
- * to query for each of the inner items.
1107
- *
1108
- * Each time items are added, the opacity fade-in animation runs,
1109
- * and each removed item is faded out.
1110
- * When either of these animations occur, the stagger effect is
1111
- * applied after each item's animation is started.
1112
- *
1113
- * ```html
1114
- * <!-- list.component.html -->
1115
- * <button (click)="toggle()">Show / Hide Items</button>
1116
- * <hr />
1117
- * <div [@listAnimation]="items.length">
1118
- * <div *ngFor="let item of items">
1119
- * {{ item }}
1120
- * </div>
1121
- * </div>
1122
- * ```
1123
- *
1124
- * Here is the component code:
1125
- *
1126
- * ```typescript
1127
- * import {trigger, transition, style, animate, query, stagger} from '@angular/animations';
1128
- * @Component({
1129
- * templateUrl: 'list.component.html',
1130
- * animations: [
1131
- * trigger('listAnimation', [
1132
- * ...
1133
- * ])
1134
- * ]
1135
- * })
1136
- * class ListComponent {
1137
- * items = [];
1138
- *
1139
- * showItems() {
1140
- * this.items = [0,1,2,3,4];
1141
- * }
1142
- *
1143
- * hideItems() {
1144
- * this.items = [];
1145
- * }
1146
- *
1147
- * toggle() {
1148
- * this.items.length ? this.hideItems() : this.showItems();
1149
- * }
1150
- * }
1151
- * ```
1152
- *
1153
- * Here is the animation trigger code:
1154
- *
1155
- * ```typescript
1156
- * trigger('listAnimation', [
1157
- * transition('* => *', [ // each time the binding value changes
1158
- * query(':leave', [
1159
- * stagger(100, [
1160
- * animate('0.5s', style({ opacity: 0 }))
1161
- * ])
1162
- * ]),
1163
- * query(':enter', [
1164
- * style({ opacity: 0 }),
1165
- * stagger(100, [
1166
- * animate('0.5s', style({ opacity: 1 }))
1167
- * ])
1168
- * ])
1169
- * ])
1170
- * ])
1171
- * ```
1172
- *
1173
- * @publicApi
1174
- */
1175
- export declare function stagger(timings: string | number, animation: AnimationMetadata | AnimationMetadata[]): AnimationStaggerMetadata;
1176
-
1177
- /**
1178
- * Declares an animation state within a trigger attached to an element.
1179
- *
1180
- * @param name One or more names for the defined state in a comma-separated string.
1181
- * The following reserved state names can be supplied to define a style for specific use
1182
- * cases:
1183
- *
1184
- * - `void` You can associate styles with this name to be used when
1185
- * the element is detached from the application. For example, when an `ngIf` evaluates
1186
- * to false, the state of the associated element is void.
1187
- * - `*` (asterisk) Indicates the default state. You can associate styles with this name
1188
- * to be used as the fallback when the state that is being animated is not declared
1189
- * within the trigger.
1190
- *
1191
- * @param styles A set of CSS styles associated with this state, created using the
1192
- * `style()` function.
1193
- * This set of styles persists on the element once the state has been reached.
1194
- * @param options Parameters that can be passed to the state when it is invoked.
1195
- * 0 or more key-value pairs.
1196
- * @return An object that encapsulates the new state data.
1197
- *
1198
- * @usageNotes
1199
- * Use the `trigger()` function to register states to an animation trigger.
1200
- * Use the `transition()` function to animate between states.
1201
- * When a state is active within a component, its associated styles persist on the element,
1202
- * even when the animation ends.
1203
- *
1204
- * @publicApi
1205
- **/
1206
- export declare function state(name: string, styles: AnimationStyleMetadata, options?: {
1207
- params: {
1208
- [name: string]: any;
1209
- };
1210
- }): AnimationStateMetadata;
1211
-
1212
- /**
1213
- * Declares a key/value object containing CSS properties/styles that
1214
- * can then be used for an animation [`state`](api/animations/state), within an animation
1215
- *`sequence`, or as styling data for calls to `animate()` and `keyframes()`.
1216
- *
1217
- * @param tokens A set of CSS styles or HTML styles associated with an animation state.
1218
- * The value can be any of the following:
1219
- * - A key-value style pair associating a CSS property with a value.
1220
- * - An array of key-value style pairs.
1221
- * - An asterisk (*), to use auto-styling, where styles are derived from the element
1222
- * being animated and applied to the animation when it starts.
1223
- *
1224
- * Auto-styling can be used to define a state that depends on layout or other
1225
- * environmental factors.
1226
- *
1227
- * @return An object that encapsulates the style data.
1228
- *
1229
- * @usageNotes
1230
- * The following examples create animation styles that collect a set of
1231
- * CSS property values:
1232
- *
1233
- * ```typescript
1234
- * // string values for CSS properties
1235
- * style({ background: "red", color: "blue" })
1236
- *
1237
- * // numerical pixel values
1238
- * style({ width: 100, height: 0 })
1239
- * ```
1240
- *
1241
- * The following example uses auto-styling to allow an element to animate from
1242
- * a height of 0 up to its full height:
1243
- *
1244
- * ```
1245
- * style({ height: 0 }),
1246
- * animate("1s", style({ height: "*" }))
1247
- * ```
1248
- *
1249
- * @publicApi
1250
- **/
1251
- export declare function style(tokens: '*' | {
1252
- [key: string]: string | number;
1253
- } | Array<'*' | {
1254
- [key: string]: string | number;
1255
- }>): AnimationStyleMetadata;
1256
-
1257
- /**
1258
- * Declares an animation transition which is played when a certain specified condition is met.
1259
- *
1260
- * @param stateChangeExpr A string with a specific format or a function that specifies when the
1261
- * animation transition should occur (see [State Change Expression](#state-change-expression)).
1262
- *
1263
- * @param steps One or more animation objects that represent the animation's instructions.
1264
- *
1265
- * @param options An options object that can be used to specify a delay for the animation or provide
1266
- * custom parameters for it.
1267
- *
1268
- * @returns An object that encapsulates the transition data.
1269
- *
1270
- * @usageNotes
1271
- *
1272
- * ### State Change Expression
1273
- *
1274
- * The State Change Expression instructs Angular when to run the transition's animations, it can
1275
- *either be
1276
- * - a string with a specific syntax
1277
- * - or a function that compares the previous and current state (value of the expression bound to
1278
- * the element's trigger) and returns `true` if the transition should occur or `false` otherwise
1279
- *
1280
- * The string format can be:
1281
- * - `fromState => toState`, which indicates that the transition's animations should occur then the
1282
- * expression bound to the trigger's element goes from `fromState` to `toState`
1283
- *
1284
- * _Example:_
1285
- * ```typescript
1286
- * transition('open => closed', animate('.5s ease-out', style({ height: 0 }) ))
1287
- * ```
1288
- *
1289
- * - `fromState <=> toState`, which indicates that the transition's animations should occur then
1290
- * the expression bound to the trigger's element goes from `fromState` to `toState` or vice versa
1291
- *
1292
- * _Example:_
1293
- * ```typescript
1294
- * transition('enabled <=> disabled', animate('1s cubic-bezier(0.8,0.3,0,1)'))
1295
- * ```
1296
- *
1297
- * - `:enter`/`:leave`, which indicates that the transition's animations should occur when the
1298
- * element enters or exists the DOM
1299
- *
1300
- * _Example:_
1301
- * ```typescript
1302
- * transition(':enter', [
1303
- * style({ opacity: 0 }),
1304
- * animate('500ms', style({ opacity: 1 }))
1305
- * ])
1306
- * ```
1307
- *
1308
- * - `:increment`/`:decrement`, which indicates that the transition's animations should occur when
1309
- * the numerical expression bound to the trigger's element has increased in value or decreased
1310
- *
1311
- * _Example:_
1312
- * ```typescript
1313
- * transition(':increment', query('@counter', animateChild()))
1314
- * ```
1315
- *
1316
- * - a sequence of any of the above divided by commas, which indicates that transition's animations
1317
- * should occur whenever one of the state change expressions matches
1318
- *
1319
- * _Example:_
1320
- * ```typescript
1321
- * transition(':increment, * => enabled, :enter', animate('1s ease', keyframes([
1322
- * style({ transform: 'scale(1)', offset: 0}),
1323
- * style({ transform: 'scale(1.1)', offset: 0.7}),
1324
- * style({ transform: 'scale(1)', offset: 1})
1325
- * ]))),
1326
- * ```
1327
- *
1328
- * Also note that in such context:
1329
- * - `void` can be used to indicate the absence of the element
1330
- * - asterisks can be used as wildcards that match any state
1331
- * - (as a consequence of the above, `void => *` is equivalent to `:enter` and `* => void` is
1332
- * equivalent to `:leave`)
1333
- * - `true` and `false` also match expression values of `1` and `0` respectively (but do not match
1334
- * _truthy_ and _falsy_ values)
1335
- *
1336
- * <div class="alert is-helpful">
1337
- *
1338
- * Be careful about entering end leaving elements as their transitions present a common
1339
- * pitfall for developers.
1340
- *
1341
- * Note that when an element with a trigger enters the DOM its `:enter` transition always
1342
- * gets executed, but its `:leave` transition will not be executed if the element is removed
1343
- * alongside its parent (as it will be removed "without warning" before its transition has
1344
- * a chance to be executed, the only way that such transition can occur is if the element
1345
- * is exiting the DOM on its own).
1346
- *
1347
- *
1348
- * </div>
1349
- *
1350
- * ### Animating to a Final State
1351
- *
1352
- * If the final step in a transition is a call to `animate()` that uses a timing value
1353
- * with no `style` data, that step is automatically considered the final animation arc,
1354
- * for the element to reach the final state, in such case Angular automatically adds or removes
1355
- * CSS styles to ensure that the element is in the correct final state.
1356
- *
1357
- *
1358
- * ### Usage Examples
1359
- *
1360
- * - Transition animations applied based on
1361
- * the trigger's expression value
1362
- *
1363
- * ```HTML
1364
- * <div [@myAnimationTrigger]="myStatusExp">
1365
- * ...
1366
- * </div>
1367
- * ```
1368
- *
1369
- * ```typescript
1370
- * trigger("myAnimationTrigger", [
1371
- * ..., // states
1372
- * transition("on => off, open => closed", animate(500)),
1373
- * transition("* <=> error", query('.indicator', animateChild()))
1374
- * ])
1375
- * ```
1376
- *
1377
- * - Transition animations applied based on custom logic dependent
1378
- * on the trigger's expression value and provided parameters
1379
- *
1380
- * ```HTML
1381
- * <div [@myAnimationTrigger]="{
1382
- * value: stepName,
1383
- * params: { target: currentTarget }
1384
- * }">
1385
- * ...
1386
- * </div>
1387
- * ```
1388
- *
1389
- * ```typescript
1390
- * trigger("myAnimationTrigger", [
1391
- * ..., // states
1392
- * transition(
1393
- * (fromState, toState, _element, params) =>
1394
- * ['firststep', 'laststep'].includes(fromState.toLowerCase())
1395
- * && toState === params?.['target'],
1396
- * animate('1s')
1397
- * )
1398
- * ])
1399
- * ```
1400
- *
1401
- * @publicApi
1402
- **/
1403
- export declare function transition(stateChangeExpr: string | ((fromState: string, toState: string, element?: any, params?: {
1404
- [key: string]: any;
1405
- }) => boolean), steps: AnimationMetadata | AnimationMetadata[], options?: AnimationOptions | null): AnimationTransitionMetadata;
1406
-
1407
- /**
1408
- * Creates a named animation trigger, containing a list of [`state()`](api/animations/state)
1409
- * and `transition()` entries to be evaluated when the expression
1410
- * bound to the trigger changes.
1411
- *
1412
- * @param name An identifying string.
1413
- * @param definitions An animation definition object, containing an array of
1414
- * [`state()`](api/animations/state) and `transition()` declarations.
1415
- *
1416
- * @return An object that encapsulates the trigger data.
1417
- *
1418
- * @usageNotes
1419
- * Define an animation trigger in the `animations` section of `@Component` metadata.
1420
- * In the template, reference the trigger by name and bind it to a trigger expression that
1421
- * evaluates to a defined animation state, using the following format:
1422
- *
1423
- * `[@triggerName]="expression"`
1424
- *
1425
- * Animation trigger bindings convert all values to strings, and then match the
1426
- * previous and current values against any linked transitions.
1427
- * Booleans can be specified as `1` or `true` and `0` or `false`.
1428
- *
1429
- * ### Usage Example
1430
- *
1431
- * The following example creates an animation trigger reference based on the provided
1432
- * name value.
1433
- * The provided animation value is expected to be an array consisting of state and
1434
- * transition declarations.
1435
- *
1436
- * ```typescript
1437
- * @Component({
1438
- * selector: "my-component",
1439
- * templateUrl: "my-component-tpl.html",
1440
- * animations: [
1441
- * trigger("myAnimationTrigger", [
1442
- * state(...),
1443
- * state(...),
1444
- * transition(...),
1445
- * transition(...)
1446
- * ])
1447
- * ]
1448
- * })
1449
- * class MyComponent {
1450
- * myStatusExp = "something";
1451
- * }
1452
- * ```
1453
- *
1454
- * The template associated with this component makes use of the defined trigger
1455
- * by binding to an element within its template code.
1456
- *
1457
- * ```html
1458
- * <!-- somewhere inside of my-component-tpl.html -->
1459
- * <div [@myAnimationTrigger]="myStatusExp">...</div>
1460
- * ```
1461
- *
1462
- * ### Using an inline function
1463
- * The `transition` animation method also supports reading an inline function which can decide
1464
- * if its associated animation should be run.
1465
- *
1466
- * ```typescript
1467
- * // this method is run each time the `myAnimationTrigger` trigger value changes.
1468
- * function myInlineMatcherFn(fromState: string, toState: string, element: any, params: {[key:
1469
- string]: any}): boolean {
1470
- * // notice that `element` and `params` are also available here
1471
- * return toState == 'yes-please-animate';
1472
- * }
1473
- *
1474
- * @Component({
1475
- * selector: 'my-component',
1476
- * templateUrl: 'my-component-tpl.html',
1477
- * animations: [
1478
- * trigger('myAnimationTrigger', [
1479
- * transition(myInlineMatcherFn, [
1480
- * // the animation sequence code
1481
- * ]),
1482
- * ])
1483
- * ]
1484
- * })
1485
- * class MyComponent {
1486
- * myStatusExp = "yes-please-animate";
1487
- * }
1488
- * ```
1489
- *
1490
- * ### Disabling Animations
1491
- * When true, the special animation control binding `@.disabled` binding prevents
1492
- * all animations from rendering.
1493
- * Place the `@.disabled` binding on an element to disable
1494
- * animations on the element itself, as well as any inner animation triggers
1495
- * within the element.
1496
- *
1497
- * The following example shows how to use this feature:
1498
- *
1499
- * ```typescript
1500
- * @Component({
1501
- * selector: 'my-component',
1502
- * template: `
1503
- * <div [@.disabled]="isDisabled">
1504
- * <div [@childAnimation]="exp"></div>
1505
- * </div>
1506
- * `,
1507
- * animations: [
1508
- * trigger("childAnimation", [
1509
- * // ...
1510
- * ])
1511
- * ]
1512
- * })
1513
- * class MyComponent {
1514
- * isDisabled = true;
1515
- * exp = '...';
1516
- * }
1517
- * ```
1518
- *
1519
- * When `@.disabled` is true, it prevents the `@childAnimation` trigger from animating,
1520
- * along with any inner animations.
1521
- *
1522
- * ### Disable animations application-wide
1523
- * When an area of the template is set to have animations disabled,
1524
- * **all** inner components have their animations disabled as well.
1525
- * This means that you can disable all animations for an app
1526
- * by placing a host binding set on `@.disabled` on the topmost Angular component.
1527
- *
1528
- * ```typescript
1529
- * import {Component, HostBinding} from '@angular/core';
1530
- *
1531
- * @Component({
1532
- * selector: 'app-component',
1533
- * templateUrl: 'app.component.html',
1534
- * })
1535
- * class AppComponent {
1536
- * @HostBinding('@.disabled')
1537
- * public animationsDisabled = true;
1538
- * }
1539
- * ```
1540
- *
1541
- * ### Overriding disablement of inner animations
1542
- * Despite inner animations being disabled, a parent animation can `query()`
1543
- * for inner elements located in disabled areas of the template and still animate
1544
- * them if needed. This is also the case for when a sub animation is
1545
- * queried by a parent and then later animated using `animateChild()`.
1546
- *
1547
- * ### Detecting when an animation is disabled
1548
- * If a region of the DOM (or the entire application) has its animations disabled, the animation
1549
- * trigger callbacks still fire, but for zero seconds. When the callback fires, it provides
1550
- * an instance of an `AnimationEvent`. If animations are disabled,
1551
- * the `.disabled` flag on the event is true.
1552
- *
1553
- * @publicApi
1554
- */
1555
- export declare function trigger(name: string, definitions: AnimationMetadata[]): AnimationTriggerMetadata;
1556
-
1557
- /**
1558
- * Starts a reusable animation that is created using the `animation()` function.
1559
- *
1560
- * @param animation The reusable animation to start.
1561
- * @param options An options object that can contain a delay value for the start of
1562
- * the animation, and additional override values for developer-defined parameters.
1563
- * @return An object that contains the animation parameters.
1564
- *
1565
- * @publicApi
1566
- */
1567
- export declare function useAnimation(animation: AnimationReferenceMetadata, options?: AnimationOptions | null): AnimationAnimateRefMetadata;
1568
-
1569
- /**
1570
- * A programmatic controller for a group of reusable animations.
1571
- * Used internally to control animations.
1572
- *
1573
- * @see `AnimationPlayer`
1574
- * @see `{@link animations/group group()}`
1575
- *
1576
- */
1577
- export declare class ɵAnimationGroupPlayer implements AnimationPlayer {
1578
- private _onDoneFns;
1579
- private _onStartFns;
1580
- private _finished;
1581
- private _started;
1582
- private _destroyed;
1583
- private _onDestroyFns;
1584
- parentPlayer: AnimationPlayer | null;
1585
- totalTime: number;
1586
- readonly players: AnimationPlayer[];
1587
- constructor(_players: AnimationPlayer[]);
1588
- private _onFinish;
1589
- init(): void;
1590
- onStart(fn: () => void): void;
1591
- private _onStart;
1592
- onDone(fn: () => void): void;
1593
- onDestroy(fn: () => void): void;
1594
- hasStarted(): boolean;
1595
- play(): void;
1596
- pause(): void;
1597
- restart(): void;
1598
- finish(): void;
1599
- destroy(): void;
1600
- private _onDestroy;
1601
- reset(): void;
1602
- setPosition(p: number): void;
1603
- getPosition(): number;
1604
- beforeDestroy(): void;
1605
- }
1606
-
1607
- export declare const ɵPRE_STYLE = "!";
1608
-
1609
-
1610
- /**
1611
- * Represents a set of CSS styles for use in an animation style as a generic.
1612
- */
1613
- export declare interface ɵStyleData {
1614
- [key: string]: string | number;
1615
- }
1616
-
1617
- /**
1618
- * Represents a set of CSS styles for use in an animation style as a Map.
1619
- */
1620
- export declare type ɵStyleDataMap = Map<string, string | number>;
1621
-
1622
- export { }
7
+
8
+ /**
9
+ * Defines an animation step that combines styling information with timing information.
10
+ *
11
+ * @param timings Sets `AnimateTimings` for the parent animation.
12
+ * A string in the format "duration [delay] [easing]".
13
+ * - Duration and delay are expressed as a number and optional time unit,
14
+ * such as "1s" or "10ms" for one second and 10 milliseconds, respectively.
15
+ * The default unit is milliseconds.
16
+ * - The easing value controls how the animation accelerates and decelerates
17
+ * during its runtime. Value is one of `ease`, `ease-in`, `ease-out`,
18
+ * `ease-in-out`, or a `cubic-bezier()` function call.
19
+ * If not supplied, no easing is applied.
20
+ *
21
+ * For example, the string "1s 100ms ease-out" specifies a duration of
22
+ * 1000 milliseconds, and delay of 100 ms, and the "ease-out" easing style,
23
+ * which decelerates near the end of the duration.
24
+ * @param styles Sets AnimationStyles for the parent animation.
25
+ * A function call to either `style()` or `keyframes()`
26
+ * that returns a collection of CSS style entries to be applied to the parent animation.
27
+ * When null, uses the styles from the destination state.
28
+ * This is useful when describing an animation step that will complete an animation;
29
+ * see "Animating to the final state" in `transitions()`.
30
+ * @returns An object that encapsulates the animation step.
31
+ *
32
+ * @usageNotes
33
+ * Call within an animation `sequence()`, `{@link animations/group group()}`, or
34
+ * `transition()` call to specify an animation step
35
+ * that applies given style data to the parent animation for a given amount of time.
36
+ *
37
+ * ### Syntax Examples
38
+ * **Timing examples**
39
+ *
40
+ * The following examples show various `timings` specifications.
41
+ * - `animate(500)` : Duration is 500 milliseconds.
42
+ * - `animate("1s")` : Duration is 1000 milliseconds.
43
+ * - `animate("100ms 0.5s")` : Duration is 100 milliseconds, delay is 500 milliseconds.
44
+ * - `animate("5s ease-in")` : Duration is 5000 milliseconds, easing in.
45
+ * - `animate("5s 10ms cubic-bezier(.17,.67,.88,.1)")` : Duration is 5000 milliseconds, delay is 10
46
+ * milliseconds, easing according to a bezier curve.
47
+ *
48
+ * **Style examples**
49
+ *
50
+ * The following example calls `style()` to set a single CSS style.
51
+ * ```typescript
52
+ * animate(500, style({ background: "red" }))
53
+ * ```
54
+ * The following example calls `keyframes()` to set a CSS style
55
+ * to different values for successive keyframes.
56
+ * ```typescript
57
+ * animate(500, keyframes(
58
+ * [
59
+ * style({ background: "blue" }),
60
+ * style({ background: "red" })
61
+ * ])
62
+ * ```
63
+ *
64
+ * @publicApi
65
+ */
66
+ export declare function animate(timings: string | number, styles?: AnimationStyleMetadata | AnimationKeyframesSequenceMetadata | null): AnimationAnimateMetadata;
67
+
68
+ /**
69
+ * Executes a queried inner animation element within an animation sequence.
70
+ *
71
+ * @param options An options object that can contain a delay value for the start of the
72
+ * animation, and additional override values for developer-defined parameters.
73
+ * @return An object that encapsulates the child animation data.
74
+ *
75
+ * @usageNotes
76
+ * Each time an animation is triggered in Angular, the parent animation
77
+ * has priority and any child animations are blocked. In order
78
+ * for a child animation to run, the parent animation must query each of the elements
79
+ * containing child animations, and run them using this function.
80
+ *
81
+ * Note that this feature is designed to be used with `query()` and it will only work
82
+ * with animations that are assigned using the Angular animation library. CSS keyframes
83
+ * and transitions are not handled by this API.
84
+ *
85
+ * @publicApi
86
+ */
87
+ export declare function animateChild(options?: AnimateChildOptions | null): AnimationAnimateChildMetadata;
88
+
89
+ /**
90
+ * Adds duration options to control animation styling and timing for a child animation.
91
+ *
92
+ * @see `animateChild()`
93
+ *
94
+ * @publicApi
95
+ */
96
+ export declare interface AnimateChildOptions extends AnimationOptions {
97
+ duration?: number | string;
98
+ }
99
+
100
+ /**
101
+ * Represents animation-step timing parameters for an animation step.
102
+ * @see `animate()`
103
+ *
104
+ * @publicApi
105
+ */
106
+ export declare type AnimateTimings = {
107
+ /**
108
+ * The full duration of an animation step. A number and optional time unit,
109
+ * such as "1s" or "10ms" for one second and 10 milliseconds, respectively.
110
+ * The default unit is milliseconds.
111
+ */
112
+ duration: number;
113
+ /**
114
+ * The delay in applying an animation step. A number and optional time unit.
115
+ * The default unit is milliseconds.
116
+ */
117
+ delay: number;
118
+ /**
119
+ * An easing style that controls how an animations step accelerates
120
+ * and decelerates during its run time. An easing function such as `cubic-bezier()`,
121
+ * or one of the following constants:
122
+ * - `ease-in`
123
+ * - `ease-out`
124
+ * - `ease-in-and-out`
125
+ */
126
+ easing: string | null;
127
+ };
128
+
129
+ /**
130
+ * Produces a reusable animation that can be invoked in another animation or sequence,
131
+ * by calling the `useAnimation()` function.
132
+ *
133
+ * @param steps One or more animation objects, as returned by the `animate()`
134
+ * or `sequence()` function, that form a transformation from one state to another.
135
+ * A sequence is used by default when you pass an array.
136
+ * @param options An options object that can contain a delay value for the start of the
137
+ * animation, and additional developer-defined parameters.
138
+ * Provided values for additional parameters are used as defaults,
139
+ * and override values can be passed to the caller on invocation.
140
+ * @returns An object that encapsulates the animation data.
141
+ *
142
+ * @usageNotes
143
+ * The following example defines a reusable animation, providing some default parameter
144
+ * values.
145
+ *
146
+ * ```typescript
147
+ * var fadeAnimation = animation([
148
+ * style({ opacity: '{{ start }}' }),
149
+ * animate('{{ time }}',
150
+ * style({ opacity: '{{ end }}'}))
151
+ * ],
152
+ * { params: { time: '1000ms', start: 0, end: 1 }});
153
+ * ```
154
+ *
155
+ * The following invokes the defined animation with a call to `useAnimation()`,
156
+ * passing in override parameter values.
157
+ *
158
+ * ```js
159
+ * useAnimation(fadeAnimation, {
160
+ * params: {
161
+ * time: '2s',
162
+ * start: 1,
163
+ * end: 0
164
+ * }
165
+ * })
166
+ * ```
167
+ *
168
+ * If any of the passed-in parameter values are missing from this call,
169
+ * the default values are used. If one or more parameter values are missing before a step is
170
+ * animated, `useAnimation()` throws an error.
171
+ *
172
+ * @publicApi
173
+ */
174
+ export declare function animation(steps: AnimationMetadata | AnimationMetadata[], options?: AnimationOptions | null): AnimationReferenceMetadata;
175
+
176
+ /**
177
+ * Encapsulates a child animation, that can be run explicitly when the parent is run.
178
+ * Instantiated and returned by the `animateChild` function.
179
+ *
180
+ * @publicApi
181
+ */
182
+ export declare interface AnimationAnimateChildMetadata extends AnimationMetadata {
183
+ /**
184
+ * An options object containing a delay and
185
+ * developer-defined parameters that provide styling defaults and
186
+ * can be overridden on invocation. Default delay is 0.
187
+ */
188
+ options: AnimationOptions | null;
189
+ }
190
+
191
+ /**
192
+ * Encapsulates an animation step. Instantiated and returned by
193
+ * the `animate()` function.
194
+ *
195
+ * @publicApi
196
+ */
197
+ export declare interface AnimationAnimateMetadata extends AnimationMetadata {
198
+ /**
199
+ * The timing data for the step.
200
+ */
201
+ timings: string | number | AnimateTimings;
202
+ /**
203
+ * A set of styles used in the step.
204
+ */
205
+ styles: AnimationStyleMetadata | AnimationKeyframesSequenceMetadata | null;
206
+ }
207
+
208
+ /**
209
+ * Encapsulates a reusable animation.
210
+ * Instantiated and returned by the `useAnimation()` function.
211
+ *
212
+ * @publicApi
213
+ */
214
+ export declare interface AnimationAnimateRefMetadata extends AnimationMetadata {
215
+ /**
216
+ * An animation reference object.
217
+ */
218
+ animation: AnimationReferenceMetadata;
219
+ /**
220
+ * An options object containing a delay and
221
+ * developer-defined parameters that provide styling defaults and
222
+ * can be overridden on invocation. Default delay is 0.
223
+ */
224
+ options: AnimationOptions | null;
225
+ }
226
+
227
+ /**
228
+ * An injectable service that produces an animation sequence programmatically within an
229
+ * Angular component or directive.
230
+ * Provided by the `BrowserAnimationsModule` or `NoopAnimationsModule`.
231
+ *
232
+ * @usageNotes
233
+ *
234
+ * To use this service, add it to your component or directive as a dependency.
235
+ * The service is instantiated along with your component.
236
+ *
237
+ * Apps do not typically need to create their own animation players, but if you
238
+ * do need to, follow these steps:
239
+ *
240
+ * 1. Use the <code>[AnimationBuilder.build](api/animations/AnimationBuilder#build)()</code> method
241
+ * to create a programmatic animation. The method returns an `AnimationFactory` instance.
242
+ *
243
+ * 2. Use the factory object to create an `AnimationPlayer` and attach it to a DOM element.
244
+ *
245
+ * 3. Use the player object to control the animation programmatically.
246
+ *
247
+ * For example:
248
+ *
249
+ * ```ts
250
+ * // import the service from BrowserAnimationsModule
251
+ * import {AnimationBuilder} from '@angular/animations';
252
+ * // require the service as a dependency
253
+ * class MyCmp {
254
+ * constructor(private _builder: AnimationBuilder) {}
255
+ *
256
+ * makeAnimation(element: any) {
257
+ * // first define a reusable animation
258
+ * const myAnimation = this._builder.build([
259
+ * style({ width: 0 }),
260
+ * animate(1000, style({ width: '100px' }))
261
+ * ]);
262
+ *
263
+ * // use the returned factory object to create a player
264
+ * const player = myAnimation.create(element);
265
+ *
266
+ * player.play();
267
+ * }
268
+ * }
269
+ * ```
270
+ *
271
+ * @publicApi
272
+ */
273
+ export declare abstract class AnimationBuilder {
274
+ /**
275
+ * Builds a factory for producing a defined animation.
276
+ * @param animation A reusable animation definition.
277
+ * @returns A factory object that can create a player for the defined animation.
278
+ * @see `animate()`
279
+ */
280
+ abstract build(animation: AnimationMetadata | AnimationMetadata[]): AnimationFactory;
281
+ }
282
+
283
+
284
+ /**
285
+ * An instance of this class is returned as an event parameter when an animation
286
+ * callback is captured for an animation either during the start or done phase.
287
+ *
288
+ * ```typescript
289
+ * @Component({
290
+ * host: {
291
+ * '[@myAnimationTrigger]': 'someExpression',
292
+ * '(@myAnimationTrigger.start)': 'captureStartEvent($event)',
293
+ * '(@myAnimationTrigger.done)': 'captureDoneEvent($event)',
294
+ * },
295
+ * animations: [
296
+ * trigger("myAnimationTrigger", [
297
+ * // ...
298
+ * ])
299
+ * ]
300
+ * })
301
+ * class MyComponent {
302
+ * someExpression: any = false;
303
+ * captureStartEvent(event: AnimationEvent) {
304
+ * // the toState, fromState and totalTime data is accessible from the event variable
305
+ * }
306
+ *
307
+ * captureDoneEvent(event: AnimationEvent) {
308
+ * // the toState, fromState and totalTime data is accessible from the event variable
309
+ * }
310
+ * }
311
+ * ```
312
+ *
313
+ * @publicApi
314
+ */
315
+ declare interface AnimationEvent_2 {
316
+ /**
317
+ * The name of the state from which the animation is triggered.
318
+ */
319
+ fromState: string;
320
+ /**
321
+ * The name of the state in which the animation completes.
322
+ */
323
+ toState: string;
324
+ /**
325
+ * The time it takes the animation to complete, in milliseconds.
326
+ */
327
+ totalTime: number;
328
+ /**
329
+ * The animation phase in which the callback was invoked, one of
330
+ * "start" or "done".
331
+ */
332
+ phaseName: string;
333
+ /**
334
+ * The element to which the animation is attached.
335
+ */
336
+ element: any;
337
+ /**
338
+ * Internal.
339
+ */
340
+ triggerName: string;
341
+ /**
342
+ * Internal.
343
+ */
344
+ disabled: boolean;
345
+ }
346
+ export { AnimationEvent_2 as AnimationEvent }
347
+
348
+ /**
349
+ * A factory object returned from the
350
+ * <code>[AnimationBuilder.build](api/animations/AnimationBuilder#build)()</code>
351
+ * method.
352
+ *
353
+ * @publicApi
354
+ */
355
+ export declare abstract class AnimationFactory {
356
+ /**
357
+ * Creates an `AnimationPlayer` instance for the reusable animation defined by
358
+ * the <code>[AnimationBuilder.build](api/animations/AnimationBuilder#build)()</code>
359
+ * method that created this factory and attaches the new player a DOM element.
360
+ *
361
+ * @param element The DOM element to which to attach the player.
362
+ * @param options A set of options that can include a time delay and
363
+ * additional developer-defined parameters.
364
+ */
365
+ abstract create(element: any, options?: AnimationOptions): AnimationPlayer;
366
+ }
367
+
368
+ /**
369
+ * Encapsulates an animation group.
370
+ * Instantiated and returned by the `{@link animations/group group()}` function.
371
+ *
372
+ * @publicApi
373
+ */
374
+ export declare interface AnimationGroupMetadata extends AnimationMetadata {
375
+ /**
376
+ * One or more animation or style steps that form this group.
377
+ */
378
+ steps: AnimationMetadata[];
379
+ /**
380
+ * An options object containing a delay and
381
+ * developer-defined parameters that provide styling defaults and
382
+ * can be overridden on invocation. Default delay is 0.
383
+ */
384
+ options: AnimationOptions | null;
385
+ }
386
+
387
+ /**
388
+ * Encapsulates a keyframes sequence. Instantiated and returned by
389
+ * the `keyframes()` function.
390
+ *
391
+ * @publicApi
392
+ */
393
+ export declare interface AnimationKeyframesSequenceMetadata extends AnimationMetadata {
394
+ /**
395
+ * An array of animation styles.
396
+ */
397
+ steps: AnimationStyleMetadata[];
398
+ }
399
+
400
+ /**
401
+ * Base for animation data structures.
402
+ *
403
+ * @publicApi
404
+ */
405
+ export declare interface AnimationMetadata {
406
+ type: AnimationMetadataType;
407
+ }
408
+
409
+ /**
410
+ * @description Constants for the categories of parameters that can be defined for animations.
411
+ *
412
+ * A corresponding function defines a set of parameters for each category, and
413
+ * collects them into a corresponding `AnimationMetadata` object.
414
+ *
415
+ * @publicApi
416
+ */
417
+ export declare const enum AnimationMetadataType {
418
+ /**
419
+ * Associates a named animation state with a set of CSS styles.
420
+ * See [`state()`](api/animations/state)
421
+ */
422
+ State = 0,
423
+ /**
424
+ * Data for a transition from one animation state to another.
425
+ * See `transition()`
426
+ */
427
+ Transition = 1,
428
+ /**
429
+ * Contains a set of animation steps.
430
+ * See `sequence()`
431
+ */
432
+ Sequence = 2,
433
+ /**
434
+ * Contains a set of animation steps.
435
+ * See `{@link animations/group group()}`
436
+ */
437
+ Group = 3,
438
+ /**
439
+ * Contains an animation step.
440
+ * See `animate()`
441
+ */
442
+ Animate = 4,
443
+ /**
444
+ * Contains a set of animation steps.
445
+ * See `keyframes()`
446
+ */
447
+ Keyframes = 5,
448
+ /**
449
+ * Contains a set of CSS property-value pairs into a named style.
450
+ * See `style()`
451
+ */
452
+ Style = 6,
453
+ /**
454
+ * Associates an animation with an entry trigger that can be attached to an element.
455
+ * See `trigger()`
456
+ */
457
+ Trigger = 7,
458
+ /**
459
+ * Contains a re-usable animation.
460
+ * See `animation()`
461
+ */
462
+ Reference = 8,
463
+ /**
464
+ * Contains data to use in executing child animations returned by a query.
465
+ * See `animateChild()`
466
+ */
467
+ AnimateChild = 9,
468
+ /**
469
+ * Contains animation parameters for a re-usable animation.
470
+ * See `useAnimation()`
471
+ */
472
+ AnimateRef = 10,
473
+ /**
474
+ * Contains child-animation query data.
475
+ * See `query()`
476
+ */
477
+ Query = 11,
478
+ /**
479
+ * Contains data for staggering an animation sequence.
480
+ * See `stagger()`
481
+ */
482
+ Stagger = 12
483
+ }
484
+
485
+ /**
486
+ * @description Options that control animation styling and timing.
487
+ *
488
+ * The following animation functions accept `AnimationOptions` data:
489
+ *
490
+ * - `transition()`
491
+ * - `sequence()`
492
+ * - `{@link animations/group group()}`
493
+ * - `query()`
494
+ * - `animation()`
495
+ * - `useAnimation()`
496
+ * - `animateChild()`
497
+ *
498
+ * Programmatic animations built using the `AnimationBuilder` service also
499
+ * make use of `AnimationOptions`.
500
+ *
501
+ * @publicApi
502
+ */
503
+ export declare interface AnimationOptions {
504
+ /**
505
+ * Sets a time-delay for initiating an animation action.
506
+ * A number and optional time unit, such as "1s" or "10ms" for one second
507
+ * and 10 milliseconds, respectively.The default unit is milliseconds.
508
+ * Default value is 0, meaning no delay.
509
+ */
510
+ delay?: number | string;
511
+ /**
512
+ * A set of developer-defined parameters that modify styling and timing
513
+ * when an animation action starts. An array of key-value pairs, where the provided value
514
+ * is used as a default.
515
+ */
516
+ params?: {
517
+ [name: string]: any;
518
+ };
519
+ }
520
+
521
+ /**
522
+ * Provides programmatic control of a reusable animation sequence,
523
+ * built using the <code>[AnimationBuilder.build](api/animations/AnimationBuilder#build)()</code>
524
+ * method which returns an `AnimationFactory`, whose
525
+ * <code>[create](api/animations/AnimationFactory#create)()</code> method instantiates and
526
+ * initializes this interface.
527
+ *
528
+ * @see `AnimationBuilder`
529
+ * @see `AnimationFactory`
530
+ * @see `animate()`
531
+ *
532
+ * @publicApi
533
+ */
534
+ export declare interface AnimationPlayer {
535
+ /**
536
+ * Provides a callback to invoke when the animation finishes.
537
+ * @param fn The callback function.
538
+ * @see `finish()`
539
+ */
540
+ onDone(fn: () => void): void;
541
+ /**
542
+ * Provides a callback to invoke when the animation starts.
543
+ * @param fn The callback function.
544
+ * @see `run()`
545
+ */
546
+ onStart(fn: () => void): void;
547
+ /**
548
+ * Provides a callback to invoke after the animation is destroyed.
549
+ * @param fn The callback function.
550
+ * @see `destroy()`
551
+ * @see `beforeDestroy()`
552
+ */
553
+ onDestroy(fn: () => void): void;
554
+ /**
555
+ * Initializes the animation.
556
+ */
557
+ init(): void;
558
+ /**
559
+ * Reports whether the animation has started.
560
+ * @returns True if the animation has started, false otherwise.
561
+ */
562
+ hasStarted(): boolean;
563
+ /**
564
+ * Runs the animation, invoking the `onStart()` callback.
565
+ */
566
+ play(): void;
567
+ /**
568
+ * Pauses the animation.
569
+ */
570
+ pause(): void;
571
+ /**
572
+ * Restarts the paused animation.
573
+ */
574
+ restart(): void;
575
+ /**
576
+ * Ends the animation, invoking the `onDone()` callback.
577
+ */
578
+ finish(): void;
579
+ /**
580
+ * Destroys the animation, after invoking the `beforeDestroy()` callback.
581
+ * Calls the `onDestroy()` callback when destruction is completed.
582
+ */
583
+ destroy(): void;
584
+ /**
585
+ * Resets the animation to its initial state.
586
+ */
587
+ reset(): void;
588
+ /**
589
+ * Sets the position of the animation.
590
+ * @param position A 0-based offset into the duration, in milliseconds.
591
+ */
592
+ setPosition(position: any /** TODO #9100 */): void;
593
+ /**
594
+ * Reports the current position of the animation.
595
+ * @returns A 0-based offset into the duration, in milliseconds.
596
+ */
597
+ getPosition(): number;
598
+ /**
599
+ * The parent of this player, if any.
600
+ */
601
+ parentPlayer: AnimationPlayer | null;
602
+ /**
603
+ * The total run time of the animation, in milliseconds.
604
+ */
605
+ readonly totalTime: number;
606
+ /**
607
+ * Provides a callback to invoke before the animation is destroyed.
608
+ */
609
+ beforeDestroy?: () => any;
610
+ }
611
+
612
+ /**
613
+ * Encapsulates an animation query. Instantiated and returned by
614
+ * the `query()` function.
615
+ *
616
+ * @publicApi
617
+ */
618
+ export declare interface AnimationQueryMetadata extends AnimationMetadata {
619
+ /**
620
+ * The CSS selector for this query.
621
+ */
622
+ selector: string;
623
+ /**
624
+ * One or more animation step objects.
625
+ */
626
+ animation: AnimationMetadata | AnimationMetadata[];
627
+ /**
628
+ * A query options object.
629
+ */
630
+ options: AnimationQueryOptions | null;
631
+ }
632
+
633
+ /**
634
+ * Encapsulates animation query options.
635
+ * Passed to the `query()` function.
636
+ *
637
+ * @publicApi
638
+ */
639
+ export declare interface AnimationQueryOptions extends AnimationOptions {
640
+ /**
641
+ * True if this query is optional, false if it is required. Default is false.
642
+ * A required query throws an error if no elements are retrieved when
643
+ * the query is executed. An optional query does not.
644
+ *
645
+ */
646
+ optional?: boolean;
647
+ /**
648
+ * A maximum total number of results to return from the query.
649
+ * If negative, results are limited from the end of the query list towards the beginning.
650
+ * By default, results are not limited.
651
+ */
652
+ limit?: number;
653
+ }
654
+
655
+ /**
656
+ * Encapsulates a reusable animation, which is a collection of individual animation steps.
657
+ * Instantiated and returned by the `animation()` function, and
658
+ * passed to the `useAnimation()` function.
659
+ *
660
+ * @publicApi
661
+ */
662
+ export declare interface AnimationReferenceMetadata extends AnimationMetadata {
663
+ /**
664
+ * One or more animation step objects.
665
+ */
666
+ animation: AnimationMetadata | AnimationMetadata[];
667
+ /**
668
+ * An options object containing a delay and
669
+ * developer-defined parameters that provide styling defaults and
670
+ * can be overridden on invocation. Default delay is 0.
671
+ */
672
+ options: AnimationOptions | null;
673
+ }
674
+
675
+ /**
676
+ * Encapsulates an animation sequence.
677
+ * Instantiated and returned by the `sequence()` function.
678
+ *
679
+ * @publicApi
680
+ */
681
+ export declare interface AnimationSequenceMetadata extends AnimationMetadata {
682
+ /**
683
+ * An array of animation step objects.
684
+ */
685
+ steps: AnimationMetadata[];
686
+ /**
687
+ * An options object containing a delay and
688
+ * developer-defined parameters that provide styling defaults and
689
+ * can be overridden on invocation. Default delay is 0.
690
+ */
691
+ options: AnimationOptions | null;
692
+ }
693
+
694
+ /**
695
+ * Encapsulates parameters for staggering the start times of a set of animation steps.
696
+ * Instantiated and returned by the `stagger()` function.
697
+ *
698
+ * @publicApi
699
+ **/
700
+ export declare interface AnimationStaggerMetadata extends AnimationMetadata {
701
+ /**
702
+ * The timing data for the steps.
703
+ */
704
+ timings: string | number;
705
+ /**
706
+ * One or more animation steps.
707
+ */
708
+ animation: AnimationMetadata | AnimationMetadata[];
709
+ }
710
+
711
+ /**
712
+ * Encapsulates an animation state by associating a state name with a set of CSS styles.
713
+ * Instantiated and returned by the [`state()`](api/animations/state) function.
714
+ *
715
+ * @publicApi
716
+ */
717
+ export declare interface AnimationStateMetadata extends AnimationMetadata {
718
+ /**
719
+ * The state name, unique within the component.
720
+ */
721
+ name: string;
722
+ /**
723
+ * The CSS styles associated with this state.
724
+ */
725
+ styles: AnimationStyleMetadata;
726
+ /**
727
+ * An options object containing
728
+ * developer-defined parameters that provide styling defaults and
729
+ * can be overridden on invocation.
730
+ */
731
+ options?: {
732
+ params: {
733
+ [name: string]: any;
734
+ };
735
+ };
736
+ }
737
+
738
+ /**
739
+ * Encapsulates an animation style. Instantiated and returned by
740
+ * the `style()` function.
741
+ *
742
+ * @publicApi
743
+ */
744
+ export declare interface AnimationStyleMetadata extends AnimationMetadata {
745
+ /**
746
+ * A set of CSS style properties.
747
+ */
748
+ styles: '*' | {
749
+ [key: string]: string | number;
750
+ } | Array<{
751
+ [key: string]: string | number;
752
+ } | '*'>;
753
+ /**
754
+ * A percentage of the total animate time at which the style is to be applied.
755
+ */
756
+ offset: number | null;
757
+ }
758
+
759
+ /**
760
+ * Encapsulates an animation transition. Instantiated and returned by the
761
+ * `transition()` function.
762
+ *
763
+ * @publicApi
764
+ */
765
+ export declare interface AnimationTransitionMetadata extends AnimationMetadata {
766
+ /**
767
+ * An expression that describes a state change.
768
+ */
769
+ expr: string | ((fromState: string, toState: string, element?: any, params?: {
770
+ [key: string]: any;
771
+ }) => boolean);
772
+ /**
773
+ * One or more animation objects to which this transition applies.
774
+ */
775
+ animation: AnimationMetadata | AnimationMetadata[];
776
+ /**
777
+ * An options object containing a delay and
778
+ * developer-defined parameters that provide styling defaults and
779
+ * can be overridden on invocation. Default delay is 0.
780
+ */
781
+ options: AnimationOptions | null;
782
+ }
783
+
784
+ /**
785
+ * Contains an animation trigger. Instantiated and returned by the
786
+ * `trigger()` function.
787
+ *
788
+ * @publicApi
789
+ */
790
+ export declare interface AnimationTriggerMetadata extends AnimationMetadata {
791
+ /**
792
+ * The trigger name, used to associate it with an element. Unique within the component.
793
+ */
794
+ name: string;
795
+ /**
796
+ * An animation definition object, containing an array of state and transition declarations.
797
+ */
798
+ definitions: AnimationMetadata[];
799
+ /**
800
+ * An options object containing a delay and
801
+ * developer-defined parameters that provide styling defaults and
802
+ * can be overridden on invocation. Default delay is 0.
803
+ */
804
+ options: {
805
+ params?: {
806
+ [name: string]: any;
807
+ };
808
+ } | null;
809
+ }
810
+
811
+ /**
812
+ * Specifies automatic styling.
813
+ *
814
+ * @publicApi
815
+ */
816
+ export declare const AUTO_STYLE = "*";
817
+
818
+ /**
819
+ * @description Defines a list of animation steps to be run in parallel.
820
+ *
821
+ * @param steps An array of animation step objects.
822
+ * - When steps are defined by `style()` or `animate()`
823
+ * function calls, each call within the group is executed instantly.
824
+ * - To specify offset styles to be applied at a later time, define steps with
825
+ * `keyframes()`, or use `animate()` calls with a delay value.
826
+ * For example:
827
+ *
828
+ * ```typescript
829
+ * group([
830
+ * animate("1s", style({ background: "black" })),
831
+ * animate("2s", style({ color: "white" }))
832
+ * ])
833
+ * ```
834
+ *
835
+ * @param options An options object containing a delay and
836
+ * developer-defined parameters that provide styling defaults and
837
+ * can be overridden on invocation.
838
+ *
839
+ * @return An object that encapsulates the group data.
840
+ *
841
+ * @usageNotes
842
+ * Grouped animations are useful when a series of styles must be
843
+ * animated at different starting times and closed off at different ending times.
844
+ *
845
+ * When called within a `sequence()` or a
846
+ * `transition()` call, does not continue to the next
847
+ * instruction until all of the inner animation steps have completed.
848
+ *
849
+ * @publicApi
850
+ */
851
+ export declare function group(steps: AnimationMetadata[], options?: AnimationOptions | null): AnimationGroupMetadata;
852
+
853
+ /**
854
+ * Defines a set of animation styles, associating each style with an optional `offset` value.
855
+ *
856
+ * @param steps A set of animation styles with optional offset data.
857
+ * The optional `offset` value for a style specifies a percentage of the total animation
858
+ * time at which that style is applied.
859
+ * @returns An object that encapsulates the keyframes data.
860
+ *
861
+ * @usageNotes
862
+ * Use with the `animate()` call. Instead of applying animations
863
+ * from the current state
864
+ * to the destination state, keyframes describe how each style entry is applied and at what point
865
+ * within the animation arc.
866
+ * Compare [CSS Keyframe Animations](https://www.w3schools.com/css/css3_animations.asp).
867
+ *
868
+ * ### Usage
869
+ *
870
+ * In the following example, the offset values describe
871
+ * when each `backgroundColor` value is applied. The color is red at the start, and changes to
872
+ * blue when 20% of the total time has elapsed.
873
+ *
874
+ * ```typescript
875
+ * // the provided offset values
876
+ * animate("5s", keyframes([
877
+ * style({ backgroundColor: "red", offset: 0 }),
878
+ * style({ backgroundColor: "blue", offset: 0.2 }),
879
+ * style({ backgroundColor: "orange", offset: 0.3 }),
880
+ * style({ backgroundColor: "black", offset: 1 })
881
+ * ]))
882
+ * ```
883
+ *
884
+ * If there are no `offset` values specified in the style entries, the offsets
885
+ * are calculated automatically.
886
+ *
887
+ * ```typescript
888
+ * animate("5s", keyframes([
889
+ * style({ backgroundColor: "red" }) // offset = 0
890
+ * style({ backgroundColor: "blue" }) // offset = 0.33
891
+ * style({ backgroundColor: "orange" }) // offset = 0.66
892
+ * style({ backgroundColor: "black" }) // offset = 1
893
+ * ]))
894
+ *```
895
+
896
+ * @publicApi
897
+ */
898
+ export declare function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSequenceMetadata;
899
+
900
+ /**
901
+ * An empty programmatic controller for reusable animations.
902
+ * Used internally when animations are disabled, to avoid
903
+ * checking for the null case when an animation player is expected.
904
+ *
905
+ * @see `animate()`
906
+ * @see `AnimationPlayer`
907
+ * @see `GroupPlayer`
908
+ *
909
+ * @publicApi
910
+ */
911
+ export declare class NoopAnimationPlayer implements AnimationPlayer {
912
+ private _onDoneFns;
913
+ private _onStartFns;
914
+ private _onDestroyFns;
915
+ private _started;
916
+ private _destroyed;
917
+ private _finished;
918
+ private _position;
919
+ parentPlayer: AnimationPlayer | null;
920
+ readonly totalTime: number;
921
+ constructor(duration?: number, delay?: number);
922
+ private _onFinish;
923
+ onStart(fn: () => void): void;
924
+ onDone(fn: () => void): void;
925
+ onDestroy(fn: () => void): void;
926
+ hasStarted(): boolean;
927
+ init(): void;
928
+ play(): void;
929
+ private _onStart;
930
+ pause(): void;
931
+ restart(): void;
932
+ finish(): void;
933
+ destroy(): void;
934
+ reset(): void;
935
+ setPosition(position: number): void;
936
+ getPosition(): number;
937
+ }
938
+
939
+ /**
940
+ * Finds one or more inner elements within the current element that is
941
+ * being animated within a sequence. Use with `animate()`.
942
+ *
943
+ * @param selector The element to query, or a set of elements that contain Angular-specific
944
+ * characteristics, specified with one or more of the following tokens.
945
+ * - `query(":enter")` or `query(":leave")` : Query for newly inserted/removed elements (not
946
+ * all elements can be queried via these tokens, see
947
+ * [Entering and Leaving Elements](#entering-and-leaving-elements))
948
+ * - `query(":animating")` : Query all currently animating elements.
949
+ * - `query("@triggerName")` : Query elements that contain an animation trigger.
950
+ * - `query("@*")` : Query all elements that contain an animation triggers.
951
+ * - `query(":self")` : Include the current element into the animation sequence.
952
+ *
953
+ * @param animation One or more animation steps to apply to the queried element or elements.
954
+ * An array is treated as an animation sequence.
955
+ * @param options An options object. Use the 'limit' field to limit the total number of
956
+ * items to collect.
957
+ * @return An object that encapsulates the query data.
958
+ *
959
+ * @usageNotes
960
+ *
961
+ * ### Multiple Tokens
962
+ *
963
+ * Tokens can be merged into a combined query selector string. For example:
964
+ *
965
+ * ```typescript
966
+ * query(':self, .record:enter, .record:leave, @subTrigger', [...])
967
+ * ```
968
+ *
969
+ * The `query()` function collects multiple elements and works internally by using
970
+ * `element.querySelectorAll`. Use the `limit` field of an options object to limit
971
+ * the total number of items to be collected. For example:
972
+ *
973
+ * ```js
974
+ * query('div', [
975
+ * animate(...),
976
+ * animate(...)
977
+ * ], { limit: 1 })
978
+ * ```
979
+ *
980
+ * By default, throws an error when zero items are found. Set the
981
+ * `optional` flag to ignore this error. For example:
982
+ *
983
+ * ```js
984
+ * query('.some-element-that-may-not-be-there', [
985
+ * animate(...),
986
+ * animate(...)
987
+ * ], { optional: true })
988
+ * ```
989
+ *
990
+ * ### Entering and Leaving Elements
991
+ *
992
+ * Not all elements can be queried via the `:enter` and `:leave` tokens, the only ones
993
+ * that can are those that Angular assumes can enter/leave based on their own logic
994
+ * (if their insertion/removal is simply a consequence of that of their parent they
995
+ * should be queried via a different token in their parent's `:enter`/`:leave` transitions).
996
+ *
997
+ * The only elements Angular assumes can enter/leave based on their own logic (thus the only
998
+ * ones that can be queried via the `:enter` and `:leave` tokens) are:
999
+ * - Those inserted dynamically (via `ViewContainerRef`)
1000
+ * - Those that have a structural directive (which, under the hood, are a subset of the above ones)
1001
+ *
1002
+ * <div class="alert is-helpful">
1003
+ *
1004
+ * Note that elements will be successfully queried via `:enter`/`:leave` even if their
1005
+ * insertion/removal is not done manually via `ViewContainerRef`or caused by their structural
1006
+ * directive (e.g. they enter/exit alongside their parent).
1007
+ *
1008
+ * </div>
1009
+ *
1010
+ * <div class="alert is-important">
1011
+ *
1012
+ * There is an exception to what previously mentioned, besides elements entering/leaving based on
1013
+ * their own logic, elements with an animation trigger can always be queried via `:leave` when
1014
+ * their parent is also leaving.
1015
+ *
1016
+ * </div>
1017
+ *
1018
+ * ### Usage Example
1019
+ *
1020
+ * The following example queries for inner elements and animates them
1021
+ * individually using `animate()`.
1022
+ *
1023
+ * ```typescript
1024
+ * @Component({
1025
+ * selector: 'inner',
1026
+ * template: `
1027
+ * <div [@queryAnimation]="exp">
1028
+ * <h1>Title</h1>
1029
+ * <div class="content">
1030
+ * Blah blah blah
1031
+ * </div>
1032
+ * </div>
1033
+ * `,
1034
+ * animations: [
1035
+ * trigger('queryAnimation', [
1036
+ * transition('* => goAnimate', [
1037
+ * // hide the inner elements
1038
+ * query('h1', style({ opacity: 0 })),
1039
+ * query('.content', style({ opacity: 0 })),
1040
+ *
1041
+ * // animate the inner elements in, one by one
1042
+ * query('h1', animate(1000, style({ opacity: 1 }))),
1043
+ * query('.content', animate(1000, style({ opacity: 1 }))),
1044
+ * ])
1045
+ * ])
1046
+ * ]
1047
+ * })
1048
+ * class Cmp {
1049
+ * exp = '';
1050
+ *
1051
+ * goAnimate() {
1052
+ * this.exp = 'goAnimate';
1053
+ * }
1054
+ * }
1055
+ * ```
1056
+ *
1057
+ * @publicApi
1058
+ */
1059
+ export declare function query(selector: string, animation: AnimationMetadata | AnimationMetadata[], options?: AnimationQueryOptions | null): AnimationQueryMetadata;
1060
+
1061
+ /**
1062
+ * Defines a list of animation steps to be run sequentially, one by one.
1063
+ *
1064
+ * @param steps An array of animation step objects.
1065
+ * - Steps defined by `style()` calls apply the styling data immediately.
1066
+ * - Steps defined by `animate()` calls apply the styling data over time
1067
+ * as specified by the timing data.
1068
+ *
1069
+ * ```typescript
1070
+ * sequence([
1071
+ * style({ opacity: 0 }),
1072
+ * animate("1s", style({ opacity: 1 }))
1073
+ * ])
1074
+ * ```
1075
+ *
1076
+ * @param options An options object containing a delay and
1077
+ * developer-defined parameters that provide styling defaults and
1078
+ * can be overridden on invocation.
1079
+ *
1080
+ * @return An object that encapsulates the sequence data.
1081
+ *
1082
+ * @usageNotes
1083
+ * When you pass an array of steps to a
1084
+ * `transition()` call, the steps run sequentially by default.
1085
+ * Compare this to the `{@link animations/group group()}` call, which runs animation steps in
1086
+ *parallel.
1087
+ *
1088
+ * When a sequence is used within a `{@link animations/group group()}` or a `transition()` call,
1089
+ * execution continues to the next instruction only after each of the inner animation
1090
+ * steps have completed.
1091
+ *
1092
+ * @publicApi
1093
+ **/
1094
+ export declare function sequence(steps: AnimationMetadata[], options?: AnimationOptions | null): AnimationSequenceMetadata;
1095
+
1096
+ /**
1097
+ * Use within an animation `query()` call to issue a timing gap after
1098
+ * each queried item is animated.
1099
+ *
1100
+ * @param timings A delay value.
1101
+ * @param animation One ore more animation steps.
1102
+ * @returns An object that encapsulates the stagger data.
1103
+ *
1104
+ * @usageNotes
1105
+ * In the following example, a container element wraps a list of items stamped out
1106
+ * by an `ngFor`. The container element contains an animation trigger that will later be set
1107
+ * to query for each of the inner items.
1108
+ *
1109
+ * Each time items are added, the opacity fade-in animation runs,
1110
+ * and each removed item is faded out.
1111
+ * When either of these animations occur, the stagger effect is
1112
+ * applied after each item's animation is started.
1113
+ *
1114
+ * ```html
1115
+ * <!-- list.component.html -->
1116
+ * <button (click)="toggle()">Show / Hide Items</button>
1117
+ * <hr />
1118
+ * <div [@listAnimation]="items.length">
1119
+ * <div *ngFor="let item of items">
1120
+ * {{ item }}
1121
+ * </div>
1122
+ * </div>
1123
+ * ```
1124
+ *
1125
+ * Here is the component code:
1126
+ *
1127
+ * ```typescript
1128
+ * import {trigger, transition, style, animate, query, stagger} from '@angular/animations';
1129
+ * @Component({
1130
+ * templateUrl: 'list.component.html',
1131
+ * animations: [
1132
+ * trigger('listAnimation', [
1133
+ * ...
1134
+ * ])
1135
+ * ]
1136
+ * })
1137
+ * class ListComponent {
1138
+ * items = [];
1139
+ *
1140
+ * showItems() {
1141
+ * this.items = [0,1,2,3,4];
1142
+ * }
1143
+ *
1144
+ * hideItems() {
1145
+ * this.items = [];
1146
+ * }
1147
+ *
1148
+ * toggle() {
1149
+ * this.items.length ? this.hideItems() : this.showItems();
1150
+ * }
1151
+ * }
1152
+ * ```
1153
+ *
1154
+ * Here is the animation trigger code:
1155
+ *
1156
+ * ```typescript
1157
+ * trigger('listAnimation', [
1158
+ * transition('* => *', [ // each time the binding value changes
1159
+ * query(':leave', [
1160
+ * stagger(100, [
1161
+ * animate('0.5s', style({ opacity: 0 }))
1162
+ * ])
1163
+ * ]),
1164
+ * query(':enter', [
1165
+ * style({ opacity: 0 }),
1166
+ * stagger(100, [
1167
+ * animate('0.5s', style({ opacity: 1 }))
1168
+ * ])
1169
+ * ])
1170
+ * ])
1171
+ * ])
1172
+ * ```
1173
+ *
1174
+ * @publicApi
1175
+ */
1176
+ export declare function stagger(timings: string | number, animation: AnimationMetadata | AnimationMetadata[]): AnimationStaggerMetadata;
1177
+
1178
+ /**
1179
+ * Declares an animation state within a trigger attached to an element.
1180
+ *
1181
+ * @param name One or more names for the defined state in a comma-separated string.
1182
+ * The following reserved state names can be supplied to define a style for specific use
1183
+ * cases:
1184
+ *
1185
+ * - `void` You can associate styles with this name to be used when
1186
+ * the element is detached from the application. For example, when an `ngIf` evaluates
1187
+ * to false, the state of the associated element is void.
1188
+ * - `*` (asterisk) Indicates the default state. You can associate styles with this name
1189
+ * to be used as the fallback when the state that is being animated is not declared
1190
+ * within the trigger.
1191
+ *
1192
+ * @param styles A set of CSS styles associated with this state, created using the
1193
+ * `style()` function.
1194
+ * This set of styles persists on the element once the state has been reached.
1195
+ * @param options Parameters that can be passed to the state when it is invoked.
1196
+ * 0 or more key-value pairs.
1197
+ * @return An object that encapsulates the new state data.
1198
+ *
1199
+ * @usageNotes
1200
+ * Use the `trigger()` function to register states to an animation trigger.
1201
+ * Use the `transition()` function to animate between states.
1202
+ * When a state is active within a component, its associated styles persist on the element,
1203
+ * even when the animation ends.
1204
+ *
1205
+ * @publicApi
1206
+ **/
1207
+ export declare function state(name: string, styles: AnimationStyleMetadata, options?: {
1208
+ params: {
1209
+ [name: string]: any;
1210
+ };
1211
+ }): AnimationStateMetadata;
1212
+
1213
+ /**
1214
+ * Declares a key/value object containing CSS properties/styles that
1215
+ * can then be used for an animation [`state`](api/animations/state), within an animation
1216
+ *`sequence`, or as styling data for calls to `animate()` and `keyframes()`.
1217
+ *
1218
+ * @param tokens A set of CSS styles or HTML styles associated with an animation state.
1219
+ * The value can be any of the following:
1220
+ * - A key-value style pair associating a CSS property with a value.
1221
+ * - An array of key-value style pairs.
1222
+ * - An asterisk (*), to use auto-styling, where styles are derived from the element
1223
+ * being animated and applied to the animation when it starts.
1224
+ *
1225
+ * Auto-styling can be used to define a state that depends on layout or other
1226
+ * environmental factors.
1227
+ *
1228
+ * @return An object that encapsulates the style data.
1229
+ *
1230
+ * @usageNotes
1231
+ * The following examples create animation styles that collect a set of
1232
+ * CSS property values:
1233
+ *
1234
+ * ```typescript
1235
+ * // string values for CSS properties
1236
+ * style({ background: "red", color: "blue" })
1237
+ *
1238
+ * // numerical pixel values
1239
+ * style({ width: 100, height: 0 })
1240
+ * ```
1241
+ *
1242
+ * The following example uses auto-styling to allow an element to animate from
1243
+ * a height of 0 up to its full height:
1244
+ *
1245
+ * ```
1246
+ * style({ height: 0 }),
1247
+ * animate("1s", style({ height: "*" }))
1248
+ * ```
1249
+ *
1250
+ * @publicApi
1251
+ **/
1252
+ export declare function style(tokens: '*' | {
1253
+ [key: string]: string | number;
1254
+ } | Array<'*' | {
1255
+ [key: string]: string | number;
1256
+ }>): AnimationStyleMetadata;
1257
+
1258
+ /**
1259
+ * Declares an animation transition which is played when a certain specified condition is met.
1260
+ *
1261
+ * @param stateChangeExpr A string with a specific format or a function that specifies when the
1262
+ * animation transition should occur (see [State Change Expression](#state-change-expression)).
1263
+ *
1264
+ * @param steps One or more animation objects that represent the animation's instructions.
1265
+ *
1266
+ * @param options An options object that can be used to specify a delay for the animation or provide
1267
+ * custom parameters for it.
1268
+ *
1269
+ * @returns An object that encapsulates the transition data.
1270
+ *
1271
+ * @usageNotes
1272
+ *
1273
+ * ### State Change Expression
1274
+ *
1275
+ * The State Change Expression instructs Angular when to run the transition's animations, it can
1276
+ *either be
1277
+ * - a string with a specific syntax
1278
+ * - or a function that compares the previous and current state (value of the expression bound to
1279
+ * the element's trigger) and returns `true` if the transition should occur or `false` otherwise
1280
+ *
1281
+ * The string format can be:
1282
+ * - `fromState => toState`, which indicates that the transition's animations should occur then the
1283
+ * expression bound to the trigger's element goes from `fromState` to `toState`
1284
+ *
1285
+ * _Example:_
1286
+ * ```typescript
1287
+ * transition('open => closed', animate('.5s ease-out', style({ height: 0 }) ))
1288
+ * ```
1289
+ *
1290
+ * - `fromState <=> toState`, which indicates that the transition's animations should occur then
1291
+ * the expression bound to the trigger's element goes from `fromState` to `toState` or vice versa
1292
+ *
1293
+ * _Example:_
1294
+ * ```typescript
1295
+ * transition('enabled <=> disabled', animate('1s cubic-bezier(0.8,0.3,0,1)'))
1296
+ * ```
1297
+ *
1298
+ * - `:enter`/`:leave`, which indicates that the transition's animations should occur when the
1299
+ * element enters or exists the DOM
1300
+ *
1301
+ * _Example:_
1302
+ * ```typescript
1303
+ * transition(':enter', [
1304
+ * style({ opacity: 0 }),
1305
+ * animate('500ms', style({ opacity: 1 }))
1306
+ * ])
1307
+ * ```
1308
+ *
1309
+ * - `:increment`/`:decrement`, which indicates that the transition's animations should occur when
1310
+ * the numerical expression bound to the trigger's element has increased in value or decreased
1311
+ *
1312
+ * _Example:_
1313
+ * ```typescript
1314
+ * transition(':increment', query('@counter', animateChild()))
1315
+ * ```
1316
+ *
1317
+ * - a sequence of any of the above divided by commas, which indicates that transition's animations
1318
+ * should occur whenever one of the state change expressions matches
1319
+ *
1320
+ * _Example:_
1321
+ * ```typescript
1322
+ * transition(':increment, * => enabled, :enter', animate('1s ease', keyframes([
1323
+ * style({ transform: 'scale(1)', offset: 0}),
1324
+ * style({ transform: 'scale(1.1)', offset: 0.7}),
1325
+ * style({ transform: 'scale(1)', offset: 1})
1326
+ * ]))),
1327
+ * ```
1328
+ *
1329
+ * Also note that in such context:
1330
+ * - `void` can be used to indicate the absence of the element
1331
+ * - asterisks can be used as wildcards that match any state
1332
+ * - (as a consequence of the above, `void => *` is equivalent to `:enter` and `* => void` is
1333
+ * equivalent to `:leave`)
1334
+ * - `true` and `false` also match expression values of `1` and `0` respectively (but do not match
1335
+ * _truthy_ and _falsy_ values)
1336
+ *
1337
+ * <div class="alert is-helpful">
1338
+ *
1339
+ * Be careful about entering end leaving elements as their transitions present a common
1340
+ * pitfall for developers.
1341
+ *
1342
+ * Note that when an element with a trigger enters the DOM its `:enter` transition always
1343
+ * gets executed, but its `:leave` transition will not be executed if the element is removed
1344
+ * alongside its parent (as it will be removed "without warning" before its transition has
1345
+ * a chance to be executed, the only way that such transition can occur is if the element
1346
+ * is exiting the DOM on its own).
1347
+ *
1348
+ *
1349
+ * </div>
1350
+ *
1351
+ * ### Animating to a Final State
1352
+ *
1353
+ * If the final step in a transition is a call to `animate()` that uses a timing value
1354
+ * with no `style` data, that step is automatically considered the final animation arc,
1355
+ * for the element to reach the final state, in such case Angular automatically adds or removes
1356
+ * CSS styles to ensure that the element is in the correct final state.
1357
+ *
1358
+ *
1359
+ * ### Usage Examples
1360
+ *
1361
+ * - Transition animations applied based on
1362
+ * the trigger's expression value
1363
+ *
1364
+ * ```HTML
1365
+ * <div [@myAnimationTrigger]="myStatusExp">
1366
+ * ...
1367
+ * </div>
1368
+ * ```
1369
+ *
1370
+ * ```typescript
1371
+ * trigger("myAnimationTrigger", [
1372
+ * ..., // states
1373
+ * transition("on => off, open => closed", animate(500)),
1374
+ * transition("* <=> error", query('.indicator', animateChild()))
1375
+ * ])
1376
+ * ```
1377
+ *
1378
+ * - Transition animations applied based on custom logic dependent
1379
+ * on the trigger's expression value and provided parameters
1380
+ *
1381
+ * ```HTML
1382
+ * <div [@myAnimationTrigger]="{
1383
+ * value: stepName,
1384
+ * params: { target: currentTarget }
1385
+ * }">
1386
+ * ...
1387
+ * </div>
1388
+ * ```
1389
+ *
1390
+ * ```typescript
1391
+ * trigger("myAnimationTrigger", [
1392
+ * ..., // states
1393
+ * transition(
1394
+ * (fromState, toState, _element, params) =>
1395
+ * ['firststep', 'laststep'].includes(fromState.toLowerCase())
1396
+ * && toState === params?.['target'],
1397
+ * animate('1s')
1398
+ * )
1399
+ * ])
1400
+ * ```
1401
+ *
1402
+ * @publicApi
1403
+ **/
1404
+ export declare function transition(stateChangeExpr: string | ((fromState: string, toState: string, element?: any, params?: {
1405
+ [key: string]: any;
1406
+ }) => boolean), steps: AnimationMetadata | AnimationMetadata[], options?: AnimationOptions | null): AnimationTransitionMetadata;
1407
+
1408
+ /**
1409
+ * Creates a named animation trigger, containing a list of [`state()`](api/animations/state)
1410
+ * and `transition()` entries to be evaluated when the expression
1411
+ * bound to the trigger changes.
1412
+ *
1413
+ * @param name An identifying string.
1414
+ * @param definitions An animation definition object, containing an array of
1415
+ * [`state()`](api/animations/state) and `transition()` declarations.
1416
+ *
1417
+ * @return An object that encapsulates the trigger data.
1418
+ *
1419
+ * @usageNotes
1420
+ * Define an animation trigger in the `animations` section of `@Component` metadata.
1421
+ * In the template, reference the trigger by name and bind it to a trigger expression that
1422
+ * evaluates to a defined animation state, using the following format:
1423
+ *
1424
+ * `[@triggerName]="expression"`
1425
+ *
1426
+ * Animation trigger bindings convert all values to strings, and then match the
1427
+ * previous and current values against any linked transitions.
1428
+ * Booleans can be specified as `1` or `true` and `0` or `false`.
1429
+ *
1430
+ * ### Usage Example
1431
+ *
1432
+ * The following example creates an animation trigger reference based on the provided
1433
+ * name value.
1434
+ * The provided animation value is expected to be an array consisting of state and
1435
+ * transition declarations.
1436
+ *
1437
+ * ```typescript
1438
+ * @Component({
1439
+ * selector: "my-component",
1440
+ * templateUrl: "my-component-tpl.html",
1441
+ * animations: [
1442
+ * trigger("myAnimationTrigger", [
1443
+ * state(...),
1444
+ * state(...),
1445
+ * transition(...),
1446
+ * transition(...)
1447
+ * ])
1448
+ * ]
1449
+ * })
1450
+ * class MyComponent {
1451
+ * myStatusExp = "something";
1452
+ * }
1453
+ * ```
1454
+ *
1455
+ * The template associated with this component makes use of the defined trigger
1456
+ * by binding to an element within its template code.
1457
+ *
1458
+ * ```html
1459
+ * <!-- somewhere inside of my-component-tpl.html -->
1460
+ * <div [@myAnimationTrigger]="myStatusExp">...</div>
1461
+ * ```
1462
+ *
1463
+ * ### Using an inline function
1464
+ * The `transition` animation method also supports reading an inline function which can decide
1465
+ * if its associated animation should be run.
1466
+ *
1467
+ * ```typescript
1468
+ * // this method is run each time the `myAnimationTrigger` trigger value changes.
1469
+ * function myInlineMatcherFn(fromState: string, toState: string, element: any, params: {[key:
1470
+ string]: any}): boolean {
1471
+ * // notice that `element` and `params` are also available here
1472
+ * return toState == 'yes-please-animate';
1473
+ * }
1474
+ *
1475
+ * @Component({
1476
+ * selector: 'my-component',
1477
+ * templateUrl: 'my-component-tpl.html',
1478
+ * animations: [
1479
+ * trigger('myAnimationTrigger', [
1480
+ * transition(myInlineMatcherFn, [
1481
+ * // the animation sequence code
1482
+ * ]),
1483
+ * ])
1484
+ * ]
1485
+ * })
1486
+ * class MyComponent {
1487
+ * myStatusExp = "yes-please-animate";
1488
+ * }
1489
+ * ```
1490
+ *
1491
+ * ### Disabling Animations
1492
+ * When true, the special animation control binding `@.disabled` binding prevents
1493
+ * all animations from rendering.
1494
+ * Place the `@.disabled` binding on an element to disable
1495
+ * animations on the element itself, as well as any inner animation triggers
1496
+ * within the element.
1497
+ *
1498
+ * The following example shows how to use this feature:
1499
+ *
1500
+ * ```typescript
1501
+ * @Component({
1502
+ * selector: 'my-component',
1503
+ * template: `
1504
+ * <div [@.disabled]="isDisabled">
1505
+ * <div [@childAnimation]="exp"></div>
1506
+ * </div>
1507
+ * `,
1508
+ * animations: [
1509
+ * trigger("childAnimation", [
1510
+ * // ...
1511
+ * ])
1512
+ * ]
1513
+ * })
1514
+ * class MyComponent {
1515
+ * isDisabled = true;
1516
+ * exp = '...';
1517
+ * }
1518
+ * ```
1519
+ *
1520
+ * When `@.disabled` is true, it prevents the `@childAnimation` trigger from animating,
1521
+ * along with any inner animations.
1522
+ *
1523
+ * ### Disable animations application-wide
1524
+ * When an area of the template is set to have animations disabled,
1525
+ * **all** inner components have their animations disabled as well.
1526
+ * This means that you can disable all animations for an app
1527
+ * by placing a host binding set on `@.disabled` on the topmost Angular component.
1528
+ *
1529
+ * ```typescript
1530
+ * import {Component, HostBinding} from '@angular/core';
1531
+ *
1532
+ * @Component({
1533
+ * selector: 'app-component',
1534
+ * templateUrl: 'app.component.html',
1535
+ * })
1536
+ * class AppComponent {
1537
+ * @HostBinding('@.disabled')
1538
+ * public animationsDisabled = true;
1539
+ * }
1540
+ * ```
1541
+ *
1542
+ * ### Overriding disablement of inner animations
1543
+ * Despite inner animations being disabled, a parent animation can `query()`
1544
+ * for inner elements located in disabled areas of the template and still animate
1545
+ * them if needed. This is also the case for when a sub animation is
1546
+ * queried by a parent and then later animated using `animateChild()`.
1547
+ *
1548
+ * ### Detecting when an animation is disabled
1549
+ * If a region of the DOM (or the entire application) has its animations disabled, the animation
1550
+ * trigger callbacks still fire, but for zero seconds. When the callback fires, it provides
1551
+ * an instance of an `AnimationEvent`. If animations are disabled,
1552
+ * the `.disabled` flag on the event is true.
1553
+ *
1554
+ * @publicApi
1555
+ */
1556
+ export declare function trigger(name: string, definitions: AnimationMetadata[]): AnimationTriggerMetadata;
1557
+
1558
+ /**
1559
+ * Starts a reusable animation that is created using the `animation()` function.
1560
+ *
1561
+ * @param animation The reusable animation to start.
1562
+ * @param options An options object that can contain a delay value for the start of
1563
+ * the animation, and additional override values for developer-defined parameters.
1564
+ * @return An object that contains the animation parameters.
1565
+ *
1566
+ * @publicApi
1567
+ */
1568
+ export declare function useAnimation(animation: AnimationReferenceMetadata, options?: AnimationOptions | null): AnimationAnimateRefMetadata;
1569
+
1570
+ /**
1571
+ * A programmatic controller for a group of reusable animations.
1572
+ * Used internally to control animations.
1573
+ *
1574
+ * @see `AnimationPlayer`
1575
+ * @see `{@link animations/group group()}`
1576
+ *
1577
+ */
1578
+ export declare class ɵAnimationGroupPlayer implements AnimationPlayer {
1579
+ private _onDoneFns;
1580
+ private _onStartFns;
1581
+ private _finished;
1582
+ private _started;
1583
+ private _destroyed;
1584
+ private _onDestroyFns;
1585
+ parentPlayer: AnimationPlayer | null;
1586
+ totalTime: number;
1587
+ readonly players: AnimationPlayer[];
1588
+ constructor(_players: AnimationPlayer[]);
1589
+ private _onFinish;
1590
+ init(): void;
1591
+ onStart(fn: () => void): void;
1592
+ private _onStart;
1593
+ onDone(fn: () => void): void;
1594
+ onDestroy(fn: () => void): void;
1595
+ hasStarted(): boolean;
1596
+ play(): void;
1597
+ pause(): void;
1598
+ restart(): void;
1599
+ finish(): void;
1600
+ destroy(): void;
1601
+ private _onDestroy;
1602
+ reset(): void;
1603
+ setPosition(p: number): void;
1604
+ getPosition(): number;
1605
+ beforeDestroy(): void;
1606
+ }
1607
+
1608
+ export declare const ɵPRE_STYLE = "!";
1609
+
1610
+
1611
+ /**
1612
+ * Represents a set of CSS styles for use in an animation style as a generic.
1613
+ */
1614
+ export declare interface ɵStyleData {
1615
+ [key: string]: string | number;
1616
+ }
1617
+
1618
+ /**
1619
+ * Represents a set of CSS styles for use in an animation style as a Map.
1620
+ */
1621
+ export declare type ɵStyleDataMap = Map<string, string | number>;
1622
+
1623
+ export { }