[web-animations-2] Web animations API for specifying timeline phases in animation options.

[flackr]

As part of #7044 we resolved:

• Add ability to specify start and end delays in terms of position in a named phase position (keyword + percentage), e.g. animation-delay: contain 0%; animation-duration: contain 100% attaches the animation between the 0% and 100% points in the contain phase. (See also https://github.com/w3c/csswg-drafts/issues/4342].)
• Add shorthand that expands a phase name to 0% start delay and 100% end delay. E.g. animation-phase: contain expands to animation-delay: contain 0%; animation-end-delay: contain 100%.

These resolutions specify how in CSS you can target an animation to a particular phase of the view timeline. However, we also need a way to do the same from the web animations API. In particular the options passed for the timing of web animations are EffectTiming and OptionalEffectTiming.

Here are a few options I can think of:

1. The simplest would be to extend the delay and endDelay options to also accept a string specification equivalent to the CSS counterpart (e.g. delay: "enter 20%").
2. Extend delay and endDelay to also accept an object type representing the combination of phase and time, e.g. delay: {phase: "enter", offset: CSS.percentage(20)}.
3. Add new options, e.g. startTime / endTime or phase for specifying the "phase", "time" pairs. We would then have to decide what to do when delay and endDelay are also specified.

[kevers-google]

Leaning towards option 1 as it seems easier for the web developer (less verbose than option 2 and avoids potential confusion due to over-specification with option 3).

[ydaniv]

Also leaning towards 1, as authors expect the css animations and web animations APIs to reflect each other as much as possible.

[flackr]

Option 1 certainly seems the most straightforward, though option 2 is more consistent with the direction we've been trying to move in terms of having full rich types for the things that are expressed as strings in CSS.

Regardless of option (1) or (2), we will still have similar over-specification issues if we also allow specifying non-"auto" durations e.g. #4342. I think we'll just have to choose a precedent - probably try to align this with what happens when you specify left, right and width on an element size.

[flackr]

@birtles @graouts FYI

[flackr]

Another variant of 2 would be a new unit type to represent the phase + percentage pair, e.g. delay: CSS.PhasePercent('enter', 20) - though probably not under CSS given it's not a CSSNumber?

[birtles]

Option 1 seems fine to me. I really want to avoid having phase as a mutable property (1, 2).

We could possibly introduce option 2 (or the variant you mentioned) at a later point if it proves necessary?

[flackr]

I really want to avoid having phase as a mutable property (1, 2).

Yeah I'm hoping to bikeshed that on #7044 or possibly open a specific issue to bikeshed it. I've added a comment there.

[flackr]

The one downside to starting with option 1 is that if this is the string value is what you read back from getTiming then we can't upgrade to option 2 without risking breaking content.

[birtles]

The one downside to starting with option 1 is that if this is the string value is what you read back from getTiming then we can't upgrade to option 2 without risking breaking content.

Yeah, I mean we could introduce parallel properties -- typed and untyped/string-type -- and precedence rules for when they're both set, but then we'd break code that attempts to roundtrip the values, by fetching the timing, setting only the lower precedence one (e.g. the untyped/string-type one), then re-setting it.

[css-meeting-bot]

The CSS Working Group just discussed specifying timeline phases in WAAPI, and agreed to the following:

• RESOLVED: Go with option 2 (object/Typed OM value to specify the phase+offset), details tbd by editors

The full IRC log of that discussion

<TabAtkins> Topic: specifying timeline phases in WAAPI
<TabAtkins> github: https://github.com//issues/7589
<TabAtkins> flackr: We've resolved on a CSS syntax for timeline phases, where you can tie an animation to a phase
<TabAtkins> flackr: But we didn't talk about how this would work in waapi
<TabAtkins> flackr: So, how do you make a WEb Animation that animates in a particular timeline phase?
<TabAtkins> flackr: Main two proposals are (1) extend .delay and .endDelay properties, which map to equivalent css properties
<TabAtkins> flackr: These accept doubles currenty, would need to bea ble to take something expressing a phase+proportion
<TabAtkins> flackr: Advantage of option 1 is it's easy to udnerstand
<TabAtkins> flackr: Option 2 is more in line with the desire to use typed properties in these JS bindings
<TabAtkins> flackr: so we don't ahve to parse strings all the time
<TabAtkins> flackr: I think Brian is on board with either
<Rossen_> q?
<TabAtkins> flackr: I have a slight preference for option 2, as it's more future-proof. Requires some wrapper around the fields, and there's a naming question
<TabAtkins> TabAtkins: I'm fine with option 2, with details tbd by editors
<TabAtkins> Rossen_: reading thru comments, Brian seems to supportive as well
<TabAtkins> flackr: yeah, he doesn't seem worried about the string complexity, but had no objections to option 2
<TabAtkins> Rossen_: so current proposal is option 2
<TabAtkins> Rossen_: Not hearing much other opinions
<TabAtkins> Rossen_: so suggest resolving on the direction
<bramus> SGTM
<TabAtkins> Rossen_: complaints, objections?
<TabAtkins> RESOLVED: Go with option 2 (object/Typed OM value to specify the phase+offset), details tbd by editors