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

package/docs/reference/use-button.md

@@ -91,7 +91,7 @@ Details
 
 `params*`
 
-`UseButtonParameters`
+`function`
 
 `—`
 
@@ -101,6 +101,10 @@ Description
 
 Button configuration with activation handler and disabled check.
 
+Type
+
+`{ displayName: string; onActivate: ((event: UIEvent) => void); isDisabled: (() => boolean) }`
+
 ### Return Value
 
 Property
@@ -117,7 +121,7 @@ Details
 
 Type
 
-`((externalProps: ComponentPropsWithRef<ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement> | undefined) => DetailedHTMLProps<ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>)`
+`((externalProps?: ComponentPropsWithRef<'button'>) => ComponentPropsWithRef<'button'>)`
 
 `buttonRef`
 

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

@@ -44,7 +44,7 @@ Details
 
 `props`
 
-`CaptionsOptionsProps`
+`object`
 
 `—`
 
@@ -56,4 +56,50 @@ Optional `label`, `formatTrack`, and `disabled` overrides.
 
 ### Return Value
 
-`CaptionsOptionsResult | null`
+Property
+
+Type
+
+Details
+
+`state`
+
+`CaptionsRadioGroupCore.State`
+
+`label`
+
+`string`
+
+`value`
+
+`string`
+
+`selectedLabel`
+
+`string`
+
+`options`
+
+`CaptionsOption[]`
+
+`disabled`
+
+`boolean`
+
+`hidden`
+
+`boolean`
+
+`showMenu`
+
+`boolean`
+
+`setValue`
+
+`function`
+
+▸
+
+Type
+
+`((value: string) => void)`

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

@@ -0,0 +1,59 @@
+# 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
+
+### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`refs`
+
+`unknown`
+
+`—`
+
+▸
+
+Description
+
+Refs to update from the returned callback.
+
+### Return Value
+
+`RefCallback<T>`

package/docs/reference/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
+
+```
+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
+
+### Return Value
+
+`object | null`

package/docs/reference/use-destroy.md

@@ -0,0 +1,89 @@
+# 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
+
+### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`instance*`
+
+`{ destroy(): void }`
+
+`—`
+
+▸
+
+Description
+
+Object with a `destroy()` method.
+
+`setup`
+
+`function`
+
+`—`
+
+▸
+
+Description
+
+Optional setup called on first mount. Skipped on StrictMode re-mount since the previous setup was never torn down.
+
+Type
+
+`(() => void)`
+
+`teardown`
+
+`function`
+
+`—`
+
+▸
+
+Description
+
+Optional teardown called right before `destroy()` on real unmount. Skipped on StrictMode simulated unmount.
+
+Type
+
+`(() => void)`
+
+### Return Value
+
+`void`

package/docs/reference/use-dialog-context.md

@@ -0,0 +1,63 @@
+# useDialogContext
+
+Hook to access the nearest dialog compound-component context
+
+## Import
+
+tsx
+
+```
+import { useDialogContext } from "@videojs/react";
+```
+
+## Usage
+
+Use this hook to build a custom part inside `Dialog.Root`, `AlertDialog.Root`, or `ErrorDialog.Root`.
+
+tsx
+
+```
+function CustomCloseButton() {
+  const { dialog } = useDialogContext();
+
+  return <button onClick={() => dialog.close()}>Close</button>;
+}
+```
+
+The hook throws when there is no surrounding dialog root.
+
+## API Reference
+
+### Return Value
+
+Property
+
+Type
+
+Details
+
+`core`
+
+`DialogCore`
+
+`dialog`
+
+`object`
+
+▸
+
+Type
+
+`{ input: State<DialogInput>; triggerProps: DialogTriggerProps; open(): void; close(): void; setTriggerElement(el: HTMLElement | null): void; setPopupElement(el: HTMLElement | null): void; destroy(): void }`
+
+`state`
+
+`DialogCore.State`
+
+`stateAttrMap`
+
+`{ [Key in keyof State]?: string; }`
+
+`popupId`
+
+`string`

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

@@ -0,0 +1,75 @@
+# 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
+
+### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`onActivate*`
+
+`function`
+
+`—`
+
+▸
+
+Description
+
+Callback invoked when a matching double tap is recognized.
+
+Type
+
+`((event: PointerEvent) => void)`
+
+`options`
+
+`object`
+
+`—`
+
+▸
+
+Description
+
+Gesture matching, target, and disabled options.
+
+Type
+
+`{ target?: RefObject<HTMLElement | null> }`
+
+### Return Value
+
+`void`

package/docs/reference/use-error-dialog-context.md

@@ -0,0 +1,41 @@
+# useErrorDialogContext
+
+Hook to access the nearest ErrorDialog compound-component context
+
+## Import
+
+tsx
+
+```
+import { useErrorDialogContext } from "@videojs/react";
+```
+
+## Usage
+
+Use this hook to build a custom part rendered inside `ErrorDialog.Root`.
+
+tsx
+
+```
+function ErrorCode() {
+  const { lastError } = useErrorDialogContext();
+
+  return lastError ? <code>{lastError.code}</code> : null;
+}
+```
+
+The hook throws when there is no surrounding `ErrorDialog.Root`.
+
+## API Reference
+
+### Return Value
+
+Property
+
+Type
+
+Details
+
+`lastError`
+
+`ErrorLike | null`

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

@@ -0,0 +1,79 @@
+# 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
+
+### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`action*`
+
+`string | undefined`
+
+`—`
+
+▸
+
+Description
+
+Hotkey action to look up. Returns empty details when absent.
+
+`value`
+
+`number`
+
+`—`
+
+▸
+
+Description
+
+Optional action value used to match value-dependent shortcuts.
+
+### Return Value
+
+Property
+
+Type
+
+Details
+
+`aria`
+
+`string`
+
+`shortcut`
+
+`string`

package/docs/reference/use-hotkey.md

@@ -0,0 +1,62 @@
+# 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
+
+### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`options*`
+
+`object`
+
+`—`
+
+▸
+
+Description
+
+Shortcut keys, activation callback, scope, repeat behavior, and disabled state.
+
+Type
+
+`{ keys: string; onActivate: ((event: KeyboardEvent, key: string) => void); target?: 'player' | 'document'; repeatable?: boolean; disabled?: boolean }`
+
+### Return Value
+
+`void`

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

@@ -0,0 +1,73 @@
+# 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
+
+### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`value*`
+
+`Value`
+
+`—`
+
+▸
+
+Description
+
+Value the ref should expose after each render.
+
+### Return Value
+
+Property
+
+Type
+
+Details
+
+`current`
+
+`Value`

package/docs/reference/use-locale.md

@@ -31,6 +31,7 @@ import { useState } from 'react';
 import './BasicUsage.css';
 
 const locales = ['en-US', 'fr-FR', 'ja-JP'] as const;
+
 type Locale = (typeof locales)[number];
 
 function LocaleDetails() {
@@ -115,10 +116,10 @@ Type
 
 Details
 
-`string & object | 'ar' | 'az' | 'bs' ...`
+`(typeof LOCALES)[number] | string & o...`
 
 ▸
 
 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'`
+`(typeof LOCALES)[number] | string & object`