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

// 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()