index.d.ts 53 KB

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