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

package/docs/reference/play-button.md

@@ -0,0 +1,224 @@
+# PlayButton
+
+Accessible play/pause button with keyboard support and customizable rendering
+
+## Anatomy
+
+tsx
+
+```
+<PlayButton />
+```
+
+## Behavior
+
+PlayButton is a three-state button: **play**, **pause**, and **replay**. When media reaches the end (`ended` state), clicking restarts playback from the beginning.
+
+## Styling
+
+Style with the `[data-paused]` and `[data-ended]` attributes to show/hide play/pause/replay icons based on state. For example:
+
+React renders a `<button>` element. Add a `className` to style it:
+
+css
+
+```
+/* Paused (but not ended) */
+.play-button[data-paused]:not([data-ended]) .play-icon { display: inline; }
+
+/* Playing */
+.play-button:not([data-paused]) .pause-icon { display: inline; }
+
+/* Ended */
+.play-button[data-ended] .replay-icon { display: inline; }
+```
+
+After first play, the `data-started` attribute is added and remains present until a new source is loaded. Use this to hide the play button when media hasn’t started yet:
+
+css
+
+```
+/* Hide play button before first play */
+.play-button:not([data-started]) .play-icon { display: none; }
+```
+
+## Accessibility
+
+Renders a `<button>` element with an automatic `aria-label` that updates based on state: “Play”, “Pause”, or “Replay”. Override with the `label` prop (accepts a string or function). Keyboard activation: Enter / Space.
+
+## Examples
+
+### Basic Usage
+
+Play
+
+App.tsx
+
+App.css
+
+```
+import { createPlayer, PlayButton } 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
+        />
+        <PlayButton
+          className="media-play-button"
+          render={(props, state) => (
+            <button {...props}>{state.ended ? 'Replay' : state.paused ? 'Play' : 'Pause'}</button>
+          )}
+        />
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.media-play-button {
+  position: absolute;
+  bottom: 10px;
+  left: 10px;
+  padding-block: 8px;
+  padding-inline: 20px;
+  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);
+}
+```
+
+## API Reference
+
+### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`disabled`
+
+`boolean`
+
+`false`
+
+▸
+
+Description
+
+Whether the button is disabled.
+
+`label`
+
+`string | function`
+
+`''`
+
+▸
+
+Description
+
+Custom label for the button.
+
+Type
+
+`string | ((state: PlayButtonState) => string)`
+
+### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+Property
+
+Type
+
+Details
+
+`paused`
+
+`boolean`
+
+▸
+
+Description
+
+Whether playback is paused.
+
+`ended`
+
+`boolean`
+
+▸
+
+Description
+
+Whether playback has reached the end.
+
+`started`
+
+`boolean`
+
+▸
+
+Description
+
+Whether playback has started (played or seeked).
+
+`label`
+
+`string`
+
+### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-paused`
+
+▸
+
+Description
+
+Present when the media is paused.
+
+`data-ended`
+
+▸
+
+Description
+
+Present when the media has ended.
+
+`data-started`
+
+▸
+
+Description
+
+Present when playback has started.

package/docs/reference/playback-rate-button.md

@@ -0,0 +1,185 @@
+# PlaybackRateButton
+
+A button that cycles through playback speed rates
+
+## Anatomy
+
+tsx
+
+```
+<PlaybackRateButton />
+```
+
+## Behavior
+
+Cycles through playback rates on click. The default rate list is `[0.2, 0.5, 0.7, 1, 1.2, 1.5, 1.7, 2]`. After the last rate, it wraps back to the first. If the current rate isn’t in the list (e.g., set programmatically), the button jumps to the next rate greater than the current one.
+
+When `menuTrigger` is enabled, activation opens the linked playback-rate menu instead of cycling through rates. Use this mode when the button is the trigger for a `Menu` that contains playback-rate options.
+
+## Styling
+
+Display the current rate using the `data-rate` attribute:
+
+Use the `render` prop for rate display:
+
+tsx
+
+```
+<PlaybackRateButton
+  render={(props, state) => <button {...props}>{state.rate}&times;</button>}
+/>
+```
+
+## Accessibility
+
+Renders a `<button>` with an automatic `aria-label` of `"Playback rate {rate}"` (e.g., `"Playback rate 1.5"`). Override with the `label` prop. Keyboard activation: Enter / Space.
+
+In menu-trigger mode, the button behaves as a menu trigger and reflects menu state through the trigger attributes.
+
+## Examples
+
+### Basic Usage
+
+1×
+
+App.tsx
+
+App.css
+
+```
+import { createPlayer, PlaybackRateButton } 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
+        />
+        <PlaybackRateButton
+          className="media-playback-rate-button"
+          render={(props, state) => <button {...props}>{Math.round(state.rate * 10) / 10}&times;</button>}
+        />
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.media-playback-rate-button {
+  position: absolute;
+  bottom: 10px;
+  left: 10px;
+  padding-block: 8px;
+  padding-inline: 20px;
+  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);
+}
+```
+
+## API Reference
+
+### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`disabled`
+
+`boolean`
+
+`false`
+
+▸
+
+Description
+
+Whether the button is disabled.
+
+`label`
+
+`string | function`
+
+`''`
+
+▸
+
+Description
+
+Custom label for the button.
+
+Type
+
+`string | ((state: PlaybackRateButtonState) => string)`
+
+`menuTrigger`
+
+`boolean`
+
+`false`
+
+▸
+
+Description
+
+When true, pointer activation opens a menu instead of cycling. React sets this automatically inside `Menu.Trigger`.
+
+### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+Property
+
+Type
+
+Details
+
+`rate`
+
+`number`
+
+`label`
+
+`string`
+
+### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-rate`
+
+`number`
+
+▸
+
+Description
+
+Current playback rate.

package/docs/reference/player-container.md

@@ -0,0 +1,109 @@
+# Player.Container
+
+The player's interaction surface — handles layout, fullscreen, media attachment, and user activity detection.
+
+The `Player.Container` is the player’s physical surface. It defines the visual boundary, attaches the media element, and detects user interaction like activity and (eventually) gestures and keyboard input. It lives inside a [`Player.Provider`](./player-provider.md).
+
+tsx
+
+```
+<Player.Provider>
+  <Player.Container>
+    <video src="video.mp4" />
+    <Controls.Root>
+      {/* ... */}
+    </Controls.Root>
+  </Player.Container>
+</Player.Provider>
+```
+
+## How it’s created
+
+The `Player.Container` comes from the same `createPlayer()` call that creates the `Player.Provider`. They’re a matched pair wired to the same feature set.
+
+tsx
+
+```
+import { createPlayer } from '@videojs/react';
+import { videoFeatures } from '@videojs/react/video';
+
+const Player = createPlayer({ features: videoFeatures });
+```
+
+[`createPlayer` reference](./create-player.md)
+
+## What it does
+
+### Layout & fullscreen
+
+The container is the visual box around your media and controls. Sizing, aspect ratio, and visual boundaries all go here — on the container, not the provider.
+
+tsx
+
+```
+<Player.Container style={{ width: 640, aspectRatio: '16/9' }}>
+  <video src="video.mp4" />
+  <Controls.Root>
+    {/* ... */}
+  </Controls.Root>
+</Player.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.
+
+### Media attachment
+
+Media discovery is handled by the provider, not the container. When a media component like `<Video>` registers itself via context, the provider 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** — Click-to-play, double-click fullscreen, swipe to seek, and other touch/mouse gestures. Configured via the `Gesture` component.
+*   **Keyboard controls** — Spacebar to play/pause, arrow keys to seek, and other keyboard shortcuts scoped to the container. Configured via the `Hotkey` component.
+
+## Relationship to skins
+
+A [skin](../concepts/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.
+
+tsx
+
+```
+{/* Packaged skin — container is inside VideoSkin */}
+<Player.Provider>
+  <VideoSkin>
+    <Video src="video.mp4" />
+  </VideoSkin>
+</Player.Provider>
+
+{/* Custom UI — you use Player.Container directly */}
+<Player.Provider>
+  <Player.Container>
+    <video src="video.mp4" />
+    <PlayButton />
+  </Player.Container>
+</Player.Provider>
+```
+
+## Inside vs. outside the container
+
+The [provider](./player-provider.md) gives components access to state and actions. The container layers on physical behaviors — fullscreen, activity detection, gesture handling. Components work in both places; the container just adds those extras.
+
+tsx
+
+```
+<Player.Provider>
+  <Player.Container>
+    <video src="video.mp4" />
+    <Controls.Root>          {/* fullscreen, activity detection, gestures */}
+      {/* ... */}
+    </Controls.Root>
+  </Player.Container>
+
+  <Transcript />          {/* state & actions, but no container behaviors */}
+  <PlaylistSidebar />     {/* state & actions, but no container behaviors */}
+</Player.Provider>
+```
+
+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/player-provider.md

@@ -0,0 +1,104 @@
+# Player.Provider
+
+The state boundary — creates a store and broadcasts it to all descendants.
+
+The `Player.Provider` 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
+
+```
+import { videoFeatures } from '@videojs/react/video';
+import { createPlayer } from '@videojs/react';
+
+const Player = createPlayer({ features: videoFeatures });
+
+function App() {
+  return (
+    <Player.Provider>
+      {/* Everything inside can access the player store */}
+      <Player.Container>
+        <video src="video.mp4" />
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+
+## How it’s created
+
+Call `createPlayer()` with a `features` array. The returned object contains `Provider`, `Container`, `usePlayer`, and `useMedia` — everything you need for one player instance.
+
+tsx
+
+```
+import { createPlayer } from '@videojs/react';
+import { videoFeatures } from '@videojs/react/video';
+
+const Player = createPlayer({
+  features: videoFeatures,
+});
+```
+
+The [features](../concepts/features.md) you pass determine what state is available in the store. `videoFeatures` is a [preset](../concepts/presets.md) that includes playback, volume, fullscreen, and other standard video controls.
+
+[createPlayer reference](./create-player.md)
+
+## What lives inside it
+
+Everything that needs player state goes inside the provider: skins, containers, UI components, and your own custom components. Anything inside can access the store.
+
+tsx
+
+```
+<Player.Provider>
+  <VideoSkin>           {/* skin — includes container + controls */}
+    <Video src="..." /> {/* media element */}
+  </VideoSkin>
+  <MyCustomOverlay />   {/* your own component — can use Player.usePlayer() */}
+</Player.Provider>
+```
+
+## No visual presence
+
+The `Provider` renders no visible element of its own — it’s purely a state wrapper. Sizing, borders, and background go on the [`Container`](./player-container.md), not the Provider.
+
+## Accessing state
+
+Use `Player.usePlayer` to read state or call actions from any component inside the Provider:
+
+PlayPauseButton.tsx
+
+```
+function PlayPauseButton() {
+  const paused = Player.usePlayer(selectPlayback).paused;
+  const store = Player.usePlayer();
+
+  return (
+    <button onClick={() => store.dispatch('toggle-playback')}>
+      {paused ? 'Play' : 'Pause'}
+    </button>
+  );
+}
+```
+
+[usePlayer reference](./use-player.md)
+
+## Extended player layouts
+
+The provider’s scope can extend beyond the fullscreen target. Playlists, transcripts, sidebars, and other supplementary UI can live inside the provider but outside the container. They still have full access to the store, they just won’t go fullscreen with the video.
+
+tsx
+
+```
+<Player.Provider>
+  <Player.Container>
+    <video src="video.mp4" />
+    <Controls.Root>          {/* goes fullscreen with the video */}
+      {/* ... */}
+    </Controls.Root>
+  </Player.Container>
+
+  <Transcript />          {/* outside container — still has store access */}
+  <PlaylistSidebar />     {/* outside container — still has store access */}
+</Player.Provider>
+```