[web-animations-1] Define animation replacing behavior

[birtles]

This fixes #3689.

[birtles]

This still needs work:

• There are three issues in the PR that should probably be addressed before merging
• The wording for the commit styles procedure is very wordy and could almost certainly be improved

I've tried to make the descriptions very general so that they "just work" when we introduce group effects. That's at least partly why some of them are a bit convoluted. (In my experience, the implementation for this is simpler than the spec text.)

For now, though, hopefully this is ready enough for feedback.

[birtles]

I've made all the outstanding changes I had in mind for this PR so it should be ready to review now.

[birtles]

@graouts @stephenmcgruer @flackr review ping?

[flackr]

Can this still result in growing lists? I.e. if we have composite: 'add' transforms might this result in an ever growing transform list or is the effect value the transform matrix? What about filter lists?

[birtles]

Yes, it can. The computed value for transforms is a list, it just happens to be serialized as a single matrix value. For filters too, there is a similar issue.

[flackr]

Should the animation then be removed? Is the replace state change sufficient to imply the animations is removed?

[birtles]

Yes, setting the replace state to removed at the beginning of the procedure is sufficient for it to stop being returned from getAnimations() and stop contributing to the effect stack.

[flackr]

Do you expect that only applying some of the animation styles but not all of them will be a common use case? Might it make sense to start with an API where all properties are applied and allow for upgrading in the future?

[birtles]

Yes, I'm not sure. I added this at @graouts' suggestion but I'm fine with leaving it off and adding it later if that's preferable. (And when I implemented it I made this feature a separate patch to prove it could be incrementally added.)

[graouts]

I think we should start without any arguments and consider adding a list of properties in a future version if we feel it is warranted.

[flackr]

What's the motivation for adding a commit mechanism over a way to retrieve the animation's effective output? I haven't fully thought through the implications but it seems a simpler API to simply pass a dictionary of values with the replace event.

[birtles]

I believe the motivation was simply to avoid authors having to add boilerplate code. Unfortunately, passing a dictionary of values has two problems:

1. It doesn't extend easily to GroupEffects. We'd need to add a Map or something to the event instead, to map from target elements to computed style.

2. It requires us to either always flush style in order to produce the correct computed style for the current frame, or never flush style and return potentially out-of-date style (see examples here).

   At least always flushing style means we only do it once, regardless of how many animations are being removed in the current frame. Perhaps we could even spec that it only happens if there is at least one remove event listener, I'm not sure. Flushing style at that point in the frame might be a bit odd though -- triggering transitions before we run requestAnimationFrame callbacks.

   The advantage of the commitStyles() approach is that, even assuming we make it flush style, the author is in charge of calling it so it won't flush styles unless they use it and the side effects are more understandable. The disadvantage is that it means that if several animations are removed in the same frame, then calling commitStyles() several times will flush and dirty style multiple times.

Having a means to get the computed style of an Animation / AnimationEffect is nice because it might be more generally useful but it doesn't really help avoid the boilerplate @graouts was concerned about.

[flackr]

I'm a little unclear what the state of a removed animation is, i.e. can it be replayed? retargeted? Does it's replace state change if it is?

[birtles]

I'm a little unclear what the state of a removed animation is, i.e. can it be replayed? retargeted? Does it's replace state change if it is?

The replace state is part of the animation model so it's entirely orthogonal to any timing. All it means is that:

1. Its effect(s) won't contribute to the effect stack(s) of their target elements.
2. It won't be returned from getAnimations()

So:

• A removed animation can be replayed and will dispatch the appropriate events etc. It just won't have any affect on style.
• It can be retargeted.
• It won't change replace state when it is retargeted. The only thing that can change its replace state once it is removed is calling persist().

I have a few tests (1, 2, 3) for these things that may or may not be useful in understanding the behavior.

[graouts]

This looks good to me overall, many thanks to you @birtles for all the work putting this together. I look forward to implementing this and possibly providing finer details at that stage.

[birtles]

I've dropped the properties parameter from commitStyles for now.