@videojs/react 10.0.0-beta.3 → 10.0.0-beta.31

package/docs/reference/use-store.md

@@ -0,0 +1,245 @@
+# 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 `Player`, `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 { Container, createPlayer, useStore } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player, usePlayer } = createPlayer({
+  features: videoFeatures,
+});
+
+function SeekControls() {
+  const store = 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>
+      <Container className="media-container">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
+        <SeekControls />
+      </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 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 { Container, createPlayer, useStore } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player, usePlayer } = createPlayer({
+  features: videoFeatures,
+});
+
+function DerivedState() {
+  const store = 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>
+      <Container className="media-container">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
+        <DerivedState />
+      </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 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`

package/docs/reference/use-translator.md

@@ -0,0 +1,119 @@
+# useTranslator
+
+React hook that returns the typed translator for the nearest I18nProvider
+
+`useTranslator` returns the translator from the nearest [`I18nProvider`](./i18n-provider.md). Control components pass text descriptors from core `getLabel()`. Custom UI can pass an opaque key with its English fallback.
+
+When no provider is mounted, the hook falls back to English registry strings so standalone demos do not throw.
+
+## Example
+
+Switch the provider locale to see `useTranslator` resolve a simple key and a parameterized key from the nearest provider.
+
+LanguageSpanishFrench
+
+Button
+
+Reproducir
+
+Parameterized
+
+Adelantar 10 segundos
+
+App.tsx
+
+App.css
+
+```
+import { I18nProvider, useTranslator } from '@videojs/react/i18n';
+import { useState } from 'react';
+
+import './BasicUsage.css';
+
+const translations = {
+  es: {
+    buttons: { play: 'Reproducir' },
+    seek: { forward: 'Adelantar {seconds} segundos' },
+  },
+  fr: {
+    buttons: { play: 'Lire' },
+    seek: { forward: 'Avancer de {seconds} secondes' },
+  },
+} as const;
+
+type Locale = keyof typeof translations;
+
+function Labels() {
+  const t = useTranslator();
+
+  return (
+    <dl className="react-use-translator-basic__output">
+      <div>
+        <dt>Button</dt>
+        <dd>{t('buttons.play', { default: 'Play' })}</dd>
+      </div>
+      <div>
+        <dt>Parameterized</dt>
+        <dd>{t('seek.forward', { seconds: 10, default: 'Seek forward {seconds} seconds' })}</dd>
+      </div>
+    </dl>
+  );
+}
+
+export default function BasicUsage() {
+  const [locale, setLocale] = useState<Locale>('es');
+
+  return (
+    <div className="react-use-translator-basic">
+      <label>
+        Language
+        <select value={locale} onChange={(event) => setLocale(event.currentTarget.value as Locale)}>
+          <option value="es">Spanish</option>
+          <option value="fr">French</option>
+        </select>
+      </label>
+      <I18nProvider locale={locale} translations={translations[locale]}>
+        <Labels />
+      </I18nProvider>
+    </div>
+  );
+}
+```
+```
+.react-use-translator-basic {
+  display: grid;
+  gap: 16px;
+  padding: 16px;
+}
+
+.react-use-translator-basic label,
+.react-use-translator-basic__output div {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+}
+
+.react-use-translator-basic select {
+  padding: 4px 8px;
+}
+
+.react-use-translator-basic__output {
+  display: grid;
+  gap: 8px;
+  margin: 0;
+}
+
+.react-use-translator-basic__output dt {
+  color: #6b7280;
+}
+
+.react-use-translator-basic__output dd {
+  margin: 0;
+}
+```
+
+## API Reference
+
+### Return Value
+
+`Translator`