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

package/docs/reference/airplay-button.md

@@ -14,7 +14,7 @@ tsx
 
 Opens the WebKit AirPlay playback target picker and reflects session state. AirPlay is a WebKit-only feature, so the button reports `availability: "unsupported"` outside Safari (macOS and iOS). On supported platforms availability flips to `"available"` once Safari discovers at least one AirPlay receiver on the local network, and `"unavailable"` otherwise.
 
-The toggle is a no-op unless `availability` is `"available"` — clicking the button while `"unsupported"` or `"unavailable"` will not open the picker. Style the button accordingly (see [Styling](#styling) below) so its appearance matches its actual behavior.
+The button is hidden until `availability` is `"available"`: the HTML custom element receives the native `hidden` attribute, and the React component returns `null`. An explicitly disabled, otherwise available button stays visible and focusable with `aria-disabled="true"` and `data-disabled`, but does not open the picker.
 
 The component consumes the unified [`remotePlayback`](./feature-remote-playback.md) store feature alongside `CastButton`: both buttons drive their state from the same feature, but each only surfaces on its supported platform (WebKit for AirPlay, Chromium for Cast).
 
@@ -40,6 +40,18 @@ Current AirPlay session state
 
 Whether AirPlay is reachable on the current platform
 
+`data-disabled`
+
+Present / absent
+
+Present when the button is non-interactive
+
+`data-hidden`
+
+Present / absent
+
+Present on the HTML element while AirPlay is unavailable or unsupported
+
 Use `data-airplay-state` to swap icons or labels based on the session state:
 
 React renders a `<button>` element. Add a `className` and use it as the selector:
@@ -53,16 +65,19 @@ css
 }
 ```
 
-Consider hiding the button on platforms where AirPlay isn’t supported:
+Use `data-disabled` to style an explicitly disabled, available button:
 
 css
 
 ```
-.airplay-button[data-availability="unsupported"] {
-  display: none;
+.airplay-button[data-disabled] {
+  cursor: not-allowed;
+  opacity: 0.5;
 }
 ```
 
+Unavailable and unsupported buttons are hidden automatically. No availability selector or extra hiding CSS is required.
+
 ## Accessibility
 
 Renders a `<button>` with an automatic `aria-label`: “Start AirPlay” when disconnected, “Stop AirPlay” when connected. (The component also supports a `"Connecting"` label, but WebKit AirPlay never emits a `connecting` state, so that label is unreachable in practice.) Override with the `label` prop — either a string or a function that receives the current state. Keyboard activation: Enter / Space.
@@ -71,8 +86,6 @@ Renders a `<button>` with an automatic `aria-label`: “Start AirPlay” when di
 
 ### Basic Usage
 
-AirPlay not supported
-
 App.tsx
 
 App.css
@@ -87,26 +100,12 @@ 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
-        />
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
         <AirPlayButton
           className="media-airplay-button"
-          render={(props, state) => {
-            const label =
-              state.availability === 'unsupported'
-                ? 'AirPlay not supported'
-                : state.state === 'connected'
-                  ? 'Stop AirPlay'
-                  : state.availability === 'unavailable'
-                    ? 'No AirPlay devices found'
-                    : 'Start AirPlay';
-            return <button {...props}>{label}</button>;
-          }}
+          render={(props, state) => (
+            <button {...props}>{state.state === 'connected' ? 'Stop AirPlay' : 'Start AirPlay'}</button>
+          )}
         />
       </Player.Container>
     </Player.Provider>
@@ -136,9 +135,8 @@ export default function BasicUsage() {
   backdrop-filter: blur(10px);
 }
 
-/* Inactive states: the toggle is a no-op unless availability is "available". */
-.media-airplay-button[data-availability="unavailable"],
-.media-airplay-button[data-availability="unsupported"] {
+/* Explicitly disabled while AirPlay is available. */
+.media-airplay-button[data-disabled] {
   cursor: not-allowed;
   opacity: 0.5;
   filter: grayscale(1);
@@ -171,7 +169,7 @@ Whether the button is disabled.
 
 `label`
 
-`string | function`
+`Text | string | Text) | function`
 
 `''`
 
@@ -183,7 +181,7 @@ Custom label for the button.
 
 Type
 
-`string | ((state: AirPlayButtonState) => string)`
+`Text | string | ((state: AirPlayButtonState) => string | Text)`
 
 ### State
 
@@ -223,9 +221,29 @@ Type
 
 `'available' | 'unavailable' | 'unsupported'`
 
+`disabled`
+
+`boolean`
+
+▸
+
+Description
+
+Non-interactive but still focusable (mirrors `aria-disabled`).
+
+`hidden`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the button is hidden until AirPlay is available.
+
 `label`
 
-`string`
+`Text | string`
 
 ### Data attributes
 
@@ -261,4 +279,20 @@ Whether AirPlay is available on the active platform and media. @see [https://dev
 
 Type
 
-`'available' | 'unavailable' | 'unsupported'`
+`'available' | 'unavailable' | 'unsupported'`
+
+`data-disabled`
+
+▸
+
+Description
+
+Present when the button is non-interactive (mirrors `aria-disabled`).
+
+`data-hidden`
+
+▸
+
+Description
+
+Present when the button is hidden because AirPlay is unavailable.

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

@@ -9,16 +9,11 @@ Creates radio items from the player audio track state and selects the enabled tr
 tsx
 
 ```
-const audioTrack = useAudioTrackOptions();
-
-<Menu.RadioGroup value={audioTrack.value} onValueChange={audioTrack.setValue}>
-  <Menu.GroupLabel>Audio</Menu.GroupLabel>
-  {audioTrack.options.map((option) => (
-    <Menu.RadioItem key={option.value} value={option.value} disabled={option.disabled}>
-      {option.label}
-      <Menu.ItemIndicator checked={option.value === audioTrack.value} />
-    </Menu.RadioItem>
-  ))}
+<Menu.RadioGroup>
+  <Menu.GroupLabel />
+  <Menu.RadioItem>
+    <Menu.ItemIndicator />
+  </Menu.RadioItem>
 </Menu.RadioGroup>
 ```
 
@@ -26,7 +21,7 @@ const audioTrack = useAudioTrackOptions();
 
 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` returns `null` when the [audio track feature](./feature-audio-track.md) is not configured. Use the returned options with [`Menu.RadioGroup`](./menu.md).
+[`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).
 
 ## Styling
 
@@ -56,4 +51,144 @@ Whether multiple audio tracks are available.
 
 ## Accessibility
 
-The group uses the menu radio group pattern. It receives an accessible label from the `label` prop or defaults to `Audio`.
+The group uses the menu radio group pattern.
+
+Give `Menu.RadioGroup` an accessible name with `aria-label` or a nested `Menu.GroupLabel`.
+
+## Examples
+
+### Basic usage
+
+App.tsx
+
+App.css
+
+```
+import { createPlayer, Menu, useAudioTrackOptions } 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 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
+          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">
+                ✓
+              </Menu.ItemIndicator>
+            </Menu.RadioItem>
+          ))}
+        </Menu.RadioGroup>
+      </Menu.Content>
+    </Menu.Root>
+  );
+}
+
+export default function BasicUsage() {
+  return (
+    <Player.Provider>
+      <Player.Container className="media-container">
+        <HlsJsVideo src={src} autoPlay crossOrigin="anonymous" muted playsInline loop />
+        <div className="menu-bar">
+          <AudioMenu />
+        </div>
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.menu-bar {
+  position: absolute;
+  right: 10px;
+  bottom: 10px;
+}
+
+.settings-trigger {
+  padding: 6px 16px;
+  color: black;
+  cursor: pointer;
+  background: rgba(255, 255, 255, 0.75);
+  border: 1px solid rgba(255, 255, 255, 0.35);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+
+.menu {
+  --media-menu-side-offset: 8px;
+  box-sizing: border-box;
+  display: grid;
+  gap: 2px;
+  min-width: 180px;
+  max-width: var(--media-menu-available-width, var(--media-popover-available-width, none));
+  max-height: var(--media-menu-available-height, var(--media-popover-available-height, none));
+  padding: 6px;
+  margin: 0;
+  overflow: auto;
+  overscroll-behavior: none;
+  font-size: 14px;
+  color: white;
+  background: rgba(0, 0, 0, 0.88);
+  border: 0;
+  border-radius: 8px;
+  backdrop-filter: blur(10px);
+}
+
+.menu-group {
+  display: grid;
+  gap: 2px;
+}
+
+.menu-item {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  justify-content: space-between;
+  min-height: 32px;
+  padding: 0 10px;
+  font: inherit;
+  color: inherit;
+  cursor: pointer;
+  background: none;
+  border: 0;
+  border-radius: 6px;
+}
+
+.menu-item[data-highlighted] {
+  background: rgba(255, 255, 255, 0.16);
+}
+
+.menu-indicator {
+  opacity: 0;
+}
+
+[role="menuitemradio"][aria-checked="true"] .menu-indicator {
+  opacity: 1;
+}
+```

package/docs/reference/buffering-indicator.md

@@ -36,13 +36,7 @@ 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
-        />
+        <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>}

package/docs/reference/captions-button.md

@@ -12,9 +12,9 @@ tsx
 
 ## Behavior
 
-Toggles captions and subtitles on and off. The button checks the media’s text track list for tracks with `kind="captions"` or `kind="subtitles"` and reflects availability via `data-availability`.
+Toggles captions and subtitles on and off. The button checks the media’s text track list for tracks with `kind="captions"` or `kind="subtitles"`. When none are present, the HTML custom element receives the native `hidden` attribute and the React component returns `null`. The raw state remains available as `data-availability`.
 
-When no caption or subtitle tracks are present, `data-availability="unavailable"` is set. Use this to hide the button when there are no tracks to toggle.
+An explicitly disabled button with caption tracks stays visible and focusable with `aria-disabled="true"` and `data-disabled`, but does not toggle captions.
 
 When `menuTrigger` is enabled and multiple caption or subtitle tracks are available, activation opens the linked captions menu instead of toggling captions directly. React enables `menuTrigger` automatically when a `CaptionsButton` is rendered inside `Menu.Trigger`.
 
@@ -29,16 +29,19 @@ media-captions-button[data-active] .icon-on { display: inline; }
 media-captions-button:not([data-active]) .icon-off { display: inline; }
 ```
 
-Hide when no caption tracks are available:
+Style an explicitly disabled, available button:
 
 css
 
 ```
-media-captions-button[data-availability="unavailable"] {
-  display: none;
+media-captions-button[data-disabled] {
+  cursor: not-allowed;
+  opacity: 0.5;
 }
 ```
 
+The button hides automatically when no caption tracks are available. No availability selector or extra hiding CSS is required.
+
 ## Accessibility
 
 Renders a `<button>` with an automatic `aria-label`: “Disable captions” when active, “Enable captions” when inactive. Override with the `label` prop. Keyboard activation: Enter / Space.
@@ -49,8 +52,6 @@ In menu-trigger mode, the button behaves as a menu trigger and reflects menu sta
 
 ### Basic Usage
 
-Captions On
-
 App.tsx
 
 App.css
@@ -65,13 +66,7 @@ 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
-        >
+        <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>
         <CaptionsButton
@@ -135,7 +130,7 @@ Whether the button is disabled.
 
 `label`
 
-`string | function`
+`Text | string | Text) | function`
 
 `''`
 
@@ -147,7 +142,7 @@ Custom label for the button.
 
 Type
 
-`string | ((state: CaptionsButtonState) => string)`
+`Text | string | ((state: CaptionsButtonState) => string | Text)`
 
 `menuTrigger`
 
@@ -175,6 +170,32 @@ Details
 
 `'available' | 'unavailable'`
 
+▸
+
+Description
+
+Whether caption/subtitle tracks are present.
+
+`disabled`
+
+`boolean`
+
+▸
+
+Description
+
+Non-interactive but still focusable (mirrors `aria-disabled`).
+
+`hidden`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the button is hidden because no caption tracks are present.
+
 `subtitlesShowing`
 
 `boolean`
@@ -187,7 +208,7 @@ Whether captions/subtitles are currently enabled.
 
 `label`
 
-`string`
+`Text | string`
 
 ### Data attributes
 
@@ -213,4 +234,20 @@ Present when captions are enabled.
 
 Description
 
-Indicates captions availability (`available` or `unavailable`).
+Indicates captions availability (`available` or `unavailable`).
+
+`data-disabled`
+
+▸
+
+Description
+
+Present when the button is non-interactive (mirrors `aria-disabled`).
+
+`data-hidden`
+
+▸
+
+Description
+
+Present when the button is hidden because no caption tracks are present.

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

@@ -0,0 +1,195 @@
+# CaptionsRadioGroup
+
+A menu radio group for selecting caption and subtitle tracks
+
+Creates radio items from the player text track state and selects the showing caption or subtitle track.
+
+## Anatomy
+
+tsx
+
+```
+<Menu.RadioGroup>
+  <Menu.GroupLabel />
+  <Menu.RadioItem>
+    <Menu.ItemIndicator />
+  </Menu.RadioItem>
+</Menu.RadioGroup>
+```
+
+## 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).
+
+## Styling
+
+Attribute
+
+Values
+
+Description
+
+`data-active`
+
+Present / absent
+
+Present when captions are enabled.
+
+`data-disabled`
+
+Present / absent
+
+Present when track selection is disabled.
+
+`data-availability`
+
+`"available"` / `"unavailable"`
+
+Whether caption or subtitle tracks are available.
+
+## Accessibility
+
+The group uses the menu radio group pattern.
+
+Give `Menu.RadioGroup` an accessible name with `aria-label` or a nested `Menu.GroupLabel`.
+
+## Examples
+
+### Basic usage
+
+App.tsx
+
+App.css
+
+```
+import { createPlayer, Menu, useCaptionsOptions } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+import type { ReactNode } from 'react';
+
+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
+          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">
+                ✓
+              </Menu.ItemIndicator>
+            </Menu.RadioItem>
+          ))}
+        </Menu.RadioGroup>
+      </Menu.Content>
+    </Menu.Root>
+  );
+}
+
+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>
+          <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" />
+        </Video>
+        <div className="menu-bar">
+          <CaptionsMenu />
+        </div>
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.menu-bar {
+  position: absolute;
+  right: 10px;
+  bottom: 10px;
+}
+
+.settings-trigger {
+  padding: 6px 16px;
+  color: black;
+  cursor: pointer;
+  background: rgba(255, 255, 255, 0.75);
+  border: 1px solid rgba(255, 255, 255, 0.35);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+
+.menu {
+  --media-menu-side-offset: 8px;
+  box-sizing: border-box;
+  display: grid;
+  gap: 2px;
+  min-width: 180px;
+  max-width: var(--media-menu-available-width, var(--media-popover-available-width, none));
+  max-height: var(--media-menu-available-height, var(--media-popover-available-height, none));
+  padding: 6px;
+  margin: 0;
+  overflow: auto;
+  overscroll-behavior: none;
+  font-size: 14px;
+  color: white;
+  background: rgba(0, 0, 0, 0.88);
+  border: 0;
+  border-radius: 8px;
+  backdrop-filter: blur(10px);
+}
+
+.menu-group {
+  display: grid;
+  gap: 2px;
+}
+
+.menu-item {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  justify-content: space-between;
+  min-height: 32px;
+  padding: 0 10px;
+  font: inherit;
+  color: inherit;
+  cursor: pointer;
+  background: none;
+  border: 0;
+  border-radius: 6px;
+}
+
+.menu-item[data-highlighted] {
+  background: rgba(255, 255, 255, 0.16);
+}
+
+.menu-indicator {
+  opacity: 0;
+}
+
+[role="menuitemradio"][aria-checked="true"] .menu-indicator {
+  opacity: 1;
+}
+```