Overview.bs

<link href='web-animations.css' rel='stylesheet' type='text/css'>
<pre class='metadata'>
Title: Scroll-linked Animations
Group: CSSWG
Status: UD
Work Status: exploring
ED: https://birtles.github.io/scroll-animations/
Shortname: scroll-animations
Abstract: Defines an API and markup for creating animations that are either
          triggered by or tied to the scroll offset of a scroll container.
Editor: Dean Jackson <dino@apple.com>
Editor: Brian Birtles <bbirtles@mozilla.com>
Editor: Botond Ballo <botond@mozilla.com>
Editor: Mantaroh Yoshinaga <mantaroh@mozilla-japan.org>
</pre>
<pre class=anchors>
urlPrefix: https://w3c.github.io/web-animations/; type: dfn; spec: web-animations
    text: animation; url: concept-animation
    text: current time
    text: default document timeline
    text: duration
    text: inactive timeline
    text: start delay
    text: target effect end
    text: timeline
</pre>

# Introduction # {#intro}

This specification defines mechanisms for
[[#triggering-animations|triggering the start and end]] of an [=animation=]
based on the scroll progress of a [=scroll container=], as well as 
[[#controlling-animation-playback|driving the progress of an animation]] based
on the scroll progress of a scroll container.

## Relationship to other specifications ## {#other-specs}

Web Animations [[WEB-ANIMATIONS-1]] defines an abstract conceptual model for
animations on the Web platform, with elements of the model including
[=animations=] and their [=timelines=],
and associated programming interfaces.

This specification extends this model in two ways: by defining a new concept,
that of an [=animation timeline trigger=], which can optionally be associated with
an animation [=timeline=]; and by defining a new type of animation [=timeline=]:
a [=scroll timeline=].

This specification defines both programming interfaces for interacting with these
concepts, as well as CSS markup which applies these concepts to CSS Animations
[[CSS3-ANIMATIONS]].

The behavior of the CSS markup is described in terms of the programming interfaces.
User-agents that do not support script may still implement the CSS markup
provided it behaves as if the underlying programming interfaces were in place.

# Use cases # {#use-cases}

<div class='informative-bg'>

## Scroll-triggered Animations ## {#scroll-triggered-animations-usecases}

It is common to trigger an animation to run when the scroll position
reaches a certain point. For example, a navigation bar that changes
highlight based on the reader's position within the document.

<figure>
<img src="img/usecase1-1.svg" width="600"
alt="Use case 1-1: The navigation highlight effect.">
 <figcaption>
  A navigation highlight effect<br>
  On the left, the &ldquo;Abstract&rdquo; section is scrolled into view
  and hence the abstract menu item is highlighted.<br>
  After scrolling down to the &ldquo;Background&rdquo; section (right),
  the background menu item fades in while the abstract menu item fades
  out.
 </figcaption>
</figure>

Using the CSS markup defined in this specification, we can achieve this
effect as follows:

<pre class="lang-css">
div.menu {
  animation: 1s linear 2 alternate both menu-effect;
}
#abstractItem {
  animation-trigger: scroll(element(#body), vertical, 0px, 200px);
}
#backgroundItem {
  animation-trigger: scroll(element(#body), vertical, 200px, 350px);
}
@keyframes menu-effect {
  from { opacity: 0.5 }
  to   { opacity: 1.0 }
}
</pre>

Issue: It seems like this use case would be much better suited to
''@trigger'' and transitions. (And all of this makes me wonder if we
really want triggers in the API since it seems like this case in
particular would not be representable in a way we could pass to the
compositor. I need to think about this more.)

Issue: TODO: Tidy up the above code

Issue: Put the example URLs into a note here somewhere

Alternatively, using the programming interface defined in this
specification, this might be expressed as:

<pre class='lang-javascript'>
var body = document.getElementById('body');
var timing = { duration: 1000,
               direction: 'alternate',
               iterations: 2,
               fill: 'both' };

var abstractAnimation = document.getElementById('abstractItem')
                        .animate({ opacity: [ 0.5, 1.0 ] }, timing);
abstractAnimation.timeline = new DocumentTimeline(
  { trigger: new ScrollTrigger({ scrollSource: body,
                                 orientation: 'vertical',
                                 scrollOffset: '0px',
                                 endScrollOffset: '200px' }) });
</pre>

### The navigation position effect ### {#navigation-position-effect-usecase}
Several contents are separating the initial page and main content page. So if we build single page content, we may need to use the scroll-triggered animation.

Here's example for using the scroll-triggered animations.
This content has a navigation bar, this navigation icon is displayed a large icon when viewing initial view. However, this navigation will become a small icon , when scrolling contents.

<figure>
<img src="img/usecase1-2.svg" width="600"
alt="Use case 1-2: Scroll based animation.">
 <figcaption>
  Use case 1-2: Scroll based animations.<br>
  The left figure is before scroll, menu icon is large.<br>
  The right figure is after scroll, menu icon become small.
 </figcaption>
</figure>

We can build this content using the CSS.
<pre class='lang-css'>
@keyframes navigationbar-effect {
  from {
    transform: scale(1.0, 1.0);
  }
  to {
    transform: scale(0.5, 0.5);
  }
}

div.menu {
  animation: 1s linear navigationbar-effect;
  animation-trigger: scroll(element(scrollableElement), vertical, 0px, 100px);
}
</pre>

We can build this example content as JavaScript.
<pre class='lang-javascript'>
var animation = menuDiv.getAnimations()[0];

animation.timeline = new DocumentTimeline({
  trigger: new ScrollTrigger({ scrollSource: scrollableElement,
                               orientation: "vertical",
                               scrollOffset: "0px",
                               endScrollOffset: "100px"})});
</pre>

## Scroll-triggered style changes ## {#scroll-triggered-style-changes-usecase}

### The fixed navigation bar ### {#fixed-menu-bar-usecase}
The content of displaying the menu bar is the commonplace web content.
Usually, these menu bar is fixed always. But some content will want to fix menu bar when
scrolling certain position.
Here's the example content for scroll-triggered based changing styles.
This example has a menu bar on the right of content, and this content has a large title content.
This position of navigation bar will be fixed after exceeding the certain scroll position.

Usually, we can implement using to the scroll event. However, If we use the @trigger rule, we can implement this more simply.

<figure>
<img src="img/usecase2.svg" width="600"
alt="Use case 2: Scroll based styling">
 <figcaption>
  Use case 2: Scroll based styling.<br>
  The left figure is before scroll, menubar's position is not fixed.<br>
  The right figure is after scroll, menubar's position is fixed.
 </figcaption>
</figure>

If we use animation-trigger style sheet, this example code will be as follow:
<pre class='lang-css'>
div#menu-bar {
  position: relative;
  top: 10px;
}

@trigger scroll(element(#scrollableContent), vertical, 200px) {
  #menu-bar {
    position: fixed;
    top: 10px;
  }
}
</pre>

## Scroll-linked animations ## {#scroll-linked-animations-usecase}

### Scrollable picture-story show ### {#scrollable-animation-usecase}
There are many animation contents which used the 3rd vendor plugins. These content can detect scroll event, and this content has interactive animation.

Here's content has interactive animation too, it is a picture-story show. If we scrolled this content, the character of story will move.

If we scrolled opposite direction, this animation move to the opposite direction(reverse).

<figure>
<img src="img/usecase3-1.svg" width="600"
alt="Use case 3-1: The picture-story show.">
 <figcaption>
  Use case 3-1: The picture-story show.<br>
  The left figure is before scroll, this picture-story show didn't start.<br>
  The right figure is after scroll, this story will start.
 </figcaption>
</figure>

If we use animation-timeline, example code will be as follow.
<pre class='lang-css'>
@keyframes leftCircleAnimation {
  from {
    margin-left: 200px;
  }
  to {
    margin-left: 300px;
  }
}
@keyframes rightCircleAnimation {
  from {
    margin-left: 450px;
  }
  to {
    margin-left: 350px;
  }
}
@keyframes unionCircleAnimation {
  from {
    opacity: 0.0;
  }
  to {
    opacity: 1.0;
  }
}
div#leftCircle {
  animation: 1s linear leftCircleAnimation;
  animation-trigger: scroll(element(#scrollableContainer), vertical, "200px", "300px");
  animation-timeline: scroll();
}
div#rightCircle {
  animation: 1s linear rightCircleAnimation;
  animation-trigger: scroll(element(#scrollableContainer), vertical, "200px", "300px");
  animation-timeline: scroll();
}
div#unionCircle {
  animation: 1s linear unionCircle;
  animation-trigger: scroll(element(#scrollableContainer), vertical, "250px", "300px");
}
</pre>

If we use this API for this case, the example code will be as follow:
<pre class='lang-javascript'>
var leftCircleAnimation = leftCircle.getAnimations()[0];
var rightCircleAnimation = rightCircle.getAnimations()[0];
var unionCircleAnimation = unionCircle.getAnimations()[0];

var accelerationTimeline = new ScrollTimeline({
  trigger: new ScrollTrigger({
    scrollSource: scrollableElement,
    scrollOffset: '200px',
    endScrollOffset: '300px'})});

leftCircleAnimation.timeline = accelerationTimeline;
rightCircleAnimation.timeline = accelerationTimeline;
unionCircleAnimation.timeline = new ScrollTimeline({
  trigger: new ScrollTrigger({
    scrollSource:scrollableElement,
    scrollOffset: '250px',
    endScrollOffset: '300px'})});
</pre>

### The content progress bar ### {#content-progress-bar-usecase}
There is much content that using to scroll linked animations.
Here's one of these animation content, this content has a long article.
And this content has a progress bar which indicates the current position of the article.

If we scroll the content, this progress bar increased / decreased.

<figure>
<img src="img/usecase3-2.svg" width="600"
alt="Use case 3-2: Scroll based styling">
 <figcaption>
  Use case 3-2: Content progress bar.<br>
  The left figure is before scroll, the progress bar is not displayed.<br>
  The right figure is after scroll, the progress bar advanced.
 </figcaption>
</figure>

Usually, we won't need to this progress bar, because the scroll bar indicated the progress. But some content will want to hide the scroll bar, like this content.

If we use animation-timeline, this example code will be as follow.
<pre class='lang-css'>
@keyframes progressAnimation {
  from {
    width: 0px;
  }
  to {
    width: 500px;
  }
}
div#progress {
  width: 50%;
  height: 30px;
  background: red;
  animation: 1s linear progressAnimation;
  animation-trigger: scroll(element(#scrollableContainer), vertical);
  animation-timeline: scroll();
}
</pre>

If we use this API for this case, the example code will be as follow:
<pre class='lang-javascript'>
  var animation = div.getAnimations()[0];
  animation.timeline = new ScrollTimeline(
    { trigger: new ScrollTrigger({ scrollSource: scrollableElement,
                                   scrollOffset: '0px'}) });
</pre>

## Combination scroll and time-base animations ## {#combination-scroll-and-time-base-animations-usecase}

### The photo viewer ### {#movie-show-case-usecase}
Maybe the developer will want to use the scroll based timeline and the time-based timeline.

Here's an example content which showing the photos.
If scroll position is out of specified range, the animation of the slideshow will start. The progress of this slideshow is related to scroll volume. And if scroll position is within the specified range, the animation of the slideshow will continue automatically.

<figure>
<img src="img/usecase4.svg" width="600"
alt="Use case 4: Scrollable slide show.">
 <figcaption>
  Use case 4: Scrollable slide show.<br>
  The left figure is before scroll, the slide show will start as scroll-linked animation.<br>
  The right figure is after scroll, the slide show will start as related to the time animation.
 </figcaption>
</figure>

This content can't build the CSS only.
<pre class='lang-javascript'>
  var animation = slideTarget.getAnimation()[0];
  var scrollTimeline = new ScrollTimeline(
    { trigger: new ScrollTrigger({ scrollSource: scrollableElement,
                                   orientation: "vertical",
                                   scrollOffset: '0px',
                                   endScrollOffset: '200px'})});
  animation.timeline = scrollTimeline;

  // We use scroll event in order to change the timeline.
  scrollableElement.addEventListener("scroll", function(evt) {
    if ((scrollableElement.scrollTop > 200) && animation.timeline != document.timeline) {
      animation.timeline = document.timeline;
    } else if ((scrollableElement.scrollTop < 200) && animation.timeline == document.timeline) {
      animation.timeline = scrollTimeline;
    }
  });
</pre>

</div>

# Triggering animations # {#triggering-animations}

## The {{AnimationTimelineTrigger}} interface ## {#animationtimelinetrigger-interface}

<pre class="idl">
interface AnimationTimelineTrigger {
};
</pre>

An <dfn>animation timeline trigger</dfn> is an object that can be in one of
two states: <dfn>active</dfn> and <dfn>inactive</dfn>. A trigger starts off
as inactive, and can subsequently be activated or deactivated by the user-agent
depending on the specific type of trigger.

A trigger cannot be explicitly activated or deactivated from script, only by
the user-agent.

## Extensions to the {{AnimationTimeline}} interface ## {#extensions-to-animationtimeline}

<pre class="idl">
partial interface AnimationTimeline {
  readonly attribute AnimationTimelineTrigger? trigger;
};
</pre>

If a <a>timeline</a> has a specified trigger, the timeline is only <a
lt='inactive timeline'>active</a> when its trigger is <a>active</a>.

That is, a timeline with a trigger only becomes <a
lt="inactive timeline">active</a> when its trigger becomes
<a>active</a> <strong>and</strong> all the other criteria for the timeline
becoming <a lt="inactive timeline">active</a> are met. When the trigger becomes
<a>inactive</a>, the timeline becomes <a lt="inactive timeline">inactive</a> as
well.

## Extensions to the {{DocumentTimeline}} interface ## {#document-timeline-interface}

<pre class="idl">
partial dictionary DocumentTimelineOptions {
  AnimationTimelineTrigger trigger;
};
[Constructor(optional DocumentTimelineOptions options)]
partial interface DocumentTimeline {
  // trigger attribute inherited from AnimationTimeline
};
</pre>

## Scroll Triggers ## {#scroll-triggers}

### The {{ScrollDirection}} enumeration ### {#scrolldirection-enumeration}

<pre class="idl">
enum ScrollDirection {
  "auto",
  "block",
  "inline",
  "horizontal",
  "vertical"
};
</pre>

The {{ScrollDirection}} enumeration specifies a direction of scroll of a
scrollable element.

:   <code>auto</code>
::  If only one direction is scrollable, selects that direction.
    Otherwise selects the direction along the [=block axis=].

:   <code>block</code>
::  Selects the direction along the [=block axis=].

:   <code>inline</code>
::  Selects the direction along the [=inline axis=].

:   <code>horizontal</code>
::  Selects the horizontal direction.

:   <code>vertical</code>
::  Selects the vertical direction.

<div class="issue">

Should the physical directions ("horizontal" and "vertical") be removed, leaving 
only the logical directions ("block" and "inline")?

What about a value that means, "the longest scroll direction"? That would be
more reliable than "auto" for the case where layout differences could mean that,
although normally you only expect the inline direction to be scrollable, on
some devices you end up with a small scrollable range in the block direction
too.

</div>

### The {{ScrollTriggerKind}} enumeration ### {#scrolltriggerkind-enumeration}

<pre class="idl">
enum ScrollTriggerKind {
  "offset",
  "range"
};
</pre>

The {{ScrollTriggerKind}} enumeration specifies the kind of a {{ScrollTrigger}}.

:   <code>offset</code>
::  The scroll trigger is activated when a scroll offset is reached,
    and never subsequently deactivated.

    Issue: Do we actually have use cases for this? I think in most cases we
    cancel the animation if we go back past the {{ScrollTrigger/scrollOffset}}?
    I'd be glad to be proven wrong, however.

:   <code>range</code>
::  The scroll trigger is active whenever the scroll offset is inside
    a particular range.

### The {{ScrollTrigger}} interface ### {#scrolltriggger-interface}

<pre class="idl">
dictionary ScrollTriggerOptions {
  Element scrollSource;
  ScrollTriggerKind kind = "offset";
  ScrollDirection orientation = "auto";
  DOMString scrollOffset = "auto";
  DOMString endScrollOffset = "auto";
};

[Constructor(optional ScrollTriggerOptions options)]
interface ScrollTrigger : AnimationTimelineTrigger {
  readonly attribute Element scrollSource;
  readonly attribute ScrollTriggerKind kind;
  readonly attribute ScrollDirection orientation;
  readonly attribute DOMString scrollOffset;
  readonly attribute DOMString endScrollOffset;
};
</pre>

<div link-for-hint="ScrollTrigger">
A {{ScrollTrigger}} is an {{AnimationTimelineTrigger}} associated with a scrollable
element. 

</p>

<div class="attributes">

:   <dfn attribute for=ScrollTrigger>scrollSource</dfn>
::  The scrollable element whose scrolling activates and deactivates the trigger.

    If this is not specified, the document element is used.

:   <dfn attribute for=ScrollTrigger>kind</dfn>
::  Determines the way in which scrolling {{scrollSource}} activates and deactivates
    the trigger.

    The values have the following behavior:

    :   offset
    ::  The trigger is activated when {{scrollSource}}'s scroll offset in {{orientation}} 
        reaches {{scrollOffset}}, and never subsequently deactivated. {{endScrollOffset}} 
        is ignored.

    :   range
    ::  The trigger is activated when {{scrollSource}}'s scroll offset in {{orientation}} 
        enters the interval [{{scrollOffset}}, {{endScrollOffset}}], and deactivated when 
        the scroll offset exits that interval.

:   <dfn attribute for=ScrollTrigger>orientation</dfn>
::  Determines the direction of scrolling which drives the activation and deactivation
    of the trigger.

:   <dfn attribute for=ScrollTrigger>scrollOffset</dfn>
::  The scroll offset, in the direction specified by {{orientation}}, that triggers 
    activation of the trigger.

    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 {{scrollSource}}'s scroll range in {{orientation}}.
    :   <<length>>
    ::  An absolute distance along {{scrollSource}}'s scroll range in {{orientation}}.
    :   <<percentage>>
    ::  A percentage distance along {{scrollSource}}'s scroll range in {{orientation}}.

    The way in which the trigger's activation depends on this offset is determined by the
    trigger's {{kind}}.

:   <dfn attribute for=ScrollTrigger>endScrollOffset</dfn>
::  A scroll offset that constitutes the end of a range in which the trigger 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 {{scrollSource}}'s scroll range in {{orientation}}.
    :   <<length>>
    ::  An absolute distance along {{scrollSource}}'s scroll range in {{orientation}}.
    :   <<percentage>>
    ::  A percentage distance along {{scrollSource}}'s scroll range in {{orientation}}.

    This is ignored if the trigger's {{kind}} is {{offset}}.

</div>
</div>

## The 'animation-trigger' property ## {#animation-trigger}

<a>Animation timeline triggers</a> can be applied to animations defined using
CSS Animations [[CSS3-ANIMATIONS]] with the 'animation-trigger' property.

<pre class='propdef'>
Name: animation-trigger
Value: <<single-animation-trigger>>#
Initial: none
Applies to: all elements, ::before and ::after pseudo-elements
Inherited: none
Animatable: no
Percentages: N/A
Media: interactive
Computed value: As specified
Canonical order: per grammar
</pre>

<dfn>&lt;single-animation-trigger></dfn> = none | <<scroll-trigger>>

<dfn>&lt;scroll-trigger></dfn> = scroll([element(<<id-selector>>), [,<<scroll-direction>> [, <<scroll-offset>> [, <<scroll-offset>>]]]])

<dfn>&lt;scroll-direction></dfn> = auto | horizontal | vertical

<dfn>&lt;scroll-offset></dfn> = <<length>> | <<percentage>> | auto

The 'animation-trigger' property is similar to properties like 'animation-duration' and 
'animation-timing-function' in that it can have one or more values, each one imparting 
additional behavior to a corresponding [=animation=] on the 
element, with the triggers matched up with animations as described 
[[css-animations-1#animation-name|here]].

Each value has type <<single-animation-trigger>>, whose possible values have the
following effects:

:   <dfn value for=animation-trigger>none</dfn>
::  The animation's [=timeline=] has no {{AnimationTimeline/trigger|trigger}}.

:   <<scroll-trigger>>
::  The animation's [=timeline=] has a {{ScrollTrigger}}.

    The trigger's {{ScrollTrigger/scrollSource}} is the [=scroll container=] identified
    by the <<id-selector>>, defaulting to the element's nearest scrollable ancestor.

    The <<scroll-direction>>, if provided, determines the trigger's {{ScrollTrigger/orientation}}.

    The first <<scroll-offset>>, if provided, determines the trigger's {{ScrollTrigger/scrollOffset}}.

    The second <<scroll-offset>>, if provided, determines the trigger's {{ScrollTrigger/endScrollOffset}}.

    The trigger's {{ScrollTrigger/kind}} is {{ScrollTriggerKind/range}}.

    Issue: Should we allow overriding the kind to {{ScrollTriggerKind/offset}}?

## ''@trigger'' rules ## {#trigger-rules}

The <dfn>@trigger</dfn> at-rule allows conditioning the application of CSS rules
on the scroll progress of a [=scroll container=]. It is defined as follows:

<pre>
  @trigger = @trigger <<scroll-trigger>> { <<rule-list>> }
</pre>

The <<scroll-trigger>> defines a {{ScrollTrigger}}, in a similar fashion to when it appears
as a value for 'animation-trigger'.

The <<rule-list>> inside of ''@trigger'' can contain any rules. The rules in the <<rule-list>> 
only apply when the {{ScrollTrigger}} is active.

As a special case, if one of the rules in the <<rule-list>> defines an 
[=animation=] using the 'animation-name' property, the 
[=timeline=] of that animation is associated with the {{ScrollTrigger}},
as if using the 'animation-trigger' property.

The syntax is designed to be extensible to other types of triggers in the future.

Issue: Do we need 'animation-trigger' at all, or is ''@trigger'' sufficient?

Issue: Should this be called &lsquo;@scroll&rsquo; perhaps? Or integrated with
media queries somehow?

## Examples ## {#trigger-examples}

<div class="example">
  Spin an element while the page's vertical scroll offset is within a range
  <pre class="lang-javascript">
    let spinner = document.getElementById("spinner");
    let effect = new KeyframeEffect(
      spinner,
      [
        { transform: 'rotate(0)' },
        { transform: 'rotate(1turn)' }
      ],
      { 
        duration: 300,
        fill: 'both',
        easing: 'linear',
        iterations: Infinity
      });
    let timeline = new DocumentTimeline({
      trigger: new ScrollTrigger({
        scrollSource: document.documentElement,
        orientation: "vertical",
        kind: "range",
        scrollOffset: "500px",
        endScrollOffset: "1000px"
      });
    });
    let animation = new Animation(effect, timeline);
    animation.play();
  </pre>
</div>

<div class="example">
  The same thing with CSS, using 'animation-trigger'
  <pre class="lang-css">
    @keyframes spin {
      from {
        transform: rotate(0);
      }
      to {
        transform: rotate(1turn);
      }
    }
    #spinner {
      animation-name: spin;
      animation-duration: 300ms;
      animation-fill-mode: both;
      animation-iteration-count: infinite;
      animation-timing-function: linear;
      /* Assume the HTML element has id 'root' */
      animation-trigger: scroll(element(#root), vertical, 500px, 1000px);
    }
  </pre>
</div>

<div class="example">
  The same thing with CSS, using ''@trigger''
  <pre class="lang-css">
    @keyframes spin {
      from {
        transform: rotate(0);
      }
      to {
        transform: rotate(1turn);
      }
    }
    /* Assume the HTML element has id 'root' */
    @trigger scroll(element(#root), vertical, 500px, 1000px) {
      #spinner {
        animation-name: spin;
        animation-duration: 300ms;
        animation-fill-mode: both;
        animation-iteration-count: infinite;
        animation-timing-function: linear;
      }
    }
  </pre>
</div>

<div class="example">
  Using ''@trigger'' for things other than animations
  <pre class="lang-css">
    /* 
      Elements with the class 'elusive' are only displayed while the scroll offset
      is in the range [200, 300].
      Note that 'display' can't be animated normally.
      Assume the HTML element has id 'root' 
    */
    .elusive {
      display: none;
    }
    @trigger scroll(element(#root), vertical, 200px, 300px) {
      .elusive {
        display: block;
      }
    }
  </pre>
</div>

# Controlling animation playback # {#controlling-animation-playback}

## The {{ScrollTimeline}} interface ## {#scrolltimeline-interface}

<pre class="idl">
enum ScrollTimelineAutoKeyword { "auto" };

dictionary ScrollTimelineOptions {
  required ScrollTrigger trigger;
  (double or ScrollTimelineAutoKeyword) timeRange = "auto";
  FillMode fill = "none";
};

[Constructor(ScrollTimelineOptions options)]
interface ScrollTimeline : AnimationTimeline {
  attribute (double or ScrollTimelineAutoKeyword) timeRange;
  attribute FillMode fill;
};
</pre>

<div link-for-hint="ScrollTrigger">

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 {{ScrollTimeline}} must have a {{AnimationTimeline/trigger}}, it must be of type
{{ScrollTrigger}}, and the trigger's {{kind}} must be {{range}}. If these criteria
are not met, a <strong>TypeError</strong> is thrown from the constructor.

The scroll container whose scrolling drives the timeline is the trigger's 
{{scrollSource}}. The direction of scrolling that drives the timeline is the 
trigger's {{orientation}}.

<div class="attributes">

:   <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, {{ScrollTimeline/timeRange}} represents the number of
    milliseconds to map to the scroll range defined by
    {{AnimationTimeline/trigger}}. As a result, this value does 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 
    {{AnimationTimeline/trigger}}.{{scrollOffset}} to 
    {{AnimationTimeline/trigger}}.{{endScrollOffset}},
    to the [=effective time range=].

:   <dfn attribute for=ScrollTimeline>fill</dfn>
::  Determines whether the timeline is active even when the scroll offset is outside
    the range defined by [{{scrollOffset}}, {{endScrollOffset}}].

    Possible values are:

    :   none
    ::  The timeline is inactive when the scroll offset is less than {{scrollOffset}} 
        or greater than {{endScrollOffset}}.

    :   forwards
    ::  When the scroll offset is less than {{scrollOffset}}, the
        timeline's [=current time=] is 0.
        When the scroll offset is greater than {{endScrollOffset}}, the
        timeline is inactive.

    :   backwards
    ::  When the scroll offset is less than {{scrollOffset}}, the
        timeline is inactive.
        When the scroll offset is greater than {{endScrollOffset}}, the
        timeline's [=current time=] is its 
        [=effective time range=].

    :   both
    ::  When the scroll offset is less than {{scrollOffset}}, the
        timeline's [=current time=] is 0.
        When the scroll offset is greater than {{endScrollOffset}}, the
        timeline's [=current time=] is its 
        [=effective time range=].

    :   auto
    ::  Behaves the same as <code>none</code>.
        
    ISSUE: A {{ScrollTrigger}} is only active when the scroll offset is within the range,
           and a timeline is inactive when its trigger is inactive. How can we reconcile
           this will fill modes, which require an active timeline outside the range in
           some situations?

</div>

### The effective time range of a {{ScrollTimeline}} ### {#efffective-time-range-algorithm}

The <dfn>effective time range</dfn> of a {{ScrollTimeline}} is calculated as follows:

<div class="switch">

:   If the {{ScrollTimeline/timeRange}} has the value <code>"auto"</code>,
::  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
    behavior is unspecified.

:   Otherwise,
::  The [=effective time range=] is the {{ScrollTimeline}}'s 
    {{ScrollTimeline/timeRange}}.

</div>

### The current time of a {{ScrollTimeline}} ### {#current-time-algorithm}

The [=current time=] of a {{ScrollTimeline}} is calculated
as follows:

1.  Let <var>current scroll offset</var> be the current scroll offset of {{scrollSource}}
    in the direction specified by {{orientation}}.

2.  If <var>current scroll offset</var> is less than {{scrollOffset}}, return an unresolved
    time value if {{ScrollTimeline/fill}} is <code>none</code> or <code>backwards</code>, 
    or 0 otherwise.

3.  If <var>current scroll offset</var> is greater than or equal to {{endScrollOffset}}, 
    return an unresolved time value if {{ScrollTimeline/fill}} is <code>none</code> or
    <code>forwards</code>, or the [=effective time range=] otherwise.

4.  Return the result of evaluating the following expression:

    <blockquote>
      <code>(<var>current scroll offset</var> - {{scrollOffset}}) / ({{endScrollOffset}} - {{scrollOffset}}) &times; [=effective time range=]</code>
    </blockquote>


</div>  <!-- link-for-hint="ScrollTrigger" -->

## The 'animation-timeline' property ## {#animation-timeline}

A {{ScrollTimeline}} may be applied to a CSS Animation [[CSS3-ANIMATIONS]] using
the 'animation-timeline' property.

<pre class='propdef'>
Name: animation-timeline
Value: <<single-animation-timeline>>#
Initial: auto
Applies to: all elements, ::before and ::after pseudo-elements
Inherited: none
Animatable: no
Percentages: N/A
Media: interactive
Computed value: As specified
Canonical order: per grammar
</pre>

<dfn>&lt;single-animation-timeline></dfn> = auto | scroll([<<time>> [, <<single-animation-fill-mode>>]])

The 'animation-timeline' property is similar to properties like 'animation-duration' and 
'animation-timing-function' in that it can have one or more values, each one imparting 
additional behavior to a corresponding [=animation=] on the 
element, with the timelines matched up with animations as described 
[[css-animations-1#animation-name|here]].

Each value has type <<single-animation-timeline>>, whose possible values have the
following effects:

:   auto
::  The animation's [=timeline=] is a {{DocumentTimeline}} 

    If 'animation-trigger' is ''animation-trigger/none'', the <a>default document timeline</a> is used;
    otherwise, a new {{DocumentTimeline}} with the appropriate 
    {{AnimationTimeline/trigger}} is generated.

    Issue: Do we re-use {{DocumentTimeline}} objects when the trigger is the same?

:   scroll([<<time>> [, <<single-animation-fill-mode>>]])
::  The animation's [=timeline=] is a {{ScrollTimeline}}.

    The <<time>> value, if specified, determines the timeline's {{ScrollTimeline/timeRange}}.

    The <<single-animation-fill-mode>> value, if specified, determines the timeline's
    {{ScrollTimeline/fill}}.

    If a {{ScrollTrigger}} isn't specified using the 'animation-trigger' property, the animation's
    timeline is given a default {{ScrollTrigger}}, as if via <code>animation-trigger: scroll()</code>.

## Examples ## {#timeline-examples}

<div class="example">
  Draw a reading progress bar along the top of the page as the user scrolls
  <pre class="lang-css">
    #progress {
      position: fixed;
      top: 0;
      width: 0;
      height: 2px;
      background-color: red;
    }
  </pre>
  <pre class="lang-javascript">
    let progress = document.getElementById("progress");
    let effect = new KeyframeEffect(
      progress,
      [
        { width: "0vw" },
        { width: "100vw" }
      ],
      {
        duration: 1000,
        easing: "linear"
      });
    let timeline = new ScrollTimeline({
      trigger: new ScrollTrigger({
        scrollSource: document.documentElement,
        orientation: "vertical",
        kind: "range"
      })      
    });
    let animation = new Animation(effect, timeline);
    animation.play();
  </pre>
</div>

<div class="example">
  The same thing with CSS, using 'animation-trigger'
  <pre class="lang-css">
    @keyframes progress {
      from {
        width: 0vw;
      }
      to {
        width: 100vw;
      }
    }
    #progress {
      position: fixed;
      top: 0;
      width: 0;
      height: 2px;
      background-color: red;
      animation-name: progress;
      animation-duration: 1s;
      animation-timing-function: linear;
      /* Assume the HTML element has id 'root' */
      animation-trigger: scroll(element(#root), vertical);
      animation-timeline: scroll();
    }
  </pre>
</div>

<div class="example">
  The same thing with CSS, using ''@trigger''
  <pre class="lang-css">
    @keyframes progress {
      from {
        width: 0vw;
      }
      to {
        width: 100vw;
      }
    }
    #progress {
      position: fixed;
      top: 0;
      width: 0;
      height: 2px;
      background-color: red;
    }
    /* Assume the HTML element has id 'root' */
    @trigger scroll(element(#root), vertical) {
      #progress {
        animation-name: progress;
        animation-duration: 1s;
        animation-timing-function: linear;
        animation-timeline: scroll();
      }
    }
  </pre>
</div>

# Avoiding cycles with layout # {#avoiding-cycles}

The ability for scrolling to drive the progress of an animation, gives rise to 
the possibility of <dfn>layout cycles</dfn>, where a change to a scroll offset
causes an animation's effect to update, which in turn causes a new change to the
scroll offset.

To avoid such cycles, animations with a {{ScrollTimeline}} are sampled once
per frame, after scrolling in response to input events has taken place, but
before {{requestAnimationFrame()}} callbacks are run. If the sampling of such an
animation causes a change to a scroll offset, the animation will not be
re-sampled to reflect the new offset until the next frame.

The implication of this is that in some situations, in a given frame, the 
rendered scroll offset of a scroll container may not be consistent with the state 
of an animation driven by scrolling that scroll container. However, this will
only occur in situations where the animation's effect changes the scroll offset
of that same scroll container (in other words, in situations where the animation's
author is asking for trouble). In normal situations, including - importantly - 
when scrolling happens in response to input events, the rendered scroll offset
and the state of scroll-driven animations will be consistent in each frame.