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

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

@@ -0,0 +1,173 @@
+# vimeo-video
+
+Video component that plays Vimeo videos and live events through the Vimeo player
+
+Of the embed-backed media components, the [Vimeo player SDK](https://developer.vimeo.com/player/sdk) comes closest to a native `<video>`: volume, mute, playback rate, seeking, looping, and picture-in-picture all work, and the embed pushes real events instead of being polled. Vimeo’s 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 Vimeo’s UI instead.
+
+## Import
+
+```bash
+pnpm add @videojs/vimeo-video
+```
+
+```ts
+import '@videojs/html/media/vimeo-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.3/media/vimeo-video.js"></script>
+```
+
+## Load a source
+
+`src` takes a numeric video id or a Vimeo URL. Watch (`vimeo.com/<id>`), embed (`player.vimeo.com/video/<id>`), and event (`vimeo.com/event/<id>`) URLs all work.
+
+```html
+<vimeo-video src="https://vimeo.com/76979871"></vimeo-video>
+```
+
+Collection URLs aren’t supported: channels, showcases, albums, groups, on-demand pages, and user-scoped paths carry no id the player can load. Link to a specific video instead. `#t=` fragments are ignored as well; use `engine.vimeo.start_time` to start partway in.
+
+## Unlisted videos
+
+An unlisted video needs the hash Vimeo issues alongside its id. Pass it the way Vimeo writes it, either as a trailing path segment or as an `h` parameter:
+
+```plaintext
+https://vimeo.com/76979871/abc123def
+https://vimeo.com/76979871?h=abc123def
+```
+
+Both reach the embed as its `h` parameter. When a URL carries the hash in both places, the `h` parameter wins.
+
+## Live events
+
+A `vimeo.com/event/<id>` URL plays that event through Vimeo’s event embed, and its unlisted hash becomes a path segment rather than a parameter. The media reports no stream type or live window, so a player skin renders it with the same controls as an on-demand video rather than a live UI.
+
+## Behavior
+
+- Fullscreen goes through the Vimeo player, so Vimeo’s own fullscreen chrome appears and the player reports the state back.
+- Captions round-trip by name only: the embed’s track list appears in `textTracks` and selecting one enables it, but no cues cross over. Vimeo draws captions inside the iframe.
+- `poster` has no effect. The embed shows its own thumbnail, which `engine.vimeo.thumbnail_id` picks.
+- `playbackRate` is limited to Vimeo’s supported range, 0.5 through 2.
+- `playsInline` and `preload` are read when the embed URL is built, so changing them later doesn’t take effect.
+- The video’s Vimeo title arrives as content data, so a player skin can show it without fetching anything yourself.
+
+## Examples
+
+### Basic Usage
+
+**index.html**
+
+```html
+<vimeo-video class="vimeo-video" src="https://vimeo.com/76979871" controls></vimeo-video>
+```
+
+**index.css**
+
+```css
+.vimeo-video {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+```
+
+**index.ts**
+
+```ts
+import '@videojs/html/media/vimeo-video';
+```
+
+## API Reference
+
+### Attributes
+
+These attributes configure the embedded media adapter:
+
+| Attribute | Type | Default |
+| --- | --- | --- |
+| `autoplay` | `boolean` | `false` |
+| `controls` | `boolean` | `false` |
+| `disablepictureinpicture` | `boolean` | — |
+| `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. |
+| `contentData` | `{ title?: string \| null; poster?: string \| null; storyboard?: string \| null; readonly [key: string]: MediaContentValue }` | — | Read-only. Metadata Vimeo reports about the loaded video, keyed by what it is — `title` for now. Unlike a Mux source, none of it can be derived from `src`; the embed has to report it, so the key is absent until then and empties again across a source change. `contentdatachange` announces both. |
+| `controls` | `boolean` | `false` | |
+| `currentSrc` | `string` | — | Read-only. |
+| `currentTime` | `number` | — | |
+| `defaultMuted` | `boolean` | `false` | |
+| `disablePictureInPicture` | `boolean` | — | |
+| `duration` | `number` | — | Read-only. |
+| `ended` | `boolean` | — | Read-only. |
+| `engine` | `VimeoPlayer \| null` | — | Read-only. Underlying `@vimeo/player` instance. Null until an embed URL can be resolved, which may be after `attach()`. |
+| `error` | `{ code: number; message: string } \| null` | — | Read-only. |
+| `isFullscreen` | `boolean` | — | Read-only. |
+| `isPictureInPicture` | `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?: VimeoSourceEngineConfig } \| null` | `null` | Structured source: `src` plus embed options under `engine.vimeo`. Replacing it re-derives `src`. |
+| `src` | `string` | `''` | |
+| `textTracks` | `TextTrackListLike` | — | Read-only. |
+| `videoHeight` | `number` | — | Read-only. |
+| `videoWidth` | `number` | — | Read-only. |
+| `volume` | `number` | — | |
+
+### Engine options
+
+#### `source.engine.vimeo`
+
+Pass [Vimeo embed parameters](https://developer.vimeo.com/player/sdk/embed) under `source.engine.vimeo`, spelled exactly as Vimeo spells them. [Media Sources](../../guides/media-sources.md) covers how engine options fit into a structured source.
+
+These options are typed from Vimeo’s own SDK, so your editor completes every parameter and rejects one Vimeo doesn’t have. That also means the list covers Vimeo’s oEmbed API alongside the player: `id` and `url` both override the video `src` names, and `width`, `height`, `maxwidth`, `maxheight`, and `responsive` size an oEmbed response rather than this element. Pass the video through `src`, and size the element with CSS.
+
+`autoplay`, `controls`, `loop`, `muted`, `playsinline`, and `preload` come from the props of the same name. Setting them here overrides the prop, which is worth knowing when a value seems to be ignored. The element also sends `transparent: false`, where Vimeo’s default is `true`.
+
+```ts
+const video = document.querySelector('vimeo-video');
+video.source = {
+  src: 'https://vimeo.com/76979871',
+  engine: { vimeo: { color: 'f03e3e', start_time: 30, speed: true } },
+};
+```
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `referrerPolicy` | `ReferrerPolicy \| undefined` | `referrerpolicy` for the embed iframe. Not a Vimeo embed parameter. |
+
+### Methods
+
+Supports these media methods: `exitFullscreen`, `exitPictureInPicture`, `load`, `pause`, `play`, `requestFullscreen`, `requestPictureInPicture`.
+
+### Events
+
+Implements these standard media events through the embedded player: `durationchange`, `emptied`, `ended`, `enterpictureinpicture`, `error`, `leavepictureinpicture`, `loadedmetadata`, `loadstart`, `pause`, `play`, `playing`, `progress`, `ratechange`, `resize`, `seeked`, `seeking`, `timeupdate`, `volumechange`, `waiting`.
+
+Also emits these Video.js-specific events:
+
+| Event | Description |
+| --- | --- |
+| `contentdatachange` | Fired when the embed reports a title and when that title is cleared. Read `contentData` for the new value. |
+| `fullscreenchange` | |
+| `loadcomplete` | |
+| `sourcechange` | Fired when `source` changes, either directly or by resolving a new `src`. Read `source` for the new value. |

package/docs/reference/components/volume-indicator.md

@@ -0,0 +1,293 @@
+# media-volume-indicator
+
+Display temporary visual feedback for keyboard and gesture volume actions
+
+## Import
+
+```ts
+import '@videojs/html/ui/volume-indicator';
+import '@videojs/html/ui/volume-indicator-fill';
+import '@videojs/html/ui/volume-indicator-value';
+```
+
+## Anatomy
+
+```html
+<media-volume-indicator>
+  <media-volume-indicator-fill>
+    <media-volume-indicator-value></media-volume-indicator-value>
+  </media-volume-indicator-fill>
+</media-volume-indicator>
+```
+
+## Behavior
+
+`<media-volume-indicator>` displays feedback for `toggleMuted` and `volumeStep` actions emitted by a [`<media-hotkey>`](./hotkey.md) or [`<media-gesture>`](./gesture.md) in the same player `<media-container>`. It does not react to mute buttons, volume sliders, direct player-store changes, or volume changes on their own.
+
+The input event arrives before its action is resolved. The indicator uses the media snapshot from that moment to predict the next mute state and volume. `toggleMuted` predicts the opposite mute state. `volumeStep` adds its `value` to the snapshot volume and clamps the result from 0 to 1. A step whose clamped result is above 0 also predicts that mute will clear.
+
+The root exposes the predicted level:
+
+| `data-level` | Predicted state |
+| --- | --- |
+| `"off"` | Muted or volume is 0 |
+| `"low"` | Unmuted volume is greater than 0 and at most 0.5 |
+| `"high"` | Unmuted volume is greater than 0.5 |
+
+`<media-volume-indicator-value>` displays the rounded percentage from 0% through 100%. `<media-volume-indicator-fill>` receives the same percentage through `--media-volume-fill`. Nest the value inside the fill so the progress treatment and text form one visual unit.
+
+The indicator closes after `closeDelay`, which defaults to 800 milliseconds. Repeated handled actions update the current value and restart that close timer without replaying the entry transition. Each update uses the latest media snapshot; the component does not independently accumulate volume steps.
+
+The element remains in the document with `hidden` until the next handled action.
+
+When a nonzero `volumeStep` cannot move past an already-clamped edge, `data-min` or `data-max` is present for 300 milliseconds. Hitting the same edge again briefly clears the attribute, then restores it on the next task so a CSS boundary animation can restart. Merely reaching 0% or 100% does not trigger the boundary attribute until another step tries to move farther.
+
+## Styling
+
+| Attribute | Values | Description |
+| --- | --- | --- |
+| `data-open` | Present / absent | Present while the indicator is open |
+| `data-level` | `"off"`, `"low"`, or `"high"` | Predicted volume level |
+| `data-min` | Present / absent | Present briefly after a blocked downward step at minimum volume |
+| `data-max` | Present / absent | Present briefly after a blocked upward step at maximum volume |
+| `data-starting-style` | Present / absent | Present during the open transition |
+| `data-ending-style` | Present / absent | Present during the close transition |
+
+`--media-volume-fill` is set on `<media-volume-indicator-fill>`, not `<media-volume-indicator>`. Read it from a fill selector when sizing a progress treatment.
+
+```css
+media-volume-indicator-fill::before {
+  width: var(--media-volume-fill, 0%);
+}
+
+media-volume-indicator[data-starting-style],
+media-volume-indicator[data-ending-style] {
+  opacity: 0;
+}
+```
+
+## Accessibility
+
+`<media-volume-indicator>` is visual feedback and does not create a live region. Keep volume and mute available through keyboard-operable controls, and pair the player with [`<media-status-announcer>`](./status-announcer.md) when state changes should be announced to screen readers. Do not make `<media-volume-indicator-value>` a live region.
+
+## Examples
+
+### Basic Usage
+
+Focus the player, then press M to mute or unmute. Use Arrow Up and Arrow Down to adjust volume by 5%.
+
+**index.html**
+
+```html
+<video-player>
+  <media-container class="html-volume-indicator-basic" tabindex="0">
+    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
+    <p class="html-volume-indicator-basic__instructions">Focus the player · M: mute · ↑/↓: volume ±5%</p>
+    <media-volume-indicator class="html-volume-indicator-basic__indicator" aria-hidden="true">
+      <media-volume-indicator-fill class="html-volume-indicator-basic__fill">
+        <media-volume-indicator-value class="html-volume-indicator-basic__value"></media-volume-indicator-value>
+      </media-volume-indicator-fill>
+    </media-volume-indicator>
+    <media-hotkey keys="m" action="toggleMuted"></media-hotkey>
+    <media-hotkey keys="ArrowUp" action="volumeStep" value="0.05"></media-hotkey>
+    <media-hotkey keys="ArrowDown" action="volumeStep" value="-0.05"></media-hotkey>
+  </media-container>
+</video-player>
+```
+
+**index.css**
+
+```css
+.html-volume-indicator-basic {
+  position: relative;
+}
+
+.html-volume-indicator-basic:focus-visible {
+  outline: 3px solid #60a5fa;
+  outline-offset: 2px;
+}
+
+.html-volume-indicator-basic video {
+  display: block;
+  width: 100%;
+}
+
+.html-volume-indicator-basic__instructions {
+  position: absolute;
+  top: 10px;
+  left: 50%;
+  padding: 6px 10px;
+  margin: 0;
+  color: white;
+  text-align: center;
+  background: rgb(0 0 0 / 70%);
+  border-radius: 4px;
+  translate: -50%;
+}
+
+.html-volume-indicator-basic__indicator {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  display: grid;
+  min-width: 220px;
+  padding: 18px 20px 34px;
+  color: white;
+  pointer-events: none;
+  background: rgb(0 0 0 / 72%);
+  border-radius: 12px;
+  place-items: center;
+  translate: -50% -50%;
+  transition:
+    opacity 160ms ease-in-out,
+    scale 160ms ease-in-out;
+}
+
+.html-volume-indicator-basic__indicator::before {
+  margin-bottom: 12px;
+  font-size: 28px;
+  line-height: 1;
+}
+
+.html-volume-indicator-basic__indicator[data-level="off"]::before {
+  content: "🔇";
+}
+
+.html-volume-indicator-basic__indicator[data-level="low"]::before {
+  content: "🔉";
+}
+
+.html-volume-indicator-basic__indicator[data-level="high"]::before {
+  content: "🔊";
+}
+
+.html-volume-indicator-basic__fill {
+  position: relative;
+  width: 180px;
+  height: 10px;
+  background: rgb(255 255 255 / 25%);
+  border-radius: 9999px;
+}
+
+.html-volume-indicator-basic__fill::before {
+  position: absolute;
+  inset-block: 0;
+  left: 0;
+  width: var(--media-volume-fill, 0%);
+  content: "";
+  background: currentColor;
+  border-radius: inherit;
+  transition: width 160ms linear;
+}
+
+.html-volume-indicator-basic__value {
+  position: absolute;
+  top: calc(100% + 6px);
+  left: 50%;
+  font-variant-numeric: tabular-nums;
+  translate: -50%;
+}
+
+.html-volume-indicator-basic__indicator[data-starting-style],
+.html-volume-indicator-basic__indicator[data-ending-style] {
+  opacity: 0;
+  scale: 0.85;
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .html-volume-indicator-basic__indicator[data-min],
+  .html-volume-indicator-basic__indicator[data-max] {
+    animation: html-volume-indicator-basic-shake 300ms linear;
+  }
+}
+
+@keyframes html-volume-indicator-basic-shake {
+  20% {
+    translate: calc(-50% - 8px) -50%;
+  }
+
+  40% {
+    translate: calc(-50% + 6px) -50%;
+  }
+
+  60% {
+    translate: calc(-50% - 4px) -50%;
+  }
+
+  80% {
+    translate: calc(-50% + 2px) -50%;
+  }
+}
+```
+
+**index.ts**
+
+```ts
+import '@videojs/html/video/player';
+import '@videojs/html/ui/container';
+import '@videojs/html/ui/hotkey';
+import '@videojs/html/ui/volume-indicator';
+import '@videojs/html/ui/volume-indicator-fill';
+import '@videojs/html/ui/volume-indicator-value';
+
+const initializedVideos = new WeakSet<HTMLVideoElement>();
+
+function initializeDemos(): void {
+  document.querySelectorAll<HTMLVideoElement>('.html-volume-indicator-basic video').forEach((video) => {
+    if (initializedVideos.has(video)) return;
+
+    initializedVideos.add(video);
+    video.volume = 0.5;
+  });
+}
+
+initializeDemos();
+document.addEventListener('astro:page-load', initializeDemos);
+```
+
+## API Reference
+
+### media-volume-indicator
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `closeDelay` (attribute `close-delay`) | `number` | — | Delay in milliseconds before the indicator closes. |
+
+#### 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 indicator is open. |
+| `generation` | `number` | Increments each time a volume input action updates the indicator. |
+| `level` | `'off' \| 'low' \| 'high' \| null` | Predicted volume level after the input action. |
+| `value` | `string \| null` | Predicted volume formatted as a percentage. |
+| `fill` | `string \| null` | Predicted volume percentage used by the Fill part. |
+| `min` | `boolean` | Whether a downward step tried to move past minimum volume. |
+| `max` | `boolean` | Whether an upward step tried to move past maximum volume. |
+
+#### Data attributes
+
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-open` | — | Present while the indicator is open. |
+| `data-level` | `'off' \| 'low' \| 'high' \| null` | Predicted volume level as `"off"`, `"low"`, or `"high"`. |
+| `data-min` | — | Present briefly when a downward step cannot lower the volume further. |
+| `data-max` | — | Present briefly when an upward step cannot raise the volume further. |
+| `data-starting-style` | — | Present during the open transition. |
+| `data-ending-style` | — | Present during the close transition. |
+
+#### CSS custom properties
+
+| Variable | Description |
+| --- | --- |
+| `--media-volume-fill` | Current predicted volume percentage, set on the Fill part. |
+
+### media-volume-indicator-fill
+
+### media-volume-indicator-value

package/docs/reference/components/volume-popover.md

@@ -0,0 +1,232 @@
+# media-volume-popover
+
+A volume-aware popover that keeps mute available when volume level controls are unavailable
+
+## Import
+
+```ts
+import '@videojs/html/ui/volume-popover';
+import '@videojs/html/ui/mute-button';
+import '@videojs/html/ui/volume-slider';
+import '@videojs/html/ui/slider-track';
+import '@videojs/html/ui/slider-fill';
+import '@videojs/html/ui/slider-thumb';
+```
+
+## Anatomy
+
+```html
+<media-mute-button commandfor="volume-popup"></media-mute-button>
+<media-volume-popover id="volume-popup">
+  <media-volume-slider></media-volume-slider>
+</media-volume-popover>
+```
+
+## Behavior
+
+`<media-volume-popover>` combines [popover behavior](./popover.md) with volume availability. When volume level controls are unavailable, it closes and omits the popup while keeping the mute trigger rendered. This lets media with fixed volume keep mute control without exposing a nonfunctional slider.
+
+The trigger can target the popup with `commandfor`. An immediately adjacent trigger is linked automatically when neither element has an authored ID.
+
+## Styling
+
+The popup reflects `data-availability="available"` while it can render volume controls.
+
+When it cannot, the element also receives native `hidden` and `data-hidden`.
+
+```css
+media-volume-popover[data-open] {
+  opacity: 1;
+}
+```
+
+## Accessibility
+
+The trigger receives `aria-haspopup`, `aria-expanded`, and `aria-controls` while the volume popup is available. When only mute is available, the trigger keeps the mute button’s own accessible name and behavior without popup ARIA.
+
+## Examples
+
+### Basic usage
+
+**index.html**
+
+```html
+<video-player class="html-volume-popover-basic">
+  <media-container>
+    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
+    <div class="html-volume-popover-basic__controls">
+      <media-mute-button commandfor="volume-popover-demo" class="html-volume-popover-basic__trigger">
+        <span class="muted">Unmute</span>
+        <span class="unmuted">Mute</span>
+      </media-mute-button>
+      <media-volume-popover id="volume-popover-demo" open-on-hover side="top" class="html-volume-popover-basic__popup">
+        <media-volume-slider orientation="vertical" class="html-volume-popover-basic__slider">
+          <media-slider-track class="html-volume-popover-basic__track">
+            <media-slider-fill class="html-volume-popover-basic__fill"></media-slider-fill>
+          </media-slider-track>
+          <media-slider-thumb class="html-volume-popover-basic__thumb"></media-slider-thumb>
+        </media-volume-slider>
+      </media-volume-popover>
+    </div>
+  </media-container>
+</video-player>
+```
+
+**index.css**
+
+```css
+.html-volume-popover-basic media-container {
+  position: relative;
+  display: block;
+}
+
+.html-volume-popover-basic video {
+  width: 100%;
+}
+
+.html-volume-popover-basic__controls {
+  position: absolute;
+  bottom: 10px;
+  left: 10px;
+}
+
+.html-volume-popover-basic__trigger {
+  padding: 8px 20px;
+  color: black;
+  cursor: pointer;
+  background: rgb(255 255 255 / 70%);
+  border: 1px solid rgb(255 255 255 / 30%);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+
+.html-volume-popover-basic__trigger .muted,
+.html-volume-popover-basic__trigger .unmuted {
+  display: none;
+}
+
+.html-volume-popover-basic__trigger[data-muted] .muted,
+.html-volume-popover-basic__trigger:not([data-muted]) .unmuted {
+  display: inline;
+}
+
+.html-volume-popover-basic__popup {
+  --media-popover-side-offset: 8px;
+  width: 40px;
+  height: 120px;
+  padding: 12px;
+  margin: 0;
+  background: rgb(0 0 0 / 85%);
+  border: 0;
+  border-radius: 8px;
+}
+
+.html-volume-popover-basic__slider {
+  position: relative;
+  display: block;
+  width: 16px;
+  height: 96px;
+  margin: auto;
+  cursor: pointer;
+}
+
+.html-volume-popover-basic__track {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  left: 6px;
+  width: 4px;
+  background: rgb(255 255 255 / 30%);
+  border-radius: 9999px;
+}
+
+.html-volume-popover-basic__fill {
+  position: absolute;
+  right: 0;
+  bottom: 0;
+  left: 0;
+  height: var(--media-slider-fill);
+  background: white;
+  border-radius: inherit;
+}
+
+.html-volume-popover-basic__thumb {
+  position: absolute;
+  bottom: var(--media-slider-fill);
+  left: 1px;
+  width: 14px;
+  height: 14px;
+  background: white;
+  border-radius: 50%;
+  transform: translateY(50%);
+}
+```
+
+**index.ts**
+
+```ts
+import '@videojs/html/video/player';
+import '@videojs/html/ui/container';
+import '@videojs/html/ui/mute-button';
+import '@videojs/html/ui/volume-popover';
+import '@videojs/html/ui/volume-slider';
+import '@videojs/html/ui/slider-track';
+import '@videojs/html/ui/slider-fill';
+import '@videojs/html/ui/slider-thumb';
+```
+
+## API Reference
+
+### media-volume-popover
+
+A volume-aware popover that keeps its adjacent mute trigger available as a fallback.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `align` | `'start' \| 'center' \| 'end'` | — | 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` | — | Delay in ms before closing after pointer leaves. |
+| `closeOnEscape` (attribute `close-on-escape`) | `boolean` | — | Close the popup when the Escape key is pressed. |
+| `closeOnOutsideClick` (attribute `close-on-outside-click`) | `boolean` | — | Close the popup when clicking outside the trigger and popup. |
+| `defaultOpen` (attribute `default-open`) | `boolean` | — | Initial open state for uncontrolled usage. |
+| `delay` | `number` | — | Delay in ms before opening on hover. |
+| `modal` | `boolean \| 'trap-focus'` | — | - `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` | — | Controlled open state. When set, the consumer is responsible for toggling. |
+| `openOnHover` (attribute `open-on-hover`) | `boolean` | — | Open the popup on pointer hover instead of click. |
+| `side` | `'top' \| 'bottom' \| 'left' \| 'right'` | — | 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'` | |
+| `availability` | `'available' \| 'unavailable' \| 'unsupported'` | Whether volume level controls are available. |
+| `hidden` | `boolean` | Whether the popup is hidden because volume level controls are unavailable. |
+
+#### Data attributes
+
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-open` | — | Present when the popover is open. |
+| `data-side` | `'top' \| 'bottom' \| 'left' \| 'right'` | Indicates the rendered side after collision handling. |
+| `data-align` | `'start' \| 'center' \| 'end'` | Indicates how the popup is aligned relative to its side. |
+| `data-starting-style` | — | Present during the open transition. |
+| `data-ending-style` | — | Present during the close transition. |
+| `data-availability` | `'available' \| 'unavailable' \| 'unsupported'` | Indicates volume control availability (`available`, `unavailable`, or `unsupported`). |
+| `data-hidden` | — | Present when volume level controls are unavailable. |
+
+#### Events
+
+| Event | Description |
+| --- | --- |
+| `open-change` | Fired when the popover's open state changes. |