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

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/feature-buffer.md

@@ -0,0 +1,54 @@
+# 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 [`usePlayer`](./use-player.md) to subscribe to buffer state. Returns `undefined` if the buffer feature is not configured.
+
+BufferBar.tsx
+
+```
+import { selectBuffer, usePlayer } from '@videojs/react';
+
+function BufferBar() {
+  const buffer = usePlayer(selectBuffer);
+  if (!buffer) return null;
+
+  return (
+    <div style={{ width: `${buffer.percentBuffered * 100}%` }} />
+  );
+}
+```

package/docs/reference/feature-controls.md

@@ -0,0 +1,74 @@
+# 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 [`usePlayer`](./use-player.md) to subscribe to controls state. Returns `undefined` if the controls feature is not configured.
+
+ControlsOverlay.tsx
+
+```
+import { selectControls, usePlayer } from '@videojs/react';
+
+function ControlsOverlay({ children }: { children: React.ReactNode }) {
+  const controls = usePlayer(selectControls);
+  if (!controls) return null;
+
+  return (
+    <div style={{ opacity: controls.visible ? 1 : 0 }}>
+      {children}
+    </div>
+  );
+}
+```