private_export-faY_wCkZ.mjs 38 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176
  1. /**
  2. * @license Angular v19.2.13
  3. * (c) 2010-2025 Google LLC. https://angular.io/
  4. * License: MIT
  5. */
  6. /**
  7. * @description Constants for the categories of parameters that can be defined for animations.
  8. *
  9. * A corresponding function defines a set of parameters for each category, and
  10. * collects them into a corresponding `AnimationMetadata` object.
  11. *
  12. * @publicApi
  13. */
  14. var AnimationMetadataType;
  15. (function (AnimationMetadataType) {
  16. /**
  17. * Associates a named animation state with a set of CSS styles.
  18. * See [`state()`](api/animations/state)
  19. */
  20. AnimationMetadataType[AnimationMetadataType["State"] = 0] = "State";
  21. /**
  22. * Data for a transition from one animation state to another.
  23. * See `transition()`
  24. */
  25. AnimationMetadataType[AnimationMetadataType["Transition"] = 1] = "Transition";
  26. /**
  27. * Contains a set of animation steps.
  28. * See `sequence()`
  29. */
  30. AnimationMetadataType[AnimationMetadataType["Sequence"] = 2] = "Sequence";
  31. /**
  32. * Contains a set of animation steps.
  33. * See `group()`
  34. */
  35. AnimationMetadataType[AnimationMetadataType["Group"] = 3] = "Group";
  36. /**
  37. * Contains an animation step.
  38. * See `animate()`
  39. */
  40. AnimationMetadataType[AnimationMetadataType["Animate"] = 4] = "Animate";
  41. /**
  42. * Contains a set of animation steps.
  43. * See `keyframes()`
  44. */
  45. AnimationMetadataType[AnimationMetadataType["Keyframes"] = 5] = "Keyframes";
  46. /**
  47. * Contains a set of CSS property-value pairs into a named style.
  48. * See `style()`
  49. */
  50. AnimationMetadataType[AnimationMetadataType["Style"] = 6] = "Style";
  51. /**
  52. * Associates an animation with an entry trigger that can be attached to an element.
  53. * See `trigger()`
  54. */
  55. AnimationMetadataType[AnimationMetadataType["Trigger"] = 7] = "Trigger";
  56. /**
  57. * Contains a re-usable animation.
  58. * See `animation()`
  59. */
  60. AnimationMetadataType[AnimationMetadataType["Reference"] = 8] = "Reference";
  61. /**
  62. * Contains data to use in executing child animations returned by a query.
  63. * See `animateChild()`
  64. */
  65. AnimationMetadataType[AnimationMetadataType["AnimateChild"] = 9] = "AnimateChild";
  66. /**
  67. * Contains animation parameters for a re-usable animation.
  68. * See `useAnimation()`
  69. */
  70. AnimationMetadataType[AnimationMetadataType["AnimateRef"] = 10] = "AnimateRef";
  71. /**
  72. * Contains child-animation query data.
  73. * See `query()`
  74. */
  75. AnimationMetadataType[AnimationMetadataType["Query"] = 11] = "Query";
  76. /**
  77. * Contains data for staggering an animation sequence.
  78. * See `stagger()`
  79. */
  80. AnimationMetadataType[AnimationMetadataType["Stagger"] = 12] = "Stagger";
  81. })(AnimationMetadataType || (AnimationMetadataType = {}));
  82. /**
  83. * Specifies automatic styling.
  84. *
  85. * @publicApi
  86. */
  87. const AUTO_STYLE = '*';
  88. /**
  89. * Creates a named animation trigger, containing a list of [`state()`](api/animations/state)
  90. * and `transition()` entries to be evaluated when the expression
  91. * bound to the trigger changes.
  92. *
  93. * @param name An identifying string.
  94. * @param definitions An animation definition object, containing an array of
  95. * [`state()`](api/animations/state) and `transition()` declarations.
  96. *
  97. * @return An object that encapsulates the trigger data.
  98. *
  99. * @usageNotes
  100. * Define an animation trigger in the `animations` section of `@Component` metadata.
  101. * In the template, reference the trigger by name and bind it to a trigger expression that
  102. * evaluates to a defined animation state, using the following format:
  103. *
  104. * `[@triggerName]="expression"`
  105. *
  106. * Animation trigger bindings convert all values to strings, and then match the
  107. * previous and current values against any linked transitions.
  108. * Booleans can be specified as `1` or `true` and `0` or `false`.
  109. *
  110. * ### Usage Example
  111. *
  112. * The following example creates an animation trigger reference based on the provided
  113. * name value.
  114. * The provided animation value is expected to be an array consisting of state and
  115. * transition declarations.
  116. *
  117. * ```ts
  118. * @Component({
  119. * selector: "my-component",
  120. * templateUrl: "my-component-tpl.html",
  121. * animations: [
  122. * trigger("myAnimationTrigger", [
  123. * state(...),
  124. * state(...),
  125. * transition(...),
  126. * transition(...)
  127. * ])
  128. * ]
  129. * })
  130. * class MyComponent {
  131. * myStatusExp = "something";
  132. * }
  133. * ```
  134. *
  135. * The template associated with this component makes use of the defined trigger
  136. * by binding to an element within its template code.
  137. *
  138. * ```html
  139. * <!-- somewhere inside of my-component-tpl.html -->
  140. * <div [@myAnimationTrigger]="myStatusExp">...</div>
  141. * ```
  142. *
  143. * ### Using an inline function
  144. * The `transition` animation method also supports reading an inline function which can decide
  145. * if its associated animation should be run.
  146. *
  147. * ```ts
  148. * // this method is run each time the `myAnimationTrigger` trigger value changes.
  149. * function myInlineMatcherFn(fromState: string, toState: string, element: any, params: {[key:
  150. string]: any}): boolean {
  151. * // notice that `element` and `params` are also available here
  152. * return toState == 'yes-please-animate';
  153. * }
  154. *
  155. * @Component({
  156. * selector: 'my-component',
  157. * templateUrl: 'my-component-tpl.html',
  158. * animations: [
  159. * trigger('myAnimationTrigger', [
  160. * transition(myInlineMatcherFn, [
  161. * // the animation sequence code
  162. * ]),
  163. * ])
  164. * ]
  165. * })
  166. * class MyComponent {
  167. * myStatusExp = "yes-please-animate";
  168. * }
  169. * ```
  170. *
  171. * ### Disabling Animations
  172. * When true, the special animation control binding `@.disabled` binding prevents
  173. * all animations from rendering.
  174. * Place the `@.disabled` binding on an element to disable
  175. * animations on the element itself, as well as any inner animation triggers
  176. * within the element.
  177. *
  178. * The following example shows how to use this feature:
  179. *
  180. * ```angular-ts
  181. * @Component({
  182. * selector: 'my-component',
  183. * template: `
  184. * <div [@.disabled]="isDisabled">
  185. * <div [@childAnimation]="exp"></div>
  186. * </div>
  187. * `,
  188. * animations: [
  189. * trigger("childAnimation", [
  190. * // ...
  191. * ])
  192. * ]
  193. * })
  194. * class MyComponent {
  195. * isDisabled = true;
  196. * exp = '...';
  197. * }
  198. * ```
  199. *
  200. * When `@.disabled` is true, it prevents the `@childAnimation` trigger from animating,
  201. * along with any inner animations.
  202. *
  203. * ### Disable animations application-wide
  204. * When an area of the template is set to have animations disabled,
  205. * **all** inner components have their animations disabled as well.
  206. * This means that you can disable all animations for an app
  207. * by placing a host binding set on `@.disabled` on the topmost Angular component.
  208. *
  209. * ```ts
  210. * import {Component, HostBinding} from '@angular/core';
  211. *
  212. * @Component({
  213. * selector: 'app-component',
  214. * templateUrl: 'app.component.html',
  215. * })
  216. * class AppComponent {
  217. * @HostBinding('@.disabled')
  218. * public animationsDisabled = true;
  219. * }
  220. * ```
  221. *
  222. * ### Overriding disablement of inner animations
  223. * Despite inner animations being disabled, a parent animation can `query()`
  224. * for inner elements located in disabled areas of the template and still animate
  225. * them if needed. This is also the case for when a sub animation is
  226. * queried by a parent and then later animated using `animateChild()`.
  227. *
  228. * ### Detecting when an animation is disabled
  229. * If a region of the DOM (or the entire application) has its animations disabled, the animation
  230. * trigger callbacks still fire, but for zero seconds. When the callback fires, it provides
  231. * an instance of an `AnimationEvent`. If animations are disabled,
  232. * the `.disabled` flag on the event is true.
  233. *
  234. * @publicApi
  235. */
  236. function trigger(name, definitions) {
  237. return { type: AnimationMetadataType.Trigger, name, definitions, options: {} };
  238. }
  239. /**
  240. * Defines an animation step that combines styling information with timing information.
  241. *
  242. * @param timings Sets `AnimateTimings` for the parent animation.
  243. * A string in the format "duration [delay] [easing]".
  244. * - Duration and delay are expressed as a number and optional time unit,
  245. * such as "1s" or "10ms" for one second and 10 milliseconds, respectively.
  246. * The default unit is milliseconds.
  247. * - The easing value controls how the animation accelerates and decelerates
  248. * during its runtime. Value is one of `ease`, `ease-in`, `ease-out`,
  249. * `ease-in-out`, or a `cubic-bezier()` function call.
  250. * If not supplied, no easing is applied.
  251. *
  252. * For example, the string "1s 100ms ease-out" specifies a duration of
  253. * 1000 milliseconds, and delay of 100 ms, and the "ease-out" easing style,
  254. * which decelerates near the end of the duration.
  255. * @param styles Sets AnimationStyles for the parent animation.
  256. * A function call to either `style()` or `keyframes()`
  257. * that returns a collection of CSS style entries to be applied to the parent animation.
  258. * When null, uses the styles from the destination state.
  259. * This is useful when describing an animation step that will complete an animation;
  260. * see "Animating to the final state" in `transitions()`.
  261. * @returns An object that encapsulates the animation step.
  262. *
  263. * @usageNotes
  264. * Call within an animation `sequence()`, {@link /api/animations/group group()}, or
  265. * `transition()` call to specify an animation step
  266. * that applies given style data to the parent animation for a given amount of time.
  267. *
  268. * ### Syntax Examples
  269. * **Timing examples**
  270. *
  271. * The following examples show various `timings` specifications.
  272. * - `animate(500)` : Duration is 500 milliseconds.
  273. * - `animate("1s")` : Duration is 1000 milliseconds.
  274. * - `animate("100ms 0.5s")` : Duration is 100 milliseconds, delay is 500 milliseconds.
  275. * - `animate("5s ease-in")` : Duration is 5000 milliseconds, easing in.
  276. * - `animate("5s 10ms cubic-bezier(.17,.67,.88,.1)")` : Duration is 5000 milliseconds, delay is 10
  277. * milliseconds, easing according to a bezier curve.
  278. *
  279. * **Style examples**
  280. *
  281. * The following example calls `style()` to set a single CSS style.
  282. * ```ts
  283. * animate(500, style({ background: "red" }))
  284. * ```
  285. * The following example calls `keyframes()` to set a CSS style
  286. * to different values for successive keyframes.
  287. * ```ts
  288. * animate(500, keyframes(
  289. * [
  290. * style({ background: "blue" }),
  291. * style({ background: "red" })
  292. * ])
  293. * ```
  294. *
  295. * @publicApi
  296. */
  297. function animate(timings, styles = null) {
  298. return { type: AnimationMetadataType.Animate, styles, timings };
  299. }
  300. /**
  301. * @description Defines a list of animation steps to be run in parallel.
  302. *
  303. * @param steps An array of animation step objects.
  304. * - When steps are defined by `style()` or `animate()`
  305. * function calls, each call within the group is executed instantly.
  306. * - To specify offset styles to be applied at a later time, define steps with
  307. * `keyframes()`, or use `animate()` calls with a delay value.
  308. * For example:
  309. *
  310. * ```ts
  311. * group([
  312. * animate("1s", style({ background: "black" })),
  313. * animate("2s", style({ color: "white" }))
  314. * ])
  315. * ```
  316. *
  317. * @param options An options object containing a delay and
  318. * developer-defined parameters that provide styling defaults and
  319. * can be overridden on invocation.
  320. *
  321. * @return An object that encapsulates the group data.
  322. *
  323. * @usageNotes
  324. * Grouped animations are useful when a series of styles must be
  325. * animated at different starting times and closed off at different ending times.
  326. *
  327. * When called within a `sequence()` or a
  328. * `transition()` call, does not continue to the next
  329. * instruction until all of the inner animation steps have completed.
  330. *
  331. * @publicApi
  332. */
  333. function group(steps, options = null) {
  334. return { type: AnimationMetadataType.Group, steps, options };
  335. }
  336. /**
  337. * Defines a list of animation steps to be run sequentially, one by one.
  338. *
  339. * @param steps An array of animation step objects.
  340. * - Steps defined by `style()` calls apply the styling data immediately.
  341. * - Steps defined by `animate()` calls apply the styling data over time
  342. * as specified by the timing data.
  343. *
  344. * ```ts
  345. * sequence([
  346. * style({ opacity: 0 }),
  347. * animate("1s", style({ opacity: 1 }))
  348. * ])
  349. * ```
  350. *
  351. * @param options An options object containing a delay and
  352. * developer-defined parameters that provide styling defaults and
  353. * can be overridden on invocation.
  354. *
  355. * @return An object that encapsulates the sequence data.
  356. *
  357. * @usageNotes
  358. * When you pass an array of steps to a
  359. * `transition()` call, the steps run sequentially by default.
  360. * Compare this to the {@link /api/animations/group group()} call, which runs animation steps in
  361. *parallel.
  362. *
  363. * When a sequence is used within a {@link /api/animations/group group()} or a `transition()` call,
  364. * execution continues to the next instruction only after each of the inner animation
  365. * steps have completed.
  366. *
  367. * @publicApi
  368. **/
  369. function sequence(steps, options = null) {
  370. return { type: AnimationMetadataType.Sequence, steps, options };
  371. }
  372. /**
  373. * Declares a key/value object containing CSS properties/styles that
  374. * can then be used for an animation [`state`](api/animations/state), within an animation
  375. *`sequence`, or as styling data for calls to `animate()` and `keyframes()`.
  376. *
  377. * @param tokens A set of CSS styles or HTML styles associated with an animation state.
  378. * The value can be any of the following:
  379. * - A key-value style pair associating a CSS property with a value.
  380. * - An array of key-value style pairs.
  381. * - An asterisk (*), to use auto-styling, where styles are derived from the element
  382. * being animated and applied to the animation when it starts.
  383. *
  384. * Auto-styling can be used to define a state that depends on layout or other
  385. * environmental factors.
  386. *
  387. * @return An object that encapsulates the style data.
  388. *
  389. * @usageNotes
  390. * The following examples create animation styles that collect a set of
  391. * CSS property values:
  392. *
  393. * ```ts
  394. * // string values for CSS properties
  395. * style({ background: "red", color: "blue" })
  396. *
  397. * // numerical pixel values
  398. * style({ width: 100, height: 0 })
  399. * ```
  400. *
  401. * The following example uses auto-styling to allow an element to animate from
  402. * a height of 0 up to its full height:
  403. *
  404. * ```ts
  405. * style({ height: 0 }),
  406. * animate("1s", style({ height: "*" }))
  407. * ```
  408. *
  409. * @publicApi
  410. **/
  411. function style(tokens) {
  412. return { type: AnimationMetadataType.Style, styles: tokens, offset: null };
  413. }
  414. /**
  415. * Declares an animation state within a trigger attached to an element.
  416. *
  417. * @param name One or more names for the defined state in a comma-separated string.
  418. * The following reserved state names can be supplied to define a style for specific use
  419. * cases:
  420. *
  421. * - `void` You can associate styles with this name to be used when
  422. * the element is detached from the application. For example, when an `ngIf` evaluates
  423. * to false, the state of the associated element is void.
  424. * - `*` (asterisk) Indicates the default state. You can associate styles with this name
  425. * to be used as the fallback when the state that is being animated is not declared
  426. * within the trigger.
  427. *
  428. * @param styles A set of CSS styles associated with this state, created using the
  429. * `style()` function.
  430. * This set of styles persists on the element once the state has been reached.
  431. * @param options Parameters that can be passed to the state when it is invoked.
  432. * 0 or more key-value pairs.
  433. * @return An object that encapsulates the new state data.
  434. *
  435. * @usageNotes
  436. * Use the `trigger()` function to register states to an animation trigger.
  437. * Use the `transition()` function to animate between states.
  438. * When a state is active within a component, its associated styles persist on the element,
  439. * even when the animation ends.
  440. *
  441. * @publicApi
  442. **/
  443. function state(name, styles, options) {
  444. return { type: AnimationMetadataType.State, name, styles, options };
  445. }
  446. /**
  447. * Defines a set of animation styles, associating each style with an optional `offset` value.
  448. *
  449. * @param steps A set of animation styles with optional offset data.
  450. * The optional `offset` value for a style specifies a percentage of the total animation
  451. * time at which that style is applied.
  452. * @returns An object that encapsulates the keyframes data.
  453. *
  454. * @usageNotes
  455. * Use with the `animate()` call. Instead of applying animations
  456. * from the current state
  457. * to the destination state, keyframes describe how each style entry is applied and at what point
  458. * within the animation arc.
  459. * Compare [CSS Keyframe Animations](https://www.w3schools.com/css/css3_animations.asp).
  460. *
  461. * ### Usage
  462. *
  463. * In the following example, the offset values describe
  464. * when each `backgroundColor` value is applied. The color is red at the start, and changes to
  465. * blue when 20% of the total time has elapsed.
  466. *
  467. * ```ts
  468. * // the provided offset values
  469. * animate("5s", keyframes([
  470. * style({ backgroundColor: "red", offset: 0 }),
  471. * style({ backgroundColor: "blue", offset: 0.2 }),
  472. * style({ backgroundColor: "orange", offset: 0.3 }),
  473. * style({ backgroundColor: "black", offset: 1 })
  474. * ]))
  475. * ```
  476. *
  477. * If there are no `offset` values specified in the style entries, the offsets
  478. * are calculated automatically.
  479. *
  480. * ```ts
  481. * animate("5s", keyframes([
  482. * style({ backgroundColor: "red" }) // offset = 0
  483. * style({ backgroundColor: "blue" }) // offset = 0.33
  484. * style({ backgroundColor: "orange" }) // offset = 0.66
  485. * style({ backgroundColor: "black" }) // offset = 1
  486. * ]))
  487. *```
  488. * @publicApi
  489. */
  490. function keyframes(steps) {
  491. return { type: AnimationMetadataType.Keyframes, steps };
  492. }
  493. /**
  494. * Declares an animation transition which is played when a certain specified condition is met.
  495. *
  496. * @param stateChangeExpr A string with a specific format or a function that specifies when the
  497. * animation transition should occur (see [State Change Expression](#state-change-expression)).
  498. *
  499. * @param steps One or more animation objects that represent the animation's instructions.
  500. *
  501. * @param options An options object that can be used to specify a delay for the animation or provide
  502. * custom parameters for it.
  503. *
  504. * @returns An object that encapsulates the transition data.
  505. *
  506. * @usageNotes
  507. *
  508. * ### State Change Expression
  509. *
  510. * The State Change Expression instructs Angular when to run the transition's animations, it can
  511. *either be
  512. * - a string with a specific syntax
  513. * - or a function that compares the previous and current state (value of the expression bound to
  514. * the element's trigger) and returns `true` if the transition should occur or `false` otherwise
  515. *
  516. * The string format can be:
  517. * - `fromState => toState`, which indicates that the transition's animations should occur then the
  518. * expression bound to the trigger's element goes from `fromState` to `toState`
  519. *
  520. * _Example:_
  521. * ```ts
  522. * transition('open => closed', animate('.5s ease-out', style({ height: 0 }) ))
  523. * ```
  524. *
  525. * - `fromState <=> toState`, which indicates that the transition's animations should occur then
  526. * the expression bound to the trigger's element goes from `fromState` to `toState` or vice versa
  527. *
  528. * _Example:_
  529. * ```ts
  530. * transition('enabled <=> disabled', animate('1s cubic-bezier(0.8,0.3,0,1)'))
  531. * ```
  532. *
  533. * - `:enter`/`:leave`, which indicates that the transition's animations should occur when the
  534. * element enters or exists the DOM
  535. *
  536. * _Example:_
  537. * ```ts
  538. * transition(':enter', [
  539. * style({ opacity: 0 }),
  540. * animate('500ms', style({ opacity: 1 }))
  541. * ])
  542. * ```
  543. *
  544. * - `:increment`/`:decrement`, which indicates that the transition's animations should occur when
  545. * the numerical expression bound to the trigger's element has increased in value or decreased
  546. *
  547. * _Example:_
  548. * ```ts
  549. * transition(':increment', query('@counter', animateChild()))
  550. * ```
  551. *
  552. * - a sequence of any of the above divided by commas, which indicates that transition's animations
  553. * should occur whenever one of the state change expressions matches
  554. *
  555. * _Example:_
  556. * ```ts
  557. * transition(':increment, * => enabled, :enter', animate('1s ease', keyframes([
  558. * style({ transform: 'scale(1)', offset: 0}),
  559. * style({ transform: 'scale(1.1)', offset: 0.7}),
  560. * style({ transform: 'scale(1)', offset: 1})
  561. * ]))),
  562. * ```
  563. *
  564. * Also note that in such context:
  565. * - `void` can be used to indicate the absence of the element
  566. * - asterisks can be used as wildcards that match any state
  567. * - (as a consequence of the above, `void => *` is equivalent to `:enter` and `* => void` is
  568. * equivalent to `:leave`)
  569. * - `true` and `false` also match expression values of `1` and `0` respectively (but do not match
  570. * _truthy_ and _falsy_ values)
  571. *
  572. * <div class="docs-alert docs-alert-helpful">
  573. *
  574. * Be careful about entering end leaving elements as their transitions present a common
  575. * pitfall for developers.
  576. *
  577. * Note that when an element with a trigger enters the DOM its `:enter` transition always
  578. * gets executed, but its `:leave` transition will not be executed if the element is removed
  579. * alongside its parent (as it will be removed "without warning" before its transition has
  580. * a chance to be executed, the only way that such transition can occur is if the element
  581. * is exiting the DOM on its own).
  582. *
  583. *
  584. * </div>
  585. *
  586. * ### Animating to a Final State
  587. *
  588. * If the final step in a transition is a call to `animate()` that uses a timing value
  589. * with no `style` data, that step is automatically considered the final animation arc,
  590. * for the element to reach the final state, in such case Angular automatically adds or removes
  591. * CSS styles to ensure that the element is in the correct final state.
  592. *
  593. *
  594. * ### Usage Examples
  595. *
  596. * - Transition animations applied based on
  597. * the trigger's expression value
  598. *
  599. * ```html
  600. * <div [@myAnimationTrigger]="myStatusExp">
  601. * ...
  602. * </div>
  603. * ```
  604. *
  605. * ```ts
  606. * trigger("myAnimationTrigger", [
  607. * ..., // states
  608. * transition("on => off, open => closed", animate(500)),
  609. * transition("* <=> error", query('.indicator', animateChild()))
  610. * ])
  611. * ```
  612. *
  613. * - Transition animations applied based on custom logic dependent
  614. * on the trigger's expression value and provided parameters
  615. *
  616. * ```html
  617. * <div [@myAnimationTrigger]="{
  618. * value: stepName,
  619. * params: { target: currentTarget }
  620. * }">
  621. * ...
  622. * </div>
  623. * ```
  624. *
  625. * ```ts
  626. * trigger("myAnimationTrigger", [
  627. * ..., // states
  628. * transition(
  629. * (fromState, toState, _element, params) =>
  630. * ['firststep', 'laststep'].includes(fromState.toLowerCase())
  631. * && toState === params?.['target'],
  632. * animate('1s')
  633. * )
  634. * ])
  635. * ```
  636. *
  637. * @publicApi
  638. **/
  639. function transition(stateChangeExpr, steps, options = null) {
  640. return { type: AnimationMetadataType.Transition, expr: stateChangeExpr, animation: steps, options };
  641. }
  642. /**
  643. * Produces a reusable animation that can be invoked in another animation or sequence,
  644. * by calling the `useAnimation()` function.
  645. *
  646. * @param steps One or more animation objects, as returned by the `animate()`
  647. * or `sequence()` function, that form a transformation from one state to another.
  648. * A sequence is used by default when you pass an array.
  649. * @param options An options object that can contain a delay value for the start of the
  650. * animation, and additional developer-defined parameters.
  651. * Provided values for additional parameters are used as defaults,
  652. * and override values can be passed to the caller on invocation.
  653. * @returns An object that encapsulates the animation data.
  654. *
  655. * @usageNotes
  656. * The following example defines a reusable animation, providing some default parameter
  657. * values.
  658. *
  659. * ```ts
  660. * var fadeAnimation = animation([
  661. * style({ opacity: '{{ start }}' }),
  662. * animate('{{ time }}',
  663. * style({ opacity: '{{ end }}'}))
  664. * ],
  665. * { params: { time: '1000ms', start: 0, end: 1 }});
  666. * ```
  667. *
  668. * The following invokes the defined animation with a call to `useAnimation()`,
  669. * passing in override parameter values.
  670. *
  671. * ```js
  672. * useAnimation(fadeAnimation, {
  673. * params: {
  674. * time: '2s',
  675. * start: 1,
  676. * end: 0
  677. * }
  678. * })
  679. * ```
  680. *
  681. * If any of the passed-in parameter values are missing from this call,
  682. * the default values are used. If one or more parameter values are missing before a step is
  683. * animated, `useAnimation()` throws an error.
  684. *
  685. * @publicApi
  686. */
  687. function animation(steps, options = null) {
  688. return { type: AnimationMetadataType.Reference, animation: steps, options };
  689. }
  690. /**
  691. * Executes a queried inner animation element within an animation sequence.
  692. *
  693. * @param options An options object that can contain a delay value for the start of the
  694. * animation, and additional override values for developer-defined parameters.
  695. * @return An object that encapsulates the child animation data.
  696. *
  697. * @usageNotes
  698. * Each time an animation is triggered in Angular, the parent animation
  699. * has priority and any child animations are blocked. In order
  700. * for a child animation to run, the parent animation must query each of the elements
  701. * containing child animations, and run them using this function.
  702. *
  703. * Note that this feature is designed to be used with `query()` and it will only work
  704. * with animations that are assigned using the Angular animation library. CSS keyframes
  705. * and transitions are not handled by this API.
  706. *
  707. * @publicApi
  708. */
  709. function animateChild(options = null) {
  710. return { type: AnimationMetadataType.AnimateChild, options };
  711. }
  712. /**
  713. * Starts a reusable animation that is created using the `animation()` function.
  714. *
  715. * @param animation The reusable animation to start.
  716. * @param options An options object that can contain a delay value for the start of
  717. * the animation, and additional override values for developer-defined parameters.
  718. * @return An object that contains the animation parameters.
  719. *
  720. * @publicApi
  721. */
  722. function useAnimation(animation, options = null) {
  723. return { type: AnimationMetadataType.AnimateRef, animation, options };
  724. }
  725. /**
  726. * Finds one or more inner elements within the current element that is
  727. * being animated within a sequence. Use with `animate()`.
  728. *
  729. * @param selector The element to query, or a set of elements that contain Angular-specific
  730. * characteristics, specified with one or more of the following tokens.
  731. * - `query(":enter")` or `query(":leave")` : Query for newly inserted/removed elements (not
  732. * all elements can be queried via these tokens, see
  733. * [Entering and Leaving Elements](#entering-and-leaving-elements))
  734. * - `query(":animating")` : Query all currently animating elements.
  735. * - `query("@triggerName")` : Query elements that contain an animation trigger.
  736. * - `query("@*")` : Query all elements that contain an animation triggers.
  737. * - `query(":self")` : Include the current element into the animation sequence.
  738. *
  739. * @param animation One or more animation steps to apply to the queried element or elements.
  740. * An array is treated as an animation sequence.
  741. * @param options An options object. Use the 'limit' field to limit the total number of
  742. * items to collect.
  743. * @return An object that encapsulates the query data.
  744. *
  745. * @usageNotes
  746. *
  747. * ### Multiple Tokens
  748. *
  749. * Tokens can be merged into a combined query selector string. For example:
  750. *
  751. * ```ts
  752. * query(':self, .record:enter, .record:leave, @subTrigger', [...])
  753. * ```
  754. *
  755. * The `query()` function collects multiple elements and works internally by using
  756. * `element.querySelectorAll`. Use the `limit` field of an options object to limit
  757. * the total number of items to be collected. For example:
  758. *
  759. * ```js
  760. * query('div', [
  761. * animate(...),
  762. * animate(...)
  763. * ], { limit: 1 })
  764. * ```
  765. *
  766. * By default, throws an error when zero items are found. Set the
  767. * `optional` flag to ignore this error. For example:
  768. *
  769. * ```js
  770. * query('.some-element-that-may-not-be-there', [
  771. * animate(...),
  772. * animate(...)
  773. * ], { optional: true })
  774. * ```
  775. *
  776. * ### Entering and Leaving Elements
  777. *
  778. * Not all elements can be queried via the `:enter` and `:leave` tokens, the only ones
  779. * that can are those that Angular assumes can enter/leave based on their own logic
  780. * (if their insertion/removal is simply a consequence of that of their parent they
  781. * should be queried via a different token in their parent's `:enter`/`:leave` transitions).
  782. *
  783. * The only elements Angular assumes can enter/leave based on their own logic (thus the only
  784. * ones that can be queried via the `:enter` and `:leave` tokens) are:
  785. * - Those inserted dynamically (via `ViewContainerRef`)
  786. * - Those that have a structural directive (which, under the hood, are a subset of the above ones)
  787. *
  788. * <div class="docs-alert docs-alert-helpful">
  789. *
  790. * Note that elements will be successfully queried via `:enter`/`:leave` even if their
  791. * insertion/removal is not done manually via `ViewContainerRef`or caused by their structural
  792. * directive (e.g. they enter/exit alongside their parent).
  793. *
  794. * </div>
  795. *
  796. * <div class="docs-alert docs-alert-important">
  797. *
  798. * There is an exception to what previously mentioned, besides elements entering/leaving based on
  799. * their own logic, elements with an animation trigger can always be queried via `:leave` when
  800. * their parent is also leaving.
  801. *
  802. * </div>
  803. *
  804. * ### Usage Example
  805. *
  806. * The following example queries for inner elements and animates them
  807. * individually using `animate()`.
  808. *
  809. * ```angular-ts
  810. * @Component({
  811. * selector: 'inner',
  812. * template: `
  813. * <div [@queryAnimation]="exp">
  814. * <h1>Title</h1>
  815. * <div class="content">
  816. * Blah blah blah
  817. * </div>
  818. * </div>
  819. * `,
  820. * animations: [
  821. * trigger('queryAnimation', [
  822. * transition('* => goAnimate', [
  823. * // hide the inner elements
  824. * query('h1', style({ opacity: 0 })),
  825. * query('.content', style({ opacity: 0 })),
  826. *
  827. * // animate the inner elements in, one by one
  828. * query('h1', animate(1000, style({ opacity: 1 }))),
  829. * query('.content', animate(1000, style({ opacity: 1 }))),
  830. * ])
  831. * ])
  832. * ]
  833. * })
  834. * class Cmp {
  835. * exp = '';
  836. *
  837. * goAnimate() {
  838. * this.exp = 'goAnimate';
  839. * }
  840. * }
  841. * ```
  842. *
  843. * @publicApi
  844. */
  845. function query(selector, animation, options = null) {
  846. return { type: AnimationMetadataType.Query, selector, animation, options };
  847. }
  848. /**
  849. * Use within an animation `query()` call to issue a timing gap after
  850. * each queried item is animated.
  851. *
  852. * @param timings A delay value.
  853. * @param animation One ore more animation steps.
  854. * @returns An object that encapsulates the stagger data.
  855. *
  856. * @usageNotes
  857. * In the following example, a container element wraps a list of items stamped out
  858. * by an `ngFor`. The container element contains an animation trigger that will later be set
  859. * to query for each of the inner items.
  860. *
  861. * Each time items are added, the opacity fade-in animation runs,
  862. * and each removed item is faded out.
  863. * When either of these animations occur, the stagger effect is
  864. * applied after each item's animation is started.
  865. *
  866. * ```html
  867. * <!-- list.component.html -->
  868. * <button (click)="toggle()">Show / Hide Items</button>
  869. * <hr />
  870. * <div [@listAnimation]="items.length">
  871. * <div *ngFor="let item of items">
  872. * {{ item }}
  873. * </div>
  874. * </div>
  875. * ```
  876. *
  877. * Here is the component code:
  878. *
  879. * ```ts
  880. * import {trigger, transition, style, animate, query, stagger} from '@angular/animations';
  881. * @Component({
  882. * templateUrl: 'list.component.html',
  883. * animations: [
  884. * trigger('listAnimation', [
  885. * ...
  886. * ])
  887. * ]
  888. * })
  889. * class ListComponent {
  890. * items = [];
  891. *
  892. * showItems() {
  893. * this.items = [0,1,2,3,4];
  894. * }
  895. *
  896. * hideItems() {
  897. * this.items = [];
  898. * }
  899. *
  900. * toggle() {
  901. * this.items.length ? this.hideItems() : this.showItems();
  902. * }
  903. * }
  904. * ```
  905. *
  906. * Here is the animation trigger code:
  907. *
  908. * ```ts
  909. * trigger('listAnimation', [
  910. * transition('* => *', [ // each time the binding value changes
  911. * query(':leave', [
  912. * stagger(100, [
  913. * animate('0.5s', style({ opacity: 0 }))
  914. * ])
  915. * ]),
  916. * query(':enter', [
  917. * style({ opacity: 0 }),
  918. * stagger(100, [
  919. * animate('0.5s', style({ opacity: 1 }))
  920. * ])
  921. * ])
  922. * ])
  923. * ])
  924. * ```
  925. *
  926. * @publicApi
  927. */
  928. function stagger(timings, animation) {
  929. return { type: AnimationMetadataType.Stagger, timings, animation };
  930. }
  931. /**
  932. * An empty programmatic controller for reusable animations.
  933. * Used internally when animations are disabled, to avoid
  934. * checking for the null case when an animation player is expected.
  935. *
  936. * @see {@link animate}
  937. * @see {@link AnimationPlayer}
  938. *
  939. * @publicApi
  940. */
  941. class NoopAnimationPlayer {
  942. _onDoneFns = [];
  943. _onStartFns = [];
  944. _onDestroyFns = [];
  945. _originalOnDoneFns = [];
  946. _originalOnStartFns = [];
  947. _started = false;
  948. _destroyed = false;
  949. _finished = false;
  950. _position = 0;
  951. parentPlayer = null;
  952. totalTime;
  953. constructor(duration = 0, delay = 0) {
  954. this.totalTime = duration + delay;
  955. }
  956. _onFinish() {
  957. if (!this._finished) {
  958. this._finished = true;
  959. this._onDoneFns.forEach((fn) => fn());
  960. this._onDoneFns = [];
  961. }
  962. }
  963. onStart(fn) {
  964. this._originalOnStartFns.push(fn);
  965. this._onStartFns.push(fn);
  966. }
  967. onDone(fn) {
  968. this._originalOnDoneFns.push(fn);
  969. this._onDoneFns.push(fn);
  970. }
  971. onDestroy(fn) {
  972. this._onDestroyFns.push(fn);
  973. }
  974. hasStarted() {
  975. return this._started;
  976. }
  977. init() { }
  978. play() {
  979. if (!this.hasStarted()) {
  980. this._onStart();
  981. this.triggerMicrotask();
  982. }
  983. this._started = true;
  984. }
  985. /** @internal */
  986. triggerMicrotask() {
  987. queueMicrotask(() => this._onFinish());
  988. }
  989. _onStart() {
  990. this._onStartFns.forEach((fn) => fn());
  991. this._onStartFns = [];
  992. }
  993. pause() { }
  994. restart() { }
  995. finish() {
  996. this._onFinish();
  997. }
  998. destroy() {
  999. if (!this._destroyed) {
  1000. this._destroyed = true;
  1001. if (!this.hasStarted()) {
  1002. this._onStart();
  1003. }
  1004. this.finish();
  1005. this._onDestroyFns.forEach((fn) => fn());
  1006. this._onDestroyFns = [];
  1007. }
  1008. }
  1009. reset() {
  1010. this._started = false;
  1011. this._finished = false;
  1012. this._onStartFns = this._originalOnStartFns;
  1013. this._onDoneFns = this._originalOnDoneFns;
  1014. }
  1015. setPosition(position) {
  1016. this._position = this.totalTime ? position * this.totalTime : 1;
  1017. }
  1018. getPosition() {
  1019. return this.totalTime ? this._position / this.totalTime : 1;
  1020. }
  1021. /** @internal */
  1022. triggerCallback(phaseName) {
  1023. const methods = phaseName == 'start' ? this._onStartFns : this._onDoneFns;
  1024. methods.forEach((fn) => fn());
  1025. methods.length = 0;
  1026. }
  1027. }
  1028. /**
  1029. * A programmatic controller for a group of reusable animations.
  1030. * Used internally to control animations.
  1031. *
  1032. * @see {@link AnimationPlayer}
  1033. * @see {@link animations/group group}
  1034. *
  1035. */
  1036. class AnimationGroupPlayer {
  1037. _onDoneFns = [];
  1038. _onStartFns = [];
  1039. _finished = false;
  1040. _started = false;
  1041. _destroyed = false;
  1042. _onDestroyFns = [];
  1043. parentPlayer = null;
  1044. totalTime = 0;
  1045. players;
  1046. constructor(_players) {
  1047. this.players = _players;
  1048. let doneCount = 0;
  1049. let destroyCount = 0;
  1050. let startCount = 0;
  1051. const total = this.players.length;
  1052. if (total == 0) {
  1053. queueMicrotask(() => this._onFinish());
  1054. }
  1055. else {
  1056. this.players.forEach((player) => {
  1057. player.onDone(() => {
  1058. if (++doneCount == total) {
  1059. this._onFinish();
  1060. }
  1061. });
  1062. player.onDestroy(() => {
  1063. if (++destroyCount == total) {
  1064. this._onDestroy();
  1065. }
  1066. });
  1067. player.onStart(() => {
  1068. if (++startCount == total) {
  1069. this._onStart();
  1070. }
  1071. });
  1072. });
  1073. }
  1074. this.totalTime = this.players.reduce((time, player) => Math.max(time, player.totalTime), 0);
  1075. }
  1076. _onFinish() {
  1077. if (!this._finished) {
  1078. this._finished = true;
  1079. this._onDoneFns.forEach((fn) => fn());
  1080. this._onDoneFns = [];
  1081. }
  1082. }
  1083. init() {
  1084. this.players.forEach((player) => player.init());
  1085. }
  1086. onStart(fn) {
  1087. this._onStartFns.push(fn);
  1088. }
  1089. _onStart() {
  1090. if (!this.hasStarted()) {
  1091. this._started = true;
  1092. this._onStartFns.forEach((fn) => fn());
  1093. this._onStartFns = [];
  1094. }
  1095. }
  1096. onDone(fn) {
  1097. this._onDoneFns.push(fn);
  1098. }
  1099. onDestroy(fn) {
  1100. this._onDestroyFns.push(fn);
  1101. }
  1102. hasStarted() {
  1103. return this._started;
  1104. }
  1105. play() {
  1106. if (!this.parentPlayer) {
  1107. this.init();
  1108. }
  1109. this._onStart();
  1110. this.players.forEach((player) => player.play());
  1111. }
  1112. pause() {
  1113. this.players.forEach((player) => player.pause());
  1114. }
  1115. restart() {
  1116. this.players.forEach((player) => player.restart());
  1117. }
  1118. finish() {
  1119. this._onFinish();
  1120. this.players.forEach((player) => player.finish());
  1121. }
  1122. destroy() {
  1123. this._onDestroy();
  1124. }
  1125. _onDestroy() {
  1126. if (!this._destroyed) {
  1127. this._destroyed = true;
  1128. this._onFinish();
  1129. this.players.forEach((player) => player.destroy());
  1130. this._onDestroyFns.forEach((fn) => fn());
  1131. this._onDestroyFns = [];
  1132. }
  1133. }
  1134. reset() {
  1135. this.players.forEach((player) => player.reset());
  1136. this._destroyed = false;
  1137. this._finished = false;
  1138. this._started = false;
  1139. }
  1140. setPosition(p) {
  1141. const timeAtPosition = p * this.totalTime;
  1142. this.players.forEach((player) => {
  1143. const position = player.totalTime ? Math.min(1, timeAtPosition / player.totalTime) : 1;
  1144. player.setPosition(position);
  1145. });
  1146. }
  1147. getPosition() {
  1148. const longestPlayer = this.players.reduce((longestSoFar, player) => {
  1149. const newPlayerIsLongest = longestSoFar === null || player.totalTime > longestSoFar.totalTime;
  1150. return newPlayerIsLongest ? player : longestSoFar;
  1151. }, null);
  1152. return longestPlayer != null ? longestPlayer.getPosition() : 0;
  1153. }
  1154. beforeDestroy() {
  1155. this.players.forEach((player) => {
  1156. if (player.beforeDestroy) {
  1157. player.beforeDestroy();
  1158. }
  1159. });
  1160. }
  1161. /** @internal */
  1162. triggerCallback(phaseName) {
  1163. const methods = phaseName == 'start' ? this._onStartFns : this._onDoneFns;
  1164. methods.forEach((fn) => fn());
  1165. methods.length = 0;
  1166. }
  1167. }
  1168. const ɵPRE_STYLE = '!';
  1169. export { AUTO_STYLE, AnimationGroupPlayer, AnimationMetadataType, NoopAnimationPlayer, animate, animateChild, animation, group, keyframes, query, sequence, stagger, state, style, transition, trigger, useAnimation, ɵPRE_STYLE };
  1170. //# sourceMappingURL=private_export-faY_wCkZ.mjs.map