animate

1. About
2. Installation
3. Example
4. API

About

animate is an animation library conforming to the WAAPI, with extra features.

Each write on Element is delayed and batched at the end of the frame, to prevent style/layout recalculations.

$3

1. easing can be assigned a custom timing function that would be cumbersome to implement with native easing functions (eg. multiple bounces)
2. keyframe property values can be assigned an object (PropertyController) to define how to apply the interpolated value on the animated element, which allows to animate a CSS property that cannot be animated yet, an attribute or property of an HTML element (eg. innerHTML), to stagger values from a path definition, etc…
3. MotionPathEffect is a temporary alternative to offset-path: url(#path), which is not supported in any brower yet (update: it is now supported in all 3 major browsers so this feature will be removed in the next minor version).

Demos:

- Playground
- Animating the y attribute of a
- Morphing the definition of a
- Morphing the definition of a (stagger)
- Moving an SVG element along a path

Installation

npm i @cdoublev/animate

@cdoublev/animate is built to run in the current "active LTS" version of NodeJS, which means it should be transpiled with your application using its own targets.

Example

All-in-one example:

``js
import animate, { setProperty as set } from '@cdoublev/animate'

const keyframes = [
{
opacity: 1,
transform: 'translateX(0px) scale(0.5)',
innerText: { set, value: 0 },
},
{
opacity: 0,
transform: 'translateX(100px) scale(1)',
innerText: { set, value: 100 },
},
]
const bounce = t => ((0.04 - (0.04 / t)) Math.sin(25 t)) + 1
const options = { duration: 2000, easing: bounce )

animate(element, keyframes, options).finished.then(() => console.log('done'))
`

API

`js
import animate from '@cdoublev/animate'

const target = document.getElementById('target')
const keyframes = { color: ['red', 'green'] }
const options = { duration: 1000 }

// animate :: (Element -> Keyframes|MotionPath -> Options?|Number?) -> Animation
const target = animate(target, keyframes, 1000)
`

animate(target, keyframes, options) is a shorthand of:

`js
import { Animation, KeyframeEffect } from '@cdoublev/animate'

const target = document.getElementById('target')
const keyframes = { color: ['red', 'green'] }
const options = { duration: 1000 }
const effect = new KeyframeEffect(target, keyframes, options)
const animation = new Animation(effect)

animation.play()
`

It also provides named exports setAttribute, setProperty, setStyle, which are further described in keyframes argument.

$3

#### Element (required)

Element should be a reference of the DOM element to animate.

#### Keyframes|MotionPath (required)

MotionPath should be a reference of a SVGGeometryElement (eg. , , , etc…) for a MotionPathEffect along which to move Element.

Keyframes should define the properties and values of a KeyframeEffect. There are two formats of keyframes (learn more on MDN):

1. Canonical (aka array-form):

`
Keyframes => [Keyframe]
Keyframe => {
[Property]: a,
easing?: String|Function,
offset?: Number|String,
}
`

2. Alternative (aka object-form):

`
Keyframes => {
[Property]: [a],
easing?: [String|Function]|String|Function,
offset?: [Number|String]|Number|String,
}
`

a should be an animated value. If it is a Number or a String containing numeric values (including hexadecimal values), it will be automatically interpolated and applyied on Element.style. Otherwise, it should be a PropertyController:

`
PropertyController => {
interpolate?: (From -> To -> Time) -> a,
set?: (Element -> Property -> a) -> void,
value: a|[a],
}
From => To => a
`

PropertyController should define a function to interpolate and/or to apply (set) animated values on Element.

interpolate should return the intermediate value at the current relative Time, which will be a Number relative to the animation's duration, starting from 0 and ending at 1. If not defined, the default function will interpolate value if it is a Number or a String containing numeric values (including hexadecimal values).

set should be one of the following named exports of this package:

- setStyle (default): to set the animated value as a CSS property of Element.style
- setProperty: to set the animated value as a property of Element
- setAttribute: to set the animated value as an attribute on Element

An Array can be used for value in object-form keyframes, to use a shorter syntax:

`js
const keyframes1 = {
x: [{ set: setAttribute, value: 0 }, { set: setAttribute, value: 1 }]
}
// Same as:
const keyframes2 = {
x: { set: setAttribute, value: [0, 1] },
}
`

#### Options|Number (optional)

Options should be either a Number representing the animation's duration (in milliseconds), or an Object containing one or more timing properties (learn more on MDN).

easing can be assigned a function whose type should be Time -> Number. It is supposed to return 0 when Time is 0 and 1 when Time is 1.

Only for a MotionPathEffect:

- rotate can be set to true to rotate Element towards the direction of MotionPath
- anchor can be set to a pair of SVG coordinates [Number, Number] to offset Element after applying the automatic transformation to center it on the start of MotionPath`

$3

#### Animation

Learn more on MDN.

TODO

- Performances: measure and improve