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

package/docs/reference/native-hls-video.md

@@ -16,16 +16,7 @@ App.css
 import { NativeHlsVideo } from '@videojs/react/media/native-hls-video';
 
 export default function BasicUsage() {
-  return (
-    <NativeHlsVideo
-      className="native-hls-video"
-      src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"
-      autoPlay
-      muted
-      playsInline
-      loop
-    />
-  );
+  return <NativeHlsVideo className="native-hls-video" src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" autoPlay muted playsInline loop />;
 }
 ```
 ```
@@ -37,9 +28,11 @@ export default function BasicUsage() {
 
 ## API Reference
 
-### Host Properties
+### Props
 
-Property
+Accepts the standard React props for a native `<video>`, plus these Video.js-specific props:
+
+Prop
 
 Type
 
@@ -47,42 +40,6 @@ Default
 
 Details
 
-`engine`
-
-`null`
-
-`—`
-
-▸
-
-Description
-
-Read-only. Underlying playback engine — always `null`. Native HLS has no JS engine; the browser handles playback directly.
-
-`error`
-
-`MediaError | null`
-
-`—`
-
-▸
-
-Description
-
-Read-only.
-
-`liveEdgeStart`
-
-`number`
-
-`—`
-
-▸
-
-Description
-
-Read-only. Presentation time marking the start of the Live Edge Window. Derived on each read from the current `seekable.end` and cached offset; `NaN` when the stream is not live or the offset is unavailable.
-
 `preload`
 
 `PreloadType`
@@ -113,100 +70,10 @@ Description
 
 Current stream type (`'on-demand'` / `'live'` / `'unknown'`).
 
-`targetLiveWindow`
-
-`number`
-
-`—`
-
-▸
-
-Description
-
-Read-only. Seekable range size for live content. `0` for standard live, `Infinity` for DVR, `NaN` for on-demand or unknown.
-
-### Attributes
+### Ref
 
-Renders a native `<video>` element and accepts these media attributes as React props. The standard ones behave as described in the [MDN media attributes reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video): `autopictureinpicture``autoPlay``controls``controlslist``crossOrigin``disablepictureinpicture``disableremoteplayback``loading``loop``muted``playsInline``poster``preload``src``stream-type`
+Forwards its ref to the rendered `<video>`. The ref is an [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) and exposes its complete native property and method API.
 
 ### Events
 
-Handle these media events with React event props (e.g. `onPlay`, `onTimeUpdate`). See [media events](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement#events): `abort``canplay``canplaythrough``durationchange``emptied``ended``error``loadeddata``loadedmetadata``loadstart``pause``play``playing``progress``ratechange``resize``seeked``seeking``stalled``suspend``timeupdate``volumechange``waiting`
-
-These media events have no React prop — attach a listener through a `ref` with `addEventListener`: `addtrack``change``enterpictureinpicture``leavepictureinpicture``removetrack`
-
-Beyond the media events above, this element emits:
-
-Event
-
-Description
-
-`streamtypechange`
-
-Fired when the detected stream type changes. Read \`streamType\` for the new value.
-
-`targetlivewindowchange`
-
-Fired when the target live window changes. Read \`targetLiveWindow\` for the new value.
-
-These events have no built-in React prop. Attach a listener to the element through a `ref` with `addEventListener`.
-
-### Methods
-
-Supports these methods from the native media API. See [HTMLMediaElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement) for the core methods: `addTextTrack``canPlayType``exitFullscreen``exitPictureInPicture``load``pause``play``requestFullscreen``requestPictureInPicture`
-
-In React, call these through a `ref` to the element.
-
-### CSS Custom Properties
-
-Variable
-
-Details
-
-`--media-video-border-radius`
-
-▸
-
-Description
-
-Border radius of the video element.
-
-`--media-object-fit`
-
-▸
-
-Description
-
-Object fit for the video.
-
-`--media-object-position`
-
-▸
-
-Description
-
-Object position for the video.
-
-`--media-caption-track-duration`
-
-▸
-
-Description
-
-Duration of the caption track transition.
-
-`--media-caption-track-delay`
-
-▸
-
-Description
-
-Delay before the caption track transition.
-
-`--media-caption-track-y`
-
-▸
-
-Description
-
-Vertical offset of the caption track.
+Handle standard media events with React event props such as `onPlay` and `onTimeUpdate`. For native events without a React prop, attach a listener through the ref with `addEventListener`.

package/docs/reference/on-i18n-registry-change.md

@@ -0,0 +1,49 @@
+# onI18nRegistryChange
+
+Subscribe to global i18n registry mutations
+
+`onI18nRegistryChange` registers a callback that runs whenever any locale layer changes, for example after `registerI18n` or browser translation prefetch. Returns an unsubscribe function.
+
+React `I18nProvider` uses this to invalidate translators when the registry updates.
+
+## API Reference
+
+### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`callback*`
+
+`function`
+
+`—`
+
+▸
+
+Description
+
+Invoked when any locale layer changes.
+
+Type
+
+`(() => void)`
+
+### Return Value
+
+Type
+
+Details
+
+`function`
+
+▸
+
+Type
+
+`(() => void)`

package/docs/reference/pip-button.md

@@ -12,7 +12,10 @@ tsx
 
 ## Behavior
 
-Toggles picture-in-picture (PiP) mode. Detects platform support through `availability` — when PiP is `"unsupported"`, the toggle does nothing.
+Toggles picture-in-picture (PiP) mode. The button derives two state hooks from `availability`:
+
+*   **`disabled`** (`true` until PiP is available, or when the `disabled` prop is set) — sets `aria-disabled="true"` and `data-disabled`. A prop-disabled, available button stays focusable but does not activate.
+*   **`hidden`** (`true` while PiP is `"unavailable"` or `"unsupported"`) — applies the native HTML `hidden` attribute on the custom element; the React component returns `null`.
 
 ## Styling
 
@@ -27,18 +30,16 @@ css
 .pip-button[data-pip] {
   background: red;
 }
-```
-
-Consider hiding the button when unsupported:
-
-css
 
-```
-.pip-button[data-availability="unsupported"] {
-  display: none;
+/* Non-interactive (disabled prop) */
+.pip-button[data-disabled] {
+  opacity: 0.5;
+  cursor: not-allowed;
 }
 ```
 
+The button remains hidden until picture-in-picture is available. The HTML element receives the native `hidden` attribute, and the React component returns `null`. No extra CSS is required.
+
 ## Accessibility
 
 Renders a `<button>` with an automatic `aria-label`: “Enter PiP” or “Exit PiP”. Override with the `label` prop. Keyboard activation: Enter / Space.
@@ -47,8 +48,6 @@ Renders a `<button>` with an automatic `aria-label`: “Enter PiP” or “Exit
 
 ### Basic Usage
 
-Enter PiP
-
 App.tsx
 
 App.css
@@ -63,13 +62,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 />
         <PiPButton
           className="media-pip-button"
           render={(props, state) => <button {...props}>{state.pip ? 'Exit PiP' : 'Enter PiP'}</button>}
@@ -129,7 +122,7 @@ Whether the button is disabled.
 
 `label`
 
-`string | function`
+`Text | string | Text) | function`
 
 `''`
 
@@ -141,7 +134,7 @@ Custom label for the button.
 
 Type
 
-`string | ((state: PiPButtonState) => string)`
+`Text | string | ((state: PiPButtonState) => string | Text)`
 
 ### State
 
@@ -167,6 +160,26 @@ Type
 
 `'available' | 'unavailable' | 'unsupported'`
 
+`disabled`
+
+`boolean`
+
+▸
+
+Description
+
+Non-interactive but still focusable (mirrors `aria-disabled`).
+
+`hidden`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the button is hidden until picture-in-picture is available.
+
 `pip`
 
 `boolean`
@@ -179,7 +192,7 @@ Whether picture-in-picture mode is currently active.
 
 `label`
 
-`string`
+`Text | string`
 
 ### Data attributes
 
@@ -205,8 +218,24 @@ Present when picture-in-picture mode is active.
 
 Description
 
-Indicates picture-in-picture availability (`available` or `unsupported`).
+Indicates picture-in-picture availability (`available`, `unavailable`, `unsupported`).
 
 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 picture-in-picture is not available.

package/docs/reference/play-button.md

@@ -44,7 +44,7 @@ css
 
 ## Accessibility
 
-Renders a `<button>` element with an automatic `aria-label` that updates based on state: “Play”, “Pause”, or “Replay”. Override with the `label` prop (accepts a string or function). Keyboard activation: Enter / Space.
+Renders a `<button>` element with an automatic `aria-label` that updates based on state: “Play”, “Pause”, or “Replay”. 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: 'buttons.play', text: 'Play video' }`. Keyboard activation: Enter / Space.
 
 ## Examples
 
@@ -66,12 +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
-        />
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline />
         <PlayButton
           className="media-play-button"
           render={(props, state) => (
@@ -133,7 +128,7 @@ Whether the button is disabled.
 
 `label`
 
-`string | function`
+`Text | string | Text) | function`
 
 `''`
 
@@ -145,7 +140,7 @@ Custom label for the button.
 
 Type
 
-`string | ((state: PlayButtonState) => string)`
+`Text | string | ((state: PlayButtonState) => string | Text)`
 
 ### State
 
@@ -189,7 +184,7 @@ Whether playback has started (played or seeked).
 
 `label`
 
-`string`
+`Text | string`
 
 ### Data attributes
 

package/docs/reference/playback-rate-button.md

@@ -56,13 +56,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 />
         <PlaybackRateButton
           className="media-playback-rate-button"
           render={(props, state) => <button {...props}>{Math.round(state.rate * 10) / 10}&times;</button>}
@@ -122,7 +116,7 @@ Whether the button is disabled.
 
 `label`
 
-`string | function`
+`Text | string | Text) | function`
 
 `''`
 
@@ -134,7 +128,7 @@ Custom label for the button.
 
 Type
 
-`string | ((state: PlaybackRateButtonState) => string)`
+`Text | string | ((state: PlaybackRateButtonState) => string | Text)`
 
 `menuTrigger`
 
@@ -164,7 +158,7 @@ Details
 
 `label`
 
-`string`
+`Text | string`
 
 ### Data attributes
 

package/docs/reference/playback-rate-radio-group.md

@@ -0,0 +1,194 @@
+# PlaybackRateRadioGroup
+
+A menu radio group for selecting playback speed
+
+Creates radio items from the player playback rate state and selects the playback speed.
+
+## Anatomy
+
+tsx
+
+```
+<Menu.RadioGroup>
+  <Menu.GroupLabel />
+  <Menu.RadioItem>
+    <Menu.ItemIndicator />
+  </Menu.RadioItem>
+</Menu.RadioGroup>
+```
+
+## Behavior
+
+The group is available when the configured media exposes playback rates. Option labels default to the rate followed by a multiplication sign (e.g. `1.5×`); pass `formatRate` to customize them.
+
+[`usePlaybackRateOptions`](./use-playback-rate-options.md) returns `null` when the [playback rate feature](./feature-playback-rate.md) is not configured. Use the returned options with [`Menu.RadioGroup`](./menu.md).
+
+## Styling
+
+Attribute
+
+Values
+
+Description
+
+`data-rate`
+
+`number`
+
+Current playback rate.
+
+`data-disabled`
+
+Present / absent
+
+Present when playback rate selection is disabled.
+
+`data-availability`
+
+`"available"` / `"unavailable"`
+
+Whether playback rates 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
+
+Speed
+
+App.tsx
+
+App.css
+
+```
+import { createPlayer, Menu, usePlaybackRateOptions } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+import type { ReactNode } from 'react';
+
+const Player = createPlayer({ features: videoFeatures });
+
+function SpeedMenu(): ReactNode {
+  const playbackRate = usePlaybackRateOptions();
+  if (playbackRate?.state.availability !== 'available') return null;
+
+  return (
+    <Menu.Root side="top" align="end">
+      <Menu.Trigger className="settings-trigger" render={<button type="button" />}>
+        Speed
+      </Menu.Trigger>
+      <Menu.Content className="menu">
+        <Menu.RadioGroup
+          className="menu-group"
+          value={playbackRate.value}
+          onValueChange={playbackRate.setValue}
+          aria-label="Speed"
+        >
+          {playbackRate.options.map((option) => (
+            <Menu.RadioItem key={option.value} value={option.value} disabled={option.disabled} className="menu-item">
+              {option.label}
+              <Menu.ItemIndicator checked={option.value === playbackRate.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 />
+        <div className="menu-bar">
+          <SpeedMenu />
+        </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;
+}
+```