@videojs/react 10.0.0-beta.3 → 10.0.0-beta.31

package/docs/reference/create-i18n.md

@@ -0,0 +1,84 @@
+# createI18n
+
+Factory that creates framework i18n helpers with custom loading options
+
+`createI18n` returns an `I18nProvider`, `useTranslator`, and `useLocale` wired to the shared React i18n context used by the stock skins and controls. Use it when you need options such as a custom locale loader. Most apps use the default exports from `@videojs/react/i18n`.
+
+tsx
+
+```
+import { createI18n } from '@videojs/react/i18n';
+
+const loaders = {
+  ja: () => import('@videojs/react/i18n/locales/ja'),
+};
+
+const { I18nProvider, useTranslator } = createI18n({
+  loader: async (tag) => {
+    const load = loaders[tag as keyof typeof loaders];
+    return load ? (await load()).default : undefined;
+  },
+});
+
+function App() {
+  return (
+    <I18nProvider locale="ja">
+      <Controls />
+    </I18nProvider>
+  );
+}
+```
+
+## API Reference
+
+### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`options`
+
+`CreateI18nOptions`
+
+`—`
+
+▸
+
+Description
+
+Optional hooks such as custom built-in locale loading.
+
+### Return Value
+
+Property
+
+Type
+
+Details
+
+`I18nContext`
+
+`Context<I18nContextValue | null>`
+
+`I18nProvider`
+
+`function`
+
+▸
+
+Type
+
+`((props: I18nProviderProps) => ReactNode)`
+
+`useTranslator`
+
+`useTranslator`
+
+`useLocale`
+
+`useLocale`

package/docs/reference/create-player.md

@@ -0,0 +1,247 @@
+# createPlayer
+
+Factory function that creates a typed Player component and hooks
+
+`createPlayer` is the entry point for setting up a Video.js player in React. It accepts a configuration object with a `features` array and returns hooks and components for building a player.
+
+The hook is typed according to the provided features, giving you full type safety for state selectors and actions.
+
+tsx
+
+```
+import { Container, createPlayer } from '@videojs/react';
+import { videoFeatures } from '@videojs/react/video';
+
+const { Player, usePlayer, useMedia } = createPlayer({
+  features: videoFeatures,
+});
+
+// Container is imported independently from createPlayer.
+```
+
+## Examples
+
+### Basic Usage
+
+Play
+
+App.tsx
+
+App.css
+
+```
+import { Container, createPlayer } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player, usePlayer } = createPlayer({
+  features: videoFeatures,
+});
+
+function Controls() {
+  const store = usePlayer();
+  const paused = usePlayer((s) => s.paused);
+
+  return (
+    <div className="controls">
+      <button type="button" className="button" onClick={() => (paused ? store.play() : store.pause())}>
+        {paused ? 'Play' : 'Pause'}
+      </button>
+    </div>
+  );
+}
+
+export default function BasicUsage() {
+  return (
+    <Player>
+      <Container className="media-container">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline />
+        <Controls />
+      </Container>
+    </Player>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.controls {
+  position: absolute;
+  bottom: 10px;
+  left: 10px;
+}
+
+.button {
+  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);
+}
+```
+
+## API Reference
+
+### Video
+
+Create a player instance with a typed Player component and hooks.
+
+#### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`config*`
+
+`CreatePlayerConfig<VideoFeatures>`
+
+`—`
+
+▸
+
+Description
+
+Player configuration with features and optional display name.
+
+#### Return Value
+
+Property
+
+Type
+
+Details
+
+`Player`
+
+`React.FC<PlayerProps<{ title: MediaContentValue; poster: MediaContentValue }>>`
+
+`usePlayer`
+
+`UsePlayerHook<VideoPlayerStore>`
+
+`useMedia`
+
+`null) | function`
+
+▸
+
+Type
+
+`(() => Media | null)`
+
+### Audio
+
+Create a player for audio media.
+
+#### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`config*`
+
+`CreatePlayerConfig<AudioFeatures>`
+
+`—`
+
+▸
+
+Description
+
+Player configuration with features and optional display name.
+
+#### Return Value
+
+Property
+
+Type
+
+Details
+
+`Player`
+
+`React.FC<PlayerProps<{ title: MediaContentValue; poster: MediaContentValue }>>`
+
+`usePlayer`
+
+`UsePlayerHook<AudioPlayerStore>`
+
+`useMedia`
+
+`null) | function`
+
+▸
+
+Type
+
+`(() => Media | null)`
+
+### Generic
+
+Create a player with custom features.
+
+#### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`config*`
+
+`CreatePlayerConfig<AnyPlayerFeature[]>`
+
+`—`
+
+▸
+
+Description
+
+Player configuration with features and optional display name.
+
+#### Return Value
+
+Property
+
+Type
+
+Details
+
+`Player`
+
+`React.FC<PlayerProps<Config | object>>`
+
+`usePlayer`
+
+`UsePlayerHook<PlayerStore<AnyPlayerFeature[]>>`
+
+`useMedia`
+
+`null) | function`
+
+▸
+
+Type
+
+`(() => Media | null)`

package/docs/reference/create-selector.md

@@ -0,0 +1,59 @@
+# createSelector
+
+Create a type-safe selector for a store slice's state
+
+`createSelector` creates a type-safe selector function for a given slice. The returned selector extracts that slice’s state from the full store state, or returns `undefined` if the slice is not configured.
+
+The built-in selectors ([`selectPlayback`](./feature-playback.md), [`selectBuffer`](./feature-buffer.md), etc.) are all created with `createSelector`. Use it to create selectors for custom slices.
+
+my-custom-selector.ts
+
+```
+import { createSelector } from '@videojs/store';
+import { myCustomSlice } from './my-custom-slice';
+
+const selectCustom = createSelector(myCustomSlice);
+
+// Use with usePlayer (React) or PlayerController (HTML)
+const state = selectCustom(store.state);
+```
+
+Pass selectors to [`usePlayer`](./use-player.md) or [`useStore`](./use-store.md) for reactive subscriptions.
+
+## API Reference
+
+### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`slice*`
+
+`S`
+
+`—`
+
+▸
+
+Description
+
+The slice to create a selector for.
+
+### Return Value
+
+Type
+
+Details
+
+`Selector<object, InferSliceState<S> |...`
+
+▸
+
+Type
+
+`Selector<object, InferSliceState<S> | undefined>`

package/docs/reference/create-translator.md

@@ -0,0 +1,63 @@
+# createTranslator
+
+Build a typed translator from a resolved translation map
+
+`createTranslator` wraps the flat map returned by `getI18nTranslations` and returns a typed translator. Providers call this internally after merging registry, lazy-loaded built-in packs, browser-translated fallback copy, and provider layers. Use it directly for custom UI outside built-in controls.
+
+ts
+
+```
+import { createTranslator, getI18nTranslations } from '@videojs/react/i18n';
+
+const t = createTranslator(getI18nTranslations('fr'), 'fr');
+t('buttons.play', { default: 'Play' });
+t('seek.forward', { seconds: 5, default: 'Seek forward {seconds} seconds' });
+```
+
+## API Reference
+
+### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`translations*`
+
+`object & Record<string, string | unde...`
+
+`—`
+
+▸
+
+Description
+
+Merged translation map for the active locale.
+
+Type
+
+`object & Record<string, string | undefined>`
+
+`locale*`
+
+`string & object | 'ar' | 'az' | 'bs' ...`
+
+`—`
+
+▸
+
+Description
+
+BCP 47 tag associated with the map (reserved for future locale-aware behavior).
+
+Type
+
+`string & object | 'ar' | 'az' | 'bs' | 'bg' | 'bn' | 'ca' | 'cs' | 'cy' | 'da' | 'de' | 'el' | 'es' | 'et' | 'eu' | 'fa' | 'fi' | 'fr' | 'gd' | 'gl' | 'he' | 'hi' | 'hr' | 'hu' | 'id' | 'it' | 'ja' | 'ko' | 'lt' | 'lv' | 'mr' | 'nb' | 'nl' | 'nn' | 'ne' | 'oc' | 'pl' | 'pt-BR' | 'pt-PT' | 'ro' | 'ru' | 'sk' | 'sl' | 'sr' | 'sv' | 'te' | 'th' | 'tr' | 'uk' | 'vi' | 'zh-CN' | 'zh-TW'`
+
+### Return Value
+
+`Translator`

package/docs/reference/dash-video.md

@@ -0,0 +1,124 @@
+# DashVideo
+
+DASH video element powered by dash.js for adaptive bitrate streaming
+
+DASH video element powered by [dash.js](https://github.com/Dash-Industry-Forum/dash.js/) for MPEG-DASH adaptive bitrate streaming.
+
+## Examples
+
+### Basic Usage
+
+App.tsx
+
+App.css
+
+```
+import { DashVideo } from '@videojs/react/media/dash-video';
+
+export default function BasicUsage() {
+  return <DashVideo className="dash-video" src="https://dash.akamaized.net/akamai/streamroot/050714/Spring_4Ktest.mpd" autoPlay muted playsInline loop />;
+}
+```
+```
+.dash-video {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+```
+
+## API Reference
+
+### Props
+
+Accepts the standard React props for a native `<video>`, plus these Video.js-specific props:
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`source`
+
+`DashSource | null`
+
+`null`
+
+▸
+
+Description
+
+Structured source: the MPD URL in `src`, plus dash.js settings in `engine.dashJs`. Replacing it re-derives `src`.
+
+dash.js takes settings on a live player, so changing `engine.dashJs` re-applies them in place instead of recreating the engine.
+
+`src`
+
+`string`
+
+`''`
+
+### Engine options
+
+#### `source.engine.dashJs`
+
+Pass dash.js’s own settings here. They’re handed to dash.js untouched, so every option in its [settings reference](https://cdn.dashjs.org/latest/jsdoc/module-Settings.html) works. Replacing the object resets any settings applied before it. [Media Sources](../concepts/media-sources.md) covers how engine options fit into a structured source.
+
+Each of the three below is a group of dash.js settings rather than a single value, and dash.js documents what’s inside them.
+
+tsx
+
+```
+<DashVideo
+  source={{
+    src: 'https://example.com/manifest.mpd',
+    engine: { dashJs: { streaming: { buffer: { fastSwitchEnabled: true } } } },
+  }}
+/>
+```
+
+Option
+
+Type
+
+Details
+
+`debug`
+
+`object`
+
+▸
+
+Type
+
+`{ logLevel?: LogLevel; dispatchEvent?: boolean; }`
+
+`errors`
+
+`object`
+
+▸
+
+Type
+
+`{ recoverAttempts?: { mediaErrorDecode?: number; }; }`
+
+`streaming`
+
+`object`
+
+▸
+
+Type
+
+`{ abandonLoadTimeout?: number; wallclockTimeUpdateInterval?: number; manifestUpdateRetryInterval?: number; liveUpdateTimeThresholdInMilliseconds?: number; cacheInitSegments?: boolean; ... 40 more ...; dvbReporting?: { ...; }; }`
+
+### Ref
+
+Forwards its ref to the rendered `<video>`. The ref is an [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) and exposes its complete native property and method API.
+
+### 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`.

package/docs/reference/feature-audio-track.md

@@ -0,0 +1,60 @@
+# Audio track
+
+Audio track state and actions for the player store
+
+Tracks available audio tracks and selects the enabled track.
+
+## API Reference
+
+### State
+
+Property
+
+Type
+
+Details
+
+`audioTrackList`
+
+`MediaAudioTrack[]`
+
+▸
+
+Description
+
+Audio tracks available for manual track selection.
+
+### Actions
+
+Action
+
+Type
+
+Details
+
+`selectAudioTrack`
+
+`(value: string) => void`
+
+▸
+
+Description
+
+Select an audio track by menu value.
+
+### Selector
+
+Pass `selectAudioTrack` to [`usePlayer`](./use-player.md) to subscribe to audio track state. Returns `undefined` if the audio track feature is not configured.
+
+AudioTrackInfo.tsx
+
+```
+import { selectAudioTrack, usePlayer } from '@videojs/react';
+
+function AudioTrackInfo() {
+  const audioTrack = usePlayer(selectAudioTrack);
+  if (!audioTrack) return null;
+
+  return <span>{audioTrack.audioTrackList.length} audio tracks</span>;
+}
+```

package/docs/reference/feature-buffer.md

@@ -0,0 +1,54 @@
+# Buffer
+
+Buffered and seekable time range state for the player store
+
+Read-only — tracks buffered and seekable time ranges.
+
+## API Reference
+
+### State
+
+Property
+
+Type
+
+Details
+
+`buffered`
+
+`[number, number][]`
+
+▸
+
+Description
+
+Buffered time ranges as \[start, end\] tuples.
+
+`seekable`
+
+`[number, number][]`
+
+▸
+
+Description
+
+Seekable time ranges as \[start, end\] tuples.
+
+### Selector
+
+Pass `selectBuffer` to [`usePlayer`](./use-player.md) to subscribe to buffer state. Returns `undefined` if the buffer feature is not configured.
+
+BufferBar.tsx
+
+```
+import { selectBuffer, usePlayer } from '@videojs/react';
+
+function BufferBar() {
+  const buffer = usePlayer(selectBuffer);
+  if (!buffer) return null;
+
+  return (
+    <div style={{ width: `${buffer.percentBuffered * 100}%` }} />
+  );
+}
+```