[web-animations-1] Add parameter for fetching all animations on a subtree (w3c#3902)

This fixes w3c#2058.

Author: birtles

web-animations-1/Overview.bs

@@ -5717,11 +5717,16 @@ the {{Animatable}} interface mixin.
 interface mixin Animatable {
     Animation           animate (object? keyframes,
                                  optional (unrestricted double or KeyframeAnimationOptions) options);
-    sequence<Animation> getAnimations ();
+    sequence<Animation> getAnimations (optional GetAnimationsOptions options);
 };
+
 dictionary KeyframeAnimationOptions : KeyframeEffectOptions {
     DOMString id = "";
 };
+
+dictionary GetAnimationsOptions {
+  boolean subtree = false;
+};
 </pre>
 
 <div class="methods">
@@ -5790,11 +5795,14 @@ animation.play();</pre>
 
     </div>
 
-:   <dfn method for=Animatable lt="getAnimations()">
-    sequence&lt;Animation&gt; getAnimations()</dfn>
+:   <dfn method for=Animatable lt="getAnimations(options)">
+    sequence&lt;Animation&gt; getAnimations(options)</dfn>
 ::  Returns the set of [=relevant=] {{Animation}} objects
     that contain at least one <a>animation effect</a> whose
-    <a>target element</a> is this object.
+    <a>target element</a> is this object, or,
+    if an {{Animatable/getAnimations(options)/options}} parameter
+    is passed with {{GetAnimationsOptions/subtree}} set to true,
+    an [=inclusive descendant=] of this object.
 
     An [=animation=] is
     <dfn lt="relevant animation" local-lt="relevant">relevant</dfn> if:
@@ -5803,6 +5811,10 @@ animation.play();</pre>
         <em>and</em>
     * Its [=replace state=] is <em>not</em> [=removed replace state|removed=].
 
+    For the purposes of this method
+    a [=pseudo-element=] is considered to be
+    a [=child=] of its [=originating element=].
+
     The returned list is sorted using the composite order described
     for the associated <a>animations</a> of effects in [[#the-effect-stack]].
 
@@ -5812,6 +5824,15 @@ animation.play();</pre>
     any pending style changes to animation such as changes to animation-related
     style properties that have yet to be processed.
 
+    <div class="parameters">
+
+    :   <dfn argument for="Animatable/getAnimations(options)"
+        lt="options">options</dfn>
+    ::  Parameters governing the set of animations returned by
+        {{Animatable/getAnimations()}}.
+
+    </div>
+
 </div>
 
 <div class="members">
@@ -5820,6 +5841,12 @@ animation.play();</pre>
 ::  The string to assign to the generated {{Animation}}'s {{Animation/id}}
     attribute.
 
+:   <dfn dict-member for=GetAnimationsOptions>subtree</dfn>
+::  If true, indicates that [=animations=] associated with an
+    [=animation effect=] whose [=target element=] is a [=descendant=]
+    of the object on which {{Animatable/getAnimations()}} is called should also
+    be included in the result.
+
 </div>
 
 <h3 id="extensions-to-the-document-interface">Extensions to the <code>Document</code> interface</h3>
@@ -6189,6 +6216,9 @@ The following changes have been made since the <a
         {{Animation/persist}}.
 *   Added the {{Animation/commitStyles}} method to the {{Animation}} interface
     to allow preserving the result of an [=animation=] that has been removed.
+*   Added an {{Animatable/getAnimations(options)/options}} parameter to the
+    {{Animatable/getAnimations()}} method on the {{Animatable}} interface
+    to allow fetching all animations on descendants of a particular element.
 
 The <a
   href="https://github.com/w3c/csswg-drafts/commits/master/web-animations-1">changelog</a>