@videojs/html 10.0.0-beta.9 → 10.0.0-rc.1

package/docs/reference/i-18-n-controller.md

@@ -0,0 +1,95 @@
+# I18nController
+
+Reactive controller for consuming translator and locale values from an HTML i18n context
+
+## Import
+
+ts
+
+```
+import { I18nController } from "@videojs/html";
+```
+
+## Usage
+
+Create the controller with a reactive host and an i18n context. Read the translator from `value` and the active locale from `locale`.
+
+ts
+
+```
+import { I18nController, UIElement, i18nContext } from "@videojs/html";
+
+class LocalizedPlayLabel extends UIElement {
+  readonly #i18n = new I18nController(this, i18nContext);
+
+  get label() {
+    return this.#i18n.value("buttons.play", { default: "Play" });
+  }
+}
+```
+
+The controller requests a host update when its context changes. Without a provider, it falls back to the default English locale and updates when registered translations change.
+
+## API Reference
+
+### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`host*`
+
+`object`
+
+`—`
+
+▸
+
+Description
+
+Reactive host updated when the i18n value changes.
+
+Type
+
+`{ addController(controller: ReactiveController): void; removeController(controller: ReactiveController): void; requestUpdate(): void; updateComplete: Promise<boolean> } & HTMLElement`
+
+`context*`
+
+`Context<symbol, I18nContextValue>`
+
+`—`
+
+▸
+
+Description
+
+I18n context to consume.
+
+### Return Value
+
+Property
+
+Type
+
+Details
+
+`value`
+
+`Translator`
+
+`locale`
+
+`(typeof LOCALES)[number] | string & object`
+
+`hostConnected`
+
+`(() => void)`
+
+`hostDisconnected`
+
+`(() => void)`

package/docs/reference/live-audio-minimal-skin.md

@@ -0,0 +1,45 @@
+# live-audio-minimal-skin
+
+The live audio preset's visually lighter skin, closer to a classic control bar
+
+The minimal skin of the live audio preset: the same player and the same controls in a visually lighter design, closer to a classic control bar. Like the default skin, it shows a Live button in place of time controls. [LiveAudioSkin](./live-audio-skin.md) is the same preset’s other variant. See [Skins](../concepts/skins.md) for how packaged skins work and [Presets](../concepts/presets.md) for what the live audio preset ships.
+
+## Import
+
+ts
+
+```
+import '@videojs/html/live-audio/minimal-skin';
+```
+
+The import registers the skin and every UI element it composes. The [CDN](../concepts/cdn.md) player bundle registers this skin together with its player:
+
+html
+
+```
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.1/live-audio-minimal.js"></script>
+```
+
+## Usage
+
+The skin goes between the player and the media element. It renders its controls around the media.
+
+html
+
+```
+<live-audio-player>
+  <live-audio-minimal-skin>
+    <mux-audio src="live.m3u8"></mux-audio>
+  </live-audio-minimal-skin>
+</live-audio-player>
+```
+
+The examples use the [Mux audio element](./mux-audio.md): a plain `<audio>` can’t play HLS in most browsers, and this element reports the live playback state the skin’s Live button needs. See [Play live streams](../how-to/play-live-streams.md).
+
+## Styling
+
+Packaged skins style themselves and expose a small set of public CSS custom properties. Everything else inside the skin is private and may change between releases. [Customize skins](../how-to/customize-skins.md#style-a-packaged-skin) documents the properties. When you need deeper changes, eject the skin.
+
+## Eject the skin
+
+The `@videojs/live-audio-minimal` skin installs under `components/videojs/skins/live-audio/minimal`. The player and media remain package imports. Follow [Customize skins](../how-to/customize-skins.md#set-up-the-shadcn-cli) to set up the CLI, install the skin, and use the copied files.

package/docs/reference/live-audio-skin.md

@@ -0,0 +1,45 @@
+# live-audio-skin
+
+The live audio preset's default skin, which swaps time controls for a Live button
+
+The default skin of the live audio preset: the audio layout with the time slider and time displays swapped for a Live button. [MinimalLiveAudioSkin](./live-audio-minimal-skin.md) is the same preset’s other variant. See [Skins](../concepts/skins.md) for how packaged skins work and [Presets](../concepts/presets.md) for what the live audio preset ships.
+
+## Import
+
+ts
+
+```
+import '@videojs/html/live-audio/skin';
+```
+
+The import registers the skin and every UI element it composes. The [CDN](../concepts/cdn.md) player bundle registers this skin together with its player:
+
+html
+
+```
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.1/live-audio.js"></script>
+```
+
+## Usage
+
+The skin goes between the player and the media element. It renders its controls around the media.
+
+html
+
+```
+<live-audio-player>
+  <live-audio-skin>
+    <mux-audio src="live.m3u8"></mux-audio>
+  </live-audio-skin>
+</live-audio-player>
+```
+
+The examples use the [Mux audio element](./mux-audio.md): a plain `<audio>` can’t play HLS in most browsers, and this element reports the live playback state the skin’s Live button needs. See [Play live streams](../how-to/play-live-streams.md).
+
+## Styling
+
+Packaged skins style themselves and expose a small set of public CSS custom properties. Everything else inside the skin is private and may change between releases. [Customize skins](../how-to/customize-skins.md#style-a-packaged-skin) documents the properties. When you need deeper changes, eject the skin.
+
+## Eject the skin
+
+The `@videojs/live-audio` skin installs under `components/videojs/skins/live-audio`. The player and media remain package imports. Follow [Customize skins](../how-to/customize-skins.md#set-up-the-shadcn-cli) to set up the CLI, install the skin, and use the copied files.

package/docs/reference/live-button.md

@@ -0,0 +1,257 @@
+# media-live-button
+
+Accessible live indicator button that seeks to the live edge when pressed
+
+## Import
+
+ts
+
+```
+import '@videojs/html/ui/live-button';
+```
+
+## Anatomy
+
+html
+
+```
+<media-live-button></media-live-button>
+```
+
+## Behavior
+
+LiveButton indicates whether playback is at the live edge and acts as a “go to live” control. While playback is behind the edge, clicking seeks to the live edge — the end of the last `seekable` range. At the edge the button goes inactive (`aria-disabled`) and clicking is a no-op.
+
+The button combines three player features: [live](./feature-live.md) for `liveEdgeStart` and `targetLiveWindow`, [time](./feature-time.md) for `currentTime` and the `seek()` action, and [buffer](./feature-buffer.md) for `seekable`. All three are included in the `liveVideoFeatures` and `liveAudioFeatures` presets, and the packaged live skins include the button.
+
+Media counts as live while `targetLiveWindow` is not `NaN`. That value is how far behind the live edge viewers can seek: `0` means the stream is watchable only at the edge, and `Infinity` means the stream keeps its recording seekable so viewers can rewind and catch up, like a DVR. For on-demand media the button reports neither `live` nor `liveEdge` and stays inert.
+
+The live edge is not a single instant: it begins 5 seconds before `liveEdgeStart`, the position the media reports live playback starting at, so playback that drifts slightly behind still counts as live. When the media does not report `liveEdgeStart`, the edge is the trailing 10 seconds of the seekable window instead.
+
+Without children, the button renders the translated “Live” badge text.
+
+See [Play live streams](../how-to/play-live-streams.md) for how live state flows through the player.
+
+## Styling
+
+Attribute
+
+Values
+
+Description
+
+`data-live`
+
+Present / absent
+
+Present when the stream is live (or DVR)
+
+`data-live-edge`
+
+Present / absent
+
+Present when playback is at the live edge
+
+Use `data-live-edge` to color the button red at the edge and gray behind it:
+
+css
+
+```
+media-live-button { color: gray; }
+media-live-button[data-live-edge] { color: red; }
+```
+
+## Accessibility
+
+Renders a `<button>` with an automatic `aria-label` that updates based on state: “Playing live” at the live edge, “Seek to live edge” while behind it. Override with the `label` prop, which accepts a text descriptor, literal string, or function returning either. A text descriptor contains an opaque translation key and English fallback, for example `{ key: 'live.playing', text: 'Playing live' }`. When the button is disabled or playback is at the live edge, `aria-disabled="true"` is set. Keyboard activation: Enter / Space.
+
+## Examples
+
+### Basic Usage
+
+The demo plays a continuously running live stream. Seek backward to move behind the live edge, then press the Live button to jump back to it.
+
+⏪ 30s Live
+
+index.html
+
+index.css
+
+index.ts
+
+```
+<live-video-player class="html-live-button-basic">
+  <media-container>
+    <hlsjs-video src="https://stream.mux.com/v69RSHhFelSm4701snP22dYz2jICy4E4FUyk02rW4gxRM.m3u8" autoplay muted playsinline></hlsjs-video>
+    <div class="html-live-button-basic__buttons">
+      <media-seek-button seconds="-30" class="html-live-button-basic__seek">&#9194; 30s</media-seek-button>
+      <media-live-button class="html-live-button-basic__live">
+        <span class="html-live-button-basic__dot"></span>
+        Live
+      </media-live-button>
+    </div>
+  </media-container>
+</live-video-player>
+```
+```
+.html-live-button-basic media-container {
+  position: relative;
+}
+
+.html-live-button-basic media-container hlsjs-video {
+  display: block;
+  width: 100%;
+}
+
+.html-live-button-basic__buttons {
+  position: absolute;
+  bottom: 10px;
+  left: 10px;
+  display: flex;
+  gap: 8px;
+}
+
+.html-live-button-basic__seek,
+.html-live-button-basic__live {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding-block: 8px;
+  padding-inline: 20px;
+  color: black;
+  white-space: nowrap;
+  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);
+}
+
+.html-live-button-basic__live[data-live-edge] {
+  cursor: default;
+}
+
+.html-live-button-basic__dot {
+  width: 8px;
+  height: 8px;
+  background: gray;
+  border-radius: 50%;
+}
+
+.html-live-button-basic__live[data-live-edge] .html-live-button-basic__dot {
+  background: red;
+}
+```
+```
+import '@videojs/html/live-video/player';
+import '@videojs/html/ui/container';
+import '@videojs/html/media/hlsjs-video';
+import '@videojs/html/ui/live-button';
+import '@videojs/html/ui/seek-button';
+```
+
+## API Reference
+
+### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`disabled`
+
+`boolean`
+
+`false`
+
+▸
+
+Attribute
+
+`disabled`
+
+Description
+
+Whether the button is disabled.
+
+`label`
+
+`object`
+
+`''`
+
+▸
+
+Attribute
+
+`label`
+
+Description
+
+Custom label for the button.
+
+Type
+
+`{ key: string; text: string } | string | ((state: LiveButtonState) => Text | string)`
+
+### State
+
+State is reflected as data attributes for CSS styling.
+
+Property
+
+Type
+
+Details
+
+`label`
+
+`{ key: string; text: string } | string`
+
+`live`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the stream is live (or DVR).
+
+`liveEdge`
+
+`boolean`
+
+▸
+
+Description
+
+Whether playback is at the live edge.
+
+### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-live`
+
+▸
+
+Description
+
+Present when the stream is live (or DVR).
+
+`data-live-edge`
+
+▸
+
+Description
+
+Present when playback is at the live edge.

package/docs/reference/live-video-minimal-skin.md

@@ -0,0 +1,51 @@
+# live-video-minimal-skin
+
+The live video preset's visually lighter skin, closer to a classic control bar
+
+The minimal skin of the live video preset: the same player and the same controls in a visually lighter design, closer to a classic control bar. Like the default skin, it shows a Live button in place of time controls. [LiveVideoSkin](./live-video-skin.md) is the same preset’s other variant. See [Skins](../concepts/skins.md) for how packaged skins work and [Presets](../concepts/presets.md) for what the live video preset ships.
+
+## Import
+
+ts
+
+```
+import '@videojs/html/live-video/minimal-skin';
+```
+
+The import registers the skin and every UI element it composes. The [CDN](../concepts/cdn.md) player bundle registers this skin together with its player:
+
+html
+
+```
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.1/live-video-minimal.js"></script>
+```
+
+## Usage
+
+The skin goes between the player and the media element. It renders its controls around the media.
+
+html
+
+```
+<live-video-player>
+  <live-video-minimal-skin>
+    <hls-video src="live.m3u8"></hls-video>
+  </live-video-minimal-skin>
+</live-video-player>
+```
+
+The examples use the default [HLS video element](./hls-video.md) because most browsers can’t play HLS streams with a plain `<video>`. See [Play live streams](../how-to/play-live-streams.md).
+
+## Poster
+
+The skin renders a poster image before playback starts. An element with `slot="poster"` replaces it.
+
+See [Add a poster and loading placeholder](../how-to/add-a-poster-and-loading-placeholder.md) for complete examples.
+
+## Styling
+
+Packaged skins style themselves and expose a small set of public CSS custom properties. Everything else inside the skin is private and may change between releases. [Customize skins](../how-to/customize-skins.md#style-a-packaged-skin) documents the properties. When you need deeper changes, eject the skin.
+
+## Eject the skin
+
+The `@videojs/live-video-minimal` skin installs under `components/videojs/skins/live-video/minimal`. The player and media remain package imports. Follow [Customize skins](../how-to/customize-skins.md#set-up-the-shadcn-cli) to set up the CLI, install the skin, and use the copied files.

package/docs/reference/live-video-skin.md

@@ -0,0 +1,51 @@
+# live-video-skin
+
+The live video preset's default skin, which swaps time controls for a Live button
+
+The default skin of the live video preset: the video layout with the time slider and time displays swapped for a Live button. [MinimalLiveVideoSkin](./live-video-minimal-skin.md) is the same preset’s other variant. See [Skins](../concepts/skins.md) for how packaged skins work and [Presets](../concepts/presets.md) for what the live video preset ships.
+
+## Import
+
+ts
+
+```
+import '@videojs/html/live-video/skin';
+```
+
+The import registers the skin and every UI element it composes. The [CDN](../concepts/cdn.md) player bundle registers this skin together with its player:
+
+html
+
+```
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.1/live-video.js"></script>
+```
+
+## Usage
+
+The skin goes between the player and the media element. It renders its controls around the media.
+
+html
+
+```
+<live-video-player>
+  <live-video-skin>
+    <hls-video src="live.m3u8"></hls-video>
+  </live-video-skin>
+</live-video-player>
+```
+
+The examples use the default [HLS video element](./hls-video.md) because most browsers can’t play HLS streams with a plain `<video>`. See [Play live streams](../how-to/play-live-streams.md).
+
+## Poster
+
+The skin renders a poster image before playback starts. An element with `slot="poster"` replaces it.
+
+See [Add a poster and loading placeholder](../how-to/add-a-poster-and-loading-placeholder.md) for complete examples.
+
+## Styling
+
+Packaged skins style themselves and expose a small set of public CSS custom properties. Everything else inside the skin is private and may change between releases. [Customize skins](../how-to/customize-skins.md#style-a-packaged-skin) documents the properties. When you need deeper changes, eject the skin.
+
+## Eject the skin
+
+The `@videojs/live-video` skin installs under `components/videojs/skins/live-video`. The player and media remain package imports. Follow [Customize skins](../how-to/customize-skins.md#set-up-the-shadcn-cli) to set up the CLI, install the skin, and use the copied files.

package/docs/reference/media-attach-mixin.md

@@ -0,0 +1,101 @@
+# MediaAttachMixin
+
+Mixin for custom media elements to register themselves with the provider via context
+
+## Import
+
+ts
+
+```
+import { MediaAttachMixin } from "@videojs/html";
+```
+
+`MediaAttachMixin` creates a class that registers itself with the [player](./player.md) on connect. Apply it to custom media elements so they automatically wire to the store.
+
+Built-in elements, like `<hlsjs-video>`, `<dash-video>`, `<hls-video>`, and `<background-video>`, all use this mixin internally.
+
+ts
+
+```
+import { MediaAttachMixin } from '@videojs/html';
+import { MyCustomMedia } from './my-custom-media';
+
+export class MyMedia extends MediaAttachMixin(MyCustomMedia) {
+  // inherits context registration
+}
+
+customElements.define('my-media', MyMedia);
+```
+
+## Who needs this
+
+You only need `MediaAttachMixin` when your base class doesn’t already register as a media element with the provider. For example, elements that wrap a third-party player or use a canvas renderer.
+
+For plain `<video>` and `<audio>` elements, the player tracks them automatically as they are added, removed, or replaced — no mixin needed.
+
+## Overriding the media target
+
+By default, `MediaAttachMixin` registers `this` as the media element. Override `getMediaTarget()` if the actual media element is something other than the element itself — for example, an inner `<video>` in a shadow root:
+
+ts
+
+```
+import { MediaAttachMixin } from '@videojs/html';
+
+export class BackgroundVideo extends MediaAttachMixin(HTMLElement) {
+  getMediaTarget() {
+    return this.shadowRoot?.querySelector('video') ?? null;
+  }
+}
+```
+
+## Factory function
+
+`MediaAttachMixin` is pre-configured with the default `mediaContext` published by [`PlayerElement`](./player.md). Call `createMediaAttachMixin` only when a custom player publishes a matching custom `MediaContext`:
+
+ts
+
+```
+import { createMediaAttachMixin } from '@videojs/html';
+import { myCustomContext } from './my-player/context';
+
+export const MyMediaAttachMixin = createMediaAttachMixin(myCustomContext);
+```
+
+## API Reference
+
+### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`context*`
+
+`Context<typeof MEDIA_CONTEXT_KEY, MediaContextValue>`
+
+`—`
+
+▸
+
+Description
+
+The media context to consume.
+
+### Return Value
+
+Type
+
+Details
+
+`function`
+
+▸
+
+Type
+
+`((BaseClass: Class) => Class)`

package/docs/reference/media-i18n.md

@@ -0,0 +1,45 @@
+# media-i18n
+
+HTML custom element that resolves locale and supplies translations to descendants
+
+## Import
+
+ts
+
+```
+import "@videojs/html/i18n";
+```
+
+One import registers both `<media-i18n>` and `<media-text>`.
+
+`<media-i18n>` applies the i18n provider mixin to a subtree. Wrap a player, standalone controls, or one of several players that need different locales with this element. Without it, HTML controls use English defaults.
+
+Set `lang` on the provider or an ancestor. Built-in packs lazy-load automatically; register locale strings with [`registerI18n`](./register-i18n.md) when you need custom copy or synchronous first paint. See [Translation keys](./translation-phrases.md) for supported keys.
+
+html
+
+```
+<script type="module">
+  import '@videojs/html/i18n';
+  import '@videojs/html/i18n/locales/es/register';
+</script>
+
+<media-i18n lang="es">
+  <media-text token="buttons.play">Play</media-text>
+</media-i18n>
+```
+
+## Attributes
+
+Attribute
+
+Description
+
+`lang`
+
+Forces the active BCP 47 locale for this subtree. Omit to inherit the nearest ancestor `[lang]`.
+
+## Related
+
+*   [`<media-text>`](./media-text.md): Renders translated text content
+*   [Internationalize the player](../how-to/internationalize-the-player.md)