@videojs/react 10.0.0-beta.23 → 10.0.0-beta.25

package/docs/reference/popover.md

@@ -0,0 +1,527 @@
+# Popover
+
+A popover component for displaying contextual content anchored to a trigger
+
+## Anatomy
+
+tsx
+
+```
+<Popover.Root>
+  <Popover.Trigger>Open</Popover.Trigger>
+  <Popover.Popup>
+    <Popover.Arrow />
+    Content
+  </Popover.Popup>
+</Popover.Root>
+```
+
+## 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.
+
+The `side` and `align` props control popup placement relative to the trigger. The popup repositions automatically to stay within viewport bounds.
+
+In React, the component is composed from four parts: `Root` manages state, `Trigger` toggles the popover, `Popup` contains the content, and `Arrow` renders a directional arrow.
+
+## Styling
+
+Use [CSS custom properties](#root-css-custom-properties) for positioning offsets:
+
+React renders standard DOM elements. Add a `className` to style them:
+
+css
+
+```
+.popover {
+  --media-popover-side-offset: 8px;
+  --media-popover-align-offset: 0px;
+}
+```
+
+Style based on open state and transition phases:
+
+css
+
+```
+.popover[data-open] .popup {
+  display: block;
+}
+.popover[data-starting-style] .popup {
+  opacity: 0;
+}
+.popover[data-ending-style] .popup {
+  opacity: 0;
+}
+```
+
+## 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
+
+Settings
+
+App.tsx
+
+App.css
+
+```
+import { createPlayer, Popover } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const Player = createPlayer({ features: videoFeatures });
+
+export default function BasicUsage() {
+  return (
+    <Player.Provider>
+      <Player.Container className="media-container">
+        <Video
+          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
+          autoPlay
+          muted
+          playsInline
+          loop
+        />
+        <div className="bar">
+          <Popover.Root>
+            <Popover.Trigger className="trigger">Settings</Popover.Trigger>
+            <Popover.Popup className="popup">
+              <Popover.Arrow className="arrow" />
+              <div className="content">Popover content</div>
+            </Popover.Popup>
+          </Popover.Root>
+        </div>
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.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);
+}
+
+.popup {
+  /* Reset UA [popover] defaults */
+  --media-popover-side-offset: 8px;
+  padding: 12px 16px;
+  margin: 0;
+  font-size: 14px;
+  color: white;
+
+  background: rgba(0, 0, 0, 0.85);
+  border: 0;
+  border-radius: 8px;
+  backdrop-filter: blur(10px);
+}
+
+.arrow {
+  fill: rgba(0, 0, 0, 0.85);
+}
+
+.content {
+  white-space: nowrap;
+}
+```
+
+## API Reference
+
+### 
+
+Root
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`align`
+
+`'start' | 'center' | 'end'`
+
+`'center'`
+
+▸
+
+Description
+
+Alignment of the popup along the trigger's edge.
+
+`closeDelay`
+
+`number`
+
+`0`
+
+▸
+
+Description
+
+Delay in ms before closing after pointer leaves.
+
+`closeOnEscape`
+
+`boolean`
+
+`true`
+
+▸
+
+Description
+
+Close the popup when the Escape key is pressed.
+
+`closeOnOutsideClick`
+
+`boolean`
+
+`true`
+
+▸
+
+Description
+
+Close the popup when clicking outside the trigger and popup.
+
+`defaultOpen`
+
+`boolean`
+
+`false`
+
+▸
+
+Description
+
+Initial open state for uncontrolled usage.
+
+`delay`
+
+`number`
+
+`300`
+
+▸
+
+Description
+
+Delay in ms before opening on hover.
+
+`modal`
+
+`boolean | 'trap-focus'`
+
+`false`
+
+▸
+
+Description
+
+*   `false` (default): non-modal; background content remains interactive.
+*   `true`: modal; sets `aria-modal="true"` on the popup.
+*   `'trap-focus'`: reserved for future focus-trapping behavior.
+
+`open`
+
+`boolean`
+
+`false`
+
+▸
+
+Description
+
+Controlled open state. When set, the consumer is responsible for toggling.
+
+`openOnHover`
+
+`boolean`
+
+`false`
+
+▸
+
+Description
+
+Open the popup on pointer hover instead of click.
+
+`side`
+
+`'top' | 'bottom' | 'left' | 'right'`
+
+`'top'`
+
+▸
+
+Description
+
+Which side of the trigger the popup appears on.
+
+#### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+Property
+
+Type
+
+Details
+
+`open`
+
+`boolean`
+
+`status`
+
+`'idle' | 'starting' | 'ending'`
+
+`side`
+
+`'top' | 'bottom' | 'left' | 'right'`
+
+`align`
+
+`'start' | 'center' | 'end'`
+
+`modal`
+
+`boolean | 'trap-focus'`
+
+`transitionStarting`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the open transition is in progress.
+
+`transitionEnding`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the close transition is in progress.
+
+#### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-open`
+
+▸
+
+Description
+
+Present when the popover is open.
+
+`data-side`
+
+`'top' | 'bottom' | 'left' | 'right'`
+
+▸
+
+Description
+
+Indicates which side the popover is positioned relative to the trigger.
+
+`data-align`
+
+`'start' | 'center' | 'end'`
+
+▸
+
+Description
+
+Indicates how the popover is aligned relative to the specified side.
+
+#### CSS custom properties
+
+Variable
+
+Details
+
+`--media-popover-side-offset`
+
+▸
+
+Description
+
+Distance between the popup and the trigger along the side axis.
+
+`--media-popover-align-offset`
+
+▸
+
+Description
+
+Distance between the popup and the trigger along the alignment axis.
+
+`--media-popover-boundary-offset`
+
+▸
+
+Description
+
+Minimum distance between the popup and the positioning boundary.
+
+`--media-popover-anchor-width`
+
+▸
+
+Description
+
+The anchor element's width.
+
+`--media-popover-anchor-height`
+
+▸
+
+Description
+
+The anchor element's height.
+
+`--media-popover-available-width`
+
+▸
+
+Description
+
+Available width between the trigger and the boundary edge.
+
+`--media-popover-available-height`
+
+▸
+
+Description
+
+Available height between the trigger and the boundary edge.
+
+### 
+
+Arrow
+
+Decorative arrow pointing from the popup toward the trigger. Hidden from assistive technology.
+
+### 
+
+Popup
+
+Container for the popover content. Positioned relative to the trigger using CSS anchor positioning with a JavaScript fallback.
+
+#### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-open`
+
+▸
+
+Description
+
+Present when the popover is open.
+
+`data-side`
+
+`'top' | 'bottom' | 'left' | 'right'`
+
+▸
+
+Description
+
+Indicates which side the popover is positioned relative to the trigger.
+
+`data-align`
+
+`'start' | 'center' | 'end'`
+
+▸
+
+Description
+
+Indicates how the popover is aligned relative to the specified side.
+
+### 
+
+Trigger
+
+Button that toggles the popover visibility. Renders a `<button>` element.
+
+#### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-open`
+
+▸
+
+Description
+
+Present when the popover is open.
+
+`data-side`
+
+`'top' | 'bottom' | 'left' | 'right'`
+
+▸
+
+Description
+
+Indicates which side the popover is positioned relative to the trigger.
+
+`data-align`
+
+`'start' | 'center' | 'end'`
+
+▸
+
+Description
+
+Indicates how the popover is aligned relative to the specified side.

package/docs/reference/poster.md

@@ -0,0 +1,137 @@
+# Poster
+
+Poster image component that displays a thumbnail until video playback starts
+
+## Anatomy
+
+Import the component:
+
+tsx
+
+```
+<Poster src="poster.jpg" alt="Video preview" />
+```
+
+## Behavior
+
+The poster is visible before playback starts. Once the user plays or seeks, the poster hides permanently — pausing does not bring it back. The poster reappears when a new source is loaded.
+
+## Styling
+
+Style the poster with the `[data-visible]` attribute:
+
+React renders an `<img>` element. Add a `className` to style it:
+
+css
+
+```
+.poster:not([data-visible]) {
+  display: none;
+}
+```
+
+You control the child `<img>` — this means `srcset`, `sizes`, `loading="lazy"`, and framework image components all work naturally.
+
+## Accessibility
+
+Unlike the native `<video poster>` attribute, this component allows you to provide accessible text alternatives for screen readers via the `alt` attribute on your child `<img>`. This means you can describe the poster image (e.g., `alt="Keynote speaker at a conference"`) or mark it as decorative with `alt=""` if it doesn’t convey meaningful information.
+
+## Examples
+
+### Basic Usage
+
+![](https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg)Play
+
+App.tsx
+
+App.css
+
+```
+import { createPlayer, PlayButton, Poster } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const Player = createPlayer({ features: videoFeatures });
+
+export default function BasicUsage() {
+  return (
+    <Player.Provider>
+      <Player.Container className="media-container">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" playsInline />
+
+        <Poster
+          className="media-poster"
+          src="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg"
+        />
+
+        <PlayButton
+          className="media-play-button"
+          render={(props, state) => <button {...props}>{state.paused ? 'Play' : 'Pause'}</button>}
+        />
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.media-poster {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  pointer-events: none;
+  object-fit: cover;
+  transition: opacity 0.25s;
+}
+
+.media-poster:not([data-visible]) {
+  opacity: 0;
+}
+
+.media-play-button {
+  position: absolute;
+  bottom: 10px;
+  left: 10px;
+  padding-block: 8px;
+  padding-inline: 16px;
+  color: black;
+  cursor: pointer;
+  background: rgba(255, 255, 255, 0.75);
+  border: 1px solid rgba(255, 255, 255, 0.25);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+```
+
+## API Reference
+
+### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+Property
+
+Type
+
+Details
+
+`visible`
+
+`boolean`
+
+### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-visible`

package/docs/reference/quality-radio-group.md

@@ -0,0 +1,59 @@
+# QualityRadioGroup
+
+A menu radio group for selecting video quality
+
+Creates radio items from the player video rendition state and selects automatic or manual quality.
+
+## Anatomy
+
+tsx
+
+```
+const quality = useQualityOptions();
+
+<Menu.RadioGroup value={quality.value} onValueChange={quality.setValue}>
+  <Menu.GroupLabel>Quality</Menu.GroupLabel>
+  {quality.options.map((option) => (
+    <Menu.RadioItem key={option.value} value={option.value} disabled={option.disabled}>
+      {option.label}
+      <Menu.ItemIndicator checked={option.value === quality.value} />
+    </Menu.RadioItem>
+  ))}
+</Menu.RadioGroup>
+```
+
+## Behavior
+
+The group is available when the configured media exposes more than one video rendition. The first generated option is `Auto`; selecting it returns control to adaptive bitrate selection. Pass `formatRendition` to customize visible rendition labels.
+
+`useQualityOptions` returns `null` when the [quality feature](./feature-quality.md) is not configured. Use the returned options with [`Menu.RadioGroup`](./menu.md).
+
+## Styling
+
+Attribute
+
+Values
+
+Description
+
+`data-quality`
+
+`string`
+
+Current quality value.
+
+`data-disabled`
+
+Present / absent
+
+Present when quality selection is disabled.
+
+`data-availability`
+
+`"available"` / `"unavailable"`
+
+Whether multiple renditions are available.
+
+## Accessibility
+
+The group uses the menu radio group pattern. It receives an accessible label from the `label` prop or defaults to `Quality`.