[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)