@videojs/react 10.0.0-beta.23 → 10.0.0-beta.25

package/docs/reference/controls.md

@@ -0,0 +1,238 @@
+# Controls
+
+Container component for composing and auto-hiding video player controls on user interaction
+
+## Anatomy
+
+Import the component and assemble its parts:
+
+tsx
+
+```
+<Controls.Root>
+  <Controls.Group />
+</Controls.Root>
+```
+
+## 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:
+
+React renders `<div>` elements. Add a `className` to style them:
+
+css
+
+```
+/* Click-through: clicks pass through controls to video beneath */
+.controls {
+  pointer-events: none;
+}
+
+.controls-group {
+  pointer-events: auto;
+}
+
+/* Fade transition */
+.controls {
+  transition: opacity 0.25s;
+}
+
+.controls:not([data-visible]) {
+  opacity: 0;
+}
+```
+
+## Accessibility
+
+No ARIA role is applied to `Controls.Root` — it is a layout wrapper, not a landmark. `Controls.Group` automatically receives `role="group"` when an `aria-label` or `aria-labelledby` attribute is provided; otherwise no role is assigned.
+
+## Examples
+
+### Basic Usage
+
+Play0:00
+
+App.tsx
+
+App.css
+
+```
+import { Controls, createPlayer, PlayButton, Time } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const Player = createPlayer({ features: videoFeatures });
+
+export default function BasicUsage() {
+  return (
+    <Player.Provider>
+      <Player.Container className="media-container">
+        <Video
+          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
+          autoPlay
+          muted
+          playsInline
+          loop
+        />
+
+        <Controls.Root className="media-controls">
+          <Controls.Group className="controls-group" aria-label="Playback controls">
+            <PlayButton
+              className="button"
+              render={(props, state) => <button {...props}>{state.paused ? 'Play' : 'Pause'}</button>}
+            />
+
+            <Time.Value type="current" className="time" />
+          </Controls.Group>
+        </Controls.Root>
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container 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);
+}
+```
+
+## API Reference
+
+### 
+
+Root
+
+Root container for player controls state and rendered control content.
+
+#### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+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.
+
+### 
+
+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-player.md

@@ -0,0 +1,261 @@
+# createPlayer
+
+Factory function that creates a player instance with typed store, Provider component, Container, and hooks
+
+`createPlayer` is the entry point for setting up a Video.js player in React. It accepts a configuration object with a `features` array and returns hooks and components for building a player.
+
+The hook is typed according to the provided features, giving you full type safety for state selectors and actions.
+
+tsx
+
+```
+import { createPlayer } from '@videojs/react';
+import { videoFeatures } from '@videojs/react/video';
+
+const Player = createPlayer({ features: videoFeatures });
+// Player.Provider, Player.Container, Player.usePlayer, Player.useMedia
+```
+
+## Examples
+
+### Basic Usage
+
+Play
+
+App.tsx
+
+App.css
+
+```
+import { createPlayer } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const Player = createPlayer({
+  features: videoFeatures,
+});
+
+function Controls() {
+  const store = Player.usePlayer();
+  const paused = Player.usePlayer((s) => s.paused);
+
+  return (
+    <div className="controls">
+      <button type="button" className="button" onClick={() => (paused ? store.play() : store.pause())}>
+        {paused ? 'Play' : 'Pause'}
+      </button>
+    </div>
+  );
+}
+
+export default function BasicUsage() {
+  return (
+    <Player.Provider>
+      <Player.Container className="media-container">
+        <Video
+          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
+          autoPlay
+          muted
+          playsInline
+        />
+        <Controls />
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.controls {
+  position: absolute;
+  bottom: 10px;
+  left: 10px;
+}
+
+.button {
+  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);
+}
+```
+
+## API Reference
+
+### Video
+
+Create a player instance with typed store, Provider component, Container, and hooks.
+
+#### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`config*`
+
+`CreatePlayerConfig<VideoFeatures>`
+
+`—`
+
+▸
+
+Description
+
+Player configuration with features and optional display name.
+
+#### Return Value
+
+Property
+
+Type
+
+Details
+
+`Provider`
+
+`React.FC<ProviderProps>`
+
+`Container`
+
+`React.ForwardRefExoticComponent<ContainerProps & RefAttributes<HTMLDivElement>>`
+
+`usePlayer`
+
+`UsePlayerHook<VideoPlayerStore>`
+
+`useMedia`
+
+`null) | function`
+
+▸
+
+Type
+
+`(() => Media | null)`
+
+### Audio
+
+Create a player for audio media.
+
+#### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`config*`
+
+`CreatePlayerConfig<AudioFeatures>`
+
+`—`
+
+▸
+
+Description
+
+Player configuration with features and optional display name.
+
+#### Return Value
+
+Property
+
+Type
+
+Details
+
+`Provider`
+
+`React.FC<ProviderProps>`
+
+`Container`
+
+`React.ForwardRefExoticComponent<ContainerProps & RefAttributes<HTMLDivElement>>`
+
+`usePlayer`
+
+`UsePlayerHook<AudioPlayerStore>`
+
+`useMedia`
+
+`null) | function`
+
+▸
+
+Type
+
+`(() => Media | null)`
+
+### Generic
+
+Create a player with custom features.
+
+#### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`config*`
+
+`CreatePlayerConfig<AnyPlayerFeature[]>`
+
+`—`
+
+▸
+
+Description
+
+Player configuration with features and optional display name.
+
+#### Return Value
+
+Property
+
+Type
+
+Details
+
+`Provider`
+
+`React.FC<ProviderProps>`
+
+`Container`
+
+`React.ForwardRefExoticComponent<ContainerProps & RefAttributes<HTMLDivElement>>`
+
+`usePlayer`
+
+`UsePlayerHook<PlayerStore<AnyPlayerFeature[]>>`
+
+`useMedia`
+
+`null) | function`
+
+▸
+
+Type
+
+`(() => Media | null)`

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 [`usePlayer`](./use-player.md) or [`useStore`](./use-store.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/dash-video.md

@@ -0,0 +1,138 @@
+# DashVideo
+
+DASH video element powered by dash.js for adaptive bitrate streaming
+
+DASH video element powered by [dash.js](https://github.com/Dash-Industry-Forum/dash.js/) for MPEG-DASH adaptive bitrate streaming.
+
+## Examples
+
+### Basic Usage
+
+App.tsx
+
+App.css
+
+```
+import { DashVideo } from '@videojs/react/media/dash-video';
+
+export default function BasicUsage() {
+  return (
+    <DashVideo
+      className="dash-video"
+      src="https://dash.akamaized.net/akamai/streamroot/050714/Spring_4Ktest.mpd"
+      autoPlay
+      muted
+      playsInline
+      loop
+    />
+  );
+}
+```
+```
+.dash-video {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+```
+
+## API Reference
+
+### Host Properties
+
+Property
+
+Type
+
+Default
+
+Details
+
+`engine`
+
+`MediaPlayerClass`
+
+`—`
+
+▸
+
+Description
+
+Read-only. Underlying playback engine — the dash.js `MediaPlayerClass` instance. An advanced escape hatch for direct engine access; normal playback is driven through this element's own properties and methods.
+
+`src`
+
+`string`
+
+`''`
+
+### Attributes
+
+Renders a native `<video>` element and accepts these media attributes as React props. The standard ones behave as described in the [MDN media attributes reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video): `autopictureinpicture``autoPlay``controls``controlslist``crossOrigin``disablepictureinpicture``disableremoteplayback``loading``loop``muted``playsInline``poster``preload``src``stream-type`
+
+### Events
+
+Handle these media events with React event props (e.g. `onPlay`, `onTimeUpdate`). See [media events](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement#events): `abort``canplay``canplaythrough``durationchange``emptied``ended``error``loadeddata``loadedmetadata``loadstart``pause``play``playing``progress``ratechange``resize``seeked``seeking``stalled``suspend``timeupdate``volumechange``waiting`
+
+These media events have no React prop — attach a listener through a `ref` with `addEventListener`: `addtrack``change``enterpictureinpicture``leavepictureinpicture``removetrack`
+
+This element dispatches no events beyond the media events above.
+
+### Methods
+
+Supports these methods from the native media API. See [HTMLMediaElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement) for the core methods: `addTextTrack``canPlayType``exitFullscreen``exitPictureInPicture``load``pause``play``requestFullscreen``requestPictureInPicture`
+
+In React, call these through a `ref` to the element.
+
+### CSS Custom Properties
+
+Variable
+
+Details
+
+`--media-video-border-radius`
+
+▸
+
+Description
+
+Border radius of the video element.
+
+`--media-object-fit`
+
+▸
+
+Description
+
+Object fit for the video.
+
+`--media-object-position`
+
+▸
+
+Description
+
+Object position for the video.
+
+`--media-caption-track-duration`
+
+▸
+
+Description
+
+Duration of the caption track transition.
+
+`--media-caption-track-delay`
+
+▸
+
+Description
+
+Delay before the caption track transition.
+
+`--media-caption-track-y`
+
+▸
+
+Description
+
+Vertical offset of the caption track.