@videojs/react 10.0.0-beta.31 → 10.0.0-beta.32

package/docs/reference/menu.md

@@ -2,27 +2,31 @@
 
 A composable menu component for settings, option selection, and actions
 
+## Import
+
+tsx
+
+```
+import { Menu } from '@videojs/react';
+```
+
 ## 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.
+A root menu owns one positioned Popup. Nested `Content` elements share that Popup with the root Content.
 
 tsx
 
 ```
 <Menu.Root>
   <Menu.Trigger />
-  <Menu.Content>
-    <Menu.View>
+  <Menu.Popup>
+    <Menu.Content>
       {/* Parent menu item that opens a submenu */}
       <Menu.Root>
-        {/* Submenu trigger */}
-        <Menu.Trigger>
-          <Menu.ItemValue />
-        </Menu.Trigger>
+        <Menu.Trigger />
 
-        {/* Submenu content */}
         <Menu.Content>
-          <Menu.Back />
+          <Menu.Item>Back</Menu.Item>
           <Menu.RadioGroup>
             <Menu.GroupLabel />
             <Menu.RadioItem>
@@ -41,8 +45,8 @@ tsx
       </Menu.Group>
       <Menu.Separator />
       <Menu.Item />
-    </Menu.View>
-  </Menu.Content>
+    </Menu.Content>
+  </Menu.Popup>
 </Menu.Root>
 ```
 
@@ -50,27 +54,40 @@ tsx
 
 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.
+Root menus inside a [Container](./player-container.md) join its popup group. Opening one closes any other root menu or popover that is open in the same container. Submenus remain part of their root menu instead of registering separately.
+
+In React, create a submenu by nesting another `Menu.Root` in the parent `Menu.Content`; its `Menu.Trigger` behaves as a parent item and its `Menu.Content` becomes the active Content. In HTML, add another `<media-menu-content>` as a sibling, give it an `id`, and point the parent `<media-menu-item>` at it with `commandfor`.
 
-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.
+Media option groups can render the current selection beside a submenu trigger. See [PlaybackRateRadioGroup](./playback-rate-radio-group.md), [QualityRadioGroup](./quality-radio-group.md), [AudioTrackRadioGroup](./audio-track-radio-group.md), and [CaptionsRadioGroup](./captions-radio-group.md).
 
 ## 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.
+`data-highlighted` identifies the current menu item. Its value is `"pointer"` when pointer movement caused the highlight and an empty string for other highlights, including keyboard navigation and type-ahead search. Use `[data-highlighted]` to match any highlighted item or `[data-highlighted=""]` to match highlights that were not caused by pointer movement.
 
-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`.
+The root `Menu.Popup` or `<media-menu>` receives `data-open`, `data-side`, and `data-align`. Each Content receives menu state such as `data-open` and `data-submenu`; a Content with an open logical child receives `data-child-open`.
+
+Every navigable item receives `data-item`. Use `[data-item]` when one rule should target regular, radio, checkbox, and submenu-trigger items together.
 
 css
 
 ```
-.menu[data-open] {
+.menu-popup[data-open] {
   opacity: 1;
 }
 
+.menu-content[data-child-open] {
+  translate: -100% 0;
+}
+
 .menu-item[data-highlighted] {
   background: rgba(255, 255, 255, 0.16);
+  transition: background-color 100ms ease-in-out;
+}
+
+.menu-item[data-highlighted=""] {
+  transition-duration: 0ms;
 }
 
 [role="menuitemradio"][aria-checked="true"] {
@@ -128,7 +145,6 @@ function SettingsMenu(): ReactNode {
   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 (
@@ -136,8 +152,8 @@ function SettingsMenu(): ReactNode {
       <Menu.Trigger className="settings-trigger" aria-label="Settings" render={<button type="button" />}>
         Settings
       </Menu.Trigger>
-      <Menu.Content className="menu">
-        <div className="menu-panel">
+      <Menu.Popup className="menu">
+        <Menu.Content className="menu-content">
           {hasQuality ? (
             <Menu.Root>
               <Menu.Trigger
@@ -333,8 +349,8 @@ function SettingsMenu(): ReactNode {
           <Menu.Item className="menu-item" onSelect={() => navigator.clipboard?.writeText(window.location.href)}>
             Copy link
           </Menu.Item>
-        </div>
-      </Menu.Content>
+        </Menu.Content>
+      </Menu.Popup>
     </Menu.Root>
   );
 }
@@ -364,30 +380,6 @@ 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;
@@ -429,6 +421,7 @@ export default function BasicUsage() {
   transition-property: width, height, opacity, filter;
 }
 
+.menu-content,
 .menu-panel {
   position: absolute;
   inset: 0;
@@ -444,14 +437,9 @@ export default function BasicUsage() {
   transition-property: translate, filter;
 }
 
-.menu[data-submenu-expanded="true"] > :not([data-submenu]) {
+.menu-content[data-child-open] {
   filter: blur(8px);
   translate: -100% 0;
-  animation: media-menu-content-exit var(--menu-transition-duration) ease-in-out both;
-}
-
-.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] {
@@ -628,42 +616,6 @@ Type
 
 Details
 
-`open`
-
-`boolean`
-
-`status`
-
-`'idle' | 'starting' | 'ending'`
-
-`side`
-
-`'top' | 'bottom' | 'left' | 'right' |...`
-
-▸
-
-Description
-
-Preferred side of the trigger for the menu. Root menus only.
-
-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`
@@ -684,53 +636,41 @@ Description
 
 Whether the close transition is in progress.
 
-#### Data attributes
-
-Attribute
-
-Type
-
-Details
-
-`data-open`
+`open`
 
-▸
+`boolean`
 
-Description
+`status`
 
-Present when the menu is open.
+`'idle' | 'starting' | 'ending'`
 
-`data-side`
+`side`
 
-`undefined | 'left' | 'right' | 'top' ...`
+`'top' | 'bottom' | 'left' | 'right' |...`
 
 ▸
 
 Description
 
-Rendered positioning side after collision handling. Absent on submenus.
+Preferred side of the trigger for the menu. Root menus only.
 
 Type
 
-`undefined | 'left' | 'right' | 'top' | 'bottom'`
-
-`data-align`
-
-`undefined | 'center' | 'start' | 'end'`
+`'top' | 'bottom' | 'left' | 'right' | undefined`
 
-▸
+`align`
 
-Description
+`'start' | 'center' | 'end' | undefined`
 
-Popover positioning alignment. Absent on submenus.
+`isSubmenu`
 
-`data-submenu`
+`boolean`
 
 ▸
 
 Description
 
-Present on Content when this menu is nested inside a parent menu.
+Whether this menu is nested inside another menu's content.
 
 #### CSS custom properties
 
@@ -798,6 +738,18 @@ Description
 
 Whether the item is currently checked.
 
+`className`
+
+`string | ((state: MenuState) => string | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Class name or function returning class name from state.
+
 `disabled`
 
 `boolean`
@@ -812,7 +764,7 @@ Whether the item is disabled.
 
 `onCheckedChange`
 
-`(checked: boolean) => void`
+`((checked: boolean) => void)`
 
 `—`
 
@@ -822,6 +774,30 @@ Description
 
 Called when the checked state should change.
 
+`render`
+
+`ReactElement | ((props: HTMLProps, state: MenuState) => ReactElement | null)`
+
+`—`
+
+▸
+
+Description
+
+Render prop for custom element.
+
+`style`
+
+`CSSProperties | ((state: MenuState) => CSSProperties | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Style or function returning style from state.
+
 #### Data attributes
 
 Attribute
@@ -850,61 +826,105 @@ Present when the item is highlighted. Set to `pointer` when pointer movement cau
 
 Content
 
-Container for menu items. Positioned relative to the trigger at root level; renders in-place as a submenu panel when nested.
+Accessible item and focus scope for exactly one root or nested menu page.
 
-#### Data attributes
+#### Props
 
-Attribute
+Prop
 
 Type
 
+Default
+
 Details
 
-`data-open`
+`className`
+
+`string | ((state: MenuState) => string | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Class name or function returning class name from state.
+
+`render`
+
+`ReactElement | ((props: HTMLProps, state: MenuState) => ReactElement | null)`
+
+`—`
 
 ▸
 
 Description
 
-Present when the menu is open.
+Render prop for custom element.
 
-`data-side`
+`style`
 
-`undefined | 'left' | 'right' | 'top' ...`
+`CSSProperties | ((state: MenuState) => CSSProperties | undefined)`
+
+`—`
 
 ▸
 
 Description
 
-Rendered positioning side after collision handling. Absent on submenus.
+Style or function returning style from state.
+
+### 
+
+Group
+
+Groups related menu items. Renders a `<div>` with `role="group"`.
+
+#### Props
+
+Prop
 
 Type
 
-`undefined | 'left' | 'right' | 'top' | 'bottom'`
+Default
 
-`data-align`
+Details
 
-`undefined | 'center' | 'start' | 'end'`
+`className`
+
+`string | ((state: MenuState) => string | undefined)`
+
+`—`
 
 ▸
 
 Description
 
-Popover positioning alignment. Absent on submenus.
+Class name or function returning class name from state.
 
-`data-submenu`
+`render`
+
+`ReactElement | ((props: HTMLProps, state: MenuState) => ReactElement | null)`
+
+`—`
 
 ▸
 
 Description
 
-Present on Content when this menu is nested inside a parent menu.
+Render prop for custom element.
 
-### 
+`style`
 
-Group
+`CSSProperties | ((state: MenuState) => CSSProperties | undefined)`
 
-Groups related menu items. Renders a `<div>` with `role="group"`.
+`—`
+
+▸
+
+Description
+
+Style or function returning style from state.
 
 ### 
 
@@ -912,6 +932,52 @@ GroupLabel
 
 Non-interactive label for a group of items. Renders a `<div>`.
 
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`className`
+
+`string | ((state: MenuState) => string | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Class name or function returning class name from state.
+
+`render`
+
+`ReactElement | ((props: HTMLProps, state: MenuState) => ReactElement | null)`
+
+`—`
+
+▸
+
+Description
+
+Render prop for custom element.
+
+`style`
+
+`CSSProperties | ((state: MenuState) => CSSProperties | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Style or function returning style from state.
+
 ### 
 
 Item
@@ -928,6 +994,18 @@ Default
 
 Details
 
+`className`
+
+`string | ((state: MenuState) => string | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Class name or function returning class name from state.
+
 `disabled`
 
 `boolean`
@@ -942,7 +1020,7 @@ Whether the item is disabled.
 
 `onSelect`
 
-`() => void`
+`(() => void)`
 
 `—`
 
@@ -952,6 +1030,30 @@ Description
 
 Called when the item is selected.
 
+`render`
+
+`ReactElement | ((props: HTMLProps, state: MenuState) => ReactElement | null)`
+
+`—`
+
+▸
+
+Description
+
+Render prop for custom element.
+
+`style`
+
+`CSSProperties | ((state: MenuState) => CSSProperties | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Style or function returning style from state.
+
 #### Data attributes
 
 Attribute
@@ -1004,6 +1106,18 @@ Description
 
 Whether the indicator is currently shown. Typically bound to the parent item's checked state.
 
+`className`
+
+`string | ((state: MenuState) => string | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Class name or function returning class name from state.
+
 `forceMount`
 
 `boolean`
@@ -1016,6 +1130,82 @@ Description
 
 When `true`, renders even when unchecked (useful for animating out). Defaults to `false`.
 
+`render`
+
+`ReactElement | ((props: HTMLProps, state: MenuState) => ReactElement | null)`
+
+`—`
+
+▸
+
+Description
+
+Render prop for custom element.
+
+`style`
+
+`CSSProperties | ((state: MenuState) => CSSProperties | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Style or function returning style from state.
+
+### 
+
+Popup
+
+Positioned menu surface that contains one or more sibling Content pages.
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`className`
+
+`string | ((state: MenuState) => string | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Class name or function returning class name from state.
+
+`render`
+
+`ReactElement | ((props: HTMLProps, state: MenuState) => ReactElement | null)`
+
+`—`
+
+▸
+
+Description
+
+Render prop for custom element.
+
+`style`
+
+`CSSProperties | ((state: MenuState) => CSSProperties | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Style or function returning style from state.
+
 ### 
 
 RadioGroup
@@ -1032,9 +1222,21 @@ Default
 
 Details
 
+`className`
+
+`string | ((state: MenuState) => string | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Class name or function returning class name from state.
+
 `onValueChange`
 
-`(value: string) => void`
+`((value: string) => void)`
 
 `—`
 
@@ -1044,6 +1246,30 @@ Description
 
 Called when the user selects a radio item.
 
+`render`
+
+`ReactElement | ((props: HTMLProps, state: MenuState) => ReactElement | null)`
+
+`—`
+
+▸
+
+Description
+
+Render prop for custom element.
+
+`style`
+
+`CSSProperties | ((state: MenuState) => CSSProperties | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Style or function returning style from state.
+
 `value`
 
 `string`
@@ -1072,6 +1298,18 @@ Default
 
 Details
 
+`className`
+
+`string | ((state: MenuState) => string | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Class name or function returning class name from state.
+
 `disabled`
 
 `boolean`
@@ -1084,6 +1322,30 @@ Description
 
 Whether the item is disabled.
 
+`render`
+
+`ReactElement | ((props: HTMLProps, state: MenuState) => ReactElement | null)`
+
+`—`
+
+▸
+
+Description
+
+Render prop for custom element.
+
+`style`
+
+`CSSProperties | ((state: MenuState) => CSSProperties | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Style or function returning style from state.
+
 `value`
 
 `string`
@@ -1126,6 +1388,52 @@ Separator
 
 Visual divider between groups of items. Renders a `<div>` with `role="separator"`.
 
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`className`
+
+`string | ((state: MenuState) => string | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Class name or function returning class name from state.
+
+`render`
+
+`ReactElement | ((props: HTMLProps, state: MenuState) => ReactElement | null)`
+
+`—`
+
+▸
+
+Description
+
+Render prop for custom element.
+
+`style`
+
+`CSSProperties | ((state: MenuState) => CSSProperties | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Style or function returning style from state.
+
 ### 
 
 Trigger
@@ -1142,6 +1450,18 @@ Default
 
 Details
 
+`className`
+
+`string | ((state: MenuState) => string | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Class name or function returning class name from state.
+
 `disabled`
 
 `boolean`
@@ -1166,6 +1486,30 @@ Disables the trigger.
 
 `—`
 
+`render`
+
+`ReactElement | ((props: HTMLProps, state: MenuState) => ReactElement | null)`
+
+`—`
+
+▸
+
+Description
+
+Render prop for custom element.
+
+`style`
+
+`CSSProperties | ((state: MenuState) => CSSProperties | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Style or function returning style from state.
+
 #### Data attributes
 
 Attribute