@dudadev/duda-animation-manager

Quick start

Experience the library yourself in this codesandbox.io

Install

npm i @dudadev/duda-animation-manager

Import and initialize the D.A.M singleton:

import { DudaAnimationManager } from '@dudadev/duda-animation-manager';
const dam = new DudaAnimationManager();

Create a simple animation

const bounceIn = dam.createAnimation({
    effect: 'bounce-in', // D.A.M comes with some built-in effects, custom effects can be defined
    trigger: 'entrance', // 'entrance' / 'always' / 'hover' / 'viewport' / 'mouse-proximity'
    options: {} // duration, delay, loop, reverse, yoyo, easing, and more...
    // some options (mentioned here) are available to all animations
    // but custom options can be defined on the effect level (e.g. some builtin effects supports the 'intensity' option)
});

Apply the animation to some element(s)

const instance = bounceIn.apply(targetElement || selector);

Alternatively, you can create an animation and apply it in a single line:

const instance = dam.animate(targetElement || selector)({
     effect: 'bounce-in',
     trigger: 'entrance' 
 });

Instance control: play, pause, seek:

instance.play();
instance.pause();
instance.seek(time); // seconds

Alter animation's trigger / effect / options

bounceIn.setTrigger('viewport');
bounceIn.setEffect('fade-in');
bounceIn.setOptions({duration: 5, reverse: true}); // all options available when creating an animation
// Some basic options have a sugar syntax for that:
bounceIn.setDuration(5);
bounceIn.setDelay(2);
bounceIn.reverse();

// If you "lost" a reference for the animation, and have only an instance, 
// you can get the instance's animation with:
instance.getAnimation(); 

Composition

// create 3 animations:
const bounceIn = dam.createAnimation({
    trigger: 'entrance',  
    effect: 'bounce-in'
});
const fadeIn = dam.createAnimation({
    effect: 'fade-in', 
    options: {duration: .6}
    // no need for 'trigger', since bounceIn will be the first animation in our composition, 
    // so it's trigger will be the trigger for the whole composition
});
const rotate = dam.createAnimation({
    effect: 'rotate-in',
    options: {intensity: .1}
    // no need for 'trigger', for same reason
});

// mix them all into a single animation (run parallel)
const mix = dam.mix([bounceIn, fadeIn, rotate]);
// the returned value is an Animation object, so you can do with it everything you can do with Animation (e.g. apply(someElement))

// join them all into a single animation (run sequentially)
const joined = dam.join([bounceIn, fadeIn, rotate]);
// again, the joined const will be an Animation object

// After composition has been created, 
// you can change individual animation's options, 
// and see how it affects the composition
fadeIn.setDelay(1)
rotate.setOptions({intensity: 5})
bounceIn.setOptions({from: 'right'})

Creating Custom Effects

```js // define a simple border color tween effect with custom from/to options dam.defineEffect('my-border-color-effect', {

defaultOptions: {
    fromColor: '#0000FF00', // transparent blue
    toColor: '#00F' // blue
},
tween: ({fromColor, toColor}) => ({
    start: {'border-color': fromColor},
    end: {'border-color': toColor}
})

});
// then you can use it, just like all other effects: const borderChange = dam.createAnimation({

effect: 'my-border-color-effect',
trigger: 'entrance',
options: { fromColor: '#222222', toColor: '#ABCDEF'}

});
```

Full API Reference will be available soon!

For now, here's a list of the API main classes, and methods:

- DudaAnimationManager
    
    - createAnimation(animationDescriptor) : Animation
    - animate(element | selector)(animation | animationDescriptor) : AnimationInstance

    - mix(animationsArray | animationDescriptorsArray) : Animation
    - join(animationsArray | animationDescriptorsArray) : Animation

    - defineEffect(name, effectDescriptor) 
    - composeTimelines(compositionObject, compositionType) : Timeline
    
    - getInstancesByElement(element) : Array.of(AnimationInstance)
    - getInstancesByAnimation(animation) : Array.of(AnimationInstance) 
    - getInstancesByTrigger(trigger) : Array.of(AnimationInstance)
    - getInstancesByEffect(effect) : Array.of(AnimationInstance)
    
    - getAllEffectNames() : Array.of(effectNames)
    - getOptionsForEffect(effectName, showAll = false) : Object
    
    - reset()
    - cleanDOM()
    - removeAll()
    - setEngine('scenejs' | 'animejs')
    - destroy()

• Animation

- apply(element | selector) : AnimationInstance
    
- setEffect(effect)
- setTrigger(trigger)
- setDuration(duration)
- setDelay(delay)
- setName(name)
- setOptions({...options})
- reverse()

- getOptions() : optionsObject
- getOption(optionName) : optionValue
- getDuration() : Number (seconds)
- getDelay() : Number (seconds)
- getName() : String 
- getTrigger() : String 
- getDescriptor() : Object

- getController() : ReactiveController   *** This needs the 'extras' module to be loaded. 

- join(animationsArray | animationDescriptorsArray) : Animation
- mix(animationsArray | animationDescriptorsArray) : Animation
- contains(animation) : Boolean
- getChild(index | name) : Animation
- getSub(name) : Animation
- insertChild(animation, index)
- insertChildAfter(animation, insertAfter)
- removeChild(animation | name)
- showComposition()   *** This needs the 'extras' module to be loaded. 

- createVariation() : Animation
- clone() : Animation
- getOriginal() : Animation

- resetAllInstances()
- writeDescriptorToElement()

• AnimationInstance

- play()
- pause()
- pauseOnIterationEnd()
- seek(time)

- isPlaying() : Boolean
- getTime() : Number
- whenFinsihed(callback) 

- getAnimation() : Animation
- separate() : AnimationInstance

- reset() 
- writeDescriptorToElement()
- cleanElement()
- remove()