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

package/docs/concepts/custom-element-lifecycle.md

@@ -0,0 +1,115 @@
+# Custom element lifecycle
+
+Choose the right Video.js HTML base class and clean up custom elements when they leave the page.
+
+This guide is for developers creating custom elements with `@videojs/html`. If you only compose or style Video.js’s built-in elements, you do not need to manage this lifecycle yourself.
+
+For most custom controls, extend `UIElement`, clean up listeners and observers in `disconnectedCallback()`, and call the matching superclass callbacks. Read the advanced sections if you are building a player root or media element, or if an element must remain alive while detached.
+
+## Clean up when the element disconnects
+
+The browser can call `connectedCallback()` and `disconnectedCallback()` many times for the same element. Start listeners, observers, and other connection-scoped work when the element connects. Stop that work when it disconnects. Call the superclass lifecycle methods so reactive controllers and inherited cleanup also run:
+
+ts
+
+```
+import { UIElement } from '@videojs/html';
+
+class StatusElement extends UIElement {
+  #disconnect: AbortController | null = null;
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.#disconnect = new AbortController();
+    window.addEventListener('resize', this.#onResize, {
+      signal: this.#disconnect.signal,
+    });
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.#disconnect?.abort();
+    this.#disconnect = null;
+  }
+
+  #onResize = () => this.requestUpdate();
+}
+```
+
+This cleanup runs every time the element leaves the document, including when an application moves the same element and later reconnects it.
+
+## Advanced lifecycle details
+
+The rest of this page covers permanent destruction, longer detached periods, player roots, and custom media elements. Most custom controls only need the connection cleanup above.
+
+### Release resources permanently
+
+`UIElement` waits for two animation frames after disconnection before it calls `destroy()`. Synchronous moves and brief reparenting that reconnect before the second frame keep the element alive.
+
+Reserve `destroyCallback()` for resources that should survive a temporary disconnect, such as an owned store or imperative player API. Call `super.destroyCallback()` so registered controllers also release their resources.
+
+After destruction, the mixin’s connection path and update execution no-op. Repeated `destroy()` calls also no-op. Do not reinsert a destroyed instance; create a new element instead. Subclass lifecycle code should still call its superclass methods and can check the public `destroyed` flag when it needs an explicit guard.
+
+### Keep an element alive while detached
+
+Add `keep-alive` to disable automatic destruction for an element that intentionally remains detached longer than two frames. The attribute does not disable manual cleanup: calling `destroy()` still permanently destroys the element.
+
+Caution
+
+`keep-alive` makes your code responsible for calling `destroy()` when the element is no longer needed.
+
+### Choose a specialized base
+
+Choose the narrowest base that provides the lifecycle your element needs:
+
+Base
+
+Lifecycle behavior
+
+Typical use
+
+`HTMLElement`
+
+Browser custom element callbacks only
+
+Elements that manage their own state and cleanup
+
+`ReactiveElement`
+
+Reactive properties, batched updates, and reactive controller callbacks
+
+Reactive elements that do not need permanent destruction
+
+`UIElement`
+
+`ReactiveElement` plus delayed permanent destruction
+
+Custom player controls and other interactive player UI
+
+`CustomMediaElement(...)` with `MediaAttachMixin`
+
+A media adapter lifecycle plus player registration
+
+Custom playback engines and media elements
+
+`PlayerElement`
+
+The `UIElement` lifecycle plus store context and attachment ownership
+
+Player roots
+
+Use `UIElement` for most custom controls. Use the specialized bases when your element owns a player store or media provider.
+
+### Specialized resource owners
+
+`PlayerElement` follows the `UIElement` lifecycle. It detaches the store’s current media target immediately in `disconnectedCallback()`, but keeps the store so a brief move can reconnect with its state intact. It destroys the store only from `destroyCallback()`.
+
+Built-in custom media elements compose `CustomMediaElement(...)` with [`MediaAttachMixin`](../reference/media-attach-mixin.md). `CustomMediaElement` queues one microtask after disconnection and destroys its media adapter only if it remains disconnected. This protects a synchronous move, but not a longer detached period. Its `keep-alive` attribute skips that automatic media-adapter destruction.
+
+Player roots use the configured [`PlayerElement`](../reference/player.md) returned by `createPlayer`.
+
+## See also
+
+*   [Build your own UI component](../how-to/build-your-own-component.md)
+*   [`PlayerElement`](../reference/player.md)
+*   [`MediaAttachMixin`](../reference/media-attach-mixin.md)

package/docs/concepts/features.md

@@ -0,0 +1,131 @@
+# Features
+
+The state and actions each feature adds to the player
+
+Not every player needs to support every use case. To address this, Video.js has a concept of **features** — self-contained units of player functionality. Each one adds state properties and actions to the player. For example, “playback” adds `paused` and `play()`, “volume” adds `volume` and `setVolume()`, and so on.
+
+## Using features
+
+### Feature bundles and presets
+
+You probably don’t want to hand-pick every feature your player needs. A **feature bundle** groups the features needed for a specific use case into a single array.
+
+For example, if you import `<video-player>` from the `/video` path, you will have playback, volume, time, fullscreen, and more already enabled.
+
+html
+
+```
+<script type="module">
+  import '@videojs/html/video/player';
+  import '@videojs/html/video/skin';
+</script>
+<video-player>
+  <video-skin>
+    <video src="movie.mp4"></video>
+  </video-skin>
+</video-player>
+```
+
+Feature bundles are usually paired with specific skins and media elements in a **preset**. To learn more about this, and the available presets, you’ll want to check out the presets guide.
+
+- [Learn more about presets](./presets.md)
+
+### Create a player with individual features
+
+If you’re not using presets, you can create a player that has individual features.
+
+ts
+
+```
+import { controlsFeature, createPlayer, playbackFeature, timeFeature, volumeFeature } from '@videojs/html';
+
+const { PlayerElement: MyPlayer } = createPlayer({
+  features: [playbackFeature, volumeFeature, timeFeature, controlsFeature],
+});
+
+customElements.define('my-player', MyPlayer);
+```
+
+### Extending a feature bundle
+
+Since feature bundles are just an array of features under the hood, it doesn’t take much to extend one. For example, if you were using the `/background` preset and wanted a play button on your background video, you might add the playback feature.
+
+ts
+
+```
+import { createPlayer, playbackFeature } from '@videojs/html';
+import { backgroundFeatures } from '@videojs/html/background';
+
+const { PlayerElement: MyPlayer } = createPlayer({
+  features: [...backgroundFeatures, playbackFeature],
+});
+
+customElements.define('my-player', MyPlayer);
+```
+
+### Access features in components
+
+You can access feature state and actions through [`PlayerController`](../reference/player-controller.md) and pre-built feature selectors (e.g. [`selectPlayback`](../reference/feature-playback.md), [`selectVolume`](../reference/feature-volume.md)):
+
+ts
+
+```
+import { selectPlayback } from '@videojs/html';
+
+// Subscribe to feature state (triggers element updates on change)
+readonly #playback = new PlayerController(this, selectPlayback);
+
+// Read state and call actions
+const media = this.#playback.value;
+if (media?.paused) media.play();
+```
+
+### Checking for feature support
+
+Volume, fullscreen, and picture-in-picture expose availability properties because platform support varies. Volume has two independent properties: `volumeAvailability` for changing the volume level and `mutedAvailability` for toggling mute. For example, iOS Safari allows muting but doesn’t allow programmatic volume control.
+
+Value
+
+Meaning
+
+`'available'`
+
+Ready to use
+
+`'unavailable'`
+
+Could work, not ready yet
+
+`'unsupported'`
+
+Platform can never do this
+
+Components that depend on availability (like [`MuteButton`](../reference/mute-button.md), [`PiPButton`](../reference/pip-button.md), and [`FullscreenButton`](../reference/fullscreen-button.md)) handle the three states for you:
+
+*   **`unsupported`** — the HTML custom element receives the native `hidden` attribute (and `data-hidden`); React buttons return `null`. No CSS needed.
+*   **`unavailable`** — the presentation controls stay hidden while capability detection is unresolved. Cast remains visible but disabled when its API is supported and no device is reachable.
+*   **`disabled` prop** — an available button stays visible and focusable with `aria-disabled="true"` plus `data-disabled` for styling.
+*   **`available`** — fully interactive.
+
+Use `data-disabled` to style the non-interactive state:
+
+css
+
+```
+media-pip-button[data-disabled] {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+```
+
+You can also check availability in JS:
+
+ts
+
+```
+const media = this.#pip.value;
+
+if (media?.pipAvailability !== 'available') {
+  this.hidden = true;
+}
+```