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

package/docs/reference/cast-button.md

@@ -14,11 +14,17 @@ tsx
 
 Toggles a Google Cast session. Clicking the button while `disconnected` opens the Cast device picker; clicking while `connected` ends the session.
 
-The button does nothing when `availability` is not `'available'` — for example, when no Chromecast is on the network, or on browsers that don’t support Cast.
+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 state and availability:
+Style based on cast and disabled state:
 
 React renders a `<button>` element. Add a `className` to style it:
 
@@ -30,12 +36,15 @@ css
   color: blue;
 }
 
-/* Hide when Cast is unsupported (non-Chromium browsers) */
-.cast-button[data-availability="unsupported"] {
-  display: none;
+/* 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`:
@@ -62,8 +71,6 @@ Override with the `label` prop. Keyboard activation: Enter / Space.
 
 ### Basic Usage
 
-Start casting
-
 App.tsx
 
 App.css
@@ -79,17 +86,11 @@ export default function BasicUsage() {
   return (
     <Player.Provider>
       <Player.Container className="media-container">
-        <HlsJsVideo
-          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"
-          autoPlay
-          muted
-          playsInline
-          loop
-        />
+        <HlsJsVideo src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" autoPlay muted playsInline loop />
         <CastButton
           className="media-cast-button"
           render={(props, state) => (
-            <button {...props}>{state.castState === 'connected' ? 'Stop casting' : 'Start casting'}</button>
+            <button {...props}>{state.connection === 'connected' ? 'Stop casting' : 'Start casting'}</button>
           )}
         />
       </Player.Container>
@@ -120,8 +121,10 @@ export default function BasicUsage() {
   backdrop-filter: blur(10px);
 }
 
-.media-cast-button[data-availability="unsupported"] {
-  display: none;
+.media-cast-button[data-disabled] {
+  cursor: not-allowed;
+  opacity: 0.5;
+  filter: grayscale(1);
 }
 ```
 
@@ -151,7 +154,7 @@ Whether the button is disabled.
 
 `label`
 
-`string | function`
+`Text | string | Text) | function`
 
 `''`
 
@@ -163,7 +166,7 @@ Custom label for the button.
 
 Type
 
-`string | ((state: CastButtonState) => string)`
+`Text | string | ((state: CastButtonState) => string | Text)`
 
 ### State
 
@@ -175,12 +178,16 @@ Type
 
 Details
 
-`castState`
+`connection`
 
 `'disconnected' | 'connecting' | 'conn...`
 
 ▸
 
+Description
+
+Current cast connection state (`disconnected`, `connecting`, or `connected`).
+
 Type
 
 `'disconnected' | 'connecting' | 'connected'`
@@ -191,13 +198,37 @@ Type
 
 ▸
 
+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`
 
-`string`
+`Text | string`
 
 ### Data attributes
 
@@ -233,4 +264,20 @@ Whether remote playback can be requested on this platform. @see [https://develop
 
 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 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">

package/docs/reference/create-i18n.md

@@ -0,0 +1,84 @@
+# createI18n
+
+Factory that creates framework i18n helpers with custom loading options
+
+`createI18n` returns an `I18nProvider`, `useTranslator`, and `useLocale` wired to the shared React i18n context used by the stock skins and controls. Use it when you need options such as a custom locale loader. Most apps use the default exports from `@videojs/react/i18n`.
+
+tsx
+
+```
+import { createI18n } from '@videojs/react/i18n';
+
+const loaders = {
+  ja: () => import('@videojs/react/i18n/locales/ja'),
+};
+
+const { I18nProvider, useTranslator } = createI18n({
+  loader: async (tag) => {
+    const load = loaders[tag as keyof typeof loaders];
+    return load ? (await load()).default : undefined;
+  },
+});
+
+function App() {
+  return (
+    <I18nProvider locale="ja">
+      <Controls />
+    </I18nProvider>
+  );
+}
+```
+
+## API Reference
+
+### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`options`
+
+`CreateI18nOptions`
+
+`—`
+
+▸
+
+Description
+
+Optional hooks such as custom built-in locale loading.
+
+### Return Value
+
+Property
+
+Type
+
+Details
+
+`I18nContext`
+
+`Context<I18nContextValue | null>`
+
+`I18nProvider`
+
+`function`
+
+▸
+
+Type
+
+`((props: I18nProviderProps) => ReactNode)`
+
+`useTranslator`
+
+`useTranslator`
+
+`useLocale`
+
+`useLocale`

package/docs/reference/create-player.md

@@ -51,12 +51,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 />
         <Controls />
       </Player.Container>
     </Player.Provider>

package/docs/reference/create-translator.md

@@ -0,0 +1,63 @@
+# createTranslator
+
+Build a typed translator from a resolved translation map
+
+`createTranslator` wraps the flat map returned by `getI18nTranslations` and returns a typed translator. Providers call this internally after merging registry, lazy-loaded built-in packs, browser-translated fallback copy, and provider layers. Use it directly for custom UI outside built-in controls.
+
+ts
+
+```
+import { createTranslator, getI18nTranslations } from '@videojs/react/i18n';
+
+const t = createTranslator(getI18nTranslations('fr'), 'fr');
+t('buttons.play', { default: 'Play' });
+t('seek.forward', { seconds: 5, default: 'Seek forward {seconds} seconds' });
+```
+
+## API Reference
+
+### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`translations*`
+
+`object & Record<string, string | unde...`
+
+`—`
+
+▸
+
+Description
+
+Merged translation map for the active locale.
+
+Type
+
+`object & Record<string, string | undefined>`
+
+`locale*`
+
+`string & object | 'ar' | 'az' | 'bs' ...`
+
+`—`
+
+▸
+
+Description
+
+BCP 47 tag associated with the map (reserved for future locale-aware behavior).
+
+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'`
+
+### Return Value
+
+`Translator`

package/docs/reference/dash-video.md

@@ -16,16 +16,7 @@ App.css
 import { DashVideo } from '@videojs/react/media/dash-video';
 
 export default function BasicUsage() {
-  return (
-    <DashVideo
-      className="dash-video"
-      src="https://dash.akamaized.net/akamai/streamroot/050714/Spring_4Ktest.mpd"
-      autoPlay
-      muted
-      playsInline
-      loop
-    />
-  );
+  return <DashVideo className="dash-video" src="https://dash.akamaized.net/akamai/streamroot/050714/Spring_4Ktest.mpd" 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,92 +40,16 @@ Default
 
 Details
 
-`engine`
-
-`MediaPlayerClass`
-
-`—`
-
-▸
-
-Description
-
-Read-only. Underlying playback engine — the dash.js `MediaPlayerClass` instance. An advanced escape hatch for direct engine access; normal playback is driven through this element's own properties and methods.
-
 `src`
 
 `string`
 
 `''`
 
-### 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`
-
-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/feature-error.md

@@ -16,7 +16,7 @@ Details
 
 `error`
 
-`null | MediaError`
+`null | ErrorLike`
 
 ▸
 

package/docs/reference/feature-text-tracks.md

@@ -94,15 +94,15 @@ Select a captions/subtitles track by menu value, or disable with `"off"`.
 
 ### Selector
 
-Pass `selectTextTracks` to [`usePlayer`](./use-player.md) to subscribe to text track state. Returns `undefined` if the text tracks feature is not configured.
+Pass `selectTextTrack` to [`usePlayer`](./use-player.md) to subscribe to text track state. Returns `undefined` if the text tracks feature is not configured.
 
 CaptionsButton.tsx
 
 ```
-import { selectTextTracks, usePlayer } from '@videojs/react';
+import { selectTextTrack, usePlayer } from '@videojs/react';
 
 function CaptionsButton() {
-  const tracks = usePlayer(selectTextTracks);
+  const tracks = usePlayer(selectTextTrack);
   if (!tracks) return null;
 
   return (

package/docs/reference/fullscreen-button.md

@@ -12,7 +12,10 @@ tsx
 
 ## Behavior
 
-Toggles fullscreen mode. Detects platform support through `availability` — when fullscreen is `"unsupported"`, the toggle does nothing.
+Toggles fullscreen mode. The button derives two state hooks from `availability`:
+
+*   **`disabled`** (`true` until fullscreen 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 fullscreen 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
 .fullscreen-button[data-fullscreen] {
   background: red;
 }
-```
-
-Consider hiding the button when unsupported:
-
-css
 
-```
-.fullscreen-button[data-availability="unsupported"] {
-  display: none;
+/* Non-interactive (disabled prop) */
+.fullscreen-button[data-disabled] {
+  opacity: 0.5;
+  cursor: not-allowed;
 }
 ```
 
+The button remains hidden until fullscreen 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 fullscreen” or “Exit fullscreen”. Override with the `label` prop. Keyboard activation: Enter / Space.
@@ -47,8 +48,6 @@ Renders a `<button>` with an automatic `aria-label`: “Enter fullscreen” or
 
 ### Basic Usage
 
-Fullscreen
-
 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 />
         <FullscreenButton
           className="media-fullscreen-button"
           render={(props, state) => <button {...props}>{state.fullscreen ? 'Exit Fullscreen' : 'Fullscreen'}</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: FullscreenButtonState) => string)`
+`Text | string | ((state: FullscreenButtonState) => 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 fullscreen is available.
+
 `fullscreen`
 
 `boolean`
@@ -179,7 +192,7 @@ Whether fullscreen mode is currently active.
 
 `label`
 
-`string`
+`Text | string`
 
 ### Data attributes
 
@@ -205,8 +218,24 @@ Present when fullscreen mode is active.
 
 Description
 
-Indicates fullscreen availability (`available` or `unsupported`).
+Indicates fullscreen 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 fullscreen is not available.