[css-animations-2] Specify the interaction between API methods and animation-* properties

[birtles]

This is something we've discussed a number of times and the general consensus is that once you tweak a property from the API, any changes to the corresponding markup (animation-* property or @keyframes rule) is ignored.

Furthermore, the proposal is that this should apply to animation play state too (rather than the very convoluted behavior that is currently specced where pause is sticky but play is not).

Once interesting edge case with regards to play state is setting the startTime of an animation since that is equivalent to pausing or playing in some cases.

e.g. (1) - no change to play state

div.style.animation = 'anim 10s';
const animation = div.getAnimations()[0];
await animation.ready;
// Seek using the start time. This should probably NOT override animation-play-state.
animation.startTime += 1000;
// This should probably make the animation paused
div.style.animationPlayState = 'paused';

e.g. (2) - play state is changed

div.style.animation = 'anim 10s';
const animation = div.getAnimations()[0];
await animation.ready;
// Pause using the start time
animation.startTime = null;
// This will have no effect since the animation is already paused
div.style.animationPlayState = 'paused';
getComputedStyle(div).animationPlayState;
// This should probably have no effect since the author has taken over
// play control of the animation?
div.style.animationPlayState = 'running';

That's my intuition anyway. What do others think?

I'm looking to spec this in the next few days so any feedback would be much appreciated.

/cc @graouts @stephenmcgruer @flackr @kevers-google

[kevers-google]

Basing stickiness on whether a web-animation API call changes the play state makes sense. This change would also address reverse from a paused state, or playbackRate in an onfinish handler.

[birtles]

Basing stickiness on whether a web-animation API call changes the play state makes sense. This change would also address reverse from a paused state, or playbackRate in an onfinish handler.

Currently what I have in mind (and what I am implementing in Firefox) is that for startTime and reverse(), we simply detect a change between paused and any state that is not paused. For play() and pause() they always unconditionally trigger the "play state is being overridden by API" behavior.

That is, setting the startTime such that an animation goes from finished to running would not trigger the "play state is being overridden by API" behavior.

What do you think?

[birtles]

Thinking about this a little further, I think I would be ok with startTime and reverse() not triggering the override behavior. It does feel a little magical to have these sometimes trigger the override behavior and sometimes not. I'd be curious to hear what others prefer.

[flackr]

Just to be clear, does this example (from your original post) still pause, but just not set the sticky override?

div.style.animation = 'anim 10s';
const animation = div.getAnimations()[0];
await animation.ready;
// Pause using the start time
animation.startTime = null;

[flackr]

To expediate the discussion:

If the above pauses, the div.style.animationPlayState would still resolve to running, so we would have to have some level of stickiness in order to ensure the pause, right?

Then does flipping it cause the animation to start running?

div.style.animationPlayState = 'paused';
animation.playState; // still paused, style flushed
div.style.animationPlayState = 'running';
// is it now running?

If the above doesn't pause, then setting the start time has no effect?

[birtles]

Just to be clear, does this example (from your original post) still pause, but just not set the sticky override?

Yes, that's right. This is purely about the override behavior.

If the above pauses, the div.style.animationPlayState would still resolve to running, so we would have to have some level of stickiness in order to ensure the pause, right?

Right, the proposal is that we use the same "stickiness" for timing properties that map to CSS animation-* properties. That is, once you override them from the API, we ignore the value set via style, even if it changes.

Until I write up the spec text for this (hopefully today), it might be easiest to follow by looking at the patches / tests I just landed for this in Mozilla bug 1459536.

Then does flipping it cause the animation to start running?

Flipping it does not cause the animation to start running. Once overridden, always overridden.

[flackr]

Thinking about this a little further, I think I would be ok with startTime and reverse() not triggering the override behavior. It does feel a little magical to have these sometimes trigger the override behavior and sometimes not. I'd be curious to hear what others prefer.

I think there may have been a confusion - i meant to refer to this comment ^.

I think that it probably should be sticky as it seems less confusing than having the properties not work as expected.

[birtles]

Ok, let me check I understand.

The original proposal is:

1. Calling setKeyframes() means that any subsequent changes to @keyframes will be ignored.
2. Calling updateTiming() means that any subsequent changes to the set properties will be ignored. (i.e. calling updateTiming({ duration: 1000 }) means subsequent changes to animation-duration will be ignored, but changes to animation-delay will still be reflected).
3. Calling play() or pause() means that any subsequent changes to animation-play-state will be ignored.
4. Calling reverse() or setting the startTime means that any subsequent changes to animation-play-state will be ignored, but only if the call to reverse() or startTime resulted in the animation transitioning to or from the 'paused' play state.

The point I was wondering about was whether we drop point 4 altogether or simply the condition from point 4.

[birtles]

The point I was wondering about was whether we drop point 4 altogether or simply the condition from point 4.

As I understand, your comment that "it should probably be sticky", would mean we should not drop point 4 altogether. Either we should keep it, or we should modify it so that it is unconditional.

I'm a little averse to making it unconditional since I can imagine people wanting to reverse() an animation while still keeping it responsive to animation-play-state. That would suggest sticking with the original proposal.

(And I forgot to include in the original proposal that replacing animation.effect altogether means that all changes to animation-* properties other than animation-name and animation-play-state, and all changes to @keyframes rules other than dropping the last matching @keyframes rule, would be ignored.)

[flackr]

The point I was wondering about was whether we drop point 4 altogether or simply the condition from point 4.

As I understand, your comment that "it should probably be sticky", would mean we should not drop point 4 altogether. Either we should keep it, or we should modify it so that it is unconditional.

Correct, that is what I was suggesting.

I'm a little averse to making it unconditional since I can imagine people wanting to reverse() an animation while still keeping it responsive to animation-play-state. That would suggest sticking with the original proposal.

Agreed. It's a little magical, but I think trying to avoid it has stranger ramifications.

(And I forgot to include in the original proposal that replacing animation.effect altogether means that all changes to animation-* properties other than animation-name and animation-play-state, and all changes to @keyframes rules other than dropping the last matching @keyframes rule, would be ignored.)

I think this is reasonable.

[birtles]

I started working on this today over at: birtles@83dd532

I didn't quite finish it but hopefully the outline is mostly there. Please take a look when you get a chance. I hope to finish it off tomorrow.

[birtles]

I went ahead and merged my work on this. It's not perfect but it's better than nothing and I've spent quite a while on it by now. (I was really hoping someone else would step in to do this.)

Hopefully we can tweak it from here.

[kevers-google]

What is the expected override behavior in the following case:

div.style.animation = 'anim 100s';
const animation = div.getAnimations()[0];
div.style.animationPlayState = 'paused';
reverse();
div.style.animationPlayState = 'paused';

Should reverse override animationPlayState since going from a pending pause state to pending play? In other words, should reverse and startTime be flushing any pending changes to play state? Admittedly a very contrived case.

[birtles]

Should reverse override animationPlayState since going from a pending pause state to pending play? In other words, should reverse and startTime be flushing any pending changes to play state?

I think they probably should. The spec wording...

...all operations included in programming interface defined in this specification, as well as those operations defined in Web Animations [WEB-ANIMATIONS] that may return objects or animation state defined by this specification, must produce a result consistent with having fully processed any such pending changes to computed values.

is not 100% clear, but the intention is that all these methods operate on a fully-updated state. It's somewhat unfortunate to have to make all these methods flush, but I think that's the most understandable behavior.

Also, it's quite possible Firefox doesn't flush for reverse() or startTime yet. Last week I just fixed it to flush for getTiming() and getComputedTiming(), but I didn't check reverse().