@videojs/react 10.0.0-beta.26 → 10.0.0-beta.27

package/docs/how-to/i18n-override-translations.md

@@ -27,15 +27,15 @@ tsx
 
 ```
 import { I18nProvider } from '@videojs/react/i18n';
-import { Provider, VideoSkin, Video } from '@videojs/react/video';
+import { VideoPlayer, VideoSkin, Video } from '@videojs/react/video';
 
-<Provider>
+<VideoPlayer>
   <I18nProvider locale="es" translations={{ buttons: { play: 'Comenzar' } }}>
     <VideoSkin>
       <Video src="..." playsInline />
     </VideoSkin>
   </I18nProvider>
-</Provider>
+</VideoPlayer>
 ```
 
 Nested providers inherit the parent locale when you only pass `translations`:

package/docs/how-to/i18n-register-locale.md

@@ -20,17 +20,17 @@ app.tsx
 ```
 import { I18nProvider } from '@videojs/react/i18n';
 import '@videojs/react/i18n/locales/es/register';
-import { Provider, VideoSkin, Video } from '@videojs/react/video';
+import { VideoPlayer, VideoSkin, Video } from '@videojs/react/video';
 
 export function App() {
   return (
-    <Provider>
+    <VideoPlayer>
       <I18nProvider locale="es">
         <VideoSkin>
           <Video src="..." playsInline />
         </VideoSkin>
       </I18nProvider>
-    </Provider>
+    </VideoPlayer>
   );
 }
 ```

package/docs/how-to/i18n-ssr.md

@@ -26,7 +26,7 @@ tsx
 
 ```
 import { I18nProvider } from '@videojs/react/i18n';
-import { Provider, VideoSkin, Video } from '@videojs/react/video';
+import { VideoPlayer, VideoSkin, Video } from '@videojs/react/video';
 
 const loaders = {
   es: () => import('@videojs/react/i18n/locales/es'),
@@ -39,13 +39,13 @@ export async function Player({ locale }: { locale: string }) {
   const { default: translations } = await load();
 
   return (
-    <Provider>
+    <VideoPlayer>
       <I18nProvider locale={locale} translations={translations}>
         <VideoSkin>
           <Video src="..." playsInline />
         </VideoSkin>
       </I18nProvider>
-    </Provider>
+    </VideoPlayer>
   );
 }
 ```

package/docs/how-to/i18n-switch-locale.md

@@ -31,7 +31,7 @@ tsx
 ```
 import { useState } from 'react';
 import { I18nProvider } from '@videojs/react/i18n';
-import { Provider, VideoSkin, Video } from '@videojs/react/video';
+import { VideoPlayer, VideoSkin, Video } from '@videojs/react/video';
 
 function App() {
   const [locale, setLocale] = useState<'en' | 'es' | 'fr'>('en');
@@ -41,13 +41,13 @@ function App() {
       <button type="button" onClick={() => setLocale('es')}>
         Español
       </button>
-      <Provider>
+      <VideoPlayer>
         <I18nProvider locale={locale}>
           <VideoSkin>
             <Video src="..." playsInline />
           </VideoSkin>
         </I18nProvider>
-      </Provider>
+      </VideoPlayer>
     </>
   );
 }

package/docs/how-to/installation.md

@@ -77,13 +77,8 @@ Add it to your components folder in a new file.
 ./components/player/index.tsx
 
 ```
-'use client';
-
 import '@videojs/react/video/skin.css';
-import { createPlayer, videoFeatures } from '@videojs/react';
-import { VideoSkin, Video } from '@videojs/react/video';
-
-const Player = createPlayer({ features: videoFeatures });
+import { VideoPlayer, VideoSkin, Video } from '@videojs/react/video';
 
 interface MyPlayerProps {
   src: string;
@@ -91,11 +86,11 @@ interface MyPlayerProps {
 
 export const MyPlayer = ({ src }: MyPlayerProps) => {
   return (
-    <Player.Provider>
+    <VideoPlayer>
       <VideoSkin>
         <Video src={src} playsInline />
       </VideoSkin>
-    </Player.Provider>
+    </VideoPlayer>
   );
 };
 ```

package/docs/llms.txt

@@ -20,6 +20,7 @@ Understanding-oriented pages that explain how and why things work. Read these to
 - [Presets](./concepts/presets.md): Pre-packaged player configurations that bundle state management, skins, and media elements for specific use cases.
 - [UI components](./concepts/ui-components.md): How Video.js UI components work — one element per component, data attributes for state, and compound composition.
 - [Accessibility](./concepts/accessibility.md): How Video.js approaches accessibility, and what you should consider if you're deeply customizing your player
+- [Media sources](./concepts/media-sources.md): Set what a media element plays and how its engine plays it with the structured source property
 - [Google Cast](./concepts/cast.md): Cast playback to Chromecast devices with the Google Cast component, and configure the receiver and load request
 - [Mux Data](./concepts/mux-data.md): Monitor playback quality and viewer experience by adding the Mux Data component to a player
 - [Security](./concepts/security.md): How to configure Content Security Policy for your video player
@@ -39,12 +40,16 @@ Task-oriented guides with step-by-step instructions to achieve a specific outcom
 - [Switch locale dynamically](./how-to/i18n-switch-locale.md): Change the player language at runtime in HTML and React
 - [SSR and locale](./how-to/i18n-ssr.md): Render translated player UI on the server without a flash of English
 
-## Components
+## API Reference
+
+Reference for every public export, grouped by what it is: UI components, media components, player features, and utilities.
+
+### UI Components
 
 API Reference for UI components for building media player interfaces.
 
-- [Player.Provider](./reference/player-provider.md): The state boundary — creates a store and broadcasts it to all descendants.
-- [Player.Container](./reference/player-container.md): The player's interaction surface — handles layout, fullscreen, media attachment, and user activity detection.
+- [Player](./reference/player-provider.md): The state boundary — creates a store and broadcasts it to all descendants.
+- [Container](./reference/player-container.md): The player's interaction surface — handles layout, fullscreen, media attachment, and user activity detection.
 - [I18nProvider](./reference/i18n-provider.md): React provider that resolves locale and supplies a typed translator to descendants
 - [AirPlayButton](./reference/airplay-button.md): Accessible AirPlay toggle button that opens the WebKit playback target picker and reflects session state
 - [AudioTrackRadioGroup](./reference/audio-track-radio-group.md): A menu radio group for selecting an audio track
@@ -73,32 +78,53 @@ API Reference for UI components for building media player interfaces.
 - [Tooltip](./reference/tooltip.md): A tooltip component for displaying contextual labels on hover and focus
 - [VolumeSlider](./reference/volume-slider.md): A slider component for controlling media playback volume
 
-## Media Elements
+### Media Components
 
-API Reference for media elements that handle streaming protocols and media playback.
+API Reference for media components that handle streaming protocols and media playback.
 
 - [BackgroundVideo](./reference/background-video.md): Decorative background video element with automatic muting and looping
 - [DashVideo](./reference/dash-video.md): DASH video element powered by dash.js for adaptive bitrate streaming
+- [HlsAudio](./reference/hls-audio.md): Audio-only HLS element that plays the audio rendition of an HLS stream
+- [HlsVideo](./reference/hls-video.md): Lightweight HLS video element with minimal bundle size
 - [HlsJsVideo](./reference/hlsjs-video.md): HLS video element powered by hls.js for adaptive bitrate streaming
 - [MuxAudio](./reference/mux-audio.md): Audio element for Mux-hosted HLS streams
 - [MuxVideo](./reference/mux-video.md): Video element for Mux-hosted HLS streams
 - [NativeHlsVideo](./reference/native-hls-video.md): HLS video element using the browser's built-in HLS support
-- [SimpleHlsAudioOnly](./reference/simple-hls-audio-only.md): Audio-only HLS element that plays the audio rendition of an HLS stream
-- [SimpleHlsVideo](./reference/simple-hls-video.md): Lightweight HLS video element with minimal bundle size
 
-## Hooks & Utilities
+### Player Features
 
-API reference for hooks and utilities for player integration.
+API reference for the feature modules passed to createPlayer, which provide player capabilities and state.
 
-- [createPlayer](./reference/create-player.md): Factory function that creates a player instance with typed store, Provider component, Container, and hooks
+- [createSelector](./reference/create-selector.md): Create a type-safe selector for a store slice's state
+- [Buffer](./reference/feature-buffer.md): Buffered and seekable time range state for the player store
+- [Controls](./reference/feature-controls.md): User activity and controls visibility state for the player store
+- [Error](./reference/feature-error.md): Media error state and actions for the player store
+- [Fullscreen](./reference/feature-fullscreen.md): Fullscreen state and actions for the player store
+- [Live](./reference/feature-live.md): Live edge state for the player store
+- [Orientation lock](./reference/feature-orientation-lock.md): Screen orientation locking while fullscreen is active
+- [Picture-in-picture](./reference/feature-pip.md): Picture-in-picture state and actions for the player store
+- [Playback](./reference/feature-playback.md): Play/pause state and actions for the player store
+- [Playback rate](./reference/feature-playback-rate.md): Playback speed state and actions for the player store
+- [Quality](./reference/feature-quality.md): Video rendition state and actions for the player store
+- [Audio track](./reference/feature-audio-track.md): Audio track state and actions for the player store
+- [Remote Playback](./reference/feature-remote-playback.md): Remote playback state and actions for the player store
+- [Source](./reference/feature-source.md): Media source state and actions for the player store
+- [Stream type](./reference/feature-stream-type.md): Stream delivery type (live / on-demand) state for the player store
+- [Text tracks](./reference/feature-text-tracks.md): Subtitles, captions, and chapter track state for the player store
+- [Time](./reference/feature-time.md): Playback position and duration state for the player store
+- [Volume](./reference/feature-volume.md): Volume level and mute state for the player store
+
+### Utilities
+
+API reference for the hooks, utilities, controllers, and mixins used to integrate a player into an application.
+
+- [createPlayer](./reference/create-player.md): Factory function that creates a typed Player component and hooks
+- [usePlayer](./reference/use-player.md): Hook to access the player store from within a Player
+- [useMedia](./reference/use-media.md): Hook to access the media object from within a Player
+- [useStore](./reference/use-store.md): Hook to access store state and actions with optional selector-based subscriptions
 - [createI18n](./reference/create-i18n.md): Factory that creates framework i18n helpers with custom loading options
 - [useTranslator](./reference/use-translator.md): React hook that returns the typed translator for the nearest I18nProvider
 - [useLocale](./reference/use-locale.md): React hook that returns the active BCP 47 locale from the nearest I18nProvider
-- [Player.usePlayer](./reference/use-player.md): Hook to access the player store from within a Player.Provider
-- [Player.useMedia](./reference/use-media.md): Hook to access the media object from within a Player.Provider
-- [useStore](./reference/use-store.md): Hook to access store state and actions with optional selector-based subscriptions
-### Advanced
-
 - [registerI18n](./reference/register-i18n.md): Register or merge translation strings for a BCP 47 locale tag in the global i18n registry
 - [getI18nTranslations](./reference/get-i18n-translations.md): Read the merged translation map for a locale using BCP 47 parent-chain fallback
 - [hasRegisteredLocale](./reference/has-registered-locale.md): Check whether an exact locale tag exists in the global i18n registry
@@ -114,27 +140,4 @@ API reference for hooks and utilities for player integration.
 - [usePlayerContext](./reference/use-player-context.md): Hook to access the full player context value
 - [useQualityOptions](./reference/use-quality-options.md): Hook to build video quality menu options from the player rendition state
 - [useSelector](./reference/use-selector.md): Low-level hook for subscribing to derived state with customizable equality checks
-- [useSnapshot](./reference/use-snapshot.md): Hook to subscribe to a State container's current value
-
-## Features
-
-API reference for feature modules that provide player capabilities and state.
-
-- [createSelector](./reference/create-selector.md): Create a type-safe selector for a store slice's state
-- [Buffer](./reference/feature-buffer.md): Buffered and seekable time range state for the player store
-- [Controls](./reference/feature-controls.md): User activity and controls visibility state for the player store
-- [Error](./reference/feature-error.md): Media error state and actions for the player store
-- [Fullscreen](./reference/feature-fullscreen.md): Fullscreen state and actions for the player store
-- [Live](./reference/feature-live.md): Live edge state for the player store
-- [Orientation lock](./reference/feature-orientation-lock.md): Screen orientation locking while fullscreen is active
-- [Picture-in-picture](./reference/feature-pip.md): Picture-in-picture state and actions for the player store
-- [Playback](./reference/feature-playback.md): Play/pause state and actions for the player store
-- [Playback rate](./reference/feature-playback-rate.md): Playback speed state and actions for the player store
-- [Quality](./reference/feature-quality.md): Video rendition state and actions for the player store
-- [Audio track](./reference/feature-audio-track.md): Audio track state and actions for the player store
-- [Remote Playback](./reference/feature-remote-playback.md): Remote playback state and actions for the player store
-- [Source](./reference/feature-source.md): Media source state and actions for the player store
-- [Stream type](./reference/feature-stream-type.md): Stream delivery type (live / on-demand) state for the player store
-- [Text tracks](./reference/feature-text-tracks.md): Subtitles, captions, and chapter track state for the player store
-- [Time](./reference/feature-time.md): Playback position and duration state for the player store
-- [Volume](./reference/feature-volume.md): Volume level and mute state for the player store
+- [useSnapshot](./reference/use-snapshot.md): Hook to subscribe to a State container's current value

package/docs/reference/airplay-button.md

@@ -91,15 +91,15 @@ App.tsx
 App.css
 
 ```
-import { AirPlayButton, createPlayer } from '@videojs/react';
+import { AirPlayButton, Container, createPlayer } from '@videojs/react';
 import { Video, videoFeatures } from '@videojs/react/video';
 
-const Player = createPlayer({ features: videoFeatures });
+const { Player } = createPlayer({ features: videoFeatures });
 
 export default function BasicUsage() {
   return (
-    <Player.Provider>
-      <Player.Container className="media-container">
+    <Player>
+      <Container className="media-container">
         <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
         <AirPlayButton
           className="media-airplay-button"
@@ -107,8 +107,8 @@ export default function BasicUsage() {
             <button {...props}>{state.state === 'connected' ? 'Stop AirPlay' : 'Start AirPlay'}</button>
           )}
         />
-      </Player.Container>
-    </Player.Provider>
+      </Container>
+    </Player>
   );
 }
 ```

package/docs/reference/audio-track-radio-group.md

@@ -9,19 +9,21 @@ Creates radio items from the player audio track state and selects the enabled tr
 tsx
 
 ```
-<Menu.RadioGroup>
-  <Menu.GroupLabel />
-  <Menu.RadioItem>
-    <Menu.ItemIndicator />
-  </Menu.RadioItem>
-</Menu.RadioGroup>
+<AudioTrackRadioGroup
+  renderItem={(props, item) => (
+    <Menu.RadioItem {...props}>
+      {item.label}
+      <Menu.ItemIndicator checked={item.checked} />
+    </Menu.RadioItem>
+  )}
+/>
 ```
 
 ## Behavior
 
 The group is available when the configured media exposes more than one audio track. Labels use the track label, then language, then kind. Pass `formatTrack` to customize the visible labels.
 
-[`useAudioTrackOptions`](./use-audio-track-options.md) returns `null` when the [audio track feature](./feature-audio-track.md) is not configured. Use the returned options with [`Menu.RadioGroup`](./menu.md).
+`AudioTrackRadioGroup` uses [`useAudioTrackOptions`](./use-audio-track-options.md) to own selection and generate each item. Its required `renderItem` callback renders the [`Menu.RadioItem`](./menu.md) root and receives item state containing the translated `label` and current `checked` value. It returns `null` when the [audio track feature](./feature-audio-track.md) is not configured.
 
 ## Styling
 
@@ -43,60 +45,63 @@ Present / absent
 
 Present when audio track selection is disabled.
 
+`data-hidden`
+
+Present / absent
+
+Present when multiple audio tracks are unavailable.
+
 `data-availability`
 
 `"available"` / `"unavailable"`
 
 Whether multiple audio tracks are available.
 
+Unavailable groups receive the native `hidden` attribute.
+
 ## Accessibility
 
 The group uses the menu radio group pattern.
 
-Give `Menu.RadioGroup` an accessible name with `aria-label` or a nested `Menu.GroupLabel`.
+The component receives an accessible label from the `label` prop or defaults to `Audio`. Override it with `aria-label` or `aria-labelledby`.
 
 ## Examples
 
 ### Basic usage
 
+Audio
+
 App.tsx
 
 App.css
 
 ```
-import { createPlayer, Menu, useAudioTrackOptions } from '@videojs/react';
+import { AudioTrackRadioGroup, Container, createPlayer, Menu } from '@videojs/react';
 import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
 import { videoFeatures } from '@videojs/react/video';
 import type { ReactNode } from 'react';
 
-const Player = createPlayer({ features: videoFeatures });
+const { Player } = createPlayer({ features: videoFeatures });
 const src = 'https://stream.mux.com/s41JYeqIpBMBzE4OzxDyGR2yrp2hD1CQ6gJN9SlVGDQ.m3u8';
 
 function AudioMenu(): ReactNode {
-  const audioTrack = useAudioTrackOptions();
-  if (audioTrack?.state.availability !== 'available') return null;
-
   return (
     <Menu.Root side="top" align="end">
       <Menu.Trigger className="settings-trigger" render={<button type="button" />}>
         Audio
       </Menu.Trigger>
       <Menu.Content className="menu">
-        <Menu.RadioGroup
+        <AudioTrackRadioGroup
           className="menu-group"
-          value={audioTrack.value}
-          onValueChange={audioTrack.setValue}
-          aria-label="Audio tracks"
-        >
-          {audioTrack.options.map((option) => (
-            <Menu.RadioItem key={option.value} value={option.value} disabled={option.disabled} className="menu-item">
-              {option.label}
-              <Menu.ItemIndicator checked={option.value === audioTrack.value} forceMount className="menu-indicator">
+          renderItem={(props, item) => (
+            <Menu.RadioItem {...props} className="menu-item">
+              {item.label}
+              <Menu.ItemIndicator checked={item.checked} forceMount className="menu-indicator">
                 ✓
               </Menu.ItemIndicator>
             </Menu.RadioItem>
-          ))}
-        </Menu.RadioGroup>
+          )}
+        />
       </Menu.Content>
     </Menu.Root>
   );
@@ -104,14 +109,14 @@ function AudioMenu(): ReactNode {
 
 export default function BasicUsage() {
   return (
-    <Player.Provider>
-      <Player.Container className="media-container">
+    <Player>
+      <Container className="media-container">
         <HlsJsVideo src={src} autoPlay crossOrigin="anonymous" muted playsInline loop />
         <div className="menu-bar">
           <AudioMenu />
         </div>
-      </Player.Container>
-    </Player.Provider>
+      </Container>
+    </Player>
   );
 }
 ```
@@ -191,4 +196,168 @@ export default function BasicUsage() {
 [role="menuitemradio"][aria-checked="true"] .menu-indicator {
   opacity: 1;
 }
-```
+```
+
+## API Reference
+
+### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`disabled`
+
+`boolean`
+
+`false`
+
+▸
+
+Description
+
+Whether audio track selection is disabled.
+
+`formatTrack`
+
+`Text) | function`
+
+`formatTrackLabel`
+
+▸
+
+Description
+
+Custom formatter for visible track labels.
+
+Type
+
+`((track: MediaAudioTrack) => string | Text)`
+
+`label`
+
+`Text | string | Text) | function`
+
+`''`
+
+▸
+
+Description
+
+Custom label for the options group.
+
+Type
+
+`Text | string | ((state: AudioTrackRadioGroupState) => string | Text)`
+
+### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+Property
+
+Type
+
+Details
+
+`value`
+
+`string`
+
+▸
+
+Description
+
+Current radio-group value.
+
+`options`
+
+`AudioTrackRadioGroupOption[]`
+
+▸
+
+Description
+
+Ordered options displayed by platform adapters.
+
+`disabled`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the entire option group is disabled.
+
+`hidden`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the option group is hidden because no meaningful selection is available.
+
+`availability`
+
+`'available' | 'unavailable'`
+
+▸
+
+Description
+
+Whether the media exposes a meaningful selection.
+
+`label`
+
+`Text | string`
+
+### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-audio-track`
+
+`string`
+
+▸
+
+Description
+
+Current audio track value.
+
+`data-disabled`
+
+▸
+
+Description
+
+Present when audio track selection is disabled.
+
+`data-hidden`
+
+▸
+
+Description
+
+Present when audio track selection is unavailable.
+
+`data-availability`
+
+`'available' | 'unavailable'`
+
+▸
+
+Description
+
+Indicates audio track availability (`available` or `unavailable`).

package/docs/reference/buffering-indicator.md

@@ -27,22 +27,22 @@ App.tsx
 App.css
 
 ```
-import { BufferingIndicator, createPlayer } from '@videojs/react';
+import { BufferingIndicator, Container, createPlayer } from '@videojs/react';
 import { Video, videoFeatures } from '@videojs/react/video';
 
-const Player = createPlayer({ features: videoFeatures });
+const { Player } = createPlayer({ features: videoFeatures });
 
 export default function BasicUsage() {
   return (
-    <Player.Provider>
-      <Player.Container className="media-container">
+    <Player>
+      <Container className="media-container">
         <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
         <BufferingIndicator
           className="media-buffering-indicator"
           render={(props, state) => <div {...props}>{state.visible && <div className="spinner" />}</div>}
         />
-      </Player.Container>
-    </Player.Provider>
+      </Container>
+    </Player>
   );
 }
 ```

package/docs/reference/captions-button.md

@@ -57,15 +57,15 @@ App.tsx
 App.css
 
 ```
-import { CaptionsButton, createPlayer } from '@videojs/react';
+import { CaptionsButton, Container, createPlayer } from '@videojs/react';
 import { Video, videoFeatures } from '@videojs/react/video';
 
-const Player = createPlayer({ features: videoFeatures });
+const { Player } = createPlayer({ features: videoFeatures });
 
 export default function BasicUsage() {
   return (
-    <Player.Provider>
-      <Player.Container className="media-container">
+    <Player>
+      <Container className="media-container">
         <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop>
           <track kind="captions" src="/docs/demos/captions-button/captions.vtt" srcLang="en" label="English" />
         </Video>
@@ -75,8 +75,8 @@ export default function BasicUsage() {
             <button {...props}>{state.subtitlesShowing ? 'Captions Off' : 'Captions On'}</button>
           )}
         />
-      </Player.Container>
-    </Player.Provider>
+      </Container>
+    </Player>
   );
 }
 ```