Add docs for CSS Scroll-driven animations

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

@@ -0,0 +1,167 @@
+---
+title: "AnimationTimeline: getCurrentTime() method"
+short-title: getCurrentTime()
+slug: Web/API/AnimationTimeline/getCurrentTime
+page-type: web-api-instance-method
+status:
+  - experimental
+browser-compat: api.AnimationTimeline.getCurrentTime
+---
+
+{{ APIRef("Web Animations") }}{{seecompattable}}
+
+The **`getCurrentTime()`** method of the [Web Animations API](/en-US/docs/Web/API/Web_Animations_API)'s {{domxref("AnimationTimeline")}} interface returns a representation of how far an animation has progressed through named timeline ranges in its associated timeline.
+
+## Syntax
+
+```js-nolint
+getCurrentTime()
+getCurrentTime(options)
+```
+
+### Parameters
+
+- `options` {{optional_inline}}
+  - : An options object containing the following properties:
+    - `range` {{optional_inline}}
+      - : A string representing a named timeline range (see the CSS {{cssxref("animation-range")}} property for a guide to valid values) within which to measure the timeline progression.
+
+### Return value
+
+A {{domxref("CSSNumericValue")}} representing how far an animation has progressed through its associated timeline. For time-based animations, this should be a {{domxref("CSSUnitValue")}} with `ms` units. For [CSS scroll-driven animations](/en-US/docs/Web/CSS/CSS_scroll-driven_animations), this should be a {{domxref("CSSUnitValue")}} with `percent` units.
+
+## Examples
+
+### Tracking the progress of a view progress timeline
+
+In this example, we animate an element with a `class` of `subject` along a view progress timeline — it animates when moved upwards through the document as it scrolls. Every 250 ms, we output the `getCurrentTime()` value to an output element in the top-right corner.
+
+#### HTML
+
+The HTML for the example is shown below.
+
+```html
+<div class="content">
+  <h1>Content</h1>
+
+  <p>
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
+    tempor incididunt ut labore et dolore magna aliqua. Risus quis varius quam
+    quisque id. Et ligula ullamcorper malesuada proin libero nunc consequat
+    interdum varius. Elit ullamcorper dignissim cras tincidunt lobortis feugiat
+    vivamus at augue.
+  </p>
+
+  <p>
+    Dolor sed viverra ipsum nunc aliquet. Sed sed risus pretium quam vulputate
+    dignissim. Tortor aliquam nulla facilisi cras. A erat nam at lectus urna
+    duis convallis convallis. Nibh ipsum consequat nisl vel pretium lectus.
+    Sagittis aliquam malesuada bibendum arcu vitae elementum. Malesuada bibendum
+    arcu vitae elementum curabitur vitae nunc sed velit.
+  </p>
+
+  <div class="subject animation"></div>
+
+  <p>
+    Adipiscing enim eu turpis egestas pretium aenean pharetra magna ac. Arcu
+    cursus vitae congue mauris rhoncus aenean vel. Sit amet cursus sit amet
+    dictum. Augue neque gravida in fermentum et. Gravida rutrum quisque non
+    tellus orci ac auctor augue mauris. Risus quis varius quam quisque id diam
+    vel quam elementum. Nibh praesent tristique magna sit amet purus gravida
+    quis. Duis ultricies lacus sed turpis tincidunt id aliquet. In egestas erat
+    imperdiet sed euismod nisi. Eget egestas purus viverra accumsan in nisl nisi
+    scelerisque. Netus et malesuada fames ac.
+  </p>
+
+  <div class="output"></div>
+</div>
+```
+
+#### CSS
+
+The CSS for the example looks like this:
+
+```css
+.subject {
+  width: 300px;
+  height: 200px;
+  margin: 0 auto;
+  background-color: deeppink;
+}
+
+.content {
+  width: 75%;
+  max-width: 800px;
+  margin: 0 auto;
+}
+
+.output {
+  position: fixed;
+  top: 5px;
+  right: 5px;
+}
+
+p,
+h1,
+div {
+  font-family: Arial, Helvetica, sans-serif;
+}
+
+h1 {
+  font-size: 3rem;
+}
+
+p {
+  font-size: 1.5rem;
+  line-height: 1.5;
+}
+```
+
+#### JavaScript
+
+In the JavaScript, we grab references to the `subject` and `output` `<div>`s, then create a new {{domxref("ViewTimeline")}}, associating it with the `subject` element to specify that the timeline progress is based on this element's visibility through its scrolling ancestor. We then animate the `subject` element with the Web Animations API. Last of all, we run `getCurrentTime()` on the timeline every 250ms, and display the new value in the `output` element.
+
+```js
+const subject = document.querySelector(".subject");
+const output = document.querySelector(".output");
+
+const timeline = new ViewTimeline({
+  subject,
+  axis: "block",
+});
+
+subject.animate(
+  {
+    opacity: [0, 1],
+    transform: ["scaleX(0)", "scaleX(1)"],
+  },
+  {
+    fill: "both",
+    timeline,
+  }
+);
+
+setInterval(() => {
+  output.textContent = timeline.getCurrentTime();
+}, 100);
+```
+
+#### Result
+
+Scroll to see the subject element being animated and the change in percentage progress.
+
+{{EmbedLiveSample("Tracking the progress of a view progress timeline", "100%", "480px")}}
+
+## 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("DocumentTimeline")}}, {{domxref("ScrollTimeline")}}, {{domxref("ViewTimeline")}}

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

@@ -11,9 +11,14 @@ The `AnimationTimeline` interface of the [Web Animations API](/en-US/docs/Web/AP
 
 ## 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.
 
+## Instance methods
+
+- {{domxref("AnimationTimeline.getCurrentTime", "getCurrentTime()")}} {{ReadOnlyInline}}
+  - : Returns a representation of how far an animation has progressed through its associated timeline.
+
 ## Specifications
 
 {{Specifications}}
@@ -25,5 +30,6 @@ 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")}}
+- [CSS scroll-driven animations](/en-US/docs/Web/CSS/CSS_scroll-driven_animations)
+- {{domxref("AnimationTimeline")}}, {{domxref("DocumentTimeline")}}, {{domxref("ScrollTimeline")}}, {{domxref("ViewTimeline")}}
 - {{domxref("Document.timeline")}}

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

@@ -33,10 +33,9 @@ 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.
     - `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")}}.
 
 ### Return value
 

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 `vertical`, while for vertical writing modes, it is the same as `horizontal`.
+- `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 the `horizontal` axis, while for vertical writing modes, this is the same as `vertical`.
+- `vertical`
+  - : The scrollbar on the vertical axis of the scroll container.
+- `horizontal`
+  - : 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
+
+- [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/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")}}