@videojs/react 10.0.0-rc.1 → 10.0.0-rc.2

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

@@ -9,7 +9,7 @@ Creates radio items from the player text track state and selects the showing cap
 tsx
 
 ```
-import { CaptionsRadioGroup } from '@videojs/react';
+import { CaptionsRadioGroup } from '@videojs/react/ui/captions-radio-group';
 ```
 
 ## Anatomy
@@ -17,21 +17,30 @@ import { CaptionsRadioGroup } from '@videojs/react';
 tsx
 
 ```
-<CaptionsRadioGroup
-  renderItem={(props, item) => (
-    <Menu.RadioItem {...props}>
-      {item.label}
-      <Menu.ItemIndicator checked={item.checked} />
-    </Menu.RadioItem>
-  )}
-/>
+<CaptionsRadioGroup.Root>
+  <Menu.Trigger>
+    <CaptionsRadioGroup.Value />
+  </Menu.Trigger>
+  <Menu.Content>
+    <CaptionsRadioGroup.Options
+      renderItem={(props, item) => (
+        <Menu.RadioItem {...props}>
+          {item.label}
+          <Menu.ItemIndicator checked={item.checked} />
+        </Menu.RadioItem>
+      )}
+    />
+  </Menu.Content>
+</CaptionsRadioGroup.Root>
 ```
 
 ## 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.
+`CaptionsRadioGroup.Root` uses [`useCaptionsOptions`](./use-captions-options.md) to own selection and renders no element. Wrap the menu’s `Menu.Trigger` and `Menu.Content` in it so the trigger inherits the group’s disabled and hidden state and exposes `data-availability`. `CaptionsRadioGroup.Options` renders the items, 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. `CaptionsRadioGroup.Value` displays the selected label, typically inside the trigger. `Options` and `Value` render `null` when the [text tracks feature](./feature-text-tracks.md) is not configured.
+
+The `CaptionsRadioGroup` export from the `@videojs/react` root is a compatibility component that composes `Root` and `Options` behind the former single-component props. Prefer the parts for new code.
 
 ## Styling
 
@@ -71,20 +80,21 @@ Unavailable groups receive the native `hidden` attribute.
 
 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`.
+`CaptionsRadioGroup.Options` receives its accessible label from the `label` prop on `CaptionsRadioGroup.Root` or defaults to `Captions`. Override it with `aria-label` or `aria-labelledby` on `CaptionsRadioGroup.Options`.
 
 ## Examples
 
 ### Basic usage
 
-Captions
+CaptionsOff
 
 App.tsx
 
 App.css
 
 ```
-import { CaptionsRadioGroup, Container, createPlayer, Menu } from '@videojs/react';
+import { Container, createPlayer, Menu } from '@videojs/react';
+import { CaptionsRadioGroup } from '@videojs/react/ui/captions-radio-group';
 import { Video, videoFeatures } from '@videojs/react/video';
 import type { ReactNode } from 'react';
 
@@ -93,24 +103,27 @@ 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.Popup className="menu">
-        <Menu.Content>
-          <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.Popup>
+      <CaptionsRadioGroup.Root>
+        <Menu.Trigger className="settings-trigger" render={<button type="button" />}>
+          Captions
+          <CaptionsRadioGroup.Value className="menu-hint" />
+        </Menu.Trigger>
+        <Menu.Popup className="menu">
+          <Menu.Content>
+            <CaptionsRadioGroup.Options
+              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.Popup>
+      </CaptionsRadioGroup.Root>
     </Menu.Root>
   );
 }
@@ -156,6 +169,15 @@ export default function BasicUsage() {
   backdrop-filter: blur(10px);
 }
 
+.menu-hint {
+  margin-left: 8px;
+  color: rgba(0, 0, 0, 0.6);
+}
+
+.menu-hint:empty {
+  display: none;
+}
+
 .menu {
   --media-menu-side-offset: 8px;
   box-sizing: border-box;
@@ -213,6 +235,246 @@ export default function BasicUsage() {
 
 ### 
 
+Root
+
+Owns captions option state and shares it with an enclosing menu. Does not render a DOM element.
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`disabled`
+
+`boolean`
+
+`false`
+
+▸
+
+Description
+
+Whether track selection is disabled.
+
+`formatTrack`
+
+`string) | function`
+
+`formatTrackLabel`
+
+▸
+
+Description
+
+Custom formatter for visible track labels.
+
+Type
+
+`((track: MediaTextTrack) => Text | string)`
+
+`label`
+
+`object`
+
+`''`
+
+▸
+
+Description
+
+Custom label for the options group.
+
+Type
+
+`{ key: string; text: string } | string | ((state: CaptionsRadioGroupState) => Text | string)`
+
+#### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+Property
+
+Type
+
+Details
+
+`subtitlesShowing`
+
+`boolean`
+
+▸
+
+Description
+
+Whether captions/subtitles are currently enabled.
+
+`label`
+
+`{ key: string; text: string } | string`
+
+`value`
+
+`string`
+
+▸
+
+Description
+
+Current radio-group value.
+
+`options`
+
+`readonly Option[]`
+
+▸
+
+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.
+
+#### 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`).
+
+### 
+
+Options
+
+Renders menu radio items for the player's captions and subtitles tracks.
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`className`
+
+`string | ((state: CaptionsRadioGroupCore.State) => string | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Class name or function returning class name from state.
+
+`render`
+
+`ReactElement | ((props: HTMLProps, state: CaptionsRadioGroupCore.State) => ReactElement | null)`
+
+`—`
+
+▸
+
+Description
+
+Render prop for custom element.
+
+`renderItem`
+
+`((props: CaptionsRadioGroupItemProps, state: CaptionsRadioGroupItemState) => ReactElement)`
+
+`—`
+
+▸
+
+Description
+
+Render one consumer-owned menu radio item for every captions option.
+
+`style`
+
+`CSSProperties | ((state: CaptionsRadioGroupCore.State) => CSSProperties | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Style or function returning style from state.
+
+### 
+
 Value
 
 Displays the selected captions label.

package/docs/reference/controls.md

@@ -31,6 +31,16 @@ If the user is active, or if the video is paused, this component will show contr
 
 User activity is tracked via pointer movement, keyboard input, and focus events on the player container. On touch devices, a quick tap toggles visibility. `mouseleave` immediately sets the user as inactive.
 
+`visibility` selects between the two modes. The default, `auto`, follows the player’s controls visibility state as described above. `always` keeps the controls visible and reports the user as active regardless of playback or idle state, and works without the controls feature. The idle delay itself is not configurable.
+
+tsx
+
+```
+<Controls.Root visibility="always">
+  <Controls.Content>...</Controls.Content>
+</Controls.Root>
+```
+
 ## Styling
 
 `Controls.Root` is a state and context provider. `Controls.Content` / `<media-controls-content>` renders the interactive controls surface and receives its DOM props, ref, and controls state data attributes.

package/docs/reference/error-dialog.md

@@ -52,7 +52,11 @@ css
 
 ## Accessibility
 
-The popup uses `role="alertdialog"` and `aria-modal="true"`. Its title and description are connected with `aria-labelledby` and `aria-describedby`. Focus stays within the popup and content outside it is inert while the error is open. Pressing Escape or activating the close part dismisses the error.
+The popup uses `role="alertdialog"`. Its title and description are connected with `aria-labelledby` and `aria-describedby`.
+
+Modality is scoped to the player container rather than the page. While the error is open, the rest of the container is inert and focus that lands elsewhere inside it returns to the popup, but content outside the player stays interactive and `aria-modal` is omitted. Only when the popup renders outside the container does the dialog fall back to document-wide modality: `aria-modal="true"`, Tab cycling within the popup, and everything outside it inert.
+
+Pressing Escape or activating the close part dismisses the error.
 
 ## Examples
 

package/docs/reference/live-button.md

@@ -22,6 +22,8 @@ tsx
 
 LiveButton indicates whether playback is at the live edge and acts as a “go to live” control. While playback is behind the edge, clicking seeks to the live edge — the end of the last `seekable` range. At the edge the button goes inactive (`aria-disabled`) and clicking is a no-op.
 
+The button is also disabled whenever it has no live edge to seek to: the media is not live, the `seekable` ranges are still empty (before metadata loads, for example), or the last range ends at `Infinity`. It reports `disabled` in its state, sets `data-disabled`, and ignores activation until a seek target exists. Passing `disabled` forces the same state.
+
 The button combines three player features: [live](./feature-live.md) for `liveEdgeStart` and `targetLiveWindow`, [time](./feature-time.md) for `currentTime` and the `seek()` action, and [buffer](./feature-buffer.md) for `seekable`. All three are included in the `liveVideoFeatures` and `liveAudioFeatures` presets, and the packaged live skins include the button.
 
 Media counts as live while `targetLiveWindow` is not `NaN`. That value is how far behind the live edge viewers can seek: `0` means the stream is watchable only at the edge, and `Infinity` means the stream keeps its recording seekable so viewers can rewind and catch up, like a DVR. For on-demand media the button reports neither `live` nor `liveEdge` and stays inert.
@@ -52,7 +54,13 @@ Present / absent
 
 Present when playback is at the live edge
 
-Use `data-live-edge` to color the button red at the edge and gray behind it:
+`data-disabled`
+
+Present / absent
+
+Present when the button is non-interactive (mirrors `aria-disabled`)
+
+Use `data-live-edge` to color the button red at the edge and gray behind it, and `data-disabled` to fade it while no live-edge target is available:
 
 React renders a `<button>` element with the same data attributes. Add a `className` and use it as the selector:
 
@@ -61,11 +69,12 @@ css
 ```
 .live-button { color: gray; }
 .live-button[data-live-edge] { color: red; }
+.live-button[data-disabled] { opacity: 0.5; }
 ```
 
 ## Accessibility
 
-Renders a `<button>` with an automatic `aria-label` that updates based on state: “Playing live” at the live edge, “Seek to live edge” while behind it. Override with the `label` prop, which accepts a text descriptor, literal string, or function returning either. A text descriptor contains an opaque translation key and English fallback, for example `{ key: 'live.playing', text: 'Playing live' }`. When the button is disabled or playback is at the live edge, `aria-disabled="true"` is set. Keyboard activation: Enter / Space.
+Renders a `<button>` with an automatic `aria-label` that updates based on state: “Playing live” at the live edge, “Seek to live edge” while behind it. Override with the `label` prop, which accepts a text descriptor, literal string, or function returning either. A text descriptor contains an opaque translation key and English fallback, for example `{ key: 'live.playing', text: 'Playing live' }`. When the button is disabled — explicitly, or because no live-edge seek target is available yet — or playback is at the live edge, `aria-disabled="true"` is set and activation is ignored. Keyboard activation: Enter / Space.
 
 ## Examples
 
@@ -228,6 +237,16 @@ Description
 
 Whether playback is at the live edge.
 
+`disabled`
+
+`boolean`
+
+▸
+
+Description
+
+Whether seeking to the live edge is temporarily unavailable.
+
 ### Data attributes
 
 Attribute
@@ -250,4 +269,12 @@ Present when the stream is live (or DVR).
 
 Description
 
-Present when playback is at the live edge.
+Present when playback is at the live edge.
+
+`data-disabled`
+
+▸
+
+Description
+
+Present when the button is non-interactive (mirrors `aria-disabled`).

package/docs/reference/menu.md

@@ -58,7 +58,25 @@ Root menus inside a [Container](./player-container.md) join its popup group. Ope
 
 In React, create a submenu by nesting another `Menu.Root` in the parent `Menu.Content`; its `Menu.Trigger` behaves as a parent item and its `Menu.Content` becomes the active Content. In HTML, add another `<media-menu-content>` as a sibling, give it an `id`, and point the parent `<media-menu-item>` at it with `commandfor`.
 
-Media option groups can render the current selection beside a submenu trigger. See [PlaybackRateRadioGroup](./playback-rate-radio-group.md), [QualityRadioGroup](./quality-radio-group.md), [AudioTrackRadioGroup](./audio-track-radio-group.md), and [CaptionsRadioGroup](./captions-radio-group.md).
+Media option groups share their option state with the enclosing menu: the selected value, and whether the options are disabled, hidden, or available. The menu’s trigger inherits the disabled and hidden state and exposes `data-availability`, and the menu closes if its options disappear while open. See [PlaybackRateRadioGroup](./playback-rate-radio-group.md), [QualityRadioGroup](./quality-radio-group.md), [AudioTrackRadioGroup](./audio-track-radio-group.md), and [CaptionsRadioGroup](./captions-radio-group.md).
+
+Wrap a submenu’s `Menu.Trigger` and `Menu.Content` in the group’s `Root` part, and render its `Value` part inside the trigger to show the current selection:
+
+tsx
+
+```
+<Menu.Root>
+  <QualityRadioGroup.Root>
+    <Menu.Trigger>
+      Quality
+      <QualityRadioGroup.Value />
+    </Menu.Trigger>
+    <Menu.Content>
+      <QualityRadioGroup.Options renderItem={...} />
+    </Menu.Content>
+  </QualityRadioGroup.Root>
+</Menu.Root>
+```
 
 ## Styling