Re: [csswg-drafts] [web-animations-1] Web Animations Proposal: Add `Animation.started` and `Animation.playing` promises (#5871)

## Related Proposals

1. [[web-animations-2] animation (or effect) start and iteration events #4461](https://github.com/w3c/csswg-drafts/issues/4461)
2. [[scroll-animations] Should animation events fire every time active range is left / reentered? #4324](https://github.com/w3c/csswg-drafts/issues/4324)

## Motivation & Use Cases

Often, an author needs to synchronize arbitrary code with a web animation. For example, during a few key points in an animation lifecycle, one may need to manipulate the DOM, or initiate network requests, or conditionally trigger other animations, among other things. These key lifecycle points are: 

1. When the animation is finished
2. When the animation is played 
3. When an animation effect begins (i.e. after duration has expired)
4. When an animation effect iterates

There is precedent for the usefulness of such triggers in the existence of: 

[`CSS Animation Events`](https://drafts.csswg.org/css-animations-1/#events):
- `animationstart`
- `animationend`
- `animationiteration`
- `animationcancel`

Authors can already be informed when an animation is finished (case #1 above) via the `Animation.finished` promise but it's currently impossible to be informed about cases 2, 3, and 4

## Promise vs Event

The unhandled cases 2, 3, and 4 from above can be separated into two groups:

### `Animation`

_"2. When the animation is played"_ could be handled in one of two ways:

- `Animation.played` Promise
  --or--
- `animationplay` event

I think there is an argument to be made that `Animation.played` is analogous to `Animation.ready` and, as such, it makes sense to use a Promise. I suppose this would fall under `2.3. More general state transitions` in the [Writing Promise-Using Specifications](https://www.w3.org/2001/tag/doc/promises-guide#when-to-use) document. 

Side note: even after reading the spec a few times and experimenting with the `Animation.ready` promise, I'm still unclear on it's use-case or why a Promise was used versus and event. Perhaps an exploration of that reasoning could help guide a decision for an `Animation.played` Promise.

### `AnimationEffect`

In issue 4461, You wrote:

> If we were to add iteration events they would most naturally become a property of the effects...Initially these events were not added because of performance concerns...since then we've taken a different approach to the requirements for dispatching events for CSS animations that limits events to 1~2 per animation frame. I think that would address some of the performance concerns we previously had

I agree and therefore propose that _"3. When an animation effect begins"_ and _"4. When an animation effect iterates"_ be handled by the following events:

**`AnimationEffectEvent`**

- **`effectstart`**
   The effectstart event occurs at the start of the effect. If there is a delay then this event will fire once the delay period has expired.

- **`effectiteration`**
   The effectiteration event occurs at the end of each iteration of an effect, except when an effectend event would fire at the same time.

- **`effectend`**
   The effectend event occurs when the effect finishes.


_An uneducated guess of what AnimationEffectEvent could look like:_

```cpp
interface AnimationEffectEvent : Event {
  readonly attribute CSSOMString animationEffectName;
  readonly attribute double elapsedTime;
};
```

_This would require adding a new `name` attribute to `AnimationEffect`:_

```cpp
interface AnimationEffect {
    attribute CSSOMString name; /// <--- new
    EffectTiming          getTiming();
    ComputedEffectTiming  getComputedTiming();
    undefined             updateTiming(optional OptionalEffectTiming timing = {});
};
```

## Next Steps

Would it be helpful if I created separate proposals for `AnimationEffectEvent` and/or `Animation.played` ?

-- 
GitHub Notification of comment by kevinbrewster
Please view or discuss this issue at https://github.com/w3c/csswg-drafts/issues/5871#issuecomment-760483314 using your GitHub account


-- 
Sent via github-notify-ml as configured in https://github.com/w3c/github-notify-ml-config

Received on Thursday, 14 January 2021 21:20:10 UTC