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

package/docs/reference/buffering-indicator.md

@@ -27,28 +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">
-        <Video
-          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
-          autoPlay
-          muted
-          playsInline
-          loop
-        />
+    <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

@@ -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,29 +52,21 @@ In menu-trigger mode, the button behaves as a menu trigger and reflects menu sta
 
 ### Basic Usage
 
-Captions On
-
 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">
-        <Video
-          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
-          autoPlay
-          muted
-          playsInline
-          loop
-        >
+    <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>
         <CaptionsButton
@@ -80,8 +75,8 @@ export default function BasicUsage() {
             <button {...props}>{state.subtitlesShowing ? 'Captions Off' : 'Captions On'}</button>
           )}
         />
-      </Player.Container>
-    </Player.Provider>
+      </Container>
+    </Player>
   );
 }
 ```
@@ -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,372 @@
+# 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
+
+```
+<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.
+
+`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
+
+Attribute
+
+Values
+
+Description
+
+`data-active`
+
+Present / absent
+
+Present when captions are enabled.
+
+`data-disabled`
+
+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.
+
+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 { CaptionsRadioGroup, Container, createPlayer, Menu } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+import type { ReactNode } from 'react';
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+function CaptionsMenu(): ReactNode {
+  return (
+    <Menu.Root side="top" align="end">
+      <Menu.Trigger className="settings-trigger" render={<button type="button" />}>
+        Captions
+      </Menu.Trigger>
+      <Menu.Content className="menu">
+        <CaptionsRadioGroup
+          className="menu-group"
+          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.Content>
+    </Menu.Root>
+  );
+}
+
+export default function BasicUsage() {
+  return (
+    <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>
+      </Container>
+    </Player>
+  );
+}
+```
+```
+.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;
+}
+```
+
+## 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`).