[scroll-animations] let source be explicitly nullable (w3c#5202, w3c#5211) (w3c#5263)

Fixing w3c#5202 and w3c#5211

Changes:
- Fix IDL to make source nullable.
- In CSS source will accept 'auto' and 'none' with none mapping to null.
- In JS, we now map missing 'source' to document scrolling element (i.e., auto behavior) and explicitly null 'source' to null.
- Correctly check null source when calculating offsets.

Other minor cleanups.

Author: majido

scroll-animations-1/Overview.bs

@@ -359,7 +359,7 @@ dictionary ScrollTimelineOptions {
 [Exposed=Window]
 interface ScrollTimeline : AnimationTimeline {
   constructor(optional ScrollTimelineOptions options = {});
-  readonly attribute Element source;
+  readonly attribute Element? source;
   readonly attribute ScrollDirection orientation;
   readonly attribute (DOMString or ElementBasedOffset) start;
   readonly attribute (DOMString or ElementBasedOffset) end;
@@ -378,24 +378,28 @@ determined not by wall-clock time, but by the progress of scrolling in a
 :   <dfn constructor for=ScrollTimeline lt="ScrollTimeline(options)">ScrollTimeline(options)</dfn>
 ::  Creates a new {{ScrollTimeline}} object using the following procedure:
 
-    1. Let |timeline| be a new {{ScrollTimeline}} object.
+    1.  Let |timeline| be a new {{ScrollTimeline}} object.
 
-    1. Let |source| be the result corresponding to the first matching condition from below.
+    1.  Let |source| be the result corresponding to the first matching condition
+        from the following:
 
-        : If the |source| value of |options| is non-null,
-        :: Let |source| be |source|
+        <div class="switch">
 
-        : Otherwise (|source| is null),
-        :: Let |source| be the {{scrollingElement}} of the {{Document}} <a lt="document associated with a window">associated</a> with the {{Window}} that is the <a>current global object</a>.
+        :   If the <code>source</code> member of |options| is missing,
+        ::  The {{scrollingElement}} of the {{Document}} <a lt="document
+            associated with a window">associated</a> with the {{Window}} that is
+            the <a>current global object</a>.
 
-        Note: |source| may still be null after this step, e.g. if the {{Document}} has no {{scrollingElement}}.
+        :   Otherwise,
+        ::  The <code>source</code> member of |options|.
 
-    1. Set the {{ScrollTimeline/source}} of |timeline| to |source|.
+        </div>
 
-    1. Assign the {{ScrollTimeline/orientation}}, {{ScrollTimeline/start}}, {{ScrollTimeline/end}}, and {{ScrollTimeline/timeRange}} properties of |timeline| to the corresponding value from |options|.
+    1.  Set the {{ScrollTimeline/source}} of |timeline| to |source|.
 
-Issue(5202): The above steps need clarification, particularly with regards to
-handling of null values for |source|.
+    1.  Assign the {{ScrollTimeline/orientation}}, {{ScrollTimeline/start}},
+        {{ScrollTimeline/end}}, and {{ScrollTimeline/timeRange}} properties of
+        |timeline| to the corresponding value from |options|.
 
 </div>
 
@@ -433,7 +437,7 @@ handling of null values for |source|.
     {{start}} to {{end}}, to the [=effective time range=].
 
 Issue(4862): We are working to remove the need for {{timeRange}} to be declared.
-The most recent work on this involved introduction of the concept of 
+The most recent work on this involved introduction of the concept of
 "progress-based animations" to web animations.
 
 </div>
@@ -471,18 +475,26 @@ one the following values:
 The procedure to <dfn>resolve a container-based offset</dfn> given
 <var>offset</var> is as follows:
 
-1.  [=effective scroll offset=] is the scroll offset corresponding to the first
-    matching condition from the following:
+1.  If <em>any</em> of the following are true:
+
+    * {{source}} is null, or
+    * {{source}} does not currently have a [=CSS layout box=], or
+    * {{source}}'s layout box is not a [=scroll container=].
+
+    The [=effective scroll offset=] is null and abort remaining steps.
+
+1.  The [=effective scroll offset=] is the scroll offset corresponding to the
+    first matching condition from the following:
     <div class="switch">
 
-    :  <var>offset</var> is <code>auto</code>
-    ::  Either the beginning or the ending of {{source}}'s scroll range
-        in {{orientation}} depending on whether the offset is {{start}} or {{end}}.
+    :   <var>offset</var> is <code>auto</code>
+    ::  Either the beginning or the ending of {{source}}'s scroll range in
+        {{orientation}} depending on whether the offset is {{start}} or {{end}}.
 
     :   <var>offset</var> is a <<length-percentage>>
-    ::  The distance indicated by the value along {{source}}'s scroll range in {{orientation}} as
-        expressed by absolute length, a percentage, or a ''calc()'' expression that resolves to a
-        <<length>>.
+    ::  The distance indicated by the value along {{source}}'s scroll range in
+        {{orientation}} as expressed by absolute length, a percentage, or a
+        ''calc()'' expression that resolves to a <<length>>.
 
     </div>
 
@@ -536,22 +548,27 @@ checked anywhere.
 The procedure to <dfn>resolve an element-based offset</dfn> given
 <var>offset</var> is as follows:
 
-1.  If {{source}} is null,
-    does not currently have a [=CSS layout box=],
-    or if its layout box is not a [=scroll container=],
-    abort the following steps
-    since then the [=effective scroll offset=] is null.
+1.  If <em>any</em> of the following are true:
+
+    * {{source}} is null, or
+    * {{source}} does not currently have a [=CSS layout box=], or
+    * {{source}}'s layout box is not a [=scroll container=].
+
+    The [=effective scroll offset=] is null and abort remaining steps.
 
 1.  Let <var>target</var> be <var>offset</var>'s {{target}}.
 
-1.  If <var>target</var> is null or
-    does not currently have a [=CSS layout box=],
-    abort the following steps
-    since then the [=effective scroll offset=] is null.
+1.  If <em>any</em> of the following are true:
+
+    * <var>target</var> is null, or
+    * <var>target</var> does not currently have a [=CSS layout box=].
+
+    The [=effective scroll offset=] is null and abort remaining steps.
+
 
 1.  If <var>target</var> 's nearest [=scroll container=] ancestor
     is not {{source}}
-    abort the following steps
+    abort remaining steps
     since the [=effective scroll offset=] is null.
 
 1.  Let <var>container box</var> be the {{source}}'s [=scrollport=].
@@ -809,7 +826,7 @@ the names are fully case-sensitive; two names are equal only if they are
 codepoint-by-codepoint equal. The <<custom-ident>> additionally excludes the
 none keyword.
 
-Once specified, a scroll timeline may be associated with a CSS Animation 
+Once specified, a scroll timeline may be associated with a CSS Animation
 [[CSS3-ANIMATIONS]] by using the 'animation-timeline' property.
 
 The <<declaration-list>> inside of ''@scroll-timeline'' rule can only contain the
@@ -826,19 +843,32 @@ Issue(5167): This will likely change in the future.
 <pre class='descdef'>
   Name: source
   For: @scroll-timeline
-  Value: selector(<<id-selector>>) | none
-  Initial: none
+  Value: selector(<<id-selector>>) | auto | none
+  Initial: auto
 </pre>
 
-'source' descriptor determines the scroll timeline's {{source}}. If specified as
-a 'selector()' the scroll timeline's {{source}} is the [=scroll container=]
-identified by the <<id-selector>>, otherwise if not specified or none then it is
-the the {{scrollingElement}} of the {{Document}} <a lt="document associated with
-a window">associated</a> with the {{Window}} that is the <a>current global
-object</a>.
+'source' descriptor determines the scroll timeline's {{source}}.
+
+The value of {{source}} is the result corresponding to the first matching
+condition from the following:
+
+<div class="switch">
+
+:   If 'source' is a 'selector()'
+::  The [=scroll container=] identified by the <<id-selector>>.
+
+:   If 'source' is <code>auto</code>
+::  The {{scrollingElement}} of the {{Document}} <a lt="document associated with
+    a window">associated</a> with the {{Window}} that is the
+    <a>current global object</a>.
+
+:   Otherwise ('source' is <code>none</code>)
+::  null.
+
+</div>
 
-Issue(4338): consider choosing animation target's nearest scrollable ancestor
-instead of document's scrolling Element
+Issue(4338): Consider choosing animation target's nearest scrollable ancestor
+instead of document's scrolling Element for <code>auto</code>.
 
 <pre class='descdef'>
   Name: orientation
@@ -903,7 +933,8 @@ interface CSSScrollTimelineRule : CSSRule {
 
   <dt><dfn>source</dfn></dt>
   <dd>
-    The 'source' descriptor associated with the ''@scroll-timeline'', or "none" if not specified.
+    The 'source' descriptor associated with the ''@scroll-timeline'', or "auto"
+    if not specified.
   </dd>
 
   <dt><dfn>orientation</dfn></dt>