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

package/docs/reference/player-container.md

@@ -0,0 +1,125 @@
+# media-container
+
+The player's visual and interaction surface for layout, fullscreen, focus, and user activity.
+
+The `<media-container>` is the player’s physical surface. It defines the visual boundary, registers the fullscreen and activity target, and gives gesture and hotkey elements a shared interaction surface. It lives inside a [`<video-player>`](./player.md).
+
+html
+
+```
+<video-player>
+  <media-container>
+    <video src="video.mp4"></video>
+    <media-controls><media-controls-content>...</media-controls-content></media-controls>
+  </media-container>
+</video-player>
+```
+
+## How it’s created
+
+Import the standard player entry point. It registers both `<video-player>` and `<media-container>`:
+
+ts
+
+```
+import '@videojs/html/video/player';
+```
+
+html
+
+```
+<video-player>
+  <media-container>
+    <video src="video.mp4"></video>
+  </media-container>
+</video-player>
+```
+
+For custom behavior, extend the same `ContainerElement` used by the built-in player:
+
+my-player.ts
+
+```
+import { ContainerElement } from '@videojs/html';
+
+class MyContainer extends ContainerElement {}
+customElements.define('my-container', MyContainer);
+```
+
+Extending `ContainerElement` automatically registers the element with the nearest player when it connects and releases that registration when it disconnects.
+
+Import `@videojs/html/ui/container` when you only need to register the standard `<media-container>` element.
+
+## What it does
+
+### Layout and fullscreen
+
+The container is the visual box around your media and controls. Put sizing, aspect ratio, positioning, and visual boundaries here — on `Container`, not `Player`. Place overlays inside it, use it as their positioning context, and measure it when your app needs the rendered player size.
+
+css
+
+```
+.player-surface {
+  position: relative;
+  display: block;
+  width: 640px;
+  aspect-ratio: 16 / 9;
+}
+```
+
+html
+
+```
+<media-container class="player-surface">
+  <video src="video.mp4"></video>
+  <media-controls><media-controls-content>...</media-controls-content></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.
+
+Custom video elements such as `<mux-video>` and `<hlsjs-video>` do not create their own layout boxes: their inner `<video>` fills the parent. Size and measure `<media-container>`, not `<mux-video>` or `<hlsjs-video>`. Native `<video>` and `<audio>` elements still render their own boxes.
+
+### Media attachment
+
+Media discovery is handled by the player provider, not the container. Custom media elements like `<hlsjs-video>` register themselves via context when they connect. Plain `<video>` and `<audio>` elements are tracked automatically, including when they are added, removed, or replaced after connection. 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** — Tap and double-tap actions, optionally limited by pointer type and left, center, or right region. Configured via the [`Gesture`](./gesture.md) component.
+*   **Keyboard controls** — Spacebar to play/pause, arrow keys to seek, and other keyboard shortcuts scoped to the container. Configured via the `Hotkey` component.
+
+### Popup coordination
+
+Each container owns one popup group. Opening a root [menu](./menu.md) or [popover](./popover.md) closes the previously open popup in that container. A popup rendered outside the container still manages its own open state, but it does not participate in the container’s group.
+
+## 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.
+
+Style `<video-skin>` for the player’s outer size and aspect ratio. Importing the skin registers the styles that make the built-in container fill that space and position the media, controls, poster, and overlays.
+
+If you omit `<video-skin>` to build custom UI, render and style `<media-container>` yourself. See [Layout and fullscreen](#layout-and-fullscreen) for the complete layout example.
+
+## Inside vs. outside the container
+
+[`Player`](./player.md) gives components access to state and actions. `Container` layers on physical behaviors — fullscreen, activity detection, and 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-content>...</media-controls-content></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,60 @@
+# playerContext
+
+The default player context instance for consuming the player store in controllers
+
+## Import
+
+ts
+
+```
+import { playerContext } from "@videojs/html";
+```
+
+`playerContext` is a Web Components context token that carries the player store through the DOM tree. Player elements publish the store to this context, and consumers such as [`PlayerController`](./player-controller.md) read from it. Video.js contexts follow the Web Components Community Group [Context Protocol](https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md), so providers and consumers communicate with standard context request events instead of requiring a specific element hierarchy.
+
+`playerContext` carries player state and actions. [`ContainerElement`](./player-container.md) registers the player’s visual container through `containerContext`, not `playerContext`; its internal `PlayerController` separately consumes `playerContext` for controls state.
+
+Pass it as the second argument to `PlayerController`:
+
+play-button.ts
+
+```
+import { PlayerController, UIElement, playerContext, selectPlayback } from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+
+class PlayButton extends UIElement {
+  #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 `playerContext` property that is the same `playerContext` instance exported from the package. Both approaches reference the same object:
+
+ts
+
+```
+// Direct import
+import { playerContext } from '@videojs/html';
+
+// Destructured — identical object
+const { playerContext: configuredContext } = createPlayer({ features: videoFeatures });
+configuredContext === playerContext; // true
+```
+
+Use the direct import when building reusable elements that don’t depend on a specific `createPlayer` call.
+
+### When you need this
+
+Most custom-player elements should use the configured [`PlayerController`](./player-controller.md) returned by `createPlayer`, which is already bound to the context. Import `playerContext` directly when using the package-level controller or another lower-level context consumer.
+
+## API Reference
+
+### Return Value
+
+`Store<PlayerTarget, object>`

package/docs/reference/player-controller.md

@@ -0,0 +1,314 @@
+# PlayerController
+
+Reactive controller for accessing player store state in HTML custom elements
+
+## Import
+
+ts
+
+```
+import { PlayerController } from "@videojs/html/video";
+```
+
+`PlayerController` is a reactive controller that consumes the player store from [`playerContext`](./player-context.md). Without a selector it returns the store instance directly (no subscription — use this for actions). With a selector it returns the selected value and subscribes to changes, triggering a host update on shallow-equal change. Access the current value via `.value`, which returns `undefined` until connected to a player.
+
+The controller exported by each preset, or returned by [`createPlayer`](./html-create-player.md), is already bound to that player’s context, so pass only the host and optional selector. The lower-level `PlayerController` exported from `@videojs/html` accepts the context as its second argument; its constructor signatures are documented below.
+
+ts
+
+```
+import { UIElement, selectPlayback } from '@videojs/html';
+import { PlayerController } from '@videojs/html/video';
+
+class PlayButtonElement extends UIElement {
+  readonly #playback = new PlayerController(this, selectPlayback);
+}
+```
+
+## Examples
+
+### Basic Usage
+
+Play Pause 50% Volume Paused: Yes | Time: 0.0s | Volume: 100%
+
+index.html
+
+index.css
+
+index.ts
+
+```
+<demo-ctrl-player class="demo-ctrl-player">
+  <media-container>
+    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline></video>
+    <div class="panel">
+      <demo-ctrl-actions class="actions">
+        <button type="button" class="play">Play</button>
+        <button type="button" class="pause">Pause</button>
+        <button type="button" class="volume">50% Volume</button>
+      </demo-ctrl-actions>
+      <demo-ctrl-state class="state">
+        <span class="text">Paused: Yes | Time: 0.0s | Volume: 100%</span>
+      </demo-ctrl-state>
+    </div>
+  </media-container>
+</demo-ctrl-player>
+```
+```
+.demo-ctrl-player media-container {
+  position: relative;
+}
+
+.demo-ctrl-player media-container video {
+  width: 100%;
+}
+
+.panel {
+  display: flex;
+  gap: 16px;
+  align-items: center;
+  padding: 12px;
+  background: rgba(0, 0, 0, 0.05);
+  border-top: 1px solid rgba(0, 0, 0, 0.1);
+}
+
+.actions {
+  display: flex;
+  gap: 6px;
+}
+
+.actions button {
+  padding: 4px 12px;
+  font-size: 0.8125rem;
+  cursor: pointer;
+  background: white;
+  border: 1px solid #ccc;
+  border-radius: 6px;
+}
+
+.state {
+  font-size: 0.8125rem;
+  font-variant-numeric: tabular-nums;
+  color: #374151;
+}
+```
+```
+import {
+  applyElementProps,
+  createButton,
+  createPlayer,
+  selectPlayback,
+  selectTime,
+  selectVolume,
+  UIElement,
+} from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+import '@videojs/html/ui/container';
+
+const { PlayerElement: DemoPlayerElement, PlayerController } = createPlayer({
+  features: videoFeatures,
+});
+
+class PlayerActions extends UIElement {
+  static readonly tagName = 'demo-ctrl-actions';
+
+  readonly #player = new PlayerController(this);
+
+  #disconnect: AbortController | null = null;
+
+  override connectedCallback(): void {
+    super.connectedCallback();
+    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 });
+    };
+
+    bind(playBtn, () => this.#player.value?.play());
+    bind(pauseBtn, () => this.#player.value?.pause());
+    bind(volumeBtn, () => this.#player.value?.setVolume(0.5));
+  }
+
+  override disconnectedCallback(): void {
+    super.disconnectedCallback();
+    this.#disconnect?.abort();
+    this.#disconnect = null;
+  }
+}
+
+class PlayerState extends UIElement {
+  static readonly tagName = 'demo-ctrl-state';
+
+  readonly #playback = new PlayerController(this, selectPlayback);
+  readonly #time = new PlayerController(this, selectTime);
+  readonly #volume = new PlayerController(this, selectVolume);
+
+  protected override update(changed: Map<string, unknown>): void {
+    super.update(changed);
+    const playback = this.#playback.value;
+    const time = this.#time.value;
+    const volume = this.#volume.value;
+
+    if (!playback) return;
+
+    const el = this.querySelector('.text');
+
+    if (el) {
+      el.textContent = `Paused: ${playback.paused ? 'Yes' : 'No'} | Time: ${(time?.currentTime ?? 0).toFixed(1)}s | Volume: ${Math.round((volume?.volume ?? 0) * 100)}%`;
+    }
+  }
+}
+
+customElements.define('demo-ctrl-player', DemoPlayerElement);
+customElements.define(PlayerActions.tagName, PlayerActions);
+customElements.define(PlayerState.tagName, PlayerState);
+```
+
+## API Reference
+
+### Overload 1
+
+#### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`host*`
+
+`object`
+
+`—`
+
+▸
+
+Description
+
+The host element that owns this controller.
+
+Type
+
+`{ addController(controller: ReactiveController): void; removeController(controller: ReactiveController): void; requestUpdate(): void; updateComplete: Promise<boolean> } & HTMLElement`
+
+`context*`
+
+`Context<typeof PLAYER_CONTEXT_KEY, PlayerContextValue<Store>>`
+
+`—`
+
+▸
+
+Description
+
+Player context to resolve the store from.
+
+#### Return Value
+
+Property
+
+Type
+
+Details
+
+`value`
+
+`Result | undefined`
+
+`displayName`
+
+`string | undefined`
+
+`hostConnected`
+
+`(() => void)`
+
+`hostDisconnected`
+
+`(() => void)`
+
+### Overload 2
+
+#### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`host*`
+
+`object`
+
+`—`
+
+▸
+
+Description
+
+The host element that owns this controller.
+
+Type
+
+`{ addController(controller: ReactiveController): void; removeController(controller: ReactiveController): void; requestUpdate(): void; updateComplete: Promise<boolean> } & HTMLElement`
+
+`context*`
+
+`Context<typeof PLAYER_CONTEXT_KEY, PlayerContextValue<Store>>`
+
+`—`
+
+▸
+
+Description
+
+Player context to resolve the store from.
+
+`selector*`
+
+`Selector<InferStoreState<Store>, Result>`
+
+`—`
+
+▸
+
+Description
+
+Derives a value from the player store state.
+
+#### Return Value
+
+Property
+
+Type
+
+Details
+
+`value`
+
+`Result | undefined`
+
+`displayName`
+
+`string | undefined`
+
+`hostConnected`
+
+`(() => void)`
+
+`hostDisconnected`
+
+`(() => void)`

package/docs/reference/player.md

@@ -0,0 +1,123 @@
+# video-player
+
+The state boundary — creates a store and broadcasts it to all descendants.
+
+The `<video-player>` element is the state boundary of your player. It creates a store and makes it available to every element inside it via context. Every player needs exactly one.
+
+html
+
+```
+<video-player>
+  <!-- Everything inside can access the player store -->
+  <media-container>
+    <video src="video.mp4"></video>
+  </media-container>
+</video-player>
+```
+
+## How it’s created
+
+For most users, importing from `@videojs/html/video/player` registers a ready-to-use `<video-player>` element with the standard video [features](../concepts/features.md) (bundled as a [preset](../concepts/presets.md)):
+
+ts
+
+```
+import '@videojs/html/video/player';
+```
+
+html
+
+```
+<video-player>
+  <media-container>
+    <video src="video.mp4"></video>
+  </media-container>
+</video-player>
+```
+
+If you need a custom feature set or tag name, use `createPlayer()` to get the configured `PlayerElement`. Extend `ContainerElement` separately when you need custom container behavior:
+
+my-player.ts
+
+```
+import { ContainerElement, createPlayer } from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+
+const { PlayerElement: MyPlayer } = createPlayer({ features: videoFeatures });
+
+class MyContainer extends ContainerElement {}
+customElements.define('my-player', MyPlayer);
+customElements.define('my-container', MyContainer);
+```
+
+- [createPlayer reference](./html-create-player.md)
+
+## What lives inside it
+
+Everything that needs player state goes inside `Player`: skins, containers, UI components, and your own custom components. Anything inside can access the store.
+
+html
+
+```
+<video-player>
+  <video-skin>               <!-- skin — includes container + controls -->
+    <video src="..."></video> <!-- media element -->
+  </video-skin>
+  <my-custom-overlay></my-custom-overlay> <!-- your own element — can use PlayerController -->
+</video-player>
+```
+
+## No visual presence
+
+Packaged skins make `<video-player>` boxless with `display: contents`. Width, height, positioning, transforms, and `getBoundingClientRect()` do not describe a visible player box there. Put layout and measurements on the [`<media-container>`](./player-container.md) instead.
+
+If you omit `<video-skin>` and import only the player and media elements, those skin styles are not loaded. The player element still owns state, not layout, so add and style a `<media-container>` instead of using the player itself as the layout surface.
+
+## Accessing state
+
+Use the preset’s typed `PlayerController` to subscribe to store state from any custom element inside the player:
+
+play-pause-button.ts
+
+```
+import { UIElement, selectPlayback } from '@videojs/html';
+import { PlayerController } from '@videojs/html/video';
+
+class PlayPauseButton extends UIElement {
+  readonly #playback = new PlayerController(this, selectPlayback);
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.addEventListener('click', this.#togglePlayback);
+  }
+
+  disconnectedCallback() {
+    this.removeEventListener('click', this.#togglePlayback);
+    super.disconnectedCallback();
+  }
+
+  readonly #togglePlayback = () => this.#playback.value?.togglePaused();
+}
+
+customElements.define('play-pause-button', PlayPauseButton);
+```
+
+- [PlayerController reference](./player-controller.md)
+
+## Extended player layouts
+
+The player’s scope can extend beyond the fullscreen target. Playlists, transcripts, sidebars, and other supplementary UI can live inside `Player` but outside `Container`. They still have full access to the store, but they won’t go fullscreen with the video.
+
+html
+
+```
+<video-player>
+  <media-container>
+    <video src="video.mp4"></video>
+    <media-controls><media-controls-content>...</media-controls-content></media-controls>  <!-- goes fullscreen with the video -->
+  </media-container>
+
+  <media-transcript></media-transcript>     <!-- outside container — still has store access -->
+  <playlist-sidebar></playlist-sidebar>     <!-- outside container — still has store access -->
+</video-player>
+```