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

package/docs/reference/popover.md

@@ -22,7 +22,7 @@ Displays contextual content anchored to a trigger element. By default, opens on
 
 Set `openOnHover` to open on pointer hover instead of click. Use `delay` and `closeDelay` to control timing for hover interactions.
 
-The `side` and `align` props control popup placement relative to the trigger. The popup repositions automatically to stay within viewport bounds.
+The `side` and `align` props control the preferred popup placement relative to the trigger. When the preferred side overflows the positioning boundary, the popup uses the opposite side if it has more space.
 
 In React, the component is composed from four parts: `Root` manages state, `Trigger` toggles the popover, `Popup` contains the content, and `Arrow` renders a directional arrow.
 
@@ -38,10 +38,11 @@ css
 .popover {
   --media-popover-side-offset: 8px;
   --media-popover-align-offset: 0px;
+  --media-popover-boundary-offset: 8px;
 }
 ```
 
-Style based on open state and transition phases:
+Style based on open state, rendered side, and transition phases. `data-side` reflects the rendered side and can differ from the preferred `side` prop after collision handling:
 
 css
 
@@ -55,6 +56,12 @@ css
 .popover[data-ending-style] .popup {
   opacity: 0;
 }
+.popover[data-side="top"] {
+  transform-origin: bottom center;
+}
+.popover[data-side="bottom"] {
+  transform-origin: top center;
+}
 ```
 
 ## Accessibility
@@ -81,13 +88,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 />
         <div className="bar">
           <Popover.Root>
             <Popover.Trigger className="trigger">Settings</Popover.Trigger>
@@ -286,7 +287,7 @@ Open the popup on pointer hover instead of click.
 
 Description
 
-Which side of the trigger the popup appears on.
+Preferred side of the trigger for the popup.
 
 #### State
 
@@ -310,6 +311,12 @@ Details
 
 `'top' | 'bottom' | 'left' | 'right'`
 
+▸
+
+Description
+
+Preferred side of the trigger for the popup.
+
 `align`
 
 `'start' | 'center' | 'end'`
@@ -362,7 +369,7 @@ Present when the popover is open.
 
 Description
 
-Indicates which side the popover is positioned relative to the trigger.
+Indicates the rendered side of the popover after collision handling.
 
 `data-align`
 
@@ -472,7 +479,7 @@ Present when the popover is open.
 
 Description
 
-Indicates which side the popover is positioned relative to the trigger.
+Indicates the rendered side of the popover after collision handling.
 
 `data-align`
 
@@ -514,7 +521,7 @@ Present when the popover is open.
 
 Description
 
-Indicates which side the popover is positioned relative to the trigger.
+Indicates the rendered side of the popover after collision handling.
 
 `data-align`
 

package/docs/reference/poster.md

@@ -58,10 +58,7 @@ export default function BasicUsage() {
       <Player.Container className="media-container">
         <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" playsInline />
 
-        <Poster
-          className="media-poster"
-          src="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg"
-        />
+        <Poster className="media-poster" src="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg" />
 
         <PlayButton
           className="media-play-button"

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

@@ -9,16 +9,11 @@ Creates radio items from the player video rendition state and selects automatic
 tsx
 
 ```
-const quality = useQualityOptions();
-
-<Menu.RadioGroup value={quality.value} onValueChange={quality.setValue}>
-  <Menu.GroupLabel>Quality</Menu.GroupLabel>
-  {quality.options.map((option) => (
-    <Menu.RadioItem key={option.value} value={option.value} disabled={option.disabled}>
-      {option.label}
-      <Menu.ItemIndicator checked={option.value === quality.value} />
-    </Menu.RadioItem>
-  ))}
+<Menu.RadioGroup>
+  <Menu.GroupLabel />
+  <Menu.RadioItem>
+    <Menu.ItemIndicator />
+  </Menu.RadioItem>
 </Menu.RadioGroup>
 ```
 
@@ -26,7 +21,7 @@ const quality = useQualityOptions();
 
 The group is available when the configured media exposes more than one video rendition. The first generated option is `Auto`; selecting it returns control to adaptive bitrate selection. Pass `formatRendition` to customize visible rendition labels.
 
-`useQualityOptions` returns `null` when the [quality feature](./feature-quality.md) is not configured. Use the returned options with [`Menu.RadioGroup`](./menu.md).
+[`useQualityOptions`](./use-quality-options.md) returns `null` when the [quality feature](./feature-quality.md) is not configured. Use the returned options with [`Menu.RadioGroup`](./menu.md).
 
 ## Styling
 
@@ -56,4 +51,158 @@ Whether multiple renditions are available.
 
 ## Accessibility
 
-The group uses the menu radio group pattern. It receives an accessible label from the `label` prop or defaults to `Quality`.
+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, useQualityOptions } 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/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4.m3u8';
+
+function QualityMenu(): ReactNode {
+  const quality = useQualityOptions();
+  if (quality?.state.availability !== 'available') return null;
+
+  return (
+    <Menu.Root side="top" align="end">
+      <Menu.Trigger className="settings-trigger" render={<button type="button" />}>
+        Quality
+      </Menu.Trigger>
+      <Menu.Content className="menu">
+        <Menu.RadioGroup
+          className="menu-group"
+          value={quality.value}
+          onValueChange={quality.setValue}
+          aria-label="Quality"
+        >
+          {quality.options.map((option) => (
+            <Menu.RadioItem key={option.value} value={option.value} disabled={option.disabled} className="menu-item">
+              <span>
+                {option.label}
+                {option.tier ? <sup className="menu-tier">{option.tier}</sup> : null}
+              </span>
+              {option.badge ? <span className="menu-badge">{option.badge}</span> : null}
+              <Menu.ItemIndicator checked={option.value === quality.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">
+          <QualityMenu />
+        </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-tier {
+  margin-left: 2px;
+  font-size: 10px;
+}
+
+.menu-badge {
+  margin-left: auto;
+  color: rgba(255, 255, 255, 0.72);
+}
+
+.menu-indicator {
+  opacity: 0;
+}
+
+[role="menuitemradio"][aria-checked="true"] .menu-indicator {
+  opacity: 1;
+}
+```

package/docs/reference/register-i18n.md

@@ -0,0 +1,64 @@
+# registerI18n
+
+Register or merge translation strings for a BCP 47 locale tag in the global i18n registry
+
+`registerI18n` merges a partial translation map into the process-wide registry for a locale tag. Components carry their own English fallback text. Built-in non-English packs lazy-load automatically; call `registerI18n` for custom locales, CDN locale modules, or patched shipped packs before the provider renders.
+
+Keys are nested semantic names such as `buttons.play` and `buttons.pause`. See [Translation keys](./translation-phrases.md) for the complete catalog.
+
+ts
+
+```
+import { registerI18n } from '@videojs/react/i18n';
+
+registerI18n('es', {
+  buttons: {
+    play: 'Reproducir',
+    pause: 'Pausar',
+  },
+});
+```
+
+## API Reference
+
+### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`locale*`
+
+`string & object | 'ar' | 'az' | 'bs' ...`
+
+`—`
+
+▸
+
+Description
+
+BCP 47 tag (normalized to lowercase; unicode extensions stripped for the registry key).
+
+Type
+
+`string & object | 'ar' | 'az' | 'bs' | 'bg' | 'bn' | 'ca' | 'cs' | 'cy' | 'da' | 'de' | 'el' | 'es' | 'et' | 'eu' | 'fa' | 'fi' | 'fr' | 'gd' | 'gl' | 'he' | 'hi' | 'hr' | 'hu' | 'it' | 'ja' | 'ko' | 'lv' | 'mr' | 'nb' | 'nl' | 'nn' | 'ne' | 'oc' | 'pl' | 'pt-BR' | 'pt-PT' | 'ro' | 'ru' | 'sk' | 'sl' | 'sr' | 'sv' | 'te' | 'th' | 'tr' | 'uk' | 'vi' | 'zh-CN' | 'zh-TW'`
+
+`translations*`
+
+`Partial<Translations>`
+
+`—`
+
+▸
+
+Description
+
+Partial nested locale values; merges with any existing layer for the tag.
+
+### Return Value
+
+`void`

package/docs/reference/seek-button.md

@@ -38,13 +38,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 />
         <div className="buttons">
           <SeekButton
             seconds={-5}
@@ -126,7 +120,7 @@ Whether the button is disabled.
 
 `label`
 
-`string | function`
+`Text | string | Text) | function`
 
 `''`
 
@@ -138,7 +132,7 @@ Custom label for the button.
 
 Type
 
-`string | ((state: SeekButtonState) => string)`
+`Text | string | ((state: SeekButtonState) => string | Text)`
 
 `seconds`
 
@@ -184,7 +178,7 @@ Whether the button seeks forward or backward.
 
 `label`
 
-`string`
+`Text | string`
 
 ### Data attributes
 

package/docs/reference/simple-hls-audio-only.md

@@ -16,13 +16,7 @@ App.css
 import { SimpleHlsAudioOnly } from '@videojs/react/media/simple-hls-audio-only';
 
 export default function BasicUsage() {
-  return (
-    <SimpleHlsAudioOnly
-      className="simple-hls-audio-only"
-      src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"
-      controls
-    />
-  );
+  return <SimpleHlsAudioOnly className="simple-hls-audio-only" src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" controls />;
 }
 ```
 ```
@@ -34,60 +28,14 @@ export default function BasicUsage() {
 
 ## API Reference
 
-### Host Properties
+### Props
 
-Property
+Accepts the standard React props for a native `<audio>`.
 
-Type
+### Ref
 
-Default
-
-Details
-
-`engine`
-
-`Composition<SimpleHlsAudioOnlyEngineState, SimpleHlsAudioOnlyEngineContext>`
-
-`—`
-
-▸
-
-Description
-
-Read-only. Underlying playback engine — the low-level SPF reactive composition that drives playback. An advanced escape hatch for direct engine access; normal playback is driven through this element's own properties and methods.
-
-`preload`
-
-`'' | 'none' | 'metadata' | 'auto'`
-
-`''`
-
-▸
-
-Description
-
-Preload type (`'none'` / `'metadata'` / `'auto'`).
-
-`src`
-
-`string`
-
-`''`
-
-### Attributes
-
-Renders a native `<audio>` 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/audio): `autopictureinpicture``autoPlay``controls``controlslist``crossOrigin``disablepictureinpicture``disableremoteplayback``loading``loop``muted``playsInline``poster``preload``src``stream-type`
+Forwards its ref to the rendered `<audio>`. The ref is an [HTMLAudioElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLAudioElement) 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``seeked``seeking``stalled``suspend``timeupdate``volumechange``waiting`
-
-These media events have no React prop — attach a listener through a `ref` with `addEventListener`: `addtrack``change``removetrack`
-
-This element dispatches no events beyond the media events above.
-
-### 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``load``pause``play`
-
-In React, call these through a `ref` to the element.
+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/simple-hls-video.md

@@ -16,16 +16,7 @@ App.css
 import { SimpleHlsVideo } from '@videojs/react/media/simple-hls-video';
 
 export default function BasicUsage() {
-  return (
-    <SimpleHlsVideo
-      className="simple-hls-video"
-      src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"
-      autoPlay
-      muted
-      playsInline
-      loop
-    />
-  );
+  return <SimpleHlsVideo className="simple-hls-video" src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" autoPlay muted playsInline loop />;
 }
 ```
 ```
@@ -37,114 +28,14 @@ export default function BasicUsage() {
 
 ## API Reference
 
-### Host Properties
+### Props
 
-Property
+Accepts the standard React props for a native `<video>`.
 
-Type
+### Ref
 
-Default
-
-Details
-
-`engine`
-
-`Composition<SimpleHlsEngineState, SimpleHlsEngineContext>`
-
-`—`
-
-▸
-
-Description
-
-Read-only. Underlying playback engine — the low-level SPF reactive composition that drives playback. An advanced escape hatch for direct engine access; normal playback is driven through this element's own properties and methods.
-
-`preload`
-
-`'' | 'none' | 'metadata' | 'auto'`
-
-`''`
-
-▸
-
-Description
-
-Preload type (`'none'` / `'metadata'` / `'auto'`).
-
-`src`
-
-`string`
-
-`''`
-
-### Attributes
-
-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`
-
-This element dispatches no events beyond the media events above.
-
-### 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/slider.md

@@ -301,7 +301,7 @@ Whether the slider is non-interactive.
 
 `label`
 
-`string | function`
+`Text | string | Text) | function`
 
 `''`
 
@@ -313,7 +313,7 @@ Custom label for the slider.
 
 Type
 
-`string | ((state: SliderState) => string)`
+`Text | string | ((state: SliderState) => string | Text)`
 
 `largeStep`
 

package/docs/reference/thumbnail.md

@@ -305,7 +305,7 @@ The thumbnail image failed to load.
 
 Description
 
-No thumbnail is available and not loading — the component should be hidden.
+Whether the component is hidden because no thumbnail is available and it is not loading.
 
 ### Data attributes
 

package/docs/reference/time-slider.md

@@ -42,7 +42,7 @@ css
 
 ## Accessibility
 
-Renders with `role="slider"` and automatic `aria-label` of “Seek”. Override with the `label` prop. Keyboard controls:
+Renders with `role="slider"` and an automatic `aria-label` that resolves to “Seek” from the active locale. Override with the `label` prop. Keyboard controls:
 
 *   Arrow Left / Arrow Right: step by `step` increment
 *   Page Up / Page Down: step by `largeStep` increment
@@ -69,13 +69,7 @@ export default function WithParts() {
   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 />
         <TimeSlider.Root className="media-time-slider">
           <TimeSlider.Track className="media-slider-track">
             <TimeSlider.Buffer className="media-slider-buffer" />
@@ -232,9 +226,9 @@ Whether the slider is non-interactive.
 
 `label`
 
-`string | function`
+`Text | string | Text) | function`
 
-`'Seek'`
+`''`
 
 ▸
 
@@ -244,7 +238,7 @@ Custom label for the slider.
 
 Type
 
-`string | ((state: SliderState) => string)`
+`Text | string | ((state: SliderState) => string | Text)`
 
 `largeStep`