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

package/docs/reference/player-container.md

@@ -0,0 +1,100 @@
+# Container
+
+The player's visual and interaction surface for layout, fullscreen, focus, and user activity.
+
+The `Container` is the player’s physical surface. It defines the visual boundary, registers the fullscreen and activity target, and gives gesture and hotkey components a shared interaction surface. It lives inside a [`Player`](./player.md).
+
+tsx
+
+```
+<Player>
+  <Container>
+    <Video src="video.mp4" />
+    <Controls.Root>
+      <Controls.Content>{/* ... */}</Controls.Content>
+    </Controls.Root>
+  </Container>
+</Player>
+```
+
+## How it’s created
+
+Import `Container` from the main React package. It connects to whichever `Player` contains it, so it does not need to be created for a specific feature set.
+
+tsx
+
+```
+import { Container, createPlayer } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player } = createPlayer({ features: videoFeatures });
+```
+
+- [createPlayer reference](./create-player.md)
+
+## What it does
+
+### Layout and fullscreen
+
+The container is the visual box around your media and controls. Put sizing, aspect ratio, positioning, and visual boundaries here — on `Container`, not `Player`. Place overlays inside it, use it as their positioning context, and measure it when your app needs the rendered player size.
+
+tsx
+
+```
+<Container style={{ position: 'relative', width: 640, aspectRatio: '16/9' }}>
+  <Video src="video.mp4" />
+  <Controls.Root>
+    <Controls.Content>{/* ... */}</Controls.Content>
+  </Controls.Root>
+</Container>
+```
+
+When the user goes fullscreen, the **container** goes fullscreen — not the video element. This keeps controls and other UI visible on top of the video, since they’re children of the container.
+
+React media components such as `MuxVideo` render a native media element, so the media itself has a box. The container remains the shared layout and fullscreen target for the media and its overlays.
+
+### Media attachment
+
+Media discovery is handled by `Player`, not `Container`. When a media component like `<Video>` registers itself via context, `Player` wires it to the store and all of the player’s features.
+
+### Interaction surface
+
+The container is where user intent enters the player. It listens for physical interaction on its surface and translates that into player behavior:
+
+*   **User activity** — Mouse movement, touch, and keyboard activity within the container drive idle detection. This is how controls know when to show and hide.
+*   **Gestures** — Tap and double-tap actions, optionally limited by pointer type and left, center, or right region. Configured via the [`Gesture`](./gesture.md) component.
+*   **Keyboard controls** — Spacebar to play/pause, arrow keys to seek, and other keyboard shortcuts scoped to the container. Configured via the `Hotkey` component.
+
+### Popup coordination
+
+Each container owns one popup group. Opening a root [menu](./menu.md) or [popover](./popover.md) closes the previously open popup in that container. A popup rendered outside the container still manages its own open state, but it does not participate in the container’s group.
+
+## Relationship to skins
+
+A [skin](../concepts/skins.md) is a container plus UI controls. When you use a packaged skin, the container is built in — you don’t need to add one yourself.
+
+Style `VideoSkin` for the player’s outer size and aspect ratio. Its `skin.css` import makes the built-in container fill that space and positions the media, controls, poster, and overlays.
+
+If you omit `VideoSkin` to build custom UI, render and style `Container` yourself. See [Layout and fullscreen](#layout-and-fullscreen) for the complete layout example.
+
+## Inside vs. outside the container
+
+[`Player`](./player.md) gives components access to state and actions. `Container` layers on physical behaviors — fullscreen, activity detection, and gesture handling. Components work in both places; the container just adds those extras.
+
+tsx
+
+```
+<Player>
+  <Container>
+    <Video src="video.mp4" />
+    <Controls.Root>          {/* fullscreen, activity detection, gestures */}
+      <Controls.Content>{/* ... */}</Controls.Content>
+    </Controls.Root>
+  </Container>
+
+  <Transcript />          {/* state & actions, but no container behaviors */}
+  <PlaylistSidebar />     {/* state & actions, but no container behaviors */}
+</Player>
+```
+
+A play button outside the container still reads playback state and can toggle play/pause — it just won’t go fullscreen with the player or respond to the container’s idle state.

package/docs/reference/player.md

@@ -0,0 +1,108 @@
+# Player
+
+The state boundary — creates a store and broadcasts it to all descendants.
+
+The `Player` is the state boundary of your player. It creates a store and makes it available to every component inside it via context. Every player needs exactly one.
+
+App.tsx
+
+```
+import { Video, videoFeatures } from '@videojs/react/video';
+import { Container, createPlayer } from '@videojs/react';
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+function App() {
+  return (
+    <Player>
+      {/* Everything inside can access the player store */}
+      <Container>
+        <Video src="video.mp4" />
+      </Container>
+    </Player>
+  );
+}
+```
+
+## How it’s created
+
+Call `createPlayer()` with a `features` array. It returns `Player`, `usePlayer`, and `useMedia`. Import the shared `Container` separately when building a custom layout.
+
+tsx
+
+```
+import { Container, createPlayer } from '@videojs/react';
+import { videoFeatures } from '@videojs/react/video';
+
+const { Player, usePlayer, useMedia } = createPlayer({
+  features: videoFeatures,
+});
+```
+
+The [features](../concepts/features.md) you pass determine what state is available in the store. `videoFeatures` is a [preset](../concepts/presets.md) that includes playback, volume, fullscreen, and other standard video controls.
+
+- [createPlayer reference](./create-player.md)
+
+## What lives inside it
+
+Everything that needs player state goes inside `Player`: skins, containers, UI components, and your own custom components. Anything inside can access the store.
+
+tsx
+
+```
+<Player>
+  <VideoSkin>           {/* skin — includes container + controls */}
+    <Video src="..." /> {/* media element */}
+  </VideoSkin>
+  <MyCustomOverlay />   {/* your own component — can use usePlayer() */}
+</Player>
+```
+
+## No visual presence
+
+`Player` renders no DOM element of its own — it’s purely a state wrapper. Put sizing, positioning, borders, backgrounds, and DOM measurements on the [`Container`](./player-container.md), not `Player`.
+
+`Player` is the Provider half of a React Context pair, with [`usePlayer`](./use-player.md) as its consumer, and it renders nothing. If a component needs player state, lift `Player` above it the way you’d lift any Provider: wrapping a page section, a route, or even your whole app in `Player` costs nothing visually and keeps `usePlayer` available wherever you need it.
+
+## Accessing state
+
+Use `usePlayer` to read state or call actions from any component inside `Player`:
+
+PlayPauseButton.tsx
+
+```
+import { selectPlayback, usePlayer } from '@videojs/react';
+
+function PlayPauseButton() {
+  const playback = usePlayer(selectPlayback);
+  if (!playback) return null;
+
+  return (
+    <button onClick={() => playback.togglePaused()}>
+      {playback.paused ? 'Play' : 'Pause'}
+    </button>
+  );
+}
+```
+
+- [usePlayer reference](./use-player.md)
+
+## Extended player layouts
+
+The player’s scope can extend beyond the fullscreen target. Playlists, transcripts, sidebars, and other supplementary UI can live inside `Player` but outside `Container`. They still have full access to the store, but they won’t go fullscreen with the video.
+
+tsx
+
+```
+<Player>
+  <Container>
+    <Video src="video.mp4" />
+    <Controls.Root>          {/* goes fullscreen with the video */}
+      <Controls.Content>{/* ... */}</Controls.Content>
+    </Controls.Root>
+  </Container>
+
+  <Transcript />          {/* outside container — still has store access */}
+  <PlaylistSidebar />     {/* outside container — still has store access */}
+</Player>
+```