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

package/docs/reference/components/alert-dialog.md

@@ -0,0 +1,265 @@
+# AlertDialog
+
+A modal alert dialog for urgent messages that require acknowledgement
+
+## Import
+
+```tsx
+import { AlertDialog } from '@videojs/react';
+```
+
+## Anatomy
+
+```tsx
+<AlertDialog.Root>
+  <AlertDialog.Backdrop />
+  <AlertDialog.Popup>
+    <AlertDialog.Title />
+    <AlertDialog.Description />
+    <AlertDialog.Close />
+  </AlertDialog.Popup>
+</AlertDialog.Root>
+```
+
+## Behavior
+
+Use an alert dialog for an urgent message that interrupts the user and requires acknowledgement. Your application controls when it opens and supplies its content.
+
+`AlertDialog.Root` adds alert semantics, while the other `AlertDialog` parts are re-exported from [`Dialog`](./dialog.md). For general modal content, including a player opened from a thumbnail, use `Dialog.Root` instead.
+
+Use `open` with `onOpenChange` for controlled state, or `defaultOpen` for uncontrolled state. `Root` provides state without rendering an element, while `Popup` renders only while the dialog is open.
+
+The close part and Escape close the dialog. The dialog stays rendered during a closing transition, then restores focus to the element that was focused before it opened.
+
+## Styling
+
+Use the open and transition data attributes to style visibility and animations:
+
+| Attribute | Description |
+| --- | --- |
+| `data-open` | Present while the dialog is open, including its closing transition |
+| `data-starting-style` | Present at the start of the opening transition |
+| `data-ending-style` | Present during the closing transition |
+
+React renders separate backdrop and popup elements. Add a `className` to each part and style them independently:
+
+```css
+.alert-dialog-backdrop[data-starting-style],
+.alert-dialog-backdrop[data-ending-style],
+.alert-dialog-popup[data-starting-style],
+.alert-dialog-popup[data-ending-style] {
+  opacity: 0;
+}
+```
+
+## Accessibility
+
+The dialog uses `role="alertdialog"` and `aria-modal="true"`. The title and description receive generated IDs that are connected with `aria-labelledby` and `aria-describedby`. Focus moves into the dialog when it opens, stays within it while open, and returns to the previously focused element when it closes. Content outside the dialog is inert while it is open. Pressing Escape closes the dialog.
+
+## Examples
+
+### Basic usage
+
+**App.tsx**
+
+```tsx
+import { AlertDialog } from '@videojs/react';
+import { useState } from 'react';
+
+export default function BasicUsage() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <div className="react-alert-dialog-basic">
+      <button className="react-alert-dialog-basic__trigger" type="button" onClick={() => setOpen(true)}>
+        Open alert dialog
+      </button>
+      <AlertDialog.Root open={open} onOpenChange={setOpen}>
+        <AlertDialog.Backdrop className="react-alert-dialog-basic__backdrop" />
+        <AlertDialog.Popup className="react-alert-dialog-basic__dialog">
+          <AlertDialog.Title className="react-alert-dialog-basic__title">Stop playback?</AlertDialog.Title>
+          <AlertDialog.Description className="react-alert-dialog-basic__description">
+            Your current playback position will be lost.
+          </AlertDialog.Description>
+          <AlertDialog.Close className="react-alert-dialog-basic__close">Continue</AlertDialog.Close>
+        </AlertDialog.Popup>
+      </AlertDialog.Root>
+    </div>
+  );
+}
+```
+
+**App.css**
+
+```css
+.react-alert-dialog-basic {
+  position: relative;
+  display: grid;
+  place-items: center;
+  min-height: 240px;
+  overflow: hidden;
+  background: #111827;
+  border-radius: 12px;
+}
+
+.react-alert-dialog-basic__trigger,
+.react-alert-dialog-basic__close {
+  padding: 8px 16px;
+  color: #111827;
+  cursor: pointer;
+  background: #fff;
+  border: 0;
+  border-radius: 9999px;
+}
+
+.react-alert-dialog-basic__backdrop {
+  position: absolute;
+  inset: 0;
+  background: rgb(3 7 18 / 92%);
+  transition: opacity 150ms ease;
+}
+
+.react-alert-dialog-basic__dialog {
+  position: absolute;
+  inset: 0;
+  z-index: 1;
+  display: grid;
+  gap: 12px;
+  place-content: center;
+  padding: 32px;
+  color: #fff;
+  text-align: center;
+  transition: opacity 150ms ease;
+}
+
+.react-alert-dialog-basic__backdrop[data-starting-style],
+.react-alert-dialog-basic__backdrop[data-ending-style],
+.react-alert-dialog-basic__dialog[data-starting-style],
+.react-alert-dialog-basic__dialog[data-ending-style] {
+  opacity: 0;
+}
+
+.react-alert-dialog-basic__title {
+  font-size: 20px;
+  font-weight: 600;
+}
+
+.react-alert-dialog-basic__description {
+  color: #d1d5db;
+}
+
+.react-alert-dialog-basic__close {
+  justify-self: center;
+}
+```
+
+## API Reference
+
+### Root
+
+Manages alert dialog state and provides it to the shared dialog parts.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `closeOnEscape` | `boolean` | — | Whether pressing Escape closes the dialog. |
+| `defaultOpen` | `boolean` | — | Initial open state for uncontrolled usage. |
+| `open` | `boolean` | — | Controlled open state. When set, the consumer is responsible for toggling. |
+
+#### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `transitionStarting` | `boolean` | Whether the open transition is in progress. |
+| `transitionEnding` | `boolean` | Whether the close transition is in progress. |
+| `open` | `boolean` | Whether the dialog is currently open. |
+| `status` | `'idle' \| 'starting' \| 'ending'` | Current phase of the transition lifecycle. |
+| `titleId` | `string \| undefined` | Element ID of the dialog title, used for `aria-labelledby`. |
+| `descriptionId` | `string \| undefined` | Element ID of the dialog description, used for `aria-describedby`. |
+
+### Backdrop
+
+Presentational layer behind a dialog while it is rendered, including its exit transition.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string \| ((state: DialogState) => string \| undefined)` | — | Class name or function returning class name from state. |
+| `render` | `ReactElement \| ((props: HTMLProps, state: DialogState) => ReactElement \| null)` | — | Render prop for custom element. |
+| `style` | `CSSProperties \| ((state: DialogState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |
+
+#### Data attributes
+
+| Attribute | Description |
+| --- | --- |
+| `data-open` | Present when the dialog is open. |
+| `data-starting-style` | Present during the open transition. |
+| `data-ending-style` | Present during the close transition. |
+
+### Close
+
+Renders a button that closes the dialog.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string \| ((state: DialogState) => string \| undefined)` | — | Class name or function returning class name from state. |
+| `render` | `ReactElement \| ((props: HTMLProps, state: DialogState) => ReactElement \| null)` | — | Render prop for custom element. |
+| `style` | `CSSProperties \| ((state: DialogState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |
+
+#### Data attributes
+
+| Attribute | Description |
+| --- | --- |
+| `data-open` | Present when the dialog is open. |
+| `data-starting-style` | Present during the open transition. |
+| `data-ending-style` | Present during the close transition. |
+
+### Description
+
+Renders the description announced with the dialog.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string \| ((state: DialogState) => string \| undefined)` | — | Class name or function returning class name from state. |
+| `render` | `ReactElement \| ((props: HTMLProps, state: DialogState) => ReactElement \| null)` | — | Render prop for custom element. |
+| `style` | `CSSProperties \| ((state: DialogState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |
+
+### Popup
+
+Renders the modal dialog while it is open.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string \| ((state: DialogState) => string \| undefined)` | — | Class name or function returning class name from state. |
+| `render` | `ReactElement \| ((props: HTMLProps, state: DialogState) => ReactElement \| null)` | — | Render prop for custom element. |
+| `style` | `CSSProperties \| ((state: DialogState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |
+
+#### Data attributes
+
+| Attribute | Description |
+| --- | --- |
+| `data-open` | Present when the dialog is open. |
+| `data-starting-style` | Present during the open transition. |
+| `data-ending-style` | Present during the close transition. |
+
+### Title
+
+Renders the heading that labels the dialog.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string \| ((state: DialogState) => string \| undefined)` | — | Class name or function returning class name from state. |
+| `render` | `ReactElement \| ((props: HTMLProps, state: DialogState) => ReactElement \| null)` | — | Render prop for custom element. |
+| `style` | `CSSProperties \| ((state: DialogState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

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

@@ -0,0 +1,34 @@
+# MinimalAudioSkin
+
+The audio preset's visually lighter skin, closer to a classic control bar
+
+The minimal skin of the audio preset: the same player and the same controls in a visually lighter design, closer to a classic control bar. [AudioSkin](./audio-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 audio preset ships.
+
+## Import
+
+```tsx
+import { MinimalAudioSkin } from '@videojs/react/audio';
+import '@videojs/react/audio/minimal-skin.css';
+```
+
+## Usage
+
+The skin goes between the player and the media element. It renders its controls around the media.
+
+```tsx
+<AudioPlayer>
+  <MinimalAudioSkin>
+    <Audio src="audio.mp3" />
+  </MinimalAudioSkin>
+</AudioPlayer>
+```
+
+## 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/audio-skin.md

@@ -0,0 +1,34 @@
+# AudioSkin
+
+The audio preset's default skin with the modern, frosted look
+
+The default skin of the audio preset: the control layout for on-demand audio with the modern, frosted look. [MinimalAudioSkin](./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 audio preset ships.
+
+## Import
+
+```tsx
+import { AudioSkin } from '@videojs/react/audio';
+import '@videojs/react/audio/skin.css';
+```
+
+## Usage
+
+The skin goes between the player and the media element. It renders its controls around the media.
+
+```tsx
+<AudioPlayer>
+  <AudioSkin>
+    <Audio src="audio.mp3" />
+  </AudioSkin>
+</AudioPlayer>
+```
+
+## 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/audio-track-radio-group.md

@@ -0,0 +1,264 @@
+# AudioTrackRadioGroup
+
+A menu radio group for selecting an audio track
+
+Creates radio items from the player audio track state and selects the enabled track.
+
+## Import
+
+```tsx
+import { AudioTrackRadioGroup } from '@videojs/react/ui/audio-track-radio-group';
+```
+
+## Anatomy
+
+```tsx
+<AudioTrackRadioGroup.Root>
+  <Menu.Trigger>
+    <AudioTrackRadioGroup.Value />
+  </Menu.Trigger>
+  <Menu.Content>
+    <AudioTrackRadioGroup.Options
+      renderItem={(props, item) => (
+        <Menu.RadioItem {...props}>
+          {item.label}
+          <Menu.ItemIndicator checked={item.checked} />
+        </Menu.RadioItem>
+      )}
+    />
+  </Menu.Content>
+</AudioTrackRadioGroup.Root>
+```
+
+## 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.
+
+`AudioTrackRadioGroup.Root` uses [`useAudioTrackOptions`](../api/use-audio-track-options.md) to own selection and renders no element. Wrap the menu’s `Menu.Trigger` and `Menu.Content` in it so the trigger inherits the group’s disabled and hidden state and exposes `data-availability`. `AudioTrackRadioGroup.Options` renders the items: its required `renderItem` callback renders the [`Menu.RadioItem`](./menu.md) root and receives item state containing the translated `label` and current `checked` value. `AudioTrackRadioGroup.Value` displays the selected label, typically inside the trigger. `Options` and `Value` render `null` when the [audio track feature](../api/feature-audio-track.md) is not configured.
+
+The `AudioTrackRadioGroup` export from the `@videojs/react` root is a compatibility component that composes `Root` and `Options` behind the former single-component props. Prefer the parts for new code.
+
+## Styling
+
+| Attribute | Values | Description |
+| --- | --- | --- |
+| `data-audio-track` | `string` | Current audio track value. |
+| `data-disabled` | Present / absent | Present when audio track selection is disabled. |
+| `data-hidden` | Present / absent | Present when multiple audio tracks are unavailable. |
+| `data-availability` | `"available"` / `"unavailable"` | Whether multiple audio tracks are available. |
+
+Unavailable groups receive the native `hidden` attribute.
+
+## Accessibility
+
+The group uses the menu radio group pattern.
+
+`AudioTrackRadioGroup.Options` receives its accessible label from the `label` prop on `AudioTrackRadioGroup.Root` or defaults to `Audio`. Override it with `aria-label` or `aria-labelledby` on `AudioTrackRadioGroup.Options`.
+
+## Examples
+
+### Basic usage
+
+**App.tsx**
+
+```tsx
+import { Container, createPlayer, Menu } from '@videojs/react';
+import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
+import { AudioTrackRadioGroup } from '@videojs/react/ui/audio-track-radio-group';
+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 {
+  return (
+    <Menu.Root side="top" align="end">
+      <AudioTrackRadioGroup.Root>
+        <Menu.Trigger className="settings-trigger" render={<button type="button" />}>
+          Audio
+          <AudioTrackRadioGroup.Value className="menu-hint" />
+        </Menu.Trigger>
+        <Menu.Popup className="menu">
+          <Menu.Content>
+            <AudioTrackRadioGroup.Options
+              className="menu-group"
+              renderItem={(props, item) => (
+                <Menu.RadioItem {...props} className="menu-item">
+                  {item.label}
+                  <Menu.ItemIndicator checked={item.checked} forceMount className="menu-indicator">
+                    ✓
+                  </Menu.ItemIndicator>
+                </Menu.RadioItem>
+              )}
+            />
+          </Menu.Content>
+        </Menu.Popup>
+      </AudioTrackRadioGroup.Root>
+    </Menu.Root>
+  );
+}
+
+export default function BasicUsage() {
+  return (
+    <Player>
+      <Container className="media-container">
+        <HlsJsVideo src={src} autoPlay crossOrigin="anonymous" muted playsInline loop />
+        <div className="menu-bar">
+          <AudioMenu />
+        </div>
+      </Container>
+    </Player>
+  );
+}
+```
+
+**App.css**
+
+```css
+.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-hint {
+  margin-left: 8px;
+  color: rgba(0, 0, 0, 0.6);
+}
+
+.menu-hint:empty {
+  display: none;
+}
+
+.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;
+}
+```
+
+## API Reference
+
+### Root
+
+Owns audio-track option state and shares it with an enclosing menu. Does not render a DOM element.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `disabled` | `boolean` | `false` | Whether audio track selection is disabled. |
+| `formatTrack` | `((track: MediaAudioTrack) => Text \| string)` | `formatTrackLabel` | Custom formatter for visible track labels. |
+| `label` | `{ key: string; text: string } \| string \| ((state: AudioTrackRadioGroupState) => Text \| string)` | `''` | Custom label for the options group. |
+
+#### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `label` | `{ key: string; text: string } \| string` | |
+| `value` | `string` | Current radio-group value. |
+| `options` | `readonly Option[]` | Ordered options displayed by platform adapters. |
+| `disabled` | `boolean` | Whether the entire option group is disabled. |
+| `hidden` | `boolean` | Whether the option group is hidden because no meaningful selection is available. |
+| `availability` | `'available' \| 'unavailable'` | Whether the media exposes a meaningful selection. |
+
+#### Data attributes
+
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-audio-track` | `string` | Current audio track value. |
+| `data-disabled` | — | Present when audio track selection is disabled. |
+| `data-hidden` | — | Present when audio track selection is unavailable. |
+| `data-availability` | `'available' \| 'unavailable'` | Indicates audio track availability (`available` or `unavailable`). |
+
+### Options
+
+Renders menu radio items for the player's available audio tracks.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string \| ((state: AudioTrackRadioGroupState) => string \| undefined)` | — | Class name or function returning class name from state. |
+| `render` | `ReactElement \| ((props: HTMLProps, state: AudioTrackRadioGroupState) => ReactElement \| null)` | — | Render prop for custom element. |
+| `renderItem` | `((props: AudioTrackRadioGroupItemProps, state: AudioTrackRadioGroupItemState) => ReactElement)` | — | Render one consumer-owned menu radio item for every audio track. |
+| `style` | `CSSProperties \| ((state: AudioTrackRadioGroupState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |
+
+### Value
+
+Displays the selected audio-track label.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string \| ((state: AudioTrackOptionsResult) => string \| undefined)` | — | Class name or function returning class name from state. |
+| `render` | `ReactElement \| ((props: HTMLProps, state: AudioTrackOptionsResult) => ReactElement \| null)` | — | Render prop for custom element. |
+| `style` | `CSSProperties \| ((state: AudioTrackOptionsResult) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

package/docs/reference/components/audio.md

@@ -0,0 +1,75 @@
+# Audio
+
+Native audio playback that can provide media to a Video.js player
+
+## Import
+
+Import `Audio` from the audio preset:
+
+```tsx
+import { Audio } from '@videojs/react/audio';
+```
+
+## Anatomy
+
+```tsx
+<Audio>
+  <source />
+</Audio>
+```
+
+## Use with a player
+
+Place `Audio` anywhere inside an `AudioPlayer`, or inside another Video.js `Player` configured for audio. It becomes that player’s media provider automatically. Outside a player, `Audio` behaves as a standalone native `<audio>`.
+
+## Native behavior
+
+Video.js does not replace the native audio API. Use `src` for one URL or add child [`<source>` elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/source) when the browser should choose between candidates. See [Media sources](../../guides/media-sources.md) when you need an HLS, Mux, Spotify, or other playback adapter.
+
+`Audio` forwards native attributes, event handlers, and children to the underlying `<audio>`. Its `ref` resolves to the `HTMLAudioElement`.
+
+See MDN for the complete [`<audio>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/audio), [`HTMLAudioElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLAudioElement), and shared [`HTMLMediaElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement) APIs.
+
+## Examples
+
+### Basic Usage
+
+This native audio element uses a child source and browser controls while providing media to the surrounding Video.js player.
+
+**App.tsx**
+
+```tsx
+import { Container } from '@videojs/react';
+import { Audio, AudioPlayer } from '@videojs/react/audio';
+
+import './BasicUsage.css';
+
+export default function BasicUsage() {
+  return (
+    <AudioPlayer>
+      <Container className="react-audio-basic">
+        <Audio className="react-audio-basic__media" controls preload="metadata">
+          <source src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/audio.m4a" />
+        </Audio>
+      </Container>
+    </AudioPlayer>
+  );
+}
+```
+
+**App.css**
+
+```css
+.react-audio-basic {
+  display: grid;
+  width: 100%;
+  padding: 24px;
+  background: #e5e7eb;
+  border-radius: 8px;
+  place-items: center;
+}
+
+.react-audio-basic__media {
+  width: 100%;
+}
+```