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

package/docs/concepts/overview.md

@@ -1,121 +0,0 @@
-# Overview
-
-How Video.js players are structured — state, UI, media, and extensions
-
-Video.js v10 separates player responsibilities into parts that work independently or together, so you can use as much or as little of Video.js as you need.
-
-For the reasoning behind this design, see [Why Video.js?](./why-videojs.md).
-
-## State management
-
-State is handled by a `video-player` element, which creates a central state store that all components can access. Child components can automatically connect to the state of the `video-player` element.
-
-html
-
-```
-<!-- All components inside automatically connect to state -->
-<video-player>
-  <video-skin>
-    <video src="video.mp4"></video>
-  </video-skin>
-</video-player>
-```
-
-You can access state and actions from anywhere within `<video-player>` with [`PlayerController`](../reference/player-controller.md).
-
-- [Learn more about state and actions](./features.md)
-
-## User interface
-
-Use a prebuilt **skin** or build your own from the individual **UI components**.
-
-### Skins
-
-Skins are complete, pre-designed player UIs that package components and styles together. They give you a polished starting point, with a small set of CSS custom properties for common visual changes. They don’t try to cover every player with options.
-
-html
-
-```
-<video-player>
-  <video-skin>
-    <video src="video.mp4"></video>
-  </video-skin>
-</video-player>
-```
-
-- [Learn more about skins](./skins.md)
-
-### UI components
-
-If you want more control than a packaged skin offers, build your own UI from our components. Add, remove, and rearrange them to build the player you need.
-
-html
-
-```
-<video-player>
-  <media-container>
-    <video src="video.mp4"></video>
-    <media-controls>
-      <media-controls-content>
-        <media-play-button></media-play-button>
-        <!-- ... -->
-      </media-controls-content>
-    </media-controls>
-  </media-container>
-</video-player>
-```
-
-The easiest way to get started is to [eject the closest skin](../how-to/customize-skins.md#eject-and-edit-a-skin) and use its styled components as a foundation.
-
-- [Learn more about UI components](./ui-components.md)
-- [Build your own component](../how-to/build-your-own-component.md)
-
-## Media
-
-Media components are the components that actually display your media. They’re essentially “players with no UI”. They handle the video/audio rendering and expose a consistent API.
-
-Media components can be format specific (HLS, DASH), service specific (YouTube, Vimeo, Mux), or use case specific (background video).
-
-Media elements are discovered automatically. Plain `<video>` and `<audio>` elements are found via a `querySelector`. Custom media elements like `<hlsjs-video>` register themselves after you import their registration entry point.
-
-html
-
-```
-<video-player>
-  <video-skin>
-    <hlsjs-video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"></hlsjs-video>
-  </video-skin>
-</video-player>
-```
-
-- [Learn more about media](./media-sources.md)
-
-## Extensions
-
-Extensions add behavior to a player without rendering UI or playing media themselves.
-
-html
-
-```
-<video-player>
-  <video-skin>
-    <mux-video src="https://stream.mux.com/PLAYBACK_ID.m3u8"></mux-video>
-    <mux-data></mux-data>
-    <google-cast></google-cast>
-  </video-skin>
-</video-player>
-```
-
-An extension can provide behavior that a UI component controls: GoogleCast supplies the configurable Cast route, and [CastButton](../reference/cast-button.md) renders the control that starts and ends a session.
-
-## Presets
-
-**Presets** preconfigure the state, UI, and media for a specific use case. Extensions stay opt-in, so add them to a preset player when you need them.
-
-The default presets are `@videojs/html/video` and `@videojs/html/audio`, covering the baseline set of controls you’d expect from the HTML `<video>` and `<audio>` tags.
-
-Beyond the defaults, presets target more specific use cases. The `/background` preset combines a media element with autoplay, mute, and loop built in, a skin with no controls, and only the features needed to power it.
-
-You can use it from the `@videojs/html/background/*` registration entry points.
-
-- [Learn more about presets](./presets.md)

package/docs/concepts/presets.md

@@ -1,225 +0,0 @@
-# Presets
-
-Pre-packaged player configurations that bundle state management, skins, and media elements for specific use cases.
-
-A **preset** packages what you need for a specific player use case. It can include special [state management](./features.md), one or more [skins](./skins.md) for UI, and specific media elements. Instead of assembling these pieces individually, you pick a preset that matches what you’re building.
-
-For example, the `@videojs/html/background` preset includes a media element with autoplay, mute, and loop built in, a skin with no controls, and just the features needed to power them:
-
-index.html
-
-```
-<script type="module">
-  import '@videojs/html/background/player';
-  import '@videojs/html/background/video';
-  import '@videojs/html/background/skin';
-</script>
-
-<background-video-player>
-  <background-video-skin>
-    <background-video src="hero.mp4"></background-video>
-  </background-video-skin>
-</background-video-player>
-```
-
-## Available presets
-
-The default presets are `/video` and `/audio`. These cover the baseline controls you’d expect from the HTML `<video>` and `<audio>` tags. Beyond the defaults, presets target more specific use cases — the `/background` preset, for example, needs layout but not controls. Over time we’ll add more: short-form players, podcast players, TV streaming players, and others.
-
-Import
-
-Description
-
-Details
-
-`@videojs/html/video`
-
-General-purpose video player preset with full playback controls.
-
-▸
-
-Feature bundle
-
-`videoFeatures`
-
-Features
-
-[playback](../reference/feature-playback.md), [playbackRate](../reference/feature-playback-rate.md), [quality](../reference/feature-quality.md), [audioTrack](../reference/feature-audio-track.md), [volume](../reference/feature-volume.md), [time](../reference/feature-time.md), [source](../reference/feature-source.md), [buffer](../reference/feature-buffer.md), [fullscreen](../reference/feature-fullscreen.md), [pip](../reference/feature-pip.md), [remotePlayback](../reference/feature-remote-playback.md), [controls](../reference/feature-controls.md), [textTrack](../reference/feature-text-tracks.md), [error](../reference/feature-error.md), [metadata](../reference/feature-metadata.md)
-
-Skins
-
-`<video-minimal-skin>`, `<video-skin>`
-
-Default media element
-
-`<video>`
-
-`@videojs/html/audio`
-
-Audio-only player preset with playback and volume controls.
-
-▸
-
-Feature bundle
-
-`audioFeatures`
-
-Features
-
-[playback](../reference/feature-playback.md), [playbackRate](../reference/feature-playback-rate.md), [volume](../reference/feature-volume.md), [time](../reference/feature-time.md), [source](../reference/feature-source.md), [buffer](../reference/feature-buffer.md), [error](../reference/feature-error.md), [metadata](../reference/feature-metadata.md)
-
-Skins
-
-`<audio-minimal-skin>`, `<audio-skin>`
-
-Default media element
-
-`<audio>`
-
-`@videojs/html/background`
-
-Ambient background video preset with no user controls.
-
-▸
-
-Feature bundle
-
-`backgroundFeatures`
-
-Features
-
-–
-
-Skins
-
-`<background-video-skin>`
-
-Default media element
-
-`<background-video>`
-
-`@videojs/html/live-audio`
-
-Live audio player preset — `audio` minus playback rate, plus the live feature, with a skin that swaps the time slider and time displays for a Live button.
-
-▸
-
-Feature bundle
-
-`liveAudioFeatures`
-
-Features
-
-[playback](../reference/feature-playback.md), [volume](../reference/feature-volume.md), [time](../reference/feature-time.md), [source](../reference/feature-source.md), [buffer](../reference/feature-buffer.md), [error](../reference/feature-error.md), [live](../reference/feature-live.md), [metadata](../reference/feature-metadata.md)
-
-Skins
-
-`<live-audio-minimal-skin>`, `<live-audio-skin>`
-
-Default media element
-
-`<audio>`
-
-`@videojs/html/live-video`
-
-Live video player preset — `video` minus playback rate, quality selection, and audio-track selection, plus the live feature, with a skin that swaps the time slider and time displays for a Live button.
-
-▸
-
-Feature bundle
-
-`liveVideoFeatures`
-
-Features
-
-[playback](../reference/feature-playback.md), [volume](../reference/feature-volume.md), [time](../reference/feature-time.md), [source](../reference/feature-source.md), [buffer](../reference/feature-buffer.md), [fullscreen](../reference/feature-fullscreen.md), [pip](../reference/feature-pip.md), [remotePlayback](../reference/feature-remote-playback.md), [controls](../reference/feature-controls.md), [textTrack](../reference/feature-text-tracks.md), [error](../reference/feature-error.md), [live](../reference/feature-live.md), [metadata](../reference/feature-metadata.md)
-
-Skins
-
-`<live-video-minimal-skin>`, `<live-video-skin>`
-
-Default media element
-
-`<video>`
-
-## What’s in a preset
-
-Each HTML preset provides registration entry points for a preconfigured player element, its skins, and any preset-specific media element, plus the feature bundle needed to compose your own player. For example, `@videojs/html/video/player` registers `<video-player>`, while `@videojs/html/video/skin` registers `<video-skin>`.
-
-These parts aren’t equally tied together. Skins depend tightly on their feature bundle — a skin expects specific features to exist. Media elements are more interchangeable — you can swap in an HLS or DASH provider without changing your skin or features.
-
-HTML preset roots are side-effect-free modules for importing the configured classes, typed controller, and feature bundle:
-
-ts
-
-```
-import {
-  PlayerController,
-  VideoPlayerElement,
-  VideoSkinElement,
-  videoFeatures,
-} from '@videojs/html/video';
-```
-
-Registration is explicit, so importing a value never changes the custom element registry. Registration entry points are side-effect-only; import classes, controllers, and types from the preset root:
-
-ts
-
-```
-import '@videojs/html/video/player'; // <video-player> only
-import '@videojs/html/video/skin';   // <video-skin> + container + video UI
-// Import '@videojs/html/video/minimal-skin' instead for the minimal skin.
-```
-
-A complete player imports `video/player` and one skin. Each skin registration includes its container and UI dependencies but does not register the player.
-
-## Customizing a preset
-
-You can customize a preset in three ways: extend its feature bundle, eject its skin, or swap its media element.
-
-### Extend the feature bundle
-
-Add features to a preset’s feature bundle to enable new functionality. For example, adding playback controls to a background video:
-
-index.html
-
-```
-<script type="module">
-  import { createPlayer, playbackFeature } from '@videojs/html';
-  import { backgroundFeatures } from '@videojs/html/background';
-  import '@videojs/html/background/video';
-  import '@videojs/html/ui/container';
-  import '@videojs/html/ui/play-button';
-
-  const { PlayerElement: MyPlayer } = createPlayer({
-    features: [...backgroundFeatures, playbackFeature],
-  });
-
-  customElements.define('my-player', MyPlayer);
-</script>
-
-<my-player>
-  <media-container>
-    <background-video src="hero.mp4"></background-video>
-    <media-play-button>Play / Pause</media-play-button>
-  </media-container>
-</my-player>
-```
-
-### Eject the skin
-
-If a preset’s skin is close but not quite right, [eject it](../how-to/customize-skins.md#eject-and-edit-a-skin) and customize its components and styles.
-
-### Swap the media element
-
-A preset’s default media element is just the starting point. You can replace it with any compatible media provider. For example, using an HLS source with the video preset:
-
-html
-
-```
-<video-player>
-  <video-skin>
-    <hlsjs-video src="https://example.com/stream.m3u8"></hlsjs-video>
-  </video-skin>
-</video-player>
-```

package/docs/concepts/security.md

@@ -1,32 +0,0 @@
-# Security
-
-How to configure Content Security Policy for your video player
-
-Content Security Policy (CSP) limits which resources a page can load. Video.js uses the URLs you configure for media, posters, thumbnails, and captions. Some HLS renderers also create blob URLs or web workers, so your policy must allow those resources too.
-
-## Allow player resources
-
-*   `media-src` must allow your media URLs.
-*   `img-src` must allow any poster or thumbnail image URLs.
-*   `connect-src` must allow HLS manifests, playlists, captions, and segment requests when using HLS playback.
-*   `media-src blob:` is required when using the HLS player variants, which use MSE-backed playback.
-*   `worker-src blob:` is required when using the `hls.js` player variants.
-*   `style-src 'unsafe-inline'` is required for some player UI and HTML player styling behavior.
-
-## Example
-
-http
-
-```
-Content-Security-Policy:
-  script-src 'self';
-  style-src 'self' 'unsafe-inline';
-  img-src 'self' https: data: blob:;
-  media-src 'self' https: blob:;
-  connect-src 'self' https:;
-  worker-src 'self' blob:;
-```
-
-This policy assumes you bundle Video.js with your application or serve it from your own origin. If you load the player from a CDN, add that CDN’s origin to `script-src`.
-
-Replace broad sources such as `https:` with the exact origins your player uses. Remove sources your deployment does not need, and keep `blob:` only where your selected HLS renderer requires it.

package/docs/concepts/skins.md

@@ -1,188 +0,0 @@
-# Skins
-
-Packaged player designs that include both UI components and their styles.
-
-New in version 10
-
-In prior versions of Video.js, skins were CSS-only themes applied to the same set of default controls. In version 10 the concept of skins has been expanded to include the UI components, so each skin can be completely unique and only include the UI components it needs.
-
-A skin wraps the media component and provides the player’s complete interface. It combines a specific set of UI components with the styles that arrange and present them.
-
-## Packaged and ejected skins
-
-When you choose a skin you have two options for how you use it: **packaged** or **ejected**. It’s usually easiest to start with a packaged skin and later eject its internal components into your project when you need more customization.
-
-Packaged skins cover common visual changes through documented CSS custom properties. Packaged video skins also let you replace the poster. When you need more than that, eject the skin and change the components and styles directly.
-
-Packaged skin
-
-Ejected skin
-
-Single component
-
-Many UI components
-
-Documented CSS custom properties
-
-Components and styles you own
-
-Future design updates auto-applied by bumping the version
-
-Future design updates manually applied, or intentionally ignored
-
-### Packaged skin
-
-html
-
-```
-<script type="module">
-  import '@videojs/html/video/player';
-  import '@videojs/html/video/skin';
-</script>
-
-<video-player>
-  <video-skin>
-    <video src="video.mp4"></video>
-  </video-skin>
-</video-player>
-```
-
-Don’t depend on elements, class names, or undocumented custom properties inside a packaged skin. They may change between releases.
-
-- [Style a packaged skin](../how-to/customize-skins.md#style-a-packaged-skin)
-
-### Ejected skin
-
-An ejected skin is the same skin as app code that you own. Its UI components and styles become files in your project, so you can add, remove, rearrange, or restyle any part of it.
-
-- [Eject and edit a skin](../how-to/customize-skins.md#eject-and-edit-a-skin)
-
-### Custom interface
-
-You can also build an interface without starting from a skin. In that model, you choose and arrange individual [UI components](./ui-components.md) around the media. This takes more work, but it avoids inheriting a skin’s layout and interactions.
-
-- [Build your own component](../how-to/build-your-own-component.md)
-
-## Skins, features, and presets
-
-Each skin is built with specific [features](./features.md) in mind. For example, a video skin renders fullscreen and picture-in-picture controls. An audio skin doesn’t.
-
-You’ll find a preconfigured player, its typed hook, a skin, and the matching feature bundle exported from the same path. We call these paths **presets**.
-
-Import
-
-Description
-
-Details
-
-`@videojs/html/video`
-
-General-purpose video player preset with full playback controls.
-
-▸
-
-Feature bundle
-
-`videoFeatures`
-
-Features
-
-[playback](../reference/feature-playback.md), [playbackRate](../reference/feature-playback-rate.md), [quality](../reference/feature-quality.md), [audioTrack](../reference/feature-audio-track.md), [volume](../reference/feature-volume.md), [time](../reference/feature-time.md), [source](../reference/feature-source.md), [buffer](../reference/feature-buffer.md), [fullscreen](../reference/feature-fullscreen.md), [pip](../reference/feature-pip.md), [remotePlayback](../reference/feature-remote-playback.md), [controls](../reference/feature-controls.md), [textTrack](../reference/feature-text-tracks.md), [error](../reference/feature-error.md), [metadata](../reference/feature-metadata.md)
-
-Skins
-
-`<video-minimal-skin>`, `<video-skin>`
-
-Default media element
-
-`<video>`
-
-`@videojs/html/audio`
-
-Audio-only player preset with playback and volume controls.
-
-▸
-
-Feature bundle
-
-`audioFeatures`
-
-Features
-
-[playback](../reference/feature-playback.md), [playbackRate](../reference/feature-playback-rate.md), [volume](../reference/feature-volume.md), [time](../reference/feature-time.md), [source](../reference/feature-source.md), [buffer](../reference/feature-buffer.md), [error](../reference/feature-error.md), [metadata](../reference/feature-metadata.md)
-
-Skins
-
-`<audio-minimal-skin>`, `<audio-skin>`
-
-Default media element
-
-`<audio>`
-
-`@videojs/html/background`
-
-Ambient background video preset with no user controls.
-
-▸
-
-Feature bundle
-
-`backgroundFeatures`
-
-Features
-
-–
-
-Skins
-
-`<background-video-skin>`
-
-Default media element
-
-`<background-video>`
-
-`@videojs/html/live-audio`
-
-Live audio player preset — `audio` minus playback rate, plus the live feature, with a skin that swaps the time slider and time displays for a Live button.
-
-▸
-
-Feature bundle
-
-`liveAudioFeatures`
-
-Features
-
-[playback](../reference/feature-playback.md), [volume](../reference/feature-volume.md), [time](../reference/feature-time.md), [source](../reference/feature-source.md), [buffer](../reference/feature-buffer.md), [error](../reference/feature-error.md), [live](../reference/feature-live.md), [metadata](../reference/feature-metadata.md)
-
-Skins
-
-`<live-audio-minimal-skin>`, `<live-audio-skin>`
-
-Default media element
-
-`<audio>`
-
-`@videojs/html/live-video`
-
-Live video player preset — `video` minus playback rate, quality selection, and audio-track selection, plus the live feature, with a skin that swaps the time slider and time displays for a Live button.
-
-▸
-
-Feature bundle
-
-`liveVideoFeatures`
-
-Features
-
-[playback](../reference/feature-playback.md), [volume](../reference/feature-volume.md), [time](../reference/feature-time.md), [source](../reference/feature-source.md), [buffer](../reference/feature-buffer.md), [fullscreen](../reference/feature-fullscreen.md), [pip](../reference/feature-pip.md), [remotePlayback](../reference/feature-remote-playback.md), [controls](../reference/feature-controls.md), [textTrack](../reference/feature-text-tracks.md), [error](../reference/feature-error.md), [live](../reference/feature-live.md), [metadata](../reference/feature-metadata.md)
-
-Skins
-
-`<live-video-minimal-skin>`, `<live-video-skin>`
-
-Default media element
-
-`<video>`
-
-- [Read about presets](./presets.md)

package/docs/concepts/typescript.md

@@ -1,34 +0,0 @@
-# TypeScript
-
-TypeScript version and module resolution requirements for Video.js packages
-
-Video.js packages require **TypeScript 5.0 or newer**. TypeScript must also follow the import paths that each package publishes.
-
-## TypeScript version
-
-Video.js type files use syntax introduced in TypeScript 5.0. Older versions cannot read that syntax. The `skipLibCheck` option does not help because TypeScript must read a type file before it can skip checking it.
-
-## Module resolution
-
-Video.js packages define their supported import paths using [package exports](./bundlers.md). Most web applications should use the following configuration. It makes TypeScript follow the same package rules as the bundler that builds the application:
-
-tsconfig.json
-
-```
-{
-  "compilerOptions": {
-    "module": "ESNext",
-    "moduleResolution": "bundler"
-  }
-}
-```
-
-If Node.js runs files emitted directly by TypeScript, use `node16` for both `module` and `moduleResolution`, or use `nodenext` for both.
-
-Do not use the older `node` setting, now called `node10`. It does not understand package exports and can report valid Video.js imports or types as missing.
-
-## Errors from other dependencies
-
-The older `node` setting allowed applications to import almost any file inside a dependency. Modern settings allow only the paths that dependency publishes. Changing the setting can therefore reveal an existing import into another package’s private files.
-
-If the error names a package outside `@videojs/*`, update that dependency or use one of its supported import paths. A TypeScript `paths` override can be a temporary bridge when no supported replacement exists. Do not switch back to the older resolver because that also breaks Video.js type resolution.

package/docs/concepts/ui-components.md

@@ -1,81 +0,0 @@
-# UI components
-
-How Video.js UI components use focused elements, data attributes for state, and compound composition.
-
-UI components are controls like buttons, sliders, and time displays.
-
-Visible UI components render at most one HTML element, taking inspiration from projects like [shadcn/ui](https://ui.shadcn.com/) and [Base UI](https://base-ui.com/). This approach gives you control over styling and behavior while handling the complex interactions for you. State-only components render no markup, and controls can skip rendering when their feature is unavailable.
-
-Individual controls provide interaction, accessible names, and state. You add their visible text or icons and CSS. Sliders also need the child elements and styles shown on their reference pages.
-
-## Where to put your components
-
-UI components can go anywhere inside a [`<video-player>`](../reference/player.md).
-
-However, you should consider placing your components in `<media-container>`. Components in `<media-container>` will go fullscreen with the player, respond to user activity, and more.
-
-- [Read more about <media-container>](../reference/player-container.md)
-
-## Styling and customization
-
-For components you add yourself, select them by their custom element name. Use the documented state `data-*` attributes and CSS custom properties to style them.
-
-### Add icons
-
-Import `@videojs/html/icons/element` once in your `app.ts` to register `<media-icon>`. Choose an icon with `name`. Set `family="minimal"` to use the Minimal skin’s icon designs. You can also use your own text or SVG.
-
-ts
-
-```
-import '@videojs/html/icons/element';
-```
-
-html
-
-```
-<media-play-button class="my-play-button">
-  <media-icon class="play-icon" name="play"></media-icon>
-  <media-icon class="pause-icon" name="pause"></media-icon>
-</media-play-button>
-```
-
-### Style components with state
-
-Components add `data-*` attributes to describe their current state. For example, a play button adds `data-paused` while the media is paused. Use those attributes in CSS:
-
-css
-
-```
-.my-play-button .pause-icon {
-  display: none;
-}
-
-.my-play-button:defined:not([data-paused]) .play-icon {
-  display: none;
-}
-
-.my-play-button:defined:not([data-paused]) .pause-icon {
-  display: inline-flex;
-}
-```
-
-The browser matches `:defined` after it loads the custom element. This keeps the play icon visible while JavaScript loads.
-
-Each component’s reference page documents its full set of data attributes.
-
-Some components also expose **CSS custom properties** for continuous values like fill percentage and pointer position. Sliders, for example, set `--media-slider-fill` and `--media-slider-pointer`. See individual component reference pages for specifics.
-
-## Compound components
-
-Complex interactions are split into composable parts. A parent manages shared state while children consume it. Each visible part owns at most one element.
-
-html
-
-```
-<media-volume-slider orientation="vertical">
-  <media-slider-track>
-    <media-slider-fill></media-slider-fill>
-  </media-slider-track>
-  <media-slider-thumb></media-slider-thumb>
-</media-volume-slider>
-```