@videojs/react 10.0.0-beta.26 → 10.0.0-beta.28

package/docs/reference/time-slider.md

@@ -7,15 +7,46 @@ A slider component for seeking through media playback time
 tsx
 
 ```
-<TimeSlider.Root />
+<TimeSlider.Root>
+  <TimeSlider.Track>
+    <TimeSlider.Buffer />
+    <TimeSlider.Fill />
+  </TimeSlider.Track>
+  <TimeSlider.Thumb />
+  <TimeSlider.Preview>
+    <TimeSlider.ChapterTitle />
+    <TimeSlider.Value type="pointer" />
+  </TimeSlider.Preview>
+</TimeSlider.Root>
 ```
 
+Add `Chapters` to progressively divide the track when a default `kind="chapters"` text track is available.
+
+tsx
+
+```
+<TimeSlider.Chapters
+  renderChapter={(props, state) => (
+    <div {...props}>
+      <TimeSlider.Track>
+        <TimeSlider.Buffer />
+        <TimeSlider.Fill />
+      </TimeSlider.Track>
+    </div>
+  )}
+/>
+```
+
+`renderChapter` receives the attributes, styles, and state for each normalized chapter range. When no chapter cues are available, it renders once as a full-width, cue-less range.
+
 ## Behavior
 
 Displays and controls the current playback position. Dragging the slider seeks the media. The fill level reflects `currentTime / duration` as a percentage, and the buffer level shows how much media has been buffered.
 
 Value changes during drag are throttled via the `changeThrottle` prop (default 100ms) using a leading+trailing throttle to keep the UI responsive without overwhelming the media element.
 
+Chapter cues are normalized into contiguous ranges. Any uncovered time becomes a gap range, so track geometry always spans the full duration. With no usable chapter cues, one gap range spans the entire slider. Gap ranges receive the same geometry styles but cannot be highlighted and have no chapter title.
+
 ## Styling
 
 Use [CSS custom properties](#root-css-custom-properties) to style the fill, pointer, and buffer levels:
@@ -40,6 +71,16 @@ css
 }
 ```
 
+Each rendered chapter receives `data-active` while playback is inside it and `data-highlighted` while the pointer is inside an authored chapter. Its geometry and local progress are exposed through:
+
+*   `--media-slider-chapter-start`
+*   `--media-slider-chapter-end`
+*   `--media-slider-chapter-width`
+*   `--media-slider-chapter-fill`
+*   `--media-slider-chapter-buffer`
+
+The generated fill and buffer parts also inherit the slider-level `--media-slider-fill` and `--media-slider-buffer` values. This allows every chapter to render full-width progress planes and use its chapter bounds as a clip, keeping progress transitions continuous across segments.
+
 ## Accessibility
 
 Renders with `role="slider"` and an automatic `aria-label` that resolves to “Seek” from the active locale. Override with the `label` prop. Keyboard controls:
@@ -49,6 +90,8 @@ Renders with `role="slider"` and an automatic `aria-label` that resolves to “S
 *   Home: seek to start
 *   End: seek to end
 
+`ChapterTitle` follows the pointer during pointer interaction. While the slider has keyboard focus, it follows the current playback position and announces chapter changes.
+
 ## Examples
 
 Nest sub-components for full control over the slider’s DOM structure. This example includes a track, fill bar, buffer indicator, draggable thumb, and a tooltip that shows the pointed-at time.
@@ -60,15 +103,15 @@ App.tsx
 App.css
 
 ```
-import { createPlayer, TimeSlider } from '@videojs/react';
+import { Container, createPlayer, TimeSlider } from '@videojs/react';
 import { Video, videoFeatures } from '@videojs/react/video';
 
-const Player = createPlayer({ features: videoFeatures });
+const { Player } = createPlayer({ features: videoFeatures });
 
 export default function WithParts() {
   return (
-    <Player.Provider>
-      <Player.Container className="media-container">
+    <Player>
+      <Container className="media-container">
         <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
         <TimeSlider.Root className="media-time-slider">
           <TimeSlider.Track className="media-slider-track">
@@ -78,8 +121,8 @@ export default function WithParts() {
           <TimeSlider.Thumb className="media-slider-thumb" />
           <TimeSlider.Value type="pointer" className="media-slider-value" />
         </TimeSlider.Root>
-      </Player.Container>
-    </Player.Provider>
+      </Container>
+    </Player>
   );
 }
 ```
@@ -184,6 +227,173 @@ export default function WithParts() {
 }
 ```
 
+### With chapters
+
+Add a default chapters track, then provide the markup used for each chapter. The deliberate one-minute gap in this example remains visible as an unlabelled, non-highlightable segment.
+
+0:00
+
+App.tsx
+
+App.css
+
+```
+import { Container, createPlayer, TimeSlider } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+export default function WithChapters() {
+  return (
+    <Player>
+      <Container className="media-container">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop crossOrigin="anonymous">
+          <track kind="chapters" src="/docs/demos/time-slider/chapters.vtt" srcLang="en" default />
+        </Video>
+        <TimeSlider.Root className="media-time-slider">
+          <TimeSlider.Chapters
+            className="media-slider-chapters"
+            renderChapter={(props) => (
+              <div {...props} className="media-slider-chapter">
+                <TimeSlider.Track className="media-slider-track">
+                  <TimeSlider.Buffer className="media-slider-buffer" />
+                  <TimeSlider.Fill className="media-slider-fill" />
+                </TimeSlider.Track>
+              </div>
+            )}
+          />
+          <TimeSlider.Thumb className="media-slider-thumb" />
+          <TimeSlider.Preview className="media-slider-preview">
+            <TimeSlider.ChapterTitle className="media-slider-chapter-title" />
+            <TimeSlider.Value type="pointer" />
+          </TimeSlider.Preview>
+        </TimeSlider.Root>
+      </Container>
+    </Player>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.media-time-slider {
+  position: absolute;
+  right: 12px;
+  bottom: 8px;
+  left: 12px;
+  display: flex;
+  align-items: center;
+  height: 20px;
+  color: white;
+  cursor: pointer;
+}
+
+.media-slider-chapters {
+  position: relative;
+  width: 100%;
+  height: 100%;
+}
+
+.media-slider-chapter {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  clip-path: inset(0 calc(100% - var(--media-slider-chapter-end)) 0 var(--media-slider-chapter-start));
+}
+
+.media-slider-track {
+  position: absolute;
+  right: 0;
+  left: 0;
+  height: 4px;
+  overflow: hidden;
+  background: rgb(255 255 255 / 30%);
+  border-radius: 9999px;
+  transition: height 150ms ease;
+}
+
+.media-slider-chapter .media-slider-track {
+  clip-path: inset(
+    0 calc(100% - var(--media-slider-chapter-end) + 2px) 0 calc(var(--media-slider-chapter-start) + 2px) round 9999px
+  );
+}
+
+.media-slider-chapter[data-highlighted] .media-slider-track {
+  height: 7px;
+}
+
+.media-slider-buffer,
+.media-slider-fill {
+  position: absolute;
+  inset-block: 0;
+  left: 0;
+  border-radius: inherit;
+  transition: width 200ms linear;
+}
+
+.media-slider-buffer {
+  width: var(--media-slider-buffer);
+  background: rgb(255 255 255 / 30%);
+}
+
+.media-slider-fill {
+  width: var(--media-slider-fill);
+  background: white;
+}
+
+.media-time-slider[data-dragging] .media-slider-fill {
+  width: var(--media-slider-pointer);
+  transition-duration: 0ms;
+}
+
+.media-slider-thumb {
+  position: absolute;
+  top: 50%;
+  left: var(--media-slider-fill);
+  width: 12px;
+  height: 12px;
+  background: white;
+  border-radius: 50%;
+  translate: -50% -50%;
+}
+
+.media-time-slider[data-dragging] .media-slider-thumb {
+  left: var(--media-slider-pointer);
+}
+
+.media-slider-preview {
+  position: absolute;
+  bottom: 100%;
+  left: var(--media-slider-pointer);
+  display: flex;
+  gap: 6px;
+  padding: 3px 7px;
+  color: white;
+  white-space: nowrap;
+  pointer-events: none;
+  background: rgb(0 0 0 / 80%);
+  border-radius: 4px;
+  opacity: 0;
+  translate: -50% -4px;
+}
+
+.media-time-slider[data-pointing] .media-slider-preview,
+.media-time-slider[data-interactive]:not([data-pointing]) .media-slider-preview {
+  opacity: 1;
+}
+
+.media-slider-chapter-title:empty {
+  display: none;
+}
+```
+
 ## API Reference
 
 ### 
@@ -506,6 +716,40 @@ Buffer level percentage (0–100), indicating how much media has been buffered.
 
 ### 
 
+ChapterTitle
+
+Displays the chapter title at the current pointer or keyboard position.
+
+### 
+
+Chapters
+
+Renders normalized chapter ranges across the full slider, including one full range when chapter cues are absent.
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`renderChapter`
+
+`(props: Omit<HTMLProps<HTMLElement>, 'ref'>, state: TimeSliderChapterState) => ReactElement`
+
+`—`
+
+▸
+
+Description
+
+Render one consumer-owned subtree for every normalized chapter range.
+
+### 
+
 Buffer
 
 Displays the buffered range on the slider track.

package/docs/reference/time.md

@@ -50,12 +50,12 @@ css
 
 Each `<Time.Value>` has:
 
+*   a native `<time datetime>` element for machine-readable time semantics
 *   `aria-label` for the static role label (“Current time”, “Duration”, “Remaining”)
-*   `aria-valuetext` for the dynamic human-readable time (“1 minute, 30 seconds”)
 
-No `aria-live` region is used — time updates too frequently and might overwhelm screen readers. The separator is `aria-hidden="true"` since screen readers already hear each time value separately. The negative sign is also `aria-hidden` because `aria-valuetext` already conveys “remaining”. In React, `<time datetime>` provides machine-readable time for parsers.
+No `aria-live` region is used — time updates too frequently and might overwhelm screen readers. The separator and negative sign are `aria-hidden="true"` because the accessible label already describes the value.
 
-Toggleable time displays receive `role="button"` and keyboard support for Enter and Space.
+Toggleable time displays receive `role="button"`, `tabindex="0"`, and keyboard support for Enter and Space. Their `aria-label` starts with the action and includes the current value. Their `aria-description` explains which values the control toggles between.
 
 ## Examples
 
@@ -68,19 +68,19 @@ App.tsx
 App.css
 
 ```
-import { createPlayer, Time } from '@videojs/react';
+import { Container, createPlayer, Time } from '@videojs/react';
 import { Video, videoFeatures } from '@videojs/react/video';
 
-const Player = createPlayer({ features: videoFeatures });
+const { Player } = createPlayer({ features: videoFeatures });
 
 export default function CurrentTime() {
   return (
-    <Player.Provider>
-      <Player.Container className="media-container">
+    <Player>
+      <Container className="media-container">
         <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
         <Time.Value type="current" className="media-time" />
-      </Player.Container>
-    </Player.Provider>
+      </Container>
+    </Player>
   );
 }
 ```
@@ -117,23 +117,23 @@ App.tsx
 App.css
 
 ```
-import { createPlayer, Time } from '@videojs/react';
+import { Container, createPlayer, Time } from '@videojs/react';
 import { Video, videoFeatures } from '@videojs/react/video';
 
-const Player = createPlayer({ features: videoFeatures });
+const { Player } = createPlayer({ features: videoFeatures });
 
 export default function CurrentDuration() {
   return (
-    <Player.Provider>
-      <Player.Container className="media-container">
+    <Player>
+      <Container className="media-container">
         <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
         <Time.Group className="time-group">
           <Time.Value type="current" />
           <Time.Separator />
           <Time.Value type="duration" />
         </Time.Group>
-      </Player.Container>
-    </Player.Provider>
+      </Container>
+    </Player>
   );
 }
 ```
@@ -173,19 +173,19 @@ App.tsx
 App.css
 
 ```
-import { createPlayer, Time } from '@videojs/react';
+import { Container, createPlayer, Time } from '@videojs/react';
 import { Video, videoFeatures } from '@videojs/react/video';
 
-const Player = createPlayer({ features: videoFeatures });
+const { Player } = createPlayer({ features: videoFeatures });
 
 export default function Remaining() {
   return (
-    <Player.Provider>
-      <Player.Container className="media-container">
+    <Player>
+      <Container className="media-container">
         <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
         <Time.Value type="remaining" className="media-time" />
-      </Player.Container>
-    </Player.Provider>
+      </Container>
+    </Player>
   );
 }
 ```
@@ -222,23 +222,23 @@ App.tsx
 App.css
 
 ```
-import { createPlayer, Time } from '@videojs/react';
+import { Container, createPlayer, Time } from '@videojs/react';
 import { Video, videoFeatures } from '@videojs/react/video';
 
-const Player = createPlayer({ features: videoFeatures });
+const { Player } = createPlayer({ features: videoFeatures });
 
 export default function CustomSeparator() {
   return (
-    <Player.Provider>
-      <Player.Container className="media-container">
+    <Player>
+      <Container className="media-container">
         <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
         <Time.Group className="time-group">
           <Time.Value type="current" />
           <Time.Separator> of </Time.Separator>
           <Time.Value type="duration" />
         </Time.Group>
-      </Player.Container>
-    </Player.Provider>
+      </Container>
+    </Player>
   );
 }
 ```
@@ -278,19 +278,19 @@ App.tsx
 App.css
 
 ```
-import { createPlayer, Time } from '@videojs/react';
+import { Container, createPlayer, Time } from '@videojs/react';
 import { Video, videoFeatures } from '@videojs/react/video';
 
-const Player = createPlayer({ features: videoFeatures });
+const { Player } = createPlayer({ features: videoFeatures });
 
 export default function CustomNegativeSign() {
   return (
-    <Player.Provider>
-      <Player.Container className="media-container">
+    <Player>
+      <Container className="media-container">
         <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
         <Time.Value type="remaining" negativeSign="~" className="media-time" />
-      </Player.Container>
-    </Player.Provider>
+      </Container>
+    </Player>
   );
 }
 ```
@@ -482,8 +482,52 @@ Group
 
 Container for composed time displays. Renders a `<span>` element.
 
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`children`
+
+`ReactNode`
+
+`—`
+
+▸
+
+Description
+
+Time value components to render inside the group.
+
 ### 
 
 Separator
 
-Divider between time values. Hidden from screen readers.
+Divider between time values. Hidden from screen readers.
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`children`
+
+`ReactNode`
+
+`—`
+
+▸
+
+Description
+
+Separator content. Defaults to "/".

package/docs/reference/translation-phrases.md

@@ -172,6 +172,18 @@ Remaining
 
 Remaining-time display aria label
 
+`time.elapsedSuffix`
+
+`{duration} elapsed`
+
+Elapsed time in a toggleable display aria label
+
+`time.durationSuffix`
+
+`{duration} duration`
+
+Duration in a toggleable display aria label
+
 `time.remainingSuffix`
 
 `{duration} remaining`
@@ -180,22 +192,34 @@ Remaining time display
 
 `time.showElapsed`
 
-`{duration}. Show elapsed time.`
+`Show elapsed time, {duration}.`
 
 Toggleable time display aria label
 
 `time.showDuration`
 
-`{duration}. Show duration.`
+`Show duration, {duration}.`
 
 Toggleable time display aria label
 
 `time.showRemaining`
 
-`{duration}. Show remaining time.`
+`Show remaining time, {duration}.`
 
 Toggleable time display aria label
 
+`time.toggleElapsed`
+
+`Toggle between elapsed and remaining time.`
+
+Elapsed-time toggle aria description
+
+`time.toggleDuration`
+
+`Toggle between duration and remaining time.`
+
+Duration toggle aria description
+
 `time.position`
 
 `{current} of {duration}`

package/docs/reference/use-container-attach.md

@@ -2,7 +2,7 @@
 
 Hook to register a custom container element with the player context
 
-`useContainerAttach` returns a setter function for registering a DOM element as the player’s container. The built-in `Player.Container` uses this internally; you only need it when building a custom container element.
+`useContainerAttach` returns a setter function for registering a DOM element as the player’s container. The built-in `Container` uses this internally; you only need it when building a custom container element.
 
 CustomContainer.tsx
 
@@ -17,13 +17,13 @@ function CustomContainer({ children }: { children: React.ReactNode }) {
 
 ## Who needs this
 
-You only need `useContainerAttach` if you’re replacing the built-in `Player.Container` with a custom element. For example, if you’re building a container with custom fullscreen behavior or a non-standard layout boundary.
+You only need `useContainerAttach` if you’re replacing the built-in `Container` with a custom element. For example, if you’re building a container with custom fullscreen behavior or a non-standard layout boundary.
 
-For standard player layouts, use the built-in `Player.Container`.
+For standard player layouts, use the built-in `Container`.
 
-## Safe outside Provider
+## Safe outside Player
 
-Returns `undefined` when called outside a Player `Provider`. Passing `undefined` to `ref` is harmless in React. Check the return value if your component needs to know whether it’s inside a provider.
+Returns `undefined` when called outside `Player`. Passing `undefined` to `ref` is harmless in React. Check the return value if your component needs to know whether it’s inside a player.
 
 ## API Reference
 

package/docs/reference/use-locale.md

@@ -121,4 +121,4 @@ Details
 
 Type
 
-`string & object | 'ar' | 'az' | 'bs' | 'bg' | 'bn' | 'ca' | 'cs' | 'cy' | 'da' | 'de' | 'el' | 'es' | 'et' | 'eu' | 'fa' | 'fi' | 'fr' | 'gd' | 'gl' | 'he' | 'hi' | 'hr' | 'hu' | 'it' | 'ja' | 'ko' | 'lv' | 'mr' | 'nb' | 'nl' | 'nn' | 'ne' | 'oc' | 'pl' | 'pt-BR' | 'pt-PT' | 'ro' | 'ru' | 'sk' | 'sl' | 'sr' | 'sv' | 'te' | 'th' | 'tr' | 'uk' | 'vi' | 'zh-CN' | 'zh-TW'`
+`string & object | 'ar' | 'az' | 'bs' | 'bg' | 'bn' | 'ca' | 'cs' | 'cy' | 'da' | 'de' | 'el' | 'es' | 'et' | 'eu' | 'fa' | 'fi' | 'fr' | 'gd' | 'gl' | 'he' | 'hi' | 'hr' | 'hu' | 'id' | 'it' | 'ja' | 'ko' | 'lt' | 'lv' | 'mr' | 'nb' | 'nl' | 'nn' | 'ne' | 'oc' | 'pl' | 'pt-BR' | 'pt-PT' | 'ro' | 'ru' | 'sk' | 'sl' | 'sr' | 'sv' | 'te' | 'th' | 'tr' | 'uk' | 'vi' | 'zh-CN' | 'zh-TW'`

package/docs/reference/use-media-attach.md

@@ -25,9 +25,9 @@ You only need `useMediaAttach` if you’re replacing the built-in `<Video>` or `
 
 For standard `<video>` and `<audio>` playback, use the built-in components.
 
-## Safe outside Provider
+## Safe outside Player
 
-Returns `undefined` when called outside a Player `Provider`. Check the return value before using it – this avoids crashes in components that may render outside the player tree.
+Returns `undefined` when called outside `Player`. Check the return value before using it – this avoids crashes in components that may render outside the player tree.
 
 ## API Reference
 

package/docs/reference/use-media.md

@@ -1,8 +1,14 @@
-# Player.useMedia
+# useMedia
 
-Hook to access the media object from within a Player.Provider
+Hook to access the media object from within a Player
 
-`Player.useMedia` (from [`createPlayer`](./create-player.md)) returns the current `Media` object (or `null` if no media has been registered yet). `Media` is a runtime-agnostic playback interface — any instance that conforms to it, including an `HTMLVideoElement`, can be the media. It exposes capabilities like `play()` and event subscription rather than assuming a native element. It must be called within a `Player.Provider`. The media object becomes available after a `<Video>` or `<Audio>` component mounts inside the provider tree. To attach a custom media element instead of the built-in components, see [`useMediaAttach`](./use-media-attach.md).
+The `useMedia` hook returned by [`createPlayer`](./create-player.md) returns the current `Media` object (or `null` if no media has been registered yet). `Media` is a runtime-agnostic playback interface — any instance that conforms to it, including an `HTMLVideoElement`, can be the media. It exposes capabilities like `play()` and event subscription rather than assuming a native element. It must be called within the matching `Player`. The media object becomes available after a `<Video>` or `<Audio>` component mounts inside the player tree. To attach a custom media element instead of the built-in components, see [`useMediaAttach`](./use-media-attach.md).
+
+tsx
+
+```
+const { Player, useMedia } = createPlayer({ features: videoFeatures });
+```
 
 ## Examples
 
@@ -13,15 +19,15 @@ App.tsx
 App.css
 
 ```
-import { createPlayer, isMediaSourceCapable, isMediaVideoDimensionsCapable } from '@videojs/react';
+import { Container, createPlayer, isMediaSourceCapable, isMediaVideoDimensionsCapable } from '@videojs/react';
 import { Video, videoFeatures } from '@videojs/react/video';
 
-const Player = createPlayer({
+const { Player, useMedia } = createPlayer({
   features: videoFeatures,
 });
 
 function MediaInfo() {
-  const media = Player.useMedia();
+  const media = useMedia();
 
   if (!media) return null;
 
@@ -51,12 +57,12 @@ function MediaInfo() {
 
 export default function BasicUsage() {
   return (
-    <Player.Provider>
-      <Player.Container className="media-container">
+    <Player>
+      <Container className="media-container">
         <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
         <MediaInfo />
-      </Player.Container>
-    </Player.Provider>
+      </Container>
+    </Player>
   );
 }
 ```