[Feature] Expose animation data (in particular, spring velocity)

[Acccent]

Is your feature request related to a problem? Please describe.
Currently there's no way to really manipulate a spring animation, all of it is handled "magically" by Motion One. This can be a problem if you wanted to affect the animation dynamically, for example by giving it a new impulse.
Of course you could just use animate again on the same element and trust that MO will persist the current values, but as far as I can tell that doesn't happen if you've passed a function to the first animation.

If you could at least read the current velocity of a previous spring animation, you could pass that value as the initial velocity of new anim.

Overall, even though my current use case is only related to springs, I feel that having access to all animation data in an object could be useful, in particular if that object is passed as along with / instead of progress to function animations.

Describe the solution you'd like
Instead of animation.duration, animation.playState, etc:

• Leave the control methods, finished and writable props (currentTime, playbackRate) at the top level;
• Group anim data under a read-only object like:

animation.data: {
  output: number, // the result of applying the easing function to the 0–1 progress (see below)
  duration: number,
  initialOptions: AnimationOptions, // keeps the duration passed manually, even if overwritten by easing
  direction: "normal" | "reverse",
  iteration: number,
  playState: "idle" | "running" | "paused" | "finished",
  velocity: null  | number | Record<Element, number>
)

For function animations, the syntax would change like:

animate(
  (data) => {
    box.innerHTML = data.output;
  },
  { duration: 0.5 }
)

Note that I'm calling the value output and not progress, imo the "progress" of an animation always linearly advances from 0 to 1 (ie the "output" of an animation with the default ease at progress == 0.5 would be ~0.7835. (And "progress" is different than "time" because the latter includes repeats.)

If all that's needed is the output, that can be easily achieved via destructuring:

animate( ({ output }) => { box.innerHTML = output; } )

Describe alternatives you've considered
Another way to be able to more easily manipulate function animation would be to add an identifier parameter, to tell MO to persist values from a previous animation created with the same identifier. I don't think that's as flexible though, and the data object could also be useful in other contexts.

Additional context
I just wanna say I've just started using Motion One and I might be missing something for this particular issue, but either way it's a really great library and very comfortable to use, I thought it was worth mentioning!

[trafnar]

I ran into this same issue and opened this discussion post: #211

Because of this, I switched from using a function, to animating elements directly, but I found the transfer of spring values didn't work as well as I'd hoped, and my animation would jump/skip when I was doing lots of aggressive retargeting of the springs.

I ended up using a minimal implementation of spring physics to do my animations for my current project, which probably has bad performance, but allowed me to animate lots of springs and retarget them freely while keeping everything moving fluidly.

[Acccent]

Unfortunately in my case I had to use a function to go around #216.
Sadly the combination of that issue and this one means I've had to migrate to svelte that has a good implementation of spring animations. I'm keeping Motion One in mind for future uses.