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

package/docs/reference/captions-radio-group.md

@@ -9,19 +9,21 @@ Creates radio items from the player text track state and selects the showing cap
 tsx
 
 ```
-<Menu.RadioGroup>
-  <Menu.GroupLabel />
-  <Menu.RadioItem>
-    <Menu.ItemIndicator />
-  </Menu.RadioItem>
-</Menu.RadioGroup>
+<CaptionsRadioGroup
+  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 at least one caption or subtitle track. The first generated option is `Off`; selecting it hides captions. Track labels use the track label, then language, then kind. Pass `formatTrack` to customize the visible labels.
 
-[`useCaptionsOptions`](./use-captions-options.md) returns `null` when the [text tracks feature](./feature-text-tracks.md) is not configured. Use the returned options with [`Menu.RadioGroup`](./menu.md).
+`CaptionsRadioGroup` uses [`useCaptionsOptions`](./use-captions-options.md) to own selection and generate each item, including `Off`. 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 [text tracks feature](./feature-text-tracks.md) is not configured.
 
 ## Styling
 
@@ -43,58 +45,61 @@ Present / absent
 
 Present when track selection is disabled.
 
+`data-hidden`
+
+Present / absent
+
+Present when caption or subtitle tracks are unavailable.
+
 `data-availability`
 
 `"available"` / `"unavailable"`
 
 Whether caption or subtitle 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 `Captions`. Override it with `aria-label` or `aria-labelledby`.
 
 ## Examples
 
 ### Basic usage
 
+Captions
+
 App.tsx
 
 App.css
 
 ```
-import { createPlayer, Menu, useCaptionsOptions } from '@videojs/react';
+import { CaptionsRadioGroup, Container, createPlayer, Menu } from '@videojs/react';
 import { Video, videoFeatures } from '@videojs/react/video';
 import type { ReactNode } from 'react';
 
-const Player = createPlayer({ features: videoFeatures });
+const { Player } = createPlayer({ features: videoFeatures });
 
 function CaptionsMenu(): ReactNode {
-  const captions = useCaptionsOptions();
-  if (captions?.state.availability !== 'available') return null;
-
   return (
     <Menu.Root side="top" align="end">
       <Menu.Trigger className="settings-trigger" render={<button type="button" />}>
         Captions
       </Menu.Trigger>
       <Menu.Content className="menu">
-        <Menu.RadioGroup
+        <CaptionsRadioGroup
           className="menu-group"
-          value={captions.value}
-          onValueChange={captions.setValue}
-          aria-label="Captions"
-        >
-          {captions.options.map((option) => (
-            <Menu.RadioItem key={option.value} value={option.value} disabled={option.disabled} className="menu-item">
-              {option.label}
-              <Menu.ItemIndicator checked={option.value === captions.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>
   );
@@ -102,8 +107,8 @@ function CaptionsMenu(): ReactNode {
 
 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" />
           <track kind="subtitles" src="/docs/demos/captions-button/captions.vtt" srcLang="es" label="Spanish" />
@@ -111,8 +116,8 @@ export default function BasicUsage() {
         <div className="menu-bar">
           <CaptionsMenu />
         </div>
-      </Player.Container>
-    </Player.Provider>
+      </Container>
+    </Player>
   );
 }
 ```
@@ -192,4 +197,176 @@ 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 track selection is disabled.
+
+`formatTrack`
+
+`Text) | function`
+
+`formatTrackLabel`
+
+▸
+
+Description
+
+Custom formatter for visible track labels.
+
+Type
+
+`((track: MediaTextTrack) => string | Text)`
+
+`label`
+
+`Text | string | Text) | function`
+
+`''`
+
+▸
+
+Description
+
+Custom label for the options group.
+
+Type
+
+`Text | string | ((state: CaptionsRadioGroupState) => string | Text)`
+
+### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+Property
+
+Type
+
+Details
+
+`subtitlesShowing`
+
+`boolean`
+
+▸
+
+Description
+
+Whether captions/subtitles are currently enabled.
+
+`value`
+
+`string`
+
+▸
+
+Description
+
+Current radio-group value.
+
+`options`
+
+`CaptionsRadioGroupOption[]`
+
+▸
+
+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-active`
+
+▸
+
+Description
+
+Present when captions are enabled.
+
+`data-disabled`
+
+▸
+
+Description
+
+Present when track selection is disabled.
+
+`data-hidden`
+
+▸
+
+Description
+
+Present when track selection is unavailable.
+
+`data-availability`
+
+`'available' | 'unavailable'`
+
+▸
+
+Description
+
+Indicates captions availability (`available` or `unavailable`).

package/docs/reference/cast-button.md

@@ -76,16 +76,16 @@ App.tsx
 App.css
 
 ```
-import { CastButton, createPlayer } from '@videojs/react';
+import { CastButton, Container, createPlayer } from '@videojs/react';
 import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
 import { 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">
         <HlsJsVideo src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" autoPlay muted playsInline loop />
         <CastButton
           className="media-cast-button"
@@ -93,8 +93,8 @@ export default function BasicUsage() {
             <button {...props}>{state.connection === 'connected' ? 'Stop casting' : 'Start casting'}</button>
           )}
         />
-      </Player.Container>
-    </Player.Provider>
+      </Container>
+    </Player>
   );
 }
 ```

package/docs/reference/controls.md

@@ -63,15 +63,15 @@ App.tsx
 App.css
 
 ```
-import { Controls, createPlayer, PlayButton, Time } from '@videojs/react';
+import { Container, Controls, createPlayer, PlayButton, Time } 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 />
 
         <Controls.Root className="media-controls">
@@ -84,8 +84,8 @@ export default function BasicUsage() {
             <Time.Value type="current" className="time" />
           </Controls.Group>
         </Controls.Root>
-      </Player.Container>
-    </Player.Provider>
+      </Container>
+    </Player>
   );
 }
 ```

package/docs/reference/create-player.md

@@ -1,6 +1,6 @@
 # createPlayer
 
-Factory function that creates a player instance with typed store, Provider component, Container, and hooks
+Factory function that creates a typed Player component 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.
 
@@ -9,11 +9,14 @@ The hook is typed according to the provided features, giving you full type safet
 tsx
 
 ```
-import { createPlayer } from '@videojs/react';
+import { Container, createPlayer } from '@videojs/react';
 import { videoFeatures } from '@videojs/react/video';
 
-const Player = createPlayer({ features: videoFeatures });
-// Player.Provider, Player.Container, Player.usePlayer, Player.useMedia
+const { Player, usePlayer, useMedia } = createPlayer({
+  features: videoFeatures,
+});
+
+// Container is imported independently from createPlayer.
 ```
 
 ## Examples
@@ -27,16 +30,16 @@ App.tsx
 App.css
 
 ```
-import { createPlayer } from '@videojs/react';
+import { Container, createPlayer } from '@videojs/react';
 import { Video, videoFeatures } from '@videojs/react/video';
 
-const Player = createPlayer({
+const { Player, usePlayer } = createPlayer({
   features: videoFeatures,
 });
 
 function Controls() {
-  const store = Player.usePlayer();
-  const paused = Player.usePlayer((s) => s.paused);
+  const store = usePlayer();
+  const paused = usePlayer((s) => s.paused);
 
   return (
     <div className="controls">
@@ -49,12 +52,12 @@ function Controls() {
 
 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 />
         <Controls />
-      </Player.Container>
-    </Player.Provider>
+      </Container>
+    </Player>
   );
 }
 ```
@@ -89,7 +92,7 @@ export default function BasicUsage() {
 
 ### Video
 
-Create a player instance with typed store, Provider component, Container, and hooks.
+Create a player instance with a typed Player component and hooks.
 
 #### Parameters
 
@@ -121,13 +124,9 @@ Type
 
 Details
 
-`Provider`
-
-`React.FC<ProviderProps>`
-
-`Container`
+`Player`
 
-`React.ForwardRefExoticComponent<ContainerProps & RefAttributes<HTMLDivElement>>`
+`React.FC<PlayerProps<{ contentTitle: MediaContentValue; defaultContentTitle: MediaContentValue }>>`
 
 `usePlayer`
 
@@ -177,13 +176,9 @@ Type
 
 Details
 
-`Provider`
+`Player`
 
-`React.FC<ProviderProps>`
-
-`Container`
-
-`React.ForwardRefExoticComponent<ContainerProps & RefAttributes<HTMLDivElement>>`
+`React.FC<PlayerProps<{ contentTitle: MediaContentValue; defaultContentTitle: MediaContentValue }>>`
 
 `usePlayer`
 
@@ -233,13 +228,9 @@ Type
 
 Details
 
-`Provider`
-
-`React.FC<ProviderProps>`
-
-`Container`
+`Player`
 
-`React.ForwardRefExoticComponent<ContainerProps & RefAttributes<HTMLDivElement>>`
+`React.FC<PlayerProps<Config | object>>`
 
 `usePlayer`
 

package/docs/reference/create-translator.md

@@ -56,7 +56,7 @@ BCP 47 tag associated with the map (reserved for future locale-aware behavior).
 
 Type
 
-`string & object | 'ar' | 'az' | 'bs' | 'bg' | 'bn' | 'ca' | 'cs' | 'cy' | 'da' | 'de' | 'el' | 'es' | 'et' | 'eu' | 'fa' | 'fi' | 'fr' | 'gd' | 'gl' | 'he' | 'hi' | 'hr' | 'hu' | 'it' | 'ja' | 'ko' | 'lv' | 'mr' | 'nb' | 'nl' | 'nn' | 'ne' | 'oc' | 'pl' | 'pt-BR' | 'pt-PT' | 'ro' | 'ru' | 'sk' | 'sl' | 'sr' | 'sv' | 'te' | 'th' | 'tr' | 'uk' | 'vi' | 'zh-CN' | 'zh-TW'`
+`string & object | 'ar' | 'az' | 'bs' | 'bg' | 'bn' | 'ca' | 'cs' | 'cy' | 'da' | 'de' | 'el' | 'es' | 'et' | 'eu' | 'fa' | 'fi' | 'fr' | 'gd' | 'gl' | 'he' | 'hi' | 'hr' | 'hu' | 'id' | 'it' | 'ja' | 'ko' | 'lt' | 'lv' | 'mr' | 'nb' | 'nl' | 'nn' | 'ne' | 'oc' | 'pl' | 'pt-BR' | 'pt-PT' | 'ro' | 'ru' | 'sk' | 'sl' | 'sr' | 'sv' | 'te' | 'th' | 'tr' | 'uk' | 'vi' | 'zh-CN' | 'zh-TW'`
 
 ### Return Value
 

package/docs/reference/dash-video.md

@@ -40,6 +40,20 @@ Default
 
 Details
 
+`source`
+
+`DashSource | null`
+
+`null`
+
+▸
+
+Description
+
+Structured source: the MPD URL in `src`, plus dash.js settings in `engine.dashJs`. Replacing it re-derives `src`.
+
+dash.js takes settings on a live player, so changing `engine.dashJs` re-applies them in place instead of recreating the engine.
+
 `src`
 
 `string`

package/docs/reference/feature-controls.md

@@ -32,7 +32,7 @@ Whether the user has recently interacted with the player.
 
 Description
 
-Whether controls should be visible (userActive || paused).
+Whether controls should be visible.
 
 ### Actions
 
@@ -42,6 +42,18 @@ Type
 
 Details
 
+`requestControlsLock`
+
+`() => () => void`
+
+▸
+
+Description
+
+Keep controls visible during a sustained interaction.
+
+The returned function releases the lock. Multiple concurrent locks are supported and each release function is idempotent.
+
 `toggleControls`
 
 `() => boolean`

package/docs/reference/feature-fullscreen.md

@@ -105,7 +105,7 @@ ts
 import { createPlayer, features } from '@videojs/react';
 import { videoFeatures } from '@videojs/react/video';
 
-const Player = createPlayer({
+const { Player } = createPlayer({
   features: [...videoFeatures, features.orientationLock({ type: 'portrait' })],
 });
 ```

package/docs/reference/feature-orientation-lock.md

@@ -16,7 +16,7 @@ player.tsx
 import { createPlayer, features } from '@videojs/react';
 import { videoFeatures } from '@videojs/react/video';
 
-export const Player = createPlayer({
+export const { Player } = createPlayer({
   features: [...videoFeatures, features.orientationLock],
 });
 ```
@@ -27,7 +27,7 @@ portrait-player.tsx
 import { createPlayer, features } from '@videojs/react';
 import { videoFeatures } from '@videojs/react/video';
 
-export const Player = createPlayer({
+export const { Player } = createPlayer({
   features: [...videoFeatures, features.orientationLock({ type: 'portrait' })],
 });
 ```

package/docs/reference/feature-text-tracks.md

@@ -4,6 +4,8 @@ Subtitles, captions, and chapter track state for the player store
 
 Manages subtitles, captions, chapters, and thumbnail tracks.
 
+A default `kind="chapters"` track can also divide the [time slider](./time-slider.md) into chapter ranges and label the chapter at the current interaction position.
+
 ## API Reference
 
 ### State
@@ -80,7 +82,7 @@ Details
 
 Description
 
-Toggle captions/subtitles visibility. Returns the new enabled value.
+Toggle captions/subtitles visibility. Showing restores the track that was last showing, or the first caption/subtitle track when there is none. Returns the new enabled value.
 
 `selectSubtitlesTrack`
 

package/docs/reference/feature-volume.md

@@ -2,7 +2,7 @@
 
 Volume level and mute state for the player store
 
-Controls volume level and mute state.
+Controls volume level and mute state. These capabilities have independent availability values because media can support mute without supporting volume-level changes.
 
 ## API Reference
 
@@ -44,6 +44,16 @@ Description
 
 Whether volume can be programmatically set on this platform.
 
+`mutedAvailability`
+
+`'available' | 'unavailable' | 'unsupported'`
+
+▸
+
+Description
+
+Whether the media can be muted. Separate from `volumeAvailability` because the two come apart: an embed can take a mute command while offering no way to set a level, and iOS Safari refuses a volume write on media that mutes perfectly well.
+
 ### Actions
 
 Action
@@ -76,6 +86,8 @@ Toggle mute state. Returns the new muted value.
 
 Pass `selectVolume` to [`usePlayer`](./use-player.md) to subscribe to volume state. Returns `undefined` if the volume feature is not configured.
 
+Check `volumeAvailability` before showing a volume-level control, and check `mutedAvailability` before showing a mute control.
+
 VolumeSlider.tsx
 
 ```
@@ -83,7 +95,7 @@ import { selectVolume, usePlayer } from '@videojs/react';
 
 function VolumeSlider() {
   const vol = usePlayer(selectVolume);
-  if (!vol) return null;
+  if (!vol || vol.volumeAvailability !== 'available') return null;
 
   return (
     <input

package/docs/reference/fullscreen-button.md

@@ -53,22 +53,22 @@ App.tsx
 App.css
 
 ```
-import { createPlayer, FullscreenButton } from '@videojs/react';
+import { Container, createPlayer, FullscreenButton } 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 />
         <FullscreenButton
           className="media-fullscreen-button"
           render={(props, state) => <button {...props}>{state.fullscreen ? 'Exit Fullscreen' : 'Fullscreen'}</button>}
         />
-      </Player.Container>
-    </Player.Provider>
+      </Container>
+    </Player>
   );
 }
 ```

package/docs/reference/get-i18n-translations.md

@@ -41,7 +41,7 @@ BCP 47 tag to resolve (e.g. `es-MX`, `zh-Hant-HK`).
 
 Type
 
-`string & object | 'ar' | 'az' | 'bs' | 'bg' | 'bn' | 'ca' | 'cs' | 'cy' | 'da' | 'de' | 'el' | 'es' | 'et' | 'eu' | 'fa' | 'fi' | 'fr' | 'gd' | 'gl' | 'he' | 'hi' | 'hr' | 'hu' | 'it' | 'ja' | 'ko' | 'lv' | 'mr' | 'nb' | 'nl' | 'nn' | 'ne' | 'oc' | 'pl' | 'pt-BR' | 'pt-PT' | 'ro' | 'ru' | 'sk' | 'sl' | 'sr' | 'sv' | 'te' | 'th' | 'tr' | 'uk' | 'vi' | 'zh-CN' | 'zh-TW'`
+`string & object | 'ar' | 'az' | 'bs' | 'bg' | 'bn' | 'ca' | 'cs' | 'cy' | 'da' | 'de' | 'el' | 'es' | 'et' | 'eu' | 'fa' | 'fi' | 'fr' | 'gd' | 'gl' | 'he' | 'hi' | 'hr' | 'hu' | 'id' | 'it' | 'ja' | 'ko' | 'lt' | 'lv' | 'mr' | 'nb' | 'nl' | 'nn' | 'ne' | 'oc' | 'pl' | 'pt-BR' | 'pt-PT' | 'ro' | 'ru' | 'sk' | 'sl' | 'sr' | 'sv' | 'te' | 'th' | 'tr' | 'uk' | 'vi' | 'zh-CN' | 'zh-TW'`
 
 ### Return Value