After offline discussion with Adam we came up with the good idea around AnimaitonDecaySpec and the level of granularity we might want to add.

Basic idea: Let's split AnimationDecaySpec into two abstractions: one will be an per-animation-run "Info" thing that, and the other will allow creation of this "info" things for any particular animation given some input.

Detailed information: Let's split AnimationDecaySpec into two things:

"Info" -like thing. It's an instance of a class that, when pre populated with some data at the start of animation, can give you information pieces about animation parameters at any playtime (specified in the funciton call).

the API of this will be similar to what we have right now in AnimationSpec, BUT with one big difference: you already have all the knowledge about this particular occurrence of the animation, so you don't need to remember what was your entrypoints (start position, start velocity, etc).

Given that,

fun getValue(
        playTime: Long,
        start: V,
        startVelocity: V
    ): V

will become

fun getValue(
        playTime: Long
    ): V

and similar with other methods.

Factory like class that will generate you "Info" object given the input It's something of this shape:

interface AnimationFlingSpecFactory {
    fun generateFlingInfo(start: T, startVelocity: Float) : FlingInfo
}

(Names are TDB of course).

What this separation gives us: This granularity brings clear separation of concerns and knowledge: one thing lives for a long time and hosts somewhere higher lever (in components, states) and it's generated "Info" objects can flow into lower level abstraction that are one-time fired (such as AnimatedFloat.fling or animateTo).

Additionally, I would suggest to rename Decay to Fling (or just make it part of plain animations api) everywhere because:

It used to fling 100% of cases (unless I'm missing something)
The contract in which you don't know the destination in advance appears be false. You always know the final destination at the time of Info thing creation, if we will split it as suggested above.

For the reference and initial idea: take a look here

Going forward, we can try to stretch this idea to the whole animation, and not only decay/fling part.

Doris, I'd like to know your opinion on this.