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

package/docs/reference/use-player.md

@@ -0,0 +1,245 @@
+# usePlayer
+
+Hook to access the player store from within a Player
+
+## Import
+
+tsx
+
+```
+import { usePlayer } from "@videojs/react";
+```
+
+The `usePlayer` hook returned by [`createPlayer`](./create-player.md) gives you access to the player store from any component within its `Player`. 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.
+
+tsx
+
+```
+const { Player, usePlayer } = createPlayer({ features: videoFeatures });
+```
+
+The pair works exactly like React Context: [`Player`](./player.md) is the Provider, and `usePlayer` is its `useContext`\-style consumer, so the calling component must render inside `Player`. You can still read state anywhere: `Player` renders no DOM of its own, so lift it above every component that needs player state, the way you’d lift any Provider.
+
+`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 `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 { Container, createPlayer } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player, usePlayer } = createPlayer({
+  features: videoFeatures,
+});
+
+function Controls() {
+  const store = 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>
+      <Container className="media-container">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
+        <Controls />
+      </Container>
+    </Player>
+  );
+}
+```
+```
+.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 { Container, createPlayer } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player, usePlayer } = createPlayer({
+  features: videoFeatures,
+});
+
+function StateDisplay() {
+  const state = 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>
+      <Container className="media-container">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
+        <StateDisplay />
+      </Container>
+    </Player>
+  );
+}
+```
+```
+.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.
+
+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
+
+`UnknownStore`
+
+### 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`

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

@@ -0,0 +1,95 @@
+# usePopoverContext
+
+Hook to access the nearest Popover compound-component context
+
+## Import
+
+tsx
+
+```
+import { usePopoverContext } from "@videojs/react";
+```
+
+## Usage
+
+Use this hook to build a custom part rendered inside `Popover.Root`.
+
+tsx
+
+```
+function ClosePopoverButton() {
+  const { popover } = usePopoverContext();
+
+  return <button onClick={() => popover.close()}>Close popover</button>;
+}
+```
+
+The hook throws when there is no surrounding `Popover.Root`.
+
+## API Reference
+
+### Return Value
+
+Property
+
+Type
+
+Details
+
+`core`
+
+`PopoverCore`
+
+`popover`
+
+`object`
+
+▸
+
+Type
+
+`{ input: State<PopoverInput>; triggerProps: PopoverTriggerProps; popupProps: PopoverPopupProps; triggerElement: HTMLElement | null; setTriggerElement: ((el: HTMLElement | null) => void); setPopupElement: ((el: HTMLElement | null) => void); open: ((reason?: PopoverOpenChangeReason) => void); close: ((reason?: PopoverOpenChangeReason) => void); syncOpen: ((open: boolean) => void); destroy: (() => void) }`
+
+`state`
+
+`PopoverCore.State`
+
+`preferredSide`
+
+`PopoverCore.State['side']`
+
+`setPositionedSide`
+
+`function`
+
+▸
+
+Type
+
+`((side: PopoverCore.State['side']) => void)`
+
+`stateAttrMap`
+
+`{ [Key in keyof State]?: string; }`
+
+`anchorName`
+
+`string`
+
+`popupId`
+
+`string`
+
+`boundary`
+
+`'viewport' | 'container' | string & o...`
+
+▸
+
+Type
+
+`'viewport' | 'container' | string & object | Element | null | undefined`
+
+`container`
+
+`object | null`

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

@@ -0,0 +1,109 @@
+# useQualityOptions
+
+Hook to build video quality menu options from the player rendition state
+
+## Import
+
+tsx
+
+```
+import { useQualityOptions } from "@videojs/react";
+```
+
+`useQualityOptions` returns the current quality value, the available options, and a `setValue` callback for wiring quality selection into a menu. It returns `null` when the [quality feature](./feature-quality.md) is not configured.
+
+QualityMenu.tsx
+
+```
+import { Menu, useQualityOptions } from "@videojs/react";
+
+function QualityMenu() {
+  const quality = useQualityOptions();
+  if (quality?.state.availability !== "available") return null;
+
+  return (
+    <Menu.RadioGroup value={quality.value} onValueChange={quality.setValue} aria-label="Quality">
+      {quality.options.map((option) => (
+        <Menu.RadioItem key={option.value} value={option.value} disabled={option.disabled}>
+          {option.label}
+          <Menu.ItemIndicator checked={option.value === quality.value} />
+        </Menu.RadioItem>
+      ))}
+    </Menu.RadioGroup>
+  );
+}
+```
+
+The first option is always `Auto`; selecting it returns control to adaptive bitrate selection. Options carry optional `tier` and `badge` fields (e.g. `4K`, `HD`) for richer labels. Pass `formatRendition` to customize the visible rendition labels.
+
+See [QualityRadioGroup](./quality-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`, `formatRendition`, and `disabled` overrides.
+
+### Return Value
+
+Property
+
+Type
+
+Details
+
+`state`
+
+`QualityRadioGroupCore.State`
+
+`label`
+
+`string`
+
+`value`
+
+`string`
+
+`selectedLabel`
+
+`string`
+
+`options`
+
+`QualityOption[]`
+
+`disabled`
+
+`boolean`
+
+`hidden`
+
+`boolean`
+
+`setValue`
+
+`function`
+
+▸
+
+Type
+
+`((value: string) => void)`

package/docs/reference/use-selector.md

@@ -0,0 +1,144 @@
+# useSelector
+
+Low-level hook for subscribing to derived state with customizable equality checks
+
+## Import
+
+tsx
+
+```
+import { useSelector } from "@videojs/react";
+```
+
+`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/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*`
+
+`object`
+
+`—`
+
+▸
+
+Description
+
+Derives a value from the snapshot.
+
+Type
+
+`{ (state: State): Result;; displayName?: string }`
+
+`isEqual*`
+
+`unknown`
+
+`—`
+
+▸
+
+Description
+
+Custom equality function. Defaults to `shallowEqual`.
+
+### Return Value
+
+`R`

package/docs/reference/use-slider.md

@@ -0,0 +1,133 @@
+# useSlider
+
+Hook for connecting slider input behavior to custom React elements
+
+`useSlider` is the low-level hook behind the [Slider](./slider.md), [TimeSlider](./time-slider.md), and [VolumeSlider](./volume-slider.md) components. Use it when you need to build a new slider primitive with custom state calculations. For standard player controls, use the built-in components.
+
+## Import
+
+tsx
+
+```
+import { useSlider } from "@videojs/react";
+```
+
+## Usage
+
+Pass callbacks that convert raw slider input into your component state, values, and CSS variables. Attach the returned root props, ref, and styles to the pointer target. Attach the thumb props and ref to the focusable thumb.
+
+tsx
+
+```
+function CustomSlider({ options }: { options: useSlider.Options }) {
+  const {
+    state,
+    input,
+    cssVars,
+    rootRef,
+    thumbRef,
+    rootProps,
+    rootStyle,
+    thumbProps,
+  } = useSlider(options);
+
+  return (
+    <div
+      ref={rootRef}
+      {...rootProps}
+      style={{ ...cssVars, ...rootStyle }}
+      data-dragging={state.dragging || undefined}
+    >
+      <div
+        ref={thumbRef}
+        {...thumbProps}
+        data-focused={input.current.focused || undefined}
+      />
+    </div>
+  );
+}
+```
+
+`state` is the derived state for the current render. `input` is the underlying reactive state container. Read `input.current` for the latest raw input or call `input.subscribe(listener)` when another system needs to observe changes outside React rendering.
+
+## API Reference
+
+### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`options*`
+
+`object`
+
+`—`
+
+▸
+
+Type
+
+`{ computeState: ((input: SliderInput) => State); orientation?: 'horizontal' | 'vertical'; disabled?: boolean; adjustPercent?: ((rawPercent: number, thumbSize: number, trackSize: number) => number); getCSSVars: ((state: State) => Record<string, string>) }`
+
+### Return Value
+
+Property
+
+Type
+
+Details
+
+`state`
+
+`State`
+
+`input`
+
+`SliderApi['input']`
+
+`cssVars`
+
+`Record<string, string>`
+
+`rootRef`
+
+`RefCallback<HTMLElement>`
+
+`thumbRef`
+
+`RefCallback<HTMLElement>`
+
+`rootProps`
+
+`function`
+
+▸
+
+Type
+
+`{ onPointerDown: ((event: UIPointerEvent) => void); onPointerMove: ((event: UIPointerEvent) => void); onPointerUp: ((event: UIPointerEvent) => void); onPointerLeave: ((event: UIPointerEvent) => void); onLostPointerCapture: (() => void) }`
+
+`rootStyle`
+
+`object`
+
+▸
+
+Type
+
+`{ touchAction: string; userSelect: string }`
+
+`thumbProps`
+
+`function`
+
+▸
+
+Type
+
+`{ onKeyDownCapture: ((event: UIKeyboardEvent) => void); onFocus: (() => void); onBlur: (() => void) }`