From ab606c0dfd5ad1edbdf702344480581f72f7334e Mon Sep 17 00:00:00 2001 From: Sean Perkins Date: Tue, 7 Mar 2023 14:58:47 -0500 Subject: [PATCH 1/4] docs(animations): add type interfaces --- docs/utilities/animations.md | 244 ++++++++++++++++++ .../version-v6/utilities/animations.md | 244 ++++++++++++++++++ 2 files changed, 488 insertions(+) diff --git a/docs/utilities/animations.md b/docs/utilities/animations.md index 10da9763b82..0d697c32f14 100644 --- a/docs/utilities/animations.md +++ b/docs/utilities/animations.md @@ -1560,6 +1560,246 @@ Due to a bug in Safari versions 9-11, stepping through animations via `progressS ## Interfaces +### AnimationBuilder + +```tsx +type AnimationBuilder = (baseEl: any, opts?: any) => Animation; +``` + +:::note + +`opts` are additional options that are specific to the custom animation. For example, the sheet modal enter animation includes information for the current breakpoint. + +::: + +### Animation + +```tsx +interface Animation { + parentAnimation?: Animation; + elements: HTMLElement[]; + childAnimations: Animation[]; + id: string | undefined; + + /** + * Play the animation + * + * If the `sync` options is `true`, the animation will play synchronously. This + * is the equivalent of running the animation + * with a duration of 0ms. + */ + play(opts?: AnimationPlayOptions): Promise; + + /** + * Pauses the animation + */ + pause(): void; + + /** + * Stop the animation and reset + * all elements to their initial state + */ + stop(): void; + + /** + * Destroy the animation and all child animations. + */ + destroy(clearStyleSheets?: boolean): void; + + progressStart(forceLinearEasing?: boolean, step?: number): Animation; + progressStep(step: number): Animation; + progressEnd(playTo: 0 | 1 | undefined, step: number, dur?: number): Animation; + + from(property: string, value: any): Animation; + to(property: string, value: any): Animation; + fromTo(property: string, fromValue: any, toValue: any): Animation; + + /** + * Set the keyframes for the animation. + */ + keyframes(keyframes: AnimationKeyFrames): Animation; + + /** + * Group one or more animations together to be controlled by a parent animation. + */ + addAnimation(animationToAdd: Animation | Animation[]): Animation; + + /** + * Add one or more elements to the animation + */ + addElement(el: Element | Element[] | Node | Node[] | NodeList): Animation; + + /** + * Sets the number of times the animation cycle + * should be played before stopping. + */ + iterations(iterations: number): Animation; + + /** + * Sets how the animation applies styles to its + * elements before and after the animation's execution. + */ + fill(fill: AnimationFill | undefined): Animation; + + /** + * Sets whether the animation should play forwards, + * backwards, or alternating back and forth. + */ + direction(direction: AnimationDirection | undefined): Animation; + + /** + * Sets the length of time the animation takes + * to complete one cycle. + */ + duration(duration: number | undefined): Animation; + + /** + * Sets how the animation progresses through the + * duration of each cycle. + */ + easing(easing: string | undefined): Animation; + + /** + * Sets when an animation starts (in milliseconds). + */ + delay(delay: number | undefined): Animation; + + /** + * Get an array of keyframes for the animation. + */ + getKeyframes(): AnimationKeyFrames; + + /** + * Returns the animation's direction. + */ + getDirection(): AnimationDirection; + + /** + * Returns the animation's fill mode. + */ + getFill(): AnimationFill; + + /** + * Gets the animation's delay in milliseconds. + */ + getDelay(): number; + + /** + * Gets the number of iterations the animation will run. + */ + getIterations(): number; + + /** + * Returns the animation's easing. + */ + getEasing(): string; + + /** + * Gets the animation's duration in milliseconds. + */ + getDuration(): number; + + /** + * Returns the raw Web Animations object + * for all elements in an Animation. + * This will return an empty array on + * browsers that do not support + * the Web Animations API. + */ + getWebAnimations(): any[]; + + /** + * Add a function that performs a + * DOM read to be run after the + * animation end + */ + afterAddRead(readFn: () => void): Animation; + + /** + * Add a function that performs a + * DOM write to be run after the + * animation end + */ + afterAddWrite(writeFn: () => void): Animation; + + /** + * Clear CSS inline styles from the animation's + * elements after the animation ends. + */ + afterClearStyles(propertyNames: string[]): Animation; + + /** + * Set CSS inline styles to the animation's + * elements after the animation ends. + */ + afterStyles(styles: { [property: string]: any }): Animation; + + /** + * Add CSS class to the animation's + * elements after the animation ends. + */ + afterAddClass(className: string | string[]): Animation; + + /** + * Remove CSS class from the animation's + * elements after the animation ends. + */ + afterRemoveClass(className: string | string[]): Animation; + + /** + * Add a function that performs a + * DOM read to be run before the + * animation starts + */ + beforeAddRead(readFn: () => void): Animation; + + /** + * Add a function that performs a + * DOM write to be run before the + * animation starts + */ + beforeAddWrite(writeFn: () => void): Animation; + + /** + * Clear CSS inline styles from the animation's + * elements before the animation begins. + */ + beforeClearStyles(propertyNames: string[]): Animation; + + /** + * Set CSS inline styles to the animation's + * elements before the animation begins. + */ + beforeStyles(styles: { [property: string]: any }): Animation; + + /** + * Add a class to the animation's + * elements before the animation starts + */ + beforeAddClass(className: string | string[]): Animation; + + /** + * Remove a class from the animation's + * elements before the animation starts + */ + beforeRemoveClass(className: string | string[]): Animation; + + /** + * Add a callback to be run + * upon the animation ending + */ + onFinish(callback: AnimationLifecycle, opts?: AnimationCallbackOptions): Animation; + + /** + * Returns `true` if the animation is running. + * Returns `false` otherwise. + */ + isRunning(): boolean; +} +``` + +### AnimationCallbackOptions + ```tsx interface AnimationCallbackOptions { /** @@ -1567,7 +1807,11 @@ interface AnimationCallbackOptions { */ oneTimeCallback: boolean; } +``` + +### AnimationPlayOptions +```tsx interface AnimationPlayOptions { /** * If true, the animation will play synchronously. diff --git a/versioned_docs/version-v6/utilities/animations.md b/versioned_docs/version-v6/utilities/animations.md index 10da9763b82..0d697c32f14 100644 --- a/versioned_docs/version-v6/utilities/animations.md +++ b/versioned_docs/version-v6/utilities/animations.md @@ -1560,6 +1560,246 @@ Due to a bug in Safari versions 9-11, stepping through animations via `progressS ## Interfaces +### AnimationBuilder + +```tsx +type AnimationBuilder = (baseEl: any, opts?: any) => Animation; +``` + +:::note + +`opts` are additional options that are specific to the custom animation. For example, the sheet modal enter animation includes information for the current breakpoint. + +::: + +### Animation + +```tsx +interface Animation { + parentAnimation?: Animation; + elements: HTMLElement[]; + childAnimations: Animation[]; + id: string | undefined; + + /** + * Play the animation + * + * If the `sync` options is `true`, the animation will play synchronously. This + * is the equivalent of running the animation + * with a duration of 0ms. + */ + play(opts?: AnimationPlayOptions): Promise; + + /** + * Pauses the animation + */ + pause(): void; + + /** + * Stop the animation and reset + * all elements to their initial state + */ + stop(): void; + + /** + * Destroy the animation and all child animations. + */ + destroy(clearStyleSheets?: boolean): void; + + progressStart(forceLinearEasing?: boolean, step?: number): Animation; + progressStep(step: number): Animation; + progressEnd(playTo: 0 | 1 | undefined, step: number, dur?: number): Animation; + + from(property: string, value: any): Animation; + to(property: string, value: any): Animation; + fromTo(property: string, fromValue: any, toValue: any): Animation; + + /** + * Set the keyframes for the animation. + */ + keyframes(keyframes: AnimationKeyFrames): Animation; + + /** + * Group one or more animations together to be controlled by a parent animation. + */ + addAnimation(animationToAdd: Animation | Animation[]): Animation; + + /** + * Add one or more elements to the animation + */ + addElement(el: Element | Element[] | Node | Node[] | NodeList): Animation; + + /** + * Sets the number of times the animation cycle + * should be played before stopping. + */ + iterations(iterations: number): Animation; + + /** + * Sets how the animation applies styles to its + * elements before and after the animation's execution. + */ + fill(fill: AnimationFill | undefined): Animation; + + /** + * Sets whether the animation should play forwards, + * backwards, or alternating back and forth. + */ + direction(direction: AnimationDirection | undefined): Animation; + + /** + * Sets the length of time the animation takes + * to complete one cycle. + */ + duration(duration: number | undefined): Animation; + + /** + * Sets how the animation progresses through the + * duration of each cycle. + */ + easing(easing: string | undefined): Animation; + + /** + * Sets when an animation starts (in milliseconds). + */ + delay(delay: number | undefined): Animation; + + /** + * Get an array of keyframes for the animation. + */ + getKeyframes(): AnimationKeyFrames; + + /** + * Returns the animation's direction. + */ + getDirection(): AnimationDirection; + + /** + * Returns the animation's fill mode. + */ + getFill(): AnimationFill; + + /** + * Gets the animation's delay in milliseconds. + */ + getDelay(): number; + + /** + * Gets the number of iterations the animation will run. + */ + getIterations(): number; + + /** + * Returns the animation's easing. + */ + getEasing(): string; + + /** + * Gets the animation's duration in milliseconds. + */ + getDuration(): number; + + /** + * Returns the raw Web Animations object + * for all elements in an Animation. + * This will return an empty array on + * browsers that do not support + * the Web Animations API. + */ + getWebAnimations(): any[]; + + /** + * Add a function that performs a + * DOM read to be run after the + * animation end + */ + afterAddRead(readFn: () => void): Animation; + + /** + * Add a function that performs a + * DOM write to be run after the + * animation end + */ + afterAddWrite(writeFn: () => void): Animation; + + /** + * Clear CSS inline styles from the animation's + * elements after the animation ends. + */ + afterClearStyles(propertyNames: string[]): Animation; + + /** + * Set CSS inline styles to the animation's + * elements after the animation ends. + */ + afterStyles(styles: { [property: string]: any }): Animation; + + /** + * Add CSS class to the animation's + * elements after the animation ends. + */ + afterAddClass(className: string | string[]): Animation; + + /** + * Remove CSS class from the animation's + * elements after the animation ends. + */ + afterRemoveClass(className: string | string[]): Animation; + + /** + * Add a function that performs a + * DOM read to be run before the + * animation starts + */ + beforeAddRead(readFn: () => void): Animation; + + /** + * Add a function that performs a + * DOM write to be run before the + * animation starts + */ + beforeAddWrite(writeFn: () => void): Animation; + + /** + * Clear CSS inline styles from the animation's + * elements before the animation begins. + */ + beforeClearStyles(propertyNames: string[]): Animation; + + /** + * Set CSS inline styles to the animation's + * elements before the animation begins. + */ + beforeStyles(styles: { [property: string]: any }): Animation; + + /** + * Add a class to the animation's + * elements before the animation starts + */ + beforeAddClass(className: string | string[]): Animation; + + /** + * Remove a class from the animation's + * elements before the animation starts + */ + beforeRemoveClass(className: string | string[]): Animation; + + /** + * Add a callback to be run + * upon the animation ending + */ + onFinish(callback: AnimationLifecycle, opts?: AnimationCallbackOptions): Animation; + + /** + * Returns `true` if the animation is running. + * Returns `false` otherwise. + */ + isRunning(): boolean; +} +``` + +### AnimationCallbackOptions + ```tsx interface AnimationCallbackOptions { /** @@ -1567,7 +1807,11 @@ interface AnimationCallbackOptions { */ oneTimeCallback: boolean; } +``` + +### AnimationPlayOptions +```tsx interface AnimationPlayOptions { /** * If true, the animation will play synchronously. From 90c3528babb1ce82f4468bc0aa7255007fe3c6eb Mon Sep 17 00:00:00 2001 From: Sean Perkins Date: Thu, 9 Mar 2023 16:15:53 -0500 Subject: [PATCH 2/4] fix: clean-up animation docs Remove browser support section, reword introduction description, organize the API under API heading with a description of what it pertains to. --- docs/utilities/animations.md | 273 ++---------------- .../version-v6/utilities/animations.md | 273 ++---------------- 2 files changed, 40 insertions(+), 506 deletions(-) diff --git a/docs/utilities/animations.md b/docs/utilities/animations.md index 0d697c32f14..246ded04d40 100644 --- a/docs/utilities/animations.md +++ b/docs/utilities/animations.md @@ -16,11 +16,11 @@ import TabItem from '@theme/TabItem'; ## Overview -Ionic Animations is a utility that allows developers to build complex animations in a platform agnostic manner. Developers do not need to be using a particular framework such as React or Angular, nor do they even need to be building an Ionic app. As long as developers have access to v5.0 or greater of Ionic Framework, they will have access to all of Ionic Animations. +Ionic Animations is a tool that enables developers to create complex animations in a platform-agnostic manner, without requiring a specific framework or an Ionic app. -Building efficient animations can be tricky. Developers are often limited by the libraries available to them as well as the hardware that their apps run on. On top of that, many animation libraries use a JavaScript-driven approach to running animations where they handle the calculation of your animation's values at every step in a `requestAnimationFrame` loop. This reduces the scalability of your animations as the library is constantly computing values and using up CPU time. +Creating efficient animations can be challenging, as it is limited by the available libraries and hardware resources of the app. Moreover, many animation libraries use a JavaScript-driven approach, which can reduce the scalability of animations and use up CPU time. -Ionic Animations uses the [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API) to build and run your animations. In doing this, we offload all work required to compute and run your animations to the browser. As a result, this allows the browser to make any optimizations it needs and ensures your animations run as smoothly as possible. While most browsers support a basic implementation of Web Animations, we fallback to [CSS Animations](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Animations/Using_CSS_animations) for browsers that do not support Web Animations. The performance difference in switching between these two should typically be negligible. +Ionic Animations, on the other hand, uses the [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API), which offloads all the computation and running of animations to the browser. This approach allows the browser to optimize the animations and ensure their smooth execution. In cases where Web Animations are not supported, Ionic Animations will fall back to [CSS Animations](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Animations/Using_CSS_animations), which should have a negligible difference in performance. ## Installation @@ -1535,32 +1535,25 @@ const animation = createAnimation('my-animation-identifier') .fromTo('opacity', '1', '0'); ``` -## Browser Support +## API -| Browser/Platform | Supported Versions | -| ---------------- | ------------------ | -| **Chrome** | 43+ | -| **Safari** | 9+ | -| **Firefox** | 32+ | -| **IE/Edge** | 11+ | -| **Opera** | 30+ | -| **iOS** | 9+ | -| **Android** | 5+ | +This section provides a list of all the methods and properties available on the `Animation` class. -:::note -Due to a bug in Safari versions 9-11, stepping through animations via `progressStep` is not supported. This is supported on Safari 12+. -::: +### Interfaces -## Types +#### AnimationDirection + +```tsx +type AnimationDirection = 'normal' | 'reverse' | 'alternate' | 'alternate-reverse'; +``` -| Name | Value | -| -------------------- | ------------------------------------------------------------- | -| `AnimationDirection` | `'normal' \| 'reverse' \| 'alternate' \| 'alternate-reverse'` | -| `AnimationFill` | `'auto' \| 'none' \| 'forwards' \| 'backwards' \| 'both'` | +#### AnimationFill -## Interfaces +```tsx +type AnimationFill = 'auto' | 'none' | 'forwards' | 'backwards' | 'both'; +``` -### AnimationBuilder +#### AnimationBuilder ```tsx type AnimationBuilder = (baseEl: any, opts?: any) => Animation; @@ -1572,233 +1565,7 @@ type AnimationBuilder = (baseEl: any, opts?: any) => Animation; ::: -### Animation - -```tsx -interface Animation { - parentAnimation?: Animation; - elements: HTMLElement[]; - childAnimations: Animation[]; - id: string | undefined; - - /** - * Play the animation - * - * If the `sync` options is `true`, the animation will play synchronously. This - * is the equivalent of running the animation - * with a duration of 0ms. - */ - play(opts?: AnimationPlayOptions): Promise; - - /** - * Pauses the animation - */ - pause(): void; - - /** - * Stop the animation and reset - * all elements to their initial state - */ - stop(): void; - - /** - * Destroy the animation and all child animations. - */ - destroy(clearStyleSheets?: boolean): void; - - progressStart(forceLinearEasing?: boolean, step?: number): Animation; - progressStep(step: number): Animation; - progressEnd(playTo: 0 | 1 | undefined, step: number, dur?: number): Animation; - - from(property: string, value: any): Animation; - to(property: string, value: any): Animation; - fromTo(property: string, fromValue: any, toValue: any): Animation; - - /** - * Set the keyframes for the animation. - */ - keyframes(keyframes: AnimationKeyFrames): Animation; - - /** - * Group one or more animations together to be controlled by a parent animation. - */ - addAnimation(animationToAdd: Animation | Animation[]): Animation; - - /** - * Add one or more elements to the animation - */ - addElement(el: Element | Element[] | Node | Node[] | NodeList): Animation; - - /** - * Sets the number of times the animation cycle - * should be played before stopping. - */ - iterations(iterations: number): Animation; - - /** - * Sets how the animation applies styles to its - * elements before and after the animation's execution. - */ - fill(fill: AnimationFill | undefined): Animation; - - /** - * Sets whether the animation should play forwards, - * backwards, or alternating back and forth. - */ - direction(direction: AnimationDirection | undefined): Animation; - - /** - * Sets the length of time the animation takes - * to complete one cycle. - */ - duration(duration: number | undefined): Animation; - - /** - * Sets how the animation progresses through the - * duration of each cycle. - */ - easing(easing: string | undefined): Animation; - - /** - * Sets when an animation starts (in milliseconds). - */ - delay(delay: number | undefined): Animation; - - /** - * Get an array of keyframes for the animation. - */ - getKeyframes(): AnimationKeyFrames; - - /** - * Returns the animation's direction. - */ - getDirection(): AnimationDirection; - - /** - * Returns the animation's fill mode. - */ - getFill(): AnimationFill; - - /** - * Gets the animation's delay in milliseconds. - */ - getDelay(): number; - - /** - * Gets the number of iterations the animation will run. - */ - getIterations(): number; - - /** - * Returns the animation's easing. - */ - getEasing(): string; - - /** - * Gets the animation's duration in milliseconds. - */ - getDuration(): number; - - /** - * Returns the raw Web Animations object - * for all elements in an Animation. - * This will return an empty array on - * browsers that do not support - * the Web Animations API. - */ - getWebAnimations(): any[]; - - /** - * Add a function that performs a - * DOM read to be run after the - * animation end - */ - afterAddRead(readFn: () => void): Animation; - - /** - * Add a function that performs a - * DOM write to be run after the - * animation end - */ - afterAddWrite(writeFn: () => void): Animation; - - /** - * Clear CSS inline styles from the animation's - * elements after the animation ends. - */ - afterClearStyles(propertyNames: string[]): Animation; - - /** - * Set CSS inline styles to the animation's - * elements after the animation ends. - */ - afterStyles(styles: { [property: string]: any }): Animation; - - /** - * Add CSS class to the animation's - * elements after the animation ends. - */ - afterAddClass(className: string | string[]): Animation; - - /** - * Remove CSS class from the animation's - * elements after the animation ends. - */ - afterRemoveClass(className: string | string[]): Animation; - - /** - * Add a function that performs a - * DOM read to be run before the - * animation starts - */ - beforeAddRead(readFn: () => void): Animation; - - /** - * Add a function that performs a - * DOM write to be run before the - * animation starts - */ - beforeAddWrite(writeFn: () => void): Animation; - - /** - * Clear CSS inline styles from the animation's - * elements before the animation begins. - */ - beforeClearStyles(propertyNames: string[]): Animation; - - /** - * Set CSS inline styles to the animation's - * elements before the animation begins. - */ - beforeStyles(styles: { [property: string]: any }): Animation; - - /** - * Add a class to the animation's - * elements before the animation starts - */ - beforeAddClass(className: string | string[]): Animation; - - /** - * Remove a class from the animation's - * elements before the animation starts - */ - beforeRemoveClass(className: string | string[]): Animation; - - /** - * Add a callback to be run - * upon the animation ending - */ - onFinish(callback: AnimationLifecycle, opts?: AnimationCallbackOptions): Animation; - - /** - * Returns `true` if the animation is running. - * Returns `false` otherwise. - */ - isRunning(): boolean; -} -``` - -### AnimationCallbackOptions +#### AnimationCallbackOptions ```tsx interface AnimationCallbackOptions { @@ -1809,7 +1576,7 @@ interface AnimationCallbackOptions { } ``` -### AnimationPlayOptions +#### AnimationPlayOptions ```tsx interface AnimationPlayOptions { @@ -1822,7 +1589,7 @@ interface AnimationPlayOptions { } ``` -## Properties +### Properties | Name | Description | | ------------------------------ | ------------------------------------------------- | @@ -1830,7 +1597,7 @@ interface AnimationPlayOptions { | `elements: HTMLElement[]` | All elements attached to an animation. | | `parentAnimation?: Animation` | The parent animation of a given animation object. | -## Methods +### Methods | Name | Description | | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | diff --git a/versioned_docs/version-v6/utilities/animations.md b/versioned_docs/version-v6/utilities/animations.md index 0d697c32f14..246ded04d40 100644 --- a/versioned_docs/version-v6/utilities/animations.md +++ b/versioned_docs/version-v6/utilities/animations.md @@ -16,11 +16,11 @@ import TabItem from '@theme/TabItem'; ## Overview -Ionic Animations is a utility that allows developers to build complex animations in a platform agnostic manner. Developers do not need to be using a particular framework such as React or Angular, nor do they even need to be building an Ionic app. As long as developers have access to v5.0 or greater of Ionic Framework, they will have access to all of Ionic Animations. +Ionic Animations is a tool that enables developers to create complex animations in a platform-agnostic manner, without requiring a specific framework or an Ionic app. -Building efficient animations can be tricky. Developers are often limited by the libraries available to them as well as the hardware that their apps run on. On top of that, many animation libraries use a JavaScript-driven approach to running animations where they handle the calculation of your animation's values at every step in a `requestAnimationFrame` loop. This reduces the scalability of your animations as the library is constantly computing values and using up CPU time. +Creating efficient animations can be challenging, as it is limited by the available libraries and hardware resources of the app. Moreover, many animation libraries use a JavaScript-driven approach, which can reduce the scalability of animations and use up CPU time. -Ionic Animations uses the [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API) to build and run your animations. In doing this, we offload all work required to compute and run your animations to the browser. As a result, this allows the browser to make any optimizations it needs and ensures your animations run as smoothly as possible. While most browsers support a basic implementation of Web Animations, we fallback to [CSS Animations](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Animations/Using_CSS_animations) for browsers that do not support Web Animations. The performance difference in switching between these two should typically be negligible. +Ionic Animations, on the other hand, uses the [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API), which offloads all the computation and running of animations to the browser. This approach allows the browser to optimize the animations and ensure their smooth execution. In cases where Web Animations are not supported, Ionic Animations will fall back to [CSS Animations](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Animations/Using_CSS_animations), which should have a negligible difference in performance. ## Installation @@ -1535,32 +1535,25 @@ const animation = createAnimation('my-animation-identifier') .fromTo('opacity', '1', '0'); ``` -## Browser Support +## API -| Browser/Platform | Supported Versions | -| ---------------- | ------------------ | -| **Chrome** | 43+ | -| **Safari** | 9+ | -| **Firefox** | 32+ | -| **IE/Edge** | 11+ | -| **Opera** | 30+ | -| **iOS** | 9+ | -| **Android** | 5+ | +This section provides a list of all the methods and properties available on the `Animation` class. -:::note -Due to a bug in Safari versions 9-11, stepping through animations via `progressStep` is not supported. This is supported on Safari 12+. -::: +### Interfaces -## Types +#### AnimationDirection + +```tsx +type AnimationDirection = 'normal' | 'reverse' | 'alternate' | 'alternate-reverse'; +``` -| Name | Value | -| -------------------- | ------------------------------------------------------------- | -| `AnimationDirection` | `'normal' \| 'reverse' \| 'alternate' \| 'alternate-reverse'` | -| `AnimationFill` | `'auto' \| 'none' \| 'forwards' \| 'backwards' \| 'both'` | +#### AnimationFill -## Interfaces +```tsx +type AnimationFill = 'auto' | 'none' | 'forwards' | 'backwards' | 'both'; +``` -### AnimationBuilder +#### AnimationBuilder ```tsx type AnimationBuilder = (baseEl: any, opts?: any) => Animation; @@ -1572,233 +1565,7 @@ type AnimationBuilder = (baseEl: any, opts?: any) => Animation; ::: -### Animation - -```tsx -interface Animation { - parentAnimation?: Animation; - elements: HTMLElement[]; - childAnimations: Animation[]; - id: string | undefined; - - /** - * Play the animation - * - * If the `sync` options is `true`, the animation will play synchronously. This - * is the equivalent of running the animation - * with a duration of 0ms. - */ - play(opts?: AnimationPlayOptions): Promise; - - /** - * Pauses the animation - */ - pause(): void; - - /** - * Stop the animation and reset - * all elements to their initial state - */ - stop(): void; - - /** - * Destroy the animation and all child animations. - */ - destroy(clearStyleSheets?: boolean): void; - - progressStart(forceLinearEasing?: boolean, step?: number): Animation; - progressStep(step: number): Animation; - progressEnd(playTo: 0 | 1 | undefined, step: number, dur?: number): Animation; - - from(property: string, value: any): Animation; - to(property: string, value: any): Animation; - fromTo(property: string, fromValue: any, toValue: any): Animation; - - /** - * Set the keyframes for the animation. - */ - keyframes(keyframes: AnimationKeyFrames): Animation; - - /** - * Group one or more animations together to be controlled by a parent animation. - */ - addAnimation(animationToAdd: Animation | Animation[]): Animation; - - /** - * Add one or more elements to the animation - */ - addElement(el: Element | Element[] | Node | Node[] | NodeList): Animation; - - /** - * Sets the number of times the animation cycle - * should be played before stopping. - */ - iterations(iterations: number): Animation; - - /** - * Sets how the animation applies styles to its - * elements before and after the animation's execution. - */ - fill(fill: AnimationFill | undefined): Animation; - - /** - * Sets whether the animation should play forwards, - * backwards, or alternating back and forth. - */ - direction(direction: AnimationDirection | undefined): Animation; - - /** - * Sets the length of time the animation takes - * to complete one cycle. - */ - duration(duration: number | undefined): Animation; - - /** - * Sets how the animation progresses through the - * duration of each cycle. - */ - easing(easing: string | undefined): Animation; - - /** - * Sets when an animation starts (in milliseconds). - */ - delay(delay: number | undefined): Animation; - - /** - * Get an array of keyframes for the animation. - */ - getKeyframes(): AnimationKeyFrames; - - /** - * Returns the animation's direction. - */ - getDirection(): AnimationDirection; - - /** - * Returns the animation's fill mode. - */ - getFill(): AnimationFill; - - /** - * Gets the animation's delay in milliseconds. - */ - getDelay(): number; - - /** - * Gets the number of iterations the animation will run. - */ - getIterations(): number; - - /** - * Returns the animation's easing. - */ - getEasing(): string; - - /** - * Gets the animation's duration in milliseconds. - */ - getDuration(): number; - - /** - * Returns the raw Web Animations object - * for all elements in an Animation. - * This will return an empty array on - * browsers that do not support - * the Web Animations API. - */ - getWebAnimations(): any[]; - - /** - * Add a function that performs a - * DOM read to be run after the - * animation end - */ - afterAddRead(readFn: () => void): Animation; - - /** - * Add a function that performs a - * DOM write to be run after the - * animation end - */ - afterAddWrite(writeFn: () => void): Animation; - - /** - * Clear CSS inline styles from the animation's - * elements after the animation ends. - */ - afterClearStyles(propertyNames: string[]): Animation; - - /** - * Set CSS inline styles to the animation's - * elements after the animation ends. - */ - afterStyles(styles: { [property: string]: any }): Animation; - - /** - * Add CSS class to the animation's - * elements after the animation ends. - */ - afterAddClass(className: string | string[]): Animation; - - /** - * Remove CSS class from the animation's - * elements after the animation ends. - */ - afterRemoveClass(className: string | string[]): Animation; - - /** - * Add a function that performs a - * DOM read to be run before the - * animation starts - */ - beforeAddRead(readFn: () => void): Animation; - - /** - * Add a function that performs a - * DOM write to be run before the - * animation starts - */ - beforeAddWrite(writeFn: () => void): Animation; - - /** - * Clear CSS inline styles from the animation's - * elements before the animation begins. - */ - beforeClearStyles(propertyNames: string[]): Animation; - - /** - * Set CSS inline styles to the animation's - * elements before the animation begins. - */ - beforeStyles(styles: { [property: string]: any }): Animation; - - /** - * Add a class to the animation's - * elements before the animation starts - */ - beforeAddClass(className: string | string[]): Animation; - - /** - * Remove a class from the animation's - * elements before the animation starts - */ - beforeRemoveClass(className: string | string[]): Animation; - - /** - * Add a callback to be run - * upon the animation ending - */ - onFinish(callback: AnimationLifecycle, opts?: AnimationCallbackOptions): Animation; - - /** - * Returns `true` if the animation is running. - * Returns `false` otherwise. - */ - isRunning(): boolean; -} -``` - -### AnimationCallbackOptions +#### AnimationCallbackOptions ```tsx interface AnimationCallbackOptions { @@ -1809,7 +1576,7 @@ interface AnimationCallbackOptions { } ``` -### AnimationPlayOptions +#### AnimationPlayOptions ```tsx interface AnimationPlayOptions { @@ -1822,7 +1589,7 @@ interface AnimationPlayOptions { } ``` -## Properties +### Properties | Name | Description | | ------------------------------ | ------------------------------------------------- | @@ -1830,7 +1597,7 @@ interface AnimationPlayOptions { | `elements: HTMLElement[]` | All elements attached to an animation. | | `parentAnimation?: Animation` | The parent animation of a given animation object. | -## Methods +### Methods | Name | Description | | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | From 01819470b7b161ab8c26e8c680a798102e3217a8 Mon Sep 17 00:00:00 2001 From: Sean Perkins Date: Thu, 9 Mar 2023 16:34:15 -0500 Subject: [PATCH 3/4] chore: port changes to v5 docs --- .../version-v5/utilities/animations.md | 57 +++++++++++-------- 1 file changed, 34 insertions(+), 23 deletions(-) diff --git a/versioned_docs/version-v5/utilities/animations.md b/versioned_docs/version-v5/utilities/animations.md index d41178a40ad..8f2007c6f79 100644 --- a/versioned_docs/version-v5/utilities/animations.md +++ b/versioned_docs/version-v5/utilities/animations.md @@ -6,11 +6,11 @@ import TabItem from '@theme/TabItem'; ## Overview -Ionic Animations is a utility that allows developers to build complex animations in a platform agnostic manner. Developers do not need to be using a particular framework such as React or Angular, nor do they even need to be building an Ionic app. As long as developers have access to v5.0 or greater of Ionic Framework, they will have access to all of Ionic Animations. +Ionic Animations is a tool that enables developers to create complex animations in a platform-agnostic manner, without requiring a specific framework or an Ionic app. -Building efficient animations can be tricky. Developers are often limited by the libraries available to them as well as the hardware that their apps run on. On top of that, many animation libraries use a JavaScript-driven approach to running animations where they handle the calculation of your animation's values at every step in a `requestAnimationFrame` loop. This reduces the scalability of your animations as the library is constantly computing values and using up CPU time. +Creating efficient animations can be challenging, as it is limited by the available libraries and hardware resources of the app. Moreover, many animation libraries use a JavaScript-driven approach, which can reduce the scalability of animations and use up CPU time. -Ionic Animations uses the [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API) to build and run your animations. In doing this, we offload all work required to compute and run your animations to the browser. As a result, this allows the browser to make any optimizations it needs and ensures your animations run as smoothly as possible. While most browsers support a basic implementation of Web Animations, we fallback to [CSS Animations](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Animations/Using_CSS_animations) for browsers that do not support Web Animations. The performance difference in switching between these two should typically be negligible. +Ionic Animations, on the other hand, uses the [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API), which offloads all the computation and running of animations to the browser. This approach allows the browser to optimize the animations and ensure their smooth execution. In cases where Web Animations are not supported, Ionic Animations will fall back to [CSS Animations](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Animations/Using_CSS_animations), which should have a negligible difference in performance. ## Installation @@ -1517,30 +1517,37 @@ const animation = createAnimation('my-animation-identifier') .fromTo('opacity', '1', '0'); ``` -## Browser Support +## API -| Browser/Platform | Supported Versions | -| ---------------- | ------------------ | -| **Chrome** | 43+ | -| **Safari** | 9+ | -| **Firefox** | 32+ | -| **IE/Edge** | 11+ | -| **Opera** | 30+ | -| **iOS** | 9+ | -| **Android** | 5+ | +This section provides a list of all the methods and properties available on the `Animation` class. + +### Interfaces + +#### AnimationDirection + +```tsx +type AnimationDirection = 'normal' | 'reverse' | 'alternate' | 'alternate-reverse'; +``` + +#### AnimationFill + +```tsx +type AnimationFill = 'auto' | 'none' | 'forwards' | 'backwards' | 'both'; +``` + +#### AnimationBuilder + +```tsx +type AnimationBuilder = (baseEl: any, opts?: any) => Animation; +``` :::note -Due to a bug in Safari versions 9-11, stepping through animations via `progressStep` is not supported. This is supported on Safari 12+. -::: -## Types +`opts` are additional options that are specific to the custom animation. For example, the sheet modal enter animation includes information for the current breakpoint. -| Name | Value | -| -------------------- | ------------------------------------------------------------- | -| `AnimationDirection` | `'normal' \| 'reverse' \| 'alternate' \| 'alternate-reverse'` | -| `AnimationFill` | `'auto' \| 'none' \| 'forwards' \| 'backwards' \| 'both'` | +::: -## Interfaces +#### AnimationCallbackOptions ```tsx interface AnimationCallbackOptions { @@ -1549,7 +1556,11 @@ interface AnimationCallbackOptions { */ oneTimeCallback: boolean; } +``` +#### AnimationPlayOptions + +```tsx interface AnimationPlayOptions { /** * If true, the animation will play synchronously. @@ -1560,7 +1571,7 @@ interface AnimationPlayOptions { } ``` -## Properties +### Properties | Name | Description | | ------------------------------ | ------------------------------------------------- | @@ -1568,7 +1579,7 @@ interface AnimationPlayOptions { | `elements: HTMLElement[]` | All elements attached to an animation. | | `parentAnimation?: Animation` | The parent animation of a given animation object. | -## Methods +### Methods | Name | Description | | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | From fd84dfdfb36fb5dfcaef7ac561cde38335dd211d Mon Sep 17 00:00:00 2001 From: Sean Perkins Date: Fri, 10 Mar 2023 12:56:21 -0500 Subject: [PATCH 4/4] chore: rephrase summary --- docs/utilities/animations.md | 2 +- versioned_docs/version-v5/utilities/animations.md | 2 +- versioned_docs/version-v6/utilities/animations.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/utilities/animations.md b/docs/utilities/animations.md index 246ded04d40..92c6eebc67a 100644 --- a/docs/utilities/animations.md +++ b/docs/utilities/animations.md @@ -18,7 +18,7 @@ import TabItem from '@theme/TabItem'; Ionic Animations is a tool that enables developers to create complex animations in a platform-agnostic manner, without requiring a specific framework or an Ionic app. -Creating efficient animations can be challenging, as it is limited by the available libraries and hardware resources of the app. Moreover, many animation libraries use a JavaScript-driven approach, which can reduce the scalability of animations and use up CPU time. +Creating efficient animations can be challenging, as developers are limited by the available libraries and hardware resources of the device. Moreover, many animation libraries use a JavaScript-driven approach, which can reduce the scalability of animations and use up CPU time. Ionic Animations, on the other hand, uses the [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API), which offloads all the computation and running of animations to the browser. This approach allows the browser to optimize the animations and ensure their smooth execution. In cases where Web Animations are not supported, Ionic Animations will fall back to [CSS Animations](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Animations/Using_CSS_animations), which should have a negligible difference in performance. diff --git a/versioned_docs/version-v5/utilities/animations.md b/versioned_docs/version-v5/utilities/animations.md index 8f2007c6f79..9387b9639c6 100644 --- a/versioned_docs/version-v5/utilities/animations.md +++ b/versioned_docs/version-v5/utilities/animations.md @@ -8,7 +8,7 @@ import TabItem from '@theme/TabItem'; Ionic Animations is a tool that enables developers to create complex animations in a platform-agnostic manner, without requiring a specific framework or an Ionic app. -Creating efficient animations can be challenging, as it is limited by the available libraries and hardware resources of the app. Moreover, many animation libraries use a JavaScript-driven approach, which can reduce the scalability of animations and use up CPU time. +Creating efficient animations can be challenging, as developers are limited by the available libraries and hardware resources of the device. Moreover, many animation libraries use a JavaScript-driven approach, which can reduce the scalability of animations and use up CPU time. Ionic Animations, on the other hand, uses the [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API), which offloads all the computation and running of animations to the browser. This approach allows the browser to optimize the animations and ensure their smooth execution. In cases where Web Animations are not supported, Ionic Animations will fall back to [CSS Animations](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Animations/Using_CSS_animations), which should have a negligible difference in performance. diff --git a/versioned_docs/version-v6/utilities/animations.md b/versioned_docs/version-v6/utilities/animations.md index 246ded04d40..dd2678b8086 100644 --- a/versioned_docs/version-v6/utilities/animations.md +++ b/versioned_docs/version-v6/utilities/animations.md @@ -18,7 +18,7 @@ import TabItem from '@theme/TabItem'; Ionic Animations is a tool that enables developers to create complex animations in a platform-agnostic manner, without requiring a specific framework or an Ionic app. -Creating efficient animations can be challenging, as it is limited by the available libraries and hardware resources of the app. Moreover, many animation libraries use a JavaScript-driven approach, which can reduce the scalability of animations and use up CPU time. +Creating efficient animations can be challenging, as it is limited by the available libraries and hardware resources of the device. Moreover, many animation libraries use a JavaScript-driven approach, which can reduce the scalability of animations and use up CPU time. Ionic Animations, on the other hand, uses the [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API), which offloads all the computation and running of animations to the browser. This approach allows the browser to optimize the animations and ensure their smooth execution. In cases where Web Animations are not supported, Ionic Animations will fall back to [CSS Animations](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Animations/Using_CSS_animations), which should have a negligible difference in performance.