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

package/docs/concepts/accessibility.md

@@ -0,0 +1,60 @@
+# Accessibility
+
+How Video.js approaches accessibility, and what you should consider if you're deeply customizing your player
+
+Video.js is built with accessibility in mind so your player can reach the widest possible audience.
+
+Here are some of the accessibility aspects we consider. You should consider them too if you’re performing deeper customization.
+
+## Standards we target
+
+*   [**WAI-ARIA 1.2**](https://www.w3.org/TR/wai-aria-1.2/) defines roles, states, and properties that [assistive technologies](https://www.w3.org/WAI/people-use-web/tools-techniques/) use to understand controls.
+*   [**WCAG 2.2**](https://www.w3.org/TR/WCAG22/) provides success criteria for perceivable, operable, understandable, and robust web content.
+*   [**CVAA**](https://www.fcc.gov/consumers/guides/21st-century-communications-and-video-accessibility-act-cvaa) is a U.S. federal law requiring closed captioning and accessible controls for video content.
+*   [**ADA**](https://www.ada.gov/) is a U.S. civil rights law that prohibits disability discrimination. Courts increasingly apply it to websites, including video players.
+
+## ARIA roles and labels
+
+Components set ARIA roles and attributes automatically. For example, sliders render with `role="slider"` and value attributes, buttons update their `aria-label` based on player state, and decorative elements like time separators are hidden with `aria-hidden="true"`.
+
+Verify that labels are contextually correct for your content and language. Each component’s reference page documents the attributes it sets.
+
+## Keyboard interaction
+
+All interactive components support keyboard control. For example, buttons activate with Enter and Space, sliders respond to Arrow keys, Home, End, and Page Up/Page Down, and popovers close with Escape. Each component’s reference page lists its full keyboard support. We follow the patterns in the [WAI-ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/).
+
+## Focus management
+
+Interactive elements are focusable when enabled and leave the [tab order](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex) when disabled. Popover triggers link to their popups with `aria-controls` and `aria-expanded`.
+
+## Captions and subtitles
+
+The [text tracks feature](../reference/feature-text-tracks.md) supports captions and subtitles. Closed captions in the U.S. are governed by the [FCC](https://www.fcc.gov/) under the [CVAA](https://www.fcc.gov/consumers/guides/21st-century-communications-and-video-accessibility-act-cvaa), which requires both captioning and viewer control over caption appearance (font, size, color, opacity, and edge style). Non-compliance carries legal risk. The [WebKit Caption Display Settings explainer](https://github.com/WebKit/explainers/tree/main/CaptionDisplaySettings) tracks how browsers are bringing these customization preferences into the web platform natively.
+
+## Color contrast
+
+Skins respond to [`prefers-contrast: more`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-contrast) by increasing background opacity on overlays and controls, and to [`prefers-reduced-transparency: reduce`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-transparency) by raising baseline opacity so text stays readable over video.
+
+Video is harder than most UI for contrast because the background is always changing. A control that passes checks over a dark frame can disappear over a bright title card. Automated tools won’t catch this, so test your controls against light, dark, and mixed video content. Custom components should test against [WCAG 1.4.3 (contrast minimum)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum) and [1.4.11 (non-text contrast)](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast).
+
+## Touch targets
+
+Controls use rem-based sizing so they scale with the user’s font size preference. All interactive elements set [`touch-action: manipulation`](https://developer.mozilla.org/en-US/docs/Web/CSS/touch-action) to eliminate tap delay on touch devices. Skins use [`pointer: fine` and `pointer: coarse`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/pointer) to adapt transitions for mouse and touch input.
+
+If you build custom controls, target at least 24x24 CSS pixels per [WCAG 2.5.8 (target size minimum)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum). Larger is better on touch-first surfaces.
+
+## Color scheme
+
+Skins adapt to [`prefers-color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme). Borders, backgrounds, and text colors adjust through CSS custom properties. Custom components can use the same design tokens. See [Skins](./skins.md) for details.
+
+## Reduced motion
+
+Skins respect [`prefers-reduced-motion`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) by simplifying or removing animations and transitions. Follow the same pattern in custom components.
+
+## Test with assistive technology
+
+Automated tools catch markup issues but miss real usability problems. Test your player with a [screen reader](https://www.w3.org/WAI/people-use-web/tools-techniques/) ([VoiceOver](https://support.apple.com/guide/voiceover/welcome/mac) on macOS, [NVDA](https://www.nvaccess.org/about-nvda/) or [JAWS](https://www.freedomscientific.com/products/software/jaws/) on Windows) and keyboard-only navigation. Verify that every control is reachable, operable, and announces its purpose and state. The [WAI “Easy Checks”](https://www.w3.org/WAI/test-evaluate/preliminary/) are a good starting point.
+
+## Further reading
+
+The W3C WAI guides on [making audio and video media accessible](https://www.w3.org/WAI/media/av/) and [accessible media players](https://www.w3.org/WAI/media/av/player/) go deeper on everything covered here.

package/docs/concepts/browser-support.md

@@ -0,0 +1,37 @@
+# Browser Support
+
+Which browsers Video.js 10 supports and how it handles newer platform features
+
+Video.js 10 currently targets **evergreen browsers**: the latest two stable versions of Chrome, Firefox, Safari, and Edge.
+
+Note
+
+Video.js 10 is in beta. The browser support matrix may expand as we approach GA based on community feedback and usage data.
+
+## Why evergreen?
+
+Video.js 10 builds directly on the web platform: custom elements, CSS custom properties, anchor positioning, and modern JavaScript APIs. Targeting evergreen browsers lets us:
+
+*   **Ship smaller bundles** by avoiding polyfills and transpilation for outdated syntax
+*   **Use platform-native features** like `popover` and anchor positioning instead of JavaScript equivalents
+*   **Keep the core slim** so platform-specific adapters (HTML, React) add only what they need
+
+## Progressive enhancement
+
+When we use a platform feature that hasn’t landed in all supported browsers yet, we provide a fallback. The player works either way; the experience may differ slightly in older browsers. For example, tooltips and popovers use CSS anchor positioning where available and fall back to absolute positioning where it isn’t.
+
+## Rendering contexts
+
+### WebViews and PWAs
+
+A [WebView](https://developer.mozilla.org/en-US/docs/Glossary/WebView) is a browser engine embedded inside a native app. WebViews on iOS (WKWebView) and Android (Android WebView) behave differently from the full browser; autoplay policies, fullscreen APIs, and hardware acceleration can vary. Progressive Web Apps (PWAs) installed via “Add to Homescreen” can exhibit similar quirks, since they also run in a limited browser context rather than a full browser tab.
+
+Video.js 10 beta targets only standard browser environments. If you embed a player inside a native app or PWA, test thoroughly for your specific platform and runtime.
+
+### Smart TVs and set-top boxes
+
+TV platforms run embedded browsers with limited standards support. Video.js 10’s core is not tied to any specific platform, which makes future TV adapters possible, but TV is not a supported target today.
+
+### Server-side rendering
+
+Video.js components render valid markup on the server. Interactivity — state management, media playback, and event handling — requires the browser and kicks in after hydration.

package/docs/concepts/cast.md

@@ -0,0 +1,162 @@
+# Google Cast
+
+How to add Chromecast support to your Video.js player — lazy SDK loading, session lifecycle, and configuration options
+
+Video.js has built-in Google Cast support for HLS and DASH media elements. When a Chromecast device is on the same network, a Cast button appears automatically in Chromium browsers. Tapping it starts a session that moves playback to the TV while the browser stays in control.
+
+Note
+
+Cast is only available in Chromium-based browsers (Chrome, Edge, and others built on Blink). On other browsers, `remotePlaybackAvailability` is `'unsupported'`.
+
+## How Cast works
+
+Cast uses a **sender / receiver** model:
+
+*   **Sender** — the browser tab. It controls playback commands (play, pause, seek, volume) and sends a load request to the receiver with the source URL and metadata.
+*   **Receiver** — the Chromecast device running the default media receiver application (or a custom receiver you configure).
+
+### Session lifecycle
+
+A Cast session moves through three states, exposed via the [Remote Playback](../reference/feature-remote-playback.md) feature:
+
+State
+
+Meaning
+
+`'disconnected'`
+
+No active session
+
+`'connecting'`
+
+User accepted; session negotiating
+
+`'connected'`
+
+Receiver is playing
+
+While `connected`, the media element’s `play`, `pause`, `currentTime`, `volume`, `muted`, and `playbackRate` all proxy to the Cast receiver. Local playback is suspended.
+
+### The lazy-loaded SDK
+
+The Cast SDK (`cast_sender.js`) is injected into the page as a `<script>` tag the first time a Cast-capable media element is created in a Chromium browser. No SDK cost is paid on browsers that don’t support Cast.
+
+Set `disableRemotePlayback` on the media element to opt out:
+
+tsx
+
+```
+<HlsJsVideo disableRemotePlayback />
+```
+
+## Minimal setup
+
+Cast works out of the box with the `videoFeatures` preset — no extra configuration needed. Add a `CastButton` to give users a way to start and stop a session:
+
+tsx
+
+```
+import { createPlayer, CastButton } from '@videojs/react';
+import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
+import { videoFeatures } from '@videojs/react/video';
+
+const Player = createPlayer({ features: videoFeatures });
+
+export default function App() {
+  return (
+    <Player.Provider>
+      <Player.Container>
+        <HlsJsVideo src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" autoPlay muted playsInline loop />
+        <CastButton />
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+
+## Configuring Cast
+
+All Cast configuration is set via the `config.googleCast` property. In React, pass it as a declarative prop. In HTML, set it as a JavaScript property; HTML attributes are not supported.
+
+### Custom receiver application ID
+
+By default, Video.js uses Google’s [Default Media Receiver](https://developers.google.com/cast/docs/web_sender/integrate#default_media_web_receiver) (`CC1AD845`). To use your own receiver app, set `receiver`:
+
+tsx
+
+```
+<HlsJsVideo src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" config={{ googleCast: { receiver: 'YOUR_APP_ID' } }} />
+```
+
+### Custom data on load
+
+Pass arbitrary data to the receiver with each load request via `customData`. The receiver app reads it from the `customData` field of the load request:
+
+tsx
+
+```
+<HlsJsVideo
+  src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"
+  config={{ googleCast: { customData: { token: 'abc123', userId: 'u_789' } } }}
+/>
+```
+
+### Cast source override
+
+By default the receiver loads the same URL as the browser. Use `src` (and optionally `contentType`) to send a different URL, for example, a separate manifest or CDN-edge URL accessible from the TV network:
+
+tsx
+
+```
+<HlsJsVideo
+  src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
+  config={{ googleCast: { src: 'https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8', contentType: 'application/x-mpegURL' } }}
+/>
+```
+
+### HLS on the receiver
+
+When the source (or `config.googleCast.src`) is an HLS playlist, Video.js automatically detects the segment format (TS or fMP4) by inspecting the playlist and sets `hlsSegmentFormat` / `hlsVideoSegmentFormat` on the Cast load request. The default media receiver handles HLS natively, so no extra configuration is needed.
+
+Use `streamType` to tell the receiver whether the stream is `'on-demand'` or `'live'` (falls back to the player’s `streamType` when unset):
+
+tsx
+
+```
+<HlsJsVideo src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" config={{ googleCast: { streamType: 'live' } }} />
+```
+
+## Cast state and selectors
+
+Cast session state lives in the [Remote Playback](../reference/feature-remote-playback.md) feature slice. Use `selectRemotePlayback` to subscribe:
+
+tsx
+
+```
+import { selectRemotePlayback, usePlayer } from '@videojs/react';
+
+function CastStatus() {
+  const remotePlayback = usePlayer(selectRemotePlayback);
+  if (!remotePlayback) return null;
+
+  return <span>{remotePlayback.remotePlaybackState}</span>;
+}
+```
+
+## Browser availability
+
+Cast availability is surfaced as `remotePlaybackAvailability` on the remote playback feature. Hide the button when unsupported:
+
+css
+
+```
+.cast-button[data-availability="unsupported"] {
+  display: none;
+}
+```
+
+## See also
+
+[CastButton component reference](../reference/cast-button.md)
+
+[Remote Playback feature reference](../reference/feature-remote-playback.md)

package/docs/concepts/features.md

@@ -0,0 +1,131 @@
+# Features
+
+The state and actions each feature adds to the player
+
+Not every player needs to support every use case. To address this, Video.js has a concept of **features** — self-contained units of player functionality. Each one adds state properties and actions to the player. For example, “playback” adds `paused` and `play()`, “volume” adds `volume` and `setVolume()`, and so on.
+
+## Using features
+
+### Feature bundles and presets
+
+You probably don’t want to hand-pick every feature your player needs. A **feature bundle** groups the features needed for a specific use case into a single array.
+
+For example, `videoFeatures` bundles playback, volume, time, fullscreen, and more — everything a general video player needs:
+
+tsx
+
+```
+import { createPlayer } from '@videojs/react';
+import { videoFeatures } from '@videojs/react/video';
+
+const Player = createPlayer({ features: videoFeatures });
+```
+
+Feature bundles are usually paired with specific skins and media elements in a **preset**. To learn more about this, and the available presets, you’ll want to check out the presets guide.
+
+[Learn more about presets](./presets.md)
+
+### Create a player with individual features
+
+If you’re not using presets, you can create a player that has individual features.
+
+tsx
+
+```
+import { createPlayer, playbackFeature, volumeFeature, timeFeature, controlsFeature } from '@videojs/react';
+
+const Player = createPlayer({
+  features: [playbackFeature, volumeFeature, timeFeature, controlsFeature],
+});
+```
+
+### Extending a feature bundle
+
+Since feature bundles are just an array of features under the hood, it doesn’t take much to extend one. For example, if you were using the `/background` preset and wanted a play button on your background video, you might add the playback feature.
+
+tsx
+
+```
+import { createPlayer, playbackFeature } from '@videojs/react';
+import { backgroundFeatures } from '@videojs/react/background';
+
+const Player = createPlayer({
+  features: [...backgroundFeatures, playbackFeature],
+});
+```
+
+### Access features in components
+
+You access feature state and actions through [`usePlayer`](../reference/use-player.md):
+
+tsx
+
+```
+// Subscribe to state (re-renders when selected values change)
+const { paused, volume } = usePlayer((s) => ({
+  paused: s.paused,
+  volume: s.volume,
+}));
+
+// Call actions
+const store = usePlayer();
+store.play();
+store.setVolume(0.8);
+```
+
+### Feature selectors
+
+Each feature also has a pre-built selector (e.g. [`selectPlayback`](../reference/feature-playback.md), [`selectVolume`](../reference/feature-volume.md)) that returns just that feature’s state and actions:
+
+tsx
+
+```
+import { selectPlayback, usePlayer } from '@videojs/react';
+
+const playback = usePlayer(selectPlayback);
+playback?.play();
+```
+
+### Checking for feature support
+
+Volume, fullscreen, and picture-in-picture expose an `*Availability` property because platform support varies. For example, iOS Safari doesn’t allow programmatic volume control.
+
+Value
+
+Meaning
+
+`'available'`
+
+Ready to use
+
+`'unavailable'`
+
+Could work, not ready yet
+
+`'unsupported'`
+
+Platform can never do this
+
+Components that depend on availability (like [`PiPButton`](../reference/pip-button.md) and [`FullscreenButton`](../reference/fullscreen-button.md)) expose a `data-availability` attribute, so you can hide unsupported controls with CSS:
+
+css
+
+```
+.pip-button[data-availability="unsupported"] {
+  display: none;
+}
+```
+
+You can also check availability in JS:
+
+PiPControl.tsx
+
+```
+function PiPControl() {
+  const availability = usePlayer((s) => s.pipAvailability);
+
+  if (availability === 'unsupported') return null;
+
+  return <PiPButton />;
+}
+```

package/docs/concepts/overview.md

@@ -0,0 +1,119 @@
+# Overview
+
+How Video.js players are structured — state, UI, and media
+
+Video.js v10 is built around a three-part architecture that separates concerns and maximizes flexibility. Each part is designed to work independently or together, allowing you to use as much or as little of Video.js as you need.
+
+For the reasoning behind this design, see [Why Video.js?](./why-videojs.md).
+
+## 1\. State management
+
+State is handled by a `Player.Provider`, which creates a central state store that all components can access. When you wrap your player in a `Player.Provider`, the components automatically connect to the state.
+
+tsx
+
+```
+{/* All components inside automatically connect to state */}
+<Player.Provider>
+  <VideoSkin>
+    <Video src="video.mp4" />
+  </VideoSkin>
+</Player.Provider>
+```
+
+You can access state and actions from anywhere within the provider with the [`usePlayer` hook](../reference/use-player.md).
+
+[Learn more about state and actions](./features.md)
+
+## 2\. User interface
+
+Use a prebuilt **skin** or build your own from the individual **UI components**.
+
+### Skins
+
+Skins are complete, pre-designed player UIs that package components and styles together:
+
+tsx
+
+```
+<Player.Provider>
+  <VideoSkin>
+    <Video src="video.mp4" />
+  </VideoSkin>
+</Player.Provider>
+```
+
+[Learn more about skins](./skins.md)
+
+### UI components
+
+If you want more control than skins offer you, you can build your own UI from our components.
+
+tsx
+
+```
+<Player.Provider>
+  <Player.Container>
+    <Video src="video.mp4" />
+    <Controls.Root>
+      <PlayButton />
+      {/* ... */}
+    </Controls.Root>
+  </Player.Container>
+</Player.Provider>
+```
+
+To get started with UI components, you might consider [ejecting a skin](../how-to/customize-skins.md) and using its pre-styled components as a foundation.
+
+[Learn more about UI components](./ui-components.md)
+
+[Build your own component](../how-to/build-your-own-component.md)
+
+## 3\. Media
+
+Media components are the components that actually display your media. They’re essentially “players with no UI”. They handle the video/audio rendering and expose a consistent API.
+
+Media components can be format specific (HLS, DASH), service specific (YouTube, Vimeo, Mux), or use case specific (background video).
+
+Note
+
+DASH, YouTube, Vimeo, Mux, and more media elements are currently under development.
+
+tsx
+
+```
+<Player.Provider>
+  <VideoSkin>
+    <HlsJsVideo src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" />
+  </VideoSkin>
+</Player.Provider>
+```
+
+## Presets
+
+**Presets** preconfigure these parts for a specific use case.
+
+The default presets are `@videojs/react/video` and `@videojs/react/audio`, covering the baseline set of controls you’d expect from the HTML `<video>` and `<audio>` tags.
+
+Beyond the defaults, presets target more specific use cases. For example, `/background` includes a media element with autoplay, mute, and loop built in, a skin with no controls, and just the features needed to power it:
+
+tsx
+
+```
+import { createPlayer } from '@videojs/react';
+import { backgroundFeatures, BackgroundVideo, BackgroundVideoSkin } from '@videojs/react/background';
+
+const Player = createPlayer({ features: backgroundFeatures });
+
+function Hero() {
+  return (
+    <Player.Provider>
+      <BackgroundVideoSkin>
+        <BackgroundVideo src="hero.mp4" />
+      </BackgroundVideoSkin>
+    </Player.Provider>
+  );
+}
+```
+
+[Learn more about presets](./presets.md)