[web-animations-1] Add advice about not using indefinitely filling animations (w3c#3901)

Author: birtles

web-animations-1/Overview.bs

@@ -2345,6 +2345,67 @@ The possible <a>fill modes</a> are:
 The normative definition of these modes is incorporated in the
 calculation of the <a>active time</a> in [[#calculating-the-active-time]].
 
+<div class=advisement>
+<p>
+Authors are discouraged from using [=fill modes=] to produce animations whose
+effect is applied indefinitely.
+[=Fill modes=] were introduced in order to represent the 'animation-fill-mode'
+property defined by CSS animations [[CSS-ANIMATIONS-1]].
+However, they produce situations where animation state would be accumulated
+indefinitely necessitating the automatic removal of animations defined in
+[[#replacing-animations]].
+Furthermore, indefinitely filling animations can cause changes to specified
+style to be ineffective long after all animations have completed since the
+animation style takes precedence in the CSS cascade [[css-cascade-3]].
+</p>
+
+<p>
+Where possible, authors should prefer to set the final state of the animation
+directly in specified style.
+This can be achieved by waiting for the animation to finish and then updating
+the style as illustrated below:
+</p>
+
+<div class="example"><pre class="lang-javascript">
+// In the first frame after the following animation finishes, the callback for
+// the `finished` promise will run BEFORE style is updated and hence will NOT
+// flicker.
+elem.animate({ transform: 'translateY(100px)' }, 200).finished(() => {
+  elem.style.transform = 'translateY(100px)';
+});
+</pre></div>
+
+<p>
+Alternatively, the author may set the specified style at the start of the
+animation and then animate <em>from</em> the original value
+as illustrated below:
+</p>
+
+<div class="example"><pre class="lang-javascript">
+elem.style.transform = 'translateY(100px)';
+elem.animate({ transform: 'none', offset: 0 }, 200);
+</pre></div>
+
+Complex effects involving layering many animations on top of one another may
+require temporary use of forwards fill modes to capture the final value of an
+animation before canceling it.
+For example:
+
+<div class="example"><pre class="lang-javascript">
+elem.addEventListener('click', async evt => {
+  const animation = elem.animate(
+    { transform: `translate(${evt.clientX}px, ${evt.clientY}px)` },
+    { duration: 800, fill: 'forwards' }
+  );
+  await animation.finished;
+  // commitStyles will record the style up to and including `animation` and
+  // update elem's specified style with the result.
+  animation.commitStyles();
+  animation.cancel();
+});
+</pre></div>
+</div>
+
 <h4 id="fill-modes">Fill modes</h4>
 
 <div class='informative-bg'><em>This section is non-normative</em>
@@ -3719,7 +3780,7 @@ For example, consider the following code:
 <div class="example"><pre class="lang-javascript">
 elem.addEventListener('mousemove', evt => {
   circle.animate(
-    { transform: `translate(${evt.clientX}, ${evt.clientY})` },
+    { transform: `translate(${evt.clientX}px, ${evt.clientY}px)` },
     { duration: 500, fill: 'forwards' }
   );
 });
@@ -4413,6 +4474,11 @@ dictionary OptionalEffectTiming {
 
     </div>
 
+    <div class=advisement>
+    As described in [[#fill-behavior]], authors are discouraged from using
+    indefinitely filling animations.
+    </div>
+
 :   <dfn dict-member for=EffectTiming>iterationStart</dfn><dfn dict-member
     for=OptionalEffectTiming lt=iterationStart></dfn>
 ::  The <a>animation effect</a>'s <a>iteration start</a> property which is a
@@ -4956,8 +5022,11 @@ It is possible to create an animation that simply sets a property
 without any interpolation as follows:
 
 <div class='example'><pre class='lang-javascript'>
-var effect = new KeyframeEffect(elem, { visibility: 'hidden' }, { fill: 'forwards' });</pre></div>
+var effect =
+  new KeyframeEffect(elem, { visibility: 'hidden' }, { fill: 'forwards' });</pre></div>
 
+As described in [[#fill-behavior]] however, using indefinitely filling
+animations in this way is discouraged.
 
 Having created a {{KeyframeEffect}}, it can be played by adding it to
 an {{Animation}} and then playing that animation.