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

package/docs/reference/buffering-indicator.md

@@ -0,0 +1,152 @@
+# BufferingIndicator
+
+Loading indicator that displays when the video player is buffering or waiting for data
+
+## Anatomy
+
+tsx
+
+```
+<BufferingIndicator />
+```
+
+## Behavior
+
+Shows a loading indicator when the media is waiting to buffer and not paused, but only after a configurable `delay` (default 500ms). This delay prevents the indicator from flickering during brief stalls. The indicator hides immediately when buffering ends.
+
+## Styling
+
+Hide and show the indicator based on the `data-visible` attribute.
+
+## Examples
+
+### Basic Usage
+
+App.tsx
+
+App.css
+
+```
+import { BufferingIndicator, 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
+        />
+        <BufferingIndicator
+          className="media-buffering-indicator"
+          render={(props, state) => <div {...props}>{state.visible && <div className="spinner" />}</div>}
+        />
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+  display: flex;
+  width: 100%;
+  height: 100%;
+}
+
+.media-buffering-indicator {
+  position: absolute;
+  inset: 0;
+  z-index: 30;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  pointer-events: none;
+}
+
+.spinner {
+  display: none;
+  width: 48px;
+  height: 48px;
+  border: 4px solid rgba(255, 255, 255, 0.3);
+  border-top-color: white;
+  border-radius: 50%;
+  animation: buffering-spin 0.8s linear infinite;
+}
+
+.media-buffering-indicator[data-visible] .spinner {
+  display: block;
+}
+
+@keyframes buffering-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+```
+
+## API Reference
+
+### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`delay`
+
+`number`
+
+`500`
+
+▸
+
+Description
+
+Delay in milliseconds before the indicator becomes visible.
+
+### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+Property
+
+Type
+
+Details
+
+`visible`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the indicator should be visible. True after the delay elapses while media is waiting and not paused.
+
+### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-visible`
+
+▸
+
+Description
+
+Present when the buffering indicator is visible (after delay).

package/docs/reference/captions-button.md

@@ -0,0 +1,216 @@
+# CaptionsButton
+
+Accessible captions toggle button with availability detection and state reflection
+
+## Anatomy
+
+tsx
+
+```
+<CaptionsButton />
+```
+
+## Behavior
+
+Toggles captions and subtitles on and off. The button checks the media’s text track list for tracks with `kind="captions"` or `kind="subtitles"` and reflects availability via `data-availability`.
+
+When no caption or subtitle tracks are present, `data-availability="unavailable"` is set. Use this to hide the button when there are no tracks to toggle.
+
+When `menuTrigger` is enabled and multiple caption or subtitle tracks are available, activation opens the linked captions menu instead of toggling captions directly. React enables `menuTrigger` automatically when a `CaptionsButton` is rendered inside `Menu.Trigger`.
+
+## Styling
+
+Style the button based on active state:
+
+css
+
+```
+media-captions-button[data-active] .icon-on { display: inline; }
+media-captions-button:not([data-active]) .icon-off { display: inline; }
+```
+
+Hide when no caption tracks are available:
+
+css
+
+```
+media-captions-button[data-availability="unavailable"] {
+  display: none;
+}
+```
+
+## Accessibility
+
+Renders a `<button>` with an automatic `aria-label`: “Disable captions” when active, “Enable captions” when inactive. Override with the `label` prop. Keyboard activation: Enter / Space.
+
+In menu-trigger mode, the button behaves as a menu trigger and reflects menu state through the trigger attributes.
+
+## Examples
+
+### Basic Usage
+
+Captions On
+
+App.tsx
+
+App.css
+
+```
+import { CaptionsButton, 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
+        >
+          <track kind="captions" src="/docs/demos/captions-button/captions.vtt" srcLang="en" label="English" />
+        </Video>
+        <CaptionsButton
+          className="media-captions-button"
+          render={(props, state) => (
+            <button {...props}>{state.subtitlesShowing ? 'Captions Off' : 'Captions On'}</button>
+          )}
+        />
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.media-captions-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`
+
+`string | function`
+
+`''`
+
+▸
+
+Description
+
+Custom label for the button.
+
+Type
+
+`string | ((state: CaptionsButtonState) => string)`
+
+`menuTrigger`
+
+`boolean`
+
+`false`
+
+▸
+
+Description
+
+When true with multiple tracks, pointer activation opens a menu instead of toggling. React sets this automatically inside `Menu.Trigger`.
+
+### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+Property
+
+Type
+
+Details
+
+`availability`
+
+`'available' | 'unavailable'`
+
+`subtitlesShowing`
+
+`boolean`
+
+▸
+
+Description
+
+Whether captions/subtitles are currently enabled.
+
+`label`
+
+`string`
+
+### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-active`
+
+▸
+
+Description
+
+Present when captions are enabled.
+
+`data-availability`
+
+`'available' | 'unavailable'`
+
+▸
+
+Description
+
+Indicates captions availability (`available` or `unavailable`).

package/docs/reference/cast-button.md

@@ -0,0 +1,236 @@
+# CastButton
+
+Accessible Cast toggle button with state reflection and keyboard support
+
+## Anatomy
+
+tsx
+
+```
+<CastButton />
+```
+
+## Behavior
+
+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.
+
+## Styling
+
+Style based on cast state and availability:
+
+React renders a `<button>` element. Add a `className` to style it:
+
+css
+
+```
+/* During an active session */
+.cast-button[data-cast-state="connected"] {
+  color: blue;
+}
+
+/* Hide when Cast is unsupported (non-Chromium browsers) */
+.cast-button[data-availability="unsupported"] {
+  display: none;
+}
+```
+
+## Accessibility
+
+Renders a `<button>` with an automatic `aria-label`:
+
+Cast state
+
+Default label
+
+`'disconnected'`
+
+“Start casting”
+
+`'connecting'`
+
+“Connecting”
+
+`'connected'`
+
+“Stop casting”
+
+Override with the `label` prop. Keyboard activation: Enter / Space.
+
+## Examples
+
+### Basic Usage
+
+Start casting
+
+App.tsx
+
+App.css
+
+```
+import { CastButton, createPlayer } 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 BasicUsage() {
+  return (
+    <Player.Provider>
+      <Player.Container className="media-container">
+        <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>
+          )}
+        />
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.media-cast-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);
+}
+
+.media-cast-button[data-availability="unsupported"] {
+  display: none;
+}
+```
+
+## API Reference
+
+### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`disabled`
+
+`boolean`
+
+`false`
+
+▸
+
+Description
+
+Whether the button is disabled.
+
+`label`
+
+`string | function`
+
+`''`
+
+▸
+
+Description
+
+Custom label for the button.
+
+Type
+
+`string | ((state: CastButtonState) => string)`
+
+### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+Property
+
+Type
+
+Details
+
+`castState`
+
+`'disconnected' | 'connecting' | 'conn...`
+
+▸
+
+Type
+
+`'disconnected' | 'connecting' | 'connected'`
+
+`availability`
+
+`'available' | 'unavailable' | 'unsupp...`
+
+▸
+
+Type
+
+`'available' | 'unavailable' | 'unsupported'`
+
+`label`
+
+`string`
+
+### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-cast-state`
+
+`'disconnected' | 'connecting' | 'conn...`
+
+▸
+
+Description
+
+Current remote playback 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 remote playback can be requested on this platform. @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'`