npm package: @oframe/animate
Description: @oframe/animate is a minimalistic javascript animation library written in es modules, made with creative WebGL production in mind. It mutates javascript objects, making it suitable for math, DOM and WebGL manipulation.
Latest version: 1.1.4

# @oframe/animate

@oframe/animate is a minimalistic javascript animation library written in es modules, made with creative WebGL production in mind. It mutates javascript objects, making it suitable for math, DOM and WebGL manipulation.

It doesn't do any magic CSS styling to reduce bloat, however it does have some advanced features, such as repeat, yoyo, stagger and async support. Plus it handles many of the pitfalls common in basic animation libraries (eg. animating multiple properties separately on an object, and automatically cancelling previous animations on a property).

## Install

```
npm i @oframe/animate
```

## Structure

The codebase is comprised of 2 files:

-   **Animation factory**
-   **Easing function library**

The total weight is **2kb** when gzipped.

## Usage

Import the Animate class in your project to get access to the API.

```js
import { Animate } from './Animate.js';
```

To animate an object's properties, use the structure `new Animate(object, duration, values)`. Duration is measured in milliseconds.

```js
const obj = { x: 0 };
new Animate(obj, 1000, { x: 1 });
```

The other main animation options are `ease` and `delay`, which are implemented as per below. Refer to `Easing.js` for the list of available ease equations.

```js
new Animate(obj, 1000, {
    x: 1,
    ease: 'outQuint',
    delay: 500,
});
```

If not declared, the default ease used is `outCubic`. Use the `Animate.setDefaultEase` method to change this globally for your project.

```js
Animate.setDefaultEase('outQuint');
```

Update and complete callbacks can be implemented in two ways. Either declare `update` and/or `complete` in the values object as per below.

```js
new Animate(obj, 1000, {
    x: 1,
    update: () => {/* ... */}),
    complete: () => {/* ... */}),
});
```

or

Chain the returned animation object using the `onUpdate` and/or `onComplete` methods. Multiple callbacks can be added using this technique. And both techniques can be used in tandem.

```js
new Animate(obj, 1000, { x: 1 })
    .onUpdate(() => {
        /* ... */
    })
    .onComplete(() => {
        /* ... */
    });
```

Promises are also avaible for async programming. Access the promise using the `.promise()` method on the returned animation object.

```js
await new Animate(obj, 1000, { x: 1 }).promise();
function() {/* ... */}
```

or

```js
new Animate(obj, 1000, { x: 1 }).promise().then(() => {
    /* ... */
});
```

To repeat an animation multiple times, the `repeat` option is a number designating the amount of times to repeat. e.g. a value of `1` will play the animation twice - once as per usual, and once repeated. A value of `-1` will repeat indefinitely. The `repeatDelay` option designates an optional delay between each repeat.

```js
new Animate(obj, 1000, {
    x: 1,
    repeat: 1,
    repeatDelay: 500,
});
```

Used in tandem with the `repeat` option, `yoyo` is a boolean option flagging whether the animation should reverse the values for every second repeat. As well as reversing values, setting `yoyo` to `true` will also reverse the ease for every reverse animation. e.g. if the ease is `outCubic`, on the reverse it will be `inCubic`. Override this behaviour using the `yoyoEase` value like below to set a specific ease for the reverse animations.

```js
new Animate(obj, 1000, {
    x: 1,
    repeat: 1,
    yoyo: true,
    yoyoEase: 'outCubic',
});
```

Arrays of objects can also be animated all at once simply by passing in the array. Then use the `stagger` option to assign a delay between each object's animation, which will be multiplied against their index in the array. A negative value will reverse the direction of the stagger, instead starting from last to first. Use the `staggerComplete` option to add a callback to the last animation to finish.

```js
const obj1 = { x: 0 };
const obj2 = { x: 0 };
new Animate([obj1, obj2], 1000, {
    x: 1,
    stagger: 20,
    staggerComplete: () => {/* ... */}),
});
```

For more customisation, assign a function to the `stagger` option that returns a number value. The arguments passed into the function are `i` - the index of the object, and `total` - the total number of objects in the array.

```js
new Animate([obj1, obj2], 1000, {
    x: 1,
    stagger: (i, total) => Math.pow(i, 2) * 10,
});
```

Each object can support simultaneous animations on multiple properties. For example, the second animation on the `y` property doesn't override the first on the `x` property.

```js
const obj = { x: 0, y: 1 };
new Animate(obj, 1000, { x: 1, ease: 'outQuint' });
new Animate(obj, 2000, { y: 0, ease: 'inQuint' });
```

Likewise, specific properties can be overridden without affecting the others. For example in the following, `x` will still animate to `1` after `1000`ms, whereas `y` will be overriden to animate to `2` after `2000`ms

```js
new Animate(obj, 1000, { x: 1, y: 1 });
new Animate(obj, 2000, { y: 2 });
```

To stop specific animations, use the `stop` method on the returned animation object.

```js
const anim = new Animate(obj, 1000, { x: 1 });
anim.stop();
```

To clear all animations on an object, use the `Animate.clear` method.

```js
Animate.clear(obj);
```

String suffixes are supported, meaning that the suffix will be removed to calculate the animation, and reapplied on the output value.

```js
const obj = { x: '50%' };
new Animate(obj, 1000, { x: '100%' });
```

Note: the target value doesn't need a suffix, and can just be a number - If the original value has a suffix, the output value will too.

```js
const obj = { x: '50%' };
new Animate(obj, 1000, { x: 100 });
```

Users can finely tune the elastic eases. For `inElastic`, `outElastic` and/or `inOutElastic`, users can pass in `spring` and `damping` values to change the defaults in the equation. The default values are `spring = 1.0`, and `damping = 0.4`.

```js
new Animate(obj, 1000, {
    x: 1,
    ease: 'outElastic',
    spring: 1.5,
    damping: 0.8,
});
```

---

Can create new Animate and Timeout instances that are attached to a different instance of Tick.

```js
const newTick = new TickClass({ autoplay: false });

const { Animate: newAnimate, Timeout: newTimeout } = new AnimateClass(newTick);
```