Skip to content

Commit ad86bef

Browse files
sean-perkinssean-perkins
authored
docs(animations): add type interfaces (#2811)
1 parent e6ea85f commit ad86bef

File tree

3 files changed

+102
-69
lines changed

3 files changed

+102
-69
lines changed

‎docs/utilities/animations.md

+34-23
Original file line numberDiff line numberDiff line change
@@ -16,11 +16,11 @@ import TabItem from '@theme/TabItem';
1616

1717
## Overview
1818

19-
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.
19+
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.
2020

21-
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.
21+
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.
2222

23-
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.
23+
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.
2424

2525
## Installation
2626

@@ -1535,30 +1535,37 @@ const animation = createAnimation('my-animation-identifier')
15351535
.fromTo('opacity', '1', '0');
15361536
```
15371537

1538-
## Browser Support
1538+
## API
15391539

1540-
| Browser/Platform | Supported Versions |
1541-
| ---------------- | ------------------ |
1542-
| **Chrome** | 43+ |
1543-
| **Safari** | 9+ |
1544-
| **Firefox** | 32+ |
1545-
| **IE/Edge** | 11+ |
1546-
| **Opera** | 30+ |
1547-
| **iOS** | 9+ |
1548-
| **Android** | 5+ |
1540+
This section provides a list of all the methods and properties available on the `Animation` class.
1541+
1542+
### Interfaces
1543+
1544+
#### AnimationDirection
1545+
1546+
```tsx
1547+
type AnimationDirection = 'normal' | 'reverse' | 'alternate' | 'alternate-reverse';
1548+
```
1549+
1550+
#### AnimationFill
1551+
1552+
```tsx
1553+
type AnimationFill = 'auto' | 'none' | 'forwards' | 'backwards' | 'both';
1554+
```
1555+
1556+
#### AnimationBuilder
1557+
1558+
```tsx
1559+
type AnimationBuilder = (baseEl: any, opts?: any) => Animation;
1560+
```
15491561

15501562
:::note
1551-
Due to a bug in Safari versions 9-11, stepping through animations via `progressStep` is not supported. This is supported on Safari 12+.
1552-
:::
15531563

1554-
## Types
1564+
`opts` are additional options that are specific to the custom animation. For example, the sheet modal enter animation includes information for the current breakpoint.
15551565

1556-
| Name | Value |
1557-
| -------------------- | ------------------------------------------------------------- |
1558-
| `AnimationDirection` | `'normal' \| 'reverse' \| 'alternate' \| 'alternate-reverse'` |
1559-
| `AnimationFill` | `'auto' \| 'none' \| 'forwards' \| 'backwards' \| 'both'` |
1566+
:::
15601567

1561-
## Interfaces
1568+
#### AnimationCallbackOptions
15621569

15631570
```tsx
15641571
interface AnimationCallbackOptions {
@@ -1567,7 +1574,11 @@ interface AnimationCallbackOptions {
15671574
*/
15681575
oneTimeCallback: boolean;
15691576
}
1577+
```
15701578

1579+
#### AnimationPlayOptions
1580+
1581+
```tsx
15711582
interface AnimationPlayOptions {
15721583
/**
15731584
* If true, the animation will play synchronously.
@@ -1578,15 +1589,15 @@ interface AnimationPlayOptions {
15781589
}
15791590
```
15801591

1581-
## Properties
1592+
### Properties
15821593

15831594
| Name | Description |
15841595
| ------------------------------ | ------------------------------------------------- |
15851596
| `childAnimations: Animation[]` | All child animations of a given parent animation. |
15861597
| `elements: HTMLElement[]` | All elements attached to an animation. |
15871598
| `parentAnimation?: Animation` | The parent animation of a given animation object. |
15881599

1589-
## Methods
1600+
### Methods
15901601

15911602
| Name | Description |
15921603
| -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

‎versioned_docs/version-v5/utilities/animations.md

+34-23
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,11 @@ import TabItem from '@theme/TabItem';
66

77
## Overview
88

9-
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.
9+
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.
1010

11-
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.
11+
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.
1212

13-
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.
13+
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.
1414

1515
## Installation
1616

@@ -1517,30 +1517,37 @@ const animation = createAnimation('my-animation-identifier')
15171517
.fromTo('opacity', '1', '0');
15181518
```
15191519

1520-
## Browser Support
1520+
## API
15211521

1522-
| Browser/Platform | Supported Versions |
1523-
| ---------------- | ------------------ |
1524-
| **Chrome** | 43+ |
1525-
| **Safari** | 9+ |
1526-
| **Firefox** | 32+ |
1527-
| **IE/Edge** | 11+ |
1528-
| **Opera** | 30+ |
1529-
| **iOS** | 9+ |
1530-
| **Android** | 5+ |
1522+
This section provides a list of all the methods and properties available on the `Animation` class.
1523+
1524+
### Interfaces
1525+
1526+
#### AnimationDirection
1527+
1528+
```tsx
1529+
type AnimationDirection = 'normal' | 'reverse' | 'alternate' | 'alternate-reverse';
1530+
```
1531+
1532+
#### AnimationFill
1533+
1534+
```tsx
1535+
type AnimationFill = 'auto' | 'none' | 'forwards' | 'backwards' | 'both';
1536+
```
1537+
1538+
#### AnimationBuilder
1539+
1540+
```tsx
1541+
type AnimationBuilder = (baseEl: any, opts?: any) => Animation;
1542+
```
15311543

15321544
:::note
1533-
Due to a bug in Safari versions 9-11, stepping through animations via `progressStep` is not supported. This is supported on Safari 12+.
1534-
:::
15351545

1536-
## Types
1546+
`opts` are additional options that are specific to the custom animation. For example, the sheet modal enter animation includes information for the current breakpoint.
15371547

1538-
| Name | Value |
1539-
| -------------------- | ------------------------------------------------------------- |
1540-
| `AnimationDirection` | `'normal' \| 'reverse' \| 'alternate' \| 'alternate-reverse'` |
1541-
| `AnimationFill` | `'auto' \| 'none' \| 'forwards' \| 'backwards' \| 'both'` |
1548+
:::
15421549

1543-
## Interfaces
1550+
#### AnimationCallbackOptions
15441551

15451552
```tsx
15461553
interface AnimationCallbackOptions {
@@ -1549,7 +1556,11 @@ interface AnimationCallbackOptions {
15491556
*/
15501557
oneTimeCallback: boolean;
15511558
}
1559+
```
15521560

1561+
#### AnimationPlayOptions
1562+
1563+
```tsx
15531564
interface AnimationPlayOptions {
15541565
/**
15551566
* If true, the animation will play synchronously.
@@ -1560,15 +1571,15 @@ interface AnimationPlayOptions {
15601571
}
15611572
```
15621573

1563-
## Properties
1574+
### Properties
15641575

15651576
| Name | Description |
15661577
| ------------------------------ | ------------------------------------------------- |
15671578
| `childAnimations: Animation[]` | All child animations of a given parent animation. |
15681579
| `elements: HTMLElement[]` | All elements attached to an animation. |
15691580
| `parentAnimation?: Animation` | The parent animation of a given animation object. |
15701581

1571-
## Methods
1582+
### Methods
15721583

15731584
| Name | Description |
15741585
| -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

‎versioned_docs/version-v6/utilities/animations.md

+34-23
Original file line numberDiff line numberDiff line change
@@ -16,11 +16,11 @@ import TabItem from '@theme/TabItem';
1616

1717
## Overview
1818

19-
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.
19+
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.
2020

21-
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.
21+
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.
2222

23-
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.
23+
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.
2424

2525
## Installation
2626

@@ -1535,30 +1535,37 @@ const animation = createAnimation('my-animation-identifier')
15351535
.fromTo('opacity', '1', '0');
15361536
```
15371537

1538-
## Browser Support
1538+
## API
15391539

1540-
| Browser/Platform | Supported Versions |
1541-
| ---------------- | ------------------ |
1542-
| **Chrome** | 43+ |
1543-
| **Safari** | 9+ |
1544-
| **Firefox** | 32+ |
1545-
| **IE/Edge** | 11+ |
1546-
| **Opera** | 30+ |
1547-
| **iOS** | 9+ |
1548-
| **Android** | 5+ |
1540+
This section provides a list of all the methods and properties available on the `Animation` class.
1541+
1542+
### Interfaces
1543+
1544+
#### AnimationDirection
1545+
1546+
```tsx
1547+
type AnimationDirection = 'normal' | 'reverse' | 'alternate' | 'alternate-reverse';
1548+
```
1549+
1550+
#### AnimationFill
1551+
1552+
```tsx
1553+
type AnimationFill = 'auto' | 'none' | 'forwards' | 'backwards' | 'both';
1554+
```
1555+
1556+
#### AnimationBuilder
1557+
1558+
```tsx
1559+
type AnimationBuilder = (baseEl: any, opts?: any) => Animation;
1560+
```
15491561

15501562
:::note
1551-
Due to a bug in Safari versions 9-11, stepping through animations via `progressStep` is not supported. This is supported on Safari 12+.
1552-
:::
15531563

1554-
## Types
1564+
`opts` are additional options that are specific to the custom animation. For example, the sheet modal enter animation includes information for the current breakpoint.
15551565

1556-
| Name | Value |
1557-
| -------------------- | ------------------------------------------------------------- |
1558-
| `AnimationDirection` | `'normal' \| 'reverse' \| 'alternate' \| 'alternate-reverse'` |
1559-
| `AnimationFill` | `'auto' \| 'none' \| 'forwards' \| 'backwards' \| 'both'` |
1566+
:::
15601567

1561-
## Interfaces
1568+
#### AnimationCallbackOptions
15621569

15631570
```tsx
15641571
interface AnimationCallbackOptions {
@@ -1567,7 +1574,11 @@ interface AnimationCallbackOptions {
15671574
*/
15681575
oneTimeCallback: boolean;
15691576
}
1577+
```
15701578

1579+
#### AnimationPlayOptions
1580+
1581+
```tsx
15711582
interface AnimationPlayOptions {
15721583
/**
15731584
* If true, the animation will play synchronously.
@@ -1578,15 +1589,15 @@ interface AnimationPlayOptions {
15781589
}
15791590
```
15801591

1581-
## Properties
1592+
### Properties
15821593

15831594
| Name | Description |
15841595
| ------------------------------ | ------------------------------------------------- |
15851596
| `childAnimations: Animation[]` | All child animations of a given parent animation. |
15861597
| `elements: HTMLElement[]` | All elements attached to an animation. |
15871598
| `parentAnimation?: Animation` | The parent animation of a given animation object. |
15881599

1589-
## Methods
1600+
### Methods
15901601

15911602
| Name | Description |
15921603
| -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

0 commit comments

Comments
 (0)