[scroll-animations-1] Use CSSTypedOM instead of strings (#5213) (#5300)

Use appropriate CSSTypedOM instead of DOMStrings in the API. Fixes #5213.

Changes:
 - For offsets use `CSSNumericValue` or `CSSKeywordish` instead of DOMString
 - When setting the offset, the grammars for these values is check to ensure only the valid subset can be set.
 - When computing effective scroll offset check the offset actual type and interpret it accordingly
 - Update examples to showcase the API and add noted to clarify the usage.

Author: majido

scroll-animations-1/Overview.bs

@@ -19,6 +19,7 @@ Editor: Olga Gerchikov, Microsoft, gerchiko@microsoft.com
 
 Former editor: Mantaroh Yoshinaga
 Former editor: Stephen McGruer, Google, smcgruer@google.com
+Markup Shorthands: markdown yes
 </pre>
 <pre class=anchors>
 urlPrefix: https://w3c.github.io/web-animations/; type: dfn; spec: web-animations
@@ -183,8 +184,8 @@ if (window.matchMedia('(prefers-reduced-motion: no-preference)').matches) {
 
   const collisionTimeline = new ScrollTimeline({
     source: scrollableElement,
-    start: '200px',
-    end: '300px'
+    start: CSS.px(200),
+    end: CSS.px(300)
   });
 
   const left = leftCircle.animate({ transform: 'translate(300px)' }, 1000);
@@ -196,8 +197,8 @@ if (window.matchMedia('(prefers-reduced-motion: no-preference)').matches) {
   const union = unionCircle.animate({ opacity: 1 }, { duration: 1000, fill: "forwards" });
   union.timeline = new ScrollTimeline({
     source: scrollableElement,
-    start: '250px',
-    end: '300px'
+    start: CSS.px(250),
+    end: CSS.px(300)
   });
 }
 </pre>
@@ -230,6 +231,8 @@ this example could be written as follows:
 @media (prefers-reduced-motion: no-preference) {
   @scroll-timeline progress-timeline {
     source: selector(#body);
+    start: 0;
+    end: 100%;
   }
 
   @keyframes progress {
@@ -251,7 +254,10 @@ If we use this API for this case, the example code will be as follow:
 if (window.matchMedia('(prefers-reduced-motion: no-preference)').matches) {
   var animation = div.animate({ width: '100%' }, { duration: 1000, fill: "forwards" });
   animation.timeline = new ScrollTimeline(
-    { start: '0px' }
+    { 
+      start: 0,
+      end: CSS.percent(100)
+    }
   );
 }
 </pre>
@@ -348,11 +354,14 @@ behavior under different directionalities and writing modes.
 <pre class="idl">
 enum ScrollTimelineAutoKeyword { "auto" };
 
+typedef (CSSNumericValue or CSSKeywordish) ContainerBasedOffset;
+typedef (ContainerBasedOffset or ElementBasedOffset) ScrollTimelineOffset;
+
 dictionary ScrollTimelineOptions {
   Element? source = null;
   ScrollDirection orientation = "block";
-  (DOMString or ElementBasedOffset) start = "auto";
-  (DOMString or ElementBasedOffset) end = "auto";
+  ScrollTimelineOffset start = "auto";
+  ScrollTimelineOffset end = "auto";
   (double or ScrollTimelineAutoKeyword) timeRange = "auto";
 };
 
@@ -361,8 +370,8 @@ interface ScrollTimeline : AnimationTimeline {
   constructor(optional ScrollTimelineOptions options = {});
   readonly attribute Element? source;
   readonly attribute ScrollDirection orientation;
-  readonly attribute (DOMString or ElementBasedOffset) start;
-  readonly attribute (DOMString or ElementBasedOffset) end;
+  readonly attribute ScrollTimelineOffset start;
+  readonly attribute ScrollTimelineOffset end;
   readonly attribute (double or ScrollTimelineAutoKeyword) timeRange;
 };
 </pre>
@@ -418,11 +427,48 @@ determined not by wall-clock time, but by the progress of scrolling in a
     offset=] in the direction specified by {{orientation}} that constitutes the
     beginning of the range in which the timeline is active.
 
+    On setting, run the procedure to [=set the offset value=] with the provided
+    value as |val|.
+    
+    
+    The procedure to <dfn>set the offset value</dfn> with |val| as the provided
+    value has the following steps:
+    
+    1.  If |val| is a {{DOMString}}, let |val| be the result of
+        <a lt="rectify a keywordish value">rectifying the keywordish value</a>.
+
+    2.  Set the offset value to be the result corresponding to the first
+        matching condition from the following:
+
+        <div class="switch">
+    
+        :   If |val| is a {{CSSKeywordValue}} and <a lt="match the grammar">
+            matches the grammar</a> `auto`:
+        ::  Return |val|.
+
+        :   If |val| is a {{CSSNumericValue}} and <a lt="match the grammar">
+            matches the grammar</a> <<length-percentage>>:
+        ::  Return |val|.
+
+        :   If |val| is an {{ElementBasedOffset}}:
+        ::  Return |val|.
+
+        :   Otherwise,
+        ::  Do not set the value and throw a {{DOMException}} with error name
+            {{SyntaxError}}.
+
+        </div>
+
+
 :   <dfn attribute for=ScrollTimeline>end</dfn>
 ::  A [=scroll timeline offset=] which determines the [=effective scroll
     offset=] in the direction specified by {{orientation}} that constitutes the
     end of the range in which the timeline is active.
 
+    On setting, run the procedure to [=set the offset value=] with the provided
+    value as |val|.
+
+
 :   <dfn attribute for=ScrollTimeline>timeRange</dfn>
 ::  A time duration that allows mapping between a distance scrolled, and
     quantities specified in time units, such as an animation's [=duration=] and
@@ -465,12 +511,8 @@ the [=effective scroll offset=] that is resolved from {{end}}.
 A <dfn>container-based offset</dfn> is a scroll timeline offset that is declared
 only in relation with the <a>scroll container</a> as specified by {{source}}.
 
-A [=container-based offset=] is provided in the {{DOMString}} form and can have
-one the following values:
-
-*   auto
-*   <<length-percentage>>
-
+A [=container-based offset=] is provided in the {{CSSNumericValue}} or 
+{{CSSKeywordValue}} forms.
 
 The procedure to <dfn>resolve a container-based offset</dfn> given
 <var>offset</var> is as follows:
@@ -487,21 +529,33 @@ The procedure to <dfn>resolve a container-based offset</dfn> given
     first matching condition from the following:
     <div class="switch">
 
-    :   <var>offset</var> is <code>auto</code>
+    :   If <var>offset</var> is a {{CSSKeywordValue}} and
+        <a lt="match the grammar">matches</a> `auto`:
     ::  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>>
+    :   If <var>offset</var> is a {{CSSNumericValue}} and
+        <a lt="match the grammar">matches</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>>.
 
+    :   Otherwise,
+    ::  null.
+
     </div>
 
 Note: The scroll range of an element is the range defined by its minimum and
 maximum scroll offsets which are determined by it [=scrolling box=], [=padding
 box=], and [=overflow direction=].
 
+Note: Container-based scroll offsets cannot be provided as bare numbers but
+should be {{CSSNumericValue}}. This way the full richness of {{CSSNumericValue}}
+APIs can be used to provide the offset in percentages, various length units or
+'calc()' expressions. For example `CSS.percent(50)`, `CSS.px(200)`, or
+`CSS.vh(10)` are valid and represent `50%`, `200px`, and `10vh`.
+
+
 Note: It is valid to provide a length or percentage based offset such that it is
 outside the source's scroll range and thus not reachable e.g., '120%'.