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

package/docs/reference/slider.md

@@ -0,0 +1,862 @@
+# media-slider
+
+A composable slider component with track, fill, thumb, preview, and value parts
+
+## Anatomy
+
+html
+
+```
+<media-slider>
+  <media-slider-track>
+    <media-slider-fill></media-slider-fill>
+  </media-slider-track>
+  <media-slider-thumb></media-slider-thumb>
+  <media-slider-preview>
+    <media-slider-value type="pointer"></media-slider-value>
+  </media-slider-preview>
+</media-slider>
+```
+
+## Behavior
+
+The base Slider provides a generic range input. It manages value, pointer tracking, and drag interactions. Domain-specific sliders like [TimeSlider](./time-slider.md) and [VolumeSlider](./volume-slider.md) extend this with media-specific bindings.
+
+The slider supports vertical orientation via the `orientation` prop (defaults to `"horizontal"`).
+
+## Styling
+
+Use [CSS custom properties](#root-css-custom-properties) to position fill, thumb, and preview elements:
+
+css
+
+```
+media-slider-fill {
+  width: var(--media-slider-fill);
+}
+
+media-slider-thumb {
+  left: var(--media-slider-fill);
+}
+```
+
+Style based on [interaction state](#root-data-attributes):
+
+css
+
+```
+media-slider[data-interactive] media-slider-track {
+  height: 6px;
+}
+media-slider[data-pointing] media-slider-preview {
+  opacity: 1;
+}
+```
+
+## Accessibility
+
+Renders with `role="slider"` and automatic ARIA attributes (`aria-valuemin`, `aria-valuemax`, `aria-valuenow`, `aria-valuetext`). Override the label with the `label` prop. Keyboard controls:
+
+*   Arrow Left / Arrow Right: step by `step` increment
+*   Page Up / Page Down: step by `largeStep` increment
+*   Home: jump to minimum
+*   End: jump to maximum
+
+## Examples
+
+### Basic
+
+A slider with track, fill, and thumb.
+
+index.html
+
+index.css
+
+index.ts
+
+```
+<div class="demo">
+    <media-slider class="media-slider" value="50">
+        <media-slider-track class="media-slider-track">
+            <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>
+</div>
+```
+```
+.demo {
+  display: flex;
+  align-items: center;
+  padding: 24px;
+  background: #1a1a1a;
+}
+
+.media-slider {
+  position: relative;
+  display: flex;
+  align-items: center;
+  width: 100%;
+  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-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-slider[data-interactive] .media-slider-thumb {
+  transform: translateX(-50%) scale(1);
+}
+
+.media-slider[data-dragging] .media-slider-thumb {
+  transform: translateX(-50%) scale(1.1);
+}
+```
+```
+import '@videojs/html/ui/slider';
+```
+
+### With Preview
+
+A slider with a pointer-tracking preview that displays the value at the current pointer position.
+
+index.html
+
+index.css
+
+index.ts
+
+```
+<div class="demo">
+    <media-slider class="media-slider" value="50">
+        <media-slider-track class="media-slider-track">
+            <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-preview class="preview">
+            <media-slider-value type="pointer" class="media-slider-value"></media-slider-value>
+        </media-slider-preview>
+    </media-slider>
+</div>
+```
+```
+.demo {
+  display: flex;
+  align-items: center;
+  padding: 40px 24px;
+  background: #1a1a1a;
+}
+
+.media-slider {
+  position: relative;
+  display: flex;
+  align-items: center;
+  width: 100%;
+  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-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-slider[data-interactive] .media-slider-thumb {
+  transform: translateX(-50%) scale(1);
+}
+
+.media-slider[data-dragging] .media-slider-thumb {
+  transform: translateX(-50%) scale(1.1);
+}
+
+.preview {
+  position: absolute;
+  bottom: 100%;
+  margin-bottom: 6px;
+  pointer-events: none;
+  opacity: 0;
+  transition: opacity 150ms ease;
+}
+
+.media-slider[data-pointing] .preview {
+  opacity: 1;
+}
+
+.media-slider-value {
+  padding: 2px 6px;
+  font-size: 12px;
+  color: white;
+  white-space: nowrap;
+  background: rgba(0, 0, 0, 0.8);
+  border-radius: 4px;
+}
+```
+```
+import '@videojs/html/ui/slider';
+```
+
+## API Reference
+
+### 
+
+media-slider
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`disabled`
+
+`boolean`
+
+`false`
+
+▸
+
+Attribute
+
+`disabled`
+
+Description
+
+Whether the slider is non-interactive.
+
+`label`
+
+`string | function`
+
+`''`
+
+▸
+
+Attribute
+
+`label`
+
+Description
+
+Custom label for the slider.
+
+Type
+
+`string | ((state: SliderState) => string)`
+
+`largeStep`
+
+`number`
+
+`10`
+
+▸
+
+Attribute
+
+`large-step`
+
+Description
+
+Large step increment (Page Up/Down keys).
+
+`max`
+
+`number`
+
+`100`
+
+▸
+
+Attribute
+
+`max`
+
+Description
+
+Maximum value of the slider range.
+
+`min`
+
+`number`
+
+`0`
+
+▸
+
+Attribute
+
+`min`
+
+Description
+
+Minimum value of the slider range.
+
+`orientation`
+
+`'horizontal' | 'vertical'`
+
+`'horizontal'`
+
+▸
+
+Attribute
+
+`orientation`
+
+Description
+
+Axis of slider movement.
+
+`step`
+
+`number`
+
+`1`
+
+▸
+
+Attribute
+
+`step`
+
+Description
+
+Step increment for value changes (arrow keys).
+
+`thumbAlignment`
+
+`'center' | 'edge'`
+
+`'center'`
+
+▸
+
+Attribute
+
+`thumb-alignment`
+
+Description
+
+How the thumb aligns at the track edges. `edge` constrains the thumb within track bounds.
+
+`value`
+
+`number`
+
+`0`
+
+▸
+
+Attribute
+
+`value`
+
+Description
+
+Current slider value.
+
+#### 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 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.
+
+#### 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.
+
+#### CSS custom properties
+
+Variable
+
+Details
+
+`--media-slider-fill`
+
+▸
+
+Description
+
+Fill level percentage (0–100).
+
+`--media-slider-pointer`
+
+▸
+
+Description
+
+Pointer position percentage (0–100).
+
+`--media-slider-buffer`
+
+▸
+
+Description
+
+Buffer level percentage (0–100).
+
+### 
+
+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-thumbnail
+
+### 
+
+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.