[web-animations-2] Progress APIs

@birtles

In #8669, #8765 and #8201 there seems to be a common desire to have more convenient APIs for getting some representation of progress. Currently you can get the progress of the current iteration of an effect using the getComputedTiming() API as follows:

let progress = animation.effect.getComputedTiming().progress;

You can also get the overall effect progress by doing a calculation such as:

let progress = animation.currentTime / animation.effect.getComputedTiming().endTime;

However, with several of the other linked issues it seems that it would be convenient for developers to have some form of access to the progress through the attached animation range, or to get that progress directly from the timeline.

We could add a convenience currentProgress helper alongside the currentTime API on Animation:

attribute double? currentProgress;

This could return the progress of currentTime through the entire range before which it is considered complete, e.g. calculated as follows:

currentProgress = currentTime / effect endTime

Note that endTime is infinite when either iterations or duration is infinite. In these cases currentProgress should probably be null or undefined?

Open question - should it be read only or should we allow setting the progress which would be equivalent to setting currentTime to currentProgress * endTime?

As per discussion on #8669 a progress reported on animation should be mostly independent of the effect timing, so we calculate it as the progress from startTime to the time when the animation would resolve its finished promise. This would intentionally not match the progress through the developer specified keyframes.

@birtles @bramus @fantasai

I also propose that given the uncertainty around what's expected from the getCurrentTime API on timeline, that we remove it until we have a better understanding of the specific use cases that developers need it for. Perhaps the animation progress API above will address some of them where it seems developers were trying to work this out through the timeline.

Overall it seems reasonable to me. I think defining it in terms of startTime and endTime is a nice way of keeping it at arms length from effect timing.

Note that endTime is infinite when either iterations or duration is infinite. In these cases currentProgress should probably be null or undefined?

Mathematically, should it be zero? Not sure if that would be the most useful result, however.

Open question - should it be read only or should we allow setting the progress which would be equivalent to setting currentTime to currentProgress * endTime?

I'd suggest making it readonly. As you pointed out, there are some cases where this value would be null / undefined / 0 or somesuch, and in those cases if set made it writeable I guess the setter would throw?

We already have enough ways of changing the animation position (setting currentTime, setting startTime, calling the various playback methods etc.) and it's easy enough to make a read-only attribute writeable later if compelling use cases present themselves.

Mathematically, should it be zero? Not sure if that would be the most useful result, however.

Yeah, mathematically it would be 0. I don't have a strong preference for it to be null/undefined, just thought it might be marginally more meaningful than 0 to distinguish from the case of a 0 that can make progress.

In favor of this general approach as described here, to tackle #8669.

Fine with making it readonly as a starting point.

@bramus

Thanks @bramus. Adding to agenda to discuss/resolve:

Add read-only currentProgress to Animation calculated as currentTime / effect endTime.
Should it return 0 (technically the mathematical result), null, or undefined when the animation end time is infinite?

Regarding 1. +1 on adding, with 2 suggestions:

Make it read/write. I think it should reflect the currentTime behavior and allow setting progress through this endpoint. It will both be, IMHO, more handy for authors, and if I'm not mistaken, should be necessary for animations with duration: auto.
How about naming it simply progress?

The CSS Working Group just discussed [web-animations-2] Progress APIs, and agreed to the following:

RESOLVED: Add progress to Animation and make it readonly

The full IRC log of that discussion

<faceless> present-
<bramus> flackr: So WAAPI is very focused on absolute times, but with scroll-driven aninamations, developers often just work with progress instead of time
<bramus> flackr: seems like a reasonable thing to add, so there is a proposal to get the current progress which is a calcuation between start and and end time
<bramus> flackr: also need to specify what hsould happen for infinitely repeating animations
<bramus> flackr: Proposal is adding currentProgress to Animation
<bramus> flackr: it is calculated as currentTime / effect endTime
<bramus> flackr: propose to make it readonly for now
<bramus> s/repeating/duration/
<bramus> Rossen_: Any feedback?
<ydaniv> I proposed "progress" instead of "currentProgress"
<TabAtkins> +1
<TabAtkins> (to the current proposal, no opinion on naming)
<bramus> Rossen_: You are taking into account the feedback from ydaniv?
<bramus> flackr: Yes, he proposed currentProgress instead of progress
<bramus> flackr: dont object to this shorter name and computedTIming value from the effect is also called progress
<bramus> Rossen_: what about read/write vs readonly?
<bramus> flackr: then have to decide how to handle infinite duration animation
<bramus> Rossen_: starting with readonly gives up path to go forward later
<bramus> Rossen_: Should we formulate as readonly? not hearing objections from yehonathan
<bramus> flackr: would be happy with that
<bramus> bramus: me too
<bramus> Rossen_: objections to adding as readonly?
<bramus> Rossen_: Not hearing anything
<bramus> bramus: and the name?
<bramus> flackr: we said progress
<bramus> flackr: Proposed resolution: add progress to Animation and make it readonly
<bramus> RESOLVED: Add progress to Animation and make it readonly

@DavMila

On the PR from @DavMila there is one point where we don't have a clear answer. Should the progress be clamped to [0, 1]. For the full discussion you can view the PR review #9937 (comment) however I'll do my best to summarize the pros and cons of each.

Don't clamp the progress. This makes it similar to the currentTime which progress exists alongside (which also can be negative or greater than end time) and is the natural result of the expressed formula. This could be useful for example to distinguish between being at the start time (progress = 0) where the effect is active and visibly shown, and being before the start time (progress < 0) where the effect is not applied (unless fill = backwards | both). However, this also means that to correctly reflect the progress for 0 duration animations we would likely have to return -Infinity and Infinity when you are before or at/after the start time respectively.
Clamp the progress to [0, 1]. A developer won't be able to tell when at 0 progress whether the animation is active or not without also checking whether the currentTime is less than the start time. We could consider adding another member to animation to reflect this in the future.

Ultimately, I think either works, but which is better comes back to how authors will use this. @bramus @fantasai @birtles any thoughts?

I'm leaning towards 2, since this will probably be used to sync a scroll/view timeline with another effect that can't be done with CSS, e.g.: canvas, SVG, video.

So, I think that as default behavior, having this perform as a sort of "manual" CustomEffect, with a clamped progress like KeyframeEffect's is a good way to start, and we could add a new property in the future, like you said, to reflect the more complex cases.

I agree that 2 makes most sense. I also think, as per the current PR, we shouldn't try to reflect the fill mode of the associated effect.

@bramus

However, if we consider the above use-cases, having enter/exit events on the animations, similar requested by @bramus on #7962 may become quite crucial for easily creating such effects without extra IntersectionObserver or scroll handler.
Although you can currently get a similar outcome with start/end events on CSS Animations like here: https://jsbin.com/jizahopixe/edit?css,js,console,output
I think it's currently not possible to achieve with WAAPI.

[web-animations-2] Change progress to overallProgress

Can we add these APIs to CSS?

Can we add these APIs to CSS?

Do you mean to the CSSAnimation interface? It inherits from Animation, so naturally yes.

[web-animations-2] Change progress to overallProgress (#11184)

I'm making the required WPT change also in web-platform-tests/wpt#49353.

Rename Animation.progress to Animation.overallProgress

Bug 1933609 [wpt PR 49385] - Rename Animation.progress to Animation.o…

Bug 1933609 [wpt PR 49385] - Rename Animation.progress to Animation.o…

@flackr

@flackr @DavMila can we close this one?

@flackr @DavMila can we close this one?

Yes we can. I don't believe there's any outstanding issue.

Navigation Menu

Repository navigation

[web-animations-2] Progress APIs #8799

17 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[web-animations-2] Progress APIs #8799

Description

Activity

birtles commented on May 6, 2023

flackr commented on May 10, 2023

bramus commented on May 12, 2023

flackr commented on May 12, 2023

ydaniv commented on May 13, 2023

css-meeting-bot commented on May 24, 2023

flackr commented on Feb 29, 2024

ydaniv commented on Feb 29, 2024

birtles commented on Feb 29, 2024

ydaniv commented on Mar 1, 2024

17 remaining items

yisibl commented on Nov 13, 2024

ydaniv commented on Nov 13, 2024

graouts commented on Nov 25, 2024

ydaniv commented on Jan 26, 2025

DavMila commented on Jan 27, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions