@videojs/react 10.0.0-rc.2 → 10.0.0-rc.3

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

@@ -0,0 +1,92 @@
+# Container
+
+The player's visual and interaction surface for layout, fullscreen, focus, and user activity.
+
+The `Container` is the player’s physical surface. It defines the visual boundary, registers the fullscreen and activity target, and gives gesture and hotkey components a shared interaction surface. It lives inside a [`Player`](./player.md).
+
+```tsx
+<Player>
+  <Container>
+    <Video src="video.mp4" />
+    <Controls.Root>
+      <Controls.Content>{/* ... */}</Controls.Content>
+    </Controls.Root>
+  </Container>
+</Player>
+```
+
+## How it’s created
+
+Import `Container` from the main React package. It connects to whichever `Player` contains it, so it does not need to be created for a specific feature set.
+
+```tsx
+import { Container, createPlayer } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player } = createPlayer({ features: videoFeatures });
+```
+
+- [`createPlayer` reference](../api/create-player.md)
+
+## 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 `Container`, not `Player`. Place overlays inside it, use it as their positioning context, and measure it when your app needs the rendered player size.
+
+```tsx
+<Container style={{ position: 'relative', width: 640, aspectRatio: '16/9' }}>
+  <Video src="video.mp4" />
+  <Controls.Root>
+    <Controls.Content>{/* ... */}</Controls.Content>
+  </Controls.Root>
+</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.
+
+React media components such as `MuxVideo` render a native media element, so the media itself has a box. The container remains the shared layout and fullscreen target for the media and its overlays.
+
+### Media attachment
+
+Media discovery is handled by `Player`, not `Container`. When a media component like `<Video>` registers itself via context, `Player` wires it to the store and all of the player’s features.
+
+### 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 [`Gesture`](./gesture.md) component.
+- **Keyboard controls** — Spacebar to play/pause, arrow keys to seek, and other keyboard shortcuts scoped to the container. Configured via the `Hotkey` component.
+
+### 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 `VideoSkin` for the player’s outer size and aspect ratio. Its `skin.css` import makes the built-in container fill that space and positions the media, controls, poster, and overlays.
+
+If you omit `VideoSkin` to build custom UI, render and style `Container` yourself. See [Layout and fullscreen](#layout-and-fullscreen) for the complete layout example.
+
+## Inside vs. outside the container
+
+[`Player`](./player.md) gives components access to state and actions. `Container` layers on physical behaviors — fullscreen, activity detection, and gesture handling. Components work in both places; the container just adds those extras.
+
+```tsx
+<Player>
+  <Container>
+    <Video src="video.mp4" />
+    <Controls.Root>          {/* fullscreen, activity detection, gestures */}
+      <Controls.Content>{/* ... */}</Controls.Content>
+    </Controls.Root>
+  </Container>
+
+  <Transcript />          {/* state & actions, but no container behaviors */}
+  <PlaylistSidebar />     {/* state & actions, but no container behaviors */}
+</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,102 @@
+# Player
+
+The state boundary — creates a store and broadcasts it to all descendants.
+
+The `Player` is the state boundary of your player. It creates a store and makes it available to every component inside it via context. Every player needs exactly one.
+
+**App.tsx**
+
+```tsx
+import { Video, videoFeatures } from '@videojs/react/video';
+import { Container, createPlayer } from '@videojs/react';
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+function App() {
+  return (
+    <Player>
+      {/* Everything inside can access the player store */}
+      <Container>
+        <Video src="video.mp4" />
+      </Container>
+    </Player>
+  );
+}
+```
+
+## How it’s created
+
+Call `createPlayer()` with a `features` array. It returns `Player`, `usePlayer`, and `useMedia`. Import the shared `Container` separately when building a custom layout.
+
+```tsx
+import { Container, createPlayer } from '@videojs/react';
+import { videoFeatures } from '@videojs/react/video';
+
+const { Player, usePlayer, useMedia } = createPlayer({
+  features: videoFeatures,
+});
+```
+
+The [features](../../guides/features.md) you pass determine what state is available in the store. `videoFeatures` is a [preset](../../guides/presets.md) that includes playback, volume, fullscreen, and other standard video controls.
+
+- [createPlayer reference](../api/create-player.md)
+
+## What lives inside it
+
+Everything that needs player state goes inside `Player`: skins, containers, UI components, and your own custom components. Anything inside can access the store.
+
+```tsx
+<Player>
+  <VideoSkin>           {/* skin — includes container + controls */}
+    <Video src="..." /> {/* media element */}
+  </VideoSkin>
+  <MyCustomOverlay />   {/* your own component — can use usePlayer() */}
+</Player>
+```
+
+## No visual presence
+
+`Player` renders no DOM element of its own — it’s purely a state wrapper. Put sizing, positioning, borders, backgrounds, and DOM measurements on the [`Container`](./player-container.md), not `Player`.
+
+`Player` is the Provider half of a React Context pair, with [`usePlayer`](../api/use-player.md) as its consumer, and it renders nothing. If a component needs player state, lift `Player` above it the way you’d lift any Provider: wrapping a page section, a route, or even your whole app in `Player` costs nothing visually and keeps `usePlayer` available wherever you need it.
+
+## Accessing state
+
+Use `usePlayer` to read state or call actions from any component inside `Player`:
+
+**PlayPauseButton.tsx**
+
+```tsx
+import { selectPlayback, usePlayer } from '@videojs/react';
+
+function PlayPauseButton() {
+  const playback = usePlayer(selectPlayback);
+  if (!playback) return null;
+
+  return (
+    <button onClick={() => playback.togglePaused()}>
+      {playback.paused ? 'Play' : 'Pause'}
+    </button>
+  );
+}
+```
+
+- [usePlayer reference](../api/use-player.md)
+
+## Extended player layouts
+
+The player’s scope can extend beyond the fullscreen target. Playlists, transcripts, sidebars, and other supplementary UI can live inside `Player` but outside `Container`. They still have full access to the store, but they won’t go fullscreen with the video.
+
+```tsx
+<Player>
+  <Container>
+    <Video src="video.mp4" />
+    <Controls.Root>          {/* goes fullscreen with the video */}
+      <Controls.Content>{/* ... */}</Controls.Content>
+    </Controls.Root>
+  </Container>
+
+  <Transcript />          {/* outside container — still has store access */}
+  <PlaylistSidebar />     {/* outside container — still has store access */}
+</Player>
+```

package/docs/reference/components/popover.md

@@ -0,0 +1,259 @@
+# Popover
+
+A popover component for displaying contextual content anchored to a trigger
+
+## Import
+
+```tsx
+import { Popover } from '@videojs/react';
+```
+
+## 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.
+
+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 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](#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;
+  --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
+.popover[data-open] .popup {
+  display: block;
+}
+.popover[data-starting-style] .popup {
+  opacity: 0;
+}
+.popover[data-ending-style] .popup {
+  opacity: 0;
+}
+.popover[data-side="top"] {
+  transform-origin: bottom center;
+}
+.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
+
+**App.tsx**
+
+```tsx
+import { Container, createPlayer, Popover } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+export default function BasicUsage() {
+  return (
+    <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>
+      </Container>
+    </Player>
+  );
+}
+```
+
+**App.css**
+
+```css
+.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 | 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` | `number` | `0` | Delay in ms before closing after pointer leaves. |
+| `closeOnEscape` | `boolean` | `true` | Close the popup when the Escape key is pressed. |
+| `closeOnOutsideClick` | `boolean` | `true` | Close the popup when clicking outside the trigger and popup. |
+| `defaultOpen` | `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` | `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 accessible via the `render`, `className`, and `style` props.
+
+| 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. |
+
+### Arrow
+
+Decorative arrow pointing from the popup toward the trigger. Hidden from assistive technology.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string \| ((state: PopoverState) => string \| undefined)` | — | Class name or function returning class name from state. |
+| `render` | `ReactElement \| ((props: HTMLProps, state: PopoverState) => ReactElement \| null)` | — | Render prop for custom element. |
+| `style` | `CSSProperties \| ((state: PopoverState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |
+
+### Popup
+
+Container for the popover content. Positioned relative to the trigger using CSS anchor positioning with a JavaScript fallback.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string \| ((state: PopoverState) => string \| undefined)` | — | Class name or function returning class name from state. |
+| `render` | `ReactElement \| ((props: HTMLProps, state: PopoverState) => ReactElement \| null)` | — | Render prop for custom element. |
+| `style` | `CSSProperties \| ((state: PopoverState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |
+
+#### 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. |
+
+### Trigger
+
+Button that toggles the popover visibility. Renders a `<button>` element.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string \| ((state: PopoverState) => string \| undefined)` | — | Class name or function returning class name from state. |
+| `render` | `ReactElement \| ((props: HTMLProps, state: PopoverState) => ReactElement \| null)` | — | Render prop for custom element. |
+| `style` | `CSSProperties \| ((state: PopoverState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |
+
+#### 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. |

package/docs/reference/components/poster.md

@@ -0,0 +1,228 @@
+# Poster
+
+Poster image component that displays a thumbnail until video playback starts
+
+## Import
+
+```tsx
+import { Poster } from '@videojs/react';
+```
+
+## Anatomy
+
+```tsx
+<Poster.Root>
+  <Poster.Image />
+</Poster.Root>
+```
+
+## Behavior
+
+The poster shows before playback starts. Once the user plays or seeks, it hides; pausing does not bring it back. Loading a new source shows it again.
+
+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:
+
+```tsx
+<VideoPlayer poster="poster.jpg" />
+```
+
+## Supply your own image
+
+The component fills in a source only when you leave one out. `srcset`, `sizes`, `loading`, `<picture>`, and framework image components all stay available.
+
+`Poster.Root` owns visibility and loading state. Image attributes go on `Poster.Image`:
+
+```tsx
+<Poster.Root>
+  <Poster.Image srcSet="poster-480.jpg 480w, poster-1080.jpg 1080w" sizes="100vw" />
+</Poster.Root>
+```
+
+To render a different image component, use `render` on `Poster.Image`. It receives the poster URL as `src`, undefined until one resolves:
+
+```tsx
+<Poster.Root>
+  <Poster.Image
+    render={({ src, ...props }: ComponentProps<'img'>) =>
+      src ? <Image {...props} src={src} alt="" fill /> : null
+    }
+  />
+</Poster.Root>
+```
+
+Inside a skin, pass the same function as `renderPoster`. The skin draws your image in place of its own:
+
+```tsx
+<VideoSkin
+  renderPoster={({ src, ...props }: ComponentProps<'img'>) =>
+    src ? <Image {...props} src={src} alt="" fill /> : null
+  }
+/>
+```
+
+A skin styles the `<img>` it draws directly. Render something that is not an `<img>` and its sizing is yours.
+
+## 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 |
+
+The three load attributes track the image on screen, including one you supplied yourself.
+
+React renders a root `<div>` around the `<img>`. The state attributes are on `Poster.Root`, so other presentation layers can use the same lifecycle:
+
+```tsx
+<Poster.Root className="media-poster">
+  <img className="media-poster-blur" src={blurDataURL} alt="" aria-hidden />
+  <Poster.Image className="media-poster-image" />
+  <div className="media-poster-overlay" aria-hidden />
+</Poster.Root>
+```
+
+```css
+.media-poster:not([data-visible]) {
+  opacity: 0;
+}
+
+.media-poster:not([data-loading]) .media-poster-blur {
+  opacity: 0;
+}
+```
+
+## Accessibility
+
+Unlike the native `<video poster>` attribute, this component lets you describe the poster for screen readers.
+
+The image is decorative by default (`alt=""`), since a URL says nothing about what the image shows. When the poster carries meaning, say so:
+
+```tsx
+<Poster.Root>
+  <Poster.Image alt="Keynote speaker at a conference" />
+</Poster.Root>
+```
+
+Whether a poster is informative or decorative is your judgment, per the [WAI guidelines](https://www.w3.org/WAI/tutorials/images/decorative/).
+
+## Examples
+
+### Basic Usage
+
+**App.tsx**
+
+```tsx
+import { Container, createPlayer, PlayButton, Poster } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+export default function BasicUsage() {
+  return (
+    <Player poster="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg">
+      <Container className="media-container">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" playsInline />
+
+        <Poster.Root className="media-poster">
+          <Poster.Image className="media-poster-image" />
+        </Poster.Root>
+
+        <PlayButton
+          className="media-play-button"
+          render={(props, state) => <button {...props}>{state.paused ? 'Play' : 'Pause'}</button>}
+        />
+      </Container>
+    </Player>
+  );
+}
+```
+
+**App.css**
+
+```css
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.media-poster {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  pointer-events: none;
+  transition: opacity 0.25s;
+}
+
+.media-poster:not([data-visible]) {
+  opacity: 0;
+}
+
+.media-poster-image {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.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
+
+### Root
+
+Manages poster visibility and image loading state.
+
+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.
+
+#### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+| 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 | 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. |
+
+### Image
+
+Displays the poster image managed by `Poster.Root`.
+
+Renders an `img`, so `srcSet`, `sizes`, `loading`, and the rest of the native image attributes remain available. Leave the source off and the player's resolved poster fills it in. The image is decorative unless you supply `alt`.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string \| ((state: PosterState) => string \| undefined)` | — | Class name or function returning class name from state. |
+| `render` | `ReactElement \| ((props: HTMLProps, state: PosterState) => ReactElement \| null)` | — | Render prop for custom element. |
+| `style` | `CSSProperties \| ((state: PosterState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |