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

package/docs/reference/captions-button.md

@@ -12,9 +12,11 @@ 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`.
 
 ## Styling
 
@@ -27,26 +29,29 @@ 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.
 
+In menu-trigger mode, the button behaves as a menu trigger and reflects menu state through the trigger attributes.
+
 ## Examples
 
 ### Basic Usage
 
-Captions On
-
 App.tsx
 
 App.css
@@ -61,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
@@ -131,7 +130,7 @@ Whether the button is disabled.
 
 `label`
 
-`string | function`
+`Text | string | Text) | function`
 
 `''`
 
@@ -143,7 +142,19 @@ Custom label for the button.
 
 Type
 
-`string | ((state: CaptionsButtonState) => string)`
+`Text | string | ((state: CaptionsButtonState) => string | Text)`
+
+`menuTrigger`
+
+`boolean`
+
+`false`
+
+▸
+
+Description
+
+When true with multiple tracks, pointer activation opens a menu instead of toggling. React sets this automatically inside `Menu.Trigger`.
 
 ### State
 
@@ -159,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`
@@ -171,7 +208,7 @@ Whether captions/subtitles are currently enabled.
 
 `label`
 
-`string`
+`Text | string`
 
 ### Data attributes
 
@@ -197,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;
+}
+```

package/docs/reference/cast-button.md

@@ -0,0 +1,283 @@
+# CastButton
+
+Accessible Cast toggle button with state reflection and keyboard support
+
+## Anatomy
+
+tsx
+
+```
+<CastButton />
+```
+
+## Behavior
+
+Toggles a Google Cast session. Clicking the button while `disconnected` opens the Cast device picker; clicking while `connected` ends the session.
+
+The button derives its presentation from `availability`:
+
+*   **`"unsupported"`** — the HTML custom element receives the native `hidden` attribute; the React component returns `null`.
+*   **`"unavailable"`** — the button remains visible and focusable with `aria-disabled="true"` and `data-disabled`, but does not open the picker. This lets a tooltip explain that no Cast device is reachable.
+*   **`"available"`** — the button is fully interactive unless the `disabled` prop is set.
+
+Cast sessions come from the [Google Cast](../concepts/cast.md) component. Add it to the player next to your media element; without it the button drives the browser’s native Remote Playback API instead, which offers no receiver or load-request configuration.
+
+## Styling
+
+Style based on cast and disabled state:
+
+React renders a `<button>` element. Add a `className` to style it:
+
+css
+
+```
+/* During an active session */
+.cast-button[data-cast-state="connected"] {
+  color: blue;
+}
+
+/* Cast is supported, but no device is reachable */
+.cast-button[data-disabled] {
+  cursor: not-allowed;
+  opacity: 0.5;
+}
+```
+
+Unsupported buttons are hidden automatically. No availability selector or extra hiding CSS is required.
+
+## Accessibility
+
+Renders a `<button>` with an automatic `aria-label`:
+
+Cast state
+
+Default label
+
+`'disconnected'`
+
+“Start casting”
+
+`'connecting'`
+
+“Connecting”
+
+`'connected'`
+
+“Stop casting”
+
+Override with the `label` prop. Keyboard activation: Enter / Space.
+
+## Examples
+
+### Basic Usage
+
+App.tsx
+
+App.css
+
+```
+import { CastButton, createPlayer } from '@videojs/react';
+import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
+import { videoFeatures } from '@videojs/react/video';
+
+const Player = createPlayer({ features: videoFeatures });
+
+export default function BasicUsage() {
+  return (
+    <Player.Provider>
+      <Player.Container className="media-container">
+        <HlsJsVideo src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" autoPlay muted playsInline loop />
+        <CastButton
+          className="media-cast-button"
+          render={(props, state) => (
+            <button {...props}>{state.connection === 'connected' ? 'Stop casting' : 'Start casting'}</button>
+          )}
+        />
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.media-cast-button {
+  position: absolute;
+  right: 10px;
+  bottom: 10px;
+  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);
+}
+
+.media-cast-button[data-disabled] {
+  cursor: not-allowed;
+  opacity: 0.5;
+  filter: grayscale(1);
+}
+```
+
+## API Reference
+
+### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`disabled`
+
+`boolean`
+
+`false`
+
+▸
+
+Description
+
+Whether the button is disabled.
+
+`label`
+
+`Text | string | Text) | function`
+
+`''`
+
+▸
+
+Description
+
+Custom label for the button.
+
+Type
+
+`Text | string | ((state: CastButtonState) => string | Text)`
+
+### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+Property
+
+Type
+
+Details
+
+`connection`
+
+`'disconnected' | 'connecting' | 'conn...`
+
+▸
+
+Description
+
+Current cast connection state (`disconnected`, `connecting`, or `connected`).
+
+Type
+
+`'disconnected' | 'connecting' | 'connected'`
+
+`availability`
+
+`'available' | 'unavailable' | 'unsupp...`
+
+▸
+
+Description
+
+Whether casting is `available` (a device is reachable), `unavailable` (no device), or `unsupported`.
+
+Type
+
+`'available' | 'unavailable' | 'unsupported'`
+
+`disabled`
+
+`boolean`
+
+▸
+
+Description
+
+Non-interactive but still focusable (mirrors `aria-disabled`).
+
+`hidden`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the button is hidden because the feature is unsupported.
+
+`label`
+
+`Text | string`
+
+### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-cast-state`
+
+`'disconnected' | 'connecting' | 'conn...`
+
+▸
+
+Description
+
+Current remote playback connection state. @see [https://developer.mozilla.org/en-US/docs/Web/API/RemotePlayback/state](https://developer.mozilla.org/en-US/docs/Web/API/RemotePlayback/state)
+
+Type
+
+`'disconnected' | 'connecting' | 'connected'`
+
+`data-availability`
+
+`'available' | 'unavailable' | 'unsupp...`
+
+▸
+
+Description
+
+Whether remote playback can be requested on this platform. @see [https://developer.mozilla.org/en-US/docs/Web/API/RemotePlayback](https://developer.mozilla.org/en-US/docs/Web/API/RemotePlayback)
+
+Type
+
+`'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 the feature is unsupported.

package/docs/reference/controls.md

@@ -72,13 +72,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 />
 
         <Controls.Root className="media-controls">
           <Controls.Group className="controls-group" aria-label="Playback controls">