[web-animations-1] Specify requirements on style change events

This fixes w3c#3613.

Author: birtles

web-animations-1/Overview.bs

@@ -176,6 +176,7 @@ urlPrefix: https://drafts.csswg.org/cssom/; type: dfn; spec: cssom
     text: serialize a CSS value
 urlPrefix: https://drafts.csswg.org/css-transitions/; type: dfn; spec: css-transitions-1
     text: events from CSS transitions; url: transition-events
+    text: transitionend
 urlPrefix: https://drafts.csswg.org/css-animations/; type: dfn; spec: css-animations-1
     text: events from CSS animations; url: events
 urlPrefix: https://drafts.csswg.org/css-writing-modes-4/; type: dfn; spec: css-writing-modes-4
@@ -5458,9 +5459,11 @@ animation.play();</pre>
     The returned list is sorted using the composite order described
     for the associated <a>animations</a> of effects in [[#the-effect-stack]].
 
-    The returned list reflects the state <em>after</em> applying any pending
-    changes to animation such as changes to animation-related style properties
-    that have yet to be processed.
+    Calling this method triggers a [=style change event=] for the <a>target
+    element</a>.
+    As a result, the returned list reflects the state <em>after</em> applying
+    any pending style changes to animation such as changes to animation-related
+    style properties that have yet to be processed.
 
 </div>
 
@@ -5504,9 +5507,10 @@ partial interface Document {
     The returned list is sorted using the composite order described
     for the associated <a>animations</a> of effects in [[#the-effect-stack]].
 
-    The returned list reflects the state <em>after</em> applying any pending
-    changes to animation such as changes to animation-related style properties
-    that have yet to be processed.
+    Calling this method triggers a [=style change event=] for the document.
+    As a result, the returned list reflects the state <em>after</em> applying
+    any pending style changes to animation such as changes to animation-related
+    style properties that have yet to be processed.
 
     Issue(2054): Both this method and {{Animatable/getAnimations()}} on the
                  {{Animatable}} interface mixin require retaining
@@ -5605,6 +5609,20 @@ dictionary AnimationPlaybackEventInit : EventInit {
 Changes made to any part of the model, cause the entire timing model to be
 updated and any dependent style.
 
+Unless otherwise stated,
+invoking the methods or constructors,
+or getting or setting the members
+of interfaces defined in the programming interface section of this specification
+does <em>not</em> produce a [=style change event=].
+
+Note: Other specifications that extend this specification are expected to refine
+the requirements on [=style change events=] by introducing circumstances where
+such events <em>are</em> triggered.
+For example,
+when the interfaces in this specification represent
+animations defined by CSS markup,
+many of their methods will need to trigger [=style change events=]
+in order to reflect changes to the specified style.
 
 <div class="informative-bg"><em>This section is non-normative</em>
 
@@ -5703,6 +5721,39 @@ window.requestAnimationFrame(function(now) {
 });</pre>
     </div>
 
+:   Calling methods from this programming interface will generally
+    <em>not</em> cause transitions to be triggered
+
+::  Consider the following example:
+
+    <div class="example">
+    <pre class="lang-javascript">
+// Setup transition start point
+div.style.opacity = '1';
+getComputedStyle(div).opacity;
+
+// Setup transition end point
+div.style.transition = 'opacity 1s';
+div.style.opacity = '0';
+
+// Fire an animation
+div.animate({ opacity: [0.5, 1] }, 500);
+
+// Wait for the transition to end -- the following will never be called!
+div.addEventListener('transitionend', () => {
+  console.log('transitionend');
+});</pre>
+    </div>
+
+    In this case, calling {{Animatable/animate()}} will
+    <em>not</em> trigger a [=style change event=].
+    As a result, the pending style change will be processed at the same time
+    as the style change resulting from the new animation.
+    Since the animation style will override
+    the [=before-change style=] and the [=after-change style=],
+    no transition will be generated and
+    the event handler for the [=transitionend=] event will never be called.
+
 </div>