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

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,112 @@
+# Player.useMedia
+
+Hook to access the media object from within a Player.Provider
+
+`Player.useMedia` (from [`createPlayer`](./create-player.md)) returns the current `Media` object (or `null` if no media has been registered yet). `Media` is a runtime-agnostic playback interface — any instance that conforms to it, including an `HTMLVideoElement`, can be the media. It exposes capabilities like `play()` and event subscription rather than assuming a native element. It must be called within a `Player.Provider`. The media object becomes available after a `<Video>` or `<Audio>` component mounts inside the provider tree. To attach a custom media element instead of the built-in components, see [`useMediaAttach`](./use-media-attach.md).
+
+## Examples
+
+### Basic Usage
+
+App.tsx
+
+App.css
+
+```
+import { createPlayer, isMediaSourceCapable, isMediaVideoDimensionsCapable } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const Player = createPlayer({
+  features: videoFeatures,
+});
+
+function MediaInfo() {
+  const media = Player.useMedia();
+
+  if (!media) return null;
+
+  return (
+    <dl className="info-panel">
+      {isMediaSourceCapable(media) && (
+        <div>
+          <dt>src</dt>
+          <dd>{media.currentSrc || '—'}</dd>
+        </div>
+      )}
+      {isMediaVideoDimensionsCapable(media) && (
+        <>
+          <div>
+            <dt>videoWidth</dt>
+            <dd>{media.videoWidth}px</dd>
+          </div>
+          <div>
+            <dt>videoHeight</dt>
+            <dd>{media.videoHeight}px</dd>
+          </div>
+        </>
+      )}
+    </dl>
+  );
+}
+
+export default function BasicUsage() {
+  return (
+    <Player.Provider>
+      <Player.Container className="media-container">
+        <Video
+          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
+          autoPlay
+          muted
+          playsInline
+          loop
+        />
+        <MediaInfo />
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.info-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  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);
+}
+
+.info-panel div {
+  display: flex;
+  gap: 8px;
+}
+
+.info-panel dt {
+  min-width: 80px;
+  color: #6b7280;
+}
+
+.info-panel dd {
+  margin: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+}
+```
+
+## 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,241 @@
+# Player.usePlayer
+
+Hook to access the player store from within a Player.Provider
+
+`Player.usePlayer` (from [`createPlayer`](./create-player.md)) 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, selectPlayback } from '@videojs/react';
+
+usePlayer();               // UnknownStore (state: unknown)
+usePlayer(selectPlayback); // PlaybackState | undefined
+```
+
+## 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.
+
+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
+
+`BaseStore & UnknownState`
+
+### With Selector
+
+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
+
+Details
+
+`selector*`
+
+`function`
+
+`—`
+
+▸
+
+Description
+
+Derives a value from the player store state.
+
+Type
+
+`((state: UnknownState) => R)`
+
+#### Return Value
+
+`R`