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

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`

package/docs/reference/use-snapshot.md

@@ -0,0 +1,127 @@
+# useSnapshot
+
+Hook to subscribe to a State container's current value
+
+`useSnapshot` subscribes to a `State` container and returns its current value, re-rendering when the value changes. It has two overloads:
+
+**Full state** – returns the entire state object.
+
+tsx
+
+```
+function Display({ state }) {
+  const value = useSnapshot(state);
+  return <span>{value.count}</span>;
+}
+```
+
+**With selector** – returns a derived value from the state, re-rendering only when the selected value changes. Pass a custom comparator as the third argument when needed.
+
+tsx
+
+```
+function Count({ state }) {
+  const count = useSnapshot(state, (s) => s.count);
+  return <span>{count}</span>;
+}
+```
+
+### State containers vs stores
+
+A `State` container is a reactive primitive that holds an object value and notifies subscribers on change. Stores are built on top of `State` containers but add features, actions, and lifecycle.
+
+Hook
+
+Input
+
+Subscribes to
+
+`useSnapshot`
+
+`State<T>`
+
+Raw state container
+
+[`useStore`](./use-store.md)
+
+Store instance
+
+Store-backed state with features
+
+Use `useSnapshot` when working with standalone `State` containers outside the player store system – for example, custom state in component libraries. For player state, use [`usePlayer`](./use-player.md) or [`useStore`](./use-store.md).
+
+`useSnapshot` is built on [`useSelector`](./use-selector.md) and uses `shallowEqual` by default. The HTML equivalent is `SnapshotController`.
+
+## API Reference
+
+### Without Selector
+
+Subscribe to a State container's current value.
+
+#### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`state*`
+
+`State<object>`
+
+`—`
+
+#### Return Value
+
+`object`
+
+### With Selector
+
+Select a value from state. Re-renders when the selected value changes.
+
+#### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`state*`
+
+`State<object>`
+
+`—`
+
+`selector*`
+
+`Selector<object, R>`
+
+`—`
+
+▸
+
+Description
+
+Derives a value from state.
+
+`isEqual`
+
+`Comparator<R>`
+
+`—`
+
+▸
+
+Description
+
+Custom equality function. Defaults to `shallowEqual`.
+
+#### Return Value
+
+`R`

package/docs/reference/use-store.md

@@ -0,0 +1,257 @@
+# useStore
+
+Hook to access store state and actions with optional selector-based subscriptions
+
+`useStore` subscribes to a store instance directly. It has the same two overloads as [`usePlayer`](./use-player.md) — without a selector for store access, or with a selector for reactive state. Within a player provider, `usePlayer` is usually simpler since it reads the store from context. Reach for `useStore` when you have a store instance directly or need to derive computed values from the store.
+
+## Examples
+
+### Store Access
+
+Call `useStore(store)` without a selector to get the store instance back for imperative actions. The component does not subscribe to state changes.
+
+Go to startGo to middle
+
+App.tsx
+
+App.css
+
+```
+import { createPlayer, useStore } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const Player = createPlayer({
+  features: videoFeatures,
+});
+
+function SeekControls() {
+  const store = Player.usePlayer();
+  const s = useStore(store);
+
+  return (
+    <div className="controls">
+      <button type="button" onClick={() => s.seek(0)}>
+        Go to start
+      </button>
+      <button type="button" onClick={() => s.seek(s.state.duration / 2)}>
+        Go to middle
+      </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
+        />
+        <SeekControls />
+      </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 to derive and subscribe to computed values from the store. The component re-renders when the derived value changes, using shallow equality by default.
+
+Remaining
+
+0.0s
+
+Progress
+
+0.0%
+
+App.tsx
+
+App.css
+
+```
+import { createPlayer, useStore } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const Player = createPlayer({
+  features: videoFeatures,
+});
+
+function DerivedState() {
+  const store = Player.usePlayer();
+  const derived = useStore(store, (s) => ({
+    remaining: s.duration - s.currentTime,
+    progress: s.duration > 0 ? (s.currentTime / s.duration) * 100 : 0,
+  }));
+
+  return (
+    <dl className="panel">
+      <div>
+        <dt>Remaining</dt>
+        <dd>{derived.remaining.toFixed(1)}s</dd>
+      </div>
+      <div>
+        <dt>Progress</dt>
+        <dd>{derived.progress.toFixed(1)}%</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
+        />
+        <DerivedState />
+      </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 store state and actions.
+
+Without selector: Returns the store, does NOT subscribe to changes. With selector: Returns selected state, re-renders when selected state changes (shallowEqual).
+
+#### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`store*`
+
+`S`
+
+`—`
+
+#### Return Value
+
+`S`
+
+### With Selector
+
+Select a value from the store. Re-renders when the selected value changes (shallowEqual).
+
+#### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`store*`
+
+`S`
+
+`—`
+
+`selector*`
+
+`Selector<InferStoreState<S>, R>`
+
+`—`
+
+▸
+
+Description
+
+Derives a value from the store state.
+
+`isEqual`
+
+`Comparator<R>`
+
+`—`
+
+▸
+
+Description
+
+Custom equality function. Defaults to `shallowEqual`.
+
+#### Return Value
+
+`R`