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

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

@@ -0,0 +1,101 @@
+# useButton
+
+Hook for creating accessible button components with keyboard and pointer interaction
+
+## Import
+
+```tsx
+import { useButton } from "@videojs/react";
+```
+
+`useButton` provides button behavior including keyboard activation and accessibility checks. It returns a `getButtonProps` function for spreading onto a `<button>` element and a `buttonRef` for validation.
+
+`getButtonProps` merges internal button props (click/keyboard handlers, disabled state) with any external props you pass in. Use [`renderElement`](./render-element.md) to render the button with state-driven props and render prop support. In development mode, `buttonRef` warns if the rendered element is not a `<button>`.
+
+## Examples
+
+### Basic Usage
+
+**App.tsx**
+
+```tsx
+import { useButton } from '@videojs/react';
+import type { Ref } from 'react';
+import { useState } from 'react';
+
+export default function BasicUsage() {
+  const [count, setCount] = useState(0);
+  const [disabled, setDisabled] = useState(false);
+
+  const { getButtonProps, buttonRef } = useButton({
+    displayName: 'ActivateButton',
+    onActivate: () => setCount((c) => c + 1),
+    isDisabled: () => disabled,
+  });
+
+  return (
+    <div className="demo">
+      <button ref={buttonRef as Ref<HTMLButtonElement>} {...getButtonProps()} className="button" disabled={disabled}>
+        Activated {count} times
+      </button>
+      <label className="label">
+        <input type="checkbox" checked={disabled} onChange={(e) => setDisabled(e.target.checked)} />
+        Disabled
+      </label>
+    </div>
+  );
+}
+```
+
+**App.css**
+
+```css
+.demo {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  padding: 16px;
+}
+
+.button {
+  align-self: flex-start;
+  padding: 8px 20px;
+  font-variant-numeric: tabular-nums;
+  color: #111827;
+  cursor: pointer;
+  background: #f5f5f5;
+  border: 1px solid #ccc;
+  border-radius: 6px;
+  transition: opacity 0.2s;
+}
+
+.button[disabled] {
+  cursor: not-allowed;
+  opacity: 0.5;
+}
+
+.label {
+  display: flex;
+  gap: 6px;
+  align-items: center;
+  font-size: 0.875rem;
+  color: #6b7280;
+}
+```
+
+## API Reference
+
+`useButton(params): UseButtonReturnValue`
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `params` (required) | `{ displayName: string; onActivate: ((event: UIEvent, source: ButtonActivationSource) => void); isDisabled: (() => boolean) }` | — | Button configuration with activation handler and disabled check. |
+
+### Return Value
+
+| Property | Type |
+| --- | --- |
+| `getButtonProps` | `((externalProps?: ComponentPropsWithRef<'button'>) => ComponentPropsWithRef<'button'>)` |
+| `buttonRef` | `Ref<HTMLElement>` |

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

@@ -0,0 +1,61 @@
+# useCaptionsOptions
+
+Hook to build captions menu options from the player text track state
+
+## Import
+
+```tsx
+import { useCaptionsOptions } from "@videojs/react";
+```
+
+`useCaptionsOptions` returns the currently showing caption track, the available options (starting with an `Off` option), and a `setValue` callback for wiring caption selection into a menu. It returns `null` when the [text tracks feature](./feature-text-tracks.md) is not configured.
+
+**CaptionsMenu.tsx**
+
+```tsx
+import { Menu, useCaptionsOptions } from "@videojs/react";
+
+function CaptionsMenu() {
+  const captions = useCaptionsOptions();
+  if (captions?.state.availability !== "available") return null;
+
+  return (
+    <Menu.RadioGroup value={captions.value} onValueChange={captions.setValue} aria-label="Captions">
+      {captions.options.map((option) => (
+        <Menu.RadioItem key={option.value} value={option.value} disabled={option.disabled}>
+          {option.label}
+          <Menu.ItemIndicator checked={option.value === captions.value} />
+        </Menu.RadioItem>
+      ))}
+    </Menu.RadioGroup>
+  );
+}
+```
+
+Option labels use the track label, then language, then kind. Pass `formatTrack` to customize the visible labels. The result also exposes `showMenu`, which is `true` when more than one caption or subtitle track is available — the same threshold [CaptionsButton](../components/captions-button.md) uses to open a menu instead of toggling in `menuTrigger` mode.
+
+See [CaptionsRadioGroup](../components/captions-radio-group.md) for the component-level pattern, and [Menu](../components/menu.md) for a complete settings menu example.
+
+## API Reference
+
+`useCaptionsOptions(props?): CaptionsOptionsResult | null`
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `props` | `{ label?: Text \| string \| ((state: CaptionsRadioGroupState) => Text \| string); formatTrack?: ((track: MediaTextTrack) => Text \| string); disabled?: boolean }` | — | Optional `label`, `formatTrack`, and `disabled` overrides. |
+
+### Return Value
+
+| Property | Type |
+| --- | --- |
+| `state` | `{ subtitlesShowing: boolean; label: Text \| string; value: string; options: readonly Option[]; disabled: boolean; hidden: boolean; availability: 'available' \| 'unavailable' }` |
+| `label` | `string` |
+| `value` | `string` |
+| `selectedLabel` | `string` |
+| `options` | `CaptionsOption[]` |
+| `disabled` | `boolean` |
+| `hidden` | `boolean` |
+| `showMenu` | `boolean` |
+| `setValue` | `((value: string) => void)` |

package/docs/reference/api/use-composed-refs.md

@@ -0,0 +1,41 @@
+# useComposedRefs
+
+Hook that updates multiple React refs through one stable callback ref
+
+## Import
+
+```tsx
+import { useComposedRefs } from "@videojs/react";
+```
+
+## Usage
+
+Compose an internal ref with a forwarded ref when both need the same element.
+
+```tsx
+import { forwardRef, useRef } from "react";
+import { useComposedRefs } from "@videojs/react";
+
+const Video = forwardRef<HTMLVideoElement>(function Video(_, forwardedRef) {
+  const localRef = useRef<HTMLVideoElement>(null);
+  const ref = useComposedRefs(forwardedRef, localRef);
+
+  return <video ref={ref} />;
+});
+```
+
+The callback updates callback refs and ref objects. It also preserves cleanup functions returned by React 19 callback refs.
+
+## API Reference
+
+`useComposedRefs<T>(...refs): RefCallback<T>`
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `refs` | `(Ref<T> \| undefined)[]` | — | Refs to update from the returned callback. |
+
+### Return Value
+
+`RefCallback<T>`

package/docs/reference/api/use-container-attach.md

@@ -0,0 +1,42 @@
+# useContainerAttach
+
+Hook to register a custom container element with the player context
+
+## Import
+
+```tsx
+import { useContainerAttach } from "@videojs/react";
+```
+
+`useContainerAttach` returns a setter function for registering a DOM element as the player’s container. The built-in `Container` uses this internally; you only need it when building a custom container element.
+
+**CustomContainer.tsx**
+
+```tsx
+import { useContainerAttach } from "@videojs/react";
+
+function CustomContainer({ children }: { children: React.ReactNode }) {
+  const setContainer = useContainerAttach();
+  return <div ref={setContainer}>{children}</div>;
+}
+```
+
+## Who needs this
+
+You only need `useContainerAttach` if you’re replacing the built-in `Container` with a custom element. For example, if you’re building a container with custom fullscreen behavior or a non-standard layout boundary.
+
+For standard player layouts, use the built-in `Container`.
+
+## Safe outside Player
+
+Returns `undefined` when called outside `Player`. Passing `undefined` to `ref` is harmless in React. Check the return value if your component needs to know whether it’s inside a player.
+
+## API Reference
+
+`useContainerAttach(): Dispatch<SetStateAction<HTMLElement | null>> | undefined`
+
+### Return Value
+
+| Type |
+| --- |
+| `Dispatch<SetStateAction<HTMLElement \| null>> \| undefined` |

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

@@ -0,0 +1,39 @@
+# useContainer
+
+Hook to access the media container from the nearest Player
+
+`useContainer` returns the `MediaContainer` registered with the nearest `Player`. It returns `null` until the container mounts, or whenever that player has no registered container.
+
+## Import
+
+```tsx
+import { useContainer } from "@videojs/react";
+```
+
+## Usage
+
+Call `useContainer` from a component rendered inside `Player`:
+
+**ContainerStatus.tsx**
+
+```tsx
+import { useContainer } from "@videojs/react";
+
+export function ContainerStatus() {
+  const container = useContainer();
+
+  return <output>{container ? "Player container ready" : "Mounting container"}</output>;
+}
+```
+
+Calling this hook outside `Player` throws because it reads through `usePlayerContext`. If a component can also work outside a player, use [`useOptionalContainer`](./use-optional-container.md) instead.
+
+`useContainer` reads the registered container. [`useContainerAttach`](./use-container-attach.md) returns the setter used to register a custom container and is only needed when replacing the built-in `Container`.
+
+## API Reference
+
+`useContainer(): MediaContainer | null`
+
+### Return Value
+
+`MediaContainer | null`

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

@@ -0,0 +1,41 @@
+# useDestroy
+
+Hook that destroys an imperative instance after a real React unmount
+
+## Import
+
+```tsx
+import { useDestroy } from "@videojs/react";
+```
+
+## Usage
+
+Pass an object with a `destroy()` method. Optional setup and teardown callbacks run around the instance’s mounted lifetime.
+
+```tsx
+type Destroyable = { destroy(): void };
+
+function ManagedInstance({ instance }: { instance: Destroyable }) {
+  useDestroy(instance);
+
+  return null;
+}
+```
+
+Destruction is deferred to a macrotask so React StrictMode’s simulated unmount and remount can cancel it. A real unmount runs teardown before `destroy()`.
+
+## API Reference
+
+`useDestroy(instance, setup?, teardown?): void`
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `instance` (required) | `{ destroy(): void }` | — | Object with a `destroy()` method. |
+| `setup` | `(() => void)` | — | Optional setup called on first mount. Skipped on StrictMode re-mount since the previous setup was never torn down. |
+| `teardown` | `(() => void)` | — | Optional teardown called right before `destroy()` on real unmount. Skipped on StrictMode simulated unmount. |
+
+### Return Value
+
+`void`

package/docs/reference/api/use-double-tap-gesture.md

@@ -0,0 +1,38 @@
+# useDoubleTapGesture
+
+Hook that registers a double-tap gesture for the current Player
+
+## Import
+
+```tsx
+import { useDoubleTapGesture } from "@videojs/react";
+```
+
+## Usage
+
+Call the hook inside `Player`. It listens on the current player container unless `target` supplies another element.
+
+```tsx
+function DoubleTapFeedback() {
+  useDoubleTapGesture(() => console.log("Double tap"), { region: "right" });
+
+  return null;
+}
+```
+
+Use `pointer`, `region`, and `disabled` to control recognition. Supplying `target` does not make the hook safe outside `Player`, because it still reads the player container context.
+
+## API Reference
+
+`useDoubleTapGesture(onActivate, options?): void`
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `onActivate` (required) | `((event: PointerEvent) => void)` | — | Callback invoked when a matching double tap is recognized. |
+| `options` | `{ pointer?: 'mouse' \| 'touch' \| 'pen'; region?: 'left' \| 'center' \| 'right'; disabled?: boolean; target?: RefObject<HTMLElement \| null> }` | — | Gesture matching, target, and disabled options. |
+
+### Return Value
+
+`void`

package/docs/reference/api/use-hotkey-shortcut.md

@@ -0,0 +1,41 @@
+# useHotkeyShortcut
+
+Hook that reads display and ARIA metadata for a registered Player hotkey
+
+## Import
+
+```tsx
+import { useHotkeyShortcut } from "@videojs/react";
+```
+
+## Usage
+
+Look up a registered action to keep a custom control’s visible shortcut and `aria-keyshortcuts` value synchronized.
+
+```tsx
+function PlayShortcut() {
+  const { aria, shortcut } = useHotkeyShortcut("togglePaused");
+
+  return <button aria-keyshortcuts={aria}>Play ({shortcut})</button>;
+}
+```
+
+The hook subscribes to registration changes. It returns empty details when the player container or action is unavailable; pass `value` for actions with value-specific registrations.
+
+## API Reference
+
+`useHotkeyShortcut(action, value?): HotkeyShortcutDetails`
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `action` (required) | `string \| undefined` | — | Hotkey action to look up. Returns empty details when absent. |
+| `value` | `number` | — | Optional action value used to match value-dependent shortcuts. |
+
+### Return Value
+
+| Property | Type |
+| --- | --- |
+| `aria` | `string \| undefined` |
+| `shortcut` | `string \| undefined` |

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

@@ -0,0 +1,40 @@
+# useHotkey
+
+Hook that registers a keyboard shortcut for the current Player
+
+## Import
+
+```tsx
+import { useHotkey } from "@videojs/react";
+```
+
+## Usage
+
+Call the hook inside `Player` with the accepted keys and activation callback.
+
+```tsx
+function CustomPlayHotkey() {
+  useHotkey({
+    keys: "k",
+    onActivate: (_event, key) => console.log(`Activated by ${key}`),
+  });
+
+  return null;
+}
+```
+
+Shortcuts target the player by default and accept repeated keydown events. Set `target` to `"document"`, `repeatable` to `false`, or `disabled` to change those behaviors. The hook still requires a surrounding `Player` for its coordinator.
+
+## API Reference
+
+`useHotkey(options): void`
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `options` (required) | `{ keys: string; onActivate: ((event: KeyboardEvent, key: string) => void); target?: 'player' \| 'document'; repeatable?: boolean; disabled?: boolean }` | — | Shortcut keys, activation callback, scope, repeat behavior, and disabled state. |
+
+### Return Value
+
+`void`

package/docs/reference/api/use-latest-ref.md

@@ -0,0 +1,49 @@
+# useLatestRef
+
+Hook that exposes the latest rendered value through a stable ref
+
+## Import
+
+```tsx
+import { useLatestRef } from "@videojs/react";
+```
+
+## Usage
+
+Use a latest-value ref when a long-lived callback must read current props without recreating the subscription that owns it.
+
+```tsx
+import { useEffect } from "react";
+import { useLatestRef } from "@videojs/react";
+
+type SubscriberProps = {
+  onChange(value: number): void;
+  subscribe(callback: (value: number) => void): () => void;
+};
+
+function Subscriber({ onChange, subscribe }: SubscriberProps) {
+  const onChangeRef = useLatestRef(onChange);
+
+  useEffect(() => subscribe((value) => onChangeRef.current(value)), []);
+
+  return null;
+}
+```
+
+The ref object is stable across renders and its `current` property is updated during every render.
+
+## API Reference
+
+`useLatestRef<Value>(value): Readonly<{ current: Value }>`
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` (required) | `Value` | — | Value the ref should expose after each render. |
+
+### Return Value
+
+| Property | Type |
+| --- | --- |
+| `current` | `Value` |

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

@@ -0,0 +1,114 @@
+# useLocale
+
+React hook that returns the active BCP 47 locale from the nearest I18nProvider
+
+## Import
+
+```tsx
+import { useLocale } from "@videojs/react";
+```
+
+`useLocale` returns the resolved BCP 47 tag from the nearest [`I18nProvider`](./i18n-provider.md), or `'en'` when none is mounted.
+
+Use it when UI copy depends on the active locale outside the translator, for example formatting or caption language hooks.
+
+## Example
+
+Switch the provider locale to see `useLocale` supply the BCP 47 tag used to format a date.
+
+**App.tsx**
+
+```tsx
+import { I18nProvider, useLocale } from '@videojs/react/i18n';
+import { useState } from 'react';
+
+import './BasicUsage.css';
+
+const locales = ['en-US', 'fr-FR', 'ja-JP'] as const;
+
+type Locale = (typeof locales)[number];
+
+function LocaleDetails() {
+  const locale = useLocale();
+  const date = new Intl.DateTimeFormat(locale, {
+    dateStyle: 'long',
+    timeZone: 'UTC',
+  }).format(new Date('2026-01-15T12:00:00Z'));
+
+  return (
+    <dl className="react-use-locale-basic__output">
+      <div>
+        <dt>Active locale</dt>
+        <dd>{locale}</dd>
+      </div>
+      <div>
+        <dt>Formatted date</dt>
+        <dd lang={locale}>{date}</dd>
+      </div>
+    </dl>
+  );
+}
+
+export default function BasicUsage() {
+  const [locale, setLocale] = useState<Locale>('en-US');
+
+  return (
+    <div className="react-use-locale-basic">
+      <label>
+        Locale
+        <select value={locale} onChange={(event) => setLocale(event.currentTarget.value as Locale)}>
+          {locales.map((value) => (
+            <option key={value}>{value}</option>
+          ))}
+        </select>
+      </label>
+      <I18nProvider locale={locale}>
+        <LocaleDetails />
+      </I18nProvider>
+    </div>
+  );
+}
+```
+
+**App.css**
+
+```css
+.react-use-locale-basic {
+  display: grid;
+  gap: 16px;
+  padding: 16px;
+}
+
+.react-use-locale-basic label,
+.react-use-locale-basic__output div {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+}
+
+.react-use-locale-basic select {
+  padding: 4px 8px;
+}
+
+.react-use-locale-basic__output {
+  display: grid;
+  gap: 8px;
+  margin: 0;
+}
+
+.react-use-locale-basic__output dt {
+  color: #6b7280;
+}
+
+.react-use-locale-basic__output dd {
+  margin: 0;
+}
+```
+
+## API Reference
+
+`useLocale(): Locale`
+
+### Return Value
+
+`(typeof LOCALES)[number] | string & {}`

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

@@ -0,0 +1,31 @@
+# useOptionalContainer
+
+Hook to access a Player container when one is available
+
+## Import
+
+```tsx
+import { useOptionalContainer } from "@videojs/react";
+```
+
+## Usage
+
+Use the optional hook when a component can work both inside and outside `Player`.
+
+```tsx
+function ContainerAwareStatus() {
+  const container = useOptionalContainer();
+
+  return <output>{container ? "Player container ready" : "No container"}</output>;
+}
+```
+
+It returns `null` outside `Player`, before its container mounts, or when the player has no registered container. Use `useContainer` when a missing Player should be treated as an error.
+
+## API Reference
+
+`useOptionalContainer(): MediaContainer | null`
+
+### Return Value
+
+`MediaContainer | null`