[scroll-animations] Support progress-based animations on finite timelines

[flackr]

Problem

Currently, when you write an animation based on a ScrollTimeline, you have to provide an arbitrary animation duration, e.g.:

document.getElementById('parallax').animate(
    { transform: ['translateY(0)', 'translateY(100px)']},
    { duration: 10000, // Totally arbitrary!
      fill: 'both',
      timeline: new ScrollTimeline({
          endScrollOffset: '200px'})
    });

By default, ScrollTimeline's auto value for effective scroll range will assume the range of the animation. This means that whatever duration is supplied, scroling from (in this case) 0px to 200px will advance the animation from 0 to 100%. Even worse, having too small of a value entered for duration can result in precision problems (see #4353) due to the microsecond precision on animation timers.

Proposal

Allow omitting the duration for an animation driven by finite timeline.

Concretely:

• Introduce a finite timeline type - whose range must not be infinite.
• If the animation timeline is finite (i.e. ScrollTimeline is finite, DocumentTimeline is not as it has no end value), duration may be omitted for new animations.
• When duration is omitted, the duration will be set to the end value for the timeline.
  • If the timeline has timeRange auto, the animation and timeline will have a duration / timeRange of 100 (i.e. 100%).

For the above example, this would make the following valid:

document.getElementById('parallax').animate(
    { transform: ['translateY(0)', 'translateY(100px)']},
    { fill: 'both',
      timeline: new ScrollTimeline({
          endScrollOffset: '200px'})
    });

And would result in a duration and timeRange of 100 (percent).

Open questions

• Is there a better way to express the non-time based progress fallback? i.e. For ScrollTimeline we could use pixels.
• Are the precision requirements on non time based animations different than time based animations? If not, the default time range for progress animations needs to be large enough to be precise.

Note: This is technically a change of the web-animations, but the reasons for it are due to finite timelines such as ScrollTimeline.

@birtles @graouts @majido WDYT? I can put together a prototype of this in my polyfill and include other examples if it would be helpful.

[flackr]

It may make the automatic range a little less magical when timeRange is unspecified if the default timeRange was 100%. Then the animation could assume 100% (by whatever means we represent that internally) as the duration.

[flackr]

Taking this to its logical conclusion, maybe animations without durations do not actually have a visible local time (from the developer point of view). We could add progress which would return the position within the animation.

[birtles]

Yeah, there's an interesting circular dependency here between timeRange = "auto" meaning, "calculate the timeline range from the animation durations" and this proposal where we calculate the animation duration from the timeline range. So I can understand the desire to hide the time values altogether and let the implementation use whatever units it wants for that.

It does feel like a pretty drastic change to the model, however.

In terms of the API, I wonder if we could make the duration parameter take a number, a string specifying a percentage, or "auto" (which equals "100%"). Likewise for delay values. Then for infinite timelines, define the timeline length as infinity. (Using percentages / "auto" would be useless in that context but it would at least avoid a mode switch.)

You'd still have the problem of what time scale to use, but maybe something arbitrary like 1000 would provide sufficient resolution? 100 might be even better since is represents a percentage better but might not give enough resolution.

I suspect this is worth thinking about in relationship to group effects, however. I can imagine very similar cases for group effects -- e.g. wanting to specify the duration on the group effect and then define child effects as having an offset within that (e.g. start delay of 50% and duration of 25%, or a combination of both -- start delay of 50% and duration of 1s).

We should also check that, whatever solution we arrive at, it's not too hard to swap out a ScrollTimeline for a DocumentTimeline while maintaining the currentTime.

[flackr]

It does feel like a pretty drastic change to the model, however.

I think it touches a lot of surfaces but it doesn't have to change much of the internals.

In terms of the API, I wonder if we could make the duration parameter take a number, a string specifying a percentage, or "auto" (which equals "100%"). Likewise for delay values. Then for infinite timelines, define the timeline length as infinity. (Using percentages / "auto" would be useless in that context but it would at least avoid a mode switch.)

Yes, exactly! For ease of implementation, we can convert to a time value internally.

You'd still have the problem of what time scale to use, but maybe something arbitrary like 1000 would provide sufficient resolution? 100 might be even better since is represents a percentage better but might not give enough resolution.

We could convert whatever internal time scale we use back to a percentage for the user-facing API's. This would allow us to have a better resolution internally without having to actually change all time values to something else. It might make sense to have a precision requirement on progress-bound animations which could be used as guidance by implementers to choose their internal representation.

We might want to use a different unit type when returning values such that time values and percentages don't get mistaken for each other - i.e. return '20%' instead of 20.0 or 0.2 or expose them as different properties (i.e. progress instead of currentTime). This way if a developer assigns currentTime / progress from one animation to another animation it can be interpreted correctly. In fact, for specified times, preserving percentages internally would allow dynamically adapting to changes, e.g.:

let anim = element.animate(
  {opacity: [0, 1]},
  {delay: '20%',
   duration: 5000}
);
anim.effect.updateTiming({duration: 10000}); // delay is scaled appropriately

I suspect this is worth thinking about in relationship to group effects, however. I can imagine very similar cases for group effects -- e.g. wanting to specify the duration on the group effect and then define child effects as having an offset within that (e.g. start delay of 50% and duration of 25%, or a combination of both -- start delay of 50% and duration of 1s).

Agreed. I think it makes perfect sense to allow using progress anywhere a time can be used with the caveat that we'd need to either throw or scale to 0 / Infinity for infinite duration animations.

We should also check that, whatever solution we arrive at, it's not too hard to swap out a ScrollTimeline for a DocumentTimeline while maintaining the currentTime.

I think that for the cases where this makes sense it won't be too hard. If your animation duration is a percentage, then switching to a DocumentTimeline does not make sense. Even if we could preserve the progress there is no concept of at what rate the animation should progress at. Naively I'd suggest in this case we apply the same conversion as for when percentages are specified on DocumentTimeline animations.

So concretely I think it makes sense to try to sort out the answers to the broad questions, and then we can work up a proposal and find the rough edges / gaps.

At a high level

• Add a length to timelines? [1]
• Support percentages where times are currently specified. Percentages on animations are converted to the percentage of their animation's duration, which itself may be a percentage of the timeline duration. When the timeline duration is infinite, anything other than 0 becomes infinite?
• Default animation duration to 'auto' which resolves to 100%.
• When returning currentTime, if the duration is a percentage then return a percentage currentTime.

[1] Presumably the length of a ScrollTimeline is also not a time but instead a percentage (of the total scroll distance or just '100%'?)

[mattgperry]

This is a personal view but for progress I've used 0-1 in Popmotion for years as it's directly applicable, as in it can be passed directly to easing functions, or (ironically) used to get a percentage of a value through direct multiplication.

I also think it's self descriptive and intuitive in a way that integers aren't:

mix(origin, target, 0.5)
// vs
mix(origin, target, 50)

[graouts]

Late to the party (as always) but happy this conversation is happening. I personally think this issue is primordial to a successful specification of ScrollTimeline as having to deal with anything time-related for scrolling feels out of place for page authors.

I really like the general idea of being able to specify a relative value for delay and duration, this will indeed be very useful for time containers.

[majido]

I did some thinking about this proposal and time-keyed Keyframe effect(#4907) one and their implications.

Here I will try to share some of my understanding so far in form of a proposal and explore some more interesting edge cases. Hopefully this will be useful in our F2F discussion to help tease out some
key questions and decisions that need to be made.

Figure1. Visual summary of the changes proposed to the model in each proposal.

Graphviz Dot file

digraph D { label = "Current model"; labelloc = "t";

TL [
shape=invhouse
label=<Timeline
t: 0 to infinity >
]

AN [
shape=diamond
label=<Animation
t: 0 to duration >
]

KFE [
shape=box
label=<Keyframes
p: 0 to 1 >
]

TL -> AN [label=" time" fontcolor=grey]
AN -> KFE [label=" progress" fontcolor=grey]

}

TL;DR

Below are some changes to the web animation model and API that I think will achieves both these usecases. In the new model the animation continues to produce a progress value while it can receive either progress or time from its timeline. Also the keyframes may be keyed by time values but they continue to consume only progress. Later I discuss some of the edge cases associated with these changed.

Summary of proposed changes:

• Allow progress as input/output where time is allowed and vice versa.
  • Animation.{duration, delay, endDelay, currentTime} (currently time)
  • EffectTiming.{duration, delay, endDelay, currentTime} (currently time)
  • ComputedEffectTiming.{localTime, activeDuration} (currently a mix of both)
  • Keyframe offsets (currently progress)
• Timelines are either progress-based (which implies finite) or time-based:
  • ScrollTimeline is a progress-based timeline. In other words, it would produce a progress value but not a time value.
  • DocumentTimeline would be considered a time-based timeline. In other words, it would produce a current time but not a progress value.
• Animations can be configured as either progress-based or time-based but not a mix of both.
  • In other words, both duration and delays should be in the same unit. (later we can explore how this restriction can be relaxed in future)
  • Current time will match this unit.
• Animation would continue converting their current time into simple progress values to be fed into keyframe effect.
• Keyframe effects can be keyed by either progress or time values. When time values are used with the largest value being MAX, and iteration duration is D then we can have the following:
  • D is unspecified => D is assigned to be MAX.
  • D <= MAX => In this case keyframes would be played for a smaller number of iterations as specified since animation only runs for (iterations * D) seconds.
  • D > MAX => In this case once once time is outside of the valid range (iterations * MAX) we clip it.
• In terms of API:
  • Accept timing input as unit less percentages e.g., ‘ duration: 80%’ or time e.g., duration: 800. This allows us to differentiate between them.
  • Computed timing values could be in progress or in time depending on the animation/timeline mode. This is consistent with existing API that has both.

Additional Detail

Sidenote: I use the term progress (e.g., a value in [0, 1]) when referring to progress of animation/timeline and percentage (value in 0% 100%) when referring to a fraction of a whole (which could be time or progress).

Dealing with conflicting modes

When we allow both progress-based and time-based timelines and animations then some combinations of these may not be valid. See the table below:

Timeline	Animation	Keyframe
T	T	T	Valid Note: duration may be left unspecified, if it is specified then it possible that progress > 1 in which case we cap it to 1
		P	Valid <-- **Current Model**
	P	P	**Invalid** Note: Cannot turn t:0->infinity into a progress.
	P	T	Valid
P	T	T	Valid with caveat Note: Each animation converts p:0->1 into t:0->duration with a caveat that duration cannot be infinity.
		P	Valid with the same caveat.
	P	T	Valid
		P	Valid Note: This is the fully progress-based case.

Table1. Valid combination of time-based (T) and progress-based (P) for timeline, animation, keyframe.

So here are the invalid situation in this model with some suggested reasonable behavior for them:

• Assigning a progress-based animation to a document timeline.
  • There is no intrinsic duration for this animation. Set the animation duration to zero (similar to how currently duration ‘auto’ is handled).
• Assigning a time-based animation with infinite duration (iterations: Infinity) to a progress based timeline.

  • It is not meaningful to map a [0, 1] interval into an infinite duration. A safe behavior may be to have animation current time set to 0 and log a warning. (This is already the case for scroll timeline with timeRange: auto.)

  • See below for a discussion on the finite case of this.

Open Questions:

• Is there a meaningful case for changing an animation from a time-based timeline to a progress-based timeline? And does our current behavior support this?

Using progress/percentage in the API

Once we have a progress-based timeline, it obviates the need for specifying animation timings in terms of time but we can simply have them be declared in terms of progress as well. Another alternative is to accept percentages which can be either mapped to time or progress making animation timing relative which is especially nice once we have group effects.

I think here are the main questions:

1. Should we reuse existing attributes e.g., Animation.currentTime and overload them to represent both and values or should we introduce new properties e.g., Animation.currentProgress?
2. What is the type/format that should be used to represent progress? The answer to this may depend on the answer to the above but here are some options to consider:
   1. Progress represented as a double between 0 - 100.
   2. Progress represented as a double between 0 - 1 (e.g., 0.2).
   3. Progress represented as a percentage string (e.g., ‘20%’)
3. Do we have a different style for input timing properties vs computed ones?

The introduction of a new set of properties seems to increase the API surface and make writing generic animation code less ergonomic as devs need to check the animation type and use the right property.

Another consideration is that if we overload the same properties then for input properties we need to have different JS types (e.g., string and double) for percentage/progress and time values so that parsing logic can differentiate them. Also for some output properties reading them from Animation API and using them again with the same API to create a new animation should ideally preserve the semantic. The latter case does not matter for computed output attributes (e.g., Animation.currentTime)

Note that there is some precedent to consider here:

1. Keyframe offset syntax: for these we use a (0-1) progress values for both input and computed offsets in Javascript. Interestingly we use percentages in CSS.
2. ComputedEffectTiming.progress: for these we use a (0-1) progress value.

Having said these I suggest this approach:

Accept timing input (duration, delay,...) as unit less percentages ( duration: '80%') and time (duration: 800). This allows us to differentiate between them based on type. The fact that percentages are unit less means that in future we can resolve them against other time values and they are not limited to representing progress. (If we go with this idea, perhaps we should allow use of percentage for specifying offsets.)

Output computed timing values as double which may be progress or time depending on the animation/timeline mode. This is consistent with existing API that has both except that we now overload the same property. I think this is simple and lends itself to doing math and computation using computed values.

TODO: look into CSSOM Types to see if we should use those instead?

Below is an example of how the above proposal would look like in practice.

// Lets create a progress-based animation with a progress-based timeline (scroll timeline)
Const t = new ScrollTimeline()
const a = $div.animate({opacity: 0}, {duration: '80%', delay: '20%', timeline: t};

// The conversion scheme allows the same to work if I use time values for duration 

const b = $div.animate({opacity: 0}, {duration: 800 , delay: 200, timeline: t};

document.scrollingElement.scrollTop = 100; // assume this scrolls the page half-way.

// Scroll timeline is progress-based
a.timeline.currentTime;  // 0.5

// A is a progress based animation so we return <progress>
a.currentTime;  // 0.5
a.effect.getComputedTiming().localTime; // 0.5

// Progress is one case where we have already use progress
a.effect.getComputedTiming().progress; // 0.375


// B is a time-based animation so we match that and output accordingly
b.currentTime;  // 500
b.effect.getComputedTiming().localTime; // 500
b.effect.getComputedTiming().progress; // 0.375

// What about input values? We maintain the format for them which means they can be reused for another animation without losing their semantic.
a.effect.getTiming().duration; // "80%"
b.effect.getTiming().duration; // 800

Assigning time-based animations to a progress-based timeline

This is an interesting edge case. What happens when we associate a time-based animation with a finite duration to a progress based timeline.

It will be reasonable if this case works as expected. To enable this we need a mapping between progress values to time values. Here is a simple proposal that archives this:

1. Compute animation end time T = max(start delay + active duration + end delay, 0) which will be in time unit.
2. Compute TimeToProgressRatio as 1/T
3. With this ratio all time values can be converted into progress.

Figure2. In this example the _TimeToProgressRatio_ is 1/200 which means 50ms delay gets converted into ‘0.25’ progress value.

This process ensures that the relationship between delay/duration/endDelay is preserved and they have the intended effect. Note that each animation has its own specific _TimeToProgressRatio _so associating another animation to the same timeline does not affect any other animations.

So let’s consider a bit more complex case where there is a time-keyed keyframes involved. Here we first resolve auto/unspecified values against children. In this case we resolve the auto value to 100ms. So the animation end is 150ms which gives us a 0.66 time to percent ratio.

Figure 3. A more complicated scenario involving auto duration and time to progress mapping.

Putting it all together:

1. Resolve any unspecified/auto value based on child effect’s intrinsic values.
2. Compute the animation end time which should be in time or progress units (and not mixed).
3. Convert animation timing units to match timeline:
   1. animation is time-based && timeline is progress-based => if animation end is infinite set time 0 otherwise compute TimeToProgressRatio and convert time to progress per above.
   2. animation is progress-based && timeline is time-based => if DocumentTimeline, set time to 0.
   3. Otherwise no work is necessary.
4. At the end of this step the computed timing values would be either in or in time units and consistent with the timeline units.

What about GroupEffects (TODO/Defer)

There was a suggestion that once we support progress/percentages for timings, we can perhaps use the same for group effects.

I think this can work nicely if we use percentages for input timing properties. For example consider having a child effect duration/delay be specified in percentages.
These get resolved agains the parent group effect duration.

• GroupEffects timing may be unspecified in which case they use intrinsic durations from their children.
• The children effect can use percentages which get resolved against group effect duration.

TODO: Things get more complicated if we mix both of these and create inter-dependencies. This needs more consideration.

Mixing time/progress values in a single Animation (TODO/Defer)

It is not clear to me at this point how or if at all this should work.
I think it is reasonable to not allow this for v1 but relax the restriction if we come up with a good model for it.

[birtles]

Thank you for all the time you put into this. I really appreciate it. I mostly agree but was imaging a slightly different approach, although perhaps it is really just different phrasing.

In the new model the animation continues to produce a progress value while it can receive either progress or time from its timeline.

Nit: We might be saying the same thing but I'm getting confused because animations don't produce progress.

• Animations can be configured as either progress-based or time-based but not a mix of both.

  • In other words, both duration and delays should be in the same unit. (later we can explore how this restriction can be relaxed in future)
  • Current time will match this unit.

• Animation would continue converting their current time into simple progress values to be fed into keyframe effect.

Nit: Likewise here, animations don't have a duration or delay, effects do. Similarly, animations don't convert current time into simple progress, effects do.

But possibly we're still thinking the same thing.

The approach I had in mind is maybe a little more bottom-up however. Something like:

1. Starting with keyframes, then working up to effects, then parent effects, and then animations we pass up an intrinsic duration which is either a time value, or unresolved.
   • For the keyframes, if all the offsets are times, we'd take the maximum value and pass that up. Otherwise, if we have a combination of percentages and times, we'd pass up unresolved.
     (This, incidentally, allows having a mixture of times and percentages in some cases but would require special handling when the resolved offsets would swap positions.)
   • For keyframe effects, if they have a duration specified as a time (or their keyframes produce one), we'd pass that up to the parent effect. Otherwise we'd pass up unresolved.
   • For group effects, we'd use the rules already defined there to calculate an intrinsic duration. E.g. a parallel group would take the max end time of its children, but note that if any of its children had an unresolved duration, it would pass up unresolved. Similarly for sequence effects. Note that these effects can also specify a fixed iteration duration in which case we'd pass that up instead.
   • For the root effect, we pass its intrinsic duration up to the animation.
2. At the animation we negotiate a resolved animation duration something like the following:
   • If the received duration is a time and we have a time-based timeline → Use received time
   • ... received unresolved + time-based timeline → Invalid as per third row in Majid's table. Using infinity might make sense (see below).
   • ... received duration + progress-based timeline → Do mapping as suggested by Majid's "Assigning time-based animations to progress-based timelines"
   • ... received unresolved + progress-based timeline → Use '100%' as duration
3. Pass the resolved duration back down the tree and resolve any unresolved / percentage values.
   • If we're passing down '100%' as the duration then all our computed percentage values will themselves produce percentage values. The currentTime of the animation would also be a percentage.
   • If we're passing down a percentage and we have time based durations at some point we have a problem. We could just treat those times as zero and effectively drop those effects? (That might even be useful as a way of show some effects only when running on a time-based timeline?)

Notes:

• If we were later to introduced fixed-duration time-based timelines, presumably percentage measures would still work then. In that case, the current DocumentTimeline might just be an instance of such a timeline with an infinite duration. In that case, using infinity for the invalid case would make sense (it would be useless, but consistent and understandable).
• I agree with exploring Typed OM for API ideas.

[flackr]

I've updated the pull request to clarify the key points from our discussion. In particular

• The duration of ScrollTimeline is 100%
• start and end delay on an animation with a percentage based iteration duration (i.e. duration: auto on a ScrollTimeline) resolves to 0. This is because we have no time to resolve them against. In the future, we could support percentages here.
• a non-auto iteration duration on a percentage based timeline resolves to 0. In the future we could define magical animation scaling to fit the timeline's duration range.
• The auto iteration duration resolves to 100% / iteration count.
• The time values internally for percentage based animations go from 0 to 1.

I believe this allows developers to use auto duration for now (in fact requires it for scroll timeline since anything else results in a 0 duration animation), and should not conflict with future specifications of how percentage based durations could work as auto is implementing the "filling" behavior that makes sense for unspecified values.

We may want to specify automatic filling behavior if the animation's iteration duration is not auto so that switching a time-based animation to a scroll timeline does the "right thing", let me know.

[flackr]

I believe all of the necessary changes to allow progress-based animations has landed in the spec. Closing this issue.