[scroll-animations] Add threshold definition to element-based offset

Author: majido

scroll-animations-1/Overview.bs

@@ -497,6 +497,7 @@ enum Edge { "start", "end" };
 dictionary ElementBasedOffset {
   Element target;
   Edge edge = "start";
+  double threshold = 0.0;
 };
 </pre>
 
@@ -505,17 +506,18 @@ dictionary ElementBasedOffset {
 
 :   <dfn dict-member for=ElementBasedOffset>target</dfn>
 ::  The target whose intersection with {{source}}'s [=scrolling box=] determines
-     the concrete scroll offset.
+    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>
+::  The edge of {{source}}'s [=scrolling box=] in the direction specified by
+    the {{orientation}} which the target should intersect with.
 
+:   <dfn dict-member for=ElementBasedOffset>threshold</dfn>
+::  A double in the range of [0.0, 1.0] that represent the precentage
+    of the target that is expected to be visible in  {{source}}'s [=scrollport=]
+    at the intersection offset.
 
-Issue:  TODO: Add threshold value that allows authors to control how much of the
-target should become visible within scrollport.
+</div>
 
 
 The procedure to <dfn>resolve a element-based offset</dfn> given
@@ -550,17 +552,48 @@ The procedure to <dfn>resolve a element-based offset</dfn> given
     with the <var>target box</var>'s start edge in the axis and direction
     determined by {{orientation}}.
 
+1.  Let <var>threshold amount</var> be the result of evaluating the following
+    expression where <var>target dimension</var> is <var>target box</var>'s dimension in the axis
+    determined by {{orientation}}.
+    <blockquote>
+      <code><var>threshold amount</var> = {{threshold}} &times; <var>target dimension</var></code>
+    </blockquote>
+
+
+1.  Adjust <var>scroll offset</var> by <var>threshold amount</var> as follow:
+    <div class="switch">
+
+    :   If <var>offset</var>'s {{edge}} is 'start',
+    ::  <var>scroll offset</var> = <var>scroll offset</var> - <var>threshold amount</var>.
+
+    :   Otherwise (<var>offset</var>'s {{edge}} is 'end'),
+    ::  <var>scroll offset</var> = <var>scroll offset</var> + <var>threshold amount</var>.
+
+    </div>
+
 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>
 
 
+<div class="note">
+Note: With threshold 0.0, the algorithm selects the effective scroll offset such
+that the target is adjacent to the [=scrollport=] at the given edge but not yet
+visible. The upcoming threshold value will allow authors to control the amount
+of target that needs to be visible in [=scrollport=]. In particular threshold
+value 1.0 ensure that target is fully visible (as long as [=scrollport=] is
+large enough).
+
+<figure>
+<img src="img/example-element-based-threshold.svg" width="600"
+alt="Example usage of element-based offset.">
+ <figcaption>
+  Threshold controls how much of target should be visible in [=scrollport=].
+ </figcaption>
+</figure>
 
-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>
 
 <div class="example">
 Here is a basic example showing how element-based offsets can be used to declare