#994: Spec review for Animation.progress

Visit on Github.

Opened Sep 17, 2024

こんにちは TAG-さん!

I'm requesting a TAG review of Animation.progress.

This feature adds a "progress" property to the JavaScript class Animation. The goal of this property is provide authors a convenient and consistent representation of how far along an animation has advanced across its iterations and regardless of the nature of its timeline.

Further details:

Discussions

Log in to see TAG-private discussions.

Discussed Oct 7, 2024 (See Github)

discussion on why this isn't in "explainers by google"

Dan: assigns jeffrey & lea

Comment by @torgo Oct 9, 2024 (See Github)

Hi @DavMila - just a quick question: you've indicated "CSS working group" as where this work is being done. However it doesn't seem to be in the CSS repo... is this an official CSS working draft or is it that the intention is to submit it to the CSS working group? Thanks! ✨

Comment by @DavMila Oct 11, 2024 (See Github)

Hi @DavMila - just a quick question: you've indicated "CSS working group" as where this work is being done. However it doesn't seem to be in the CSS repo... is this an official CSS working draft or is it that the intention is to submit it to the CSS working group? Thanks! ✨

Thanks for the question. It's in the web-animations-2 spec in the official CSSWG repository for editor's drafts of CSS specifications . I don't think the web-animations-2 spec has been published as a working draft so it's still an editor's draft. So it has been submitted to the CSS working group as part of an editor's draft but not yet a working draft.

Discussed Oct 14, 2024 (See Github)

Jeffrey: It seems confusing that Animation.progress would be the overall progress over all iterations, while getComputedTiming().progress would only return progress over the current iteration. They should have different names.

Jeffrey: https://github.com/DavMila/explainer-animation.progress?tab=readme-ov-file#time-driven-animation doesn't look compelling to me: you need some trigger to call updateInfo(), but a progresschanged event defeats a lot of the purpose of putting animations into CSS in the first place, that they can run more efficiently and off-the-main-thread.

Jeffrey: Similarly, https://github.com/DavMila/explainer-animation.progress?tab=readme-ov-file#scroll-driven-animation seems roundabout and should show the code an author would use to show a scroll percentage without using animations. IIRC, it's possible to use animations to set an element's contents, although it's a bit tricky and breaks copy/paste. Maybe the proponents should work on that instead?

<blockquote>

The explainer doesn't justify this feature well enough. It presents two use cases: one for showing a percentage through a time-based animation, and another for showing a scroll percentage.

The time-based animation has two issues:

  1. It doesn't say why the developer is writing code like this in the first place.
  2. It doesn't show how updateInfo would get called. A big reason to do animations with CSS is to get them off the main thread, but this seems to require interrupting the main thread periodically to change the text.

The scroll percentage code doesn't show the "before" state? What would the code look like if you only used scrollTop to measure progress and draw the meter? Is using animations simpler or more performant here?

It's possible but complicated to render text directly from an animated property: https://dev.to/madsstoumann/clocks-countdowns-timing-in-css-and-javascript-554n. Maybe the use cases for Animation.progress would be better served by making that easier to use?

Finally, if you do need a property for this, it seems confusing to have two .progress properties with different meanings (within-iteration for getComputedTiming().progress vs overall for Animation.progress). Please find a different name for the new meaning.

</blockquote>
Discussed Oct 21, 2024 (See Github)

we discuss draft comment from Jeffrey

we agree to post

Posted to https://github.com/w3ctag/design-reviews/issues/994#issuecomment-2427287323.

Comment by @jyasskin Oct 21, 2024 (See Github)

After a discussion in a breakout:

The explainer doesn't justify this feature well enough. It presents two use cases: one for showing a percentage through a time-based animation, and another for showing a scroll percentage.

The time-based animation has two issues:

  1. It doesn't say why the developer is writing code like this in the first place.
  2. It doesn't show how updateInfo would get called. A big reason to do animations with CSS is to get them off the main thread, but this seems to require interrupting the main thread periodically to change the text.

The scroll percentage code doesn't show the "before" state. What would the code look like if you only used scrollTop and friends to measure progress and draw the meter? Is using animations simpler or more performant here, given the common use cases' needs for animation-range and the named timeline ranges?

It's possible but complicated to render text directly from an animated property: https://dev.to/madsstoumann/clocks-countdowns-timing-in-css-and-javascript-554n. Maybe the use cases for Animation.progress would be better served by making that easier to use?

Finally, if you do need a property for this, it seems confusing to have two .progress properties with different meanings (within-iteration for myAnimation.effect.getComputedTiming().progress vs overall for myAnimation.progress). Please find a different name for the new meaning.

Comment by @DavMila Oct 25, 2024 (See Github)

I've updated the explainer to address some of the concerns raised by @jyasskin .

  1. It doesn't say why the developer is writing code like this in the first place.
  2. It doesn't show how updateInfo would get called. A big reason to do animations with CSS is to get them off the main thread, but this seems to require interrupting the main thread periodically to change the text.

The interest in a progress accessor was mainly driven by scroll-driven animations but it does seem to be a concept that would be valid for time-driven animations as well so I've set up a demo showing a more useful scenario: where a dev might want to synchronize audio based on the progress of an animation .

I've also:

  • included a scroll-driven demo where the currentTime of a video is set based on the progress of a scroll-driven animation.
  • included a code example of how scrollTop could instead be used to make the before/after contrast clearer.

About the name of the property, I agree that it could be confusing, maybe a name like totalProgress would work better - I'll file an issue with the CSS working group for this.

Further feedback appreciated :)

Discussed Oct 28, 2024 (See Github)

Jeffrey owes this a re-review.

Discussed Nov 4, 2024 (See Github)

Jeffrey: [sketches explainer update]. My sense is to say to keep trying to find a clearer name, but otherwise that this looks good.

Jeffrey to draft a closing comment.

Discussed Nov 11, 2024 (See Github)

Tess: https://github.com/w3c/csswg-drafts/issues/6245#issuecomment-2469190377 might affect this.

Jeffrey: I have posted to ask about that.

Comment by @jyasskin Nov 12, 2024 (See Github)

@tabatkins, does https://github.com/w3c/csswg-drafts/issues/6245#issuecomment-2469190377 affect this review?

Comment by @tabatkins Nov 13, 2024 (See Github)

No, completely unrelated name clash.

Comment by @jyasskin Nov 14, 2024 (See Github)

Thank you for the fleshed out use cases in the explainer. We agree that it makes sense to be able to pass this value through Javascript to feed it into any parts of the platform that can't be directly animated by CSS.

Thank you also for driving the CSSWG to pick a clearer name. With that done, we don't see any other issues with this proposal, so we'll close this review. Thanks!