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

package/docs/reference/use-quality-options.md

@@ -0,0 +1,59 @@
+# useQualityOptions
+
+Hook to build video quality menu options from the player rendition state
+
+`useQualityOptions` returns the current quality value, the available options, and a `setValue` callback for wiring quality selection into a menu. It returns `null` when the [quality feature](./feature-quality.md) is not configured.
+
+QualityMenu.tsx
+
+```
+import { Menu, useQualityOptions } from "@videojs/react";
+
+function QualityMenu() {
+  const quality = useQualityOptions();
+  if (quality?.state.availability !== "available") return null;
+
+  return (
+    <Menu.RadioGroup value={quality.value} onValueChange={quality.setValue} aria-label="Quality">
+      {quality.options.map((option) => (
+        <Menu.RadioItem key={option.value} value={option.value} disabled={option.disabled}>
+          {option.label}
+          <Menu.ItemIndicator checked={option.value === quality.value} />
+        </Menu.RadioItem>
+      ))}
+    </Menu.RadioGroup>
+  );
+}
+```
+
+The first option is always `Auto`; selecting it returns control to adaptive bitrate selection. Options carry optional `tier` and `badge` fields (e.g. `4K`, `HD`) for richer labels. Pass `formatRendition` to customize the visible rendition labels.
+
+See [QualityRadioGroup](./quality-radio-group.md) for the component-level pattern, and [Menu](./menu.md) for a complete settings menu example.
+
+## API Reference
+
+### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`props`
+
+`QualityOptionsProps`
+
+`—`
+
+▸
+
+Description
+
+Optional `label`, `formatRendition`, and `disabled` overrides.
+
+### Return Value
+
+`QualityOptionsResult | null`

package/docs/reference/use-selector.md

@@ -0,0 +1,132 @@
+# useSelector
+
+Low-level hook for subscribing to derived state with customizable equality checks
+
+`useSelector` is a low-level hook that subscribes to an external store using React’s `useSyncExternalStore`. It accepts a `subscribe` function, a `getSnapshot` function, a `selector` to derive state, and an optional `isEqual` comparator (defaults to `shallowEqual`).
+
+TimeDisplay.tsx
+
+```
+import { useSelector, shallowEqual } from "@videojs/store/react";
+
+function TimeDisplay({ store }) {
+  const time = useSelector(
+    (cb) => store.subscribe(cb),
+    () => store.state,
+    (state) => ({ current: state.currentTime, duration: state.duration }),
+    shallowEqual,
+  );
+
+  return (
+    <span>
+      {time.current} / {time.duration}
+    </span>
+  );
+}
+```
+
+### Relationship to useStore and useSnapshot
+
+Both `useStore` and `useSnapshot` are built on `useSelector`:
+
+Hook
+
+Input
+
+Use case
+
+[`useStore`](./use-store.md)
+
+Store instance
+
+Player and store access with selector
+
+[`useSnapshot`](./use-snapshot.md)
+
+`State` container
+
+Subscribe to raw state changes
+
+`useSelector`
+
+Custom subscribe/snapshot
+
+Full control over subscription plumbing
+
+Prefer [`useStore`](./use-store.md) for store-backed state and [`useSnapshot`](./use-snapshot.md) for `State` containers. Use `useSelector` when you need to integrate with a non-standard external source or customize the equality comparison.
+
+### Equality comparison
+
+The `isEqual` parameter controls when React re-renders. The default `shallowEqual` compares object properties one level deep – sufficient for most selector return values. Pass a custom comparator for deeply nested objects or when you need reference equality (`Object.is`).
+
+## API Reference
+
+### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`subscribe*`
+
+`function`
+
+`—`
+
+▸
+
+Description
+
+Subscribe function that returns an unsubscribe callback.
+
+Type
+
+`((cb: (() => void)) => (() => void))`
+
+`getSnapshot*`
+
+`function`
+
+`—`
+
+▸
+
+Description
+
+Returns the current snapshot value.
+
+Type
+
+`(() => S)`
+
+`selector*`
+
+`Selector<S, R>`
+
+`—`
+
+▸
+
+Description
+
+Derives a value from the snapshot.
+
+`isEqual`
+
+`Comparator<R>`
+
+`—`
+
+▸
+
+Description
+
+Custom equality function. Defaults to `shallowEqual`.
+
+### Return Value
+
+`R`

package/docs/reference/use-snapshot.md

@@ -0,0 +1,127 @@
+# useSnapshot
+
+Hook to subscribe to a State container's current value
+
+`useSnapshot` subscribes to a `State` container and returns its current value, re-rendering when the value changes. It has two overloads:
+
+**Full state** – returns the entire state object.
+
+tsx
+
+```
+function Display({ state }) {
+  const value = useSnapshot(state);
+  return <span>{value.count}</span>;
+}
+```
+
+**With selector** – returns a derived value from the state, re-rendering only when the selected value changes. Pass a custom comparator as the third argument when needed.
+
+tsx
+
+```
+function Count({ state }) {
+  const count = useSnapshot(state, (s) => s.count);
+  return <span>{count}</span>;
+}
+```
+
+### State containers vs stores
+
+A `State` container is a reactive primitive that holds an object value and notifies subscribers on change. Stores are built on top of `State` containers but add features, actions, and lifecycle.
+
+Hook
+
+Input
+
+Subscribes to
+
+`useSnapshot`
+
+`State<T>`
+
+Raw state container
+
+[`useStore`](./use-store.md)
+
+Store instance
+
+Store-backed state with features
+
+Use `useSnapshot` when working with standalone `State` containers outside the player store system – for example, custom state in component libraries. For player state, use [`usePlayer`](./use-player.md) or [`useStore`](./use-store.md).
+
+`useSnapshot` is built on [`useSelector`](./use-selector.md) and uses `shallowEqual` by default. The HTML equivalent is `SnapshotController`.
+
+## API Reference
+
+### Without Selector
+
+Subscribe to a State container's current value.
+
+#### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`state*`
+
+`State<object>`
+
+`—`
+
+#### Return Value
+
+`object`
+
+### With Selector
+
+Select a value from state. Re-renders when the selected value changes.
+
+#### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`state*`
+
+`State<object>`
+
+`—`
+
+`selector*`
+
+`Selector<object, R>`
+
+`—`
+
+▸
+
+Description
+
+Derives a value from state.
+
+`isEqual`
+
+`Comparator<R>`
+
+`—`
+
+▸
+
+Description
+
+Custom equality function. Defaults to `shallowEqual`.
+
+#### Return Value
+
+`R`

package/docs/reference/use-store.md

@@ -0,0 +1,245 @@
+# useStore
+
+Hook to access store state and actions with optional selector-based subscriptions
+
+`useStore` subscribes to a store instance directly. It has the same two overloads as [`usePlayer`](./use-player.md) — without a selector for store access, or with a selector for reactive state. Within `Player`, `usePlayer` is usually simpler since it reads the store from context. Reach for `useStore` when you have a store instance directly or need to derive computed values from the store.
+
+## Examples
+
+### Store Access
+
+Call `useStore(store)` without a selector to get the store instance back for imperative actions. The component does not subscribe to state changes.
+
+Go to startGo to middle
+
+App.tsx
+
+App.css
+
+```
+import { Container, createPlayer, useStore } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player, usePlayer } = createPlayer({
+  features: videoFeatures,
+});
+
+function SeekControls() {
+  const store = usePlayer();
+  const s = useStore(store);
+
+  return (
+    <div className="controls">
+      <button type="button" onClick={() => s.seek(0)}>
+        Go to start
+      </button>
+      <button type="button" onClick={() => s.seek(s.state.duration / 2)}>
+        Go to middle
+      </button>
+    </div>
+  );
+}
+
+export default function StoreAccess() {
+  return (
+    <Player>
+      <Container className="media-container">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
+        <SeekControls />
+      </Container>
+    </Player>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.controls {
+  display: flex;
+  gap: 6px;
+  padding: 12px;
+  background: rgba(0, 0, 0, 0.05);
+  border-top: 1px solid rgba(0, 0, 0, 0.1);
+}
+
+.controls button {
+  padding: 4px 12px;
+  font-size: 0.8125rem;
+  cursor: pointer;
+  background: white;
+  border: 1px solid #ccc;
+  border-radius: 6px;
+}
+```
+
+### Selector Subscription
+
+Pass a selector to derive and subscribe to computed values from the store. The component re-renders when the derived value changes, using shallow equality by default.
+
+Remaining
+
+0.0s
+
+Progress
+
+0.0%
+
+App.tsx
+
+App.css
+
+```
+import { Container, createPlayer, useStore } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player, usePlayer } = createPlayer({
+  features: videoFeatures,
+});
+
+function DerivedState() {
+  const store = usePlayer();
+  const derived = useStore(store, (s) => ({
+    remaining: s.duration - s.currentTime,
+    progress: s.duration > 0 ? (s.currentTime / s.duration) * 100 : 0,
+  }));
+
+  return (
+    <dl className="panel">
+      <div>
+        <dt>Remaining</dt>
+        <dd>{derived.remaining.toFixed(1)}s</dd>
+      </div>
+      <div>
+        <dt>Progress</dt>
+        <dd>{derived.progress.toFixed(1)}%</dd>
+      </div>
+    </dl>
+  );
+}
+
+export default function Selector() {
+  return (
+    <Player>
+      <Container className="media-container">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
+        <DerivedState />
+      </Container>
+    </Player>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.panel {
+  display: flex;
+  gap: 16px;
+  padding: 12px;
+  margin: 0;
+  font-size: 0.8125rem;
+  background: rgba(0, 0, 0, 0.05);
+  border-top: 1px solid rgba(0, 0, 0, 0.1);
+}
+
+.panel div {
+  display: flex;
+  gap: 8px;
+}
+
+.panel dt {
+  color: #6b7280;
+}
+
+.panel dd {
+  margin: 0;
+  font-variant-numeric: tabular-nums;
+}
+```
+
+## API Reference
+
+### Without Selector
+
+Access store state and actions.
+
+Without selector: Returns the store, does NOT subscribe to changes. With selector: Returns selected state, re-renders when selected state changes (shallowEqual).
+
+#### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`store*`
+
+`S`
+
+`—`
+
+#### Return Value
+
+`S`
+
+### With Selector
+
+Select a value from the store. Re-renders when the selected value changes (shallowEqual).
+
+#### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`store*`
+
+`S`
+
+`—`
+
+`selector*`
+
+`Selector<InferStoreState<S>, R>`
+
+`—`
+
+▸
+
+Description
+
+Derives a value from the store state.
+
+`isEqual`
+
+`Comparator<R>`
+
+`—`
+
+▸
+
+Description
+
+Custom equality function. Defaults to `shallowEqual`.
+
+#### Return Value
+
+`R`

package/docs/reference/use-translator.md

@@ -0,0 +1,119 @@
+# useTranslator
+
+React hook that returns the typed translator for the nearest I18nProvider
+
+`useTranslator` returns the translator from the nearest [`I18nProvider`](./i18n-provider.md). Control components pass text descriptors from core `getLabel()`. Custom UI can pass an opaque key with its English fallback.
+
+When no provider is mounted, the hook falls back to English registry strings so standalone demos do not throw.
+
+## Example
+
+Switch the provider locale to see `useTranslator` resolve a simple key and a parameterized key from the nearest provider.
+
+LanguageSpanishFrench
+
+Button
+
+Reproducir
+
+Parameterized
+
+Adelantar 10 segundos
+
+App.tsx
+
+App.css
+
+```
+import { I18nProvider, useTranslator } from '@videojs/react/i18n';
+import { useState } from 'react';
+
+import './BasicUsage.css';
+
+const translations = {
+  es: {
+    buttons: { play: 'Reproducir' },
+    seek: { forward: 'Adelantar {seconds} segundos' },
+  },
+  fr: {
+    buttons: { play: 'Lire' },
+    seek: { forward: 'Avancer de {seconds} secondes' },
+  },
+} as const;
+
+type Locale = keyof typeof translations;
+
+function Labels() {
+  const t = useTranslator();
+
+  return (
+    <dl className="react-use-translator-basic__output">
+      <div>
+        <dt>Button</dt>
+        <dd>{t('buttons.play', { default: 'Play' })}</dd>
+      </div>
+      <div>
+        <dt>Parameterized</dt>
+        <dd>{t('seek.forward', { seconds: 10, default: 'Seek forward {seconds} seconds' })}</dd>
+      </div>
+    </dl>
+  );
+}
+
+export default function BasicUsage() {
+  const [locale, setLocale] = useState<Locale>('es');
+
+  return (
+    <div className="react-use-translator-basic">
+      <label>
+        Language
+        <select value={locale} onChange={(event) => setLocale(event.currentTarget.value as Locale)}>
+          <option value="es">Spanish</option>
+          <option value="fr">French</option>
+        </select>
+      </label>
+      <I18nProvider locale={locale} translations={translations[locale]}>
+        <Labels />
+      </I18nProvider>
+    </div>
+  );
+}
+```
+```
+.react-use-translator-basic {
+  display: grid;
+  gap: 16px;
+  padding: 16px;
+}
+
+.react-use-translator-basic label,
+.react-use-translator-basic__output div {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+}
+
+.react-use-translator-basic select {
+  padding: 4px 8px;
+}
+
+.react-use-translator-basic__output {
+  display: grid;
+  gap: 8px;
+  margin: 0;
+}
+
+.react-use-translator-basic__output dt {
+  color: #6b7280;
+}
+
+.react-use-translator-basic__output dd {
+  margin: 0;
+}
+```
+
+## API Reference
+
+### Return Value
+
+`Translator`