[web-animations-2] Specify Animation progress API

[DavMila]

This is to specify the agreed upon animation.progress API.

[birtles]

Looks good but I suggested a few tweaks.

[birtles]

What's the thinking behind making infinite → null as opposed to zero? I think zero might be more useful overall since it represents where the animation is actually up to.

[DavMila]

I took @flackr 's point about distinguishing between 0 due to infinite duration and 0 that can actually make progress into consideration. But yes, 0 is probably more accurate. I'll write that in the algorithm.

[birtles]

Thanks for making these edits. Two follow-up questions that occurred to me:

1. If the associated effect end is zero, should the progress be 1 (or 0 if the current time is negative)? It seems odd that it's unresolved here but maybe I'm just not remembering how all this works?
2. Just to check, should we be clamping the progress to [0, 1]? I assume we shouldn't but I guess it depends on how we expect this property to be used? The answer to this will likely affect how we define the behavior for zero-duration animations.

[flackr]

Thanks for making these edits. Two follow-up questions that occurred to me:

1. If the associated effect end is zero, should the progress be 1 (or 0 if the current time is negative)? It seems odd that it's unresolved here but maybe I'm just not remembering how all this works?

I agree, it more accurately reflects the animated progress to return a value here.

2. Just to check, should we be clamping the progress to [0, 1]? I assume we shouldn't but I guess it depends on how we expect this property to be used? The answer to this will likely affect how we define the behavior for zero-duration animations.

It seems like it's more useful to allow progresses outside of the [0, 1] range, as especially for 0 it matters to know whether the effect is active or not. That said, allowing values outside of [0, 1] makes it more complicated for how to handle the 0 duration case. Perhaps we should use +/- infinity depending on whether you're before or after the start time?

@bramus @fantasai any thoughts here?

[flackr]

Thinking further on this, it may be simpler to restrict to [0, 1] and encourage authors to combine with the phase of the animation which seems like another thing that's not too easy to get today. Restricting to the [0, 1] range makes the answer to edge cases much easier to reason about, e.g. what we should do for a 0 duration effect.

[birtles]

Yeah, I think you're right. Ultimately, though, it probably depends on how we expect the API to be used.

We could mimic the behaviour of progress on ComputedEffectTiming and use the fill mode and phase of the root animation effect to make progress be unresolved when the root effect is not in effect but that might be a bit of a layering violation?

For reference, I believe ComputedEffectTiming.progress is mostly in the range [0, 1] but can extend outside that range due to easing functions.

I guess it comes back to reviewing these issues and seeing what would work best in each of those cases (quoting #8799):

In #8669, #8765 and #8201 there seems to be a common desire to have more convenient APIs for getting some representation of progress.

[flackr]

Thanks for making these edits. Two follow-up questions that occurred to me:

1. If the associated effect end is zero, should the progress be 1 (or 0 if the current time is negative)? It seems odd that it's unresolved here but maybe I'm just not remembering how all this works?

I agree, it more accurately reflects the animated progress to return a value here.

2. Just to check, should we be clamping the progress to [0, 1]? I assume we shouldn't but I guess it depends on how we expect this property to be used? The answer to this will likely affect how we define the behavior for zero-duration animations.

It seems like it's more useful to allow progresses outside of the [0, 1] range, as especially for 0 it matters to know whether the effect is active or not. That said, allowing values outside of [0, 1] makes it more complicated for how to handle the 0 duration case. Perhaps we should use +/- infinity depending on whether you're before or after the start time?

@bramus @fantasai any thoughts here?

[flackr]

Can the author tell if we're active (after the start time) or inactive (before the start time)?

[birtles]

I've reviewed this PR and I think it looks good. Thanks @DavMila for your work on this.

My only outstanding question is from here:

We could mimic the behaviour of progress on ComputedEffectTiming and use the fill mode and phase of the root animation effect to make progress be unresolved when the root effect is not in effect but that might be a bit of a layering violation?

...

I guess it comes back to reviewing these issues and seeing what would work best in each of those cases (quoting #8799):

In #8669, #8765 and #8201 there seems to be a common desire to have more convenient APIs for getting some representation of progress.

Does anyone know any specific intended uses of this API that would help determine if the progress should be unresolved when the animation is in the before/after phase and not filling?

[flackr]

I've reviewed this PR and I think it looks good. Thanks @DavMila for your work on this.

My only outstanding question is from here:

We could mimic the behaviour of progress on ComputedEffectTiming and use the fill mode and phase of the root animation effect to make progress be unresolved when the root effect is not in effect but that might be a bit of a layering violation?
...
I guess it comes back to reviewing these issues and seeing what would work best in each of those cases (quoting #8799):

In #8669, #8765 and #8201 there seems to be a common desire to have more convenient APIs for getting some representation of progress.

Does anyone know any specific intended uses of this API that would help determine if the progress should be unresolved when the animation is in the before/after phase and not filling?

I left a comment on the original issue #8799 (comment) to get a resolution here. I suppose we can land the clamping behavior and change it if we decide differently there.