@videojs/html 10.0.0-rc.2 → 10.0.0-rc.3

package/docs/reference/{time-slider.md → components/time-slider.md}

@@ -4,17 +4,22 @@ A slider component for seeking through media playback time
 
 ## Import
 
-ts
-
-```
+```ts
 import '@videojs/html/ui/time-slider';
+import '@videojs/html/ui/slider-track';
+import '@videojs/html/ui/slider-buffer';
+import '@videojs/html/ui/slider-fill';
+import '@videojs/html/ui/slider-thumb';
+import '@videojs/html/ui/slider-preview';
+import '@videojs/html/ui/slider-thumbnail';
+import '@videojs/html/ui/slider-value';
+import '@videojs/html/ui/time-slider-chapters';
+import '@videojs/html/ui/time-slider-chapter-title';
 ```
 
 ## Anatomy
 
-html
-
-```
+```html
 <media-time-slider>
   <media-slider-track>
     <media-slider-buffer></media-slider-buffer>
@@ -28,11 +33,9 @@ html
 </media-time-slider>
 ```
 
-Add `Chapters` to divide the slider track into sections. Each cue in the default `kind="chapters"` text track marks a chapter. Without chapter cues, one section covers the full slider.
+Add `<media-time-slider-chapters>` to divide the slider track into sections. Each cue in the default `kind="chapters"` text track marks a chapter. Without chapter cues, one section covers the full slider.
 
-html
-
-```
+```html
 <media-time-slider-chapters>
   <template>
     <div>
@@ -57,11 +60,9 @@ Chapter cues are normalized into contiguous ranges. Any uncovered time becomes a
 
 ## Styling
 
-Use [CSS custom properties](#root-css-custom-properties) to style the fill, pointer, and buffer levels:
-
-css
+Use [CSS custom properties](#css-custom-properties) to style the fill, pointer, and buffer levels:
 
-```
+```css
 media-time-slider::before {
   width: var(--media-slider-fill);
 }
@@ -69,9 +70,7 @@ media-time-slider::before {
 
 Use `data-seeking` to style during active seek operations:
 
-css
-
-```
+```css
 media-time-slider[data-seeking] {
   opacity: 0.8;
 }
@@ -79,11 +78,11 @@ media-time-slider[data-seeking] {
 
 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`
+- `--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.
 
@@ -91,24 +90,20 @@ The generated fill and buffer parts also inherit the slider-level `--media-slide
 
 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
+- 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.
+`<media-time-slider-chapter-title>` 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.
 
-index.html
-
-index.css
-
-index.ts
+**index.html**
 
-```
+```html
 <video-player class="video-player">
   <media-container>
     <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
@@ -123,7 +118,10 @@ index.ts
   </media-container>
 </video-player>
 ```
-```
+
+**index.css**
+
+```css
 .video-player media-container {
   position: relative;
   display: block;
@@ -224,23 +222,27 @@ index.ts
   opacity: 1;
 }
 ```
-```
+
+**index.ts**
+
+```ts
 import '@videojs/html/video/player';
 import '@videojs/html/ui/container';
 import '@videojs/html/ui/time-slider';
+import '@videojs/html/ui/slider-track';
+import '@videojs/html/ui/slider-buffer';
+import '@videojs/html/ui/slider-fill';
+import '@videojs/html/ui/slider-thumb';
+import '@videojs/html/ui/slider-value';
 ```
 
 ### 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.
 
-index.html
-
-index.css
-
-index.ts
+**index.html**
 
-```
+```html
 <video-player class="video-player">
   <media-container>
     <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop crossorigin="anonymous">
@@ -266,7 +268,10 @@ index.ts
   </media-container>
 </video-player>
 ```
-```
+
+**index.css**
+
+```css
 .video-player media-container {
   position: relative;
   display: block;
@@ -391,617 +396,153 @@ index.ts
   display: none;
 }
 ```
-```
+
+**index.ts**
+
+```ts
 import '@videojs/html/video/player';
 import '@videojs/html/ui/container';
 import '@videojs/html/ui/time-slider';
 import '@videojs/html/ui/time-slider-chapters';
+import '@videojs/html/ui/slider-track';
+import '@videojs/html/ui/slider-buffer';
+import '@videojs/html/ui/slider-fill';
+import '@videojs/html/ui/slider-thumb';
+import '@videojs/html/ui/slider-preview';
+import '@videojs/html/ui/time-slider-chapter-title';
+import '@videojs/html/ui/slider-value';
 ```
 
 ## API Reference
 
-### 
-
-media-time-slider
+### media-time-slider
 
 #### Props
 
-Prop
-
-Type
-
-Default
-
-Details
-
-`changeThrottle`
-
-`number`
-
-`100`
-
-▸
-
-Attribute
-
-`change-throttle`
-
-Description
-
-Leading+trailing throttle (ms) for `onValueChange` during drag.
-
-`disabled`
-
-`boolean`
-
-`—`
-
-▸
-
-Attribute
-
-`disabled`
-
-Description
-
-Whether the slider is non-interactive.
-
-`label`
-
-`object`
-
-`''`
-
-▸
-
-Attribute
-
-`label`
-
-Description
-
-Custom label for the slider.
-
-Type
-
-`{ key: string; text: string } | string | ((state: SliderState) => Text | string)`
-
-`largeStep`
-
-`number`
-
-`—`
-
-▸
-
-Attribute
-
-`large-step`
-
-Description
-
-Large step increment (Page Up/Down keys).
-
-`max`
-
-`number`
-
-`—`
-
-▸
-
-Attribute
-
-`max`
-
-`min`
-
-`number`
-
-`—`
-
-▸
-
-Attribute
-
-`min`
-
-`orientation`
-
-`'horizontal' | 'vertical'`
-
-`—`
-
-▸
-
-Attribute
-
-`orientation`
-
-Description
-
-Axis of slider movement.
-
-`pauseOnDrag`
-
-`boolean`
-
-`false`
-
-▸
-
-Attribute
-
-`pause-on-drag`
-
-Description
-
-When true, pause playback while the user is dragging the thumb, resuming on release if it was playing before.
-
-`step`
-
-`number`
-
-`—`
-
-▸
-
-Attribute
-
-`step`
-
-Description
-
-Step increment for value changes (arrow keys).
-
-`thumbAlignment`
-
-`'center' | 'edge'`
-
-`—`
-
-▸
-
-Attribute
-
-`thumb-alignment`
-
-Description
-
-How the thumb aligns at the track edges. `edge` constrains the thumb within track bounds.
-
-`value`
-
-`number`
-
-`—`
-
-▸
-
-Attribute
-
-`value`
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `changeThrottle` (attribute `change-throttle`) | `number` | `100` | Leading+trailing throttle (ms) for `onValueChange` during drag. |
+| `disabled` | `boolean` | — | Whether the slider is non-interactive. |
+| `label` | `{ key: string; text: string } \| string \| ((state: SliderState) => Text \| string)` | `''` | Custom label for the slider. |
+| `largeStep` (attribute `large-step`) | `number` | — | Large step increment (Page Up/Down keys). |
+| `orientation` | `'horizontal' \| 'vertical'` | — | Axis of slider movement. |
+| `pauseOnDrag` (attribute `pause-on-drag`) | `boolean` | `false` | When true, pause playback while the user is dragging the thumb, resuming on release if it was playing before. |
+| `step` | `number` | — | Step increment for value changes (arrow keys). |
+| `thumbAlignment` (attribute `thumb-alignment`) | `'center' \| 'edge'` | — | How the thumb aligns at the track edges. `edge` constrains the thumb within track bounds. |
 
 #### State
 
 State is reflected as data attributes for CSS styling.
 
-Property
-
-Type
-
-Details
-
-`value`
-
-`number`
-
-▸
-
-Description
-
-Current slider value in the min–max range.
-
-`fillPercent`
-
-`number`
-
-▸
-
-Description
-
-Fill level as a percentage (0–100), derived from value.
-
-`pointerPercent`
-
-`number`
-
-▸
-
-Description
-
-Pointer position as a percentage of the track (0–100).
-
-`dragging`
-
-`boolean`
-
-▸
-
-Description
-
-Whether the user is actively dragging.
-
-`pointing`
-
-`boolean`
-
-▸
-
-Description
-
-Whether the pointer is over the slider.
-
-`interactive`
-
-`boolean`
-
-▸
-
-Description
-
-Whether dragging, pointing, or focus is active.
-
-`orientation`
-
-`'horizontal' | 'vertical'`
-
-▸
-
-Description
-
-Axis of slider movement.
-
-`disabled`
-
-`boolean`
-
-▸
-
-Description
-
-Whether the slider is non-interactive.
-
-`thumbAlignment`
-
-`'center' | 'edge'`
-
-▸
-
-Description
-
-How the thumb aligns at the track edges.
-
-`currentTime`
-
-`number`
-
-▸
-
-Description
-
-Current playback position in seconds.
-
-`duration`
-
-`number`
-
-▸
-
-Description
-
-Total duration in seconds (0 if unknown).
-
-`seeking`
-
-`boolean`
-
-▸
-
-Description
-
-Whether a seek operation is in progress.
-
-`bufferPercent`
-
-`number`
-
-▸
-
-Description
-
-Buffered amount as a percentage of duration (0–100).
+| Property | Type | Description |
+| --- | --- | --- |
+| `value` | `number` | Current slider value in the min–max range. |
+| `fillPercent` | `number` | Fill level as a percentage (0–100), derived from value. |
+| `pointerPercent` | `number` | Pointer position as a percentage of the track (0–100). |
+| `dragging` | `boolean` | Whether the user is actively dragging. |
+| `pointing` | `boolean` | Whether the pointer is over the slider. |
+| `interactive` | `boolean` | Whether dragging, pointing, or focus is active. |
+| `orientation` | `'horizontal' \| 'vertical'` | Axis of slider movement. |
+| `disabled` | `boolean` | Whether the slider is non-interactive. |
+| `thumbAlignment` | `'center' \| 'edge'` | How the thumb aligns at the track edges. |
+| `currentTime` | `number` | Current playback position in seconds. |
+| `duration` | `number` | Total duration in seconds (0 if unknown). |
+| `seeking` | `boolean` | Whether a seek operation is in progress. |
+| `bufferPercent` | `number` | Buffered amount as a percentage of duration (0–100). |
 
 #### Data attributes
 
-Attribute
-
-Type
-
-Details
-
-`data-seeking`
-
-▸
-
-Description
-
-Present when a seek operation is in progress.
+| Attribute | Description |
+| --- | --- |
+| `data-seeking` | Present when a seek operation is in progress. |
 
 #### CSS custom properties
 
-Variable
-
-Details
-
-`--media-slider-fill`
-
-▸
-
-Description
-
-Fill level percentage (0–100), representing current playback position.
-
-`--media-slider-pointer`
-
-▸
-
-Description
-
-Pointer position percentage (0–100), tracking the cursor along the slider.
-
-`--media-slider-buffer`
-
-▸
-
-Description
-
-Buffer level percentage (0–100), indicating how much media has been buffered.
+| Variable | Description |
+| --- | --- |
+| `--media-slider-fill` | Fill level percentage (0–100), representing current playback position. |
+| `--media-slider-pointer` | Pointer position percentage (0–100), tracking the cursor along the slider. |
+| `--media-slider-buffer` | Buffer level percentage (0–100), indicating how much media has been buffered. |
 
 #### Events
 
-Event
-
-Description
+| Event | Description |
+| --- | --- |
+| `drag-end` | Fired when a pointer drag ends. |
+| `drag-start` | Fired when a pointer drag starts. |
 
-`drag-end`
-
-Fired when a pointer drag ends.
-
-`drag-start`
-
-Fired when a pointer drag starts.
-
-### 
-
-media-time-slider-chapter-title
+### media-time-slider-chapter-title
 
 Displays the chapter title at the current pointer or keyboard position.
 
-### 
+### media-time-slider-chapters
 
-media-time-slider-chapters
+Clones a light-DOM template once per normalized chapter range.
 
-Renders normalized chapter ranges across the full slider, including one full range when chapter cues are absent.
+The required template must contain exactly one HTML root element. When no chapter cues are available, the template is cloned once for a full-duration range.
 
-### 
-
-media-slider-buffer
+### media-slider-buffer
 
 Displays the buffered range on the slider track.
 
-### 
-
-media-slider-fill
+### media-slider-fill
 
 Displays the filled portion from start to the current value.
 
-### 
-
-media-slider-preview
+### media-slider-preview
 
 Positioning container for preview content that tracks the pointer along the slider.
 
-#### Data attributes
-
-Attribute
-
-Type
-
-Details
-
-`data-dragging`
-
-▸
-
-Description
-
-Present when the user is actively dragging.
-
-`data-pointing`
-
-▸
-
-Description
-
-Present when the pointer is over the slider.
-
-`data-interactive`
-
-▸
-
-Description
-
-Present when dragging, pointing, or focus is active.
-
-`data-orientation`
-
-`'horizontal' | 'vertical'`
-
-▸
-
-Description
-
-Current axis of slider movement (`horizontal` or `vertical`).
-
-`data-disabled`
-
-▸
+#### Props
 
-Description
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `overflow` | `'clamp' \| 'visible'` | — | How the preview handles slider boundaries. `clamp` keeps it within bounds; `visible` lets it extend past them. |
 
-Present when the slider is non-interactive.
+#### Data attributes
 
-### 
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-dragging` | — | Present when the user is actively dragging. |
+| `data-pointing` | — | Present when the pointer is over the slider. |
+| `data-interactive` | — | Present when dragging, pointing, or focus is active. |
+| `data-orientation` | `'horizontal' \| 'vertical'` | Current axis of slider movement (`horizontal` or `vertical`). |
+| `data-disabled` | — | Present when the slider is non-interactive. |
 
-media-slider-thumb
+### media-slider-thumb
 
 Draggable handle for setting the slider value. Receives focus and handles keyboard interaction.
 
 #### Data attributes
 
-Attribute
-
-Type
-
-Details
-
-`data-dragging`
-
-▸
-
-Description
-
-Present when the user is actively dragging.
-
-`data-pointing`
-
-▸
-
-Description
-
-Present when the pointer is over the slider.
-
-`data-interactive`
-
-▸
-
-Description
-
-Present when dragging, pointing, or focus is active.
-
-`data-orientation`
-
-`'horizontal' | 'vertical'`
-
-▸
-
-Description
-
-Current axis of slider movement (`horizontal` or `vertical`).
-
-`data-disabled`
-
-▸
-
-Description
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-dragging` | — | Present when the user is actively dragging. |
+| `data-pointing` | — | Present when the pointer is over the slider. |
+| `data-interactive` | — | Present when dragging, pointing, or focus is active. |
+| `data-orientation` | `'horizontal' \| 'vertical'` | Current axis of slider movement (`horizontal` or `vertical`). |
+| `data-disabled` | — | Present when the slider is non-interactive. |
 
-Present when the slider is non-interactive.
-
-### 
-
-media-slider-track
+### media-slider-track
 
 Contains the slider's visual track and interactive hit zone.
 
-### 
-
-media-slider-value
+### media-slider-value
 
-Displays a formatted text representation of the slider value. Renders an `<output>` element.
+Writes the formatted current or pointer slider value into its own text content, replacing any children.
 
 #### Props
 
-Prop
-
-Type
-
-Default
-
-Details
-
-`type`
-
-`'current' | 'pointer'`
-
-`—`
-
-▸
-
-Attribute
-
-`type`
-
-Description
-
-Which slider value to display: the current position or the pointer position.
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `type` | `'current' \| 'pointer'` | — | Which slider value to display: the current position or the pointer position. |
 
 #### Data attributes
 
-Attribute
-
-Type
-
-Details
-
-`data-dragging`
-
-▸
-
-Description
-
-Present when the user is actively dragging.
-
-`data-pointing`
-
-▸
-
-Description
-
-Present when the pointer is over the slider.
-
-`data-interactive`
-
-▸
-
-Description
-
-Present when dragging, pointing, or focus is active.
-
-`data-orientation`
-
-`'horizontal' | 'vertical'`
-
-▸
-
-Description
-
-Current axis of slider movement (`horizontal` or `vertical`).
-
-`data-disabled`
-
-▸
-
-Description
-
-Present when the slider is non-interactive.
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-dragging` | — | Present when the user is actively dragging. |
+| `data-pointing` | — | Present when the pointer is over the slider. |
+| `data-interactive` | — | Present when dragging, pointing, or focus is active. |
+| `data-orientation` | `'horizontal' \| 'vertical'` | Current axis of slider movement (`horizontal` or `vertical`). |
+| `data-disabled` | — | Present when the slider is non-interactive. |