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

package/docs/reference/components/thumbnail.md

@@ -0,0 +1,309 @@
+# Thumbnail
+
+Time-based thumbnail preview component for timeline scrubbing and hover previews
+
+## Quick Start: Video Track
+
+`Thumbnail` can read thumbnail cues directly from your video track. Add a `<track>` with `kind="metadata"` and `label="thumbnails"` to your media element.
+
+[Mux](https://www.mux.com?utm_source=videojs&utm_campaign=vjs10) provides this as `storyboard.vtt`:
+
+`https://image.mux.com/{PLAYBACK_ID}/storyboard.vtt`
+
+That track is cross-origin, and a cross-origin `<track>` only loads when the media element is CORS-enabled:
+
+```tsx
+<Video src="video.mp4" crossOrigin="anonymous">
+  <track
+    kind="metadata"
+    label="thumbnails"
+    src="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.vtt"
+    default
+  />
+</Video>
+<Thumbnail.Root time={12}>
+  <Thumbnail.Image />
+</Thumbnail.Root>
+```
+
+A same-origin track needs none of this.
+
+## Import
+
+```tsx
+import { Thumbnail } from '@videojs/react';
+```
+
+## Anatomy
+
+```tsx
+<Thumbnail.Root>
+  <Thumbnail.Image />
+</Thumbnail.Root>
+```
+
+## Behavior
+
+The thumbnail root resolves an image for the current `time`, owns `src` and `srcset` on it, and reports its loading lifecycle.
+
+Render that image with `Thumbnail.Image`.
+
+Supported source formats:
+
+- Text track: `<track kind="metadata" label="thumbnails" src="...vtt">`
+- JSON array: `{ url, startTime, endTime? }[]`
+- JSON sprite array: `{ url, startTime, endTime?, width, height, coords }[]`
+
+Text-track mode needs `Player` because it reads track state from the player store. JSON modes (`thumbnails` prop) work without a player.
+
+The component picks the latest thumbnail whose `startTime` is less than or equal to the current `time`, then scales/clips sprite tiles to fill CSS min/max constraints while preserving aspect ratio. Tiles scale up as well as down, so a preview whose `max-width` grows — a container query widening it in fullscreen, say — grows with it.
+
+### Cross-origin images
+
+Leave `crossOrigin` unset and the component follows the media element. A cross-origin thumbnail `<track>` only loads when the media is CORS-enabled, so the images its cues point at are fetched with that same mode. Skins get this for free, with nothing to thread through.
+
+Opt out to fetch them without CORS:
+
+```tsx
+<Thumbnail.Root time={12}>
+  <Thumbnail.Image crossOrigin={null} />
+</Thumbnail.Root>
+```
+
+An empty value does not opt out either. The [CORS settings attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/crossorigin) reads anything other than `use-credentials` as Anonymous, so it is a value like any other.
+
+Thumbnails you supply through `thumbnails` never inherit, since they need not be related to the media element at all. Set `crossOrigin` yourself when those images need it.
+
+## Styling
+
+Use state data attributes for pure CSS styling:
+
+React renders a root `<div>` around an `<img>`. State attributes belong to `Thumbnail.Root`, while image attributes and `render` belong to `Thumbnail.Image`:
+
+```tsx
+<Thumbnail.Root className="media-thumbnail" time={12}>
+  <Thumbnail.Image className="media-thumbnail-image" loading="eager" />
+  <div className="media-thumbnail-overlay" aria-hidden />
+</Thumbnail.Root>
+```
+
+The root clips to the selected tile while the image inside spans the whole sprite sheet, so anything after the image in flow lands past the clip edge. Position the root and lay overlays over it:
+
+```css
+.media-thumbnail {
+  position: relative;
+}
+
+.media-thumbnail-overlay {
+  position: absolute;
+  inset: 0;
+}
+
+.media-thumbnail[data-hidden] {
+  display: none;
+}
+
+.media-thumbnail[data-loading] {
+  opacity: 0.6;
+}
+
+.media-thumbnail[data-error] {
+  outline: 1px solid #ef4444;
+}
+```
+
+## Accessibility
+
+`Thumbnail.Root` is decorative by default (`aria-hidden="true"`). It is intended for visual preview UX (for example, timeline hover previews) rather than primary accessible content.
+
+## Examples
+
+### Text Track (VTT)
+
+**App.tsx**
+
+```tsx
+import { Container, createPlayer, Thumbnail } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+export default function TextTrackUsage() {
+  return (
+    <Player>
+      <Container className="demo">
+        <Video
+          className="media"
+          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
+          preload="auto"
+          muted
+          playsInline
+          crossOrigin="anonymous"
+        >
+          <track kind="metadata" label="thumbnails" src="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.vtt" default />
+        </Video>
+        <Thumbnail.Root className="media-thumbnail" time={12}>
+          <Thumbnail.Image className="media-thumbnail-image" />
+        </Thumbnail.Root>
+      </Container>
+    </Player>
+  );
+}
+```
+
+**App.css**
+
+```css
+.demo {
+  position: relative;
+  max-width: 280px;
+}
+
+.media {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  pointer-events: none;
+  opacity: 0;
+}
+
+.media-thumbnail {
+  display: block;
+  width: auto;
+  min-width: 0;
+  max-width: 240px;
+}
+
+.media-thumbnail-image {
+  display: block;
+}
+
+.media-thumbnail[data-hidden] {
+  display: none;
+}
+```
+
+### JSON Array
+
+**App.tsx**
+
+```tsx
+import { Thumbnail } from '@videojs/react';
+
+const THUMBNAILS = [
+  {
+    url: 'https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg?time=0',
+    startTime: 0,
+    endTime: 10,
+  },
+  {
+    url: 'https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg?time=10',
+    startTime: 10,
+    endTime: 20,
+  },
+  {
+    url: 'https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg?time=20',
+    startTime: 20,
+  },
+];
+
+export default function JsonUsage() {
+  return (
+    <Thumbnail.Root thumbnails={THUMBNAILS} time={12} style={{ maxWidth: 240 }}>
+      <Thumbnail.Image />
+    </Thumbnail.Root>
+  );
+}
+```
+
+### JSON Sprite Array
+
+**App.tsx**
+
+```tsx
+import { Thumbnail } from '@videojs/react';
+
+const THUMBNAILS = [
+  {
+    url: 'https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.jpg',
+    startTime: 0,
+    endTime: 10,
+    width: 284,
+    height: 160,
+    coords: { x: 0, y: 0 },
+  },
+  {
+    url: 'https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.jpg',
+    startTime: 10,
+    endTime: 20,
+    width: 284,
+    height: 160,
+    coords: { x: 284, y: 0 },
+  },
+  {
+    url: 'https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.jpg',
+    startTime: 20,
+    width: 284,
+    height: 160,
+    coords: { x: 568, y: 0 },
+  },
+];
+
+export default function JsonSpriteUsage() {
+  return (
+    <Thumbnail.Root thumbnails={THUMBNAILS} time={12} style={{ maxWidth: 240 }}>
+      <Thumbnail.Image />
+    </Thumbnail.Root>
+  );
+}
+```
+
+## API Reference
+
+### Root
+
+Resolves, sizes, and clips a thumbnail for a point in time.
+
+Renders a `div` and exposes `data-hidden`, `data-loading`, and `data-error` for styling every layer in the preview. Render `Thumbnail.Image` inside it for the image the root controls and measures.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `thumbnails` | `ThumbnailImage[]` | — | Pre-parsed thumbnail images — bypasses the automatic `<track>` detection. |
+| `time` | `number` | — | Time in seconds to display the thumbnail for. |
+
+#### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `loading` | `boolean` | The thumbnail image is loading. |
+| `error` | `boolean` | The thumbnail image failed to load. |
+| `hidden` | `boolean` | Whether the component is hidden because no thumbnail is available and it is not loading. |
+
+#### Data attributes
+
+| Attribute | Description |
+| --- | --- |
+| `data-loading` | |
+| `data-error` | |
+| `data-hidden` | |
+
+### Image
+
+Displays the image selected and measured by `Thumbnail.Root`.
+
+Renders an `img`, so native image attributes and the `render` escape hatch remain available without replacing the root that owns thumbnail state.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string \| ((state: ThumbnailState) => string \| undefined)` | — | Class name or function returning class name from state. |
+| `crossOrigin` | `ThumbnailCrossOrigin` | — | CORS setting for the selected image. Leave unset to follow the media element, or pass `null` to opt out. |
+| `fetchPriority` | `ThumbnailFetchPriority` | — | Image fetch priority hint. |
+| `loading` | `ThumbnailLoading` | — | Image loading strategy. |
+| `render` | `ReactElement \| ((props: HTMLProps, state: ThumbnailState) => ReactElement \| null)` | — | Render prop for custom element. |
+| `style` | `CSSProperties \| ((state: ThumbnailState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

package/docs/reference/components/tiktok-video.md

@@ -0,0 +1,128 @@
+# TikTokVideo
+
+Video component that plays TikTok videos through the TikTok embed player
+
+The [TikTok embed player](https://developers.tiktok.com/doc/embed-player) expects portrait video and won’t draw its chrome below 325×578, so the element starts at that size rather than the usual 300×150.
+
+## Import
+
+```bash
+pnpm add @videojs/tiktok-video
+```
+
+```tsx
+import { TikTokVideo } from '@videojs/react/media/tiktok-video';
+```
+
+## Load a source
+
+`src` takes a TikTok video URL or a raw numeric video id. The `@user/video/<id>` URLs the app hands out, `share/video/<id>` links, and `player/v1/<id>` embed URLs all work.
+
+```tsx
+<TikTokVideo src="https://www.tiktok.com/@_luwes/video/7527476667770522893" />
+```
+
+## Controls
+
+TikTok always draws part of its own chrome: the center play button, author header, and social rail are always visible. `controls` adds the progress bar and control buttons on top of those. Without `controls`, the element ignores pointer events, so a [player skin](../../guides/skins.md) above it receives every click.
+
+## Deferred startup
+
+TikTok builds its player lazily: until something starts playback, the embed has no video element, reports a duration of 0, and silently drops commands. The element works around this by starting a muted autoplay and pausing it immediately, so the embed answers play, pause, and seek before the first play.
+
+Two settings opt out. `preload="none"` skips the warm-up, leaving the network untouched until the viewer presses play, and the controls inert until then. `controls` hands playback to TikTok’s own chrome instead.
+
+## Behavior
+
+- Mute works, but there’s no volume control: the embed reports a level but takes no command to set one.
+- No playback rate and no text tracks; captions are toggled with `engine.tiktok.closed_caption`.
+- `poster` and `playsInline` never reach the embed: it always plays inline and draws the video’s own cover image.
+- Changing `controls` or `loop` after the embed is up rebuilds it; rewriting the iframe URL is the only reload TikTok allows.
+
+## Examples
+
+### Basic Usage
+
+**App.tsx**
+
+```tsx
+import { TikTokVideo } from '@videojs/react/media/tiktok-video';
+
+export default function BasicUsage() {
+  return (
+    <div className="tiktok-video">
+      <TikTokVideo src="https://www.tiktok.com/@_luwes/video/7527476667770522893" controls />
+    </div>
+  );
+}
+```
+
+**App.css**
+
+```css
+/* TikTok videos are portrait: the element floors itself at 325x578. */
+.tiktok-video {
+  display: block;
+  width: 325px;
+  height: 578px;
+  margin-inline: auto;
+}
+```
+
+## API Reference
+
+### Props
+
+Accepts these Video.js-specific props:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `autoplay` | `boolean` | `false` | |
+| `controls` | `boolean` | `false` | |
+| `defaultMuted` | `boolean` | `false` | |
+| `loop` | `boolean` | `false` | |
+| `muted` | `boolean` | `false` | |
+| `playsInline` | `boolean` | `true` | |
+| `poster` | `string` | `''` | |
+| `preload` | `MediaPreloadType` | `'metadata'` | |
+| `source` | `{ src?: string; engine?: TikTokSourceEngineConfig } \| null` | `null` | TikTok URL or id in `src`, player params under `engine.tiktok`. Re-derives `src`; equal sources skip reload. |
+| `src` | `string` | `''` | |
+
+### Engine options
+
+#### `source.engine.tiktok`
+
+Pass [TikTok player parameters](https://developers.tiktok.com/doc/embed-player) under `source.engine.tiktok`, spelled exactly as TikTok spells them, each one `0` or `1`, plus anything TikTok adds next. [Media Sources](../../guides/media-sources.md) covers how engine options fit into a structured source.
+
+`autoplay`, `controls`, `loop`, and `muted` come from the props of the same name, so they have no `engine.tiktok` spelling.
+
+```tsx
+<TikTokVideo
+  source={{
+    src: 'https://www.tiktok.com/@_luwes/video/7527476667770522893',
+    engine: { tiktok: { closed_caption: 0, rel: 1 } },
+  }}
+/>
+```
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `closed_caption` | `0 \| 1 \| undefined` | Show the closed-caption button. Defaults to `1`. |
+| `description` | `0 \| 1 \| undefined` | Show the video description. Defaults to `0`. |
+| `fullscreen_button` | `0 \| 1 \| undefined` | Show the fullscreen button. Defaults to `1`. |
+| `music_info` | `0 \| 1 \| undefined` | Show the track the video uses. Defaults to `0`. |
+| `native_context_menu` | `0 \| 1 \| undefined` | Show the browser's native context menu. Defaults to `1`. |
+| `play_button` | `0 \| 1 \| undefined` | Show the play button. Defaults to `1`. |
+| `progress_bar` | `0 \| 1 \| undefined` | Show the progress bar. Defaults to `1`. |
+| `referrerPolicy` | `ReferrerPolicy \| undefined` | `referrerpolicy` for the embed iframe. Not a TikTok player parameter. |
+| `rel` | `0 \| 1 \| undefined` | Draw related videos from TikTok's recommendations (`1`) or the author's own videos (`0`). Defaults to `1`. |
+| `timestamp` | `0 \| 1 \| undefined` | Show the current playback time and duration. Defaults to `1`. |
+| `volume_control` | `0 \| 1 \| undefined` | Show the volume control. Defaults to `1`. |
+
+### Ref
+
+Forwards its ref to the rendered `<iframe>`. The ref is an [HTMLIFrameElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLIFrameElement). Control playback with the component props and player APIs rather than the iframe ref.
+
+### Events
+
+Handle standard media events with React event props such as `onPlay` and `onTimeUpdate`. For native events without a React prop, attach a listener through the ref with `addEventListener`.