[scroll-animations-1] CSSNumberish time values to represent types.

[flackr]

In #6674 the rewritten API uses doubles to represent time values for many of the properties. However, the current scroll-animations-1 spec switched to using CSSNumberish in #4890 when we decided that the different time units should have different types. Using CSSNumberish allows us to avoid accidentally using one type in another context, and we can use doubles for backwards compatibility with time-based animations.

I think we should continue to use CSSNumberish (either pixels or percentages depending on which way we go on #7045) for time values on these scroll timeline animations.

[kevers-google]

Agreed, in fact the lack of units for non-scroll-linked animations has been a source of confusion for some developers who feel more comfortable working in seconds rather than milliseconds.

In sticking with CSSNumberish, we don't have to strictly limit ourselves to percentages or pixels. If we do decide that pixels is an acceptable unit of time (not my preference), we could allow setters to use either unit provided we agree on a canonical form for the corresponding getters and have suitable conversion algorithms in place (straightforward extension of the normalization process used went updating the timeline on a previously non-scroll-based animation).

[flackr]

Another reason to use CSSNumberish is to explain why there would be an automatic conversion if you apply a scroll-timeline to an animation that has a duration in time. If we naively mix units, you would convert milliseconds to pixels which in my opinion is unexpected.

e.g.

<style>
#target {
  animation: slide 2s linear;
}
.scroll-linked {
  animation-timeline: scroll();
}
</style>
<div id="target" class="scroll-linked"></div>

Naively, if we want animation.currentTime to be unit-less pixels, then we would be effectively treating each millisecond as one pixel. However, automatically converting the above animation to a 2000px scroll animation feels awkward. As a developer, I would greatly prefer the above animation either scale to fit the timeline or fail to animate
due to an error mixing units.

[flackr]

@birtles you were instrumental in the original PR where we shifted scroll-animations to use CSSNumberish, let me know if I've missed any reasons why we should use CSSNumberish or if you think we shouldn't.

[birtles]

@birtles you were instrumental in the original PR where we shifted scroll-animations to use CSSNumberish, let me know if I've missed any reasons why we should use CSSNumberish or if you think we shouldn't.

Hi!

I'm afraid I haven't followed too closely the API update so I don't know what would be best. Flicking through the previous discussion about this, I think some of the concerns included:

• loss of information / round-tripping if APIs return percentages resolved to absolute values (perhaps the API has changed such that this is no longer an issue?)
• precision of specifying percentages (i.e. if percentages are specified as values in the range [0, 1] you are more likely run into floating-point issues, e.g. 0.2 + 0.4 === 0.6000000000000001 whereas 20 + 40 === 60). That said, we already use fractions like this for keyframe offsets so I guess it's not an issue.

I think it's probably helpful to think about what we want to do with (1) percentage-based times and (2) absolute-time keyframes in the future and let that inform our decision.

For example, for (1) I think we will want to support group effects where we specify the length of the group (e.g. 1000ms) and then define child keyframe effects that take up, e.g. 50% of that duration, and have a start delay of 25% etc. We've seen requests for that.

In that case, even for a purely time-based animation, it seems we would want to be able to support percentage-based inputs, at least. Would that suggest we should support percentage-based outputs too?

For (2) we've had almost the opposite request: support keyframes with absolute offsets (i.e. time values instead of percentages). See #4907 which includes samples like:

document.querySelector(".box").animate([
    { offset: "0s", opacity: 1 },
    { offset: "1s", opacity: 0 }
  ]); /* No duration needed */

Would supporting that suggest we will end up using CSSNumberish in at least some places in the API anyway?

It's a tough issue! I can see how the pixel-based approach feels simpler and more intuitive in some cases at least, but I wonder if the CSSNumberish approach might be more inline with future directions we want to take the API?

[flackr]

It's a tough issue! I can see how the pixel-based approach feels simpler and more intuitive in some cases at least, but I wonder if the CSSNumberish approach might be more inline with future directions we want to take the API?

Note that whether we go with pixels or percentages is the issue discussed in #7045.

However even if we decide to use a pixel-based approach I still have the same concern that if the currentTime (and other "time" value API's) don't have units on them, it will be tricky to distinguish them and avoid mixing units. Also (as I think you alluded to) it makes it more awkward to support multiple input unit types in the future.

[flackr]

To attempt to summarize, this issue is about what type of value API's like currentTime, or the values in getTiming / getComputedTiming should return. Regardless of whether scroll linked animations return pixels or percentages, the question in this issue is whether they should be double or CSSNumericValue with the corresponding type (but fall back to double when that type is milliseconds for backwards compatibility). The old web animations interface only supported double, but in preparation for ScrollTimeline we updated these interfaces in web-animations-2 to return CSSNumberish.

The advantages of using double are:

• Ease of use - can be directly used in calculations
• Follows existing pattern of unit-less type for animation times in current APIs.
• No errors required as all numbers are assumed to be the same units.

The advantages of CSSNumberish are:

• Can fall back to double for backwards compatibility on time based animations.
• Avoids accidental mixing of types (e.g. anim1.currentTime = anim2.currentTime where types are not equal)
• Can support other types of time in the future (e.g. we may want a different type of timeline to use percentages / lengths)
• Allows sensible implicit conversion to adapt a time based animation to a non-time based timeline.
• We will likely want to support CSSNumberish input anyways as @birtles mentioned above for offsets

I think a discussion would be really helpful to surface whether there are strong reasons for or against one or the other approach.

[css-meeting-bot]

The CSS Working Group just discussed CSSNumberish Time values to represent types, and agreed to the following:

• RESOLVED: Use CSSNumberish for "time" values in Web Animations API

The full IRC log of that discussion

<fantasai> Subtopic: CSSNumberish Time values to represent types
<fantasai> github: https://github.com//issues/7102
<fantasai> flackr: Scroll-linked animations is the first animation feature we're animating that doesn't animate in terms of time values
<fantasai> flackr: takes a scroll position and ultimately turns it into progress in an animation
<fantasai> flackr: but animations APIs let you observe the time, e.g. .currentTime
<fantasai> flackr: so question is whether we should reflect the type of the unit to make it clear to the developer that it's not a time
<fantasai> flackr: or just make it a double, and have the risk of mixing units
<fantasai> flackr: I've outlines the advantages and disadvantages of each approach
<fantasai> flackr: we know that using numbers for non-time values works, that is what we have implemented in Chrome
<TabAtkins> q+
<fantasai> flackr: we'd have to use CSSNumberish in order to use units, so as not to break existing content which uses doubles
<Rossen_> q?
<fantasai> flackr: My preference is CSSNumberish, since that gives us the flexibility to know when different types are being into the system, and raise errors if mixing types
<fantasai> flackr: and we can define conversions, as we have done in current spec, for taking a time-based animation and ...
<fantasai> flackr: rather than using time units as pixels or percentages
<fantasai> TabAtkins: I agree with flackr, keeping the double for representing milliseconds is fine
<fantasai> TabAtkins: reasoable for handling that
<fantasai> TabAtkins: Being able to distinguish the actual CSS types when there is not a clear and obvious answer, and being able to use different CSS units, is bad
<fantasai> TabAtkins: so very in favor of accepting all length units here
<Rossen_> ack TabAtkins
<fantasai> TabAtkins: it wouldn't be possible if using a single type mapping against the double
<fantasai> Rossen_: sounds reasonable
<TabAtkins> s/being able/being unable/
<fantasai> Rossen_: anyone here prefer keeping doubles?
<fantasai> Rossen_: Why were doubles used? Why didn't we use CSSNumberish?
<fantasai> flackr: Legacy. Animations were only in the time domain; I don't think numberic values existed when the API was defined
<fantasai> Rossen_: Sounds like we have a well-articulated path forward, and didn't hear anyone pushing for keeping doubles, so calling for objections
<fantasai> fantasai: Wanted to ask if Birtles had an opinion
<fantasai> flackr: Birtles was reviewing all the changes in Web Animations 2 to make this change
<fantasai> flackr: so this is just checking with the rest of the WG
<fantasai> flackr: unless he changed opinion, expect he's on board
<fantasai> Rossen_: OK, we can take a resolution, and re-open if he has a problem
<fantasai> Rossen_: Didn't hear any objections, so let's resolved
<fantasai> flackr: Brian actually commented on the issue in favor
<fantasai> RESOLVED: Use CSSNumberish for "time" values in Web Animations API