@videojs/react 10.0.0-beta.3 → 10.0.0-beta.31

package/docs/reference/volume-slider.md

@@ -0,0 +1,712 @@
+# VolumeSlider
+
+A slider component for controlling media playback volume
+
+## Anatomy
+
+tsx
+
+```
+<VolumeSlider.Root />
+```
+
+## Behavior
+
+Controls the media volume level. The slider maps its 0–100 internal range to the media’s 0–1 volume scale. When the media is muted, the fill level drops to 0 regardless of the stored volume value. When `volumeAvailability` is not `"available"`, the HTML custom element receives native `hidden`, `data-hidden`, and disabled ARIA semantics; the React component returns `null`. This is independent of `mutedAvailability`, which controls whether the mute button is shown.
+
+## Styling
+
+Use [CSS custom properties](#root-css-custom-properties) to style the fill and pointer levels:
+
+React renders a `<div>` element. Add a `className` to style it:
+
+css
+
+```
+.volume-slider::before {
+  width: calc(var(--media-slider-fill) * 1%);
+}
+```
+
+## Accessibility
+
+Renders with `role="slider"` and an automatic `aria-label` that resolves to “Volume” 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: set volume to 0
+*   End: set volume to max
+
+Scroll wheel support:
+
+*   **Mouse wheel / trackpad scroll**: adjusts volume by `wheelStep` increment (default `5`)
+
+## Examples
+
+Nest sub-components for full control over the slider’s DOM structure. This example includes a track, fill bar, draggable thumb, and a tooltip that shows the volume percentage on hover.
+
+App.tsx
+
+App.css
+
+```
+import { Container, createPlayer, MuteButton, VolumeSlider } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+export default function WithParts() {
+  return (
+    <Player>
+      <Container className="media-container">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
+        <MuteButton
+          className="media-mute-button"
+          render={(props, state) => <button {...props}>{state.muted ? 'Unmute' : 'Mute'}</button>}
+        />
+        <VolumeSlider.Root className="media-volume-slider">
+          <VolumeSlider.Track className="media-slider-track">
+            <VolumeSlider.Fill className="media-slider-fill" />
+          </VolumeSlider.Track>
+          <VolumeSlider.Thumb className="media-slider-thumb" />
+          <VolumeSlider.Value type="pointer" className="media-slider-value" />
+        </VolumeSlider.Root>
+      </Container>
+    </Player>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.media-mute-button {
+  position: absolute;
+  bottom: 10px;
+  left: 10px;
+  padding-block: 8px;
+  padding-inline: 20px;
+  color: black;
+  cursor: pointer;
+  background: rgba(255, 255, 255, 0.7);
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+
+.media-volume-slider {
+  position: absolute;
+  right: 10px;
+  bottom: 10px;
+  display: flex;
+  align-items: center;
+  width: 100px;
+  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;
+  backdrop-filter: blur(10px);
+  transition: height 150ms ease;
+}
+
+.media-volume-slider[data-interactive] .media-slider-track {
+  height: 6px;
+}
+
+.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-volume-slider[data-interactive] .media-slider-thumb {
+  transform: translateX(-50%) scale(1);
+}
+
+.media-volume-slider[data-dragging] .media-slider-thumb {
+  transform: translateX(-50%) scale(1.1);
+}
+
+.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-volume-slider[data-pointing] .media-slider-value {
+  opacity: 1;
+}
+```
+
+## API Reference
+
+### 
+
+Root
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`disabled`
+
+`boolean`
+
+`—`
+
+▸
+
+Description
+
+Whether the slider is non-interactive.
+
+`label`
+
+`Text | string | Text) | function`
+
+`''`
+
+▸
+
+Description
+
+Custom label for the slider.
+
+Type
+
+`Text | string | ((state: SliderState) => string | Text)`
+
+`largeStep`
+
+`number`
+
+`—`
+
+▸
+
+Description
+
+Large step increment (Page Up/Down keys).
+
+`max`
+
+`number`
+
+`—`
+
+`min`
+
+`number`
+
+`—`
+
+`orientation`
+
+`'horizontal' | 'vertical'`
+
+`—`
+
+▸
+
+Description
+
+Axis of slider movement.
+
+`step`
+
+`number`
+
+`—`
+
+▸
+
+Description
+
+Step increment for value changes (arrow keys).
+
+`thumbAlignment`
+
+`'center' | 'edge'`
+
+`—`
+
+▸
+
+Description
+
+How the thumb aligns at the track edges. `edge` constrains the thumb within track bounds.
+
+`value`
+
+`number`
+
+`—`
+
+`wheelStep`
+
+`number`
+
+`5`
+
+▸
+
+Description
+
+Step increment for wheel scrolling.
+
+#### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+Property
+
+Type
+
+Details
+
+`availability`
+
+`'available' | 'unavailable' | 'unsupp...`
+
+▸
+
+Type
+
+`'available' | 'unavailable' | 'unsupported'`
+
+`hidden`
+
+`boolean`
+
+`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.
+
+`muted`
+
+`boolean`
+
+▸
+
+Description
+
+Whether audio is muted.
+
+`volume`
+
+`number`
+
+▸
+
+Description
+
+Volume level from 0 (silent) to 1 (max).
+
+#### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-availability`
+
+`'available' | 'unavailable' | 'unsupp...`
+
+▸
+
+Type
+
+`'available' | 'unavailable' | 'unsupported'`
+
+`data-hidden`
+
+#### CSS custom properties
+
+Variable
+
+Details
+
+`--media-slider-fill`
+
+▸
+
+Description
+
+Fill level percentage (0–100), representing the current volume level.
+
+`--media-slider-pointer`
+
+▸
+
+Description
+
+Pointer position percentage (0–100), tracking the cursor along the slider.
+
+### 
+
+Fill
+
+Displays the filled portion from start to the current value.
+
+### 
+
+Preview
+
+Positioning container for preview content that tracks the pointer along the slider.
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`overflow`
+
+`SliderPreviewOverflow`
+
+`—`
+
+▸
+
+Description
+
+Whether the preview is clamped to the slider bounds.
+
+#### 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.
+
+### 
+
+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.
+
+### 
+
+Track
+
+Contains the slider's visual track and interactive hit zone.
+
+### 
+
+Value
+
+Displays a formatted text representation of the slider value. Renders an `<output>` element.
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`format`
+
+`((value: number) => string)`
+
+`—`
+
+▸
+
+Description
+
+Custom formatter for the displayed value. Overrides the root's `formatValue`.
+
+`type`
+
+`"current" | "pointer"`
+
+`—`
+
+▸
+
+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.