Document AnimationTimeline.duration (#40979)

* Document AnimationTimeline.duration

* Update files/en-us/web/api/animationtimeline/duration/index.md

Co-authored-by: Hamish Willee <[email protected]>

---------

Co-authored-by: Hamish Willee <[email protected]>

Author: Elchi3

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

@@ -0,0 +1,70 @@
+---
+title: "AnimationTimeline: duration property"
+short-title: duration
+slug: Web/API/AnimationTimeline/duration
+page-type: web-api-instance-property
+browser-compat: api.AnimationTimeline.duration
+---
+
+{{ APIRef("Web Animations") }}
+
+The **`duration`** read-only property of the [Web Animations API](/en-US/docs/Web/API/Web_Animations_API)'s {{domxref("AnimationTimeline")}} interface returns the maximum value for this timeline or `null`.
+
+Note that the derived interfaces {{domxref("ViewTimeline")}} and {{domxref("ScrollTimeline")}} always return a duration of 100%, while {{domxref("DocumentTimeline")}} has no duration, and returns `null`.
+
+## Value
+
+A number representing the timeline's duration (the maximum value for this timeline) or `null`.
+
+## Examples
+
+### View timeline duration
+
+The {{domxref("ViewTimeline")}} always returns a duration of 100% as a {{domxref("CSSUnitValue")}}.
+
+```js
+const subject = document.querySelector(".subject");
+const timeline = new ViewTimeline({
+  subject,
+  axis: "block",
+});
+
+timeline.duration; // CSSUnitValue { value: 100, unit: "percent" }
+```
+
+### Scroll timeline duration
+
+The {{domxref("ScrollTimeline")}} always returns a duration of 100% as a {{domxref("CSSUnitValue")}}.
+
+```js
+const timeline = new ScrollTimeline({
+  source: document.documentElement,
+  axis: "block",
+});
+
+timeline.duration; // CSSUnitValue { value: 100, unit: "percent" }
+```
+
+### Document timeline duration
+
+The {{domxref("DocumentTimeline")}} has no duration.
+
+```js
+document.timeline.duration; // null
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Web Animations API](/en-US/docs/Web/API/Web_Animations_API)
+- {{domxref("AnimationTimeline")}}
+- {{domxref("DocumentTimeline")}} inherits this property
+- {{domxref("ScrollTimeline")}} inherits this property
+- {{domxref("ViewTimeline")}} inherits this property

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

@@ -17,6 +17,8 @@ The `AnimationTimeline` interface of the [Web Animations API](/en-US/docs/Web/AP
 
 - {{domxref("AnimationTimeline.currentTime", "currentTime")}} {{ReadOnlyInline}}
   - : Returns the time value in milliseconds for this timeline or `null` if this timeline is inactive.
+- {{domxref("AnimationTimeline.duration", "duration")}} {{ReadOnlyInline}}
+  - : Returns the maximum value for this timeline or `null`.
 
 ## Specifications