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

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

@@ -4,27 +4,21 @@ Displays the resolved content title for the current media
 
 ## Import
 
-ts
-
-```
+```ts
 import '@videojs/html/ui/title';
 ```
 
 ## Anatomy
 
-html
-
-```
+```html
 <media-title></media-title>
 ```
 
 ## Behavior
 
-The component shows the name of what is playing. It writes its own text, so set the title on the player instead of passing children.
-
-html
+The element renders the resolved title directly as text and owns that text: it replaces any authored content whenever the title updates. Set the title on the player instead.
 
-```
+```html
 <video-player content-title="Big Buck Bunny">
   <video src="video.mp4"></video>
   <media-title></media-title>
@@ -33,18 +27,16 @@ html
 
 A title can come from two places. The player uses the first one that has a value:
 
-1.  The title you set on the player.
-2.  The title the media reports about itself.
+1. The title you set on the player.
+2. The title the media reports about itself.
 
 If neither has a value, there is nothing to show and the title hides itself.
 
-The title is player input, not player state, so change it the way you set it in the first place. The store exposes the resolved `title` to read, and nothing to write. That resolution belongs to the [metadata feature](./feature-metadata.md), which the video and audio presets include.
+The title is player input, not player state, so change it the way you set it in the first place. The store exposes the resolved `title` to read, and nothing to write. That resolution belongs to the [metadata feature](../api/feature-metadata.md), which the video and audio presets include.
 
 `title` already means the tooltip on an element, so the player takes the title as `content-title`, reflected by the `contentTitle` property:
 
-ts
-
-```
+```ts
 const player = document.querySelector("video-player");
 
 player.contentTitle = "Sintel";
@@ -52,23 +44,21 @@ player.contentTitle = "Sintel";
 
 Set it to `null` to hand the title back to the media.
 
-The title shows whenever there is a title to show. It does not follow the controls or playback on its own — when you want it to come and go with the controls, style it against the controls in your own layout, the same way you would any other piece of chrome.
+The component exposes `data-visible` while controls are visible. Use that hook to animate the title with the controls.
 
 ## Styling
 
 When no title resolves, the element sets the native `hidden` attribute and `data-hidden`, so it takes up no space and a background or gradient never sits over empty space.
 
-To fade the title in and out with the controls, style it against a sibling `media-controls` rather than reaching for state on the title itself:
+To fade the title in and out with the controls, use the root’s `data-visible` attribute:
 
-css
-
-```
+```css
 media-title {
   opacity: 0;
   transition: opacity 150ms ease-out;
 }
 
-media-controls[data-visible] ~ media-title {
+media-title[data-visible] {
   opacity: 1;
 }
 ```
@@ -85,15 +75,9 @@ The component does not name the player. To give the player region an accessible
 
 ### Basic Usage
 
-Play Pause
+**index.html**
 
-index.html
-
-index.css
-
-index.ts
-
-```
+```html
 <video-player content-title="Big Buck Bunny">
   <media-container class="html-title-basic">
     <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsinline loop></video>
@@ -105,7 +89,10 @@ index.ts
   </media-container>
 </video-player>
 ```
-```
+
+**index.css**
+
+```css
 .html-title-basic {
   position: relative;
   display: block;
@@ -161,7 +148,10 @@ index.ts
   display: inline;
 }
 ```
-```
+
+**index.ts**
+
+```ts
 import '@videojs/html/video/player';
 import '@videojs/html/ui/container';
 import '@videojs/html/ui/play-button';
@@ -174,44 +164,15 @@ import '@videojs/html/ui/title';
 
 State is reflected as data attributes for CSS styling.
 
-Property
-
-Type
-
-Details
-
-`title`
-
-`MediaMetadataState['title']`
-
-▸
-
-Description
-
-The resolved content title. Empty when no source supplied one.
-
-`hidden`
-
-`boolean`
-
-▸
-
-Description
-
-Whether the component is hidden because no title is available.
+| Property | Type | Description |
+| --- | --- | --- |
+| `title` | `string` | The resolved content title. Empty when no source supplied one. |
+| `hidden` | `boolean` | Whether the component is hidden because no title is available. |
+| `visible` | `boolean` | Whether the player controls are visible. |
 
 ### Data attributes
 
-Attribute
-
-Type
-
-Details
-
-`data-hidden`
-
-▸
-
-Description
-
-Present when the element is hidden because no title is available.
+| Attribute | Description |
+| --- | --- |
+| `data-hidden` | Present when the element is hidden because no title is available. |
+| `data-visible` | Present while the player controls are visible. |

package/docs/reference/components/tooltip.md

@@ -0,0 +1,274 @@
+# media-tooltip
+
+A tooltip component for displaying contextual labels on hover and focus
+
+## Import
+
+```ts
+import '@videojs/html/ui/tooltip';
+import '@videojs/html/ui/tooltip-group';
+import '@videojs/html/ui/tooltip-label';
+import '@videojs/html/ui/tooltip-shortcut';
+```
+
+## Anatomy
+
+```html
+<media-tooltip-group>
+  <button commandfor="my-tooltip">Hover me</button>
+  <media-tooltip id="my-tooltip">
+    <media-tooltip-label>Label text</media-tooltip-label>
+    <media-tooltip-shortcut>K</media-tooltip-shortcut>
+  </media-tooltip>
+</media-tooltip-group>
+```
+
+## Behavior
+
+Displays a short label anchored to a trigger element. Opens after a configurable `delay` (default 600ms) on hover or immediately on focus. Closes when the pointer leaves or focus moves away, with an optional `closeDelay`.
+
+The `side` and `align` props control the preferred placement relative to the trigger. When the preferred side overflows the positioning boundary, the tooltip uses the opposite side if it has more space. Positioning uses CSS Anchor Positioning where supported, with a JavaScript measurement fallback.
+
+The `<media-tooltip>` element is the popup itself. Link it to a trigger using the `commandfor` attribute on any button, pointing to the tooltip’s `id`. The element discovers its trigger automatically and manages open/close state and positioning. Wrap tooltip trigger/popup pairs in `<media-tooltip-group>` to coordinate timing — the group’s `delay`, `close-delay`, and `timeout` attributes control shared timing for all contained tooltips.
+
+Tooltips inside a [player container](./player-container.md) also observe its popup group. By default, a tooltip does not open—or closes if already open—while a menu or popover attached to the same trigger is open. Set `sticky` when the tooltip should remain visible with that trigger’s popup.
+
+`<media-tooltip-group>` coordinates tooltip delay timing only; it does not replace the container’s popup group.
+
+## Styling
+
+Use [CSS custom properties](#css-custom-properties) for positioning offsets:
+
+```css
+media-tooltip {
+  --media-tooltip-side-offset: 8px;
+  --media-tooltip-align-offset: 0px;
+  --media-tooltip-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-tooltip[data-open] {
+  display: block;
+}
+media-tooltip[data-starting-style] {
+  opacity: 0;
+}
+media-tooltip[data-ending-style] {
+  opacity: 0;
+}
+media-tooltip[data-side="top"] {
+  transform-origin: bottom center;
+}
+media-tooltip[data-side="bottom"] {
+  transform-origin: top center;
+}
+```
+
+## Accessibility
+
+Tooltips are visual-only, supplementary labels. The popup renders with `role="presentation"` and is not referenced by the trigger with `aria-describedby`. Give the trigger its own accessible name instead of relying on tooltip content. Built-in media buttons already expose a state-aware `aria-label`, and their tooltips reuse that translated label. Tooltips still open on focus so keyboard users who can see the label receive the same visual hint.
+
+## Examples
+
+### Basic Usage
+
+**index.html**
+
+```html
+<div class="demo">
+  <button type="button" commandfor="tooltip-demo" class="trigger">Hover me</button>
+  <media-tooltip id="tooltip-demo" class="media-tooltip"> Tooltip content </media-tooltip>
+</div>
+```
+
+**index.css**
+
+```css
+.demo {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 40px 24px;
+}
+
+.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-tooltip {
+  --media-tooltip-side-offset: 8px;
+  padding: 4px 10px;
+  font-size: 13px;
+  color: white;
+  white-space: nowrap;
+  pointer-events: none;
+  background: rgba(0, 0, 0, 0.85);
+  border-radius: 6px;
+  backdrop-filter: blur(10px);
+}
+```
+
+**index.ts**
+
+```ts
+import '@videojs/html/ui/tooltip';
+```
+
+### Grouping
+
+Wrap tooltip trigger/popup pairs in `<media-tooltip-group>` to coordinate timing. The group’s `delay`, `close-delay`, and `timeout` attributes control shared timing for all contained tooltips.
+
+**index.html**
+
+```html
+<media-tooltip-group class="demo">
+  <button type="button" commandfor="tooltip-play" class="trigger">Play</button>
+  <media-tooltip id="tooltip-play" class="media-tooltip">Play video</media-tooltip>
+
+  <button type="button" commandfor="tooltip-mute" class="trigger">Mute</button>
+  <media-tooltip id="tooltip-mute" class="media-tooltip">Mute audio</media-tooltip>
+
+  <button type="button" commandfor="tooltip-fullscreen" class="trigger">Fullscreen</button>
+  <media-tooltip id="tooltip-fullscreen" class="media-tooltip">Enter fullscreen</media-tooltip>
+</media-tooltip-group>
+```
+
+**index.css**
+
+```css
+.demo {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 40px 24px;
+}
+
+.trigger {
+  padding: 6px 16px;
+  color: black;
+  cursor: pointer;
+  background: rgba(255, 255, 255, 0.7);
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  backdrop-filter: blur(10px);
+}
+
+.media-tooltip {
+  --media-tooltip-side-offset: 8px;
+  padding: 4px 10px;
+  font-size: 13px;
+  color: white;
+  white-space: nowrap;
+  pointer-events: none;
+  background: rgba(0, 0, 0, 0.85);
+  border-radius: 6px;
+  backdrop-filter: blur(10px);
+}
+```
+
+**index.ts**
+
+```ts
+import '@videojs/html/ui/tooltip';
+import '@videojs/html/ui/tooltip-group';
+```
+
+## API Reference
+
+### media-tooltip-group
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `closeDelay` (attribute `close-delay`) | `number` | — | Default close delay in ms for tooltips in this group. |
+| `delay` | `number` | — | Default open delay in ms for tooltips in this group. |
+| `timeout` | `number` | — | Duration in ms after a tooltip closes during which the next tooltip opens instantly. |
+
+### media-tooltip
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `align` | `'start' \| 'center' \| 'end'` | `'center'` | Alignment of the tooltip along the trigger's edge. |
+| `boundary` | `'viewport' \| 'container' \| string & {}` | — | Boundary used to constrain the tooltip position. |
+| `closeDelay` (attribute `close-delay`) | `number` | `0` | Delay in ms before closing after pointer leaves. |
+| `defaultOpen` (attribute `default-open`) | `boolean` | `false` | Initial open state for uncontrolled usage. |
+| `delay` | `number` | `600` | Delay in ms before opening on hover. |
+| `disabled` | `boolean` | `false` | When true, the tooltip is disabled and will not open. |
+| `disableHoverablePopup` (attribute `disable-hoverable-popup`) | `boolean` | `true` | When true, hovering the popup does not keep it open. |
+| `open` | `boolean` | `false` | Controlled open state. |
+| `side` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'` | Preferred side of the trigger for the tooltip. |
+| `sticky` | `boolean` | `false` | Whether the tooltip stays open when another popup opens from its trigger. |
+
+#### 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` | Whether the tooltip is currently visible. |
+| `status` | `'idle' \| 'starting' \| 'ending'` | Current phase of the transition lifecycle. |
+| `side` | `'top' \| 'bottom' \| 'left' \| 'right'` | Preferred side of the trigger for the tooltip. |
+| `align` | `'start' \| 'center' \| 'end'` | How the tooltip is aligned relative to the specified side. |
+
+#### Data attributes
+
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-open` | — | Present when the tooltip is open. |
+| `data-side` | `'top' \| 'bottom' \| 'left' \| 'right'` | Indicates the rendered side of the tooltip after collision handling. |
+| `data-align` | `'start' \| 'center' \| 'end'` | Indicates how the tooltip is aligned relative to the specified side. |
+
+#### CSS custom properties
+
+| Variable | Description |
+| --- | --- |
+| `--media-tooltip-side-offset` | Distance between the popup and the trigger along the side axis. |
+| `--media-tooltip-align-offset` | Distance between the popup and the trigger along the alignment axis. |
+| `--media-tooltip-boundary-offset` | Minimum distance between the popup and the positioning boundary. |
+| `--media-tooltip-anchor-width` | The anchor element's width. |
+| `--media-tooltip-anchor-height` | The anchor element's height. |
+| `--media-tooltip-available-width` | Available width between the trigger and the boundary edge. |
+| `--media-tooltip-available-height` | Available height between the trigger and the boundary edge. |
+
+#### Events
+
+| Event | Description |
+| --- | --- |
+| `open-change` | Fired when the tooltip's open state changes. |
+
+### media-tooltip-label
+
+Label region inside `media-tooltip`; parent syncs text from the trigger when linked to a media button.
+
+#### Data attributes
+
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-open` | — | Present when the tooltip is open. |
+| `data-side` | `'top' \| 'bottom' \| 'left' \| 'right'` | Indicates the rendered side of the tooltip after collision handling. |
+| `data-align` | `'start' \| 'center' \| 'end'` | Indicates how the tooltip is aligned relative to the specified side. |
+
+### media-tooltip-shortcut
+
+Shortcut hint inside `media-tooltip`. CSS skins: `class="media-tooltip__kbd"`; Tailwind skins: `class` from `popup.tooltipShortcut`.
+
+#### Data attributes
+
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-open` | — | Present when the tooltip is open. |
+| `data-side` | `'top' \| 'bottom' \| 'left' \| 'right'` | Indicates the rendered side of the tooltip after collision handling. |
+| `data-align` | `'start' \| 'center' \| 'end'` | Indicates how the tooltip is aligned relative to the specified side. |

package/docs/reference/components/twitch-video.md

@@ -0,0 +1,161 @@
+# twitch-video
+
+Video component that plays Twitch videos and live channels through the Twitch embed player
+
+The [Twitch embed player](https://dev.twitch.tv/docs/embed/video-and-clips/) handles both recorded videos and live channels. Its own chrome stays hidden by default, so it drops into a [player skin](../../guides/skins.md) like any other media component; set `controls` to use Twitch’s UI instead.
+
+## Import
+
+```bash
+pnpm add @videojs/twitch-video
+```
+
+```ts
+import '@videojs/html/media/twitch-video';
+```
+
+Or load it from the [CDN](../../guides/cdn.md):
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.4/media/twitch-video.js"></script>
+```
+
+## Load a source
+
+`src` takes a video URL (`twitch.tv/videos/<id>`) or a channel URL (`twitch.tv/<channel>`), with or without the `www.` and `go.` hosts. A channel URL plays the channel’s live stream. Clips (`clips.twitch.tv`) are a different embed and aren’t supported.
+
+```html
+<twitch-video src="https://www.twitch.tv/videos/106400740"></twitch-video>
+```
+
+## Live channels
+
+A channel embed behaves like a live media component:
+
+- `duration` reports `Infinity` while the stream is live.
+- Seeking is unavailable: the embed exposes no DVR window.
+- The stream going away and coming back dispatch `offline` and `online` events.
+- `loop` never repeats a channel; a live stream doesn’t end.
+
+## Parent hostnames
+
+Twitch checks the embedding page’s ancestors against a `parent` allowlist and won’t play unless the current page is on it. The element always includes your page’s own hostname, so a plain embed needs no setup. When your player is itself framed by other hostnames, name each of them under `engine.twitch.parent`:
+
+```ts
+const video = document.querySelector('twitch-video');
+video.source = {
+  src: 'https://www.twitch.tv/videos/106400740',
+  engine: { twitch: { parent: ['embed.example.com'] } },
+};
+```
+
+## Behavior
+
+- Volume and mute both work, like a native `<video>`.
+- `playbackRate` is reported but never applied: the embed has no rate command.
+- `loop` restarts a finished video from the top; the embed has no loop parameter.
+- `controls` is read when the embed is built; changing it later doesn’t take effect, since rebuilding the iframe would lose the playback session.
+- Fullscreen targets the iframe, so Twitch’s own chrome shows in fullscreen.
+
+## Examples
+
+### Basic Usage
+
+**index.html**
+
+```html
+<twitch-video class="twitch-video" src="https://www.twitch.tv/videos/106400740" controls></twitch-video>
+```
+
+**index.css**
+
+```css
+.twitch-video {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+```
+
+**index.ts**
+
+```ts
+import '@videojs/html/media/twitch-video';
+```
+
+## API Reference
+
+### Attributes
+
+These attributes configure the embedded media adapter:
+
+| Attribute | Type | Default |
+| --- | --- | --- |
+| `autoplay` | `boolean` | `false` |
+| `controls` | `boolean` | `false` |
+| `loop` | `boolean` | `false` |
+| `muted` | `boolean` | `false` |
+| `playsinline` | `boolean` | `true` |
+| `poster` | `string` | `''` |
+| `preload` | `MediaPreloadType` | `'metadata'` |
+| `src` | `string` | `''` |
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `autoplay` | `boolean` | `false` | |
+| `buffered` | `TimeRangeLike` | — | Read-only. |
+| `controls` | `boolean` | `false` | |
+| `currentSrc` | `string` | — | Read-only. |
+| `currentTime` | `number` | — | |
+| `defaultMuted` | `boolean` | `false` | |
+| `duration` | `number` | — | Read-only. |
+| `ended` | `boolean` | — | Read-only. |
+| `engine` | `Window \| null` | — | Read-only. The embed's own window, which every command is posted to. Null until an embed is bound and in a document. |
+| `error` | `MediaError \| null` | — | Read-only. |
+| `isFullscreen` | `boolean` | — | Read-only. |
+| `loop` | `boolean` | `false` | |
+| `muted` | `boolean` | `false` | |
+| `paused` | `boolean` | — | Read-only. |
+| `playbackRate` | `number` | — | |
+| `played` | `{ length: number; start(index: number): number; end(index: number): number }` | — | Read-only. |
+| `playsInline` | `boolean` | `true` | |
+| `poster` | `string` | `''` | |
+| `preload` | `MediaPreloadType` | `'metadata'` | |
+| `readyState` | `number` | — | Read-only. |
+| `seekable` | `TimeRangeLike` | — | Read-only. |
+| `seeking` | `boolean` | — | Read-only. |
+| `source` | `{ src?: string; engine?: TwitchSourceEngineConfig } \| null` | `null` | Twitch VOD or channel URL in `src`, plus embed parameters under `engine.twitch`. Replacing it re-derives `src`. |
+| `src` | `string` | `''` | |
+| `textTracks` | `TextTrackListLike` | — | Read-only. |
+| `volume` | `number` | — | |
+
+### Engine options
+
+#### `source.engine.twitch`
+
+Pass [Twitch embed parameters](https://dev.twitch.tv/docs/embed/video-and-clips/) under `source.engine.twitch`, spelled exactly as Twitch spells them, plus anything Twitch adds next. [Media Sources](../../guides/media-sources.md) covers how engine options fit into a structured source.
+
+`controls`, `autoplay`, and `muted` come from the props of the same name, and the video or channel comes from `src`, so none of those have an `engine.twitch` spelling.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `collection` | `string \| undefined` | Collection to play through, starting from the video named by `src`. |
+| `parent` | `string \| readonly string[] \| undefined` | Every hostname the embed may be framed by. Twitch checks the frame's ancestors against it and refuses to play when the current page is missing, which is why the page's own hostname is always included on top of this. |
+| `referrerPolicy` | `ReferrerPolicy \| undefined` | `referrerpolicy` for the embed iframe. Not a Twitch embed parameter, so it never reaches the URL: the React player applies it to the iframe it renders, and the HTML player reads its own `referrerpolicy` attribute instead. |
+| `time` | `string \| undefined` | Start position, spelled the way Twitch spells timestamps: `1h30m10s`. |
+
+### Methods
+
+Supports these media methods: `exitFullscreen`, `load`, `pause`, `play`, `requestFullscreen`.
+
+### Events
+
+Implements these standard media events through the embedded player: `durationchange`, `emptied`, `ended`, `error`, `loadedmetadata`, `loadstart`, `playing`, `progress`, `seeked`, `seeking`, `timeupdate`, `volumechange`, `waiting`.
+
+Also emits these Video.js-specific events:
+
+| Event | Description |
+| --- | --- |
+| `loadcomplete` | |
+| `sourcechange` | Fired when `source` changes, either directly or by resolving a new `src`. Read `source` for the new value. |

package/docs/reference/components/video-minimal-skin.md

@@ -0,0 +1,51 @@
+# video-minimal-skin
+
+The video preset's visually lighter skin, closer to a classic control bar
+
+The minimal skin of the video preset: the same player and the same controls in a visually lighter design, closer to a classic control bar. The [default video skin](./video-skin.md) is the same preset’s other variant. See [Skins](../../guides/skins.md) for how packaged skins work and [Presets](../../guides/presets.md) for what the video preset ships.
+
+## Import
+
+```ts
+import '@videojs/html/video/minimal-skin';
+```
+
+The import registers the skin and every UI element it composes. The [CDN](../../guides/cdn.md) player bundle registers this skin together with its player:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.4/video-minimal.js"></script>
+```
+
+## Usage
+
+The skin goes between the player and the media element. It renders its controls around the media.
+
+```html
+<video-player>
+  <video-minimal-skin>
+    <video src="video.mp4"></video>
+  </video-minimal-skin>
+</video-player>
+```
+
+## Poster
+
+The skin renders a poster image before playback starts. An element with `slot="poster"` replaces it.
+
+See [Add a poster and loading placeholder](../../guides/poster.md) for complete examples.
+
+## Thumbnail
+
+The skin renders a storyboard preview image while scrubbing the time slider. An `<img slot="thumbnail">` replaces it, so image attributes such as `crossorigin`, `loading`, and `fetchpriority` go on it.
+
+See [Show timeline thumbnail previews](../../guides/thumbnails.md) for complete examples.
+
+## Styling
+
+Packaged skins style themselves and expose a small set of public CSS custom properties. Everything else inside the skin is private and may change between releases. [Customize skins](../../guides/customize-skins.md#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.
+
+## Own the UI
+
+Packaged skins keep their controls and layout inside Video.js. When you need to add, remove, rearrange, or deeply restyle controls, use Shadcn to add the skin source to your project. Its components, layout, styles, and interactions become local files you can change.
+
+- [Install Video.js with Shadcn](../../guides/installation-shadcn.md#choose-how-to-install): Add editable skin source and build a working React or HTML player