@videojs/html 10.0.0-beta.22 → 10.0.0-beta.24

package/docs/reference/play-button.md

@@ -0,0 +1,251 @@
+# media-play-button
+
+Accessible play/pause button with keyboard support and customizable rendering
+
+## Anatomy
+
+html
+
+```
+<media-play-button></media-play-button>
+```
+
+## 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:
+
+css
+
+```
+/* Paused (but not ended) */
+media-play-button[data-paused]:not([data-ended]) .play-icon { display: inline; }
+
+/* Playing */
+media-play-button:not([data-paused]) .pause-icon { display: inline; }
+
+/* Ended */
+media-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 */
+media-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 Pause Replay
+
+index.html
+
+index.css
+
+index.ts
+
+```
+<video-player class="video-player">
+    <media-container>
+        <video
+            src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
+            autoplay
+            muted
+            playsinline
+        ></video>
+        <media-play-button class="media-play-button">
+            <span class="paused">Play</span>
+            <span class="playing">Pause</span>
+            <span class="ended">Replay</span>
+        </media-play-button>
+    </media-container>
+</video-player>
+```
+```
+.video-player {
+  position: relative;
+}
+
+.video-player 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);
+}
+
+.media-play-button .paused {
+  display: none;
+}
+.media-play-button .playing {
+  display: none;
+}
+.media-play-button .ended {
+  display: none;
+}
+.media-play-button[data-paused]:not([data-ended]) .paused {
+  display: inline;
+}
+.media-play-button:not([data-paused]) .playing {
+  display: inline;
+}
+.media-play-button[data-ended] .ended {
+  display: inline;
+}
+.media-play-button[data-ended] .paused {
+  display: none;
+}
+.media-play-button[data-ended] .playing {
+  display: none;
+}
+```
+```
+import '@videojs/html/video/player';
+import '@videojs/html/ui/play-button';
+```
+
+## API Reference
+
+### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`disabled`
+
+`boolean`
+
+`false`
+
+▸
+
+Attribute
+
+`disabled`
+
+Description
+
+Whether the button is disabled.
+
+`label`
+
+`string | function`
+
+`''`
+
+▸
+
+Attribute
+
+`label`
+
+Description
+
+Custom label for the button.
+
+Type
+
+`string | ((state: PlayButtonState) => string)`
+
+### State
+
+State is reflected as data attributes for CSS styling.
+
+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,170 @@
+# media-playback-rate-button
+
+A button that cycles through playback speed rates
+
+## Anatomy
+
+html
+
+```
+<media-playback-rate-button></media-playback-rate-button>
+```
+
+## 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.
+
+## Styling
+
+Display the current rate using the `data-rate` attribute:
+
+css
+
+```
+media-playback-rate-button::after {
+  content: attr(data-rate) "\00D7";
+}
+```
+
+## 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.
+
+## Examples
+
+### Basic Usage
+
+index.html
+
+index.css
+
+index.ts
+
+```
+<video-player class="video-player">
+    <video
+        src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
+        autoplay
+        muted
+        playsinline
+        loop
+    ></video>
+    <media-playback-rate-button class="media-playback-rate-button">
+    </media-playback-rate-button>
+</video-player>
+```
+```
+.video-player {
+  position: relative;
+}
+
+.video-player 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);
+}
+
+.media-playback-rate-button::after {
+  content: attr(data-rate) "\00D7";
+}
+```
+```
+import '@videojs/html/video/player';
+import '@videojs/html/ui/playback-rate-button';
+```
+
+## API Reference
+
+### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`disabled`
+
+`boolean`
+
+`false`
+
+▸
+
+Attribute
+
+`disabled`
+
+Description
+
+Whether the button is disabled.
+
+`label`
+
+`string | function`
+
+`''`
+
+▸
+
+Attribute
+
+`label`
+
+Description
+
+Custom label for the button.
+
+Type
+
+`string | ((state: PlaybackRateButtonState) => string)`
+
+### State
+
+State is reflected as data attributes for CSS styling.
+
+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,126 @@
+# media-container
+
+The player's interaction surface — handles layout, fullscreen, media attachment, and user activity detection.
+
+The `<media-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 [`<video-player>`](./player-provider.md).
+
+html
+
+```
+<video-player>
+  <media-container>
+    <video src="video.mp4"></video>
+    <media-controls>...</media-controls>
+  </media-container>
+</video-player>
+```
+
+## How it’s created
+
+For most users, importing from `@videojs/html/video/player` registers both `<video-player>` and `<media-container>` with the standard video features:
+
+ts
+
+```
+import '@videojs/html/video/player';
+```
+
+html
+
+```
+<video-player>
+  <media-container>
+    <video src="video.mp4"></video>
+  </media-container>
+</video-player>
+```
+
+For custom behavior, use `ContainerMixin` from `createPlayer()`:
+
+my-player.ts
+
+```
+import { createPlayer, MediaElement } from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+
+const { ContainerMixin } = createPlayer({ features: videoFeatures });
+
+class MyContainer extends ContainerMixin(MediaElement) {}
+customElements.define('my-container', MyContainer);
+```
+
+[createPlayer reference](./html-create-player.md)
+
+[ContainerMixin reference](./container-mixin.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.
+
+html
+
+```
+<media-container style="width: 640px; aspect-ratio: 16/9;">
+  <video src="video.mp4"></video>
+  <media-controls>...</media-controls>
+</media-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. Custom media elements like `<hls-video>` register themselves via context when they connect. Plain `<video>` and `<audio>` elements are picked up automatically via a `querySelector` fallback. No `slot="media"` attribute is needed.
+
+### 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.
+
+html
+
+```
+<!-- Packaged skin — container is inside video-skin -->
+<video-player>
+  <video-skin>
+    <video src="video.mp4"></video>
+  </video-skin>
+</video-player>
+
+<!-- Custom UI — you use media-container directly -->
+<video-player>
+  <media-container>
+    <video src="video.mp4"></video>
+    <media-play-button></media-play-button>
+  </media-container>
+</video-player>
+```
+
+## 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.
+
+html
+
+```
+<video-player>
+  <media-container>
+    <video src="video.mp4"></video>
+    <media-controls>...</media-controls>  <!-- fullscreen, activity detection, gestures -->
+  </media-container>
+
+  <media-transcript></media-transcript>     <!-- state & actions, but no container behaviors -->
+  <playlist-sidebar></playlist-sidebar>     <!-- state & actions, but no container behaviors -->
+</video-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/player-context.md

@@ -0,0 +1,50 @@
+# playerContext
+
+The default player context instance for consuming the player store in controllers
+
+`playerContext` is a Web Components context token that carries the player store through the DOM tree. Provider elements publish the store to this context, and consumer elements (via [`PlayerController`](./player-controller.md) or [`ContainerMixin`](./container-mixin.md)) read from it.
+
+Pass it as the second argument to `PlayerController`:
+
+play-button.ts
+
+```
+import { PlayerController, MediaElement, playerContext, selectPlayback } from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+
+class PlayButton extends MediaElement {
+  #playback = new PlayerController(this, playerContext, selectPlayback);
+
+  render() {
+    const playback = this.#playback.value;
+    // Use playback state to render
+  }
+}
+```
+
+### Import directly or destructure from createPlayer
+
+[`createPlayer`](./html-create-player.md) returns a `context` property that is the same `playerContext` instance. Both approaches reference the same object:
+
+ts
+
+```
+// Direct import
+import { playerContext } from '@videojs/html';
+
+// Destructured — identical object
+const { context } = createPlayer({ features: videoFeatures });
+context === playerContext; // true
+```
+
+Use the direct import when building reusable elements that don’t depend on a specific `createPlayer` call. Destructure from `createPlayer` when you want all player utilities from a single result.
+
+### When you need this
+
+Most elements should use [`PlayerController`](./player-controller.md) (which accepts a context argument) rather than importing `playerContext` directly. Import it directly when you need to pass the context token to a lower-level API like [`ContainerMixin`](./container-mixin.md) or [`ProviderMixin`](./provider-mixin.md).
+
+## API Reference
+
+### Return Value
+
+`Context<PLAYER_CONTEXT_KEY, AnyPlayerStore>`