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

package/docs/reference/{menu.md → components/menu.md}

@@ -4,19 +4,24 @@ A composable menu component for settings, option selection, and actions
 
 ## Import
 
-ts
-
-```
+```ts
 import '@videojs/html/ui/menu';
+import '@videojs/html/ui/menu-content';
+import '@videojs/html/ui/menu-item';
+import '@videojs/html/ui/menu-group';
+import '@videojs/html/ui/menu-group-label';
+import '@videojs/html/ui/menu-separator';
+import '@videojs/html/ui/menu-radio-group';
+import '@videojs/html/ui/menu-radio-item';
+import '@videojs/html/ui/menu-checkbox-item';
+import '@videojs/html/ui/menu-item-indicator';
 ```
 
 ## Anatomy
 
-A root menu owns one positioned Popup. Nested `Content` elements share that Popup with the root Content.
+`<media-menu>` is the root menu and its one positioned popup. The root and nested `<media-menu-content>` elements are its direct children and share that popup.
 
-html
-
-```
+```html
 <button type="button" commandfor="settings-menu">Settings</button>
 
 <media-menu id="settings-menu">
@@ -54,17 +59,15 @@ html
 
 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.
 
-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.
+Root menus inside a [player 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`.
+To create a submenu, add another `<media-menu-content>` as a sibling, give it an `id`, and point the parent `<media-menu-item>` at it with `commandfor`.
 
 Media option groups share their option state with the enclosing menu: the selected value, and whether the options are disabled, hidden, or available. The menu’s trigger inherits the disabled and hidden state and exposes `data-availability`, and the menu closes if its options disappear while open. See [PlaybackRateRadioGroup](./playback-rate-radio-group.md), [QualityRadioGroup](./quality-radio-group.md), [AudioTrackRadioGroup](./audio-track-radio-group.md), and [CaptionsRadioGroup](./captions-radio-group.md).
 
 The generated radio group publishes its state to the `<media-menu>` that contains it. Add an element with `data-part="hint"` inside the parent `<media-menu-item>` and the menu writes the selected label into it:
 
-html
-
-```
+```html
 <media-menu-item commandfor="quality-menu">
   Quality
   <span data-part="hint"></span>
@@ -77,13 +80,11 @@ Use data attributes to style open state, highlighted items, selected radio items
 
 `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.
 
-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`.
+The root `<media-menu>` receives `data-open`, `data-side`, and `data-align`. Each `<media-menu-content>` receives menu state such as `data-open` and `data-submenu`; a content element 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
-
-```
+```css
 media-menu[data-open] {
   opacity: 1;
 }
@@ -112,27 +113,21 @@ Menu content renders with `role="menu"`. Items use `menuitem`, `menuitemradio`,
 
 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.
+- 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.
+Use `<media-menu-group-label>` inside grouped choices so the group receives an accessible label.
 
 ## Examples
 
 ### Basic usage
 
- Settings Quality › Audio › Speed › Captions › Copy link ‹ Quality ‹ Audio ‹ Speed ‹ Captions
+**index.html**
 
-index.html
-
-index.css
-
-index.ts
-
-```
+```html
 <video-player class="video-player">
   <media-container>
     <hlsjs-video
@@ -246,7 +241,10 @@ index.ts
   </media-container>
 </video-player>
 ```
-```
+
+**index.css**
+
+```css
 .video-player media-container {
   position: relative;
   display: block;
@@ -398,11 +396,18 @@ media-menu-radio-item[aria-checked="true"] .menu-indicator {
   opacity: 1;
 }
 ```
-```
+
+**index.ts**
+
+```ts
 import '@videojs/html/video/player';
 import '@videojs/html/ui/container';
 import '@videojs/html/media/hlsjs-video';
 import '@videojs/html/ui/menu';
+import '@videojs/html/ui/menu-content';
+import '@videojs/html/ui/menu-item';
+import '@videojs/html/ui/menu-radio-item';
+import '@videojs/html/ui/menu-item-indicator';
 import '@videojs/html/ui/quality-radio-group';
 import '@videojs/html/ui/audio-track-radio-group';
 import '@videojs/html/ui/playback-rate-radio-group';
@@ -411,578 +416,155 @@ import '@videojs/html/ui/captions-radio-group';
 
 ## API Reference
 
-### 
+### media-menu
 
-media-menu
+Root menu state and positioned popup. Content pages are direct children.
 
 #### Props
 
-Prop
-
-Type
-
-Default
-
-Details
-
-`align`
-
-`'start' | 'center' | 'end'`
-
-`'start'`
-
-▸
-
-Attribute
-
-`align`
-
-Description
-
-Alignment along the trigger's edge. Root menus only.
-
-`boundary`
-
-`'viewport' | 'container' | string & o...`
-
-`—`
-
-▸
-
-Attribute
-
-`boundary`
-
-Description
-
-Boundary used to constrain the root menu popup.
-
-Type
-
-`'viewport' | 'container' | string & object`
-
-`closeOnEscape`
-
-`boolean`
-
-`true`
-
-▸
-
-Attribute
-
-`close-on-escape`
-
-Description
-
-Close the menu when Escape is pressed at root level.
-
-`closeOnOutsideClick`
-
-`boolean`
-
-`true`
-
-▸
-
-Attribute
-
-`close-on-outside-click`
-
-Description
-
-Close the menu when clicking outside. Root menus only.
-
-`defaultOpen`
-
-`boolean`
-
-`false`
-
-▸
-
-Attribute
-
-`default-open`
-
-Description
-
-Initial open state (uncontrolled).
-
-`open`
-
-`boolean`
-
-`false`
-
-▸
-
-Attribute
-
-`open`
-
-Description
-
-Controlled open state.
-
-`side`
-
-`'top' | 'bottom' | 'left' | 'right'`
-
-`'bottom'`
-
-▸
-
-Attribute
-
-`side`
-
-Description
-
-Preferred side of the trigger for the menu. Root menus only.
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `align` | `'start' \| 'center' \| 'end'` | `'start'` | Alignment along the trigger's edge. Root menus only. |
+| `boundary` | `'viewport' \| 'container' \| string & {}` | — | Boundary used to constrain the root menu popup. |
+| `closeOnEscape` (attribute `close-on-escape`) | `boolean` | `true` | Close the menu when Escape is pressed at root level. |
+| `closeOnOutsideClick` (attribute `close-on-outside-click`) | `boolean` | `true` | Close the menu when clicking outside. Root menus only. |
+| `defaultOpen` (attribute `default-open`) | `boolean` | `false` | Initial open state (uncontrolled). |
+| `open` | `boolean` | `false` | Controlled open state. |
+| `side` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | Preferred side of the trigger for the menu. Root menus only. |
 
 #### State
 
 State is reflected as data attributes for CSS styling.
 
-Property
-
-Type
-
-Details
-
-`transitionStarting`
-
-`boolean`
-
-▸
-
-Description
-
-Whether the open transition is in progress.
-
-`transitionEnding`
-
-`boolean`
-
-▸
-
-Description
-
-Whether the close transition is in progress.
-
-`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.
+| Property | Type | Description |
+| --- | --- | --- |
+| `transitionStarting` | `boolean` | Whether the open transition is in progress. |
+| `transitionEnding` | `boolean` | Whether the close transition is in progress. |
+| `open` | `boolean` | |
+| `status` | `'idle' \| 'starting' \| 'ending'` | |
+| `side` | `'top' \| 'bottom' \| 'left' \| 'right' \| undefined` | Preferred side of the trigger for the menu. Root menus only. |
+| `align` | `'start' \| 'center' \| 'end' \| undefined` | |
+| `isSubmenu` | `boolean` | Whether this menu is nested inside another menu's content. |
 
 #### CSS custom properties
 
-Variable
-
-Details
-
-`--media-menu-width`
-
-▸
-
-Description
-
-Width of the active menu panel (px).
-
-`--media-menu-height`
-
-▸
-
-Description
-
-Height of the active menu panel (px).
-
-`--media-menu-available-width`
-
-▸
-
-Description
-
-Viewport-constrained max width for the menu (px).
-
-`--media-menu-available-height`
-
-▸
-
-Description
-
-Viewport-constrained max height for the menu (px).
+| Variable | Description |
+| --- | --- |
+| `--media-menu-width` | Width of the active menu panel (px). |
+| `--media-menu-height` | Height of the active menu panel (px). |
+| `--media-menu-available-width` | Viewport-constrained max width for the menu (px). |
+| `--media-menu-available-height` | Viewport-constrained max height for the menu (px). |
 
 #### Events
 
-Event
-
-Description
-
-`open-change`
+| Event | Description |
+| --- | --- |
+| `open-change` | Fired before the menu's open state changes. Cancel the event to prevent the change. |
 
-Fired before the menu's open state changes. Cancel the event to prevent the change.
+### media-menu-checkbox-item
 
-### 
-
-media-menu-checkbox-item
-
-A checkbox-style menu item. Renders a `<div>` with `role="menuitemcheckbox"`.
+Menu item that toggles `checked` when activated and leaves the menu open. The element itself takes `role="menuitemcheckbox"`.
 
 #### Props
 
-Prop
-
-Type
-
-Default
-
-Details
-
-`checked`
-
-`boolean`
-
-`—`
-
-▸
-
-Attribute
-
-`checked`
-
-Description
-
-Whether the item is currently checked.
-
-`disabled`
-
-`boolean`
-
-`—`
-
-▸
-
-Attribute
-
-`disabled`
-
-Description
-
-Whether the item is disabled.
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `checked` | `boolean` | — | Whether the item is currently checked. |
+| `disabled` | `boolean` | — | Whether the item is disabled. |
 
 #### 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.
+| Attribute | Description |
+| --- | --- |
+| `data-item` | 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` | Present when the item is highlighted. Set to `pointer` when pointer movement caused the highlight; otherwise empty. |
 
 #### Events
 
-Event
-
-Description
+| Event | Description |
+| --- | --- |
+| `checked-change` | Fired when the checked state changes. |
 
-`checked-change`
+### media-menu-content
 
-Fired when the checked state changes.
-
-### 
-
-media-menu-content
-
-Accessible item and focus scope for exactly one root or nested menu page.
+One accessible menu page. Root and nested pages are sibling children of `<media-menu>`.
 
 #### Events
 
-Event
-
-Description
-
-`open-change`
-
-### 
-
-media-menu-group
-
-Groups related menu items. Renders a `<div>` with `role="group"`.
+| Event | Description |
+| --- | --- |
+| `open-change` | |
 
-### 
+### media-menu-group
 
-media-menu-group-label
+Groups related menu items; the element itself takes `role="group"`. A `<media-menu-group-label>` child names the group unless it already has an `aria-label` or `aria-labelledby`.
 
-Non-interactive label for a group of items. Renders a `<div>`.
+### media-menu-group-label
 
-### 
+Non-interactive label that names its enclosing `<media-menu-group>` or `<media-menu-radio-group>`.
 
-media-menu-item
+### media-menu-item
 
-A single action in the menu. Renders a `<div>` with `role="menuitem"`.
+Menu action; the element itself takes `role="menuitem"`. Activation fires a cancelable `select` event and then closes the menu, unless `commandfor` names a nested `<media-menu-content>` page to open instead.
 
 #### Props
 
-Prop
-
-Type
-
-Default
-
-Details
-
-`disabled`
-
-`boolean`
-
-`—`
-
-▸
-
-Attribute
-
-`disabled`
-
-Description
-
-Whether the item is disabled.
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `disabled` | `boolean` | — | Whether the item is disabled. |
 
 #### Data attributes
 
-Attribute
-
-Type
-
-Details
-
-`data-item`
-
-▸
-
-Description
+| Attribute | Description |
+| --- | --- |
+| `data-item` | 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` | Present when the item is highlighted. Set to `pointer` when pointer movement caused the highlight; otherwise empty. |
 
-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.
+### media-menu-item-indicator
 
-`data-highlighted`
-
-▸
-
-Description
-
-Present when the item is highlighted. Set to `pointer` when pointer movement caused the highlight; otherwise empty.
-
-### 
-
-media-menu-item-indicator
-
-Visual indicator for a checked state. Only renders when `checked` is `true` (or `forceMount` is set).
+Decorative checked-state mark inside a menu item, hidden from assistive technology. It stays `hidden` unless `checked` or `force-mount` is set; option radio groups set `checked` on the indicators in the items they generate.
 
 #### Props
 
-Prop
-
-Type
-
-Default
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `checked` | `boolean` | — | Whether the indicator is currently shown. Typically bound to the parent item's checked state. |
+| `forceMount` (attribute `force-mount`) | `boolean` | — | When `true`, renders even when unchecked (useful for animating out). Defaults to `false`. |
 
-Details
+### media-menu-radio-group
 
-`checked`
-
-`boolean`
-
-`—`
-
-▸
-
-Attribute
-
-`checked`
-
-Description
-
-Whether the indicator is currently shown. Typically bound to the parent item's checked state.
-
-`forceMount`
-
-`boolean`
-
-`—`
-
-▸
-
-Attribute
-
-`force-mount`
-
-Description
-
-When `true`, renders even when unchecked (useful for animating out). Defaults to `false`.
-
-### 
-
-media-menu-radio-group
-
-A group of mutually exclusive radio items. Renders a `<div>` with `role="group"`.
+Group of mutually exclusive `<media-menu-radio-item>` children; the element itself takes `role="group"`.
 
 #### Props
 
-Prop
-
-Type
-
-Default
-
-Details
-
-`value`
-
-`string`
-
-`—`
-
-▸
-
-Attribute
-
-`value`
-
-Description
-
-The currently selected value.
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `string` | — | The currently selected value. |
 
 #### Events
 
-Event
-
-Description
-
-`value-change`
-
-Fired when the selected value changes.
+| Event | Description |
+| --- | --- |
+| `value-change` | Fired when the selected value changes. |
 
-### 
+### media-menu-radio-item
 
-media-menu-radio-item
-
-A radio-style menu item. Renders a `<div>` with `role="menuitemradio"`.
+Menu item that selects its `value` in the enclosing `<media-menu-radio-group>` and closes the menu. The element itself takes `role="menuitemradio"`, checked while its value matches the group's.
 
 #### Props
 
-Prop
-
-Type
-
-Default
-
-Details
-
-`disabled`
-
-`boolean`
-
-`—`
-
-▸
-
-Attribute
-
-`disabled`
-
-Description
-
-Whether the item is disabled.
-
-`value`
-
-`string`
-
-`—`
-
-▸
-
-Attribute
-
-`value`
-
-Description
-
-The value this item represents.
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `disabled` | `boolean` | — | Whether the item is disabled. |
+| `value` | `string` | — | 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.
-
-### 
+| Attribute | Description |
+| --- | --- |
+| `data-item` | 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` | Present when the item is highlighted. Set to `pointer` when pointer movement caused the highlight; otherwise empty. |
 
-media-menu-separator
+### media-menu-separator
 
-Visual divider between groups of items. Renders a `<div>` with `role="separator"`.
+Visual divider between groups of menu items; the element itself takes `role="separator"`.