React Animation Orchestrator

A react-based library for managing complex animations

state = (oldState, action) => newState

but

animation = (time) => frame

React Animation Orchestrator is a library that solves the problem of discrepancy between the fact that state changes are nearly instantaneous but animations, by definition, take time to complete.

It provides higher order components to manage multiple, complex animations in an app that contains a lot of state changes that affect its animations, oftentimes even while other animations are running

Based on the timeline feature of the incredible GSAP animation library it offers:

• Different modes of resolving conflicting animations (queueing or fast-forwarding animations)
• Support for Static/Dynamic Animations
• Triggering animations from a state change or from user-initiated events (mouse click, scroll etc)
• Taking care of annoying edge cases, like how components shouldn't be removed from the DOM until they've performed their requested animations.

See a live demo live!

Overview

React Animation Orchestrator is used in two major steps: Defining animations and Describing scenarios that decide when to run these animations.

1. First, a user decorates a React component to become an AnimatedComponent. An AnimatedComponent can use its registerAnimation function to register animation specific to the component domain, to be later used within a scenario.

2. An AnimatedComponent is configured with a set of Scenarios with the attachAnimation function, to act as a "controller" of sorts to its domain-specific animations. Once the props of an AnimatedComponent change, all triggers in all of its scenarios are evaluated. If one of the triggers is evaluated to be triggered, the animations associated with the scenario the trigger belongs to are added to a timeline.

Woah that was a mouthful - in practice this should be much clearer:

Usage example

npm install @ekolabs/react-animation-orchestrator

Defining and registering animation for a component:

import React from "react";
import { TimelineMax } from 'gsap';
import { attachAnimation } from "@ekolabs/react-animation-orchestrator";

// an example of an animation generator function
const lookAtMeAnimation = (ref, options) => {
    let tl = new TimelineMax();   
    let myEl = ref.current;
    
    tl.to(myEl, 0.5, {
            scale: 1.5,
            rotating: '45deg',
            transformOrigin: 'center',
            opacity: 0.7,          
        })
        .to(myEl, 0.2, {
            scale: 1,
            rotating: '0deg',
            transformOrigin: 'center',
            opacity: 1,   
        });

    return tl;
};

class FancyComponent extends React.Component {
    constructor(props){
        super(props);
        this.ref = React.createRef();
        this.props.registerAnimation('lookAtMe', lookAtMeAnimation, this.ref);       
    }
    

    render(){
        return (
            <div ref={this.ref}>Attention-grabbing element</div>
        )
    }
}

export default attachAnimation(FancyComponent);

Configuring scenarios to trigger animations

import React from "react";
import { attachAnimation } from "@ekolabs/react-animation-orchestrator";
import FancyComponent from "./FancyComponent";

class PageComponent extends React.Component {
  
    render(){
        return (
            <div>
                <FancyComponent/>
                <AnotherComponent />
                <MoreComponents />
            </div>
        )
    }
}

export default attachAnimation(PageComponent, [
    // when the grabAttention prop changes from false to true, 
    // we want to queue the lookAtMe animation
    {
        id: 'someChange',
        trigger: {          
             select: props => props.grabAttention,
             value: false,
             nextValue: true
        },
        animations: 'lookAtMe'
    }
]);

API

registerAnimation(animationId, animationGeneratorFunction, elementReference)

Registers a new animation for an AnimatedComponent. This method is a available in the props of an attached component.

| Parameter| Type | Value | | ------------- |----- |--------| animationId string | A unique id for this animation | animationGeneratorFunction| AnimationGenrator | The animation generator function for this reference | elementReference | React reference | A React reference for the DOM object being animated

// example
class FancyComponent extends React.Component {
    constructor(props){
        super(props);
        this.ref = React.createRef();
        this.props.registerAnimation('lookAtMe', lookAtMeAnimation, this.ref);       
    }
    

    render(){
        return (
            <div ref={this.ref}>Attention-grabbing element</div>
        )
    }
}

attachAnimation(WrappedComponent, scenariosConfig)

Creates a higher-order component AnimatedComponent based on the supplied component, along with its scenario configurations.

| Parameter| Type | Value | | ------------- |----- |--------| WrappedComponent | React.Component | A react component class (not an instance) | | scenariosConfig| Scenario Configuration | An array of scenario configurations to be managed by this component (optional)|

addAnimation(animations, timelineOrTimelineId, options)

Manually add animations to a timeline

| Parameter| Type | Value | | ------------- |----- |--------| animations | An array of AnimationConfiguration | The animations to run | timelineOrTimelineId | A timeline id or a timeline instance | The timeline to add the animations to. If a timeline with such id does not exist, a new timeline will be created. options | object | The options will be passed as the second parameter of the animation generator function

triggerScenario(scenarioId)

Manually triggers the scenario's animations

| Parameter| Type | Value | | ------------- |----- |--------| scenarioId | string | The id of the scenario to trigger

setGlobalOptions(options)

Sets global options for React Animation Orchestrator. Options are:

// example
{
    onScenarioTriggered: (matchedScenario) => {},
    onScenarioStart: (refs, scenarioConfig, triggerConfig) => {},
    onScenarioComplete: (refs, scenarioConfig, triggerConfig) => {}
}

##Configuration

###Scenario A scenario describes a set of animations to be added to a timeline once a certain trigger has been met.

| Property| Type | Value | | --- | --- | --- |
| id | string | The scenario ID | | trigger| TriggerConfiguration / array of TriggerConfiguration | Triggers associated with this scenario | timeline | string | The id of the animation where the animations will be inserted to. If not specified the default master timeline is used. | animations | AnimationConfiguration | Describes which animations will be added once a trigger is met | interrupt | boolean | if true, all other animations currently present the timeline will complete immediately before adding this scenario's animations

###Trigger Configuration

A trigger describes a certain change in props that if evaluated to be true will ultimately result in addition of animations to a timeline

Can be either an object or a function

As an object

When testing the trigger, the select function will be executed with the props as its parameter once on the previous props and once on the next (changed) props. If the result of the previous props selection is equal to value and the next props selection is equal to nextValue the trigger is considered, well, triggered.

{
    // example
    {
        select: props => props.varToCheck,
        value: 'oldValue',
        nextValue: 'newValue'
    }
}

As a function

This allows more custom logic of props comparison to determine how to evaluate the trigger.

// example
(triggerComponent, prevProps, nextProps) => {   
            nextProps.VarToCheck === prevProps.varToCheck + 1;                
        },

Trigger function Parameters:

| Property| Type | Value | --- | --- | --- |
| triggerComponent | React.Component instance | The instance of the attached component | prevProps| object | The props before the change | nextProps | object | The props after the change

###Animation

An animation is a configuration which is ultimately resolved into a GSAP sub-timeline using an Animation Generator function, and then added to a Animation Orchestrator timeline

Can be either a string, an object, a function or an array containing these types for multiple animations.

As a string

'fadeIn'

As an Object

// example
{
 animation: 'fadeIn',
 position: 'withPrev',
 immediate: false,
 onComplete: ()=>{ console.log()}
}

| Property| Type | Value | | --- | --- | --- |
| animation | string | The animation ID | | timeline | string | The id of timeline to insert the animation. If not specified the default master timeline is used. | position | string / number / 'withPrev' | Where in the timeline to place the animation. Maps to GSAP position paramater, See documentation. Also accepts a special withPrev value that places this animation at the start time of the previous animation in the timeline. | immediate | boolean | if true, animation will completely instantly (duration ~0) onStart | function | A callback that will fire when the animation starts. See callback function signature onComplete| function | A callback that will fire when the animation ends. See callback function signature animationOptions | object | This object will be passed to the animation generator as a second parameter. Useful for passing data to dynamic animations.

As a function

The animation configuration function will be evaluated when a trigger condition is met. This is useful for dynamic animations. Must return an object or a string (as described above)

// example
animatedComponentInstance => {
                 animation: 'fadeIn',
                 position: '+=2',
                 animationsOptions" {
                    myVar: 12
                 }
             }

As an array of animations

['fadeIn', 'expand']

Usage:

import { attachAnimation } from "@ekolabs/react-animation-orchestrator";

attachAnimation(WrappedComponent, [
    {
        id: 'myAnimation1'
        trigger: ...,
        animations: ...
    },
    {
        id: 'myAnimation2',
        trigger: ...,
        animations: ...
    },
    ...
    ])

###Animation Callback Function

The function that gets executed once when onStart or onComplete is defined for an animation.

| Property| Type | Value | | --- | --- | --- |
| references.animatedComponent | AnimatedComponent | A reference to the component being animated | references.triggerComponent | AnimatedComponent | A reference to the component that triggered the scenario (will be null if animation was triggered manually via addAnimation) | references.tween | Tween | A reference to GSAP tween object

// example
(refs) => {}

###Animation Generator Function

A function that generates a sub-timeline that describes the animation. Returns a GSAP timeline

| Property| Type | Value | | --- | --- | --- |
| ref | React reference | The element reference passsed in registerAnimation | | options | object | The value of animationOptions as configured in an AnimationConfiguration (optional)

// example
(ref, options) => {
    let tl = new TimelineMax();   
    let myEl = ref.current;
    
    tl.to(myEl, 0.5, {
            scale: 1.5,
            rotating: '45deg',
            transformOrigin: 'center',
            opacity: 0.7,          
        });       

    return tl;
};

Contributing

When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method before submitting a PR.

Authors

• Opher Vishnia - Opherv

License

This project is licensed under the MIT License - see the LICENSE.md file for details