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

package/docs/reference/components/playback-rate-radio-group.md

@@ -0,0 +1,211 @@
+# media-playback-rate-radio-group
+
+A menu radio group for selecting playback speed
+
+Creates radio items from the player playback rate state and selects the playback speed.
+
+## Import
+
+```ts
+import '@videojs/html/ui/playback-rate-radio-group';
+import '@videojs/html/ui/menu-radio-item';
+import '@videojs/html/ui/menu-item-indicator';
+```
+
+## Anatomy
+
+```html
+<media-playback-rate-radio-group>
+  <template>
+    <media-menu-radio-item>
+      <span data-part="label"></span>
+      <media-menu-item-indicator></media-menu-item-indicator>
+    </media-menu-radio-item>
+  </template>
+</media-playback-rate-radio-group>
+```
+
+## Behavior
+
+The group is available when the configured media exposes playback rates. Option labels default to the rate followed by a multiplication sign (e.g. `1.5×`); pass `formatRate` to customize them.
+
+`<media-playback-rate-radio-group>` generates `<media-menu-radio-item>` children. Add an optional `<template>` with a single `<media-menu-radio-item>` to customize each generated item.
+
+## Styling
+
+| Attribute | Values | Description |
+| --- | --- | --- |
+| `data-rate` | `number` | Current playback rate. |
+| `data-disabled` | Present / absent | Present when playback rate selection is disabled. |
+| `data-hidden` | Present / absent | Present when playback-rate selection is unavailable. |
+| `data-availability` | `"available"` / `"unavailable"` | Whether playback rates are available. |
+
+Unavailable groups receive the native `hidden` attribute.
+
+## Accessibility
+
+The group uses the menu radio group pattern.
+
+The element receives an accessible label from the `label` property or defaults to `Playback rate`. Override it with `aria-label` or `aria-labelledby`.
+
+## Examples
+
+### Basic usage
+
+**index.html**
+
+```html
+<video-player class="video-player">
+  <media-container>
+    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
+    <div class="menu-bar">
+      <button type="button" commandfor="speed-menu" class="settings-trigger">Speed</button>
+      <media-menu id="speed-menu" side="top" align="end" class="menu">
+        <media-menu-content>
+          <media-playback-rate-radio-group class="menu-group" aria-label="Speed">
+            <template>
+              <media-menu-radio-item class="menu-item">
+                <span data-part="label"></span>
+                <media-menu-item-indicator force-mount class="menu-indicator">✓</media-menu-item-indicator>
+              </media-menu-radio-item>
+            </template>
+          </media-playback-rate-radio-group>
+        </media-menu-content>
+      </media-menu>
+    </div>
+  </media-container>
+</video-player>
+```
+
+**index.css**
+
+```css
+.video-player media-container {
+  position: relative;
+  display: block;
+}
+
+.video-player 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;
+  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;
+  overflow: auto;
+  overscroll-behavior: none;
+  font-size: 14px;
+  color: white;
+  background: rgba(0, 0, 0, 0.88);
+  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;
+}
+
+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/ui/menu';
+import '@videojs/html/ui/menu-content';
+import '@videojs/html/ui/menu-radio-item';
+import '@videojs/html/ui/menu-item-indicator';
+import '@videojs/html/ui/playback-rate-radio-group';
+```
+
+## API Reference
+
+### media-playback-rate-radio-group
+
+Menu radio group that generates a `<media-menu-radio-item>` per available playback rate and shares the selected label and availability with an enclosing menu. An optional `<template>` holding one `<media-menu-radio-item>` customizes each generated item.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `disabled` | `boolean` | `false` | Whether playback rate selection is disabled. |
+| `formatRate` (attribute `format-rate`) | `((rate: number) => string)` | `formatPlaybackRate` | Custom formatter for visible playback rate labels. |
+
+#### State
+
+State is reflected as data attributes for CSS styling.
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `label` | `{ key: string; text: string } \| string` | |
+| `value` | `string` | Current radio-group value. |
+| `options` | `readonly Option[]` | Ordered options displayed by platform adapters. |
+| `disabled` | `boolean` | Whether the entire option group is disabled. |
+| `hidden` | `boolean` | Whether the option group is hidden because no meaningful selection is available. |
+| `availability` | `'available' \| 'unavailable'` | Whether the media exposes a meaningful selection. |
+| `rate` | `number` | |
+
+#### Data attributes
+
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-rate` | `number` | Current playback rate. |
+| `data-disabled` | — | Present when playback rate selection is disabled. |
+| `data-hidden` | — | Present when playback rate selection is unavailable. |
+| `data-availability` | `'available' \| 'unavailable'` | Indicates playback rate availability (`available` or `unavailable`). |
+
+#### Events
+
+| Event | Description |
+| --- | --- |
+| `value-change` | Fired when the selected value changes. |

package/docs/reference/components/player-container.md

@@ -0,0 +1,114 @@
+# media-container
+
+The player's visual and interaction surface for layout, fullscreen, focus, and user activity.
+
+The `<media-container>` is the player’s physical surface. It defines the visual boundary, registers the fullscreen and activity target, and gives gesture and hotkey elements a shared interaction surface. It lives inside a [`<video-player>`](./player.md).
+
+```html
+<video-player>
+  <media-container>
+    <video src="video.mp4"></video>
+    <media-controls><media-controls-content>...</media-controls-content></media-controls>
+  </media-container>
+</video-player>
+```
+
+## How it’s created
+
+Import the standard player entry point and the container. `video/player` registers only `<video-player>`; `ui/container` registers `<media-container>`:
+
+```ts
+import '@videojs/html/video/player';
+import '@videojs/html/ui/container';
+```
+
+```html
+<video-player>
+  <media-container>
+    <video src="video.mp4"></video>
+  </media-container>
+</video-player>
+```
+
+For custom behavior, extend the same `ContainerElement` used by the built-in player:
+
+**my-player.ts**
+
+```ts
+import { ContainerElement } from '@videojs/html';
+
+class MyContainer extends ContainerElement {}
+customElements.define('my-container', MyContainer);
+```
+
+Extending `ContainerElement` automatically registers the element with the nearest player when it connects and releases that registration when it disconnects.
+
+Import `@videojs/html/ui/container` when you only need to register the standard `<media-container>` element.
+
+## What it does
+
+### Layout and fullscreen
+
+The container is the visual box around your media and controls. Put sizing, aspect ratio, positioning, and visual boundaries here — on `<media-container>`, not `<video-player>`. Place overlays inside it, use it as their positioning context, and measure it when your app needs the rendered player size.
+
+```css
+.player-surface {
+  position: relative;
+  display: block;
+  width: 640px;
+  aspect-ratio: 16 / 9;
+}
+```
+
+```html
+<media-container class="player-surface">
+  <video src="video.mp4"></video>
+  <media-controls><media-controls-content>...</media-controls-content></media-controls>
+</media-container>
+```
+
+When the user goes fullscreen, the **container** goes fullscreen — not the video element. This keeps controls and other UI visible on top of the video, since they’re children of the container.
+
+Custom video elements such as `<mux-video>` and `<hlsjs-video>` do not create their own layout boxes: their inner `<video>` fills the parent. Size and measure `<media-container>`, not `<mux-video>` or `<hlsjs-video>`. Native `<video>` and `<audio>` elements still render their own boxes.
+
+### Media attachment
+
+Media discovery is handled by the player provider, not the container. Custom media elements like `<hlsjs-video>` register themselves via context when they connect. Plain `<video>` and `<audio>` elements are tracked automatically, including when they are added, removed, or replaced after connection. No `slot="media"` attribute is needed.
+
+### Interaction surface
+
+The container is where user intent enters the player. It listens for physical interaction on its surface and translates that into player behavior:
+
+- **User activity** — Mouse movement, touch, and keyboard activity within the container drive idle detection. This is how controls know when to show and hide.
+- **Gestures** — Tap and double-tap actions, optionally limited by pointer type and left, center, or right region. Configured via the [`<media-gesture>`](./gesture.md) element.
+- **Keyboard controls** — Spacebar to play/pause, arrow keys to seek, and other keyboard shortcuts scoped to the container. Configured via the `<media-hotkey>` element.
+
+### Popup coordination
+
+Each container owns one popup group. Opening a root [menu](./menu.md) or [popover](./popover.md) closes the previously open popup in that container. A popup rendered outside the container still manages its own open state, but it does not participate in the container’s group.
+
+## Relationship to skins
+
+A [skin](../../guides/skins.md) is a container plus UI controls. When you use a packaged skin, the container is built in — you don’t need to add one yourself.
+
+Style `<video-skin>` for the player’s outer size and aspect ratio. Importing the skin registers the styles that make the built-in container fill that space and position the media, controls, poster, and overlays.
+
+If you omit `<video-skin>` to build custom UI, render and style `<media-container>` yourself. See [Layout and fullscreen](#layout-and-fullscreen) for the complete layout example.
+
+## Inside vs. outside the container
+
+[`<video-player>`](./player.md) gives components access to state and actions. `<media-container>` layers on physical behaviors — fullscreen, activity detection, and gesture handling. Components work in both places; the container just adds those extras.
+
+```html
+<video-player>
+  <media-container>
+    <video src="video.mp4"></video>
+    <media-controls><media-controls-content>...</media-controls-content></media-controls>  <!-- fullscreen, activity detection, gestures -->
+  </media-container>
+
+  <media-transcript></media-transcript>     <!-- state & actions, but no container behaviors -->
+  <playlist-sidebar></playlist-sidebar>     <!-- state & actions, but no container behaviors -->
+</video-player>
+```
+
+A play button outside the container still reads playback state and can toggle play/pause — it just won’t go fullscreen with the player or respond to the container’s idle state.

package/docs/reference/components/player.md

@@ -0,0 +1,113 @@
+# video-player
+
+The state boundary — creates a store and broadcasts it to all descendants.
+
+The `<video-player>` element is the state boundary of your player. It creates a store and makes it available to every element inside it via context. Every player needs exactly one.
+
+```html
+<video-player>
+  <!-- Everything inside can access the player store -->
+  <media-container>
+    <video src="video.mp4"></video>
+  </media-container>
+</video-player>
+```
+
+## How it’s created
+
+For most users, importing from `@videojs/html/video/player` registers a ready-to-use `<video-player>` element with the standard video [features](../../guides/features.md) (bundled as a [preset](../../guides/presets.md)):
+
+```ts
+import '@videojs/html/video/player';
+```
+
+```html
+<video-player>
+  <media-container>
+    <video src="video.mp4"></video>
+  </media-container>
+</video-player>
+```
+
+If you need a custom feature set or tag name, use `createPlayer()` to get the configured `PlayerElement`. Extend `ContainerElement` separately when you need custom container behavior:
+
+**my-player.ts**
+
+```ts
+import { ContainerElement, createPlayer } from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+
+const { PlayerElement: MyPlayer } = createPlayer({ features: videoFeatures });
+
+class MyContainer extends ContainerElement {}
+customElements.define('my-player', MyPlayer);
+customElements.define('my-container', MyContainer);
+```
+
+- [`createPlayer` reference](../api/html-create-player.md)
+
+## What lives inside it
+
+Everything that needs player state goes inside `<video-player>`: skins, containers, UI components, and your own custom components. Anything inside can access the store.
+
+```html
+<video-player>
+  <video-skin>               <!-- skin — includes container + controls -->
+    <video src="..."></video> <!-- media element -->
+  </video-skin>
+  <my-custom-overlay></my-custom-overlay> <!-- your own element — can use PlayerController -->
+</video-player>
+```
+
+## No visual presence
+
+Packaged skins make `<video-player>` boxless with `display: contents`. Width, height, positioning, transforms, and `getBoundingClientRect()` do not describe a visible player box there. Put layout and measurements on the [`<media-container>`](./player-container.md) instead.
+
+If you omit `<video-skin>` and import only the player and media elements, those skin styles are not loaded. The player element still owns state, not layout, so add and style a `<media-container>` instead of using the player itself as the layout surface.
+
+## Accessing state
+
+Use the preset’s typed `PlayerController` to subscribe to store state from any custom element inside the player:
+
+**play-pause-button.ts**
+
+```ts
+import { UIElement, selectPlayback } from '@videojs/html';
+import { PlayerController } from '@videojs/html/video';
+
+class PlayPauseButton extends UIElement {
+  readonly #playback = new PlayerController(this, selectPlayback);
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.addEventListener('click', this.#togglePlayback);
+  }
+
+  disconnectedCallback() {
+    this.removeEventListener('click', this.#togglePlayback);
+    super.disconnectedCallback();
+  }
+
+  readonly #togglePlayback = () => this.#playback.value?.togglePaused();
+}
+
+customElements.define('play-pause-button', PlayPauseButton);
+```
+
+- [PlayerController reference](../api/player-controller.md)
+
+## Extended player layouts
+
+The player’s scope can extend beyond the fullscreen target. Playlists, transcripts, sidebars, and other supplementary UI can live inside `<video-player>` but outside `<media-container>`. They still have full access to the store, but they won’t go fullscreen with the video.
+
+```html
+<video-player>
+  <media-container>
+    <video src="video.mp4"></video>
+    <media-controls><media-controls-content>...</media-controls-content></media-controls>  <!-- goes fullscreen with the video -->
+  </media-container>
+
+  <media-transcript></media-transcript>     <!-- outside container — still has store access -->
+  <playlist-sidebar></playlist-sidebar>     <!-- outside container — still has store access -->
+</video-player>
+```

package/docs/reference/components/popover.md

@@ -0,0 +1,193 @@
+# media-popover
+
+A popover component for displaying contextual content anchored to a trigger
+
+## Import
+
+```ts
+import '@videojs/html/ui/popover';
+```
+
+## Anatomy
+
+```html
+<media-popover>
+  <button>Open</button>
+  <div>Content</div>
+</media-popover>
+```
+
+## Behavior
+
+Displays contextual content anchored to a trigger element. By default, opens on click and closes when clicking outside, pressing Escape, or when the trigger loses focus.
+
+Set `openOnHover` to open on pointer hover instead of click. Use `delay` and `closeDelay` to control timing for hover interactions.
+
+Popovers inside a [player container](./player-container.md) join its popup group. Opening one closes any other popover or root menu that is open in the same container. A popover outside the container still opens and closes normally, but it is not coordinated with that group.
+
+The `side` and `align` props control the preferred popup placement relative to the trigger. When the preferred side overflows the positioning boundary, the popup uses the opposite side if it has more space.
+
+The `media-popover` element wraps a trigger (first child button) and popup content (second child). The element manages open/close state and positioning automatically.
+
+## Styling
+
+Use [CSS custom properties](#css-custom-properties) for positioning offsets:
+
+```css
+media-popover {
+  --media-popover-side-offset: 8px;
+  --media-popover-align-offset: 0px;
+  --media-popover-boundary-offset: 8px;
+}
+```
+
+Style based on open state, rendered side, and transition phases. `data-side` reflects the rendered side and can differ from the preferred `side` prop after collision handling:
+
+```css
+media-popover[data-open] .popup {
+  display: block;
+}
+media-popover[data-starting-style] .popup {
+  opacity: 0;
+}
+media-popover[data-ending-style] .popup {
+  opacity: 0;
+}
+media-popover[data-side="top"] {
+  transform-origin: bottom center;
+}
+media-popover[data-side="bottom"] {
+  transform-origin: top center;
+}
+```
+
+## Accessibility
+
+The trigger receives `aria-expanded` reflecting the open state. When `modal` is set, the popup receives `aria-modal="true"`. Closing via Escape is enabled by default and can be disabled with `closeOnEscape={false}`.
+
+## Examples
+
+### Basic Usage
+
+**index.html**
+
+```html
+<video-player class="video-player">
+  <media-container>
+    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
+    <div class="bar">
+      <button type="button" commandfor="popover-demo" class="trigger">Settings</button>
+      <media-popover id="popover-demo" class="media-popover">
+        <div class="popup">Popover content</div>
+      </media-popover>
+    </div>
+  </media-container>
+</video-player>
+```
+
+**index.css**
+
+```css
+.video-player media-container {
+  position: relative;
+  display: block;
+}
+
+.video-player media-container video {
+  width: 100%;
+}
+
+.bar {
+  position: absolute;
+  bottom: 10px;
+  left: 10px;
+}
+
+.trigger {
+  padding: 6px 16px;
+  color: black;
+  cursor: pointer;
+  background: rgba(255, 255, 255, 0.7);
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+
+.media-popover {
+  padding: 12px 16px;
+  font-size: 14px;
+  color: white;
+  white-space: nowrap;
+  background: rgba(0, 0, 0, 0.85);
+  border-radius: 8px;
+  backdrop-filter: blur(10px);
+}
+```
+
+**index.ts**
+
+```ts
+import '@videojs/html/video/player';
+import '@videojs/html/ui/container';
+import '@videojs/html/ui/popover';
+```
+
+## API Reference
+
+### media-popover
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `align` | `'start' \| 'center' \| 'end'` | `'center'` | Alignment of the popup along the trigger's edge. |
+| `boundary` | `'viewport' \| 'container' \| string & {}` | — | Boundary used to constrain the popup position. |
+| `closeDelay` (attribute `close-delay`) | `number` | `0` | Delay in ms before closing after pointer leaves. |
+| `closeOnEscape` (attribute `close-on-escape`) | `boolean` | `true` | Close the popup when the Escape key is pressed. |
+| `closeOnOutsideClick` (attribute `close-on-outside-click`) | `boolean` | `true` | Close the popup when clicking outside the trigger and popup. |
+| `defaultOpen` (attribute `default-open`) | `boolean` | `false` | Initial open state for uncontrolled usage. |
+| `delay` | `number` | `300` | Delay in ms before opening on hover. |
+| `modal` | `boolean \| 'trap-focus'` | `false` | - `false` (default): non-modal; background content remains interactive.<br>- `true`: modal; sets `aria-modal="true"` on the popup.<br>- `'trap-focus'`: reserved for future focus-trapping behavior. |
+| `open` | `boolean` | `false` | Controlled open state. When set, the consumer is responsible for toggling. |
+| `openOnHover` (attribute `open-on-hover`) | `boolean` | `false` | Open the popup on pointer hover instead of click. |
+| `side` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'` | Preferred side of the trigger for the popup. |
+
+#### State
+
+State is reflected as data attributes for CSS styling.
+
+| 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'` | Preferred side of the trigger for the popup. |
+| `align` | `'start' \| 'center' \| 'end'` | |
+| `modal` | `boolean \| 'trap-focus'` | |
+
+#### Data attributes
+
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-open` | — | Present when the popover is open. |
+| `data-side` | `'top' \| 'bottom' \| 'left' \| 'right'` | Indicates the rendered side of the popover after collision handling. |
+| `data-align` | `'start' \| 'center' \| 'end'` | Indicates how the popover is aligned relative to the specified side. |
+
+#### CSS custom properties
+
+| Variable | Description |
+| --- | --- |
+| `--media-popover-side-offset` | Distance between the popup and the trigger along the side axis. |
+| `--media-popover-align-offset` | Distance between the popup and the trigger along the alignment axis. |
+| `--media-popover-boundary-offset` | Minimum distance between the popup and the positioning boundary. |
+| `--media-popover-anchor-width` | The anchor element's width. |
+| `--media-popover-anchor-height` | The anchor element's height. |
+| `--media-popover-available-width` | Available width between the trigger and the boundary edge. |
+| `--media-popover-available-height` | Available height between the trigger and the boundary edge. |
+
+#### Events
+
+| Event | Description |
+| --- | --- |
+| `open-change` | Fired when the popover's open state changes. |