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

package/docs/reference/menu.md

@@ -48,11 +48,11 @@ tsx
 
 ## 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`.
+Menus open from a trigger and close when you select an item, click outside, move focus away, or press Escape. Root menus use `side` and `align` as their preferred placement. When the preferred side overflows the positioning boundary, the menu uses the opposite side if it has more space.
 
 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.
+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 [PlaybackRateRadioGroup](./playback-rate-radio-group.md), [QualityRadioGroup](./quality-radio-group.md), [AudioTrackRadioGroup](./audio-track-radio-group.md), and [CaptionsRadioGroup](./captions-radio-group.md) for the generated option groups.
 
 ## Styling
 
@@ -60,6 +60,8 @@ Use data attributes to style open state, highlighted items, selected radio items
 
 `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.
 
+On root menu content, `data-side` reflects the rendered side and can differ from the preferred `side` prop after collision handling. Submenus do not have `data-side`.
+
 css
 
 ```
@@ -102,6 +104,7 @@ App.css
 
 ```
 import {
+  Container,
   createPlayer,
   Menu,
   useAudioTrackOptions,
@@ -113,8 +116,8 @@ 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';
+const { Player } = createPlayer({ features: videoFeatures });
+const src = 'https://stream.mux.com/s41JYeqIpBMBzE4OzxDyGR2yrp2hD1CQ6gJN9SlVGDQ.m3u8';
 
 function SettingsMenu(): ReactNode {
   const playbackRate = usePlaybackRateOptions();
@@ -134,27 +137,26 @@ function SettingsMenu(): ReactNode {
         Settings
       </Menu.Trigger>
       <Menu.Content className="menu">
-        <Menu.View className="menu-panel">
+        <div 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 />
+                      {quality.selectedLabel}
                       <span aria-hidden="true">›</span>
                     </span>
                   </div>
                 )}
               />
               <Menu.Content className="menu-panel">
-                <Menu.Back className="menu-back">
+                <Menu.Item className="menu-back">
                   <span aria-hidden="true">‹</span>
                   Quality
-                </Menu.Back>
+                </Menu.Item>
                 <Menu.RadioGroup
                   className="menu-group"
                   value={quality.value}
@@ -190,23 +192,22 @@ function SettingsMenu(): ReactNode {
           {hasAudioTrack ? (
             <Menu.Root>
               <Menu.Trigger
-                type="audio-track"
                 className="menu-item"
                 render={(props) => (
                   <div {...props}>
                     <span>Audio</span>
                     <span className="menu-value">
-                      <Menu.ItemValue />
+                      {audioTrack.selectedLabel}
                       <span aria-hidden="true">›</span>
                     </span>
                   </div>
                 )}
               />
               <Menu.Content className="menu-panel">
-                <Menu.Back className="menu-back">
+                <Menu.Item className="menu-back">
                   <span aria-hidden="true">‹</span>
                   Audio
-                </Menu.Back>
+                </Menu.Item>
                 <Menu.RadioGroup
                   className="menu-group"
                   value={audioTrack.value}
@@ -238,23 +239,22 @@ function SettingsMenu(): ReactNode {
           {hasPlaybackRate ? (
             <Menu.Root>
               <Menu.Trigger
-                type="playback-rate"
                 className="menu-item"
                 render={(props) => (
                   <div {...props}>
                     <span>Speed</span>
                     <span className="menu-value">
-                      <Menu.ItemValue />
+                      {playbackRate.selectedLabel}
                       <span aria-hidden="true">›</span>
                     </span>
                   </div>
                 )}
               />
               <Menu.Content className="menu-panel">
-                <Menu.Back className="menu-back">
+                <Menu.Item className="menu-back">
                   <span aria-hidden="true">‹</span>
                   Speed
-                </Menu.Back>
+                </Menu.Item>
                 <Menu.RadioGroup
                   className="menu-group"
                   value={playbackRate.value}
@@ -286,23 +286,22 @@ function SettingsMenu(): ReactNode {
           {hasCaptions ? (
             <Menu.Root>
               <Menu.Trigger
-                type="captions"
                 className="menu-item"
                 render={(props) => (
                   <div {...props}>
                     <span>Captions</span>
                     <span className="menu-value">
-                      <Menu.ItemValue />
+                      {captions.selectedLabel}
                       <span aria-hidden="true">›</span>
                     </span>
                   </div>
                 )}
               />
               <Menu.Content className="menu-panel">
-                <Menu.Back className="menu-back">
+                <Menu.Item className="menu-back">
                   <span aria-hidden="true">‹</span>
                   Captions
-                </Menu.Back>
+                </Menu.Item>
                 <Menu.RadioGroup
                   className="menu-group"
                   value={captions.value}
@@ -334,7 +333,7 @@ function SettingsMenu(): ReactNode {
           <Menu.Item className="menu-item" onSelect={() => navigator.clipboard?.writeText(window.location.href)}>
             Copy link
           </Menu.Item>
-        </Menu.View>
+        </div>
       </Menu.Content>
     </Menu.Root>
   );
@@ -342,8 +341,8 @@ function SettingsMenu(): ReactNode {
 
 export default function BasicUsage() {
   return (
-    <Player.Provider>
-      <Player.Container className="media-container">
+    <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" />
@@ -351,8 +350,8 @@ export default function BasicUsage() {
         <div className="menu-bar">
           <SettingsMenu />
         </div>
-      </Player.Container>
-    </Player.Provider>
+      </Container>
+    </Player>
   );
 }
 ```
@@ -365,6 +364,30 @@ export default function BasicUsage() {
   width: 100%;
 }
 
+@keyframes media-menu-content-exit {
+  from {
+    filter: none;
+    translate: 0 0;
+  }
+
+  to {
+    filter: blur(8px);
+    translate: -100% 0;
+  }
+}
+
+@keyframes media-menu-content-enter {
+  from {
+    filter: blur(8px);
+    translate: -100% 0;
+  }
+
+  to {
+    filter: none;
+    translate: 0 0;
+  }
+}
+
 .menu-bar {
   position: absolute;
   right: 10px;
@@ -422,41 +445,28 @@ export default function BasicUsage() {
   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"] {
+.menu[data-submenu-expanded="true"] > :not([data-submenu]) {
   filter: blur(8px);
   translate: -100% 0;
+  animation: media-menu-content-exit var(--menu-transition-duration) ease-in-out both;
 }
 
-.menu-panel[data-submenu] {
-  z-index: 1;
+.menu[data-submenu-expanded="false"] > :not([data-submenu]) {
+  animation: media-menu-content-enter var(--menu-transition-duration) ease-in-out both;
 }
 
-.menu-panel[data-submenu]:not([data-open], [data-ending-style]) {
-  translate: -100% 0;
-  transition-property: none;
+.menu-panel[data-submenu] {
+  z-index: 1;
 }
 
 .menu-panel[data-submenu][data-starting-style],
 .menu-panel[data-submenu][data-ending-style] {
+  overflow: hidden;
   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;
@@ -619,7 +629,7 @@ Controlled open state.
 
 Description
 
-Which side of the trigger the menu appears on. Root menus only.
+Preferred side of the trigger for the menu. Root menus only.
 
 #### State
 
@@ -645,6 +655,10 @@ Details
 
 ▸
 
+Description
+
+Preferred side of the trigger for the menu. Root menus only.
+
 Type
 
 `'top' | 'bottom' | 'left' | 'right' | undefined`
@@ -707,7 +721,7 @@ Present when the menu is open.
 
 Description
 
-Popover positioning side. Absent on submenus.
+Rendered positioning side after collision handling. Absent on submenus.
 
 Type
 
@@ -743,7 +757,7 @@ Details
 
 Description
 
-Width of the incoming submenu view (px). Set on root Content before each transition.
+Width of the active menu panel (px).
 
 `--media-menu-height`
 
@@ -751,7 +765,7 @@ Width of the incoming submenu view (px). Set on root Content before each transit
 
 Description
 
-Height of the incoming submenu view (px). Set on root Content before each transition.
+Height of the active menu panel (px).
 
 `--media-menu-available-width`
 
@@ -759,7 +773,7 @@ Height of the incoming submenu view (px). Set on root Content before each transi
 
 Description
 
-Viewport-constrained max width for the menu (px). Set from popover positioning.
+Viewport-constrained max width for the menu (px).
 
 `--media-menu-available-height`
 
@@ -767,35 +781,7 @@ Viewport-constrained max width for the menu (px). Set from popover positioning.
 
 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.
+Viewport-constrained max height for the menu (px).
 
 ### 
 
@@ -849,6 +835,30 @@ Description
 
 Called when the checked state should change.
 
+#### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-item`
+
+▸
+
+Description
+
+Present on all navigable item types: Item, RadioItem, CheckboxItem, and the Trigger when acting as a submenu trigger inside a parent menu. Use `[data-item]` as a shared selector to target all item types at once.
+
+`data-highlighted`
+
+▸
+
+Description
+
+Present when the item is highlighted. Set to `pointer` when pointer movement caused the highlight; otherwise empty.
+
 ### 
 
 Content
@@ -879,7 +889,7 @@ Present when the menu is open.
 
 Description
 
-Popover positioning side. Absent on submenus.
+Rendered positioning side after collision handling. Absent on submenus.
 
 Type
 
@@ -955,17 +965,29 @@ Description
 
 Called when the item is selected.
 
-`type`
+#### Data attributes
 
-`MenuItemSettingType`
+Attribute
 
-`—`
+Type
+
+Details
+
+`data-item`
+
+▸
+
+Description
+
+Present on all navigable item types: Item, RadioItem, CheckboxItem, and the Trigger when acting as a submenu trigger inside a parent menu. Use `[data-item]` as a shared selector to target all item types at once.
+
+`data-highlighted`
 
 ▸
 
 Description
 
-Setting kind for submenu triggers (`playback-rate`, `quality`, `audio-track`, or `captions`).
+Present when the item is highlighted. Set to `pointer` when pointer movement caused the highlight; otherwise empty.
 
 ### 
 
@@ -1009,60 +1031,6 @@ When `true`, renders even when unchecked (useful for animating out). Defaults to
 
 ### 
 
-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"`.
@@ -1141,6 +1109,30 @@ Description
 
 The value this item represents.
 
+#### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-item`
+
+▸
+
+Description
+
+Present on all navigable item types: Item, RadioItem, CheckboxItem, and the Trigger when acting as a submenu trigger inside a parent menu. Use `[data-item]` as a shared selector to target all item types at once.
+
+`data-highlighted`
+
+▸
+
+Description
+
+Present when the item is highlighted. Set to `pointer` when pointer movement caused the highlight; otherwise empty.
+
 ### 
 
 Separator
@@ -1151,7 +1143,7 @@ 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.
+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 opens the submenu on click or ArrowRight.
 
 #### Props
 
@@ -1175,20 +1167,38 @@ Description
 
 Disables the trigger.
 
-`type`
+`onClick`
 
-`MenuItemSettingType`
+`MouseEventHandler<MenuTriggerElement>`
 
 `—`
 
+`onKeyDown`
+
+`KeyboardEventHandler<MenuTriggerElement>`
+
+`—`
+
+#### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-item`
+
 ▸
 
 Description
 
-Setting kind for submenu triggers (`playback-rate`, `quality`, `audio-track`, or `captions`).
+Present on all navigable item types: Item, RadioItem, CheckboxItem, and the Trigger when acting as a submenu trigger inside a parent menu. Use `[data-item]` as a shared selector to target all item types at once.
 
-### 
+`data-highlighted`
 
-View
+▸
+
+Description
 
-Root menu view inside the menu viewport.
+Present when the item is highlighted. Set to `pointer` when pointer movement caused the highlight; otherwise empty.