@videojs/react 10.0.0-beta.9 → 10.0.0-rc.2

package/docs/reference/captions-radio-group.md

@@ -0,0 +1,526 @@
+# CaptionsRadioGroup
+
+A menu radio group for selecting caption and subtitle tracks
+
+Creates radio items from the player text track state and selects the showing caption or subtitle track.
+
+## Import
+
+tsx
+
+```
+import { CaptionsRadioGroup } from '@videojs/react/ui/captions-radio-group';
+```
+
+## Anatomy
+
+tsx
+
+```
+<CaptionsRadioGroup.Root>
+  <Menu.Trigger>
+    <CaptionsRadioGroup.Value />
+  </Menu.Trigger>
+  <Menu.Content>
+    <CaptionsRadioGroup.Options
+      renderItem={(props, item) => (
+        <Menu.RadioItem {...props}>
+          {item.label}
+          <Menu.ItemIndicator checked={item.checked} />
+        </Menu.RadioItem>
+      )}
+    />
+  </Menu.Content>
+</CaptionsRadioGroup.Root>
+```
+
+## Behavior
+
+The group is available when the configured media exposes at least one caption or subtitle track. The first generated option is `Off`; selecting it hides captions. Track labels use the track label, then language, then kind. Pass `formatTrack` to customize the visible labels.
+
+`CaptionsRadioGroup.Root` uses [`useCaptionsOptions`](./use-captions-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`. `CaptionsRadioGroup.Options` renders the items, including `Off`: its required `renderItem` callback renders the [`Menu.RadioItem`](./menu.md) root and receives item state containing the translated `label` and current `checked` value. `CaptionsRadioGroup.Value` displays the selected label, typically inside the trigger. `Options` and `Value` render `null` when the [text tracks feature](./feature-text-tracks.md) is not configured.
+
+The `CaptionsRadioGroup` 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-active`
+
+Present / absent
+
+Present when captions are enabled.
+
+`data-disabled`
+
+Present / absent
+
+Present when track selection is disabled.
+
+`data-hidden`
+
+Present / absent
+
+Present when caption or subtitle tracks are unavailable.
+
+`data-availability`
+
+`"available"` / `"unavailable"`
+
+Whether caption or subtitle tracks are available.
+
+Unavailable groups receive the native `hidden` attribute.
+
+## Accessibility
+
+The group uses the menu radio group pattern.
+
+`CaptionsRadioGroup.Options` receives its accessible label from the `label` prop on `CaptionsRadioGroup.Root` or defaults to `Captions`. Override it with `aria-label` or `aria-labelledby` on `CaptionsRadioGroup.Options`.
+
+## Examples
+
+### Basic usage
+
+CaptionsOff
+
+App.tsx
+
+App.css
+
+```
+import { Container, createPlayer, Menu } from '@videojs/react';
+import { CaptionsRadioGroup } from '@videojs/react/ui/captions-radio-group';
+import { Video, videoFeatures } from '@videojs/react/video';
+import type { ReactNode } from 'react';
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+function CaptionsMenu(): ReactNode {
+  return (
+    <Menu.Root side="top" align="end">
+      <CaptionsRadioGroup.Root>
+        <Menu.Trigger className="settings-trigger" render={<button type="button" />}>
+          Captions
+          <CaptionsRadioGroup.Value className="menu-hint" />
+        </Menu.Trigger>
+        <Menu.Popup className="menu">
+          <Menu.Content>
+            <CaptionsRadioGroup.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>
+      </CaptionsRadioGroup.Root>
+    </Menu.Root>
+  );
+}
+
+export default function BasicUsage() {
+  return (
+    <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" />
+          <track kind="subtitles" src="/docs/demos/captions-button/captions.vtt" srcLang="es" label="Spanish" />
+        </Video>
+        <div className="menu-bar">
+          <CaptionsMenu />
+        </div>
+      </Container>
+    </Player>
+  );
+}
+```
+```
+.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 captions option state and shares it with an enclosing menu. Does not render a DOM element.
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`disabled`
+
+`boolean`
+
+`false`
+
+▸
+
+Description
+
+Whether track selection is disabled.
+
+`formatTrack`
+
+`string) | function`
+
+`formatTrackLabel`
+
+▸
+
+Description
+
+Custom formatter for visible track labels.
+
+Type
+
+`((track: MediaTextTrack) => Text | string)`
+
+`label`
+
+`object`
+
+`''`
+
+▸
+
+Description
+
+Custom label for the options group.
+
+Type
+
+`{ key: string; text: string } | string | ((state: CaptionsRadioGroupState) => Text | string)`
+
+#### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+Property
+
+Type
+
+Details
+
+`subtitlesShowing`
+
+`boolean`
+
+▸
+
+Description
+
+Whether captions/subtitles are currently enabled.
+
+`label`
+
+`{ key: string; text: string } | string`
+
+`value`
+
+`string`
+
+▸
+
+Description
+
+Current radio-group value.
+
+`options`
+
+`readonly Option[]`
+
+▸
+
+Description
+
+Ordered options displayed by platform adapters.
+
+`disabled`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the entire option group is disabled.
+
+`hidden`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the option group is hidden because no meaningful selection is available.
+
+`availability`
+
+`'available' | 'unavailable'`
+
+▸
+
+Description
+
+Whether the media exposes a meaningful selection.
+
+#### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-active`
+
+▸
+
+Description
+
+Present when captions are enabled.
+
+`data-disabled`
+
+▸
+
+Description
+
+Present when track selection is disabled.
+
+`data-hidden`
+
+▸
+
+Description
+
+Present when track selection is unavailable.
+
+`data-availability`
+
+`'available' | 'unavailable'`
+
+▸
+
+Description
+
+Indicates captions availability (`available` or `unavailable`).
+
+### 
+
+Options
+
+Renders menu radio items for the player's captions and subtitles tracks.
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`className`
+
+`string | ((state: CaptionsRadioGroupCore.State) => string | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Class name or function returning class name from state.
+
+`render`
+
+`ReactElement | ((props: HTMLProps, state: CaptionsRadioGroupCore.State) => ReactElement | null)`
+
+`—`
+
+▸
+
+Description
+
+Render prop for custom element.
+
+`renderItem`
+
+`((props: CaptionsRadioGroupItemProps, state: CaptionsRadioGroupItemState) => ReactElement)`
+
+`—`
+
+▸
+
+Description
+
+Render one consumer-owned menu radio item for every captions option.
+
+`style`
+
+`CSSProperties | ((state: CaptionsRadioGroupCore.State) => CSSProperties | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Style or function returning style from state.
+
+### 
+
+Value
+
+Displays the selected captions label.
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`className`
+
+`string | ((state: CaptionsOptionsResult) => string | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Class name or function returning class name from state.
+
+`render`
+
+`ReactElement | ((props: HTMLProps, state: CaptionsOptionsResult) => ReactElement | null)`
+
+`—`
+
+▸
+
+Description
+
+Render prop for custom element.
+
+`style`
+
+`CSSProperties | ((state: CaptionsOptionsResult) => CSSProperties | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Style or function returning style from state.