Add docs for CSS Scroll-driven animations

files/en-us/web/api/animationtimeline/index.md

@@ -7,11 +7,15 @@ browser-compat: api.AnimationTimeline
 
 {{ APIRef("Web Animations") }}
 
-The `AnimationTimeline` interface of the [Web Animations API](/en-US/docs/Web/API/Web_Animations_API) represents the timeline of an animation. This interface exists to define timeline features (inherited by {{domxref("DocumentTimeline")}} and future timeline types) and is not itself directly used by developers. Anywhere you see `AnimationTimeline`, you should use `DocumentTimeline` or any other timeline type instead.
+The `AnimationTimeline` interface of the [Web Animations API](/en-US/docs/Web/API/Web_Animations_API) represents the timeline of an animation. This interface exists to define timeline features, inherited by other timeline types:
+
+- {{domxref("DocumentTimeline")}}
+- {{domxref("ScrollTimeline")}}
+- {{domxref("ViewTimeline")}}
 
 ## Instance properties
 
-- {{domxref("AnimationTimeline.currentTime")}} {{ReadOnlyInline}}
+- {{domxref("AnimationTimeline.currentTime", "currentTime")}} {{ReadOnlyInline}}
   - : Returns the time value in milliseconds for this timeline or `null` if this timeline is inactive.
 
 ## Specifications
@@ -24,6 +28,7 @@ The `AnimationTimeline` interface of the [Web Animations API](/en-US/docs/Web/AP
 
 ## See also
 
-- [Web Animations API](/en-US/docs/Web/API/Web_Animations_API)
-- {{domxref("DocumentTimeline")}}
+- {{domxref("DocumentTimeline")}}, {{domxref("ScrollTimeline")}}, {{domxref("ViewTimeline")}}
 - {{domxref("Document.timeline")}}
+- [Web Animations API](/en-US/docs/Web/API/Web_Animations_API)
+- [CSS scroll-driven animations](/en-US/docs/Web/CSS/CSS_scroll-driven_animations)

files/en-us/web/api/element/animate/index.md

@@ -33,10 +33,31 @@ animate(keyframes, options)
     milliseconds), **or** an Object containing one or more timing properties described in the [`KeyframeEffect()` options parameter](/en-US/docs/Web/API/KeyframeEffect/KeyframeEffect#parameters) and/or the following options:
 
     - `id` {{optional_inline}}
-      - : A property unique to `animate()`: a string
-        with which to reference the animation.
+      - : A property unique to `animate()`: A string with which to reference the animation.
+    - `rangeEnd` {{optional_inline}}
+
+      - : Specifies the end of an animation's attachment range along its timeline, i.e. where along the timeline an animation will end. The JavaScript equivalent of the CSS {{cssxref("animation-range-end")}} property. `rangeEnd` can take several different value types, as follows:
+
+        - A string that can be `normal` (meaning no change to the animation's attachment range), a CSS {{cssxref("length-percentage")}} representing an offset, a `<timeline-range-name>`, or a `<timeline-range-name>` with a `<length-percentage>` following it. See [`animation-range`](/en-US/docs/Web/CSS/animation-range) for a detailed description of the available values. Also check out the [View Timeline Ranges Visualizer](https://scroll-driven-animations.style/tools/view-timeline/ranges/), which shows exactly what the different values mean in an easy visual format.
+        - An object containing `rangeName` (a string) and `offset` (a {{domxref("CSSNumericValue")}}) properties representing a `<timeline-range-name>` and `<length-percentage>`, as described in the previous bullet. For example:
+
+          ```js
+          {
+            rangeName: 'entry',
+            offset: CSS.percent('100'),
+          }
+          ```
+
+        - A {{domxref("CSSNumericValue")}} representing an offset, for example:
+
+          ```js
+          CSS.percent("100");
+          ```
+
+    - `rangeStart` {{optional_inline}}
+      - : Specifies the start of an animation's attachment range along its timeline, i.e. where along the timeline an animation will start. The JavaScript equivalent of the CSS {{cssxref("animation-range-start")}} property. `rangeStart` can take the same value types as `rangeEnd`.
     - `timeline` {{optional_inline}}
-      - : A property unique to `animate()`: the {{domxref("AnimationTimeline")}} to associate with the animation. Defaults to {{domxref("Document.timeline")}}.
+      - : A property unique to `animate()`: The {{domxref("AnimationTimeline")}} to associate with the animation. Defaults to {{domxref("Document.timeline")}}. The JavaScript equivalent of the CSS {{cssxref("animation-timeline")}} property.
 
 ### Return value
 
@@ -137,6 +158,33 @@ let rotate360 = [{ transform: "rotate(360deg)" }];
 We have only specified the end state of the animation, and the beginning state is
 implied.
 
+### timeline, rangeStart, and rangeEnd
+
+Typical usage of the `timeline`, `rangeStart`, and `rangeEnd` properties might look like this:
+
+```js
+const img = document.querySelector("img");
+
+const timeline = new ViewTimeline({
+  subject: img,
+  axis: "block",
+});
+
+img.animate(
+  {
+    opacity: [0, 1],
+    transform: ["scaleX(0)", "scaleX(1)"],
+  },
+  {
+    fill: "both",
+    duration: 1,
+    timeline,
+    rangeStart: { rangeName: "entry", offset: CSS.percent("0") },
+    rangeEnd: CSS.percent("50"),
+  }
+);
+```
+
 ## Specifications
 
 {{Specifications}}
@@ -147,6 +195,8 @@ implied.
 
 ## See also
 
-- [Web Animations API](/en-US/docs/Web/API/Web_Animations_API)
-- {{domxref("Element.getAnimations()")}}
 - {{domxref("Animation")}}
+- {{domxref("Element.getAnimations()")}}
+- {{cssxref("animation-range-end")}}, {{cssxref("animation-range-start")}}, {{cssxref("animation-timeline")}}
+- [CSS scroll-driven animations](/en-US/docs/Web/CSS/CSS_scroll-driven_animations)
+- [Web Animations API](/en-US/docs/Web/API/Web_Animations_API)

files/en-us/web/api/scrolltimeline/axis/index.md

@@ -0,0 +1,46 @@
+---
+title: "ScrollTimeline: axis property"
+short-title: axis
+slug: Web/API/ScrollTimeline/axis
+page-type: web-api-instance-property
+status:
+  - experimental
+browser-compat: api.ScrollTimeline.axis
+---
+
+{{APIRef("Web Animations")}}{{SeeCompatTable}}
+
+The **`axis`** read-only property of the
+{{domxref("ScrollTimeline")}} interface returns an enumerated value representing the scroll axis that is driving the progress of the timeline.
+
+## Value
+
+An enumerated value. Possible values are:
+
+- `"block"`
+  - : The scrollbar on the block axis of the scroll container, which is the axis in the direction perpendicular to the flow of text within a line. For horizontal writing modes, such as standard English, this is the same as `"y"`, while for vertical writing modes, it is the same as `"x"`.
+- `"inline"`
+  - : The scrollbar on the inline axis of the scroll container, which is the axis in the direction parallel to the flow of text in a line. For horizontal writing modes, this is the same as `"x"`, while for vertical writing modes, this is the same as `"y"`.
+- `"y"`
+  - : The scrollbar on the vertical axis of the scroll container.
+- `"x"`
+  - : The scrollbar on the horizontal axis of the scroll container.
+
+## Examples
+
+See the main {{domxref("ScrollTimeline")}} page for an example.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("ScrollTimeline")}}
+- {{domxref("AnimationTimeline")}}, {{domxref("ViewTimeline")}}
+- [Web Animations API](/en-US/docs/Web/API/Web_Animations_API)
+- [CSS scroll-driven animations](/en-US/docs/Web/CSS/CSS_scroll-driven_animations)

files/en-us/web/api/scrolltimeline/index.md

@@ -0,0 +1,123 @@
+---
+title: ScrollTimeline
+slug: Web/API/ScrollTimeline
+page-type: web-api-interface
+status:
+  - experimental
+browser-compat: api.ScrollTimeline
+---
+
+{{APIRef("Web Animations")}}{{SeeCompatTable}}
+
+The **`ScrollTimeline`** interface of the {{domxref("Web Animations API", "Web Animations API", "", "nocode")}} represents a scroll progress timeline (see [CSS scroll-driven animations](/en-US/docs/Web/CSS/CSS_scroll-driven_animations) for more details).
+
+Pass a `ScrollTimeline` instance to the {{domxref("Animation.Animation", "Animation()")}} constructor or the {{domxref("Element.animate()", "animate()")}} method to specify it as the timeline that will control the progress of the animation.
+
+{{InheritanceDiagram}}
+
+## Constructor
+
+- {{domxref("ScrollTimeline.ScrollTimeline", "ScrollTimeline()")}}
+  - : Creates a new `ScrollTimeline` object instance.
+
+## Instance properties
+
+_This interface also inherits the properties of its parent, {{domxref("AnimationTimeline")}}._
+
+- {{domxref("ScrollTimeline.source", "source")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Returns a reference to the scrollable element (_scroller_) whose scroll position is driving the progress of the timeline and therefore the animation.
+- {{domxref("ScrollTimeline.axis", "axis")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Returns an enumerated value representing the scroll axis that is driving the progress of the timeline.
+
+## Instance methods
+
+_This interface inherits the methods of its parent, {{domxref("AnimationTimeline")}}._
+
+## Examples
+
+### Displaying the source and axis of a scroll progress timeline
+
+In this example, we animate an element with a `class` of `box` along a view progress timeline — it animates across the screen as the document scrolls. We output the `source` element and scroll `axis` to an `output` element in the top-right corner.
+
+#### HTML
+
+The HTML for the example is shown below.
+
+```html
+<div class="content"></div>
+<div class="box"></div>
+<div class="output"></div>
+```
+
+#### CSS
+
+The CSS for the example looks like this:
+
+```css
+.content {
+  height: 2000px;
+}
+
+.box {
+  width: 100px;
+  height: 100px;
+  border-radius: 10px;
+  background-color: rebeccapurple;
+  position: fixed;
+  top: 20px;
+  left: 0%;
+}
+
+.output {
+  font-family: Arial, Helvetica, sans-serif;
+  position: fixed;
+  top: 5px;
+  right: 5px;
+}
+```
+
+#### JavaScript
+
+In the JavaScript, we grab references to the `box` and `output` `<div>`s, then create a new `ScrollTimeline`, specifying that the element that will drive the scroll timeline progress is the document ({{htmlelement("html")}}) element, and the scroll axis is the `block` axis. We then animate the `box` element with the Web Animations API. Last of all, we display the source element and axis in the `output` element.
+
+```js
+const box = document.querySelector(".box");
+const output = document.querySelector(".output");
+
+const timeline = new ScrollTimeline({
+  source: document.documentElement,
+  axis: "block",
+});
+
+box.animate(
+  {
+    rotate: ["0deg", "720deg"],
+    left: ["0%", "100%"],
+  },
+  {
+    timeline,
+  }
+);
+
+output.textContent = `Timeline source element: ${timeline.source.nodeName}. Timeline scroll axis: ${timeline.axis}`;
+```
+
+#### Result
+
+Scroll to see the box being animated.
+
+{{EmbedLiveSample("Displaying the source and axis of a scroll progress timeline", "100%", "320px")}}
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Web Animations API](/en-US/docs/Web/API/Web_Animations_API)
+- [CSS scroll-driven animations](/en-US/docs/Web/CSS/CSS_scroll-driven_animations)
+- {{domxref("AnimationTimeline")}}, {{domxref("ViewTimeline")}}

files/en-us/web/api/scrolltimeline/scrolltimeline/index.md

@@ -0,0 +1,61 @@
+---
+title: "ScrollTimeline: ScrollTimeline() constructor"
+short-title: ScrollTimeline()
+slug: Web/API/ScrollTimeline/ScrollTimeline
+page-type: web-api-constructor
+status:
+  - experimental
+browser-compat: api.ScrollTimeline.ScrollTimeline
+---
+
+{{APIRef("History API")}}
+
+The **`ScrollTimeline()`** constructor creates a new {{domxref("ScrollTimeline")}} object instance.
+
+## Syntax
+
+```js-nolint
+new ScrollTimeline(options)
+```
+
+### Parameters
+
+- `options`
+
+  - : An object that can contain the following properties:
+
+    - `source`
+      - : A reference to an {{domxref("Element")}} representing the scrollable element (_scroller_) whose scroll position will drive the progress of the timeline.
+    - `axis` {{optional_inline}}
+
+      - : An enumerated value representing the scroll axis that will drive the progress of the timeline. Possible values are:
+
+        - `"block"`: The scrollbar on the block axis of the scroll container, which is the axis in the direction perpendicular to the flow of text within a line. For horizontal writing modes, such as standard English, this is the same as `"y"`, while for vertical writing modes, it is the same as `"x"`.
+        - `"inline"`: The scrollbar on the inline axis of the scroll container, which is the axis in the direction parallel to the flow of text in a line. For horizontal writing modes, this is the same as `"x"`, while for vertical writing modes, this is the same as `"y"`.
+        - `"y"`: The scrollbar on the vertical axis of the scroll container.
+        - `"x"`: The scrollbar on the horizontal axis of the scroll container.
+
+        If omitted, `axis` defaults to `"block"`.
+
+### Return value
+
+A new {{domxref("ScrollTimeline")}} object instance.
+
+## Examples
+
+See the main {{domxref("ScrollTimeline")}} page for an example.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Web Animations API](/en-US/docs/Web/API/Web_Animations_API)
+- [CSS scroll-driven animations](/en-US/docs/Web/CSS/CSS_scroll-driven_animations)
+- {{domxref("ScrollTimeline")}}
+- {{domxref("AnimationTimeline")}}, {{domxref("ViewTimeline")}}

files/en-us/web/api/scrolltimeline/source/index.md

@@ -0,0 +1,37 @@
+---
+title: "ScrollTimeline: source property"
+short-title: source
+slug: Web/API/ScrollTimeline/source
+page-type: web-api-instance-property
+status:
+  - experimental
+browser-compat: api.ScrollTimeline.source
+---
+
+{{APIRef("Web Animations")}}{{SeeCompatTable}}
+
+The **`source`** read-only property of the
+{{domxref("ScrollTimeline")}} interface returns a reference to the scrollable element (_scroller_) whose scroll position is driving the progress of the timeline and therefore the animation.
+
+## Value
+
+An {{domxref("Element")}}.
+
+## Examples
+
+See the main {{domxref("ScrollTimeline")}} page for an example.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Web Animations API](/en-US/docs/Web/API/Web_Animations_API)
+- [CSS scroll-driven animations](/en-US/docs/Web/CSS/CSS_scroll-driven_animations)
+- {{domxref("ScrollTimeline")}}
+- {{domxref("AnimationTimeline")}}, {{domxref("ViewTimeline")}}