rebase

Author: Kevin Ellis

scroll-animations-1/Overview.bs

@@ -140,7 +140,6 @@ Using the CSS markup:
 <pre class='lang-css'>
 @media (prefers-reduced-motion: no-preference) {
   div.circle {
-    animation-duration: 1s;
     animation-timing-function: linear;
     animation-timeline: collision-timeline;
   }
@@ -191,13 +190,13 @@ if (window.matchMedia('(prefers-reduced-motion: no-preference)').matches) {
     scrollOffsets: [CSS.px(200), CSS.px(300)]
   });
 
-  const left = leftCircle.animate({ transform: 'translate(300px)' }, 1000);
+  const left = leftCircle.animate({ transform: 'translate(300px)' });
   left.timeline = collisionTimeline;
 
-  const right = leftCircle.animate({ transform: 'translate(350px)' }, 1000);
+  const right = leftCircle.animate({ transform: 'translate(350px)' });
   right.timeline = collisionTimeline;
 
-  const union = unionCircle.animate({ opacity: 1 }, { duration: 1000, fill: "forwards" });
+  const union = unionCircle.animate({ opacity: 1 }, { fill: "forwards" });
   union.timeline = new ScrollTimeline({
     source: scrollableElement,
     scrollOffsets: [CSS.px(250), CSS.px(300)]
@@ -253,7 +252,7 @@ If we use this API for this case, the example code will be as follow:
 
 <pre class='lang-javascript'>
 if (window.matchMedia('(prefers-reduced-motion: no-preference)').matches) {
-  var animation = div.animate({ width: '100%' }, { duration: 1000, fill: "forwards" });
+  var animation = div.animate({ width: '100%' }, { fill: "forwards" });
   animation.timeline = new ScrollTimeline(
     {
       scrollOffsets: [0, CSS.percent(100)]
@@ -360,7 +359,6 @@ dictionary ScrollTimelineOptions {
   Element? source;
   ScrollDirection orientation = "block";
   sequence&lt;ScrollTimelineOffset&gt; scrollOffsets = [];
-  (double or ScrollTimelineAutoKeyword) timeRange = "auto";
 };
 
 [Exposed=Window]
@@ -369,14 +367,15 @@ interface ScrollTimeline : AnimationTimeline {
   readonly attribute Element? source;
   readonly attribute ScrollDirection orientation;
   readonly attribute FrozenArray&lt;ScrollTimelineOffset&gt; scrollOffsets;
-  readonly attribute (double or ScrollTimelineAutoKeyword) timeRange;
 };
 </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=].
 
+The {{AnimationTimeline/Duration}} of a <a>scroll timeline</a> is 100%.
+
 <div link-for-hint="ScrollTimeline">
 
 <div class="constructors">
@@ -403,10 +402,9 @@ determined not by wall-clock time, but by the progress of scrolling in a
 
     1.  Set the {{ScrollTimeline/source}} of |timeline| to |source|.
 
-    1.  Assign the {{ScrollTimeline/orientation}}, {{ScrollTimeline/scrollOffsets}}
-        and {{ScrollTimeline/timeRange}} properties of
+    1.  Assign the {{ScrollTimeline/orientation}} and
+        {{ScrollTimeline/scrollOffsets}} properties of
         |timeline| to the corresponding value from |options|.
-
 </div>
 
 <div class="attributes">
@@ -453,25 +451,6 @@ determined not by wall-clock time, but by the progress of scrolling in a
 
         </div>
 
-:   <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.
-
-    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=].
-
-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
-"progress-based animations" to web animations.
-
-</div>
-
 ### Scroll Timeline Offset ### {#scroll-timeline-offset-section}
 
 An <dfn>effective scroll offset</dfn> is a scroll position for a given [=scroll
@@ -711,8 +690,7 @@ if (window.matchMedia('(prefers-reduced-motion: no-preference)').matches) {
       transform: ['translateX(0)', 'translateX(50vw)'],
       opacity: [0, 1]
     }, {
-      timeline:timeline,
-      duration: 1000
+      timeline:timeline
     }
   );
 }
@@ -741,36 +719,12 @@ The same logic can be done in CSS markup:
 
   #target {
     animation-name: slide-in;
-    animation-duration: 1s;
     animation-timeline: image-in-scrollport;
   }
 
 }
 </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:
-
-<div class="switch">
-
-:   If the {{timeRange}} has the value `"auto"`,
-::  The [=effective time range=] is the maximum value of the
-    [=target effect end=] of all animations
-    directly associated with this timeline.
-
-    If any animation directly associated with the timeline has a
-    [=target effect end=] of infinity, the [=effective time range=]
-    is zero.
-
-:   Otherwise,
-::  The [=effective time range=] is the {{ScrollTimeline}}'s
-    {{timeRange}}.
-
 </div>
 
 ### The effective scroll offsets of a {{ScrollTimeline}} ### {#effective-scroll-offsets-algorithm}
@@ -910,15 +864,15 @@ The [=current time=] of a {{ScrollTimeline}} is calculated as follows:
 
 :   If |current scroll offset| is greater than or equal to [=effective
     end offset=]:
-::  The [=current time=] is the [=effective time range=].
+::  The [=current time=] is the [=duration=].
 
 :   Otherwise,
 ::  1.  Let |progress| be a result of applying
         [=calculate scroll timeline progress=] procedure for <var>current scroll offset</var>.
     1.  The [=current time=] is the result of evaluating the following expression:
 
     <blockquote>
-      <code>|progress| &times; [=effective time range=]</code>
+      <code>|progress| &times; [=duration=]</code>
     </blockquote>
 
 </div>
@@ -1032,17 +986,6 @@ following:
       * {{ElementBasedOffset/threshold}} is the optional value <<number>>. If
         not provided it defaults to 0.
 
-</div>
-
-<pre class='descdef'>
-  Name: time-range
-  For: @scroll-timeline
-  Value: auto | <<time>>
-  Initial: auto
-</pre>
-
-'time-range' descriptor determines the scroll timeline's {{timeRange}}.
-
 </div>  <!-- link-for-hint="ScrollTimeline" -->
 
 ### The <dfn interface>CSSScrollTimelineRule</dfn> Interface ### {#the-css-scroll-timeline-rule-interface}
@@ -1054,7 +997,6 @@ interface CSSScrollTimelineRule : CSSRule {
     readonly attribute CSSOMString source;
     readonly attribute CSSOMString orientation;
     readonly attribute CSSOMString scrollOffsets;
-    readonly attribute CSSOMString timeRange;
 };
 </pre>
 
@@ -1079,11 +1021,6 @@ interface CSSScrollTimelineRule : CSSRule {
   <dd>
     The 'scroll-offsets' descriptor associated with the ''@scroll-timeline'', or "none" if not specified.
   </dd>
-
-  <dt><dfn>timeRange</dfn></dt>
-  <dd>
-    The 'time-range' descriptor associated with the ''@scroll-timeline'', or "auto" if not specified.
-  </dd>
 </dl>
 
 <div algorithm>
@@ -1212,7 +1149,6 @@ interface CSSScrollTimelineRule : CSSRule {
           { width: "100vw" }
         ],
         {
-          duration: 1000,
           easing: "linear",
           fill: "forwards"
         });
@@ -1255,7 +1191,6 @@ interface CSSScrollTimelineRule : CSSRule {
         /* This name is used to select both the keyframes and the
            scroll-timeline at-rules. */
         animation-name: progress;
-        animation-duration: 1s;
         animation-fill-mode: forwards;
         animation-timing-function: linear;
       }

web-animations-2/Overview.bs

@@ -144,9 +144,48 @@ Along with the following updated description:
 </div>
 
 
+<h3 id="timelines">Timelines</h3>
+
+Add:
+
+> The <dfn lt="timeline duration">duration</dfn> of a timeline gives the
+> maximum value a timeline may generate for its current time. This value is
+> used to calculate the [=intrinsic iteration duration=] for the target effect
+> of an animation that is associated with the timeline when the effect's
+> [=iteration duration=] is 'auto'. The value is computed such that the effect
+> fills the available time.  For a monotonic timeline, there is no upper bound
+> on current time, and [=timeline duration=] is unresolved. For a progress based
+> timeline, the [=timeline duration=] is 100%.
+
 <h3 id="animations">Animations</h3>
 
-<div class="informative-bg"><em>This section is non-normative</em>
+Add:
+
+> Animation effects associated with a progress-based timeline require their
+> timing properties to be converted to proportions. The procedure for converting
+> a <dfn lt="time-based animation to a proportional animation"></dnf> is as
+> follows:
+>
+> 1.  If the [=iteration duration=] is auto, then perform the following steps.
+>
+>     1.   Compute [=start delay=] and [=end delay=] to 0, as it is not possible
+>          to mix time and proportions. Future versions may allow these properties
+>          to be assigned percentages.
+>
+> 1.  Otherwise,
+>
+> 1.  Let <var>total time</var> be equal to the result of evaluating
+>     <code>|start delay| + |iteration count| * |iteration duration| +
+>     |end delay|</code>.
+>
+> 1.  Compute [=start delay=] to be the result of evaluating
+>     <code>|start delay| / |total time| * |timeline duration|</code>.
+>
+> 1.  Compute [=iteration duration=] to be the result of evaluating
+>     <code>|iteration duration| / |total time| * |timeline duration|</code>.
+>
+> 1.  Compute [=end delay=] to be the result of evaluating
+>     <code>|end delay| / |total time| * |timeline duration|</code>.
 
 <h4 id="setting-the-timeline">Setting the timeline of an animation</h4>
 
@@ -944,13 +983,24 @@ Add:
 
 >     The initial <a>iteration duration</a> of an animation effect is simply its
 >     <a>intrinsic iteration duration</a>.
+>     The <dfn>intrinsic iteration duration</dfn> is calculated from the first
+>     matching condition from below:
+>
+> <div class="switch">
+> :   If the animation effect is a <a>group effect</a>,
+> ::  Follow the procedure in
+>     [[#the-intrinsic-iteration-duration-of-a-group-effect]]
 >
->     The <dfn>intrinsic iteration duration</dfn> of an animation effect is
->     zero, however some specific types of animation effect such as
->     <a>group effects</a> override this behavior and provide an
->     alternative intrinsic duration (see
->     [[#the-intrinsic-iteration-duration-of-a-group-effect]] and
->     [[#the-intrinsic-iteration-duration-of-a-sequence-effect]]).
+> :   If the animation effect is a <a>sequence effect</a>,
+> ::  Follow the procedure in
+>     [[#the-intrinsic-iteration-duration-of-a-sequence-effect]]
+>
+> :   If [=timeline duration=] is unresolved,
+> ::  Return 0
+>
+> :   Otherwise
+> ::  Return  [=timeline duration=] / <a>iteration count</a>
+> </div>
 >
 >     The <a>iteration duration</a> of an <a>animation effect</a> may be set
 >     by the author to represent a value other than the <a>intrinsic
@@ -1886,10 +1936,18 @@ Items sorted earlier are executed before those sorted later.
 <pre class="idl">
 [Exposed=Window]
 partial interface AnimationTimeline {
+    readonly attribute CSSNumberish? duration;
     Animation play (optional AnimationEffect? effect = null);
 };
 </pre>
 
+<div class='attributes'>
+
+:   <dfn attribute for=AnimationTimeline>duration</dfn>
+::  Returns the <a lt="timeline duration">duration</a> for this timeline.
+
+</div>
+
 <div class='methods'>
 
 :   <dfn method for=AnimationTimeline lt='play()'>
@@ -2054,6 +2112,10 @@ partial dictionary OptionalEffectTiming {
     > The <a>start delay</a> which represents the number of milliseconds from an
     > <a>animation effect</a>'s <a lt="animation effect start time">start
     > time</a> to the start of the <a>active interval</a>.
+    > If the <a lt="timeline duration">duration</dfn> of the Animation's
+    > <a>timeline</a> is a percentage, the start delay will be treated as the
+    > result of applying the procedure to convert a
+    > [=time-based animation to a proportional animation=].
 
 :   <dfn>endDelay</dfn>
 ::  Update the description as:
@@ -2063,12 +2125,21 @@ partial dictionary OptionalEffectTiming {
     > until the <a lt='animation effect start time'>start time</a> of any
     > <a>animation effect</a> that may
     > follow, for example, in a <a>sequence effect</a>.
+    > If the <a lt="timeline duration">duration</dfn> of the Animation's
+    > <a>timeline</a> is a percentage, the end delay will be treated as the
+    > result of applying the procedure to convert a
+    > [=time-based animation to a proportional animation=].
 
 </div>
 
 :   <dfn>duration</dfn>
 ::  Add:
 
+    > If the <a lt="timeline duration">duration</dfn> of the Animation's
+    > <a>timeline</a> is a percentage, a non <code>auto</code> duration will
+    > be treated as the result of applying the procedure to convert a
+    > [=time-based animation to a proportional animation=].
+
     > The string value <code>auto</code> is used to indicate that the
     > <a>iteration duration</a> reflects the animation effect's
     > <a>intrinsic iteration duration</a>.
@@ -2086,15 +2157,20 @@ partial dictionary OptionalEffectTiming {
 
 <pre class='idl'>
 partial dictionary ComputedEffectTiming {
-    double startTime;
+    CSSNumberish         startTime;
+    CSSNumberish         endTime;
+    CSSNumberish         activeDuration;
+    CSSNumberish?        localTime;
+    CSSNumberish?        progress;
 };
 </pre>
 
 <div class='members'>
 
 :   <dfn dict-member for=ComputedEffectTiming>startTime</dfn>
 ::  The <a lt='animation effect start time'>start time</a> of this
-    <a>animation effect</a> in milliseconds.
+    <a>animation effect</a> in milliseconds or as a percentage of the
+    [=timeline duration=].
     This is the time at which the <a>parent group</a>, if
     any, has scheduled this child to run within its <a
     lt="transformed time">transformed time space</a>, that is, the
@@ -2110,7 +2186,7 @@ partial dictionary ComputedEffectTiming {
 
     > The <a>end time</a> of the <a>animation effect</a> expressed
     > in milliseconds in <a lt="inherited time">inherited time
-    > space</a>.
+    > space</a> or as a percentage of the [=timeline duration=].
 
     > This corresponds to the end of the <a>animation effect</a>'s active
     > interval plus any <a>end delay</a>.
@@ -2478,8 +2554,8 @@ Replace:
 
 with:
 
->     If the duration is not specified, the <a>intrinsic iteration
->     duration</a> is used which, for a <a>keyframe effect</a>, is zero.
+>     If the duration is not specified, the [=intrinsic iteration duration=] is
+>     used.
 
 Add: