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

package/docs/reference/airplay-button.md

@@ -0,0 +1,298 @@
+# AirPlayButton
+
+Accessible AirPlay toggle button that opens the WebKit playback target picker and reflects session state
+
+## Anatomy
+
+tsx
+
+```
+<AirPlayButton />
+```
+
+## Behavior
+
+Opens the WebKit AirPlay playback target picker and reflects session state. AirPlay is a WebKit-only feature, so the button reports `availability: "unsupported"` outside Safari (macOS and iOS). On supported platforms availability flips to `"available"` once Safari discovers at least one AirPlay receiver on the local network, and `"unavailable"` otherwise.
+
+The button is hidden until `availability` is `"available"`: the HTML custom element receives the native `hidden` attribute, and the React component returns `null`. An explicitly disabled, otherwise available button stays visible and focusable with `aria-disabled="true"` and `data-disabled`, but does not open the picker.
+
+The component consumes the unified [`remotePlayback`](./feature-remote-playback.md) store feature alongside `CastButton`: both buttons drive their state from the same feature, but each only surfaces on its supported platform (WebKit for AirPlay, Chromium for Cast).
+
+WebKit does not expose a `"connecting"` intermediate state — the `state` slice flips directly between `"disconnected"` and `"connected"` when the AirPlay session changes. When connected, the picker itself acts as the disconnect UI.
+
+## Styling
+
+Attribute
+
+Values
+
+Description
+
+`data-airplay-state`
+
+`"disconnected"` | `"connecting"` | `"connected"`
+
+Current AirPlay session state
+
+`data-availability`
+
+`"available"` | `"unavailable"` | `"unsupported"`
+
+Whether AirPlay is reachable on the current platform
+
+`data-disabled`
+
+Present / absent
+
+Present when the button is non-interactive
+
+`data-hidden`
+
+Present / absent
+
+Present on the HTML element while AirPlay is unavailable or unsupported
+
+Use `data-airplay-state` to swap icons or labels based on the session state:
+
+React renders a `<button>` element. Add a `className` and use it as the selector:
+
+css
+
+```
+/* AirPlay active */
+.airplay-button[data-airplay-state="connected"] {
+  color: var(--accent);
+}
+```
+
+Use `data-disabled` to style an explicitly disabled, available button:
+
+css
+
+```
+.airplay-button[data-disabled] {
+  cursor: not-allowed;
+  opacity: 0.5;
+}
+```
+
+Unavailable and unsupported buttons are hidden automatically. No availability selector or extra hiding CSS is required.
+
+## Accessibility
+
+Renders a `<button>` with an automatic `aria-label`: “Start AirPlay” when disconnected, “Stop AirPlay” when connected. (The component also supports a `"Connecting"` label, but WebKit AirPlay never emits a `connecting` state, so that label is unreachable in practice.) Override with the `label` prop — either a string or a function that receives the current state. Keyboard activation: Enter / Space.
+
+## Examples
+
+### Basic Usage
+
+App.tsx
+
+App.css
+
+```
+import { AirPlayButton, createPlayer } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const Player = createPlayer({ features: videoFeatures });
+
+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 />
+        <AirPlayButton
+          className="media-airplay-button"
+          render={(props, state) => (
+            <button {...props}>{state.state === 'connected' ? 'Stop AirPlay' : 'Start AirPlay'}</button>
+          )}
+        />
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.media-airplay-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);
+}
+
+/* Explicitly disabled while AirPlay is available. */
+.media-airplay-button[data-disabled] {
+  cursor: not-allowed;
+  opacity: 0.5;
+  filter: grayscale(1);
+}
+```
+
+## 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: AirPlayButtonState) => string | Text)`
+
+### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+Property
+
+Type
+
+Details
+
+`state`
+
+`'disconnected' | 'connecting' | 'conn...`
+
+▸
+
+Description
+
+Current AirPlay connection state.
+
+Type
+
+`'disconnected' | 'connecting' | 'connected'`
+
+`availability`
+
+`'available' | 'unavailable' | 'unsupp...`
+
+▸
+
+Description
+
+Whether AirPlay is available on the active platform and media.
+
+Type
+
+`'available' | 'unavailable' | 'unsupported'`
+
+`disabled`
+
+`boolean`
+
+▸
+
+Description
+
+Non-interactive but still focusable (mirrors `aria-disabled`).
+
+`hidden`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the button is hidden until AirPlay is available.
+
+`label`
+
+`Text | string`
+
+### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-airplay-state`
+
+`'disconnected' | 'connecting' | 'conn...`
+
+▸
+
+Description
+
+Current AirPlay connection state. @see [https://developer.mozilla.org/en-US/docs/Web/API/RemotePlayback/state](https://developer.mozilla.org/en-US/docs/Web/API/RemotePlayback/state)
+
+Type
+
+`'disconnected' | 'connecting' | 'connected'`
+
+`data-availability`
+
+`'available' | 'unavailable' | 'unsupp...`
+
+▸
+
+Description
+
+Whether AirPlay is available on the active platform and media. @see [https://developer.mozilla.org/en-US/docs/Web/API/RemotePlayback](https://developer.mozilla.org/en-US/docs/Web/API/RemotePlayback)
+
+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 AirPlay is unavailable.

package/docs/reference/audio-track-radio-group.md

@@ -0,0 +1,194 @@
+# AudioTrackRadioGroup
+
+A menu radio group for selecting an audio track
+
+Creates radio items from the player audio track state and selects the enabled track.
+
+## Anatomy
+
+tsx
+
+```
+<Menu.RadioGroup>
+  <Menu.GroupLabel />
+  <Menu.RadioItem>
+    <Menu.ItemIndicator />
+  </Menu.RadioItem>
+</Menu.RadioGroup>
+```
+
+## Behavior
+
+The group is available when the configured media exposes more than one audio track. Labels use the track label, then language, then kind. Pass `formatTrack` to customize the visible labels.
+
+[`useAudioTrackOptions`](./use-audio-track-options.md) returns `null` when the [audio track feature](./feature-audio-track.md) is not configured. Use the returned options with [`Menu.RadioGroup`](./menu.md).
+
+## Styling
+
+Attribute
+
+Values
+
+Description
+
+`data-audio-track`
+
+`string`
+
+Current audio track value.
+
+`data-disabled`
+
+Present / absent
+
+Present when audio track selection is disabled.
+
+`data-availability`
+
+`"available"` / `"unavailable"`
+
+Whether multiple audio tracks 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
+
+App.tsx
+
+App.css
+
+```
+import { createPlayer, Menu, useAudioTrackOptions } 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/s41JYeqIpBMBzE4OzxDyGR2yrp2hD1CQ6gJN9SlVGDQ.m3u8';
+
+function AudioMenu(): ReactNode {
+  const audioTrack = useAudioTrackOptions();
+  if (audioTrack?.state.availability !== 'available') return null;
+
+  return (
+    <Menu.Root side="top" align="end">
+      <Menu.Trigger className="settings-trigger" render={<button type="button" />}>
+        Audio
+      </Menu.Trigger>
+      <Menu.Content className="menu">
+        <Menu.RadioGroup
+          className="menu-group"
+          value={audioTrack.value}
+          onValueChange={audioTrack.setValue}
+          aria-label="Audio tracks"
+        >
+          {audioTrack.options.map((option) => (
+            <Menu.RadioItem key={option.value} value={option.value} disabled={option.disabled} className="menu-item">
+              {option.label}
+              <Menu.ItemIndicator checked={option.value === audioTrack.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">
+          <AudioMenu />
+        </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;
+}
+```

package/docs/reference/background-video.md

@@ -0,0 +1,76 @@
+# BackgroundVideo
+
+Decorative background video element with automatic muting and looping
+
+Decorative background video. By default it’s muted, looped, and autoplaying — use the opt-out attributes below to change that. Renders a `<video>` inside a shadow DOM, positioned to fill its container.
+
+## Examples
+
+### Basic Usage
+
+App.tsx
+
+App.css
+
+```
+import { BackgroundVideo } from '@videojs/react/media/background-video';
+
+export default function BasicUsage() {
+  return (
+    <div className="container">
+      <BackgroundVideo src="https://stream.mux.com/601n4w1fq88NJiVpzvrQQeQfNnnjjfKMIN7dCGAEarTs/highest.mp4" />
+    </div>
+  );
+}
+```
+```
+.container {
+  position: relative;
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+```
+
+## API Reference
+
+### Attributes
+
+Attribute
+
+Description
+
+`src`
+
+URL of the video source.
+
+`nomuted`
+
+Opt out of muted playback. By default the video is muted.
+
+`noloop`
+
+Opt out of looped playback. By default the video loops.
+
+`noautoplay`
+
+Opt out of autoplay. By default the video autoplays.
+
+### CSS Custom Properties
+
+Variable
+
+Default
+
+Description
+
+`–media-object-fit`
+
+`inherit`
+
+Controls how the video fits its container.
+
+`–media-object-position`
+
+`50% 50%`
+
+Controls the position of the video within its container.

package/docs/reference/buffering-indicator.md

@@ -36,13 +36,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 />
         <BufferingIndicator
           className="media-buffering-indicator"
           render={(props, state) => <div {...props}>{state.visible && <div className="spinner" />}</div>}