@videojs/react 10.0.0-rc.2 → 10.0.0-rc.3

package/docs/reference/components/live-audio-skin.md

@@ -0,0 +1,36 @@
+# LiveAudioSkin
+
+The live audio preset's default skin, which swaps time controls for a Live button
+
+The default skin of the live audio preset: the audio layout with the time slider and time displays swapped for a Live button. [MinimalLiveAudioSkin](./live-audio-minimal-skin.md) is the same preset’s other variant. See [Skins](../../guides/skins.md) for how packaged skins work and [Presets](../../guides/presets.md) for what the live audio preset ships.
+
+## Import
+
+```tsx
+import { LiveAudioSkin } from '@videojs/react/live-audio';
+import '@videojs/react/live-audio/skin.css';
+```
+
+## Usage
+
+The skin goes between the player and the media element. It renders its controls around the media.
+
+```tsx
+<LiveAudioPlayer>
+  <LiveAudioSkin>
+    <MuxAudio src="live.m3u8" />
+  </LiveAudioSkin>
+</LiveAudioPlayer>
+```
+
+The examples use the [Mux audio element](./mux-audio.md): a plain `<audio>` can’t play HLS in most browsers, and this element reports the live playback state the skin’s Live button needs. See [Play live streams](../../guides/live-streams.md).
+
+## Styling
+
+Packaged skins style themselves and expose a small set of public CSS custom properties. Everything else inside the skin is private and may change between releases. [Customize skins](../../guides/customize-skins.md#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.
+
+## Own the UI
+
+Packaged skins keep their controls and layout inside Video.js. When you need to add, remove, rearrange, or deeply restyle controls, use Shadcn to add the skin source to your project. Its components, layout, styles, and interactions become local files you can change.
+
+- [Install Video.js with Shadcn](../../guides/installation-shadcn.md): Add editable skin source and build a working React or HTML player

package/docs/reference/components/live-button.md

@@ -0,0 +1,167 @@
+# LiveButton
+
+Accessible live indicator button that seeks to the live edge when pressed
+
+## Import
+
+```tsx
+import { LiveButton } from '@videojs/react';
+```
+
+## Anatomy
+
+```tsx
+<LiveButton />
+```
+
+## Behavior
+
+The live button indicates whether playback is at the live edge and acts as a “go to live” control. While playback is behind the edge, clicking seeks to the live edge — the end of the last `seekable` range. At the edge the button goes inactive (`aria-disabled`) and clicking is a no-op.
+
+The button is also disabled whenever it has no live edge to seek to: the media is not live, the `seekable` ranges are still empty (before metadata loads, for example), or the last range ends at `Infinity`. It reports `disabled` in its state, sets `data-disabled`, and ignores activation until a seek target exists. Passing `disabled` forces the same state.
+
+The button combines three player features: [live](../api/feature-live.md) for `liveEdgeStart` and `targetLiveWindow`, [time](../api/feature-time.md) for `currentTime` and the `seek()` action, and [buffer](../api/feature-buffer.md) for `seekable`. All three are included in the `liveVideoFeatures` and `liveAudioFeatures` presets, and the packaged live skins include the button.
+
+Media counts as live while `targetLiveWindow` is not `NaN`. That value is how far behind the live edge viewers can seek: `0` means the stream is watchable only at the edge, and `Infinity` means the stream keeps its recording seekable so viewers can rewind and catch up, like a DVR. For on-demand media the button reports neither `live` nor `liveEdge` and stays inert.
+
+The live edge is not a single instant: it begins 5 seconds before `liveEdgeStart`, the position the media reports live playback starting at, so playback that drifts slightly behind still counts as live. When the media does not report `liveEdgeStart`, the edge is the trailing 10 seconds of the seekable window instead.
+
+Without children, the button renders the translated “Live” badge text.
+
+See [Play live streams](../../guides/live-streams.md) for how live state flows through the player.
+
+## Styling
+
+| Attribute | Values | Description |
+| --- | --- | --- |
+| `data-live` | Present / absent | Present when the stream is live (or DVR) |
+| `data-live-edge` | Present / absent | Present when playback is at the live edge |
+| `data-disabled` | Present / absent | Present when the button is non-interactive (mirrors `aria-disabled`) |
+
+Use `data-live-edge` to color the button red at the edge and gray behind it, and `data-disabled` to fade it while no live-edge target is available:
+
+React renders a `<button>` element with the same data attributes. Add a `className` and use it as the selector:
+
+```css
+.live-button { color: gray; }
+.live-button[data-live-edge] { color: red; }
+.live-button[data-disabled] { opacity: 0.5; }
+```
+
+## Accessibility
+
+Renders a `<button>` with an automatic `aria-label` that updates based on state: “Playing live” at the live edge, “Seek to live edge” while behind it. 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: 'live.playing', text: 'Playing live' }`. When the button is disabled — explicitly, or because no live-edge seek target is available yet — or playback is at the live edge, `aria-disabled="true"` is set and activation is ignored. Keyboard activation: Enter / Space.
+
+## Examples
+
+### Basic Usage
+
+The demo plays a continuously running live stream. Seek backward to move behind the live edge, then press the Live button to jump back to it.
+
+**App.tsx**
+
+```tsx
+import { Container, createPlayer, LiveButton, SeekButton } from '@videojs/react';
+import { liveVideoFeatures } from '@videojs/react/live-video';
+import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
+
+const { Player } = createPlayer({ features: liveVideoFeatures });
+
+export default function BasicUsage() {
+  return (
+    <Player>
+      <Container className="react-live-button-basic">
+        <HlsJsVideo src="https://stream.mux.com/v69RSHhFelSm4701snP22dYz2jICy4E4FUyk02rW4gxRM.m3u8" autoPlay muted playsInline />
+        <div className="react-live-button-basic__buttons">
+          <SeekButton seconds={-30} className="react-live-button-basic__seek">
+            {'⏪'} 30s
+          </SeekButton>
+          <LiveButton className="react-live-button-basic__live">
+            <span className="react-live-button-basic__dot" />
+            Live
+          </LiveButton>
+        </div>
+      </Container>
+    </Player>
+  );
+}
+```
+
+**App.css**
+
+```css
+.react-live-button-basic {
+  position: relative;
+}
+
+.react-live-button-basic video {
+  width: 100%;
+}
+
+.react-live-button-basic__buttons {
+  position: absolute;
+  bottom: 10px;
+  left: 10px;
+  display: flex;
+  gap: 8px;
+}
+
+.react-live-button-basic__seek,
+.react-live-button-basic__live {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding-block: 8px;
+  padding-inline: 20px;
+  color: black;
+  white-space: nowrap;
+  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);
+}
+
+.react-live-button-basic__live[data-live-edge] {
+  cursor: default;
+}
+
+.react-live-button-basic__dot {
+  width: 8px;
+  height: 8px;
+  background: gray;
+  border-radius: 50%;
+}
+
+.react-live-button-basic__live[data-live-edge] .react-live-button-basic__dot {
+  background: red;
+}
+```
+
+## API Reference
+
+### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `disabled` | `boolean` | `false` | Whether the button is disabled. |
+| `label` | `{ key: string; text: string } \| string \| ((state: LiveButtonState) => Text \| string)` | `''` | Custom label for the button. |
+
+### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `label` | `{ key: string; text: string } \| string` | |
+| `live` | `boolean` | Whether the stream is live (or DVR). |
+| `liveEdge` | `boolean` | Whether playback is at the live edge. |
+| `disabled` | `boolean` | Whether seeking to the live edge is temporarily unavailable. |
+
+### Data attributes
+
+| Attribute | Description |
+| --- | --- |
+| `data-live` | Present when the stream is live (or DVR). |
+| `data-live-edge` | Present when playback is at the live edge. |
+| `data-disabled` | Present when the button is non-interactive (mirrors `aria-disabled`). |

package/docs/reference/components/live-video-minimal-skin.md

@@ -0,0 +1,42 @@
+# MinimalLiveVideoSkin
+
+The live video preset's visually lighter skin, closer to a classic control bar
+
+The minimal skin of the live video preset: the same player and the same controls in a visually lighter design, closer to a classic control bar. Like the default skin, it shows a Live button in place of time controls. [LiveVideoSkin](./live-video-skin.md) is the same preset’s other variant. See [Skins](../../guides/skins.md) for how packaged skins work and [Presets](../../guides/presets.md) for what the live video preset ships.
+
+## Import
+
+```tsx
+import { MinimalLiveVideoSkin } from '@videojs/react/live-video';
+import '@videojs/react/live-video/minimal-skin.css';
+```
+
+## Usage
+
+The skin goes between the player and the media element. It renders its controls around the media.
+
+```tsx
+<LiveVideoPlayer>
+  <MinimalLiveVideoSkin>
+    <HlsVideo src="live.m3u8" />
+  </MinimalLiveVideoSkin>
+</LiveVideoPlayer>
+```
+
+The examples use the lightweight [HLS video element](./hls-video.md) because most browsers can’t play HLS streams with a plain `<video>`. See [Play live streams](../../guides/live-streams.md).
+
+## Poster
+
+The skin renders a poster image before playback starts. Pass `renderPoster` to replace it with your own component.
+
+See [Add a poster and loading placeholder](../../guides/poster.md) for complete examples.
+
+## Styling
+
+Packaged skins style themselves and expose a small set of public CSS custom properties. Everything else inside the skin is private and may change between releases. [Customize skins](../../guides/customize-skins.md#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.
+
+## Own the UI
+
+Packaged skins keep their controls and layout inside Video.js. When you need to add, remove, rearrange, or deeply restyle controls, use Shadcn to add the skin source to your project. Its components, layout, styles, and interactions become local files you can change.
+
+- [Install Video.js with Shadcn](../../guides/installation-shadcn.md): Add editable skin source and build a working React or HTML player

package/docs/reference/components/live-video-skin.md

@@ -0,0 +1,42 @@
+# LiveVideoSkin
+
+The live video preset's default skin, which swaps time controls for a Live button
+
+The default skin of the live video preset: the video layout with the time slider and time displays swapped for a Live button. [MinimalLiveVideoSkin](./live-video-minimal-skin.md) is the same preset’s other variant. See [Skins](../../guides/skins.md) for how packaged skins work and [Presets](../../guides/presets.md) for what the live video preset ships.
+
+## Import
+
+```tsx
+import { LiveVideoSkin } from '@videojs/react/live-video';
+import '@videojs/react/live-video/skin.css';
+```
+
+## Usage
+
+The skin goes between the player and the media element. It renders its controls around the media.
+
+```tsx
+<LiveVideoPlayer>
+  <LiveVideoSkin>
+    <HlsVideo src="live.m3u8" />
+  </LiveVideoSkin>
+</LiveVideoPlayer>
+```
+
+The examples use the lightweight [HLS video element](./hls-video.md) because most browsers can’t play HLS streams with a plain `<video>`. See [Play live streams](../../guides/live-streams.md).
+
+## Poster
+
+The skin renders a poster image before playback starts. Pass `renderPoster` to replace it with your own component.
+
+See [Add a poster and loading placeholder](../../guides/poster.md) for complete examples.
+
+## Styling
+
+Packaged skins style themselves and expose a small set of public CSS custom properties. Everything else inside the skin is private and may change between releases. [Customize skins](../../guides/customize-skins.md#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.
+
+## Own the UI
+
+Packaged skins keep their controls and layout inside Video.js. When you need to add, remove, rearrange, or deeply restyle controls, use Shadcn to add the skin source to your project. Its components, layout, styles, and interactions become local files you can change.
+
+- [Install Video.js with Shadcn](../../guides/installation-shadcn.md): Add editable skin source and build a working React or HTML player

package/docs/reference/components/llms.txt

@@ -0,0 +1,122 @@
+# Video.js v10 — React Components
+
+> API reference for skins, media components, extensions, and interface components. Bundled with `@videojs/react` v10.0.0-rc.3. Links are relative paths to files in this directory.
+
+## Layout
+
+API reference for the components that establish a player and lay out its interface.
+
+- [Player](./player.md): The state boundary — creates a store and broadcasts it to all descendants.
+- [Container](./player-container.md): The player's visual and interaction surface for layout, fullscreen, focus, and user activity.
+- [Controls](./controls.md): Container component for composing and auto-hiding video player controls on user interaction
+
+## Skins
+
+API reference for the packaged skins each preset ships.
+
+- [VideoSkin](./video-skin.md): The video preset's default skin with the modern, frosted look
+- [MinimalVideoSkin](./video-minimal-skin.md): The video preset's visually lighter skin, closer to a classic control bar
+- [AudioSkin](./audio-skin.md): The audio preset's default skin with the modern, frosted look
+- [MinimalAudioSkin](./audio-minimal-skin.md): The audio preset's visually lighter skin, closer to a classic control bar
+- [LiveVideoSkin](./live-video-skin.md): The live video preset's default skin, which swaps time controls for a Live button
+- [MinimalLiveVideoSkin](./live-video-minimal-skin.md): The live video preset's visually lighter skin, closer to a classic control bar
+- [LiveAudioSkin](./live-audio-skin.md): The live audio preset's default skin, which swaps time controls for a Live button
+- [MinimalLiveAudioSkin](./live-audio-minimal-skin.md): The live audio preset's visually lighter skin, closer to a classic control bar
+- [BackgroundVideoSkin](./background-video-skin.md): The background preset's chrome-less skin for ambient video
+
+## Media
+
+API reference for media components that handle streaming protocols and playback.
+
+- [Audio](./audio.md): Native audio playback that can provide media to a Video.js player
+- [BackgroundVideo](./background-video.md): Decorative background video element with automatic muting and looping
+- [CloudflareVideo](./cloudflare-video.md): Video component that plays Cloudflare Stream videos through the Stream player
+- [DashVideo](./dash-video.md): DASH video element powered by dash.js for adaptive bitrate streaming
+- [HlsAudio](./hls-audio.md): Audio-only HLS element that plays the audio rendition of an HLS stream
+- [HlsBackgroundVideo](./hls-background-video.md): HLS background video without controls, audio, captions, or adaptive quality
+- [HlsVideo](./hls-video.md): Lightweight HLS video element with minimal bundle size
+- [HlsJsVideo](./hlsjs-video.md): HLS video element powered by hls.js for adaptive bitrate streaming
+- [MuxAudio](./mux-audio.md): Audio element for Mux-hosted HLS streams
+- [MuxBackgroundVideo](./mux-background-video.md): Mux-specific name for the HLS background video component
+- [MuxVideo](./mux-video.md): Video element for Mux-hosted HLS streams
+- [NativeHlsVideo](./native-hls-video.md): HLS video element using the browser's built-in HLS support
+- [ShakaVideo](./shaka-video.md): Video element powered by Shaka Player for DASH, HLS, and progressive playback with DRM
+- [SpotifyAudio](./spotify-audio.md): Audio component that plays Spotify tracks, episodes, playlists, and shows through the Spotify embed
+- [TikTokVideo](./tiktok-video.md): Video component that plays TikTok videos through the TikTok embed player
+- [TwitchVideo](./twitch-video.md): Video component that plays Twitch videos and live channels through the Twitch embed player
+- [Video](./video.md): Native video playback that can provide media to a Video.js player
+- [VimeoVideo](./vimeo-video.md): Video component that plays Vimeo videos and live events through the Vimeo player
+- [WistiaVideo](./wistia-video.md): Video component that plays Wistia-hosted videos through Wistia's web component
+- [YouTubeVideo](./youtube-video.md): Video component that plays YouTube videos and playlists through the YouTube IFrame player
+
+## Extensions
+
+API reference for extensions that connect external services to the player.
+
+- [GoogleCast](./google-cast.md): Options for the Google Cast extension that configures the receiver and load request
+- [MuxData](./mux-data.md): Options for the Mux Data extension that monitors playback quality
+
+## Buttons
+
+API reference for the button components that trigger playback actions.
+
+- [PlayButton](./play-button.md): Accessible play/pause button with keyboard support and customizable rendering
+- [MuteButton](./mute-button.md): Accessible mute/unmute button with keyboard support and volume state reflection
+- [SeekButton](./seek-button.md): Accessible seek button for skipping forward or backward by a configurable number of seconds
+- [FullscreenButton](./fullscreen-button.md): Accessible fullscreen toggle button with keyboard support and state reflection
+- [PiPButton](./pip-button.md): Accessible picture-in-picture toggle button with keyboard support and state reflection
+- [CaptionsButton](./captions-button.md): Accessible captions toggle button with availability detection and state reflection
+- [PlaybackRateButton](./playback-rate-button.md): A button that cycles through playback speed rates
+- [LiveButton](./live-button.md): Accessible live indicator button that seeks to the live edge when pressed
+- [AirPlayButton](./airplay-button.md): Accessible AirPlay toggle button that opens the WebKit playback target picker and reflects session state
+- [CastButton](./cast-button.md): Accessible Cast toggle button with state reflection and keyboard support
+
+## Sliders
+
+API reference for the slider components that scrub time and adjust volume.
+
+- [Slider](./slider.md): A composable slider component with track, fill, thumb, preview, and value parts
+- [TimeSlider](./time-slider.md): A slider component for seeking through media playback time
+- [VolumeSlider](./volume-slider.md): A slider component for controlling media playback volume
+
+## Menus
+
+API reference for menus, popovers, and the radio groups that pick tracks, quality, and speed.
+
+- [Menu](./menu.md): A composable menu component for settings, option selection, and actions
+- [Popover](./popover.md): A popover component for displaying contextual content anchored to a trigger
+- [VolumePopover](./volume-popover.md): A volume-aware popover that keeps mute available when volume level controls are unavailable
+- [AudioTrackRadioGroup](./audio-track-radio-group.md): A menu radio group for selecting an audio track
+- [CaptionsRadioGroup](./captions-radio-group.md): A menu radio group for selecting caption and subtitle tracks
+- [PlaybackRateRadioGroup](./playback-rate-radio-group.md): A menu radio group for selecting playback speed
+- [QualityRadioGroup](./quality-radio-group.md): A menu radio group for selecting video quality
+
+## Display
+
+API reference for components that display player state, media metadata, and previews.
+
+- [Time](./time.md): Time display components for showing current time, duration, and remaining time in a video player
+- [Title](./title.md): Displays the resolved content title for the current media
+- [Poster](./poster.md): Poster image component that displays a thumbnail until video playback starts
+- [Thumbnail](./thumbnail.md): Time-based thumbnail preview component for timeline scrubbing and hover previews
+- [Tooltip](./tooltip.md): A tooltip component for displaying contextual labels on hover and focus
+- [BufferingIndicator](./buffering-indicator.md): Loading indicator that displays when the video player is buffering or waiting for data
+- [SeekIndicator](./seek-indicator.md): A temporary visual indicator for keyboard and gesture seeking
+- [StatusIndicator](./status-indicator.md): Display temporary visual feedback for keyboard and gesture actions
+- [VolumeIndicator](./volume-indicator.md): Display temporary visual feedback for keyboard and gesture volume actions
+
+## Dialogs
+
+API reference for modal dialogs, alerts, and playback error surfaces.
+
+- [Dialog](./dialog.md): A modal dialog for application content, including players opened from a thumbnail
+- [AlertDialog](./alert-dialog.md): A modal alert dialog for urgent messages that require acknowledgement
+- [ErrorDialog](./error-dialog.md): An alert dialog that presents and dismisses playback errors
+
+## Behavior
+
+API reference for the non-visual components that add gestures, hotkeys, and announcements.
+
+- [Gesture](./gesture.md): Map tap and double-tap gestures to player actions
+- [Hotkey](./hotkey.md): Register a keyboard shortcut that invokes a player action
+- [StatusAnnouncer](./status-announcer.md): Announce player state changes through a persistent status live region