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

package/docs/reference/feature-fullscreen.md

@@ -0,0 +1,112 @@
+# Fullscreen
+
+Fullscreen state and actions for the player store
+
+Controls fullscreen mode. Tries the container element first, falls back to the media element.
+
+## API Reference
+
+### State
+
+Property
+
+Type
+
+Details
+
+`fullscreen`
+
+`boolean`
+
+▸
+
+Description
+
+Whether fullscreen mode is currently active.
+
+`fullscreenAvailability`
+
+`'available' | 'unavailable' | 'unsupported'`
+
+▸
+
+Description
+
+Whether fullscreen can be requested on this platform.
+
+### Actions
+
+Action
+
+Type
+
+Details
+
+`requestFullscreen`
+
+`() => Promise<void>`
+
+▸
+
+Description
+
+Enter fullscreen mode. Tries container first, falls back to media element.
+
+`exitFullscreen`
+
+`() => Promise<void>`
+
+▸
+
+Description
+
+Exit fullscreen mode.
+
+`toggleFullscreen`
+
+`() => Promise<void>`
+
+▸
+
+Description
+
+Toggle fullscreen mode.
+
+### Selector
+
+Pass `selectFullscreen` to [`usePlayer`](./use-player.md) to subscribe to fullscreen state. Returns `undefined` if the fullscreen feature is not configured.
+
+FullscreenButton.tsx
+
+```
+import { selectFullscreen, usePlayer } from '@videojs/react';
+
+function FullscreenButton() {
+  const fs = usePlayer(selectFullscreen);
+  if (!fs || fs.fullscreenAvailability !== 'available') return null;
+
+  return (
+    <button onClick={fs.toggleFullscreen}>
+      {fs.fullscreen ? 'Exit fullscreen' : 'Fullscreen'}
+    </button>
+  );
+}
+```
+
+### Screen orientation
+
+Add [`features.orientationLock`](./feature-orientation-lock.md) to lock screen orientation while fullscreen is active. Unsupported browsers and rejected lock requests are ignored, so iOS Safari continues to use its normal fullscreen behavior.
+
+The feature locks to `landscape` unless the provider sets another Screen Orientation API type.
+
+tsx
+
+```
+<Player orientationLockType="portrait">
+  <Container>
+    <video src="/video.mp4" />
+  </Container>
+</Player>
+```
+
+See [Orientation lock](./feature-orientation-lock.md) for the player setup.

package/docs/reference/feature-live.md

@@ -0,0 +1,62 @@
+# Live
+
+Live edge state for the player store
+
+Exposes live-edge state so components can render a “jump to live” button, detect DVR vs. standard live, or hide live-only UI for on-demand sources.
+
+`liveEdgeStart` is the presentation time at which the Live Edge Window begins — playback is “at the live edge” when `currentTime >= liveEdgeStart`. `targetLiveWindow` reports the seekable range size: `0` for standard latency live, `Infinity` for DVR, `NaN` for on-demand or unknown. Both values are `NaN` when the media doesn’t expose live-edge state (anything other than an HLS source today).
+
+The live feature is included by the `liveVideoFeatures` and `liveAudioFeatures` presets; apps that build a custom preset can compose it in directly.
+
+## API Reference
+
+### State
+
+Property
+
+Type
+
+Details
+
+`liveEdgeStart`
+
+`number`
+
+▸
+
+Description
+
+Presentation time marking the start of the Live Edge Window.
+
+Playing at the live edge when `currentTime >= liveEdgeStart`. `NaN` when the stream isn't live or the value is unknown.
+
+`targetLiveWindow`
+
+`number`
+
+▸
+
+Description
+
+Offset representing the seekable range size for live content.
+
+`0` for standard latency live, `Infinity` for DVR, `NaN` for on-demand or unknown.
+
+### Selector
+
+Pass `selectLive` to [`usePlayer`](./use-player.md) to subscribe to live state. Returns `undefined` if the live feature is not configured.
+
+LiveEdgeIndicator.tsx
+
+```
+import { selectLive, selectTime, usePlayer } from '@videojs/react';
+
+function LiveEdgeIndicator() {
+  const live = usePlayer(selectLive);
+  const time = usePlayer(selectTime);
+  if (!live || Number.isNaN(live.targetLiveWindow)) return null;
+
+  const atEdge = time != null && time.currentTime >= live.liveEdgeStart;
+  return <span className="live-indicator">{atEdge ? 'LIVE' : 'BEHIND LIVE'}</span>;
+}
+```

package/docs/reference/feature-metadata.md

@@ -0,0 +1,129 @@
+# Metadata
+
+Resolved title and poster values for the player store
+
+Resolves what is playing into two values your UI can render: `title` and `poster`.
+
+`title` and `poster` each resolve independently through the same two tiers: the value you set, then the value the media reports. The first tier that holds a value wins; when neither does, the resolved value is an empty string. Because the tiers stay separate, clearing the value you set reveals the media’s, and a source that reports a poster but no title contributes to one while leaving the other empty.
+
+An empty string counts as a value and stops the chain: set `title` to `''` and the resolved title is `''`. Pass `null` to clear your value.
+
+The metadata feature is included by the `videoFeatures`, `audioFeatures`, `liveVideoFeatures`, and `liveAudioFeatures` [presets](../concepts/presets.md); apps that build a custom preset can compose it in directly.
+
+## API Reference
+
+### Configuration
+
+Props the Player component accepts. They exist only while this feature is selected.
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`title`
+
+`undefined | null | string`
+
+`—`
+
+▸
+
+Description
+
+The title to display. Takes precedence over the title the media carries.
+
+`poster`
+
+`undefined | null | string`
+
+`—`
+
+▸
+
+Description
+
+The poster to display. Takes precedence over the poster the media carries.
+
+### State
+
+Property
+
+Type
+
+Details
+
+`title`
+
+`string`
+
+▸
+
+Description
+
+The resolved content title. Set it through the player, not through the store.
+
+`poster`
+
+`string`
+
+▸
+
+Description
+
+The resolved poster URL, independent of the media element's own `poster`. Set it through the player, not through the store.
+
+### Selector
+
+Pass `selectMetadata` to [`usePlayer`](./use-player.md) to subscribe to metadata state. Returns `undefined` if the metadata feature is not configured.
+
+ContentTitle.tsx
+
+```
+import { selectMetadata, usePlayer } from '@videojs/react';
+
+function ContentTitle() {
+  const metadata = usePlayer(selectMetadata);
+  if (!metadata?.title) return null;
+
+  return <h2 className="content-title">{metadata.title}</h2>;
+}
+```
+
+### Player inputs
+
+The store publishes the resolved values and takes no writes. A player input is the only way to set one.
+
+Every input is a prop on [`Player`](./player-provider.md). A player built without the metadata feature has none of them, and none is forwarded.
+
+App.tsx
+
+```
+import { Container, createPlayer } from '@videojs/react';
+import { videoFeatures } from '@videojs/react/video';
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+function App({ episode }: { episode: { title: string | null; art: string | null } }) {
+  return (
+    <Player title={episode.title} poster={episode.art}>
+      <Container>
+        <video src="episode.mp4" />
+      </Container>
+    </Player>
+  );
+}
+```
+
+Passing `null` clears your value, so `title={null}` falls through to the title the media reports.
+
+### Media-reported values
+
+The media tier comes from media that reports content data and announces changes to it, and it covers `title` and `poster`. A media reports only the keys it can vouch for, so either may be absent while the other arrives. A key that never arrives means that tier never contributes, and the resolved value is whatever you set. Detaching the media clears its values; the values you set survive and apply to the next source.
+
+`poster` is the feature’s own resolved value, not the media element’s `poster` attribute. Setting one does not set the other.
+
+A low-resolution stand-in to show while the poster loads is not part of this feature. The [poster](./poster.md) renders an `<img>` you control, so give it a `background-image` and that shows until the poster itself paints over it.

package/docs/reference/feature-orientation-lock.md

@@ -0,0 +1,121 @@
+# Orientation lock
+
+Screen orientation locking while fullscreen is active
+
+Locks screen orientation while fullscreen is active. Add it explicitly to a feature list; it is not included in the default video presets.
+
+## API Reference
+
+### Configuration
+
+Props the Player component accepts. They exist only while this feature is selected.
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`orientationLockType`
+
+`undefined | null | 'any' | 'landscape' | 'landscape-primary' | 'landscape-secondary' | 'natural' | 'portrait' | 'portrait-primary' | 'portrait-secondary'`
+
+`'landscape'`
+
+▸
+
+Description
+
+Screen orientation type to lock while fullscreen is active.
+
+### State
+
+Property
+
+Type
+
+Details
+
+`orientationLockType`
+
+`'any' | 'landscape' | 'landscape-primary' | 'landscape-secondary' | 'natural' | 'portrait' | 'portrait-primary' | 'portrait-secondary'`
+
+▸
+
+Description
+
+Screen orientation type locked while fullscreen is active.
+
+### Actions
+
+Action
+
+Type
+
+Details
+
+`setOrientationLockType`
+
+`(value: undefined | null | 'any' | 'landscape' | 'landscape-primary' | 'landscape-secondary' | 'natural' | 'portrait' | 'portrait-primary' | 'portrait-secondary') => void`
+
+▸
+
+Description
+
+Sets the locked orientation type. Absent input — nullish, or the empty string a valueless HTML attribute produces — restores the default.
+
+### Usage
+
+Selecting the feature adds it to the player.
+
+player.tsx
+
+```
+import { Container, createPlayer, features } from '@videojs/react';
+import { videoFeatures } from '@videojs/react/video';
+
+export const { Player } = createPlayer({
+  features: [...videoFeatures, features.orientationLock],
+});
+```
+
+### Orientation type
+
+The feature locks to `landscape` unless the provider sets another Screen Orientation API type. The value can change while the player is running; if the screen is already locked, it re-locks to the new type.
+
+tsx
+
+```
+<Player orientationLockType="portrait">
+  <Container>
+    <video src="/video.mp4" />
+  </Container>
+</Player>
+```
+
+Clearing the value restores `landscape`.
+
+### Selector
+
+Pass `selectOrientationLock` to [`usePlayer`](./use-player.md) to subscribe to the lock state. Returns `undefined` if the orientation lock feature is not configured.
+
+OrientationToggle.tsx
+
+```
+import { selectOrientationLock, usePlayer } from '@videojs/react';
+
+function OrientationToggle() {
+  const lock = usePlayer(selectOrientationLock);
+  if (!lock) return null;
+
+  return (
+    <button onClick={() => lock.setOrientationLockType('portrait')}>
+      Lock portrait
+    </button>
+  );
+}
+```
+
+Unsupported browsers and rejected lock requests are ignored.

package/docs/reference/feature-pip.md

@@ -0,0 +1,94 @@
+# Picture-in-picture
+
+Picture-in-picture state and actions for the player store
+
+Controls picture-in-picture mode.
+
+## API Reference
+
+### State
+
+Property
+
+Type
+
+Details
+
+`pip`
+
+`boolean`
+
+▸
+
+Description
+
+Whether picture-in-picture mode is currently active.
+
+`pipAvailability`
+
+`'available' | 'unavailable' | 'unsupported'`
+
+▸
+
+Description
+
+Whether picture-in-picture can be requested on this platform.
+
+### Actions
+
+Action
+
+Type
+
+Details
+
+`requestPictureInPicture`
+
+`() => Promise<void>`
+
+▸
+
+Description
+
+Enter picture-in-picture mode.
+
+`exitPictureInPicture`
+
+`() => Promise<void>`
+
+▸
+
+Description
+
+Exit picture-in-picture mode.
+
+`togglePictureInPicture`
+
+`() => Promise<void>`
+
+▸
+
+Description
+
+Toggle picture-in-picture mode.
+
+### Selector
+
+Pass `selectPiP` to [`usePlayer`](./use-player.md) to subscribe to picture-in-picture state. Returns `undefined` if the PiP feature is not configured.
+
+PiPButton.tsx
+
+```
+import { selectPiP, usePlayer } from '@videojs/react';
+
+function PiPButton() {
+  const pip = usePlayer(selectPiP);
+  if (!pip || pip.availability !== 'available') return null;
+
+  return (
+    <button onClick={pip.toggle}>
+      {pip.active ? 'Exit PiP' : 'Picture-in-Picture'}
+    </button>
+  );
+}
+```

package/docs/reference/feature-playback-rate.md

@@ -0,0 +1,70 @@
+# Playback rate
+
+Playback speed state and actions for the player store
+
+Controls speed of playback.
+
+## API Reference
+
+### State
+
+Property
+
+Type
+
+Details
+
+`playbackRates`
+
+`readonly number[]`
+
+▸
+
+Description
+
+Available playback rates.
+
+`playbackRate`
+
+`number`
+
+▸
+
+Description
+
+Current playback rate.
+
+### Actions
+
+Action
+
+Type
+
+Details
+
+`setPlaybackRate`
+
+`(rate: number) => void`
+
+▸
+
+Description
+
+Set the playback rate.
+
+### Selector
+
+Pass `selectPlaybackRate` to [`usePlayer`](./use-player.md) to subscribe to playback rate state. Returns `undefined` if the playback rate feature is not configured.
+
+RateDisplay.tsx
+
+```
+import { selectPlaybackRate, usePlayer } from '@videojs/react';
+
+function RateDisplay() {
+  const rate = usePlayer(selectPlaybackRate);
+  if (!rate) return null;
+
+  return <span>{rate.playbackRate}x</span>;
+}
+```

package/docs/reference/feature-playback.md

@@ -0,0 +1,109 @@
+# Playback
+
+Play/pause state and actions for the player store
+
+Controls play/pause state and tracks whether playback has started or is stalled.
+
+## API Reference
+
+### State
+
+Property
+
+Type
+
+Details
+
+`paused`
+
+`boolean`
+
+▸
+
+Description
+
+Whether playback is paused.
+
+`ended`
+
+`boolean`
+
+▸
+
+Description
+
+Whether playback has reached the end.
+
+`started`
+
+`boolean`
+
+▸
+
+Description
+
+Whether playback has started (played or seeked).
+
+`waiting`
+
+`boolean`
+
+▸
+
+Description
+
+Whether playback is stalled waiting for data.
+
+### Actions
+
+Action
+
+Type
+
+Details
+
+`play`
+
+`() => Promise<void>`
+
+▸
+
+Description
+
+Start playback.
+
+`pause`
+
+`() => void`
+
+▸
+
+Description
+
+Pause playback.
+
+`togglePaused`
+
+`() => boolean`
+
+▸
+
+Description
+
+Toggle play/pause. Returns `true` if playback started.
+
+### Selector
+
+Pass `selectPlayback` to [`usePlayer`](./use-player.md) to subscribe to playback state. Returns `undefined` if the playback feature is not configured.
+
+PlayButton.tsx
+
+```
+import { selectPlayback, usePlayer } from '@videojs/react';
+
+function PlayButton() {
+  const playback = usePlayer(selectPlayback);
+  if (!playback) return null;
+  return <button onClick={playback.togglePaused}>{playback.paused ? 'Play' : 'Pause'}</button>;
+}
+```