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

package/docs/llms.txt

@@ -0,0 +1,155 @@
+# Video.js v10 — React Documentation
+
+## Getting started
+
+Installation, project setup, and introductory guides.
+
+- [Installation](./how-to/installation.md): Install Video.js and build your first player with streaming support and accessible controls
+### Migrate to Video.js 10
+
+Guides for moving an existing player integration to Video.js v10, one per player you might be coming from.
+
+- [Migrate from Video.js 8](./how-to/migrate-from-video-js-8.md): Move a Video.js 8 integration to v10, mapping the options object, techs, plugins, and player API onto composed components
+- [Migrate from Mux Player](./how-to/migrate-from-mux-player.md): Move a Mux Player embed to Video.js v10, splitting one element into a player, a media, and a skin
+- [Migrate from Plyr](./how-to/migrate-from-plyr.md): Move an existing Plyr integration to Video.js v10, mapping Plyr options and its instance API onto components and player state
+- [Migrate from Media Chrome](./how-to/migrate-from-media-chrome.md): Map Media Chrome's controller, elements, and attributes onto Video.js v10, where most of the work is renaming and reshaping rather than rewriting
+
+- [Why Video.js?](./concepts/why-videojs.md): The open-source video player for React and HTML. Lightweight, accessible components built for performance and streaming.
+- [Overview](./concepts/overview.md): How Video.js players are structured — state, UI, and media
+- [Build with AI](./how-to/build-with-ai.md): How to give AI tools the context they need to build Video.js players alongside you
+- [v10 Roadmap](./concepts/v10-roadmap.md): Timeline and milestones for Video.js v10 rebuild and the future of v8
+- [Browser Support](./concepts/browser-support.md): Which browsers Video.js 10 supports and how it handles newer platform features
+
+## Concepts
+
+Understanding-oriented pages that explain how and why things work. Read these to build a mental model of the library.
+
+- [Features](./concepts/features.md): The state and actions each feature adds to the player
+- [Skins](./concepts/skins.md): Packaged player designs that include both UI components and their styles.
+- [Presets](./concepts/presets.md): Pre-packaged player configurations that bundle state management, skins, and media elements for specific use cases.
+- [UI components](./concepts/ui-components.md): How Video.js UI components work — one element per component, data attributes for state, and compound composition.
+- [Accessibility](./concepts/accessibility.md): How Video.js approaches accessibility, and what you should consider if you're deeply customizing your player
+- [Media sources](./concepts/media-sources.md): Set what a media element plays and how its engine plays it with the structured source property
+- [Google Cast](./concepts/cast.md): Cast playback to Chromecast devices with the Google Cast component, and configure the receiver and load request
+- [Mux Data](./concepts/mux-data.md): Monitor playback quality and viewer experience by adding the Mux Data component to a player
+- [Security](./concepts/security.md): How to configure Content Security Policy for your video player
+- [Internationalization](./concepts/i18n.md): How Video.js chooses a language and translates built-in player text
+
+## How to
+
+Task-oriented guides with step-by-step instructions to achieve a specific outcome by applying one or more concepts. Each guide may assume you already understand the relevant concepts.
+
+- [Customize skins](./how-to/customize-skins.md): Learn how to customize Video.js v10 skins by copying and modifying them
+- [Add a poster placeholder](./how-to/add-a-poster-placeholder.md): Show a lightweight placeholder while the poster image loads
+- [Build your own UI component](./how-to/build-your-own-component.md): Create custom player controls that read state, dispatch actions, and stay accessible.
+### Internationalization
+
+- [Translation phrases](./reference/translation-phrases.md): Semantic i18n keys, their English defaults, and the player UI that uses them
+- [Register a custom locale](./how-to/i18n-register-locale.md): Register translation packs for HTML, React, and CDN players
+- [Override translations](./how-to/i18n-override-translations.md): Patch individual i18n strings without replacing an entire locale pack
+- [Switch locale dynamically](./how-to/i18n-switch-locale.md): Change the player language at runtime in HTML and React
+- [SSR and locale](./how-to/i18n-ssr.md): Render translated player UI on the server without a flash of English
+
+## API Reference
+
+Reference for every public export, grouped by what it is: UI components, media components, player features, and utilities.
+
+### UI Components
+
+API Reference for UI components for building media player interfaces.
+
+- [Player](./reference/player-provider.md): The state boundary — creates a store and broadcasts it to all descendants.
+- [Container](./reference/player-container.md): The player's interaction surface — handles layout, fullscreen, media attachment, and user activity detection.
+- [I18nProvider](./reference/i18n-provider.md): React provider that resolves locale and supplies a typed translator to descendants
+- [AirPlayButton](./reference/airplay-button.md): Accessible AirPlay toggle button that opens the WebKit playback target picker and reflects session state
+- [AudioTrackRadioGroup](./reference/audio-track-radio-group.md): A menu radio group for selecting an audio track
+- [BufferingIndicator](./reference/buffering-indicator.md): Loading indicator that displays when the video player is buffering or waiting for data
+- [CaptionsButton](./reference/captions-button.md): Accessible captions toggle button with availability detection and state reflection
+- [CaptionsRadioGroup](./reference/captions-radio-group.md): A menu radio group for selecting caption and subtitle tracks
+- [CastButton](./reference/cast-button.md): Accessible Cast toggle button with state reflection and keyboard support
+- [Controls](./reference/controls.md): Container component for composing and auto-hiding video player controls on user interaction
+- [FullscreenButton](./reference/fullscreen-button.md): Accessible fullscreen toggle button with keyboard support and state reflection
+- [GoogleCast](./reference/google-cast.md): Options for the Google Cast component that configures the receiver and load request
+- [Menu](./reference/menu.md): A composable menu component for settings, option selection, and actions
+- [MuteButton](./reference/mute-button.md): Accessible mute/unmute button with keyboard support and volume state reflection
+- [MuxData](./reference/mux-data.md): Options for the Mux Data component that monitors playback quality
+- [PiPButton](./reference/pip-button.md): Accessible picture-in-picture toggle button with keyboard support and state reflection
+- [PlayButton](./reference/play-button.md): Accessible play/pause button with keyboard support and customizable rendering
+- [PlaybackRateButton](./reference/playback-rate-button.md): A button that cycles through playback speed rates
+- [PlaybackRateRadioGroup](./reference/playback-rate-radio-group.md): A menu radio group for selecting playback speed
+- [Popover](./reference/popover.md): A popover component for displaying contextual content anchored to a trigger
+- [Poster](./reference/poster.md): Poster image component that displays a thumbnail until video playback starts
+- [QualityRadioGroup](./reference/quality-radio-group.md): A menu radio group for selecting video quality
+- [SeekButton](./reference/seek-button.md): Accessible seek button for skipping forward or backward by a configurable number of seconds
+- [Slider](./reference/slider.md): A composable slider component with track, fill, thumb, preview, and value parts
+- [Thumbnail](./reference/thumbnail.md): Time-based thumbnail preview component for timeline scrubbing and hover previews
+- [Time](./reference/time.md): Time display components for showing current time, duration, and remaining time in a video player
+- [TimeSlider](./reference/time-slider.md): A slider component for seeking through media playback time
+- [Title](./reference/title.md): Displays the resolved content title for the current media
+- [Tooltip](./reference/tooltip.md): A tooltip component for displaying contextual labels on hover and focus
+- [VolumeSlider](./reference/volume-slider.md): A slider component for controlling media playback volume
+
+### Media Components
+
+API Reference for media components that handle streaming protocols and media playback.
+
+- [BackgroundVideo](./reference/background-video.md): Decorative background video element with automatic muting and looping
+- [DashVideo](./reference/dash-video.md): DASH video element powered by dash.js for adaptive bitrate streaming
+- [HlsAudio](./reference/hls-audio.md): Audio-only HLS element that plays the audio rendition of an HLS stream
+- [HlsVideo](./reference/hls-video.md): Lightweight HLS video element with minimal bundle size
+- [HlsJsVideo](./reference/hlsjs-video.md): HLS video element powered by hls.js for adaptive bitrate streaming
+- [MuxAudio](./reference/mux-audio.md): Audio element for Mux-hosted HLS streams
+- [MuxVideo](./reference/mux-video.md): Video element for Mux-hosted HLS streams
+- [NativeHlsVideo](./reference/native-hls-video.md): HLS video element using the browser's built-in HLS support
+
+### Player Features
+
+API reference for the feature modules passed to createPlayer, which provide player capabilities and state.
+
+- [createSelector](./reference/create-selector.md): Create a type-safe selector for a store slice's state
+- [Buffer](./reference/feature-buffer.md): Buffered and seekable time range state for the player store
+- [Controls](./reference/feature-controls.md): User activity and controls visibility state for the player store
+- [Error](./reference/feature-error.md): Media error state and actions for the player store
+- [Fullscreen](./reference/feature-fullscreen.md): Fullscreen state and actions for the player store
+- [Live](./reference/feature-live.md): Live edge state for the player store
+- [Metadata](./reference/feature-metadata.md): Resolved title and poster values for the player store
+- [Orientation lock](./reference/feature-orientation-lock.md): Screen orientation locking while fullscreen is active
+- [Picture-in-picture](./reference/feature-pip.md): Picture-in-picture state and actions for the player store
+- [Playback](./reference/feature-playback.md): Play/pause state and actions for the player store
+- [Playback rate](./reference/feature-playback-rate.md): Playback speed state and actions for the player store
+- [Quality](./reference/feature-quality.md): Video rendition state and actions for the player store
+- [Audio track](./reference/feature-audio-track.md): Audio track state and actions for the player store
+- [Remote Playback](./reference/feature-remote-playback.md): Remote playback state and actions for the player store
+- [Source](./reference/feature-source.md): Media source state and actions for the player store
+- [Stream type](./reference/feature-stream-type.md): Stream delivery type (live / on-demand) state for the player store
+- [Text tracks](./reference/feature-text-tracks.md): Subtitles, captions, and chapter track state for the player store
+- [Time](./reference/feature-time.md): Playback position and duration state for the player store
+- [Volume](./reference/feature-volume.md): Volume level and mute state for the player store
+
+### Utilities
+
+API reference for the hooks, utilities, controllers, and mixins used to integrate a player into an application.
+
+- [createPlayer](./reference/create-player.md): Factory function that creates a typed Player component and hooks
+- [usePlayer](./reference/use-player.md): Hook to access the player store from within a Player
+- [useMedia](./reference/use-media.md): Hook to access the media object from within a Player
+- [useStore](./reference/use-store.md): Hook to access store state and actions with optional selector-based subscriptions
+- [createI18n](./reference/create-i18n.md): Factory that creates framework i18n helpers with custom loading options
+- [useTranslator](./reference/use-translator.md): React hook that returns the typed translator for the nearest I18nProvider
+- [useLocale](./reference/use-locale.md): React hook that returns the active BCP 47 locale from the nearest I18nProvider
+- [registerI18n](./reference/register-i18n.md): Register or merge translation strings for a BCP 47 locale tag in the global i18n registry
+- [getI18nTranslations](./reference/get-i18n-translations.md): Read the merged translation map for a locale using BCP 47 parent-chain fallback
+- [hasRegisteredLocale](./reference/has-registered-locale.md): Check whether an exact locale tag exists in the global i18n registry
+- [onI18nRegistryChange](./reference/on-i18n-registry-change.md): Subscribe to global i18n registry mutations
+- [createTranslator](./reference/create-translator.md): Build a typed translator from a resolved translation map
+- [renderElement](./reference/render-element.md): Utility for rendering UI component elements with state-driven props and render prop support
+- [useAudioTrackOptions](./reference/use-audio-track-options.md): Hook to build audio track menu options from the player audio track state
+- [useButton](./reference/use-button.md): Hook for creating accessible button components with keyboard and pointer interaction
+- [useCaptionsOptions](./reference/use-captions-options.md): Hook to build captions menu options from the player text track state
+- [useContainerAttach](./reference/use-container-attach.md): Hook to register a custom container element with the player context
+- [useMediaAttach](./reference/use-media-attach.md): Hook to register a custom media element with the player context
+- [usePlaybackRateOptions](./reference/use-playback-rate-options.md): Hook to build playback rate menu options from the player playback rate state
+- [usePlayerContext](./reference/use-player-context.md): Hook to access the full player context value
+- [useQualityOptions](./reference/use-quality-options.md): Hook to build video quality menu options from the player rendition state
+- [useSelector](./reference/use-selector.md): Low-level hook for subscribing to derived state with customizable equality checks
+- [useSnapshot](./reference/use-snapshot.md): Hook to subscribe to a State container's current value

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, Container, createPlayer } 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 />
+        <AirPlayButton
+          className="media-airplay-button"
+          render={(props, state) => (
+            <button {...props}>{state.state === 'connected' ? 'Stop AirPlay' : 'Start AirPlay'}</button>
+          )}
+        />
+      </Container>
+    </Player>
+  );
+}
+```
+```
+.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.