@videojs/react 10.0.0-beta.3 → 10.0.0-beta.31

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

@@ -0,0 +1,144 @@
+# NativeHlsVideo
+
+HLS video element using the browser's built-in HLS support
+
+HLS video element that relies on the browser’s native HLS support. Works on Safari and other browsers with built-in HLS playback. For cross-browser HLS support, use [HlsJsVideo](/docs/framework/html/reference/hlsjs-video/) instead.
+
+## Examples
+
+### Basic Usage
+
+App.tsx
+
+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 />;
+}
+```
+```
+.native-hls-video {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+```
+
+## API Reference
+
+### Props
+
+Accepts the standard React props for a native `<video>`, plus these Video.js-specific props:
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`preload`
+
+`PreloadType`
+
+`'metadata'`
+
+▸
+
+Description
+
+Preload type (`'none'` / `'metadata'` / `'auto'`).
+
+`source`
+
+`NativeHlsSource | null`
+
+`null`
+
+▸
+
+Description
+
+Structured source: what to play (`src`) plus how to play it (`engine.nativeHls`). Assigning it derives `src`.
+
+Only a new URL reaches the element, so reassigning an equivalent source — an inline React prop, for instance — neither reloads nor disturbs key exchange. Use `src` or `load()` to reload what is already playing.
+
+Unlike `HlsJsMedia`, this does not announce a `sourcechange`. It is also the delegate `HlsJsMedia` plays native sources through, and every event it dispatches is re-dispatched there — which already announces its own.
+
+`src`
+
+`string`
+
+`''`
+
+▸
+
+Description
+
+Media source URL. Assigning it replaces the identity half of `source` and leaves `engine` intact, so changing the URL never disturbs key exchange.
+
+Like the element's own `src`, assigning it always loads — including the URL already playing. This is the imperative half of the API, and what `HlsJsMedia` loads its native delegate through.
+
+`streamType`
+
+`MediaStreamType`
+
+`'unknown'`
+
+▸
+
+Description
+
+Current stream type (`'on-demand'` / `'live'` / `'unknown'`).
+
+### Engine options
+
+#### `source.engine.nativeHls`
+
+This element hands playback to the browser, so there’s no JavaScript engine to configure. This carries the one thing native playback still needs from you. [Media Sources](../concepts/media-sources.md) covers how engine options fit into a structured source.
+
+tsx
+
+```
+<NativeHlsVideo
+  source={{
+    src: 'https://example.com/playlist.m3u8',
+    engine: {
+      nativeHls: {
+        drmSystems: { 'com.apple.fps': { licenseUrl: 'https://example.com/license' } },
+      },
+    },
+  }}
+/>
+```
+
+Option
+
+Type
+
+Details
+
+`drmSystems`
+
+`Partial<Record<KeySystem, DrmSystemCo...`
+
+▸
+
+Description
+
+License servers for protected content, keyed by EME key system id. An escape hatch for licensing native playback differently from every other path: naming it replaces `source.drm` here, and nowhere else.
+
+Type
+
+`Partial<Record<KeySystem, DrmSystemConfig>> | undefined`
+
+### Ref
+
+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 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

@@ -0,0 +1,241 @@
+# PiPButton
+
+Accessible picture-in-picture toggle button with keyboard support and state reflection
+
+## Anatomy
+
+tsx
+
+```
+<PiPButton />
+```
+
+## Behavior
+
+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
+
+You can style the button based on PiP state:
+
+React renders a `<button>` element. Add a `className` to style it:
+
+css
+
+```
+/* In PiP mode */
+.pip-button[data-pip] {
+  background: red;
+}
+
+/* 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.
+
+## Examples
+
+### Basic Usage
+
+App.tsx
+
+App.css
+
+```
+import { Container, createPlayer, PiPButton } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+export default function BasicUsage() {
+  return (
+    <Player>
+      <Container className="media-container">
+        <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>}
+        />
+      </Container>
+    </Player>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.media-pip-button {
+  position: absolute;
+  right: 10px;
+  bottom: 10px;
+  padding-block: 8px;
+  padding-inline: 20px;
+  color: black;
+  cursor: pointer;
+  background: rgba(255, 255, 255, 0.7);
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+```
+
+## API Reference
+
+### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`disabled`
+
+`boolean`
+
+`false`
+
+▸
+
+Description
+
+Whether the button is disabled.
+
+`label`
+
+`Text | string | Text) | function`
+
+`''`
+
+▸
+
+Description
+
+Custom label for the button.
+
+Type
+
+`Text | string | ((state: PiPButtonState) => string | Text)`
+
+### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+Property
+
+Type
+
+Details
+
+`availability`
+
+`'available' | 'unavailable' | 'unsupp...`
+
+▸
+
+Description
+
+Whether picture-in-picture can be requested on this platform.
+
+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`
+
+▸
+
+Description
+
+Whether picture-in-picture mode is currently active.
+
+`label`
+
+`Text | string`
+
+### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-pip`
+
+▸
+
+Description
+
+Present when picture-in-picture mode is active.
+
+`data-availability`
+
+`'available' | 'unavailable' | 'unsupp...`
+
+▸
+
+Description
+
+Indicates picture-in-picture availability (`available`, `unavailable`, `unsupported`).
+
+Type
+
+`'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

@@ -0,0 +1,219 @@
+# PlayButton
+
+Accessible play/pause button with keyboard support and customizable rendering
+
+## Anatomy
+
+tsx
+
+```
+<PlayButton />
+```
+
+## Behavior
+
+PlayButton is a three-state button: **play**, **pause**, and **replay**. When media reaches the end (`ended` state), clicking restarts playback from the beginning.
+
+## Styling
+
+Style with the `[data-paused]` and `[data-ended]` attributes to show/hide play/pause/replay icons based on state. For example:
+
+React renders a `<button>` element. Add a `className` to style it:
+
+css
+
+```
+/* Paused (but not ended) */
+.play-button[data-paused]:not([data-ended]) .play-icon { display: inline; }
+
+/* Playing */
+.play-button:not([data-paused]) .pause-icon { display: inline; }
+
+/* Ended */
+.play-button[data-ended] .replay-icon { display: inline; }
+```
+
+After first play, the `data-started` attribute is added and remains present until a new source is loaded. Use this to hide the play button when media hasn’t started yet:
+
+css
+
+```
+/* Hide play button before first play */
+.play-button:not([data-started]) .play-icon { display: none; }
+```
+
+## Accessibility
+
+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
+
+### Basic Usage
+
+Play
+
+App.tsx
+
+App.css
+
+```
+import { Container, createPlayer, PlayButton } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+export default function BasicUsage() {
+  return (
+    <Player>
+      <Container className="media-container">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline />
+        <PlayButton
+          className="media-play-button"
+          render={(props, state) => (
+            <button {...props}>{state.ended ? 'Replay' : state.paused ? 'Play' : 'Pause'}</button>
+          )}
+        />
+      </Container>
+    </Player>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.media-play-button {
+  position: absolute;
+  bottom: 10px;
+  left: 10px;
+  padding-block: 8px;
+  padding-inline: 20px;
+  color: black;
+  cursor: pointer;
+  background: rgba(255, 255, 255, 0.7);
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+```
+
+## API Reference
+
+### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`disabled`
+
+`boolean`
+
+`false`
+
+▸
+
+Description
+
+Whether the button is disabled.
+
+`label`
+
+`Text | string | Text) | function`
+
+`''`
+
+▸
+
+Description
+
+Custom label for the button.
+
+Type
+
+`Text | string | ((state: PlayButtonState) => string | Text)`
+
+### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+Property
+
+Type
+
+Details
+
+`paused`
+
+`boolean`
+
+▸
+
+Description
+
+Whether playback is paused.
+
+`ended`
+
+`boolean`
+
+▸
+
+Description
+
+Whether playback has reached the end.
+
+`started`
+
+`boolean`
+
+▸
+
+Description
+
+Whether playback has started (played or seeked).
+
+`label`
+
+`Text | string`
+
+### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-paused`
+
+▸
+
+Description
+
+Present when the media is paused.
+
+`data-ended`
+
+▸
+
+Description
+
+Present when the media has ended.
+
+`data-started`
+
+▸
+
+Description
+
+Present when playback has started.