[scroll-animations-1] Percentages vs Pixels for Scroll Timeline Values

[fantasai]

Parts of the ScrollTimeline and ViewTimeline interfaces need to represent values in “time”. In Web Animations 1, this was a raw number representing milliseconds. But for scroll animations, we're operating in a spatial dimension, not the time dimension. What should these “time” values represent?

So far options considered have been:

• progress from the starting scroll position to the ending scroll position
  • additional question in this case is, what represents 100%: 100 or 1.0?
• pixels from the starting scroll position

Web Animations 2 additions to the API allow for values with units, but for compatibility with Web Animations 1 we still need an answer here.

[fantasai]

Here are my arguments for pixel-based.

• The closest analog to what time-based timelines do is to make it represent an absolute length, since they represent absolute time.
• Calculating percentage progress from the absolute offset is easy (and vice versa), but going the other way around makes the API feel like it provides the less fundamental bit of information.
• Having the value of .currentTime changing as layout expands the content of the scroller, even though the scroll position (i.e. the current time in absolute terms) is not changing, feels odd.
• For ViewTimelines, using percentage progress also means that the startTime/endTime values are shifting in indirect and nonlinear ways as the amount of scroller content changes, even if the element does not move or change, which also feels uncomfortable.

(The arguments for percentage-based were around mapping animations from one context to another; I unfortunately can't remember exactly what the use case was.)

[tabatkins]

For the "values change as the size of the scrollable area changes", do those change your scroll-animation progress as well? Or is progress based directly on the scroll value as an absolute length?

I think we should choose the mapping that most closely matches the behavior in this regard.

[flackr]

Web Animations 2 additions to the API allow for values with units, but for compatibility with Web Animations 1 we still need an answer here.

My presumption was that whichever unit we choose, we wouldn't coerce it into double values, and that Scroll Timeline animations would always use typed units (whether it's percentages or pixels). Time-based animations would continue to use double (milliseconds) so as to be backwards compatible with web-animations-1. I filed #7102 to track this.

[flackr]

(The arguments for percentage-based were around mapping animations from one context to another; I unfortunately can't remember exactly what the use case was.)

The arguments for percentage-based are:

• We expect that it will be common for developers to take a time-based animation (i.e. with duration, startDelay and other properties specified) and assign it to a scroll timeline. Converting those times to their relative proportions / percentages of the overall animation length is an easy way to explain how we can support this use case and those times only need to be converted once, rather than every time layout changes.
• Currently, keyframes are specified as percentage offsets, so for most animations the percentage time value will map directly to the value specified as the keyframe offset.
• For ViewTimelines, developers currently often use percentages from IntersectionObserver to track elements entering / exiting the view.
• More directly matches the animation progress, i.e. time value changes when animation progress changes whereas with pixel based the current time may not change even when animation progress changes.

[kevers-google]

A further argument in support of percentages is that I struggle with calling a length based unit a valid time value. Perhaps if we had used a more generic term within the web-animations-1 API we could more easily accommodate different units, but we are locked into using currentTime etc. Percentages can be thought of as a normalized dimensionless time, so this doesn't seem like much of a stretch, but a as a strikes me as odd. Perhaps I'm just being pedantic, but think we should try to avoid a potential obstacle that makes the animation API less intuitive.

I should add that this does not necessarily need to be an either or situation for setters in the API. If using CSSNumberish with setters we could decide to allow for different units, provided there is a simple conversion process and consensus on the units for the getters and calculated timing call. The web-animation-2 spec contains rules for how to convert times to percentages when setting a scroll-timeline to an animation.

[flackr]

For the "values change as the size of the scrollable area changes", do those change your scroll-animation progress as well? Or is progress based directly on the scroll value as an absolute length?

I think we should choose the mapping that most closely matches the behavior in this regard.

@tabatkins Yes, when the values change as the size of the scrollable area changes, your scroll-animation progress also changes. The values are exactly the progress through the scroll animation. Percentage is direct mapping to animation progress.

[flackr]

To summarize, I think we only need to resolve on what the internal time values for scroll linked animations are (i.e. what is returned by currentTime and other API's), as we likely would want to support specified values to include other types (e.g. 100vh for one full viewport of scroll height). Issue #7102 covers whether the API's which access the internal times should return their types.

#7045 (comment) covers the arguments for pixel based time values. #7045 (comment) presents the arguments for percentage based time.

[css-meeting-bot]

The CSS Working Group just discussed Percentages vs Pixels for Scroll Timeline Values, and agreed to the following:

• RESOLVED: Use percentages for scroll-timeline values

The full IRC log of that discussion

<fantasai> subtopic: Percentages vs Pixels for Scroll Timeline Values
<fantasai> github: https://github.com//issues/7045#issuecomment-1081276755
<fantasai> flackr: For scroll-linked animations, now the question is, what is the internal time: is it percentages or lengths?
<TabAtkins> q+
<fantasai> flackr: This would specifically be for the output
<TabAtkins> ack fantasai
<Zakim> fantasai, you wanted to ask about birtles' opinion
<Rossen_> ack fantasai
<fantasai> flackr: This is just for what we report to the developer; can take any type as input regardless
<fantasai> flackr: arguments for each are in the issue, but will try to summarize
<fantasai> flackr: pixel-based is very analogous to the way time works for regular animations
<fantasai> flackr: scroll-timeline is animating over a length
<fantasai> flackr: whereas for percentages, these are pretty much exactly what the animation progress is, which is how devs specify keyframes
<fantasai> flackr: and is closer to intersection-observer API as it relates to view timelines
<bmathwig> q
<fantasai> TabAtkins: Given resolution to the previous issue, is this just about how we should interpret a double in this case or can we return a typed value, and then is it a question of which typed value to return?
<bmathwig> q+
<fantasai> flackr: question of which typed value to return
<Rossen_> ack tantek
<fantasai> flackr: for setters, we could even throw for a double, since time values don't belong in a scroll animation
<Rossen_> ack TabAtkins
<fantasai> TabAtkins: in that case, I suggest if the progress value changes as the scrollable area changes ...
<fantasai> TabAtkins: if you freeze an animation, and you change the scrollable area size, the time value should stay ocnstant
<fantasai> flackr: standard behavior is ... mapping to progress
<fantasai> flackr: if a change in the scrollable length causes a change to the animation progress, using percentages the current time will also change to reflect that change in animation progress, but a length will not
<fantasai> flackr: because would have the same absolute scroll position
<Rossen_> q?
<fantasai> fantasai: I think that's a pretty convincing argument
<Rossen_> ack bmathwig
<fantasai> bmathwig: Just building on what Tab was saying, what are the artifacts that would occur should the case of an infinite scroller and timeline being used, and animation jumps back to a previous keyframe
<fantasai> bmathwig: would that cause a disruption in the continuity and disruption / artifact ?
<fantasai> flackr: I don't think our decision here would affect that. We can accept either type as input
<fantasai> flackr: the current behavior for most of the animation APIs is that you specify keyframes in percentage progress, so until we expand that to express absolute positions in time, won't have discontinuity
<fantasai> flackr: regardless of whether output value is pixels or percentages
<fantasai> bmathwig: OK, then percent is interesting... I don't have an opinion, don't have enough context.
<fantasai> Rossen_: OK, where does that leave us?
<fantasai> flackr: Seems we have slight preference for percentages, because maps directly to animation progress
<fantasai> flackr: if there's no objections, I would resolve on that
<fantasai> flackr: I think we can support both types in terms of specifying values
<fantasai> flackr: which should make it easy for devs to work with this
<fantasai> Rossen_: Should we then try to resolve on percentages?
<bmathwig> +1 for percentages
<fantasai> Rossen_: Any objections for using percentages for scroll timeline values?
<fantasai> RESOLVED: Use percentages for scroll-timeline values