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

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. |

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

@@ -4,17 +4,13 @@ Poster image component that displays a thumbnail until video playback starts
 
 ## Import
 
-ts
-
-```
+```ts
 import '@videojs/html/ui/poster';
 ```
 
 ## Anatomy
 
-html
-
-```
+```html
 <media-poster>
   <img alt="" />
 </media-poster>
@@ -28,9 +24,7 @@ The `<img>` child is optional. Leave it out and `<media-poster>` draws one of it
 
 You can set the poster URL on the player. This is useful when you want to change the poster from inside a skin, or keep all your media metadata in one place:
 
-html
-
-```
+```html
 <video-player poster="poster.jpg"></video-player>
 ```
 
@@ -40,9 +34,7 @@ The component fills in a source only when you leave one out. `srcset`, `sizes`,
 
 `<media-poster>` draws a fallback image in its shadow DOM and fills in its `src`. Put an `<img>` inside it and the element uses yours instead, filling in its `src` the same way:
 
-html
-
-```
+```html
 <media-poster>
   <img alt="" />
 </media-poster>
@@ -50,9 +42,7 @@ html
 
 Give that image a `src`, a `srcset`, or `<source>` candidates and it is yours; the component leaves it alone:
 
-html
-
-```
+```html
 <media-poster>
   <img src="poster.jpg" srcset="poster-480.jpg 480w, poster-1080.jpg 1080w" alt="Keynote speaker" />
 </media-poster>
@@ -60,9 +50,7 @@ html
 
 Inside a skin, slot your image instead. The skin carries a plain one that yours replaces:
 
-html
-
-```
+```html
 <video-skin>
   <video src="video.mp4" playsinline></video>
   <img slot="poster" src="poster.jpg" alt="Keynote speaker" />
@@ -73,41 +61,16 @@ A skin can only style an `<img>` you slot directly. Wrap one in a `<picture>` or
 
 ## Styling
 
-Attribute
-
-Values
-
-Description
-
-`data-visible`
-
-Present / absent
-
-Present before playback starts
-
-`data-loading`
-
-Present / absent
-
-Present while the image is fetching
-
-`data-loaded`
-
-Present / absent
-
-Present once the image has loaded
-
-`data-error`
-
-Present / absent
-
-Present when the image failed
+| Attribute | Values | Description |
+| --- | --- | --- |
+| `data-visible` | Present / absent | Present before playback starts |
+| `data-loading` | Present / absent | Present while the image is fetching |
+| `data-loaded` | Present / absent | Present once the image has loaded |
+| `data-error` | Present / absent | Present when the image failed |
 
 The three load attributes track the image on screen, including one you supplied yourself.
 
-css
-
-```
+```css
 media-poster:not([data-visible]) {
   opacity: 0;
 }
@@ -115,9 +78,7 @@ media-poster:not([data-visible]) {
 
 The image the element draws is exposed as a part. An image you supply is an ordinary child, so style it as a descendant:
 
-css
-
-```
+```css
 media-poster::part(image),
 media-poster img {
   object-fit: cover;
@@ -132,9 +93,7 @@ Unlike the native `<video poster>` attribute, this component lets you describe t
 
 The image is decorative by default (`alt=""`), since a URL says nothing about what the image shows. When the poster carries meaning, say so:
 
-html
-
-```
+```html
 <media-poster>
   <img src="poster.jpg" alt="Keynote speaker at a conference" />
 </media-poster>
@@ -146,15 +105,9 @@ Whether a poster is informative or decorative is your judgment, per the [WAI gui
 
 ### Basic Usage
 
- Play Pause
-
-index.html
+**index.html**
 
-index.css
-
-index.ts
-
-```
+```html
 <!-- TODO: add a captions track to the demo. -->
 <video-player class="video-player" poster="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg">
   <media-container>
@@ -171,7 +124,10 @@ index.ts
   </media-container>
 </video-player>
 ```
-```
+
+**index.css**
+
+```css
 .video-player media-container {
   position: relative;
   display: block;
@@ -225,7 +181,10 @@ index.ts
   display: inline;
 }
 ```
-```
+
+**index.ts**
+
+```ts
 import '@videojs/html/video/player';
 import '@videojs/html/ui/container';
 import '@videojs/html/ui/play-button';
@@ -234,110 +193,31 @@ import '@videojs/html/ui/poster';
 
 ## API Reference
 
-### 
+### media-poster
 
-media-poster
+`<media-poster>` — sets `src` on a poster image it does not own.
 
-Manages poster visibility and image loading state.
+The image is a child, as in `<picture>`, but sourcing runs the other way around: `<picture>` treats the `src` on its `<img>` as the fallback, while here an image with no source of its own is the one this element fills in. Give the child a `src`, a `srcset`, or `<source>` candidates and it is yours, left alone.
 
-Renders a `div` and exposes `data-visible`, `data-loading`, `data-loaded`, and `data-error` for styling every layer in the poster presentation. Render `Poster.Image` inside it for the image that supplies the loading lifecycle.
+Left empty, the element draws an image of its own in its shadow root. Supply one as a child to describe it or wrap it: `<media-poster><img alt="Keynote speaker"></media-poster>`. Inside a skin, an `<img slot="poster">` of yours replaces the one the skin carries.
 
 #### State
 
 State is reflected as data attributes for CSS styling.
 
-Property
-
-Type
-
-Details
-
-`visible`
-
-`boolean`
-
-▸
-
-Description
-
-Whether the poster should be shown, which it is until playback starts.
-
-`src`
-
-`string`
-
-▸
-
-Description
-
-Resolved poster URL, empty when nothing supplied one.
-
-`loading`
-
-`boolean`
-
-▸
-
-Description
-
-Whether the poster image is fetching.
-
-`loaded`
-
-`boolean`
-
-▸
-
-Description
-
-Whether the poster image has decoded.
-
-`error`
-
-`boolean`
-
-▸
-
-Description
-
-Whether the poster image failed.
+| Property | Type | Description |
+| --- | --- | --- |
+| `visible` | `boolean` | Whether the poster should be shown, which it is until playback starts. |
+| `src` | `string` | Resolved poster URL, empty when nothing supplied one. |
+| `loading` | `boolean` | Whether the poster image is fetching. |
+| `loaded` | `boolean` | Whether the poster image has decoded. |
+| `error` | `boolean` | Whether the poster image failed. |
 
 #### Data attributes
 
-Attribute
-
-Type
-
-Details
-
-`data-visible`
-
-▸
-
-Description
-
-Present until playback starts.
-
-`data-loading`
-
-▸
-
-Description
-
-Present while the poster image is fetching.
-
-`data-loaded`
-
-▸
-
-Description
-
-Present once the poster image has decoded.
-
-`data-error`
-
-▸
-
-Description
-
-Present when the poster image failed.
+| Attribute | Description |
+| --- | --- |
+| `data-visible` | Present until playback starts. |
+| `data-loading` | Present while the poster image is fetching. |
+| `data-loaded` | Present once the poster image has decoded. |
+| `data-error` | Present when the poster image failed. |