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

package/docs/reference/api/use-optional-player.md

@@ -0,0 +1,63 @@
+# useOptionalPlayer
+
+Hook to access or select Player state when a Player is available
+
+## Import
+
+```tsx
+import { useOptionalPlayer } from "@videojs/react";
+```
+
+## Usage
+
+Without a selector, the hook returns the player store or `undefined` outside `Player`.
+
+```tsx
+const store = useOptionalPlayer();
+```
+
+With a selector, it subscribes while a player is available and returns the selected value. The selector is not called outside `Player`.
+
+```tsx
+import { selectPlayback, useOptionalPlayer } from "@videojs/react";
+
+const playback = useOptionalPlayer(selectPlayback);
+```
+
+Use `usePlayer` when the component requires a surrounding player.
+
+## API Reference
+
+### Without Selector
+
+`useOptionalPlayer(): UnknownStore | undefined`
+
+Returns the player store when available, or `undefined` outside a Player.
+
+#### Return Value
+
+| Property | Type |
+| --- | --- |
+| `$state` | `{ current: Readonly<UnknownState>; subscribe(callback: (() => void), options?: SubscribeOptions): (() => void) }` |
+| `target` | `unknown \| null` |
+| `destroyed` | `boolean` |
+| `state` | `Record<string, unknown>` |
+| `attach` | `((target: unknown) => (() => void))` |
+| `destroy` | `(() => void)` |
+| `subscribe` | `((callback: StateChange, options?: SubscribeOptions) => (() => void))` |
+
+### With Selector
+
+`useOptionalPlayer<R>(selector): R | undefined`
+
+Selects a player value when available, or returns `undefined` outside a Player.
+
+#### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `selector` (required) | `((state: UnknownState) => R)` | — | Derives a value from the player store state. |
+
+#### Return Value
+
+`R | undefined`

package/docs/reference/api/use-playback-rate-options.md

@@ -0,0 +1,62 @@
+# usePlaybackRateOptions
+
+Hook to build playback rate menu options from the player playback rate state
+
+## Import
+
+```tsx
+import { usePlaybackRateOptions } from "@videojs/react";
+```
+
+`usePlaybackRateOptions` returns the current playback rate, the available options, and `setRate` / `setValue` callbacks for wiring rate selection into a menu. It returns `null` when the [playback rate feature](./feature-playback-rate.md) is not configured.
+
+**SpeedMenu.tsx**
+
+```tsx
+import { Menu, usePlaybackRateOptions } from "@videojs/react";
+
+function SpeedMenu() {
+  const playbackRate = usePlaybackRateOptions();
+  if (playbackRate?.state.availability !== "available") return null;
+
+  return (
+    <Menu.RadioGroup value={playbackRate.value} onValueChange={playbackRate.setValue} aria-label="Speed">
+      {playbackRate.options.map((option) => (
+        <Menu.RadioItem key={option.value} value={option.value} disabled={option.disabled}>
+          {option.label}
+          <Menu.ItemIndicator checked={option.value === playbackRate.value} />
+        </Menu.RadioItem>
+      ))}
+    </Menu.RadioGroup>
+  );
+}
+```
+
+Options come from the player’s configured playback rates. Labels default to the rate followed by a multiplication sign (e.g. `1.5×`); pass `formatRate` to customize them. `setValue` accepts an option’s string value, while `setRate` accepts a number directly.
+
+See [PlaybackRateRadioGroup](../components/playback-rate-radio-group.md) for the component-level pattern, and [Menu](../components/menu.md) for a complete settings menu example.
+
+## API Reference
+
+`usePlaybackRateOptions(props?): PlaybackRateOptionsResult | null`
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `props` | `{ label?: Text \| string \| ((state: PlaybackRateRadioGroupState) => Text \| string); formatRate?: ((rate: number) => string); disabled?: boolean }` | — | Optional `label`, `formatRate`, and `disabled` overrides. |
+
+### Return Value
+
+| Property | Type |
+| --- | --- |
+| `state` | `{ label: Text \| string; value: string; options: readonly Option[]; disabled: boolean; hidden: boolean; availability: 'available' \| 'unavailable'; rate: number }` |
+| `label` | `string` |
+| `rate` | `number` |
+| `value` | `string` |
+| `selectedLabel` | `string` |
+| `options` | `PlaybackRateOption[]` |
+| `disabled` | `boolean` |
+| `hidden` | `boolean` |
+| `setRate` | `((rate: number) => void)` |
+| `setValue` | `((value: string) => void)` |

package/docs/reference/api/use-player.md

@@ -0,0 +1,224 @@
+# usePlayer
+
+Hook to access the player store from within a Player
+
+## Import
+
+```tsx
+import { usePlayer } from "@videojs/react";
+```
+
+The `usePlayer` hook returned by [`createPlayer`](./create-player.md) gives you access to the player store from any component within its `Player`. It’s typed to the features you passed to `createPlayer`, and has two overloads — without arguments for direct store access, or with a selector for reactive state subscriptions.
+
+```tsx
+const { Player, usePlayer } = createPlayer({ features: videoFeatures });
+```
+
+The pair works exactly like React Context: [`Player`](../components/player.md) is the Provider, and `usePlayer` is its `useContext`-style consumer, so the calling component must render inside `Player`. You can still read state anywhere: `Player` renders no DOM of its own, so lift it above every component that needs player state, the way you’d lift any Provider.
+
+`usePlayer` is also available as a standalone import (`import { usePlayer } from '@videojs/react'`), but the standalone version returns an untyped `UnknownStore`. Pass a premade selector to recover typing:
+
+```tsx
+import { usePlayer, selectPlayback } from '@videojs/react';
+
+usePlayer();               // UnknownStore (state: unknown)
+usePlayer(selectPlayback); // MediaPlaybackState | undefined
+```
+
+## Examples
+
+### Store Access
+
+Call `usePlayer()` without arguments to get the store instance. Use this for imperative actions like play, pause, and volume changes. The component does not re-render on state changes.
+
+**App.tsx**
+
+```tsx
+import { Container, createPlayer } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player, usePlayer } = createPlayer({
+  features: videoFeatures,
+});
+
+function Controls() {
+  const store = usePlayer();
+
+  return (
+    <div className="controls">
+      <button type="button" onClick={() => store.play()}>
+        Play
+      </button>
+      <button type="button" onClick={() => store.pause()}>
+        Pause
+      </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 />
+        <Controls />
+      </Container>
+    </Player>
+  );
+}
+```
+
+**App.css**
+
+```css
+.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;
+  color: #111827;
+  cursor: pointer;
+  background: white;
+  border: 1px solid #ccc;
+  border-radius: 6px;
+}
+```
+
+### Selector Subscription
+
+Pass a selector function to subscribe to specific state. The component re-renders when the selected value changes, using shallow equality by default.
+
+**App.tsx**
+
+```tsx
+import { Container, createPlayer } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player, usePlayer } = createPlayer({
+  features: videoFeatures,
+});
+
+function StateDisplay() {
+  const state = usePlayer((s) => ({
+    paused: s.paused,
+    currentTime: s.currentTime,
+    duration: s.duration,
+  }));
+
+  return (
+    <dl className="panel">
+      <div>
+        <dt>Paused</dt>
+        <dd>{String(state.paused)}</dd>
+      </div>
+      <div>
+        <dt>Time</dt>
+        <dd>
+          {state.currentTime.toFixed(1)}s / {state.duration.toFixed(1)}s
+        </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 />
+        <StateDisplay />
+      </Container>
+    </Player>
+  );
+}
+```
+
+**App.css**
+
+```css
+.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
+
+`usePlayer(): UnknownStore`
+
+Access the player store from within a Player.
+
+This standalone hook has no knowledge of your configured features, so it returns an untyped `UnknownStore` whose state properties are typed as `unknown`. For typed access, use the `usePlayer` returned by `createPlayer()`, or pass a premade selector to recover the type from its return value.
+
+#### Return Value
+
+| Property | Type |
+| --- | --- |
+| `$state` | `{ current: Readonly<UnknownState>; subscribe(callback: (() => void), options?: SubscribeOptions): (() => void) }` |
+| `target` | `unknown \| null` |
+| `destroyed` | `boolean` |
+| `state` | `Record<string, unknown>` |
+| `attach` | `((target: unknown) => (() => void))` |
+| `destroy` | `(() => void)` |
+| `subscribe` | `((callback: StateChange, options?: SubscribeOptions) => (() => void))` |
+
+### With Selector
+
+`usePlayer<R>(selector): R`
+
+Select a value from the player store. Re-renders when the selected value changes.
+
+The selector receives `UnknownState`, so an inline selector returns `unknown`. Pass a premade selector (e.g. `selectPlayback`) to get a typed result.
+
+#### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `selector` (required) | `((state: UnknownState) => R)` | — | Derives a value from the player store state. |
+
+#### Return Value
+
+`R`

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

@@ -0,0 +1,60 @@
+# useQualityOptions
+
+Hook to build video quality menu options from the player rendition state
+
+## Import
+
+```tsx
+import { useQualityOptions } from "@videojs/react";
+```
+
+`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**
+
+```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](../components/quality-radio-group.md) for the component-level pattern, and [Menu](../components/menu.md) for a complete settings menu example.
+
+## API Reference
+
+`useQualityOptions(props?): QualityOptionsResult | null`
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `props` | `{ label?: Text \| string \| ((state: QualityRadioGroupState) => Text \| string); formatRendition?: ((rendition: MediaVideoRendition) => Text \| string); disabled?: boolean }` | — | Optional `label`, `formatRendition`, and `disabled` overrides. |
+
+### Return Value
+
+| Property | Type |
+| --- | --- |
+| `state` | `{ label: Text \| string; value: string; options: readonly Option[]; disabled: boolean; hidden: boolean; availability: 'available' \| 'unavailable' }` |
+| `label` | `string` |
+| `value` | `string` |
+| `selectedLabel` | `string` |
+| `options` | `QualityOption[]` |
+| `disabled` | `boolean` |
+| `hidden` | `boolean` |
+| `setValue` | `((value: string) => void)` |

package/docs/reference/api/use-selector.md

@@ -0,0 +1,65 @@
+# useSelector
+
+Low-level hook for subscribing to derived state with customizable equality checks
+
+## Import
+
+```tsx
+import { useSelector } from "@videojs/react";
+```
+
+`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**
+
+```tsx
+import { useSelector, shallowEqual } from "@videojs/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
+
+`useSelector<S, R>(subscribe, getSnapshot, selector, isEqual?): R`
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `subscribe` (required) | `((cb: (() => void)) => (() => void))` | — | Subscribe function that returns an unsubscribe callback. |
+| `getSnapshot` (required) | `(() => S)` | — | Returns the current snapshot value. |
+| `selector` (required) | `{ (state: S): R; displayName?: string }` | — | Derives a value from the snapshot. |
+| `isEqual` | `((a: R, b: R) => boolean)` | `shallowEqual` | Custom equality function. Defaults to `shallowEqual`. |
+
+### Return Value
+
+`R`

package/docs/reference/api/use-slider.md

@@ -0,0 +1,70 @@
+# useSlider
+
+Hook for connecting slider input behavior to custom React elements
+
+`useSlider` is the low-level hook behind the [Slider](../components/slider.md), [TimeSlider](../components/time-slider.md), and [VolumeSlider](../components/volume-slider.md) components. Use it when you need to build a new slider primitive with custom state calculations. For standard player controls, use the built-in components.
+
+## Import
+
+```tsx
+import { useSlider } from "@videojs/react";
+```
+
+## Usage
+
+Pass callbacks that convert raw slider input into your component state, values, and CSS variables. Attach the returned root props, ref, and styles to the pointer target. Attach the thumb props and ref to the focusable thumb.
+
+```tsx
+function CustomSlider({ options }: { options: useSlider.Options }) {
+  const {
+    state,
+    input,
+    cssVars,
+    rootRef,
+    thumbRef,
+    rootProps,
+    rootStyle,
+    thumbProps,
+  } = useSlider(options);
+
+  return (
+    <div
+      ref={rootRef}
+      {...rootProps}
+      style={{ ...cssVars, ...rootStyle }}
+      data-dragging={state.dragging || undefined}
+    >
+      <div
+        ref={thumbRef}
+        {...thumbProps}
+        data-focused={input.current.focused || undefined}
+      />
+    </div>
+  );
+}
+```
+
+`state` is the derived state for the current render. `input` is the underlying reactive state container. Read `input.current` for the latest raw input or call `input.subscribe(listener)` when another system needs to observe changes outside React rendering.
+
+## API Reference
+
+`useSlider<State extends SliderState = SliderState>(options): UseSliderReturnValue<State>`
+
+### Parameters
+
+| Parameter | Type | Default |
+| --- | --- | --- |
+| `options` (required) | `{ getPercent: (() => number); getStepPercent: (() => number); getLargeStepPercent: (() => number); changeThrottle?: number; onValueChange?: ((percent: number) => void); onValueCommit?: ((percent: number) => void); onPressStart?: (() => void); onPressEnd?: (() => void); onDragStart?: (() => void); onDragEnd?: (() => void); computeState: ((input: SliderInput) => State); orientation?: 'horizontal' \| 'vertical'; disabled?: boolean; adjustPercent?: ((rawPercent: number, thumbSize: number, trackSize: number) => number); getCSSVars: ((state: State) => Record<string, string>) }` | — |
+
+### Return Value
+
+| Property | Type |
+| --- | --- |
+| `state` | `State` |
+| `input` | `State<SliderInput>` |
+| `cssVars` | `Record<string, string>` |
+| `rootRef` | `RefCallback<HTMLElement>` |
+| `thumbRef` | `RefCallback<HTMLElement>` |
+| `rootProps` | `{ onPointerDown: ((event: UIPointerEvent) => void); onPointerMove: ((event: UIPointerEvent) => void); onPointerUp: ((event: UIPointerEvent) => void); onPointerLeave: ((event: UIPointerEvent) => void); onLostPointerCapture: (() => void) }` |
+| `rootStyle` | `{ touchAction: string; userSelect: string }` |
+| `thumbProps` | `{ onKeyDownCapture: ((event: UIKeyboardEvent) => void); onFocus: (() => void); onBlur: (() => void) }` |

package/docs/reference/api/use-snapshot.md

@@ -0,0 +1,76 @@
+# useSnapshot
+
+Hook to subscribe to a State container's current value
+
+## Import
+
+```tsx
+import { useSnapshot } from "@videojs/store/react";
+```
+
+`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
+
+`useSnapshot<T extends object>(state): T`
+
+#### Parameters
+
+| Parameter | Type | Default |
+| --- | --- | --- |
+| `state` (required) | `{ current: Readonly<T>; subscribe(callback: (() => void), options?: SubscribeOptions): (() => void) }` | — |
+
+#### Return Value
+
+`T`
+
+### With Selector
+
+`useSnapshot<T extends object, R>(state, selector, isEqual?): R`
+
+Select a value from state. Re-renders when the selected value changes.
+
+#### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `state` (required) | `{ current: Readonly<T>; subscribe(callback: (() => void), options?: SubscribeOptions): (() => void) }` | — | |
+| `selector` (required) | `{ (state: T): R; displayName?: string }` | — | Derives a value from state. |
+| `isEqual` | `((a: R, b: R) => boolean)` | — | Custom equality function. Defaults to `shallowEqual`. |
+
+#### Return Value
+
+`R`