@videojs/html 10.0.0-beta.22 → 10.0.0-beta.24

package/docs/reference/time-slider.md

@@ -0,0 +1,794 @@
+# media-time-slider
+
+A slider component for seeking through media playback time
+
+## Anatomy
+
+html
+
+```
+<media-time-slider></media-time-slider>
+```
+
+## 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.
+
+## Styling
+
+Use [CSS custom properties](#root-css-custom-properties) to style the fill, pointer, and buffer levels:
+
+css
+
+```
+media-time-slider::before {
+  width: var(--media-slider-fill);
+}
+```
+
+Use `data-seeking` to style during active seek operations:
+
+css
+
+```
+media-time-slider[data-seeking] {
+  opacity: 0.8;
+}
+```
+
+## Accessibility
+
+Renders with `role="slider"` and automatic `aria-label` of “Seek”. 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
+
+## 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
+
+```
+<video-player class="video-player">
+    <media-container>
+        <video
+            src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
+            autoplay
+            muted
+            playsinline
+            loop
+        ></video>
+        <media-time-slider class="media-time-slider">
+            <media-slider-track class="media-slider-track">
+                <media-slider-buffer class="media-slider-buffer"></media-slider-buffer>
+                <media-slider-fill class="media-slider-fill"></media-slider-fill>
+            </media-slider-track>
+            <media-slider-thumb class="media-slider-thumb"></media-slider-thumb>
+            <media-slider-value type="pointer" class="media-slider-value"></media-slider-value>
+        </media-time-slider>
+    </media-container>
+</video-player>
+```
+```
+.video-player,
+.video-player media-container {
+  position: relative;
+  display: block;
+}
+
+.video-player video {
+  width: 100%;
+}
+
+.media-time-slider {
+  position: absolute;
+  right: 0;
+  bottom: 0;
+  left: 0;
+  display: flex;
+  align-items: center;
+  height: 20px;
+  cursor: pointer;
+}
+
+.media-slider-track {
+  position: absolute;
+  right: 0;
+  left: 0;
+  height: 4px;
+  background: rgba(255, 255, 255, 0.3);
+  border-radius: 9999px;
+  transition: height 150ms ease;
+}
+
+.media-time-slider[data-interactive] .media-slider-track {
+  height: 6px;
+}
+
+.media-slider-buffer {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: var(--media-slider-buffer);
+  height: 100%;
+  background: rgba(255, 255, 255, 0.4);
+  border-radius: 9999px;
+}
+
+.media-slider-fill {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: var(--media-slider-fill);
+  height: 100%;
+  background: white;
+  border-radius: 9999px;
+}
+
+.media-slider-thumb {
+  position: absolute;
+  left: var(--media-slider-fill);
+  width: 14px;
+  height: 14px;
+  background: white;
+  border-radius: 50%;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.4);
+  transform: translateX(-50%) scale(0);
+  transition: transform 150ms ease;
+}
+
+.media-time-slider[data-interactive] .media-slider-thumb {
+  transform: translateX(-50%) scale(1);
+}
+
+.media-time-slider[data-dragging] .media-slider-thumb {
+  left: var(--media-slider-pointer);
+  transform: translateX(-50%) scale(1.1);
+}
+
+.media-time-slider[data-dragging] .media-slider-fill {
+  width: var(--media-slider-pointer);
+}
+
+.media-slider-value {
+  position: absolute;
+  bottom: 100%;
+  left: var(--media-slider-pointer);
+  padding: 2px 6px;
+  margin-bottom: 6px;
+  font-size: 12px;
+  color: white;
+  white-space: nowrap;
+  pointer-events: none;
+  background: rgba(0, 0, 0, 0.8);
+  border-radius: 4px;
+  opacity: 0;
+  transform: translateX(-50%);
+  transition: opacity 150ms ease;
+}
+
+.media-time-slider[data-pointing] .media-slider-value {
+  opacity: 1;
+}
+```
+```
+import '@videojs/html/video/player';
+import '@videojs/html/ui/time-slider';
+```
+
+## API Reference
+
+### 
+
+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`
+
+`string | function`
+
+`'Seek'`
+
+▸
+
+Attribute
+
+`label`
+
+Description
+
+Custom label for the slider.
+
+Type
+
+`string | ((state: SliderState) => 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.
+
+`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`
+
+#### State
+
+State is reflected as data attributes for CSS styling.
+
+Property
+
+Type
+
+Details
+
+`bufferPercent`
+
+`number`
+
+▸
+
+Description
+
+Buffered amount as a percentage of duration (0–100).
+
+`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 or pointing 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.
+
+`seeking`
+
+`boolean`
+
+▸
+
+Description
+
+Whether a seek operation is in progress.
+
+`duration`
+
+`number`
+
+▸
+
+Description
+
+Total duration in seconds (0 if unknown).
+
+#### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-seeking`
+
+▸
+
+Description
+
+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.
+
+### 
+
+media-slider-buffer
+
+Displays the buffered range on the slider track.
+
+### 
+
+media-slider-fill
+
+Displays the filled portion from start to the current value.
+
+### 
+
+media-slider-preview
+
+Positioning container for preview content that tracks the pointer along the slider.
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`overflow`
+
+`SliderPreviewOverflow`
+
+`—`
+
+▸
+
+Attribute
+
+`overflow`
+
+Description
+
+How the preview handles the slider boundaries. `'clamp'` keeps the preview within bounds, `'visible'` allows it to extend beyond the edges.
+
+#### 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 or pointing 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.
+
+### 
+
+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 or pointing 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.
+
+### 
+
+media-slider-track
+
+Contains the slider's visual track and interactive hit zone.
+
+### 
+
+media-slider-value
+
+Displays a formatted text representation of the slider value. Renders an `<output>` element.
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`format`
+
+`((value: number) => string)`
+
+`—`
+
+▸
+
+Attribute
+
+`format`
+
+Description
+
+Custom formatter for the displayed value. Overrides the root's `formatValue`.
+
+`type`
+
+`"current" | "pointer"`
+
+`—`
+
+▸
+
+Attribute
+
+`type`
+
+Description
+
+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 or pointing 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.