useAnimation: Improve dealing with delayed dependencies

[ThaNarie]

useAnimation has a dependency array, which is often used for refs that are not available immediately.

Examples

Two common use cases are a setState ref for "async components", or a useExposedAnimation ref.

1. setState

If the icon needs to be loaded async, the ref is only available when that's done. Since we need to know when the ref is available, we need to use setState.

const [iconRef, setIconRef] = useState(null);

useAnimation(() => { ... }, [iconRef]);

<Icon ref={setIconRef} name="cross" />

2. useExposedAnimation

const nestedAnimation = useExposedAnimation(refs.nested);

useAnimation(() => { ... }, [nestedAnimation]);

Situation

In these types of situations, you often do a check in your animation function:

useAnimation(() => {
  if (!animation) return gsap.timeline();

  // do something with animation (and other refs)
}, [animation]);

Forgetting to do this, or incorrectly checking it, could result in the animation/timeline being started multiple times (the more delayed dependencies you have, the more often it restarts).

Complications

Without explicit configuration, it's hard to know which dependencies are required (and delayed) or are optional.

It becomes even more tricky if delayed dependencies can be optional at the same time, how will you know when the animation should start, does it need an idleTimeout before it starts playing?

Goal

Prevent animations being created/started multiple times.

Maybe part of this problem comes down to the "autoplay" behaviour of the current setup, where the creation of the animation is also "controlling" the animation (or rather, it's not controlling it at all).

Potential Solutions

Or at least directions we can go in.

Configure which refs are required

We could also go with configuring the optional refs, in case most use cases have everything as required.

Either from the refs object, or individual delayed refs. We should come up with a good system.
The idea is to only call the "createAnimation" callback when all required refs are available.

We do need to decide what to return initially (an empty gsap animation most likely?)

Configure an idleTimeout

For cases where we have delayed dependencies, which are not marked as required.
In those scenario we need to know when we can create the animation.
A default for this timeout could be set to a few frames.

A different hook for playing the animation

Go in a slightly different direction. Similarly to the useScrollAnimation where that hook takes care of playing/controlling the created animation, we might want to have a useInTransition hook that handles the logic of knowing when to play the animation.

We might still want to introduce some ergonomics into the useAnimation, but part of it could be implemented in this new hook.

---

@strikkerpt you encountered this issue as well, let me know if I missed anything, or if you have some suggestions yourself.
@larsvanbraam @leroykorterink @ReneDrie FYI