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

package/docs/how-to/build-your-own-component.md

@@ -1,350 +0,0 @@
-# Build your own UI component
-
-Create custom player controls that read state, dispatch actions, and stay accessible.
-
-Custom components subscribe to player state and dispatch actions, like built-in controls.
-
-## You might not need a custom component
-
-Before building from scratch, check if an existing approach covers your use case:
-
-*   **Restyle a control**: use CSS custom properties and data attributes. See [UI components](../concepts/ui-components.md).
-*   **Rearrange or remove controls**: eject a skin and modify it. See [Customize skins](./customize-skins.md#eject-and-edit-a-skin).
-
-Build a custom component when you need new behavior, a new state display, or integration with an external system.
-
-## Use player state and actions
-
-Need access to player state or actions? You’ll want to familiarize yourself with [features](../concepts/features.md). Each feature exposes a set. Here are some features you might reach for first:
-
-State
-
-Actions
-
-Feature
-
-`paused`, `ended`
-
-`play()`, `pause()`
-
-[Playback](../reference/feature-playback.md)
-
-`currentTime`, `duration`
-
-`seek()`
-
-[Time](../reference/feature-time.md)
-
-`volume`, `muted`
-
-`setVolume()`, `toggleMuted()`
-
-[Volume](../reference/feature-volume.md)
-
-`fullscreen`
-
-`requestFullscreen()`, `exitFullscreen()`
-
-[Fullscreen](../reference/feature-fullscreen.md)
-
-Browse the full list in the **Features** section of the sidebar.
-
-Features for platform-dependent capabilities also expose one or more **availability** properties (`'available'`, `'unavailable'`, or `'unsupported'`) for hiding controls the platform does not support. See [Features](../concepts/features.md) for details.
-
-Access state and actions with [`PlayerController`](../reference/player-controller.md) and a feature selector:
-
-ts
-
-```
-import { PlayerController, playerContext, selectPlayback } from '@videojs/html';
-
-// Subscribe to a feature — triggers update() when its state changes
-#playback = new PlayerController(this, playerContext, selectPlayback);
-
-// In update():
-const playback = this.#playback.value;
-if (playback?.paused) {
-  playback.play();
-}
-```
-
-Each selector returns both state and actions for that feature. Use separate controllers when you need multiple features (the [full example](#full-example) demonstrates this).
-
-Without a selector, `PlayerController` returns the full store without subscribing to changes:
-
-ts
-
-```
-#store = new PlayerController(this, playerContext);
-
-// Call any action
-this.#store.value.play();
-this.#store.value.setVolume(0.5);
-```
-
-## Place your component in the player
-
-Your element needs to be inside [`<video-player>`](../reference/player.md) to access state. Place it inside [`<media-container>`](../reference/player-container.md) if it should also participate in fullscreen and respond to user activity. `<video-skin>` slots its children into `<media-container>`, so a child of the skin works:
-
-html
-
-```
-<video-player>
-  <video-skin>
-    <video slot="media" src="video.mp4"></video>
-    <skip-intro-button>Skip intro</skip-intro-button>
-  </video-skin>
-</video-player>
-```
-
-Extend `UIElement` from `@videojs/html` so `PlayerController` can schedule DOM updates when state changes:
-
-ts
-
-```
-import { UIElement, PlayerController, playerContext, selectTime, type PropertyValues } from '@videojs/html';
-
-class SkipIntroButtonElement extends UIElement {
-  #player = new PlayerController(this, playerContext, selectTime);
-
-  update(changed: PropertyValues) {
-    super.update(changed);
-    const time = this.#player.value;
-  }
-}
-```
-
-If your element starts listeners, observers, or other work, see [Custom element lifecycle](../concepts/custom-element-lifecycle.md) for how to clean it up when the element is removed from the page.
-
-## Make it accessible
-
-- [Learn more about accessibility in video players](../concepts/accessibility.md)
-
-## Full example
-
-A “skip intro” button that appears during the first 30 seconds of playback and seeks past the intro when clicked.
-
-skip-intro-button.ts
-
-skip-intro-button.css
-
-```
-import {
-  UIElement,
-  PlayerController,
-  playerContext,
-  selectTime,
-  selectPlayback,
-  type PropertyValues,
-} from '@videojs/html';
-
-class SkipIntroButtonElement extends UIElement {
-  #time = new PlayerController(this, playerContext, selectTime);
-  #playback = new PlayerController(this, playerContext, selectPlayback);
-  #disconnect: AbortController | null = null;
-
-  connectedCallback() {
-    super.connectedCallback();
-    this.#disconnect?.abort();
-    this.#disconnect = new AbortController();
-    const { signal } = this.#disconnect;
-
-    this.setAttribute('role', 'button');
-    this.setAttribute('aria-label', 'Skip intro');
-    this.setAttribute('tabindex', '0');
-    this.addEventListener('click', this.#handleActivate, { signal });
-    this.addEventListener('keydown', this.#handleKeydown, { signal });
-    this.addEventListener('keyup', this.#handleKeyup, { signal });
-  }
-
-  disconnectedCallback() {
-    super.disconnectedCallback();
-    // Removes all listeners registered with this signal
-    this.#disconnect?.abort();
-    this.#disconnect = null;
-  }
-
-  update(changed: PropertyValues) {
-    super.update(changed);
-    const time = this.#time.value;
-    const playback = this.#playback.value;
-
-    // Features are configured per-player, so a feature may not be available
-    if (!time || !playback) return;
-
-    const visible = time.currentTime < 30 && !playback.paused;
-    this.toggleAttribute('data-visible', visible);
-    this.setAttribute('tabindex', visible ? '0' : '-1');
-  }
-
-  #handleActivate = () => {
-    this.#time.value?.seek(30);
-  };
-
-  #handleKeydown = (event: KeyboardEvent) => {
-    if (event.key === 'Enter') {
-      event.preventDefault();
-      this.#handleActivate();
-    } else if (event.key === ' ') {
-      // Prevent Space from scrolling the page
-      event.preventDefault();
-    }
-  };
-
-  // ARIA button pattern: Space activates on keyup, not keydown
-  #handleKeyup = (event: KeyboardEvent) => {
-    if (event.key === ' ') {
-      this.#handleActivate();
-    }
-  };
-}
-
-customElements.define('skip-intro-button', SkipIntroButtonElement);
-```
-
-```
-skip-intro-button {
-  position: absolute;
-  bottom: 5rem;
-  right: 1rem;
-  opacity: 0;
-  pointer-events: none;
-  transition: opacity 200ms;
-}
-
-skip-intro-button[data-visible] {
-  opacity: 1;
-  pointer-events: auto;
-}
-```
-
-Your element needs to be inside [`<video-player>`](../reference/player.md) to access state. Place it inside [`<media-container>`](../reference/player-container.md) if it should also participate in fullscreen and respond to user activity. `<video-skin>` slots its children into `<media-container>`, so a child of the skin works:
-
-html
-
-```
-<video-player>
-  <video-skin>
-    <video src="video.mp4"></video>
-    <skip-intro-button>Skip intro</skip-intro-button>
-  </video-skin>
-</video-player>
-<script type="module">
-  import '@videojs/html/video/skin';
-  import './skip-intro-button.js';
-</script>
-```
-
-## How it works
-
-Custom components read player state and dispatch actions through [features](../concepts/features.md). Each feature exposes a set. Here are some features you might reach for first:
-
-State
-
-Actions
-
-Feature
-
-`paused`, `ended`
-
-`play()`, `pause()`
-
-[Playback](../reference/feature-playback.md)
-
-`currentTime`, `duration`
-
-`seek()`
-
-[Time](../reference/feature-time.md)
-
-`volume`, `muted`
-
-`setVolume()`, `toggleMuted()`
-
-[Volume](../reference/feature-volume.md)
-
-`fullscreen`
-
-`requestFullscreen()`, `exitFullscreen()`
-
-[Fullscreen](../reference/feature-fullscreen.md)
-
-Browse the full list in the **Features** section of the sidebar.
-
-Extend `MediaElement` from `@videojs/html` so [`PlayerController`](../reference/player-controller.md) can schedule DOM updates when state changes, and access state and actions with a feature selector:
-
-ts
-
-```
-import { PlayerController, playerContext, selectPlayback } from '@videojs/html';
-
-// Subscribe to a feature — triggers update() when its state changes
-#playback = new PlayerController(this, playerContext, selectPlayback);
-
-// In update():
-const playback = this.#playback.value;
-if (playback?.paused) {
-  playback.play();
-}
-```
-
-Each selector returns both state and actions for that feature. Use separate controllers when you need multiple features (the [full example](#full-example) demonstrates this).
-
-Without a selector, `PlayerController` returns the full store without subscribing to changes. Create the controller with the typed context that [`createPlayer`](../reference/html-create-player.md) returns — the shared `playerContext` types the store’s members as `unknown` — and guard the value, which stays `undefined` until a player provides the store:
-
-ts
-
-```
-import { createPlayer, PlayerController } from '@videojs/html';
-import { videoFeatures } from '@videojs/html/video';
-
-const { context } = createPlayer({ features: videoFeatures });
-
-#store = new PlayerController(this, context);
-
-// Call any action
-this.#store.value?.play();
-this.#store.value?.setVolume(0.5);
-```
-
-Custom controls also need real button semantics — the examples above set the accessible name, keyboard focus, and (in HTML, where there is no native `<button>`) the ARIA button pattern by hand.
-
-- [Learn more about accessibility in video players](../concepts/accessibility.md)
-
-## Availability and constraints
-
-*   Features are configured per player, so a feature your component asks for may not be present. Selectors return `undefined` for a missing feature; guard the value before using it, as the example does.
-*   Volume, fullscreen, picture-in-picture, and remote playback also expose an `*Availability` property (`'available'`, `'unavailable'`, or `'unsupported'`) for hiding controls the platform does not support. See [Features](../concepts/features.md) for details.
-
-## Common variations
-
-Before building from scratch, check if an existing approach covers your use case. Build a custom component when you need new behavior, a new state display, or integration with an external system.
-
-### Restyle a control
-
-Use CSS custom properties and data attributes. See [UI components](../concepts/ui-components.md).
-
-### Rearrange or remove controls
-
-Eject a skin and modify it. See [Customize skins](./customize-skins.md#eject-and-edit-a-skin).
-
-## Troubleshooting
-
-### State and actions are typed as `unknown`
-
-You’re using the standalone `usePlayer` export or the shared `playerContext`, which don’t know which features your player has. In React, import `usePlayer` from your player’s preset (for example `@videojs/react/video`), or use the hook returned by `createPlayer` if you built the player with a custom feature set. In HTML, use the typed `context` returned by `createPlayer`.
-
-### The component renders but never updates
-
-In React, the component sits outside the player (such as `<VideoPlayer>`), so `usePlayer` has no store to subscribe to. In HTML, the element sits outside `<video-player>`, or the class doesn’t extend `MediaElement`, so `PlayerController` has nothing to schedule updates on.
-
-## Related API
-
-*   [usePlayer](/docs/framework/react/reference/use-player)
-*   [PlayerController](../reference/player-controller.md)
-*   [createPlayer](/docs/framework/react/reference/create-player)
-*   [Player container](../reference/player-container.md)
-
-## Related guides
-
-*   [Customize skins](./customize-skins.md)

package/docs/how-to/customize-skins.md

@@ -1,358 +0,0 @@
-# Customize skins
-
-Style a packaged Video.js skin or copy its source to change controls, layout, styles, and interactions
-
-Start with the path that matches the change you want:
-
-If you want to…
-
-Use this path
-
-Change colors, typography, sizing, or how the poster fills the player
-
-[Style a packaged skin](#style-a-packaged-skin). The skin stays in the Video.js package, and you set its supported CSS properties.
-
-Add, remove, rearrange, or deeply restyle controls; change layout or interactions
-
-[Eject and edit a skin](#eject-and-edit-a-skin). Ejecting copies the skin’s source files into your project so you can change them.
-
-## Style a packaged skin
-
-Use a packaged skin’s public settings to match it to your site without copying its source into your project.
-
-### Set the skin’s styles
-
-Packaged skins expose [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) for their supported visual changes. Set them on the skin or any element that contains it:
-
-html
-
-```
-<video-skin style="--media-accent-color: #f5c518; --media-border-radius: 1rem">
-  <video src="video.mp4"></video>
-</video-skin>
-```
-
-Property name
-
-What it changes
-
-Value
-
-Example
-
-`--media-accent-color`
-
-Slider fills, highlighted controls and menu items, and primary actions
-
-[`<color>`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)
-
-`#f5c518`
-
-`--media-accent-text-color`
-
-Text and icons shown on the accent color
-
-[`<color>`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)
-
-`black`
-
-`--media-border-color`
-
-The hairline around the player
-
-[`<color>`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)
-
-`transparent`
-
-`--media-border-radius`
-
-The player corner radius
-
-A valid [border-radius value](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/border-radius#values)
-
-`1rem`
-
-`--media-font-family`
-
-The player interface font stack
-
-A valid [font-family value](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/font-family)
-
-`Roboto, sans-serif`
-
-`--media-object-fit`
-
-How the media and poster fill the player
-
-A valid [object-fit value](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/object-fit)
-
-`cover`
-
-`--media-object-position`
-
-Where the media and poster sit when they do not fill the player
-
-A valid [object-position value](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/object-position)
-
-`top`
-
-`--media-scale-unit`
-
-The base size for skin spacing, icons, and text
-
-[`<length>`](https://developer.mozilla.org/en-US/docs/Web/CSS/length)
-
-`1rem`
-
-If you omit `--media-accent-text-color`, the skins choose a contrasting text color from `--media-accent-color` using [`contrast-color()`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/contrast-color). Set it only when you want a different result.
-
-The skins use [`Inter`](https://rsms.me/inter/) when your page loads it and fall back to the system UI font. Video.js does not load the webfont for you. Set `--media-font-family` to use another font.
-
-The media element and poster share `--media-object-fit` and `--media-object-position`, so a `cover` poster stays aligned with `cover` video. See [Add a poster and loading placeholder](./add-a-poster-and-loading-placeholder.md).
-
-### Set the color scheme
-
-The audio skins adapt their main palette for light and dark mode using [`light-dark()`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/light-dark). They read the inherited [`color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/color-scheme), so set it on the player or an element that contains it:
-
-css
-
-```
-:root {
-  color-scheme: light dark;
-}
-```
-
-The video skins keep their dark controls in both color schemes. Only their hairline border follows the scheme, and `--media-border-color` replaces it.
-
-### Scale from the document font size
-
-The skins derive control spacing, icon sizes, and text from `--media-scale-unit`. It defaults to `16px`, so the player does not change with the document root font size or your app’s Tailwind spacing scale. Set it to `1rem` to make the interface scale from the document root font size:
-
-css
-
-```
-.player {
-  --media-scale-unit: 1rem;
-}
-```
-
-In fullscreen, the skins increase the unit up to 1.75 times on displays 1920 pixels and wider. This keeps controls legible from a distance.
-
-You can also add your own class names to the skins.
-
-### Know where packaged styling stops
-
-The properties above are the public styling settings for packaged skins. Do not depend on the elements, class names, or other custom properties inside a packaged skin. They may change between releases.
-
-Packaged video skins also let you replace the poster through the `poster` slot.
-
-See [Poster](../reference/poster.md).
-
-Packaged skins do not provide settings for adding, removing, or rearranging controls, or for replacing built-in feedback and interactions. To make those changes, [eject the closest skin](#eject-and-edit-a-skin) and edit its source.
-
-## Eject and edit a skin
-
-If a packaged skin is close to the interface you want, eject it and edit the copy in your project. Ejecting turns the skin’s controls, layout, styles, and interactions into app code that you own.
-
-Video.js publishes the skin source in a catalog of installable files. The [`shadcn` CLI](https://ui.shadcn.com/docs/cli) is the command-line tool that copies those files into your project, whether you use React or HTML.
-
-Note
-
-Commit your work before installing or updating source. You can then review every file the CLI adds or replaces.
-
-### Set up the `shadcn` CLI
-
-If your project does not have a `components.json` configuration file, create one:
-
-npm
-
-pnpm
-
-yarn
-
-bun
-
-```
-npx shadcn@latest init
-```
-
-```
-pnpm dlx shadcn@latest init
-```
-
-```
-yarn dlx shadcn@latest init
-```
-
-```
-bunx --bun shadcn@latest init
-```
-
-### Choose how the skin is styled
-
-HTML skins use plain stylesheets, labeled Vanilla CSS. Each skin includes markup that renders directly in the page, a module that registers its custom elements, and a stylesheet.
-
-HTML skins install as vanilla CSS.
-
-### Connect the CLI to Video.js
-
-Run this command once. It saves `@videojs` as a short prefix in `components.json`, so later commands can use names such as `@videojs/video`:
-
-npm
-
-pnpm
-
-yarn
-
-bun
-
-```
-npx shadcn@latest registry add @videojs=https://shadcn.videojs.org/r/html/{name}.json
-```
-
-```
-pnpm dlx shadcn@latest registry add @videojs=https://shadcn.videojs.org/r/html/{name}.json
-```
-
-```
-yarn dlx shadcn@latest registry add @videojs=https://shadcn.videojs.org/r/html/{name}.json
-```
-
-```
-bunx --bun shadcn@latest registry add @videojs=https://shadcn.videojs.org/r/html/{name}.json
-```
-
-### Install a skin
-
-Install the skin closest to the interface you want. Default skins use the preset name, and Minimal skins add `-minimal`:
-
-npm
-
-pnpm
-
-yarn
-
-bun
-
-```
-npx shadcn@latest add @videojs/video
-```
-
-```
-pnpm dlx shadcn@latest add @videojs/video
-```
-
-```
-yarn dlx shadcn@latest add @videojs/video
-```
-
-```
-bunx --bun shadcn@latest add @videojs/video
-```
-
-Skin
-
-Install name
-
-Installs to
-
-Default Video
-
-`@videojs/video`
-
-`components/videojs/skins/video`
-
-Minimal Video
-
-`@videojs/video-minimal`
-
-`components/videojs/skins/video/minimal`
-
-Default Audio
-
-`@videojs/audio`
-
-`components/videojs/skins/audio`
-
-Minimal Audio
-
-`@videojs/audio-minimal`
-
-`components/videojs/skins/audio/minimal`
-
-Default Live Video
-
-`@videojs/live-video`
-
-`components/videojs/skins/live-video`
-
-Minimal Live Video
-
-`@videojs/live-video-minimal`
-
-`components/videojs/skins/live-video/minimal`
-
-Default Live Audio
-
-`@videojs/live-audio`
-
-`components/videojs/skins/live-audio`
-
-Minimal Live Audio
-
-`@videojs/live-audio-minimal`
-
-`components/videojs/skins/live-audio/minimal`
-
-The paths in the table start from the component location configured in `components.json`. The background video skin cannot be ejected.
-
-### Use the installed skin
-
-The skin’s files are under `components/videojs/skins/<preset>`. Keep importing the player and media from `@videojs/html`. Import the installed `skin.ts` once, then paste the markup from `skin.html` inside your player around the media element.
-
-### Edit the installed files
-
-Start with the file that owns the change you want:
-
-Goal
-
-Where to start
-
-Add, remove, or rearrange controls
-
-`skin.tsx` in React or `skin.html` in HTML
-
-Change colors, surfaces, shadows, sizes, or motion across the skin
-
-`components/videojs/styles/theme.css`
-
-Change one control’s appearance
-
-That control’s classes or stylesheet
-
-Change one control’s interaction
-
-That control’s module
-
-The `skin.html` file contains the layout. The `skin.ts` module registers the custom elements and loads `skin.css`. Elements use class names that start with `media-`; change a class in `skin.html` or a rule in the stylesheet to change one part of the interface.
-
-### Inspect or update an ejected skin
-
-Use the CLI’s `search` command to find source and `view` to inspect it before installation:
-
-bash
-
-```
-npx shadcn@latest search @videojs --query volume
-npx shadcn@latest view @videojs/video
-```
-
-Installed files belong to your project, so an update replaces your local copy. Commit your changes, reinstall with `--overwrite`, and review the resulting version-control diff before keeping it:
-
-bash
-
-```
-npx shadcn@latest add @videojs/video --overwrite
-```
-
-To understand how skins fit into Video.js, read [Skins](../concepts/skins.md). To create a control instead of editing one, follow [Build your own component](./build-your-own-component.md).