Add support for spring duration

[Latropos]

Summary

We have decided to introduce two new config props - damping ratio and duration to make usage of withSpring easier.

  graph LR;
      A[Use<br>withSpring<br>animation] --> B;
      B{Did user provide<br>config with duration or<br>dampingRatio?} --YES-->C[Calculate spring movement using default or provided<br>mass and damping. Defaults:<br>damping 10, mass 1];
      B--NO-->D[Calculate spring movement using default or provided<br>duration and damping ratio. Defaults:<br>duration: 2, dampingRatio: 0.5];

Implementation

When starting an animation with predefined duration we have to find a mass that would give us the expected duration. Thus we have to solve a simple numeric equation. We do it with bisection, since Newton method appears to be much slower in this case (it happens, when finding roots of functions that grow really fast 📈)

Testing that Newton's method is much slower

Screen.Recording.2023-04-20.at.11.01.07.mov

Recordings

In all the examples below duration is set to 5000ms

dampingRatio=1	dampingRatio=0.5
Screen.Recording.2023-04-20.at.12.11.53.mov	Screen.Recording.2023-04-20.at.12.13.11.mov
dampingRatio=1000	dampingRatio=0.1
Screen.Recording.2023-04-20.at.12.14.11.mov	Screen.Recording.2023-04-20.at.12.15.20.mov

Test plan

Run demo

[piaskowyk]

For me is great! But let's wait with merge since kmagiera opinion.

[piaskowyk]

Oh, we forgot about typescript and about adding proper types to d.ts

[kmagiera]

Discussed that with @piaskowyk today but wanted to post the summary anyways;

1. We should allow for a few different configurations to work: a) duraiton + damping b) duration + stiffness c) just duration with some sensible default (preferably we should treat if someone has provided the default damping). The difference is that now we always override damping, so if user passes a damping parameter it'd get overridden and result in unexpected behavior. Note that damping is a parameter that's intuitive to use (e.g. critical damping results in no overshooting, underdamping results in the oscillator making swings and there are more swings the lower the parameter value).
2. We should always make sure that if duration is provided the animation always finishes at that specified time. Currently we use position and velocity thresholds for finishing the animation but that may result in the time being a bit off dompared to the provided duration. For the case when duration is provided we should use a different condition and only look at elapsed time (similar to what we do in timing animations)

[kmagiera]

Is it ok that we don't take velocity into account when calculating damping/mass?

[kmagiera]

I wonder why we limit duration-based animation to underdamped case only (over-damped seem to have an easier mechanics). On top of that it looks like we are not handling the case of overriding an ongoing spring animation with duration. I'd suggest that you try and replace this line https://github.com/software-mansion/react-native-reanimated/blob/main/Example/src/AnimatedStyleUpdateExample.tsx#L20 with spring animation with duration – then when you tap the button while the animation is still running, in case of timing it will only change the destination but it will finish at the designated time. With spring animation it seem like the new animation will start from new point and on top of that velocity will be reset, so there will be no smooth transition between animation from one target to the other?

[Latropos]

@kmagiera

velocity will be reset, so there will be no smooth transition

Yes, but I don't think that average user will be able to see it. I've decided to set it to zero, since if we modify mass to change the duration we get this formula LINK. So unless $v_0$ is zero we have to use Lambert W function 😢 I can try to improve it for cases in which user did not provide default damping, since if we update damping instead of mass it gets easier [LINK]

I wonder why we limit duration-based animation to underdamped case only

Type of the motion depends on $\zeta$, and
$$\zeta = \frac{c}{2 \sqrt{km}}$$
It means we know $\zeta$ after we have calculated mass and damping, so

1. If toValue is not predefined different animations with the same config could have different types. In case of real world spring type of motion never change, no matter how you change the amplitude
2. We would have the following cycle: Damping depends on duration -> motion type depends on damping -> duration depends on motion type. So it would be much more difficult. Even if we can solve it, as you've noticed "over-damped seem to have an easier mechanics" so user can obtain such a result with some easing as well.

[kmagiera]

This is getting very close, just a couple more comments I added inline

[kmagiera]

Can we please revert all the changes to this file. It was meant to be the most basic example of using animations inside uAS. We link to it in bunch of places. If we want, we can swap out timing with spring but don't make it any more sophisticated than that (i.e. don't add more components etc)

[kmagiera]

I think it'd been discussed somewhere before but perhaps got lost: we want for animations with duration set to have additional stop condition such that it ends at the exact moment in time. This is needed because duration could be used to synchronize things happening on screen and we need to make sure the animation finishes exactly when requested

[Latropos]

I've been thinking you mean cases when the obtained animation is too long and we want to terminate it earlier, but it looks like you want to "animate a static string" as well. IMHO both situations are very different so I've added four options to specify exactDuration parameter, instead of a single boolean flag. 🤔

[kmagiera]

There seem to be no point in calling this method when duration is set. We should collocate the final condition for the case when duration is set and not set to make this cleaner

[kmagiera]

Suggested change

	const config = { ...defaultConfig, ...userConfig };
	const config = { ...defaultConfig, ...userConfig, useDuration: userConfig.duration || userConfig.dampingRatio };