@videojs/html 10.0.0-rc.3 → 10.0.0-rc.5

package/docs/reference/api/html-create-player.md

@@ -54,9 +54,11 @@ class PlayerRegion extends ContainerElement {}
 <demo-video-player class="demo-video-player">
   <media-container>
     <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline></video>
-    <demo-play-toggle class="media-play-button">
-      <span class="paused">Play</span>
-      <span class="playing">Pause</span>
+    <demo-play-toggle>
+      <button type="button" class="media-play-button">
+        <span class="paused">Play</span>
+        <span class="playing">Pause</span>
+      </button>
     </demo-play-toggle>
   </media-container>
 </demo-video-player>
@@ -73,12 +75,16 @@ class PlayerRegion extends ContainerElement {}
   width: 100%;
 }
 
-.media-play-button {
+.demo-video-player demo-play-toggle {
   position: absolute;
   bottom: 10px;
   left: 10px;
+}
+
+.media-play-button {
   padding-block: 8px;
   padding-inline: 20px;
+  font: inherit;
   color: black;
   cursor: pointer;
   background: rgba(255, 255, 255, 0.7);
@@ -95,11 +101,11 @@ class PlayerRegion extends ContainerElement {}
   display: none;
 }
 
-.media-play-button[data-paused] .paused {
+.demo-video-player demo-play-toggle[data-paused] .paused {
   display: inline;
 }
 
-.media-play-button:not([data-paused]) .playing {
+.demo-video-player demo-play-toggle:not([data-paused]) .playing {
   display: inline;
 }
 ```
@@ -107,14 +113,7 @@ class PlayerRegion extends ContainerElement {}
 **index.ts**
 
 ```ts
-import {
-  applyElementProps,
-  applyStateDataAttrs,
-  createButton,
-  createPlayer,
-  selectPlayback,
-  UIElement,
-} from '@videojs/html';
+import { createPlayer, selectPlayback, UIElement } from '@videojs/html';
 import { videoFeatures } from '@videojs/html/video';
 import '@videojs/html/ui/container';
 
@@ -133,17 +132,7 @@ class PlayToggle extends UIElement {
     super.connectedCallback();
     this.#disconnect = new AbortController();
 
-    const buttonProps = createButton({
-      onActivate: () => {
-        const state = this.#player.value;
-        if (!state) return;
-
-        state.paused ? state.play() : state.pause();
-      },
-      isDisabled: () => !this.#player.value,
-    });
-
-    applyElementProps(this, buttonProps, { signal: this.#disconnect.signal });
+    this.querySelector('button')?.addEventListener('click', this.#toggle, { signal: this.#disconnect.signal });
   }
 
   override disconnectedCallback(): void {
@@ -157,8 +146,17 @@ class PlayToggle extends UIElement {
     const state = this.#player.value;
     if (!state) return;
 
-    applyStateDataAttrs(this, state, { paused: 'data-paused', ended: 'data-ended' });
+    this.toggleAttribute('data-paused', state.paused);
+    this.toggleAttribute('data-ended', state.ended);
   }
+
+  #toggle = (): void => {
+    const state = this.#player.value;
+    if (!state) return;
+
+    if (state.paused) state.play();
+    else state.pause();
+  };
 }
 
 customElements.define('demo-video-player', VideoPlayerElement);

package/docs/reference/api/i18n-controller.md

@@ -10,7 +10,7 @@ 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`.
+Create the controller with a reactive host and an i18n context. `i18nContext` is the default context that `<media-i18n>` provides; its `I18nContextValue` holds the active `translator` and `locale`. Read the `Translator` from `value` and the active locale from `locale`.
 
 ```ts
 import { I18nController, UIElement, i18nContext } from "@videojs/html";

package/docs/reference/api/is-text.md

@@ -0,0 +1,33 @@
+# isText
+
+Check whether a value is a text descriptor
+
+## Import
+
+```ts
+import { isText } from "@videojs/html/i18n";
+```
+
+`isText` returns whether a value is a text descriptor: an object with a translation `key` and its English default `text`. Use it to accept either a descriptor or a plain string, as [`translateText`](./translate-text.md) does. See [Translation phrases](./translation-phrases.md) for the built-in descriptors.
+
+```ts
+import { isText } from '@videojs/html/i18n';
+import { playText } from '@videojs/html/i18n/text/buttons';
+
+isText(playText); // true
+isText('Play'); // false
+```
+
+## API Reference
+
+`isText(value): value is Text`
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` (required) | `unknown` | — | Value to check. |
+
+### Return Value
+
+`value is Text`

package/docs/reference/api/llms.txt

@@ -1,6 +1,6 @@
 # Video.js v10 — HTML API
 
-> API reference for the player factory, store controllers, features, translation tools, and utilities. Bundled with `@videojs/html` v10.0.0-rc.3. Links are relative paths to files in this directory.
+> API reference for the player factory, presets, store controllers, features, translation tools, and utilities. Bundled with `@videojs/html` v10.0.0-rc.5. Links are relative paths to files in this directory.
 
 ## Player
 
@@ -8,11 +8,24 @@ API reference for creating a player and reaching it and its container from your
 
 - [createPlayer](./html-create-player.md): Factory function that creates a typed player element and controller for HTML custom elements
 - [PlayerController](./player-controller.md): Reactive controller for accessing player store state in HTML custom elements
+- [UIElement](./ui-element.md): Base class for custom elements that read player state through reactive controllers
+- [Media capability guards](./media-capabilities.md): Type guards that narrow a Media object to the capabilities it supports
+
+## Presets
+
+API reference for the presets: each bundles a player, feature bundle, skins, and media for one use case.
+
+- [Video preset](./preset-video.md): The general-purpose video preset — a player, feature bundle, skins, and media for on-demand video
+- [Audio preset](./preset-audio.md): The audio-only preset — a player, feature bundle, skins, and media for on-demand audio
+- [Live video preset](./preset-live-video.md): The live video preset — a player, feature bundle, skins, and media for live video streams
+- [Live audio preset](./preset-live-audio.md): The live audio preset — a player, feature bundle, skins, and media for live audio streams
+- [Background preset](./preset-background.md): The background video preset — a player, feature bundle, skin, and media for ambient video with no controls
 
 ## Store
 
 API reference for reading and subscribing to player state: selectors and the store controllers.
 
+- [Player store](./player-store.md): Every state field and action on the player store, grouped by the feature that adds it
 - [createSelector](./create-selector.md): Create a type-safe selector for a store slice's state
 - [StoreController](./store-controller.md): Reactive controller for subscribing to store state in HTML custom elements
 - [SnapshotController](./snapshot-controller.md): Reactive controller for subscribing to a State container in HTML custom elements
@@ -54,12 +67,20 @@ API reference for translating the player: the i18n elements, controller, and the
 - [hasRegisteredLocale](./has-registered-locale.md): Check whether an exact locale tag exists in the global i18n registry
 - [onI18nRegistryChange](./on-i18n-registry-change.md): Subscribe to global i18n registry mutations
 - [createTranslator](./create-translator.md): Build a typed translator from a resolved translation map
+- [translateText](./translate-text.md): Translate a text descriptor, or fall back to its English default
+- [resolveTranslation](./resolve-translation.md): Translate a key with the params its English default requires
+- [isText](./is-text.md): Check whether a value is a text descriptor
+- [loadLocale](./load-locale.md): Lazy-load the built-in translation pack for a locale
+- [getLocaleKey](./get-locale-key.md): Normalize a locale tag to the key the i18n registry stores it under
+- [findLocaleKeys](./find-locale-keys.md): List the locale tags a lookup falls back through, most specific first
 - [I18nController](./i18n-controller.md): Reactive controller for consuming translator and locale values from an HTML i18n context
 
 ## Utils
 
-Lower-level building blocks for custom components: the keyboard shortcut controller.
+Lower-level building blocks: adapter and MIME type resolution, and the keyboard shortcut controller for custom components.
 
+- [resolveAdapterType](./resolve-adapter-type.md): Resolve which type of adapter plays a source URL, from its host, MIME type, or file extension
+- [resolveMimeType](./resolve-mime-type.md): Resolve a source's MIME type from its file extension
 - [AriaKeyShortcutsController](./aria-key-shortcuts-controller.md): Reactive controller that exposes registered hotkey shortcut metadata
 
 ## Error codes

package/docs/reference/api/load-locale.md

@@ -0,0 +1,36 @@
+# loadLocale
+
+Lazy-load the built-in translation pack for a locale
+
+## Import
+
+```ts
+import { loadLocale } from "@videojs/html/i18n";
+```
+
+`loadLocale` imports the built-in pack for a tag, or for the closest tag in its [`findLocaleKeys`](./find-locale-keys.md) chain, and resolves to its flat translations. It resolves to `undefined` when that chain reaches a locale registered with [`registerI18n`](./register-i18n.md) first, or when no built-in pack matches. Providers call it for you; use it to translate UI outside a provider without bundling every pack.
+
+```ts
+import { createTranslator, getI18nTranslations, loadLocale } from '@videojs/html/i18n';
+
+const pack = await loadLocale('fr-CA');
+const t = createTranslator({ ...pack, ...getI18nTranslations('fr-CA') }, 'fr-CA');
+
+t('buttons.play'); // 'Lecture'
+```
+
+## API Reference
+
+`loadLocale(tag): Promise<Partial<FlatTranslations> | undefined>`
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `tag` (required) | `string` | — | BCP 47 tag to load, such as `fr-CA`. |
+
+### Return Value
+
+| Type |
+| --- |
+| `Promise<Partial<FlatTranslations> \| undefined>` |

package/docs/reference/api/media-capabilities.md

@@ -0,0 +1,255 @@
+# Media capability guards
+
+Type guards that narrow a Media object to the capabilities it supports
+
+The media a player attaches is typed as `Media`, which guarantees only a `play()` method and the `addEventListener`, `removeEventListener`, and `dispatchEvent` event methods. A native `<video>` element, an engine-backed media such as `HlsVideo`, and an embed such as YouTube each support a different set of everything else. Capability guards test whether a media supports one capability and narrow its type to that capability’s members.
+
+## Import
+
+```ts
+import { isMediaSeekCapable, isMediaVolumeCapable } from "@videojs/html";
+```
+
+Every guard on this page is a named export of the same package.
+
+## Usage
+
+The player element’s `store.target` holds the media the player attached. It’s `null` until a media element inside the player registers, so read it when you need it rather than once at startup:
+
+**index.ts**
+
+```ts
+import "@videojs/html/video/player";
+import { isMediaVolumeCapable } from "@videojs/html";
+
+const player = document.querySelector("video-player");
+
+document.querySelector("#half-volume")?.addEventListener("click", () => {
+  const media = player?.store.target?.media;
+  if (isMediaVolumeCapable(media)) media.volume = 0.5;
+});
+```
+
+The examples below assume `player` is the queried player element.
+
+Each `isMedia*Capable` guard accepts any value and returns `false` for `null`, `undefined`, and other non-objects, so you can pass the media straight in without a separate null check.
+
+## Behavior
+
+A guard checks that a few members of a capability are present, then narrows to every member of that capability’s contract. The table lists both.
+
+Some media, such as embeds, can’t provide buffered ranges, text tracks, or remote playback, and report a shared empty placeholder in their place. `isMediaBufferCapable`, `isMediaTextTrackCapable`, and `isMediaRemotePlaybackCapable` return `false` for that placeholder.
+
+A guard describes what the media object supports, not its current state. `isMediaErrorCapable` returns `true` while `error` is `null`, and `isMediaVolumeCapable` returns `true` on platforms that ignore volume changes. For current state and availability, such as `volumeAvailability` from the [volume feature](./feature-volume.md), read the player’s [features](../../guides/features.md) instead.
+
+| Guard | Checks | Narrows to |
+| --- | --- | --- |
+| `isMediaPauseCapable` | `paused`, `ended`, `pause()` | `pause()`, `paused`, `ended` |
+| `isMediaSeekCapable` | `currentTime`, `duration`, `seeking` | `currentTime`, `loop`, `duration`, `seeking` |
+| `isMediaSourceCapable` | `src`, `currentSrc`, `readyState`, `load()` | `src`, `currentSrc`, `readyState`, `preload`, `crossOrigin`, `load()`, `canPlayType()` |
+| `isMediaVolumeCapable` | `volume`, `muted` | `volume`, `muted`, `defaultMuted` |
+| `isMediaPlaybackRateCapable` | `playbackRate` | `playbackRate`, `defaultPlaybackRate` |
+| `isMediaBufferCapable` | `buffered`, `seekable`, neither an empty placeholder | `buffered`, `seekable` |
+| `isMediaErrorCapable` | `error` (`null` counts) | `error` |
+| `isMediaTextTrackCapable` | `textTracks`, not an empty placeholder | `textTracks`, `addTextTrack()` |
+| `isMediaVideoRenditionCapable` | `videoRenditions` | `videoRenditions` |
+| `isMediaAudioTrackCapable` | `audioTracks` | `audioTracks`, `addAudioTrack()`, `removeAudioTrack()` |
+| `isMediaVideoDimensionsCapable` | `videoWidth`, `videoHeight` | `videoWidth`, `videoHeight` |
+| `isMediaRemotePlaybackCapable` | `remote` is an object, not an empty placeholder | `remote`, `disableRemotePlayback` |
+| `isMediaStreamTypeCapable` | `streamType` | `streamType` |
+| `isMediaLiveCapable` | `liveEdgeStart`, `targetLiveWindow` | `liveEdgeStart`, `targetLiveWindow` |
+
+`hasMetadata` isn’t a type guard: it takes a media already narrowed by `isMediaSourceCapable` and returns a boolean.
+
+## Guards
+
+### `isMediaPauseCapable`
+
+Narrows to `pause()` and the read-only `paused` and `ended` booleans.
+
+```ts
+function togglePaused() {
+  const media = player?.store.target?.media;
+  if (!isMediaPauseCapable(media)) return;
+
+  if (media.paused) media.play();
+  else media.pause();
+}
+```
+
+### `isMediaSeekCapable`
+
+Narrows to the writable `currentTime` and `loop`, and the read-only `duration` and `seeking`. All times are in seconds.
+
+```ts
+function skipForward() {
+  const media = player?.store.target?.media;
+  if (isMediaSeekCapable(media)) media.currentTime = Math.min(media.currentTime + 10, media.duration);
+}
+```
+
+### `isMediaSourceCapable`
+
+Narrows to the writable `src`, `preload`, and `crossOrigin`; the read-only `currentSrc` and `readyState`; and the `load()` and `canPlayType(type)` methods. `canPlayType` returns `''`, `'maybe'`, or `'probably'`.
+
+```ts
+function playNext(url: string) {
+  const media = player?.store.target?.media;
+  if (!isMediaSourceCapable(media)) return;
+
+  media.src = url;
+  media.play();
+}
+```
+
+### `hasMetadata`
+
+Returns `true` when the media’s `readyState` is at least `HAVE_METADATA` (`1`), meaning duration and dimensions are known. It reads only `readyState`, so narrow with `isMediaSourceCapable` first.
+
+```ts
+function resumeAt(seconds: number) {
+  const media = player?.store.target?.media;
+  if (!isMediaSourceCapable(media) || !hasMetadata(media)) return;
+  if (isMediaSeekCapable(media)) media.currentTime = seconds;
+}
+```
+
+### `isMediaVolumeCapable`
+
+Narrows to the writable `volume` (`0` to `1`), `muted`, and `defaultMuted`.
+
+```ts
+function unmuteAtHalfVolume() {
+  const media = player?.store.target?.media;
+  if (!isMediaVolumeCapable(media)) return;
+
+  media.muted = false;
+  media.volume = 0.5;
+}
+```
+
+### `isMediaPlaybackRateCapable`
+
+Narrows to the writable `playbackRate` and `defaultPlaybackRate`.
+
+```ts
+function playFaster() {
+  const media = player?.store.target?.media;
+  if (isMediaPlaybackRateCapable(media)) media.playbackRate = 1.5;
+}
+```
+
+### `isMediaBufferCapable`
+
+Narrows to the read-only `buffered` and `seekable` time ranges. Each range list has a `length` and `start(index)` and `end(index)` methods that return seconds.
+
+```ts
+function getBufferedEnd() {
+  const media = player?.store.target?.media;
+  if (!isMediaBufferCapable(media) || media.buffered.length === 0) return 0;
+
+  return media.buffered.end(media.buffered.length - 1);
+}
+```
+
+### `isMediaErrorCapable`
+
+Narrows to the read-only `error`, which is `null` or an object with a numeric `code` and a `message`.
+
+```ts
+function reportError() {
+  const media = player?.store.target?.media;
+  if (isMediaErrorCapable(media) && media.error) console.error(media.error.code, media.error.message);
+}
+```
+
+### `isMediaTextTrackCapable`
+
+Narrows to the read-only `textTracks` list and `addTextTrack(kind, label?, language?)`. The list is iterable and indexable, and each track has `kind`, `label`, `language`, `id`, a writable `mode` (`'showing'`, `'hidden'`, or `'disabled'`), and `cues`.
+
+```ts
+function showCaptions(language: string) {
+  const media = player?.store.target?.media;
+  if (!isMediaTextTrackCapable(media)) return;
+
+  for (const track of media.textTracks) {
+    if (track.kind === "captions" || track.kind === "subtitles") {
+      track.mode = track.language === language ? "showing" : "disabled";
+    }
+  }
+}
+```
+
+### `isMediaVideoRenditionCapable`
+
+Narrows to the read-only `videoRenditions` list. The list is iterable and indexable, has `getRenditionById(id)`, and has a writable `selectedIndex`; `-1` means automatic selection. Each rendition has `id`, `width`, `height`, `bitrate`, `frameRate`, `codec`, and `selected`.
+
+```ts
+function switchToAutomaticQuality() {
+  const media = player?.store.target?.media;
+  if (isMediaVideoRenditionCapable(media)) media.videoRenditions.selectedIndex = -1;
+}
+```
+
+### `isMediaAudioTrackCapable`
+
+Narrows to the read-only `audioTracks` list, `addAudioTrack(kind, label?, language?)`, and `removeAudioTrack(track)`. The list is iterable and indexable, and each track has `id`, `kind`, `label`, `language`, and a writable `enabled`.
+
+```ts
+function selectAudioLanguage(language: string) {
+  const media = player?.store.target?.media;
+  if (!isMediaAudioTrackCapable(media)) return;
+
+  for (const track of media.audioTracks) track.enabled = track.language === language;
+}
+```
+
+### `isMediaVideoDimensionsCapable`
+
+Narrows to the read-only `videoWidth` and `videoHeight`, in pixels. Both are `0` until metadata loads.
+
+```ts
+function getAspectRatio() {
+  const media = player?.store.target?.media;
+  if (!isMediaVideoDimensionsCapable(media) || !media.videoHeight) return null;
+
+  return media.videoWidth / media.videoHeight;
+}
+```
+
+### `isMediaRemotePlaybackCapable`
+
+Narrows to the read-only `remote` object and the writable `disableRemotePlayback`. `remote` has a `state` (`'connecting'`, `'connected'`, or `'disconnected'`), `prompt()`, `watchAvailability(callback)`, and `cancelWatchAvailability(id?)`, matching the browser’s [Remote Playback API](https://developer.mozilla.org/en-US/docs/Web/API/RemotePlayback).
+
+```ts
+function castToDevice() {
+  const media = player?.store.target?.media;
+  if (isMediaRemotePlaybackCapable(media)) media.remote.prompt();
+}
+```
+
+Call `prompt()` from a user gesture, such as a click handler; browsers reject it otherwise.
+
+### `isMediaStreamTypeCapable`
+
+Narrows to `streamType`: `'on-demand'`, `'live'`, or `'unknown'` before the type is determined.
+
+```ts
+function isLiveStream() {
+  const media = player?.store.target?.media;
+  return isMediaStreamTypeCapable(media) && media.streamType === "live";
+}
+```
+
+### `isMediaLiveCapable`
+
+Narrows to the read-only `liveEdgeStart` and `targetLiveWindow`. Playback is at the live edge when `currentTime` is at or past `liveEdgeStart`, which is `NaN` when the stream isn’t live or the value is unknown. `targetLiveWindow` is `0` for a sliding live window, `Infinity` for a live event with playback history, and `NaN` for on-demand or unknown; it isn’t a duration.
+
+```ts
+function isAtLiveEdge() {
+  const media = player?.store.target?.media;
+  if (!isMediaLiveCapable(media) || !isMediaSeekCapable(media)) return false;
+
+  return media.currentTime >= media.liveEdgeStart;
+}
+```

package/docs/reference/api/player-controller.md

@@ -21,6 +21,39 @@ class PlayButtonElement extends UIElement {
 }
 ```
 
+The host must be a reactive controller host, such as a subclass of [`UIElement`](./ui-element.md), so the controller can request updates.
+
+## Player context
+
+`playerContext` is the context every player element provides to its descendants, whether the element comes from a preset or from [`createPlayer`](./html-create-player.md). `PlayerController` requests it from its host when the host connects, and the nearest ancestor player answers with its store. An element outside a player receives nothing, so `value` stays `undefined`.
+
+Pass `playerContext` to the `PlayerController` exported from `@videojs/html`:
+
+```ts
+import { PlayerController, playerContext, selectPlayback, UIElement } from "@videojs/html";
+
+class PlayButtonElement extends UIElement {
+  readonly #playback = new PlayerController(this, playerContext, selectPlayback);
+}
+```
+
+With a selector, the selector types the value. Without one, `value` is typed as the base player store, with no feature state or actions, because `playerContext` does not know the player’s features. For typed access, use the `PlayerController` that `createPlayer` returns, which is already bound to its player, or pass the context `createPlayer` returns, which is the same context as `playerContext` typed for its feature set:
+
+```ts
+import { createPlayer, PlayerController, UIElement } from "@videojs/html";
+import { videoFeatures } from "@videojs/html/video";
+
+const { playerContext } = createPlayer({ features: videoFeatures });
+
+class VolumeResetElement extends UIElement {
+  readonly #store = new PlayerController(this, playerContext);
+
+  reset() {
+    this.#store.value?.setVolume(1);
+  }
+}
+```
+
 ## Examples
 
 ### Basic Usage
@@ -90,15 +123,7 @@ class PlayButtonElement extends UIElement {
 **index.ts**
 
 ```ts
-import {
-  applyElementProps,
-  createButton,
-  createPlayer,
-  selectPlayback,
-  selectTime,
-  selectVolume,
-  UIElement,
-} from '@videojs/html';
+import { createPlayer, selectPlayback, selectTime, selectVolume, UIElement } from '@videojs/html';
 import { videoFeatures } from '@videojs/html/video';
 import '@videojs/html/ui/container';
 
@@ -118,19 +143,13 @@ class PlayerActions extends UIElement {
     this.#disconnect = new AbortController();
     const signal = this.#disconnect.signal;
 
-    const playBtn = this.querySelector<HTMLButtonElement>('.play')!;
-    const pauseBtn = this.querySelector<HTMLButtonElement>('.pause')!;
-    const volumeBtn = this.querySelector<HTMLButtonElement>('.volume')!;
-
-    const bind = (el: HTMLElement, action: () => void) => {
-      const props = createButton({ onActivate: action, isDisabled: () => !this.#player.value });
-
-      applyElementProps(el, props, { signal });
+    const bind = (selector: string, action: () => void) => {
+      this.querySelector(selector)?.addEventListener('click', action, { signal });
     };
 
-    bind(playBtn, () => this.#player.value?.play());
-    bind(pauseBtn, () => this.#player.value?.pause());
-    bind(volumeBtn, () => this.#player.value?.setVolume(0.5));
+    bind('.play', () => this.#player.value?.play());
+    bind('.pause', () => this.#player.value?.pause());
+    bind('.volume', () => this.#player.value?.setVolume(0.5));
   }
 
   override disconnectedCallback(): void {