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

package/docs/reference/fullscreen-button.md

@@ -0,0 +1,229 @@
+# media-fullscreen-button
+
+Accessible fullscreen toggle button with keyboard support and state reflection
+
+## Anatomy
+
+html
+
+```
+<media-fullscreen-button></media-fullscreen-button>
+```
+
+## Behavior
+
+Toggles fullscreen mode. Detects platform support through `availability` — when fullscreen is `"unsupported"`, the toggle does nothing.
+
+## Styling
+
+You can style the button based on fullscreen state:
+
+css
+
+```
+/* In fullscreen */
+media-fullscreen-button[data-fullscreen] {
+  background: red;
+}
+```
+
+Consider hiding the button when unsupported:
+
+css
+
+```
+media-fullscreen-button[data-availability="unsupported"] {
+  display: none;
+}
+```
+
+## Accessibility
+
+Renders a `<button>` with an automatic `aria-label`: “Enter fullscreen” or “Exit fullscreen”. Override with the `label` prop. Keyboard activation: Enter / Space.
+
+## Examples
+
+### Basic Usage
+
+Exit Fullscreen Fullscreen
+
+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
+            loop
+        ></video>
+        <media-fullscreen-button class="media-fullscreen-button">
+            <span class="fullscreen">Exit Fullscreen</span>
+            <span class="not-fullscreen">Fullscreen</span>
+        </media-fullscreen-button>
+    </media-container>
+</video-player>
+```
+```
+.video-player {
+  position: relative;
+  display: block;
+}
+
+.video-player video {
+  width: 100%;
+}
+
+.media-fullscreen-button {
+  position: absolute;
+  right: 10px;
+  bottom: 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-fullscreen-button .fullscreen {
+  display: none;
+}
+.media-fullscreen-button .not-fullscreen {
+  display: none;
+}
+.media-fullscreen-button[data-fullscreen] .fullscreen {
+  display: inline;
+}
+.media-fullscreen-button:not([data-fullscreen]) .not-fullscreen {
+  display: inline;
+}
+```
+```
+import '@videojs/html/video/player';
+import '@videojs/html/ui/fullscreen-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: FullscreenButtonState) => string)`
+
+### State
+
+State is reflected as data attributes for CSS styling.
+
+Property
+
+Type
+
+Details
+
+`availability`
+
+`'available' | 'unavailable' | 'unsupp...`
+
+▸
+
+Description
+
+Whether fullscreen can be requested on this platform.
+
+Type
+
+`'available' | 'unavailable' | 'unsupported'`
+
+`fullscreen`
+
+`boolean`
+
+▸
+
+Description
+
+Whether fullscreen mode is currently active.
+
+`label`
+
+`string`
+
+### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-fullscreen`
+
+▸
+
+Description
+
+Present when fullscreen mode is active.
+
+`data-availability`
+
+`'available' | 'unavailable' | 'unsupp...`
+
+▸
+
+Description
+
+Indicates fullscreen availability (`available` or `unsupported`).
+
+Type
+
+`'available' | 'unavailable' | 'unsupported'`

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

@@ -0,0 +1,449 @@
+# createPlayer
+
+Factory function that creates a player instance with typed store, mixins, and controller for HTML custom elements
+
+`createPlayer` is the entry point for setting up a Video.js player with HTML custom elements. It accepts a configuration object with a `features` array and returns a typed [`PlayerController`](./player-controller.md), `context`, `ProviderMixin`, `ContainerMixin`, and a `create` store factory.
+
+player.ts
+
+```
+import { createPlayer, MediaElement, selectPlayback } from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+
+const { ProviderMixin, ContainerMixin, PlayerController, context } = createPlayer({
+  features: videoFeatures,
+});
+
+// Provider element: owns the store, provides context to descendants
+class VideoPlayer extends ProviderMixin(MediaElement) {}
+customElements.define('video-player', VideoPlayer);
+
+// Control element with selector
+class PlayButton extends MediaElement {
+  #playback = new PlayerController(this, context, selectPlayback);
+}
+```
+
+`PlayerController`, `ProviderMixin`, and `ContainerMixin` are intended for controller hosts and custom-element composition. Keep wiring minimal in utility examples, and build concrete elements where needed.
+
+Use split elements (recommended for reusable skins/layouts):
+
+player.ts
+
+```
+import { createPlayer, MediaElement } from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+
+const { ProviderMixin, ContainerMixin } = createPlayer({ features: videoFeatures });
+
+class PlayerRoot extends ProviderMixin(MediaElement) {}
+class PlayerRegion extends ContainerMixin(MediaElement) {}
+```
+
+Use a single composed element when the same element should both own the store and attach media:
+
+player.ts
+
+```
+import { createPlayer, MediaElement } from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+
+const { ProviderMixin, ContainerMixin } = createPlayer({ features: videoFeatures });
+
+class ComposedPlayer extends ProviderMixin(ContainerMixin(MediaElement)) {}
+```
+
+## Examples
+
+### Basic Usage
+
+Play Pause
+
+index.html
+
+index.css
+
+index.ts
+
+```
+<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>
+    </media-container>
+</demo-video-player>
+```
+```
+.demo-video-player {
+  position: relative;
+}
+
+.demo-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[data-paused] .paused {
+  display: inline;
+}
+
+.media-play-button:not([data-paused]) .playing {
+  display: inline;
+}
+```
+```
+import {
+  applyElementProps,
+  applyStateDataAttrs,
+  createButton,
+  createPlayer,
+  MediaElement,
+  PlayerController,
+  selectPlayback,
+} from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+import '@videojs/html/media/container';
+
+const { ProviderMixin, context } = createPlayer({
+  features: videoFeatures,
+});
+
+class VideoPlayer extends ProviderMixin(MediaElement) {
+  static readonly tagName = 'demo-video-player';
+}
+
+class PlayToggle extends MediaElement {
+  static readonly tagName = 'demo-play-toggle';
+
+  readonly #player = new PlayerController(this, context, selectPlayback);
+
+  #disconnect: AbortController | null = null;
+
+  override connectedCallback(): void {
+    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 });
+  }
+
+  override disconnectedCallback(): void {
+    super.disconnectedCallback();
+    this.#disconnect?.abort();
+    this.#disconnect = null;
+  }
+
+  protected override update(changed: Map<string, unknown>): void {
+    super.update(changed);
+    const state = this.#player.value;
+    if (!state) return;
+    applyStateDataAttrs(this, state, { paused: 'data-paused', ended: 'data-ended' });
+  }
+}
+
+customElements.define(VideoPlayer.tagName, VideoPlayer);
+customElements.define(PlayToggle.tagName, PlayToggle);
+```
+
+## API Reference
+
+### Video
+
+Creates a player factory with typed store, mixins, and controller.
+
+#### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`config*`
+
+`CreatePlayerConfig<VideoFeatures>`
+
+`—`
+
+▸
+
+Description
+
+Player configuration with features.
+
+#### Return Value
+
+Property
+
+Type
+
+Details
+
+`context`
+
+`PlayerContext<Store>`
+
+▸
+
+Description
+
+Context for consuming player in controllers.
+
+`create`
+
+`function`
+
+▸
+
+Description
+
+Creates a store instance for imperative access.
+
+Type
+
+`() => Store`
+
+`PlayerController`
+
+`PlayerController.Constructor<Store>`
+
+▸
+
+Description
+
+Player controller bound to this player's context.
+
+`ProviderMixin`
+
+`ProviderMixin<Store>`
+
+▸
+
+Description
+
+Mixin that provides player context to descendants.
+
+`ContainerMixin`
+
+`ContainerMixin<Store>`
+
+▸
+
+Description
+
+Mixin that consumes player context and registers as the container element.
+
+### Audio
+
+Creates a player factory for audio media.
+
+#### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`config*`
+
+`CreatePlayerConfig<AudioFeatures>`
+
+`—`
+
+▸
+
+Description
+
+Player configuration with features.
+
+#### Return Value
+
+Property
+
+Type
+
+Details
+
+`context`
+
+`PlayerContext<Store>`
+
+▸
+
+Description
+
+Context for consuming player in controllers.
+
+`create`
+
+`function`
+
+▸
+
+Description
+
+Creates a store instance for imperative access.
+
+Type
+
+`() => Store`
+
+`PlayerController`
+
+`PlayerController.Constructor<Store>`
+
+▸
+
+Description
+
+Player controller bound to this player's context.
+
+`ProviderMixin`
+
+`ProviderMixin<Store>`
+
+▸
+
+Description
+
+Mixin that provides player context to descendants.
+
+`ContainerMixin`
+
+`ContainerMixin<Store>`
+
+▸
+
+Description
+
+Mixin that consumes player context and registers as the container element.
+
+### Generic
+
+Creates a player factory with custom features.
+
+#### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`config*`
+
+`CreatePlayerConfig<Features>`
+
+`—`
+
+▸
+
+Description
+
+Player configuration with features.
+
+#### Return Value
+
+Property
+
+Type
+
+Details
+
+`context`
+
+`PlayerContext<Store>`
+
+▸
+
+Description
+
+Context for consuming player in controllers.
+
+`create`
+
+`function`
+
+▸
+
+Description
+
+Creates a store instance for imperative access.
+
+Type
+
+`() => Store`
+
+`PlayerController`
+
+`PlayerController.Constructor<Store>`
+
+▸
+
+Description
+
+Player controller bound to this player's context.
+
+`ProviderMixin`
+
+`ProviderMixin<Store>`
+
+▸
+
+Description
+
+Mixin that provides player context to descendants.
+
+`ContainerMixin`
+
+`ContainerMixin<Store>`
+
+▸
+
+Description
+
+Mixin that consumes player context and registers as the container element.