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

package/docs/guides/quality.md

@@ -0,0 +1,268 @@
+# Add a quality selector
+
+Read available renditions, let the engine adapt automatically, and offer manual quality selection.
+
+Quality selection applies to streaming sources. A progressive MP4 plays at one fixed quality and exposes no renditions; HLS and DASH streams offer several. See [Media sources](./media-sources.md).
+
+> **Note**
+>
+> Using a pre-built [skin](./skins.md)? It already includes the controls shown here. You may still need the media or player setup in this guide. The component examples are for building your own player UI from individual [components](./ui-components.md).
+
+## Installation
+
+This guide uses the hls.js media component, so install its adapter with the framework façade:
+
+```bash
+pnpm add @videojs/react @videojs/hlsjs-video
+```
+
+## Recommended approach
+
+Let automatic quality selection do its job by default, and offer a quality menu for users who want to pin a rendition. Render the menu only when quality selection is available.
+
+**App.tsx**
+
+```tsx
+import { Container, createPlayer, Menu } from '@videojs/react';
+import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
+import { QualityRadioGroup } from '@videojs/react/ui/quality-radio-group';
+import { videoFeatures } from '@videojs/react/video';
+import type { ReactNode } from 'react';
+
+const { Player } = createPlayer({ features: videoFeatures });
+const src = 'https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4.m3u8';
+
+function QualityMenu(): ReactNode {
+  return (
+    <Menu.Root side="top" align="end">
+      <QualityRadioGroup.Root>
+        <Menu.Trigger className="settings-trigger" render={<button type="button" />}>
+          Quality
+          <QualityRadioGroup.Value className="menu-hint" />
+        </Menu.Trigger>
+        <Menu.Popup className="menu">
+          <Menu.Content>
+            <QualityRadioGroup.Options
+              className="menu-group"
+              renderItem={(props, item) => (
+                <Menu.RadioItem {...props} className="menu-item">
+                  <span>
+                    {item.label}
+                    {item.tier ? <sup className="menu-tier">{item.tier}</sup> : null}
+                  </span>
+                  {item.badge ? <span className="menu-badge">{item.badge}</span> : null}
+                  <Menu.ItemIndicator checked={item.checked} forceMount className="menu-indicator">
+                    ✓
+                  </Menu.ItemIndicator>
+                </Menu.RadioItem>
+              )}
+            />
+          </Menu.Content>
+        </Menu.Popup>
+      </QualityRadioGroup.Root>
+    </Menu.Root>
+  );
+}
+
+export default function BasicUsage() {
+  return (
+    <Player>
+      <Container className="media-container">
+        <HlsJsVideo src={src} autoPlay crossOrigin="anonymous" muted playsInline loop />
+        <div className="menu-bar">
+          <QualityMenu />
+        </div>
+      </Container>
+    </Player>
+  );
+}
+```
+
+**App.css**
+
+```css
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.menu-bar {
+  position: absolute;
+  right: 10px;
+  bottom: 10px;
+}
+
+.settings-trigger {
+  padding: 6px 16px;
+  color: black;
+  cursor: pointer;
+  background: rgba(255, 255, 255, 0.75);
+  border: 1px solid rgba(255, 255, 255, 0.35);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+
+.menu-hint {
+  margin-left: 8px;
+  color: rgba(0, 0, 0, 0.6);
+}
+
+.menu-hint:empty {
+  display: none;
+}
+
+.menu {
+  --media-menu-side-offset: 8px;
+  box-sizing: border-box;
+  display: grid;
+  gap: 2px;
+  min-width: 180px;
+  max-width: var(--media-menu-available-width, var(--media-popover-available-width, none));
+  max-height: var(--media-menu-available-height, var(--media-popover-available-height, none));
+  padding: 6px;
+  margin: 0;
+  overflow: auto;
+  overscroll-behavior: none;
+  font-size: 14px;
+  color: white;
+  background: rgba(0, 0, 0, 0.88);
+  border: 0;
+  border-radius: 8px;
+  backdrop-filter: blur(10px);
+}
+
+.menu-group {
+  display: grid;
+  gap: 2px;
+}
+
+.menu-item {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  justify-content: space-between;
+  min-height: 32px;
+  padding: 0 10px;
+  font: inherit;
+  color: inherit;
+  cursor: pointer;
+  background: none;
+  border: 0;
+  border-radius: 6px;
+}
+
+.menu-item[data-highlighted] {
+  background: rgba(255, 255, 255, 0.16);
+}
+
+.menu-tier {
+  margin-left: 2px;
+  font-size: 10px;
+}
+
+.menu-badge {
+  margin-left: auto;
+  color: rgba(255, 255, 255, 0.72);
+}
+
+.menu-indicator {
+  opacity: 0;
+}
+
+[role="menuitemradio"][aria-checked="true"] .menu-indicator {
+  opacity: 1;
+}
+```
+
+## How it works
+
+The [quality feature](../reference/api/feature-quality.md) mirrors the media element’s video renditions into player state:
+
+- `videoRenditionList` holds each rendition’s `id`, `width`, `height`, `bitrate`, `frameRate`, `codec`, and whether it’s `selected`.
+- `activeVideoRendition` is the rendition currently playing. When the engine doesn’t report one directly, the player matches it from the video’s current dimensions.
+- `selectVideoRendition(value)` pins one rendition; pass `'auto'` to return control to the engine’s adaptive selection.
+
+[`useQualityOptions`](../reference/api/use-quality-options.md) turns this state into ready-made menu options — labels like “1080p”, an “Auto” entry, and `availability` — as the example above shows.
+
+Selecting “Auto” keeps adaptive bitrate switching active: the engine picks the best rendition for current bandwidth and viewport. Pinning a rendition disables adaptation until the user selects “Auto” again.
+
+## Availability and constraints
+
+- Quality availability is `'unavailable'` for media that doesn’t offer a choice — progressive files, streams before the manifest loads, and single-rendition streams. Render quality UI conditionally on that value.
+- Renditions come from the streaming engine, so the list depends on what the manifest declares. A single-rendition stream offers no meaningful selection, so availability stays `'unavailable'`.
+- Pinning a high rendition on a slow connection causes buffering: the engine can no longer step down. Keep “Auto” the default.
+- Rendition lists change on source change; selection resets with them.
+
+## Common variations
+
+### Auto quality only
+
+If you don’t want to expose manual selection, do nothing: adaptive selection is on by default and needs no UI.
+
+### Cap or pin quality programmatically
+
+```tsx
+import { Container } from '@videojs/react';
+import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
+import { usePlayer, VideoPlayer } from '@videojs/react/video';
+
+function PinLowestRendition() {
+  const store = usePlayer();
+  const renditions = usePlayer((s) => s.videoRenditionList);
+
+  const lowest = [...renditions].sort((a, b) => (a.height ?? 0) - (b.height ?? 0))[0];
+
+  return (
+    <button type="button" onClick={() => lowest?.id && store.selectVideoRendition(lowest.id)}>
+      Data saver
+    </button>
+  );
+}
+
+export default function App() {
+  return (
+    <VideoPlayer>
+      <Container>
+        <HlsJsVideo src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" muted playsInline />
+        <PinLowestRendition />
+      </Container>
+    </VideoPlayer>
+  );
+}
+```
+
+## Troubleshooting
+
+### The quality menu doesn’t render
+
+Quality availability is `'unavailable'`. The source is progressive (no renditions), the manifest hasn’t loaded yet, or the media element doesn’t support renditions. Use a streaming media element such as [HlsVideo](../reference/components/hls-video.md) or [HlsJsVideo](../reference/components/hlsjs-video.md).
+
+### The menu doesn’t render for a single-rendition stream
+
+The manifest declares a single rendition, so quality availability stays `'unavailable'` — one entry offers no choice. Encode the stream as a multi-rendition ladder to give the engine and users something to choose between.
+
+### Playback buffers after selecting a quality
+
+The pinned rendition exceeds available bandwidth. Selecting “Auto” lets the engine step down again.
+
+## Related pages
+
+### Components
+
+- [QualityRadioGroup](../reference/components/quality-radio-group.md): A menu radio group for selecting video quality
+- [Menu](../reference/components/menu.md): A composable menu component for settings, option selection, and actions
+
+### API
+
+- [Quality](../reference/api/feature-quality.md): Video rendition state and actions for the player store
+- [useQualityOptions](../reference/api/use-quality-options.md): Hook to build video quality menu options from the player rendition state
+- [HlsVideo](../reference/components/hls-video.md): Lightweight HLS video element with minimal bundle size
+- [HlsJsVideo](../reference/components/hlsjs-video.md): HLS video element powered by hls.js for adaptive bitrate streaming
+- [DashVideo](../reference/components/dash-video.md): DASH video element powered by dash.js for adaptive bitrate streaming
+
+### Guides
+
+- [Media sources](./media-sources.md): Set what a media element plays and how its engine plays it with the structured source property

package/docs/guides/skins.md

@@ -0,0 +1,72 @@
+# Skins
+
+Packaged player designs that include both UI components and their styles.
+
+> **Note: 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 skins and skin source
+
+When you choose a skin, you can import the packaged version or add its source to your project. It’s usually easiest to start with a packaged skin and add its source 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, add the skin source to your project and change the components and styles directly.
+
+| Packaged skin | Skin source in your project |
+| --- | --- |
+| Single component | Many UI components |
+| Documented CSS custom properties | Editable components and styles |
+| Future design updates auto-applied by bumping the version | Future design updates manually applied, or intentionally ignored |
+
+### Packaged skin
+
+**Player.tsx**
+
+```tsx
+import { Video, VideoPlayer, VideoSkin } from '@videojs/react/video';
+import '@videojs/react/video/skin.css';
+
+export function Player() {
+  return (
+    <VideoPlayer>
+      <VideoSkin>
+        <Video src="video.mp4" />
+      </VideoSkin>
+    </VideoPlayer>
+  );
+}
+```
+
+Don’t depend on elements, class names, or undocumented custom properties inside a packaged skin. They may change between releases.
+
+- [Style a packaged skin](./customize-skins.md#style-a-packaged-skin)
+
+### Skin source in your project
+
+The skin source contains the complete interface. You can add, remove, rearrange, or restyle any part of it.
+
+- [Style skin source](./customize-skins.md#style-skin-source)
+
+### 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](./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/react/video` | General-purpose video player preset with full playback controls. | **Feature bundle:** `videoFeatures`; **Features:** [playback](../reference/api/feature-playback.md), [playbackRate](../reference/api/feature-playback-rate.md), [quality](../reference/api/feature-quality.md), [audioTrack](../reference/api/feature-audio-track.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [fullscreen](../reference/api/feature-fullscreen.md), [pip](../reference/api/feature-pip.md), [remotePlayback](../reference/api/feature-remote-playback.md), [controls](../reference/api/feature-controls.md), [textTrack](../reference/api/feature-text-tracks.md), [error](../reference/api/feature-error.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<MinimalVideoSkin>` with `import '@videojs/react/video/minimal-skin.css';`, `<VideoSkin>` with `import '@videojs/react/video/skin.css';`; **Default media element:** `<Video>` |
+| `@videojs/react/audio` | Audio-only player preset with playback and volume controls. | **Feature bundle:** `audioFeatures`; **Features:** [playback](../reference/api/feature-playback.md), [playbackRate](../reference/api/feature-playback-rate.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [error](../reference/api/feature-error.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<MinimalAudioSkin>` with `import '@videojs/react/audio/minimal-skin.css';`, `<AudioSkin>` with `import '@videojs/react/audio/skin.css';`; **Default media element:** `<Audio>` |
+| `@videojs/react/background` | Ambient background video preset with no user controls. | **Feature bundle:** `backgroundFeatures`; **Features:** –; **Skins:** `<BackgroundVideoSkin>` with `import '@videojs/react/background/skin.css';`; **Default media element:** `<BackgroundVideo>` |
+| `@videojs/react/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/api/feature-playback.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [error](../reference/api/feature-error.md), [live](../reference/api/feature-live.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<MinimalLiveAudioSkin>` with `import '@videojs/react/live-audio/minimal-skin.css';`, `<LiveAudioSkin>` with `import '@videojs/react/live-audio/skin.css';`; **Default media element:** `<Audio>` |
+| `@videojs/react/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/api/feature-playback.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [fullscreen](../reference/api/feature-fullscreen.md), [pip](../reference/api/feature-pip.md), [remotePlayback](../reference/api/feature-remote-playback.md), [controls](../reference/api/feature-controls.md), [textTrack](../reference/api/feature-text-tracks.md), [error](../reference/api/feature-error.md), [live](../reference/api/feature-live.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<MinimalLiveVideoSkin>` with `import '@videojs/react/live-video/minimal-skin.css';`, `<LiveVideoSkin>` with `import '@videojs/react/live-video/skin.css';`; **Default media element:** `<Video>` |
+
+- [Read about presets](./presets.md)

package/docs/guides/thumbnails.md

@@ -0,0 +1,179 @@
+# Show timeline thumbnail previews
+
+Preview frames along the timeline while the user scrubs, powered by a storyboard track.
+
+Show preview frames along the timeline while the user scrubs, like YouTube’s seek previews.
+
+> **Tip: Using Mux?**
+>
+> With [MuxVideo](../reference/components/mux-video.md), the storyboard track is wired up for you — skip adding the track and go straight to the slider thumbnail. For other services, generate the storyboard on their platform and add the track yourself.
+
+> **Note**
+>
+> Using a pre-built [skin](./skins.md)? It already includes the controls shown here. You may still need the media or player setup in this guide. The component examples are for building your own player UI from individual [components](./ui-components.md).
+
+## Recommended approach
+
+Add a `kind="metadata"` track labeled `thumbnails` whose cues reference storyboard images, then put a slider thumbnail inside the [TimeSlider](../reference/components/time-slider.md). Scrubbing shows the frame under the pointer. The slider thumbnail reads the pointer time from the slider, so you never pass `time`; it otherwise accepts the same props as the standalone [Thumbnail](../reference/components/thumbnail.md).
+
+Compose `Slider.Thumbnail.Root` around `Slider.Thumbnail.Image`, and put image settings such as `crossOrigin`, `loading`, and `fetchPriority` on the image part. Inside a packaged skin, pass `renderThumbnail` to draw the image yourself; the skin still supplies `src` and sizing:
+
+```tsx
+<VideoSkin renderThumbnail={<img alt="" loading="lazy" fetchPriority="low" />} />
+```
+
+**App.tsx**
+
+```tsx
+import { Container, createPlayer, Slider, TimeSlider } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+export default function BasicUsage() {
+  return (
+    <Player>
+      <Container className="media-container">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop crossOrigin="anonymous">
+          <track kind="metadata" label="thumbnails" src="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.vtt" default />
+        </Video>
+        <TimeSlider.Root className="media-time-slider">
+          <TimeSlider.Track className="media-slider-track">
+            <TimeSlider.Fill className="media-slider-fill" />
+          </TimeSlider.Track>
+          <Slider.Thumbnail.Root className="media-slider-thumbnail">
+            <Slider.Thumbnail.Image className="media-slider-thumbnail-image" />
+          </Slider.Thumbnail.Root>
+        </TimeSlider.Root>
+      </Container>
+    </Player>
+  );
+}
+```
+
+**App.css**
+
+```css
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.media-time-slider {
+  position: absolute;
+  right: 10px;
+  bottom: 6px;
+  left: 10px;
+  display: flex;
+  align-items: center;
+  height: 20px;
+  cursor: pointer;
+}
+
+.media-slider-track {
+  position: absolute;
+  right: 0;
+  left: 0;
+  height: 4px;
+  background: rgba(255, 255, 255, 0.3);
+  border-radius: 9999px;
+  transition: height 150ms ease;
+}
+
+.media-time-slider[data-interactive] .media-slider-track {
+  height: 6px;
+}
+
+.media-slider-fill {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: var(--media-slider-fill);
+  height: 100%;
+  background: white;
+  border-radius: 9999px;
+}
+
+/* Reveal the preview over the pointer while it is on the slider. */
+.media-slider-thumbnail {
+  position: absolute;
+  bottom: 100%;
+  left: var(--media-slider-pointer);
+  max-width: 160px;
+  margin-bottom: 8px;
+  pointer-events: none;
+  border-radius: 4px;
+  opacity: 0;
+  transform: translateX(-50%);
+  transition: opacity 150ms ease;
+}
+
+.media-time-slider[data-pointing] .media-slider-thumbnail {
+  opacity: 1;
+}
+
+.media-slider-thumbnail[data-hidden] {
+  display: none;
+}
+
+.media-slider-thumbnail-image {
+  display: block;
+}
+```
+
+## How it works
+
+- Previews come from a storyboard: a `kind="metadata"` text track labeled `thumbnails` whose WebVTT cues map time ranges to image URLs (optionally with sprite coordinates). The [text track feature](../reference/api/feature-text-tracks.md) exposes these as `thumbnailCues` and `thumbnailTrackSrc`.
+- The slider thumbnail renders the storyboard frame for the slider’s pointer position. While the pointer is over the slider, the slider sets `data-pointing` and the `--media-slider-pointer` CSS variable; the example’s CSS uses them to reveal the preview and position it over the pointer.
+- To render a storyboard frame outside the slider — a fixed preview for a chapter list, for example — use the standalone [Thumbnail](../reference/components/thumbnail.md) component with an explicit `time`.
+
+Each cue’s text is an image URL. An optional `#xywh=x,y,w,h` fragment crops one frame out of a sprite sheet:
+
+**storyboard.vtt**
+
+```txt
+WEBVTT
+
+00:00:00.000 --> 00:00:05.000
+storyboard.jpg#xywh=0,0,256,160
+
+00:00:05.000 --> 00:00:10.000
+storyboard.jpg#xywh=256,0,256,160
+```
+
+## Availability and constraints
+
+- Thumbnails require a storyboard asset generated alongside the media; the player doesn’t extract frames from the video itself.
+- Cross-origin storyboards need CORS headers, and `crossOrigin` on the media element for the track to load.
+- Cues load asynchronously. The track appears before its cues are parsed, so previews fill in when the track finishes loading.
+- Storyboard images download on demand; oversized sprite sheets hurt seek-preview responsiveness more than they help quality.
+
+## Troubleshooting
+
+### Thumbnails don’t appear while scrubbing
+
+Confirm the storyboard track is `kind="metadata"` with `label="thumbnails"` and has the `default` attribute — the browser leaves a non-default track disabled and never loads its cues. Then confirm the VTT loads (network panel) and cross-origin assets have CORS headers with `crossOrigin` set on the media element.
+
+### Thumbnails are blurry or slow
+
+Regenerate the storyboard with a larger frame size, or split giant sprite sheets into smaller images.
+
+## Related pages
+
+### Components
+
+- [Thumbnail](../reference/components/thumbnail.md): Time-based thumbnail preview component for timeline scrubbing and hover previews
+- [Slider](../reference/components/slider.md): A composable slider component with track, fill, thumb, preview, and value parts
+- [TimeSlider](../reference/components/time-slider.md): A slider component for seeking through media playback time
+
+### API
+
+- [Text tracks](../reference/api/feature-text-tracks.md): Subtitles, captions, and chapter track state for the player store
+
+### Guides
+
+- [Add a poster and loading placeholder](./poster.md): Set the image shown before playback, then add a lightweight placeholder while it loads
+- [Show captions and subtitles](./captions.md): Show captions and subtitles, and let users turn them on and pick a language.

package/docs/guides/typescript.md

@@ -0,0 +1,41 @@
+# 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**
+
+```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.
+
+## Related pages
+
+### Guides
+
+- [Installation](./installation.md): Install Video.js packages and build an accessible, customizable video player with composable controls
+- [Bundlers](./bundlers.md): Bundler requirements for Video.js package exports, CSS, and wrapper libraries

package/docs/guides/ui-components.md

@@ -0,0 +1,82 @@
+# 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 [`<Player>`](../reference/components/player.md).
+
+However, you should consider placing your components in `<Container>`. Components in `<Container>` will go fullscreen with the player, respond to user activity, and more.
+
+- [Read more about `<Container>`](../reference/components/player-container.md)
+
+## Styling and customization
+
+For components you add yourself, use the documented props, state `data-*` attributes, and CSS custom properties. Add your own `className` when you need a selector.
+
+### The `render` prop
+
+The `render` prop is the primary customization mechanism. It accepts a function that receives `props` and `state`, and returns your element. The `props` object includes event handlers, ARIA attributes, data attributes, and a ref — always spread `{...props}` to keep everything working:
+
+```tsx
+import { PlayButton } from '@videojs/react';
+import { PauseIcon, PlayIcon } from '@videojs/react/icons';
+
+<PlayButton
+  render={(props, state) => (
+    <button {...props}>
+      {state.paused ? <PlayIcon /> : <PauseIcon />}
+    </button>
+  )}
+/>
+```
+
+`className` and `style` also accept functions of state for dynamic styling without a full render prop:
+
+```tsx
+<PlayButton
+  className={(state) =>
+    state.paused ? 'btn btn--paused' : 'btn btn--playing'
+  }
+/>
+```
+
+### Data attributes and CSS custom properties
+
+Components reflect player state as `data-*` attributes on their element. For example, `data-paused` or `data-volume-level="high"`.
+
+This lets you style state changes in pure CSS:
+
+```css
+/* Show/hide icons based on play state */
+.play-icon  { display: none; }
+.pause-icon { display: none; }
+
+button[data-paused] .play-icon        { display: inline; }
+button:not([data-paused]) .pause-icon { display: inline; }
+```
+
+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.
+
+Compound components use dot notation off a shared namespace:
+
+```tsx
+<VolumeSlider.Root orientation="vertical">
+  <VolumeSlider.Track>
+    <VolumeSlider.Fill />
+  </VolumeSlider.Track>
+  <VolumeSlider.Thumb />
+</VolumeSlider.Root>
+```