[scroll-animations-1] Add Element-based offset (w3c#4337) (w3c#5124)

Add basic definition for Element-based offsets

Major changes:
- Introduce concept of "scroll timeline offset" that can be container-based (existing concept) and element-based (new concept).
- Add IDL for the new offset type and use it.
- Define the process for each offset type to be resolved into an effective scroll offset.
- Update current time calculation to resolve offsets and use the effective values.
- Add basic diagram to show the behavior visually for a simple example

Minor changes:
 - Rewrap lines to fit in 80 chars
 - Trim end-of-line whitespace
 - Clarify some definitions

TODO (as follow ups):
 - Define threshold for element-based offset.
 - Add css syntax for element-based offsets.
 - Add more examples.

Author: majido

scroll-animations-1/Overview.bs

@@ -9,7 +9,7 @@ Group: CSSWG
 URL: https://drafts.csswg.org/scroll-animations-1/
 ED: https://drafts.csswg.org/scroll-animations-1/
 Shortname: scroll-animations-1
-Abstract: Defines an API and markup for creating animations that are tied to 
+Abstract: Defines an API and markup for creating animations that are tied to
           the scroll offset of a scroll container.
 Editor: Brian Birtles, Invited Expert, brian@birchill.co.jp, w3cid 43194
 Editor: Botond Ballo, Mozilla, botond@mozilla.com
@@ -32,6 +32,7 @@ urlPrefix: https://w3c.github.io/web-animations/; type: dfn; spec: web-animation
     text: timeline
 urlPrefix: https://drafts.csswg.org/cssom-view/; type: dfn; spec: cssom-view-1
     text: CSS layout box
+    text: overflow direction; url: overflow-directions
 urlPrefix: https://html.spec.whatwg.org/multipage/browsers.html; type: dfn; spec: html
     text: document associated with a window; url: concept-document-window
 </pre>
@@ -216,7 +217,7 @@ Typically, the scroll bar provides this visual indication but
 applications may wish to hide the scroll bar for aesthetic or useability
 reasons.
 
-Using the updated 'animation' shorthand that includes 'animation-timeline', 
+Using the updated 'animation' shorthand that includes 'animation-timeline',
 this example could be written as follows:
 
 <pre class='lang-css'>
@@ -344,8 +345,8 @@ enum ScrollTimelineAutoKeyword { "auto" };
 dictionary ScrollTimelineOptions {
   Element? source = null;
   ScrollDirection orientation = "block";
-  DOMString start = "auto";
-  DOMString end = "auto";
+  (DOMString or ElementBasedOffset) start = "auto";
+  (DOMString or ElementBasedOffset) end = "auto";
   (double or ScrollTimelineAutoKeyword) timeRange = "auto";
 };
 
@@ -360,8 +361,9 @@ interface ScrollTimeline : AnimationTimeline {
 };
 </pre>
 
-A <dfn>scroll timeline</dfn> is an {{AnimationTimeline}} whose time values are determined
-not by wall-clock time, but by the progress of scrolling in a [=scroll container=].
+A <dfn>scroll timeline</dfn> is an {{AnimationTimeline}} whose time values are
+determined not by wall-clock time, but by the progress of scrolling in a
+[=scroll container=].
 
 <div link-for-hint="ScrollTimeline">
 
@@ -391,69 +393,224 @@ not by wall-clock time, but by the progress of scrolling in a [=scroll container
 <div class="attributes">
 
 :   <dfn attribute for=ScrollTimeline>source</dfn>
-::  The scrollable element whose scrolling triggers the activation and drives the
-    progress of the timeline.
+::  The scrollable element whose scrolling triggers the activation and drives
+    the progress of the timeline.
 
 :   <dfn attribute for=ScrollTimeline>orientation</dfn>
-::  Determines the direction of scrolling which triggers the activation and drives
-    the progress of the timeline.
+::  Determines the direction of scrolling which triggers the activation and
+    drives the progress of the timeline.
 
 :   <dfn attribute for=ScrollTimeline>start</dfn>
-::  A scroll offset, in the direction specified by {{orientation}}, which constitutes
-    the beginning of the range in which the timeline is active.
-
-    Recognized values are defined by the following grammar:
-
-    <blockquote>
-      <pre class="prod">auto | <<length>> | <<percentage>></pre>
-    </blockquote>
-
-    The meaning of each value is as follows:
-
-    :   auto
-    ::  The beginning of {{source}}'s scroll range in {{orientation}}.
-    :   <<length>>
-    ::  An absolute distance along {{source}}'s scroll range in {{orientation}}.
-    :   <<percentage>>
-    ::  A percentage distance along {{source}}'s scroll range in {{orientation}}.
+::  A [=scroll timeline offset=] which determines the [=effective scroll
+    offset=] in the direction specified by {{orientation}} that constitutes the
+    beginning of the range in which the timeline is active.
 
 :   <dfn attribute for=ScrollTimeline>end</dfn>
-::  A scroll offset, in the direction specified by {{orientation}}, which constitutes
-    the end of the range in which the timeline is activated.
-
-    Recognized values are defined by the following grammar:
-
-    <blockquote>
-      <pre class="prod">auto | <<length>> | <<percentage>></pre>
-    </blockquote>
-
-    The meaning of each value is as follows:
-
-    :   auto
-    ::  The end of {{source}}'s scroll range in {{orientation}}.
-    :   <<length>>
-    ::  An absolute distance along {{source}}'s scroll range in {{orientation}}.
-    :   <<percentage>>
-    ::  A percentage distance along {{source}}'s scroll range in {{orientation}}.
+::  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.
 
 :   <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
     [=start delay=].
 
-    Conceptually, {{timeRange}} represents the number of milliseconds to map to the
-    scroll range defined by {{start}} and {{end}}. As a
-    result, this value does not have a correspondence to wall-clock time.
+    Conceptually, {{timeRange}} represents the number of milliseconds to map to
+    the scroll range defined by {{start}} and {{end}}. As a result, this value
+    does not have a correspondence to wall-clock time.
 
     This value is used to compute the timeline's [=effective time range=], and
     the mapping is then defined by mapping the scroll distance from
     {{start}} to {{end}}, to the [=effective time range=].
 
 </div>
 
-### The effective time range of a {{ScrollTimeline}} ### {#efffective-time-range-algorithm}
+### Scroll Timeline Offset ### {#scroll-timeline-offset-section}
+
+An <dfn>effective scroll offset</dfn> is a scroll position for a given [=scroll
+container=] and on a given scroll direction.
+
+A <dfn>scroll timeline offset</dfn> is provided by authors and determines a
+[=effective scroll offset=] for the {{source}} and in the direction specified by
+{{orientation}}.
+
+There are two types of scroll timeline offset: [=container-based offset=], and
+[=element-based offset=]. To <dfn>resolve a scroll timeline offset</dfn> into an
+[=effective scroll offset=], run the procedure to [=resolve a container-based
+offset=] or to [=resolve a element-based offset=] depending on the offset type.
+It is possible for a [=scroll timeline offset=] to be resolved to null.
+
+The <dfn>effective start offset</dfn> is the [=effective scroll offset=] that is
+resolved from {{start}}. The <dfn>effective end offset</dfn> is
+the [=effective scroll offset=] that is resolved from {{end}}.
+
+#### Container-based Offset #### {#container-based-offset-section}
+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 three values:
+
+*   auto
+*   <<length>>
+*   <<percentage>>
+
+
+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:
+    <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 a <<length>>
+    ::  The absolute distance indicated by the value along {{source}}'s scroll range
+        in {{orientation}}.
+
+    :  <var>offset</var> is a <<percentage>>
+    ::  The percentage distance along {{source}}'s scroll range in {{orientation}}.
+
+    </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: 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%'.
+
+#### Element-based Offset #### {#element-based-offset-section}
+
+An <dfn>element-based offset</dfn> is a scroll timeline offset that is declared
+in terms of the intersection of the <a>scroll container</a> as specified by
+{{source}} and one of its descendents as specified by {{target}}.
+
+An [=element-based offset=] is provided in the {{ElementBasedOffset}} form.
+
+<pre class="idl">
+enum Edge { "start", "end" };
+
+dictionary ElementBasedOffset {
+  Element target;
+  Edge edge = "start";
+};
+</pre>
+
+
+<div class=members>
+
+:   <dfn dict-member for=ElementBasedOffset>target</dfn>
+::  The target whose intersection with {{source}}'s [=scrolling box=] determines
+     the concrete scroll offset.
+
+:   <dfn dict-member for=ElementBasedOffset>edge</dfn>
+::  The edge of {{source}}'s [=scrolling box=] which the target should
+    intersect with.
+
+</div>
+
+
+Issue:  TODO: Add threshold value that allows authors to control how much of the
+target should become visible within scrollport.
+
+
+The procedure to <dfn>resolve a 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=], then the [=effective scroll
+    offset=] is null and abort the following steps.
+
+1.  Let <var>target</var> be <var>offset</var>'s {{target}}.
+
+1.  If <var>target</var> is null, does not currently have a [=CSS layout box=],
+    then the [=effective scroll offset=] is null and abort the following steps.
+
+1.  If <var>target</var> 's nearest [=scroll container=] ancestor is not the
+    {{source}} then the [=effective scroll offset=] is null and abort the
+    following steps.
+
+1.  Let <var>container box</var> be the {{source}}'s [=scrollport=].
+
+1.  Let <var>target box</var> be the result of finding the rectangular bounding
+    box (axis-aligned in the {{source}}’s coordinate space) of
+    <var>target</var>'s transformed border box.
+
+1.  If <var>offset</var>'s {{edge}} is 'start' then let <var>scroll offset</var>
+    be the scroll offset at which <var>container box</var>'s start edge is flush
+    with the <var>target box</var>'s end edge in the axis and direction
+    determined by {{orientation}}.
+
+1.  If <var>offset</var>'s {{edge}} is 'end' then let <var>scroll offset</var>
+    be the scroll offset at which <var>container box</var>'s end edge is flush
+    with the <var>target box</var>'s start edge in the axis and direction
+    determined by {{orientation}}.
+
+1.  Clamp the value of <var>scroll offset</var> to be within the {{source}}'s
+     scroll range.
+
+1.  The [=effective scroll offset=] is <var>scroll offset</var>
+
+
+
+Note: The current algorithm selects the effective scroll offset such that the
+target is adjacent to the scrollport but not yet visible. The upcoming threshold
+value will allow authors to control the amount of target that needs to be
+visible.
+
+<div class="example">
+Here is a basic example showing how element-based offsets can be used to declare
+an scroll-linked animation that occurs when an element enters the scroller
+scrollport and ends once it exits the scrollport.
+
+<figure>
+<img src="img/example-element-based.svg" width="600"
+alt="Example usage of element-based offset.">
+ <figcaption>
+  Usage of element-based offsets to create enter/exit triggers.<br>
+  The left figure shows the scroller and target being aligned at 'end' edge.<br>
+  The right figure shows them being aligned at 'start' edge.
+ </figcaption>
+</figure>
+
+
+Note that here we are expecting a typical top to bottom scrolling and thus
+consider the entrance to coincide when target's start edge is flushed with
+scrollport's <strong>end edge</strong> and viceversa for exit.
+
+<pre class='lang-javascript'>
+if (window.matchMedia('(prefers-reduced-motion: no-preference)').matches) {
+  const scrollableElement = document.querySelector('#container');
+  const image = document.querySelector('#image');
+
+  const timeline = new ScrollTimeline({
+    source: scrollableElement,
+    start: {target: image, edge: 'end'},
+    end: {target: image, edge: 'start'},
+  });
+
+  const slideIn = target.animate({
+      transform: ['translateX(0)',q 'translateX(50vw)'],
+      opacity: [0, 1]
+    }, {
+      timeline:timeline,
+      duration: 1000
+    }
+  );
+}
+</pre>
+
+
+</div>
+
+### The effective time range of a {{ScrollTimeline}} ### {#effective-time-range-algorithm}
 
-The <dfn>effective time range</dfn> of a {{ScrollTimeline}} is calculated as follows:
+The <dfn>effective time range</dfn> of a {{ScrollTimeline}} is calculated as
+follows:
 
 <div class="switch">
 
@@ -472,29 +629,63 @@ The <dfn>effective time range</dfn> of a {{ScrollTimeline}} is calculated as fol
 
 </div>
 
+### The effective scroll range of a {{ScrollTimeline}} ### {#effective-scroll-range-algorithm}
+
+The procedure to calculate <dfn>effective scroll range</dfn> of a
+{{ScrollTimeline}} is as follows:
+
+1.  Run the procedure to [=resolve a scroll timeline offset=] for both {{start}}
+    and {{end}}.
+
+1.  Calculate [=effective scroll range=] as follow:
+    <div class="switch">
+    :   If [=effective start offset=] or [=effective end offset=] is null.
+    ::  The [=effective scroll range=] is null.
+
+    :   Otherwise
+    ::  The [=effective scroll range=] is the result of evaluating the following
+        expression:
+        <blockquote>
+        <code>[=effective end offset=] - [=effective start offset=]</code>
+        </blockquote>
+
+    </div>
+
 ### The current time of a {{ScrollTimeline}} ### {#current-time-algorithm}
 
-The [=current time=] of a {{ScrollTimeline}} is calculated
-as follows:
+The [=current time=] of a {{ScrollTimeline}} is calculated 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=], return an unresolved time
+    value.
 
-1.  If {{source}} is null, does not currently have a [=CSS layout box=], or
-    if its layout box is not a [=scroll container=], return an unresolved time value.
+1.  Otherwise, let <var>current scroll offset</var> be the current scroll offset
+    of {{source}} in the direction specified by {{orientation}}.
 
-1.  Otherwise, let <var>current scroll offset</var> be the current scroll offset of {{source}}
-    in the direction specified by {{orientation}}.
+1.  If [=effective scroll range=] is null, return an unresolved time value.
 
-1.  If <var>current scroll offset</var> is less than {{start}}, return 0.
+1.  If <var>current scroll offset</var> is less than [=effective start offset=],
+    return 0.
 
-    Note: TODO(<a href="https://github.com/w3c/csswg-drafts/issues/4325#issuecomment-585295758">Issue 4325</a>): Define what the correct timeline state is based on scroll offset.
+    Issue(4325): Define what the correct timeline state is based on scroll
+    offset.
 
-1.  If <var>current scroll offset</var> is greater than or equal to {{end}}, return [=effective time range=].
+1.  If <var>current scroll offset</var> is greater than or equal to [=effective
+    end offset=], return [=effective time range=].
 
 1.  Return the result of evaluating the following expression:
 
     <blockquote>
-      <code>(<var>current scroll offset</var> - {{start}}) / ({{end}} - {{start}}) &times; [=effective time range=]</code>
+      <code>(<var>current scroll offset</var> - [=effective start offset=]) / [=effective scroll range=] &times; [=effective time range=]</code>
     </blockquote>
 
+
+
+Note: To be considered active a scroll timeline requires its [=effective start
+offset=] and its [=effective end offset=] to be non-null. This means that for
+example if one uses an element-based offset whose {{target}} is not a descendant
+of the scroll timeline {{source}}, the timeline remains inactive.
+
 ## The 'animation-timeline' property ## {#animation-timeline}
 
 A {{ScrollTimeline}} may be applied to a CSS Animation [[CSS3-ANIMATIONS]] using