@videojs/react 10.0.0-beta.23 → 10.0.0-beta.24

package/docs/reference/use-button.md

@@ -0,0 +1,124 @@
+# useButton
+
+Hook for creating accessible button components with keyboard and pointer interaction
+
+`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
+
+Activated 0 timesDisabled
+
+App.tsx
+
+App.css
+
+```
+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>
+  );
+}
+```
+```
+.demo {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  padding: 16px;
+}
+
+.button {
+  align-self: flex-start;
+  padding: 8px 20px;
+  font-variant-numeric: tabular-nums;
+  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
+
+### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`params*`
+
+`UseButtonParameters`
+
+`—`
+
+▸
+
+Description
+
+Button configuration with activation handler and disabled check.
+
+### Return Value
+
+Property
+
+Type
+
+Details
+
+`getButtonProps`
+
+`function`
+
+▸
+
+Type
+
+`((externalProps: ComponentPropsWithRef<ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement> | undefined) => DetailedHTMLProps<ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>)`
+
+`buttonRef`
+
+`Ref<HTMLElement>`

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

@@ -0,0 +1,42 @@
+# useContainerAttach
+
+Hook to register a custom container element with the player context
+
+`useContainerAttach` returns a setter function for registering a DOM element as the player’s container. The built-in `Player.Container` uses this internally; you only need it when building a custom container element.
+
+CustomContainer.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 `Player.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 `Player.Container`.
+
+## Safe outside Provider
+
+Returns `undefined` when called outside a Player `Provider`. Passing `undefined` to `ref` is harmless in React. Check the return value if your component needs to know whether it’s inside a provider.
+
+## API Reference
+
+### Return Value
+
+Type
+
+Details
+
+`Dispatch<SetStateAction<HTMLElement |...`
+
+▸
+
+Type
+
+`Dispatch<SetStateAction<HTMLElement | null>> | undefined`

package/docs/reference/use-media-attach.md

@@ -0,0 +1,46 @@
+# useMediaAttach
+
+Hook to register a custom media element with the player context
+
+`useMediaAttach` returns a setter function for attaching a media element to the player context. The built-in `<Video>` and `<Audio>` components use this internally — you only need it when building a custom media element.
+
+CustomMedia.tsx
+
+```
+import { useMediaAttach } from "@videojs/react";
+
+function CustomMedia({ src }: { src: string }) {
+  const setMedia = useMediaAttach();
+  return <video ref={setMedia} src={src} />;
+}
+```
+
+## Who needs this
+
+You only need `useMediaAttach` if you’re replacing the built-in `<Video>` or `<Audio>` components with a custom element. For example, if you’re…
+
+*   Wrapping a third-party video player
+*   Using a `<canvas>` or WebGL-based renderer
+*   Building a custom `<audio>` element with additional markup
+
+For standard `<video>` and `<audio>` playback, use the built-in components.
+
+## Safe outside Provider
+
+Returns `undefined` when called outside a Player `Provider`. Check the return value before using it — this avoids crashes in components that may render outside the player tree.
+
+## API Reference
+
+### Return Value
+
+Type
+
+Details
+
+`Dispatch<SetStateAction<Media | null>...`
+
+▸
+
+Type
+
+`Dispatch<SetStateAction<Media | null>> | undefined`

package/docs/reference/use-media.md

@@ -0,0 +1,11 @@
+# Player.useMedia
+
+Hook to access the underlying media element from within a Player.Provider
+
+`Player.useMedia` returns the current `HTMLMediaElement` (or `null` if no media element has been registered yet). Use it to interact directly with the native media element when needed. It must be called within a `Player.Provider`. The media element becomes available after a `<Video>` or `<Audio>` component mounts inside the provider tree. Also available as a standalone import (`import { useMedia } from '@videojs/react'`) — identical behavior, no typing difference. To attach a custom media element instead of the built-in components, see [`useMediaAttach`](./use-media-attach.md).
+
+## API Reference
+
+### Return Value
+
+`Media | null`

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

@@ -0,0 +1,93 @@
+# usePlayerContext
+
+Hook to access the full player context including store, media element, and media setter
+
+`usePlayerContext` returns the full `PlayerContextValue` object, which includes the store, the current media element, and the media setter.
+
+DebugPanel.tsx
+
+```
+import { usePlayerContext } from "@videojs/react";
+
+function DebugPanel() {
+  const { store, media, setMedia } = usePlayerContext();
+
+  return (
+    <pre>
+      {JSON.stringify(
+        {
+          hasStore: !!store,
+          hasMedia: !!media,
+          tagName: media?.tagName,
+        },
+        null,
+        2,
+      )}
+    </pre>
+  );
+}
+```
+
+Throws an error if called outside a Player `Provider`.
+
+### Prefer higher-level hooks
+
+For most use cases, use the focused hooks instead:
+
+Need
+
+Hook
+
+Store access with selector
+
+[`usePlayer`](./use-player.md)
+
+Current media element
+
+[`useMedia`](./use-media.md)
+
+Attach custom media
+
+[`useMediaAttach`](./use-media-attach.md)
+
+These hooks read from the same context internally. `usePlayerContext` exposes the raw context value — use it when you need multiple context fields in one call or when building a custom abstraction over the player context.
+
+## API Reference
+
+### Return Value
+
+Property
+
+Type
+
+Details
+
+`store`
+
+`BaseStore & UnknownState`
+
+`media`
+
+`Media | null`
+
+`setMedia`
+
+`Dispatch<SetStateAction<Media | null>>`
+
+`container`
+
+`MediaContainer | null`
+
+`setContainer`
+
+`Dispatch<SetStateAction<HTMLElement |...`
+
+▸
+
+Type
+
+`Dispatch<SetStateAction<HTMLElement | null>>`
+
+`popupGroup`
+
+`PopupGroup`

package/docs/reference/use-player.md

@@ -0,0 +1,226 @@
+# Player.usePlayer
+
+Hook to access the player store from within a Player.Provider
+
+`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`](./create-player.md). It’s also available as a standalone import (`import { usePlayer } from '@videojs/react'`), but the standalone version returns an untyped store.
+
+## Examples
+
+### Store Access
+
+Call `Player.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.
+
+PlayPause
+
+App.tsx
+
+App.css
+
+```
+import { createPlayer } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const Player = createPlayer({
+  features: videoFeatures,
+});
+
+function Controls() {
+  const store = Player.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.Provider>
+      <Player.Container className="media-container">
+        <Video
+          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
+          autoPlay
+          muted
+          playsInline
+          loop
+        />
+        <Controls />
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+```
+.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 function to subscribe to specific state. The component re-renders when the selected value changes, using shallow equality by default.
+
+Paused
+
+true
+
+Time
+
+0.0s / 0.0s
+
+App.tsx
+
+App.css
+
+```
+import { createPlayer } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const Player = createPlayer({
+  features: videoFeatures,
+});
+
+function StateDisplay() {
+  const state = Player.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.Provider>
+      <Player.Container className="media-container">
+        <Video
+          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
+          autoPlay
+          muted
+          playsInline
+          loop
+        />
+        <StateDisplay />
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+```
+.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 the player store from within a Player Provider.
+
+#### Return Value
+
+`BaseStore & UnknownState`
+
+### With Selector
+
+Select a value from the player store. Re-renders when the selected value changes.
+
+#### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`selector*`
+
+`function`
+
+`—`
+
+▸
+
+Description
+
+Derives a value from the player store state.
+
+Type
+
+`((state: UnknownState) => R)`
+
+#### Return Value
+
+`R`

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`