From 8c447e2e5a6d4874cbc8a671b2ded1131ca6e03d Mon Sep 17 00:00:00 2001 From: Manuel Calleriza Date: Fri, 5 Jun 2026 16:01:15 -0300 Subject: [PATCH 1/2] docs(react): clarify usePlayer typed vs untyped store access Add a note callout on the use-player reference page contrasting the typed Player.usePlayer (from createPlayer) with the untyped standalone usePlayer, and enrich the standalone hook's JSDoc so the generated reference explains the UnknownStore return and selector-based typing. Refs #1483 --- packages/react/src/player/context.tsx | 8 ++++++++ site/src/content/docs/reference/use-player.mdx | 13 +++++++++++++ 2 files changed, 21 insertions(+) diff --git a/packages/react/src/player/context.tsx b/packages/react/src/player/context.tsx index c72d005fc..bffe1ba30 100644 --- a/packages/react/src/player/context.tsx +++ b/packages/react/src/player/context.tsx @@ -45,12 +45,20 @@ export function usePlayerContext(): PlayerContextValue { /** * Access the player store from within a Player Provider. * + * 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. + * * @label Without Selector */ export function usePlayer(): UnknownStore; /** * 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. + * * @label With Selector * @param selector - Derives a value from the player store state. */ diff --git a/site/src/content/docs/reference/use-player.mdx b/site/src/content/docs/reference/use-player.mdx index d533f8a7c..306acd2dd 100644 --- a/site/src/content/docs/reference/use-player.mdx +++ b/site/src/content/docs/reference/use-player.mdx @@ -4,6 +4,7 @@ description: Hook to access the player store from within a Player.Provider --- import UtilReference from "@/components/docs/api-reference/UtilReference.astro"; +import Aside from "@/components/Aside.astro"; import Demo from "@/components/docs/demos/Demo.astro"; import DocsLink from "@/components/docs/DocsLink.astro"; import FrameworkCase from "@/components/docs/FrameworkCase.astro"; @@ -17,6 +18,18 @@ import selectorReactCss from "@/components/docs/demos/use-player/react/css/Selec `Player.usePlayer` gives you access to the player store from any component within a `Player.Provider`. It has two overloads — without arguments for direct store access, or with a selector for reactive state subscriptions. `Player.usePlayer` is typed to the features you passed to `createPlayer`. It's also available as a standalone import (`import { usePlayer } from '@videojs/react'`), but the standalone version returns an untyped store. + + +```tsx +import { usePlayer } from '@videojs/react'; +import { selectPlayback } from '@videojs/core/dom'; + +usePlayer(); // UnknownStore (state: unknown) +usePlayer(selectPlayback); // PlaybackState | undefined +``` + ## Examples ### Store Access From 3a5b74071b8a96dcb93997d950046aa1a0e9ed64 Mon Sep 17 00:00:00 2001 From: Manuel Calleriza Date: Mon, 15 Jun 2026 17:02:14 -0300 Subject: [PATCH 2/2] docs(site): fold usePlayer typed/untyped note into prose Address PR review: drop the redundant aside in favor of a two-paragraph intro plus example, and import selectPlayback from @videojs/react rather than @videojs/core/dom (which isn't part of the public API surface). Refs #1483 --- site/src/content/docs/reference/use-player.mdx | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/site/src/content/docs/reference/use-player.mdx b/site/src/content/docs/reference/use-player.mdx index 306acd2dd..4f9e25d63 100644 --- a/site/src/content/docs/reference/use-player.mdx +++ b/site/src/content/docs/reference/use-player.mdx @@ -4,7 +4,6 @@ description: Hook to access the player store from within a Player.Provider --- import UtilReference from "@/components/docs/api-reference/UtilReference.astro"; -import Aside from "@/components/Aside.astro"; import Demo from "@/components/docs/demos/Demo.astro"; import DocsLink from "@/components/docs/DocsLink.astro"; import FrameworkCase from "@/components/docs/FrameworkCase.astro"; @@ -16,15 +15,12 @@ import SelectorDemoReact from "@/components/docs/demos/use-player/react/css/Sele import selectorReactTsx from "@/components/docs/demos/use-player/react/css/Selector.tsx?raw"; import selectorReactCss from "@/components/docs/demos/use-player/react/css/Selector.css?raw"; -`Player.usePlayer` gives you access to the player store from any component within a `Player.Provider`. It has two overloads — without arguments for direct store access, or with a selector for reactive state subscriptions. `Player.usePlayer` is typed to the features you passed to `createPlayer`. It's also available as a standalone import (`import { usePlayer } from '@videojs/react'`), but the standalone version returns an untyped store. +`Player.usePlayer` (from `createPlayer`) gives you access to the player store from any component within a `Player.Provider`. 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. - +`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 } from '@videojs/react'; -import { selectPlayback } from '@videojs/core/dom'; +import { usePlayer, selectPlayback } from '@videojs/react'; usePlayer(); // UnknownStore (state: unknown) usePlayer(selectPlayback); // PlaybackState | undefined