@videojs/react 10.0.0-beta.25 → 10.0.0-beta.27

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,15 +71,27 @@ 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 automatic `aria-label` of “Seek”. Override with the `label` prop. Keyboard controls:
+Renders with `role="slider"` and an automatic `aria-label` that resolves to “Seek” from the active locale. Override with the `label` prop. Keyboard controls:
 
 *   Arrow Left / Arrow Right: step by `step` increment
 *   Page Up / Page Down: step by `largeStep` increment
 *   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,22 +103,16 @@ 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">
-        <Video
-          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
-          autoPlay
-          muted
-          playsInline
-          loop
-        />
+    <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">
             <TimeSlider.Buffer className="media-slider-buffer" />
@@ -84,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>
   );
 }
 ```
@@ -190,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
 
 ### 
@@ -232,9 +436,9 @@ Whether the slider is non-interactive.
 
 `label`
 
-`string | function`
+`Text | string | Text) | function`
 
-`'Seek'`
+`''`
 
 ▸
 
@@ -244,7 +448,7 @@ Custom label for the slider.
 
 Type
 
-`string | ((state: SliderState) => string)`
+`Text | string | ((state: SliderState) => string | Text)`
 
 `largeStep`
 
@@ -512,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,25 +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">
-        <Video
-          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
-          autoPlay
-          muted
-          playsInline
-          loop
-        />
+    <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>
   );
 }
 ```
@@ -123,29 +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">
-        <Video
-          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
-          autoPlay
-          muted
-          playsInline
-          loop
-        />
+    <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>
   );
 }
 ```
@@ -185,25 +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">
-        <Video
-          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
-          autoPlay
-          muted
-          playsInline
-          loop
-        />
+    <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>
   );
 }
 ```
@@ -240,29 +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">
-        <Video
-          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
-          autoPlay
-          muted
-          playsInline
-          loop
-        />
+    <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>
   );
 }
 ```
@@ -302,25 +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">
-        <Video
-          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
-          autoPlay
-          muted
-          playsInline
-          loop
-        />
+    <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>
   );
 }
 ```
@@ -368,7 +338,7 @@ Details
 
 `label`
 
-`string | function`
+`Text | string | Text) | function`
 
 `''`
 
@@ -380,7 +350,7 @@ Custom label for accessibility.
 
 Type
 
-`string | ((state: TimeState) => string)`
+`Text | string | ((state: TimeState) => string | Text)`
 
 `negativeSign`
 
@@ -512,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 "/".