@videojs/react 10.0.0-beta.9 → 10.0.0-rc.2

package/docs/reference/use-media.md

@@ -0,0 +1,149 @@
+# useMedia
+
+Hook to access the media object from within a Player
+
+## Import
+
+tsx
+
+```
+import { useMedia } from "@videojs/react";
+```
+
+`useMedia` returns the media object attached to the current player. It returns `null` until the media mounts. Call it inside the matching `Player`.
+
+The media object may be an `HTMLVideoElement` or a Video.js media object that controls one. It always provides `play()`. Check `isMediaPauseCapable(media)` before using `pause()` because lightweight media implementations do not have to provide it.
+
+With a packaged preset, import `useMedia` from `@videojs/react`. With a player made by [`createPlayer`](./create-player.md), use the `useMedia` hook returned by that call. It is connected to the new player’s context.
+
+tsx
+
+```
+const { Player, useMedia } = createPlayer({ features: videoFeatures });
+```
+
+## Choose between `useMedia` and a ref
+
+A React ref on `<MuxVideo>` or `<HlsJsVideo>` receives the rendered `HTMLVideoElement`. `useMedia()` receives the Video.js media object attached to the player. Use the ref for browser video APIs. Use `useMedia()` for Video.js properties such as `streamType` and `targetLiveWindow`.
+
+To attach your own media object, see [`useMediaAttach`](./use-media-attach.md).
+
+LiveDetails.tsx
+
+```
+import { isMediaLiveCapable, isMediaStreamTypeCapable, useMedia } from '@videojs/react';
+
+export function LiveDetails() {
+  const media = useMedia();
+  if (!media) return null;
+
+  const streamType = isMediaStreamTypeCapable(media) ? media.streamType : 'unknown';
+  const targetLiveWindow = isMediaLiveCapable(media) ? media.targetLiveWindow : Number.NaN;
+
+  return <output>{streamType}: {String(targetLiveWindow)}</output>;
+}
+```
+
+## Access hls.js
+
+Media backed by hls.js also provides an `engine` property. That property is specific to hls.js, so keep direct engine calls in a small part of your app rather than treating them as part of the common `Media` API.
+
+## Examples
+
+### Basic Usage
+
+App.tsx
+
+App.css
+
+```
+import { Container, createPlayer, isMediaSourceCapable, isMediaVideoDimensionsCapable } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player, useMedia } = createPlayer({
+  features: videoFeatures,
+});
+
+function MediaInfo() {
+  const media = 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>
+      <Container className="media-container">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
+        <MediaInfo />
+      </Container>
+    </Player>
+  );
+}
+```
+```
+.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-menu-context.md

@@ -0,0 +1,115 @@
+# useMenuContext
+
+Hook to access the nearest Menu compound-component context
+
+## Import
+
+tsx
+
+```
+import { useMenuContext } from "@videojs/react";
+```
+
+## Usage
+
+Use this hook to build a custom part rendered inside `Menu.Root`.
+
+tsx
+
+```
+function CloseMenuButton() {
+  const { menu } = useMenuContext();
+
+  return <button onClick={() => menu.close()}>Close menu</button>;
+}
+```
+
+The hook throws when there is no surrounding `Menu.Root`.
+
+## API Reference
+
+### Return Value
+
+Property
+
+Type
+
+Details
+
+`core`
+
+`MenuCore`
+
+`menu`
+
+`object`
+
+▸
+
+Type
+
+`{ input: State<MenuInput>; triggerProps: MenuTriggerProps; contentProps: MenuContentProps; triggerElement: HTMLElement | null; contentElement: HTMLElement | null; popupElement: HTMLElement | null; setTriggerElement: ((element: HTMLElement | null) => void); setContentElement: ((element: HTMLElement | null) => void); setPopupElement: ((element: HTMLElement | null) => void); registerItem: ((element: HTMLElement) => (() => void)); registerSubmenu: ((menu: MenuApi) => (() => void)); highlight: ((element: HTMLElement | null, options?: MenuHighlightOptions) => void); highlightFirstItem: ((options?: MenuHighlightOptions) => void); restoreFocus: ((options?: FocusOptions) => void); open: ((reason?: MenuOpenChangeReason) => void); close: ((reason?: MenuOpenChangeReason) => void); syncOpen: ((open: boolean) => void); destroy: (() => void) }`
+
+`parent`
+
+`object`
+
+▸
+
+Type
+
+`{ core: MenuCore; menu: MenuApi; parent: MenuContextValue | null; state: MenuState; preferredSide: MenuState['side']; setPositionedSide: ((side: MenuState['side']) => void); contentId: string; anchorName: string; boundary: PositioningBoundary; container: MediaContainer | null; optionState: MenuOptionState | null; setOptionState: ((source: symbol, state: MenuOptionState | null) => void) } | null`
+
+`state`
+
+`MenuState`
+
+`preferredSide`
+
+`MenuState['side']`
+
+`setPositionedSide`
+
+`function`
+
+▸
+
+Type
+
+`((side: MenuState['side']) => void)`
+
+`contentId`
+
+`string`
+
+`anchorName`
+
+`string`
+
+`boundary`
+
+`'viewport' | 'container' | string & o...`
+
+▸
+
+Type
+
+`'viewport' | 'container' | string & object | Element | null | undefined`
+
+`container`
+
+`object | null`
+
+`optionState`
+
+`MenuOptionState | null`
+
+`setOptionState`
+
+`((source: symbol, state: MenuOptionState | function`
+
+▸
+
+Type
+
+`((source: symbol, state: MenuOptionState | null) => void)`

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

@@ -0,0 +1,33 @@
+# 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
+
+### Return Value
+
+`object | null`

package/docs/reference/use-optional-menu-context.md

@@ -0,0 +1,115 @@
+# useOptionalMenuContext
+
+Hook to access a Menu context when one is available
+
+## Import
+
+tsx
+
+```
+import { useOptionalMenuContext } from "@videojs/react";
+```
+
+## Usage
+
+Use the optional hook when a component can work both inside and outside `Menu.Root`.
+
+tsx
+
+```
+function MenuAwareLabel() {
+  const menu = useOptionalMenuContext();
+
+  return <span>{menu ? "Nested in a menu" : "Standalone"}</span>;
+}
+```
+
+It returns `null` instead of throwing when no menu context is available.
+
+## API Reference
+
+### Return Value
+
+Property
+
+Type
+
+Details
+
+`core`
+
+`MenuCore`
+
+`menu`
+
+`object`
+
+▸
+
+Type
+
+`{ input: State<MenuInput>; triggerProps: MenuTriggerProps; contentProps: MenuContentProps; triggerElement: HTMLElement | null; contentElement: HTMLElement | null; popupElement: HTMLElement | null; setTriggerElement: ((element: HTMLElement | null) => void); setContentElement: ((element: HTMLElement | null) => void); setPopupElement: ((element: HTMLElement | null) => void); registerItem: ((element: HTMLElement) => (() => void)); registerSubmenu: ((menu: MenuApi) => (() => void)); highlight: ((element: HTMLElement | null, options?: MenuHighlightOptions) => void); highlightFirstItem: ((options?: MenuHighlightOptions) => void); restoreFocus: ((options?: FocusOptions) => void); open: ((reason?: MenuOpenChangeReason) => void); close: ((reason?: MenuOpenChangeReason) => void); syncOpen: ((open: boolean) => void); destroy: (() => void) }`
+
+`parent`
+
+`object`
+
+▸
+
+Type
+
+`{ core: MenuCore; menu: MenuApi; parent: MenuContextValue | null; state: MenuState; preferredSide: MenuState['side']; setPositionedSide: ((side: MenuState['side']) => void); contentId: string; anchorName: string; boundary: PositioningBoundary; container: MediaContainer | null; optionState: MenuOptionState | null; setOptionState: ((source: symbol, state: MenuOptionState | null) => void) } | null`
+
+`state`
+
+`MenuState`
+
+`preferredSide`
+
+`MenuState['side']`
+
+`setPositionedSide`
+
+`function`
+
+▸
+
+Type
+
+`((side: MenuState['side']) => void)`
+
+`contentId`
+
+`string`
+
+`anchorName`
+
+`string`
+
+`boundary`
+
+`'viewport' | 'container' | string & o...`
+
+▸
+
+Type
+
+`'viewport' | 'container' | string & object | Element | null | undefined`
+
+`container`
+
+`object | null`
+
+`optionState`
+
+`MenuOptionState | null`
+
+`setOptionState`
+
+`((source: symbol, state: MenuOptionState | function`
+
+▸
+
+Type
+
+`((source: symbol, state: MenuOptionState | null) => void)`

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

@@ -0,0 +1,77 @@
+# useOptionalPlayer
+
+Hook to access or select Player state when a Player is available
+
+## Import
+
+tsx
+
+```
+import { useOptionalPlayer } from "@videojs/react";
+```
+
+## Usage
+
+Without a selector, the hook returns the player store or `undefined` outside `Player`.
+
+tsx
+
+```
+const store = useOptionalPlayer();
+```
+
+With a selector, it subscribes while a player is available and returns the selected value. The selector is not called outside `Player`.
+
+tsx
+
+```
+import { selectPlayback, useOptionalPlayer } from "@videojs/react";
+
+const playback = useOptionalPlayer(selectPlayback);
+```
+
+Use `usePlayer` when the component requires a surrounding player.
+
+## API Reference
+
+### Without Selector
+
+Returns the player store when available, or `undefined` outside a Player.
+
+#### Return Value
+
+`UnknownStore | undefined`
+
+### With Selector
+
+Selects a player value when available, or returns `undefined` outside a Player.
+
+#### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`selector*`
+
+`function`
+
+`—`
+
+▸
+
+Description
+
+Derives a value from the player store state.
+
+Type
+
+`((state: UnknownState) => R)`
+
+#### Return Value
+
+`R | undefined`

package/docs/reference/use-playback-rate-options.md

@@ -0,0 +1,123 @@
+# usePlaybackRateOptions
+
+Hook to build playback rate menu options from the player playback rate state
+
+## Import
+
+tsx
+
+```
+import { usePlaybackRateOptions } from "@videojs/react";
+```
+
+`usePlaybackRateOptions` returns the current playback rate, the available options, and `setRate` / `setValue` callbacks for wiring rate selection into a menu. It returns `null` when the [playback rate feature](./feature-playback-rate.md) is not configured.
+
+SpeedMenu.tsx
+
+```
+import { Menu, usePlaybackRateOptions } from "@videojs/react";
+
+function SpeedMenu() {
+  const playbackRate = usePlaybackRateOptions();
+  if (playbackRate?.state.availability !== "available") return null;
+
+  return (
+    <Menu.RadioGroup value={playbackRate.value} onValueChange={playbackRate.setValue} aria-label="Speed">
+      {playbackRate.options.map((option) => (
+        <Menu.RadioItem key={option.value} value={option.value} disabled={option.disabled}>
+          {option.label}
+          <Menu.ItemIndicator checked={option.value === playbackRate.value} />
+        </Menu.RadioItem>
+      ))}
+    </Menu.RadioGroup>
+  );
+}
+```
+
+Options come from the player’s configured playback rates. Labels default to the rate followed by a multiplication sign (e.g. `1.5×`); pass `formatRate` to customize them. `setValue` accepts an option’s string value, while `setRate` accepts a number directly.
+
+See [PlaybackRateRadioGroup](./playback-rate-radio-group.md) for the component-level pattern, and [Menu](./menu.md) for a complete settings menu example.
+
+## API Reference
+
+### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`props`
+
+`object`
+
+`—`
+
+▸
+
+Description
+
+Optional `label`, `formatRate`, and `disabled` overrides.
+
+### Return Value
+
+Property
+
+Type
+
+Details
+
+`state`
+
+`PlaybackRateRadioGroupCore.State`
+
+`label`
+
+`string`
+
+`rate`
+
+`number`
+
+`value`
+
+`string`
+
+`selectedLabel`
+
+`string`
+
+`options`
+
+`PlaybackRateOption[]`
+
+`disabled`
+
+`boolean`
+
+`hidden`
+
+`boolean`
+
+`setRate`
+
+`function`
+
+▸
+
+Type
+
+`((rate: number) => void)`
+
+`setValue`
+
+`function`
+
+▸
+
+Type
+
+`((value: string) => void)`

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

@@ -0,0 +1,98 @@
+# usePlayerContext
+
+Hook to access the full player context value
+
+## Import
+
+tsx
+
+```
+import { usePlayerContext } from "@videojs/react";
+```
+
+`usePlayerContext` returns the full `PlayerContextValue` object for lower-level integrations that need direct access to player context fields.
+
+DebugPanel.tsx
+
+```
+import { usePlayerContext } from "@videojs/react";
+
+function DebugPanel() {
+  const { store, media, container } = usePlayerContext();
+
+  return (
+    <pre>
+      {JSON.stringify(
+        {
+          hasStore: !!store,
+          hasMedia: !!media,
+          hasContainer: !!container,
+          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`
+
+`UnknownStore`
+
+`media`
+
+`Media | null`
+
+`setMedia`
+
+`Dispatch<SetStateAction<Media | null>>`
+
+`container`
+
+`object | null`
+
+`setContainer`
+
+`Dispatch<SetStateAction<HTMLElement |...`
+
+▸
+
+Type
+
+`Dispatch<SetStateAction<HTMLElement | null>>`