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

package/docs/reference/controls.md

@@ -0,0 +1,248 @@
+# media-controls
+
+Container component for composing and auto-hiding video player controls on user interaction
+
+## Anatomy
+
+Import the component and assemble its parts:
+
+html
+
+```
+<media-controls>
+  <media-controls-group></media-controls-group>
+</media-controls>
+```
+
+## Behavior
+
+If the user is active, or if the video is paused, this component will show controls. Otherwise, it will hide them after a short delay.
+
+User activity is tracked via pointer movement, keyboard input, and focus events on the player container. On touch devices, a quick tap toggles visibility. `mouseleave` immediately sets the user as inactive.
+
+## Styling
+
+By default, controls have the following styles:
+
+css
+
+```
+/* Click-through: clicks pass through controls to video beneath */
+media-controls {
+  pointer-events: none;
+}
+
+media-controls-group {
+  pointer-events: auto;
+}
+
+/* Fade transition */
+media-controls {
+  transition: opacity 0.25s;
+}
+
+media-controls:not([data-visible]) {
+  opacity: 0;
+}
+```
+
+## Accessibility
+
+No ARIA role is applied to `<media-controls>` — it is a layout wrapper, not a landmark. `<media-controls-group>` automatically receives `role="group"` when an `aria-label` or `aria-labelledby` attribute is provided; otherwise no role is assigned.
+
+## Examples
+
+### Basic Usage
+
+Play Pause
+
+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-controls class="media-controls">
+            <media-controls-group class="controls-group" aria-label="Playback controls">
+                <media-play-button class="button media-play-button">
+                    <span class="paused">Play</span>
+                    <span class="playing">Pause</span>
+                </media-play-button>
+                <media-time class="time" type="current"></media-time>
+            </media-controls-group>
+        </media-controls>
+    </media-container>
+</video-player>
+```
+```
+.video-player {
+  position: relative;
+  display: block;
+}
+
+.video-player video {
+  width: 100%;
+}
+
+.media-controls {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: flex-end;
+  padding: 12px;
+  pointer-events: none;
+  background: linear-gradient(to top, rgba(0, 0, 0, 0.45), transparent 45%);
+  transition: opacity 0.25s;
+}
+
+.media-controls:not([data-visible]) {
+  opacity: 0;
+}
+
+.controls-group {
+  pointer-events: auto;
+}
+
+.time {
+  display: inline-flex;
+  gap: 4px;
+  align-items: center;
+  padding-block: 8px;
+  padding-inline: 16px;
+  font-size: 14px;
+  color: black;
+  background: rgba(255, 255, 255, 0.75);
+  border: 1px solid rgba(255, 255, 255, 0.25);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+
+.controls-group {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+}
+
+.button {
+  padding-block: 8px;
+  padding-inline: 16px;
+  font-size: 14px;
+  color: black;
+  cursor: pointer;
+  background: rgba(255, 255, 255, 0.75);
+  border: 1px solid rgba(255, 255, 255, 0.25);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+
+.button .paused,
+.button .playing {
+  display: none;
+}
+
+.media-play-button[data-paused] .paused {
+  display: inline;
+}
+
+.media-play-button:not([data-paused]) .playing {
+  display: inline;
+}
+```
+```
+import '@videojs/html/video/player';
+import '@videojs/html/ui/controls';
+import '@videojs/html/ui/play-button';
+import '@videojs/html/ui/time';
+```
+
+## API Reference
+
+### 
+
+media-controls
+
+Root container for player controls state and rendered control content.
+
+#### State
+
+State is reflected as data attributes for CSS styling.
+
+Property
+
+Type
+
+Details
+
+`visible`
+
+`boolean`
+
+`userActive`
+
+`boolean`
+
+#### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-visible`
+
+▸
+
+Description
+
+Present when controls are visible.
+
+`data-user-active`
+
+▸
+
+Description
+
+Present when the user has recently interacted.
+
+### 
+
+media-controls-group
+
+Layout group for related controls; sets `role="group"` when labeled.
+
+#### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-visible`
+
+▸
+
+Description
+
+Present when controls are visible.
+
+`data-user-active`
+
+▸
+
+Description
+
+Present when the user has recently interacted.

package/docs/reference/create-selector.md

@@ -0,0 +1,59 @@
+# createSelector
+
+Create a type-safe selector for a store slice's state
+
+`createSelector` creates a type-safe selector function for a given slice. The returned selector extracts that slice’s state from the full store state, or returns `undefined` if the slice is not configured.
+
+The built-in selectors ([`selectPlayback`](./feature-playback.md), [`selectBuffer`](./feature-buffer.md), etc.) are all created with `createSelector`. Use it to create selectors for custom slices.
+
+my-custom-selector.ts
+
+```
+import { createSelector } from '@videojs/store';
+import { myCustomSlice } from './my-custom-slice';
+
+const selectCustom = createSelector(myCustomSlice);
+
+// Use with usePlayer (React) or PlayerController (HTML)
+const state = selectCustom(store.state);
+```
+
+Pass selectors to [`PlayerController`](./player-controller.md) or [`StoreController`](./store-controller.md) for reactive subscriptions.
+
+## API Reference
+
+### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`slice*`
+
+`S`
+
+`—`
+
+▸
+
+Description
+
+The slice to create a selector for.
+
+### Return Value
+
+Type
+
+Details
+
+`Selector<object, InferSliceState<S> |...`
+
+▸
+
+Type
+
+`Selector<object, InferSliceState<S> | undefined>`

package/docs/reference/feature-buffer.md

@@ -0,0 +1,52 @@
+# Buffer
+
+Buffered and seekable time range state for the player store
+
+Read-only — tracks buffered and seekable time ranges.
+
+## API Reference
+
+### State
+
+Property
+
+Type
+
+Details
+
+`buffered`
+
+`[number, number][]`
+
+▸
+
+Description
+
+Buffered time ranges as \[start, end\] tuples.
+
+`seekable`
+
+`[number, number][]`
+
+▸
+
+Description
+
+Seekable time ranges as \[start, end\] tuples.
+
+### Selector
+
+Pass `selectBuffer` to [`PlayerController`](./player-controller.md) to subscribe to buffer state. Returns `undefined` if the buffer feature is not configured.
+
+buffer-bar.ts
+
+```
+import { createPlayer, MediaElement, selectBuffer } from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+
+const { PlayerController, context } = createPlayer({ features: videoFeatures });
+
+class BufferBar extends MediaElement {
+  readonly #buffer = new PlayerController(this, context, selectBuffer);
+}
+```

package/docs/reference/feature-controls.md

@@ -0,0 +1,70 @@
+# Controls
+
+User activity and controls visibility state for the player store
+
+Read-only — tracks user activity for showing and hiding controls.
+
+## API Reference
+
+### State
+
+Property
+
+Type
+
+Details
+
+`userActive`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the user has recently interacted with the player.
+
+`controlsVisible`
+
+`boolean`
+
+▸
+
+Description
+
+Whether controls should be visible (userActive || paused).
+
+### Actions
+
+Action
+
+Type
+
+Details
+
+`toggleControls`
+
+`() => boolean`
+
+▸
+
+Description
+
+Toggle controls visibility. Returns the new `controlsVisible` value.
+
+### Selector
+
+Pass `selectControls` to [`PlayerController`](./player-controller.md) to subscribe to controls state. Returns `undefined` if the controls feature is not configured.
+
+controls-overlay.ts
+
+```
+import { createPlayer, MediaElement, selectControls } from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+
+const { PlayerController, context } = createPlayer({ features: videoFeatures });
+
+class ControlsOverlay extends MediaElement {
+  readonly #controls = new PlayerController(this, context, selectControls);
+}
+```

package/docs/reference/feature-error.md

@@ -0,0 +1,60 @@
+# Error
+
+Media error state and actions for the player store
+
+Tracks media errors.
+
+## API Reference
+
+### State
+
+Property
+
+Type
+
+Details
+
+`error`
+
+`null | MediaError`
+
+▸
+
+Description
+
+The current media error, or null if none.
+
+### Actions
+
+Action
+
+Type
+
+Details
+
+`dismissError`
+
+`() => void`
+
+▸
+
+Description
+
+Dismiss the current error by clearing it.
+
+### Selector
+
+Pass `selectError` to [`PlayerController`](./player-controller.md) to subscribe to error state. Returns `undefined` if the error feature is not configured.
+
+error-display.ts
+
+```
+import { createPlayer, MediaElement, selectError } from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+
+const { PlayerController, context } = createPlayer({ features: videoFeatures });
+
+class ErrorDisplay extends MediaElement {
+  readonly #error = new PlayerController(this, context, selectError);
+}
+```

package/docs/reference/feature-fullscreen.md

@@ -0,0 +1,90 @@
+# Fullscreen
+
+Fullscreen state and actions for the player store
+
+Controls fullscreen mode. Tries the container element first, falls back to the media element.
+
+## API Reference
+
+### State
+
+Property
+
+Type
+
+Details
+
+`fullscreen`
+
+`boolean`
+
+▸
+
+Description
+
+Whether fullscreen mode is currently active.
+
+`fullscreenAvailability`
+
+`'available' | 'unavailable' | 'unsupported'`
+
+▸
+
+Description
+
+Whether fullscreen can be requested on this platform.
+
+### Actions
+
+Action
+
+Type
+
+Details
+
+`requestFullscreen`
+
+`() => Promise<void>`
+
+▸
+
+Description
+
+Enter fullscreen mode. Tries container first, falls back to media element.
+
+`exitFullscreen`
+
+`() => Promise<void>`
+
+▸
+
+Description
+
+Exit fullscreen mode.
+
+`toggleFullscreen`
+
+`() => Promise<void>`
+
+▸
+
+Description
+
+Toggle fullscreen mode.
+
+### Selector
+
+Pass `selectFullscreen` to [`PlayerController`](./player-controller.md) to subscribe to fullscreen state. Returns `undefined` if the fullscreen feature is not configured.
+
+fullscreen-button.ts
+
+```
+import { createPlayer, MediaElement, selectFullscreen } from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+
+const { PlayerController, context } = createPlayer({ features: videoFeatures });
+
+class FullscreenButton extends MediaElement {
+  readonly #fullscreen = new PlayerController(this, context, selectFullscreen);
+}
+```

package/docs/reference/feature-live.md

@@ -0,0 +1,60 @@
+# Live
+
+Live edge state for the player store
+
+Exposes live-edge state so components can render a “jump to live” button, detect DVR vs. standard live, or hide live-only UI for on-demand sources.
+
+`liveEdgeStart` is the presentation time at which the Live Edge Window begins — playback is “at the live edge” when `currentTime >= liveEdgeStart`. `targetLiveWindow` reports the seekable range size: `0` for standard latency live, `Infinity` for DVR, `NaN` for on-demand or unknown. Both values are `NaN` when the media doesn’t expose live-edge state (anything other than an HLS source today).
+
+The live feature is included by the `liveVideoFeatures` and `liveAudioFeatures` presets; apps that build a custom preset can compose it in directly.
+
+## API Reference
+
+### State
+
+Property
+
+Type
+
+Details
+
+`liveEdgeStart`
+
+`number`
+
+▸
+
+Description
+
+Presentation time marking the start of the Live Edge Window.
+
+Playing at the live edge when `currentTime >= liveEdgeStart`. `NaN` when the stream isn't live or the value is unknown.
+
+`targetLiveWindow`
+
+`number`
+
+▸
+
+Description
+
+Offset representing the seekable range size for live content.
+
+`0` for standard latency live, `Infinity` for DVR, `NaN` for on-demand or unknown.
+
+### Selector
+
+Pass `selectLive` to [`PlayerController`](./player-controller.md) to subscribe to live state. Returns `undefined` if the live feature is not configured.
+
+live-edge-button.ts
+
+```
+import { createPlayer, MediaElement, selectLive } from '@videojs/html';
+import { liveVideoFeatures } from '@videojs/html/live-video';
+
+const { PlayerController, context } = createPlayer({ features: liveVideoFeatures });
+
+class LiveEdgeButton extends MediaElement {
+  readonly #live = new PlayerController(this, context, selectLive);
+}
+```

package/docs/reference/feature-pip.md

@@ -0,0 +1,90 @@
+# Picture-in-picture
+
+Picture-in-picture state and actions for the player store
+
+Controls picture-in-picture mode.
+
+## API Reference
+
+### State
+
+Property
+
+Type
+
+Details
+
+`pip`
+
+`boolean`
+
+▸
+
+Description
+
+Whether picture-in-picture mode is currently active.
+
+`pipAvailability`
+
+`'available' | 'unavailable' | 'unsupported'`
+
+▸
+
+Description
+
+Whether picture-in-picture can be requested on this platform.
+
+### Actions
+
+Action
+
+Type
+
+Details
+
+`requestPictureInPicture`
+
+`() => Promise<void>`
+
+▸
+
+Description
+
+Enter picture-in-picture mode.
+
+`exitPictureInPicture`
+
+`() => Promise<void>`
+
+▸
+
+Description
+
+Exit picture-in-picture mode.
+
+`togglePictureInPicture`
+
+`() => Promise<void>`
+
+▸
+
+Description
+
+Toggle picture-in-picture mode.
+
+### Selector
+
+Pass `selectPiP` to [`PlayerController`](./player-controller.md) to subscribe to picture-in-picture state. Returns `undefined` if the PiP feature is not configured.
+
+pip-button.ts
+
+```
+import { createPlayer, MediaElement, selectPiP } from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+
+const { PlayerController, context } = createPlayer({ features: videoFeatures });
+
+class PiPButton extends MediaElement {
+  readonly #pip = new PlayerController(this, context, selectPiP);
+}
+```