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

package/docs/reference/menu.md

@@ -0,0 +1,1194 @@
+# Menu
+
+A composable menu component for settings, option selection, and actions
+
+## Anatomy
+
+A submenu is a menu inside another menu. The submenu trigger lives in the parent list, and the submenu content is the next view.
+
+tsx
+
+```
+<Menu.Root>
+  <Menu.Trigger />
+  <Menu.Content>
+    <Menu.View>
+      {/* Parent menu item that opens a submenu */}
+      <Menu.Root>
+        {/* Submenu trigger */}
+        <Menu.Trigger>
+          <Menu.ItemValue />
+        </Menu.Trigger>
+
+        {/* Submenu content */}
+        <Menu.Content>
+          <Menu.Back />
+          <Menu.RadioGroup>
+            <Menu.GroupLabel />
+            <Menu.RadioItem>
+              <Menu.ItemIndicator />
+            </Menu.RadioItem>
+          </Menu.RadioGroup>
+        </Menu.Content>
+      </Menu.Root>
+
+      {/* Other parent menu items */}
+      <Menu.Group>
+        <Menu.GroupLabel />
+        <Menu.CheckboxItem>
+          <Menu.ItemIndicator />
+        </Menu.CheckboxItem>
+      </Menu.Group>
+      <Menu.Separator />
+      <Menu.Item />
+    </Menu.View>
+  </Menu.Content>
+</Menu.Root>
+```
+
+## Behavior
+
+Menus open from a trigger and close when you select an item, click outside, move focus away, or press Escape. Root menus are positioned against their trigger with `side` and `align`.
+
+Create a submenu by putting another menu inside the root menu’s content. Its trigger stays in the root list, and its content becomes the next view. In HTML, give the submenu a matching `id` and point the trigger at it with `commandfor`. Wrap the root list in `Menu.View` or `<media-menu-view>` when the root list and submenus share one animated viewport.
+
+Set `type="playback-rate"`, `type="quality"`, `type="audio-track"`, or `type="captions"` on a submenu trigger when it represents a media setting. `Menu.ItemValue` and `<media-menu-item-value>` read that setting context and display the current value, such as `1.5x`, `Auto`, `English`, or `Off`. See [QualityRadioGroup](./quality-radio-group.md) and [AudioTrackRadioGroup](./audio-track-radio-group.md) for the generated option groups.
+
+## Styling
+
+Use data attributes to style open state, highlighted items, selected radio items, and submenu views:
+
+`data-highlighted` is added to the current menu item. The highlighted item is the item that keyboard selection will act on. It changes when the menu opens, when the pointer moves over another item, when the user presses arrow keys, or when type-ahead search finds a match.
+
+css
+
+```
+.menu[data-open] {
+  opacity: 1;
+}
+
+.menu-item[data-highlighted] {
+  background: rgba(255, 255, 255, 0.16);
+}
+
+[role="menuitemradio"][aria-checked="true"] {
+  font-weight: 600;
+}
+```
+
+## Accessibility
+
+Menu content renders with `role="menu"`. Items use `menuitem`, `menuitemradio`, or `menuitemcheckbox` roles. Radio and checkbox items reflect selection with `aria-checked`.
+
+Keyboard controls:
+
+*   Enter / Space: Select the highlighted item.
+*   Arrow Up / Arrow Down: Move between items.
+*   Arrow Right: Open a submenu.
+*   Arrow Left: Return to the parent menu.
+*   Escape: Close the root menu or return from a submenu.
+
+Use `Menu.GroupLabel` or `<media-menu-group-label>` inside grouped choices so the group receives an accessible label.
+
+## Examples
+
+### Basic usage
+
+Settings
+
+App.tsx
+
+App.css
+
+```
+import {
+  createPlayer,
+  Menu,
+  useAudioTrackOptions,
+  useCaptionsOptions,
+  usePlaybackRateOptions,
+  useQualityOptions,
+} from '@videojs/react';
+import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
+import { videoFeatures } from '@videojs/react/video';
+import type { ReactNode } from 'react';
+
+const Player = createPlayer({ features: videoFeatures });
+const src = 'https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4.m3u8';
+
+function SettingsMenu(): ReactNode {
+  const playbackRate = usePlaybackRateOptions();
+  const quality = useQualityOptions();
+  const audioTrack = useAudioTrackOptions();
+  const captions = useCaptionsOptions();
+  const hasPlaybackRate = playbackRate?.state.availability === 'available';
+  const hasQuality = quality?.state.availability === 'available';
+  const hasAudioTrack = audioTrack?.state.availability === 'available';
+  const hasCaptions = captions?.state.availability === 'available';
+
+  if (!hasPlaybackRate && !hasQuality && !hasAudioTrack && !hasCaptions) return null;
+
+  return (
+    <Menu.Root side="top" align="end">
+      <Menu.Trigger className="settings-trigger" aria-label="Settings" render={<button type="button" />}>
+        Settings
+      </Menu.Trigger>
+      <Menu.Content className="menu">
+        <Menu.View className="menu-panel">
+          {hasQuality ? (
+            <Menu.Root>
+              <Menu.Trigger
+                type="quality"
+                className="menu-item"
+                render={(props) => (
+                  <div {...props}>
+                    <span>Quality</span>
+                    <span className="menu-value">
+                      <Menu.ItemValue />
+                      <span aria-hidden="true">›</span>
+                    </span>
+                  </div>
+                )}
+              />
+              <Menu.Content className="menu-panel">
+                <Menu.Back className="menu-back">
+                  <span aria-hidden="true">‹</span>
+                  Quality
+                </Menu.Back>
+                <Menu.RadioGroup
+                  className="menu-group"
+                  value={quality.value}
+                  onValueChange={quality.setValue}
+                  aria-label="Quality"
+                >
+                  {quality.options.map((option) => (
+                    <Menu.RadioItem
+                      key={option.value}
+                      value={option.value}
+                      disabled={option.disabled}
+                      className="menu-item"
+                    >
+                      <span>
+                        {option.label}
+                        {option.tier ? <sup className="menu-tier">{option.tier}</sup> : null}
+                      </span>
+                      {option.badge ? <span className="menu-badge">{option.badge}</span> : null}
+                      <Menu.ItemIndicator
+                        checked={option.value === quality.value}
+                        forceMount
+                        className="menu-indicator"
+                      >
+                        ✓
+                      </Menu.ItemIndicator>
+                    </Menu.RadioItem>
+                  ))}
+                </Menu.RadioGroup>
+              </Menu.Content>
+            </Menu.Root>
+          ) : null}
+
+          {hasAudioTrack ? (
+            <Menu.Root>
+              <Menu.Trigger
+                type="audio-track"
+                className="menu-item"
+                render={(props) => (
+                  <div {...props}>
+                    <span>Audio</span>
+                    <span className="menu-value">
+                      <Menu.ItemValue />
+                      <span aria-hidden="true">›</span>
+                    </span>
+                  </div>
+                )}
+              />
+              <Menu.Content className="menu-panel">
+                <Menu.Back className="menu-back">
+                  <span aria-hidden="true">‹</span>
+                  Audio
+                </Menu.Back>
+                <Menu.RadioGroup
+                  className="menu-group"
+                  value={audioTrack.value}
+                  onValueChange={audioTrack.setValue}
+                  aria-label="Audio tracks"
+                >
+                  {audioTrack.options.map((option) => (
+                    <Menu.RadioItem
+                      key={option.value}
+                      value={option.value}
+                      disabled={option.disabled}
+                      className="menu-item"
+                    >
+                      <span>{option.label}</span>
+                      <Menu.ItemIndicator
+                        checked={option.value === audioTrack.value}
+                        forceMount
+                        className="menu-indicator"
+                      >
+                        ✓
+                      </Menu.ItemIndicator>
+                    </Menu.RadioItem>
+                  ))}
+                </Menu.RadioGroup>
+              </Menu.Content>
+            </Menu.Root>
+          ) : null}
+
+          {hasPlaybackRate ? (
+            <Menu.Root>
+              <Menu.Trigger
+                type="playback-rate"
+                className="menu-item"
+                render={(props) => (
+                  <div {...props}>
+                    <span>Speed</span>
+                    <span className="menu-value">
+                      <Menu.ItemValue />
+                      <span aria-hidden="true">›</span>
+                    </span>
+                  </div>
+                )}
+              />
+              <Menu.Content className="menu-panel">
+                <Menu.Back className="menu-back">
+                  <span aria-hidden="true">‹</span>
+                  Speed
+                </Menu.Back>
+                <Menu.RadioGroup
+                  className="menu-group"
+                  value={playbackRate.value}
+                  onValueChange={playbackRate.setValue}
+                  aria-label="Playback rate"
+                >
+                  {playbackRate.options.map((option) => (
+                    <Menu.RadioItem
+                      key={option.value}
+                      value={option.value}
+                      disabled={option.disabled}
+                      className="menu-item"
+                    >
+                      <span>{option.label}</span>
+                      <Menu.ItemIndicator
+                        checked={option.value === playbackRate.value}
+                        forceMount
+                        className="menu-indicator"
+                      >
+                        ✓
+                      </Menu.ItemIndicator>
+                    </Menu.RadioItem>
+                  ))}
+                </Menu.RadioGroup>
+              </Menu.Content>
+            </Menu.Root>
+          ) : null}
+
+          {hasCaptions ? (
+            <Menu.Root>
+              <Menu.Trigger
+                type="captions"
+                className="menu-item"
+                render={(props) => (
+                  <div {...props}>
+                    <span>Captions</span>
+                    <span className="menu-value">
+                      <Menu.ItemValue />
+                      <span aria-hidden="true">›</span>
+                    </span>
+                  </div>
+                )}
+              />
+              <Menu.Content className="menu-panel">
+                <Menu.Back className="menu-back">
+                  <span aria-hidden="true">‹</span>
+                  Captions
+                </Menu.Back>
+                <Menu.RadioGroup
+                  className="menu-group"
+                  value={captions.value}
+                  onValueChange={captions.setValue}
+                  aria-label="Captions"
+                >
+                  {captions.options.map((option) => (
+                    <Menu.RadioItem
+                      key={option.value}
+                      value={option.value}
+                      disabled={option.disabled}
+                      className="menu-item"
+                    >
+                      <span>{option.label}</span>
+                      <Menu.ItemIndicator
+                        checked={option.value === captions.value}
+                        forceMount
+                        className="menu-indicator"
+                      >
+                        ✓
+                      </Menu.ItemIndicator>
+                    </Menu.RadioItem>
+                  ))}
+                </Menu.RadioGroup>
+              </Menu.Content>
+            </Menu.Root>
+          ) : null}
+
+          <Menu.Item className="menu-item" onSelect={() => navigator.clipboard?.writeText(window.location.href)}>
+            Copy link
+          </Menu.Item>
+        </Menu.View>
+      </Menu.Content>
+    </Menu.Root>
+  );
+}
+
+export default function BasicUsage() {
+  return (
+    <Player.Provider>
+      <Player.Container className="media-container">
+        <HlsJsVideo src={src} autoPlay crossOrigin="anonymous" 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" />
+        </HlsJsVideo>
+        <div className="menu-bar">
+          <SettingsMenu />
+        </div>
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+```
+.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 {
+  --media-menu-side-offset: 8px;
+  --menu-transition-duration: 220ms;
+  position: relative;
+  box-sizing: border-box;
+  width: var(--media-menu-width);
+  min-width: 180px;
+  max-width: var(--media-menu-available-width, var(--media-popover-available-width, none));
+  height: var(--media-menu-height);
+  max-height: var(--media-menu-available-height, var(--media-popover-available-height, none));
+  padding: 6px;
+  margin: 0;
+  overflow: hidden;
+  overscroll-behavior: none;
+  font-size: 14px;
+  color: white;
+  background: rgba(0, 0, 0, 0.88);
+  border: 0;
+  border-radius: 8px;
+  backdrop-filter: blur(10px);
+  transition-timing-function: ease-in-out;
+  transition-duration: var(--menu-transition-duration);
+  transition-property: width, height, opacity, filter;
+}
+
+.menu-panel {
+  position: absolute;
+  inset: 0;
+  display: grid;
+  gap: 2px;
+  padding: 6px;
+  overflow: auto;
+  overscroll-behavior: none;
+  outline: none;
+  translate: 0 0;
+  transition-timing-function: ease-in-out;
+  transition-duration: var(--menu-transition-duration);
+  transition-property: translate, filter;
+  will-change: translate;
+}
+
+.menu-panel[data-starting-style],
+.menu-panel[data-ending-style] {
+  overflow: hidden;
+}
+
+.menu-panel[data-menu-root-view][data-menu-view-state="inactive"] {
+  filter: blur(8px);
+  translate: -100% 0;
+}
+
+.menu-panel[data-submenu] {
+  z-index: 1;
+}
+
+.menu-panel[data-submenu]:not([data-open], [data-ending-style]) {
+  translate: -100% 0;
+  transition-property: none;
+}
+
+.menu-panel[data-submenu][data-starting-style],
+.menu-panel[data-submenu][data-ending-style] {
+  pointer-events: none;
+  filter: blur(8px);
+}
+
+.menu-panel[data-submenu][data-starting-style][data-direction="forward"],
+.menu-panel[data-submenu][data-ending-style][data-direction="back"] {
+  translate: 100% 0;
+}
+
+.menu-panel[data-submenu][data-ending-style][data-direction="forward"],
+.menu-panel[data-submenu][data-starting-style][data-direction="back"] {
+  translate: -100% 0;
+}
+
+.menu-item,
+.menu-back {
+  display: flex;
+  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],
+.menu-back:hover {
+  background: rgba(255, 255, 255, 0.16);
+}
+
+.menu-back {
+  gap: 8px;
+  justify-content: flex-start;
+}
+
+.menu-value {
+  display: inline-flex;
+  gap: 8px;
+  align-items: center;
+  color: rgba(255, 255, 255, 0.72);
+}
+
+.menu-group {
+  display: grid;
+  gap: 2px;
+}
+
+.menu-tier {
+  margin-left: 2px;
+  font-size: 10px;
+}
+
+.menu-badge {
+  margin-left: auto;
+  color: rgba(255, 255, 255, 0.72);
+}
+
+.menu-back [aria-hidden],
+[role="menuitemradio"] [aria-hidden],
+.menu-item [aria-hidden] {
+  font-size: 18px;
+  line-height: 1;
+  color: rgba(255, 255, 255, 0.72);
+}
+
+.menu-indicator {
+  opacity: 0;
+}
+
+[role="menuitemradio"][aria-checked="true"] .menu-indicator {
+  opacity: 1;
+}
+```
+
+## API Reference
+
+### 
+
+Root
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`align`
+
+`'start' | 'center' | 'end'`
+
+`'start'`
+
+▸
+
+Description
+
+Alignment along the trigger's edge. Root menus only.
+
+`closeOnEscape`
+
+`boolean`
+
+`true`
+
+▸
+
+Description
+
+Close the menu when Escape is pressed at root level.
+
+`closeOnOutsideClick`
+
+`boolean`
+
+`true`
+
+▸
+
+Description
+
+Close the menu when clicking outside. Root menus only.
+
+`defaultOpen`
+
+`boolean`
+
+`false`
+
+▸
+
+Description
+
+Initial open state (uncontrolled).
+
+`isSubmenu`
+
+`boolean`
+
+`false`
+
+▸
+
+Description
+
+True when this menu instance is nested inside a parent menu's content.
+
+`open`
+
+`boolean`
+
+`false`
+
+▸
+
+Description
+
+Controlled open state.
+
+`side`
+
+`'top' | 'bottom' | 'left' | 'right'`
+
+`'bottom'`
+
+▸
+
+Description
+
+Which side of the trigger the menu appears on. Root menus only.
+
+#### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+Property
+
+Type
+
+Details
+
+`open`
+
+`boolean`
+
+`status`
+
+`'idle' | 'starting' | 'ending'`
+
+`side`
+
+`'top' | 'bottom' | 'left' | 'right' |...`
+
+▸
+
+Type
+
+`'top' | 'bottom' | 'left' | 'right' | undefined`
+
+`align`
+
+`'start' | 'center' | 'end' | undefined`
+
+`isSubmenu`
+
+`boolean`
+
+▸
+
+Description
+
+Whether this menu is nested inside another menu's content.
+
+`transitionStarting`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the open transition is in progress.
+
+`transitionEnding`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the close transition is in progress.
+
+#### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-open`
+
+▸
+
+Description
+
+Present when the menu is open.
+
+`data-side`
+
+`undefined | 'top' | 'bottom' | 'left'...`
+
+▸
+
+Description
+
+Popover positioning side. Absent on submenus.
+
+Type
+
+`undefined | 'top' | 'bottom' | 'left' | 'right'`
+
+`data-align`
+
+`undefined | 'start' | 'center' | 'end'`
+
+▸
+
+Description
+
+Popover positioning alignment. Absent on submenus.
+
+`data-submenu`
+
+▸
+
+Description
+
+Present on Content when this menu is nested inside a parent menu.
+
+#### CSS custom properties
+
+Variable
+
+Details
+
+`--media-menu-width`
+
+▸
+
+Description
+
+Width of the incoming submenu view (px). Set on root Content before each transition.
+
+`--media-menu-height`
+
+▸
+
+Description
+
+Height of the incoming submenu view (px). Set on root Content before each transition.
+
+`--media-menu-available-width`
+
+▸
+
+Description
+
+Viewport-constrained max width for the menu (px). Set from popover positioning.
+
+`--media-menu-available-height`
+
+▸
+
+Description
+
+Viewport-constrained max height for the menu (px). Set from popover positioning.
+
+### 
+
+Back
+
+Button that navigates back to the parent menu view. Place at the top of a submenu Content.
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`label`
+
+`string`
+
+`—`
+
+▸
+
+Description
+
+Accessible label for the back button.
+
+### 
+
+CheckboxItem
+
+A checkbox-style menu item. Renders a `<div>` with `role="menuitemcheckbox"`.
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`checked`
+
+`boolean`
+
+`—`
+
+▸
+
+Description
+
+Whether the item is currently checked.
+
+`disabled`
+
+`boolean`
+
+`—`
+
+▸
+
+Description
+
+Whether the item is disabled.
+
+`onCheckedChange`
+
+`(checked: boolean) => void`
+
+`—`
+
+▸
+
+Description
+
+Called when the checked state should change.
+
+### 
+
+Content
+
+Container for menu items. Positioned relative to the trigger at root level; renders in-place as a submenu panel when nested.
+
+#### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-open`
+
+▸
+
+Description
+
+Present when the menu is open.
+
+`data-side`
+
+`undefined | 'top' | 'bottom' | 'left'...`
+
+▸
+
+Description
+
+Popover positioning side. Absent on submenus.
+
+Type
+
+`undefined | 'top' | 'bottom' | 'left' | 'right'`
+
+`data-align`
+
+`undefined | 'start' | 'center' | 'end'`
+
+▸
+
+Description
+
+Popover positioning alignment. Absent on submenus.
+
+`data-submenu`
+
+▸
+
+Description
+
+Present on Content when this menu is nested inside a parent menu.
+
+### 
+
+Group
+
+Groups related menu items. Renders a `<div>` with `role="group"`.
+
+### 
+
+GroupLabel
+
+Non-interactive label for a group of items. Renders a `<div>`.
+
+### 
+
+Item
+
+A single action in the menu. Renders a `<div>` with `role="menuitem"`.
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`disabled`
+
+`boolean`
+
+`—`
+
+▸
+
+Description
+
+Whether the item is disabled.
+
+`onSelect`
+
+`() => void`
+
+`—`
+
+▸
+
+Description
+
+Called when the item is selected.
+
+`type`
+
+`MenuItemSettingType`
+
+`—`
+
+▸
+
+Description
+
+Setting kind for submenu triggers (`playback-rate`, `quality`, `audio-track`, or `captions`).
+
+### 
+
+ItemIndicator
+
+Visual indicator for a checked state. Only renders when `checked` is `true` (or `forceMount` is set).
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`checked`
+
+`boolean`
+
+`—`
+
+▸
+
+Description
+
+Whether the indicator is currently shown. Typically bound to the parent item's checked state.
+
+`forceMount`
+
+`boolean`
+
+`—`
+
+▸
+
+Description
+
+When `true`, renders even when unchecked (useful for animating out). Defaults to `false`.
+
+### 
+
+ItemValue
+
+Displays the current value for a settings menu item from `Menu.Item` or `Menu.Trigger` context.
+
+#### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-open`
+
+▸
+
+Description
+
+Present when the menu is open.
+
+`data-side`
+
+`undefined | 'top' | 'bottom' | 'left'...`
+
+▸
+
+Description
+
+Popover positioning side. Absent on submenus.
+
+Type
+
+`undefined | 'top' | 'bottom' | 'left' | 'right'`
+
+`data-align`
+
+`undefined | 'start' | 'center' | 'end'`
+
+▸
+
+Description
+
+Popover positioning alignment. Absent on submenus.
+
+`data-submenu`
+
+▸
+
+Description
+
+Present on Content when this menu is nested inside a parent menu.
+
+### 
+
+RadioGroup
+
+A group of mutually exclusive radio items. Renders a `<div>` with `role="group"`.
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`onValueChange`
+
+`(value: string) => void`
+
+`—`
+
+▸
+
+Description
+
+Called when the user selects a radio item.
+
+`value`
+
+`string`
+
+`—`
+
+▸
+
+Description
+
+The currently selected value.
+
+### 
+
+RadioItem
+
+A radio-style menu item. Renders a `<div>` with `role="menuitemradio"`.
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`disabled`
+
+`boolean`
+
+`—`
+
+▸
+
+Description
+
+Whether the item is disabled.
+
+`value`
+
+`string`
+
+`—`
+
+▸
+
+Description
+
+The value this item represents.
+
+### 
+
+Separator
+
+Visual divider between groups of items. Renders a `<div>` with `role="separator"`.
+
+### 
+
+Trigger
+
+Button that toggles the menu visibility. At root level renders a `<button>`. When inside a parent menu (as a submenu trigger), renders as a `<div role="menuitem">` that pushes the submenu on click or ArrowRight.
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`disabled`
+
+`boolean`
+
+`—`
+
+▸
+
+Description
+
+Disables the trigger.
+
+`type`
+
+`MenuItemSettingType`
+
+`—`
+
+▸
+
+Description
+
+Setting kind for submenu triggers (`playback-rate`, `quality`, `audio-track`, or `captions`).
+
+### 
+
+View
+
+Root menu view inside the menu viewport.