@videojs/react 10.0.0-rc.1 → 10.0.0-rc.2

package/docs/reference/playback-rate-radio-group.md

@@ -9,7 +9,7 @@ Creates radio items from the player playback rate state and selects the playback
 tsx
 
 ```
-import { PlaybackRateRadioGroup } from '@videojs/react';
+import { PlaybackRateRadioGroup } from '@videojs/react/ui/playback-rate-radio-group';
 ```
 
 ## Anatomy
@@ -17,21 +17,30 @@ import { PlaybackRateRadioGroup } from '@videojs/react';
 tsx
 
 ```
-<PlaybackRateRadioGroup
-  renderItem={(props, item) => (
-    <Menu.RadioItem {...props}>
-      {item.label}
-      <Menu.ItemIndicator checked={item.checked} />
-    </Menu.RadioItem>
-  )}
-/>
+<PlaybackRateRadioGroup.Root>
+  <Menu.Trigger>
+    <PlaybackRateRadioGroup.Value />
+  </Menu.Trigger>
+  <Menu.Content>
+    <PlaybackRateRadioGroup.Options
+      renderItem={(props, item) => (
+        <Menu.RadioItem {...props}>
+          {item.label}
+          <Menu.ItemIndicator checked={item.checked} />
+        </Menu.RadioItem>
+      )}
+    />
+  </Menu.Content>
+</PlaybackRateRadioGroup.Root>
 ```
 
 ## Behavior
 
 The group is available when the configured media exposes playback rates. Option labels default to the rate followed by a multiplication sign (e.g. `1.5×`); pass `formatRate` to customize them.
 
-`PlaybackRateRadioGroup` uses [`usePlaybackRateOptions`](./use-playback-rate-options.md) to own selection and generate each item. Its required `renderItem` callback renders the [`Menu.RadioItem`](./menu.md) root and receives item state containing the translated `label` and current `checked` value. It returns `null` when the [playback rate feature](./feature-playback-rate.md) is not configured.
+`PlaybackRateRadioGroup.Root` uses [`usePlaybackRateOptions`](./use-playback-rate-options.md) to own selection and renders no element. Wrap the menu’s `Menu.Trigger` and `Menu.Content` in it so the trigger inherits the group’s disabled and hidden state and exposes `data-availability`. `PlaybackRateRadioGroup.Options` renders the items: its required `renderItem` callback renders the [`Menu.RadioItem`](./menu.md) root and receives item state containing the translated `label` and current `checked` value. `PlaybackRateRadioGroup.Value` displays the selected label, typically inside the trigger. `Options` and `Value` render `null` when the [playback rate feature](./feature-playback-rate.md) is not configured.
+
+The `PlaybackRateRadioGroup` export from the `@videojs/react` root is a compatibility component that composes `Root` and `Options` behind the former single-component props. Prefer the parts for new code.
 
 ## Styling
 
@@ -71,20 +80,21 @@ Unavailable groups receive the native `hidden` attribute.
 
 The group uses the menu radio group pattern.
 
-The component receives an accessible label from the `label` prop or defaults to `Playback rate`. Override it with `aria-label` or `aria-labelledby`.
+`PlaybackRateRadioGroup.Options` receives its accessible label from the `label` prop on `PlaybackRateRadioGroup.Root` or defaults to `Playback rate`. Override it with `aria-label` or `aria-labelledby` on `PlaybackRateRadioGroup.Options`.
 
 ## Examples
 
 ### Basic usage
 
-Speed
+Speed1×
 
 App.tsx
 
 App.css
 
 ```
-import { Container, createPlayer, Menu, PlaybackRateRadioGroup } from '@videojs/react';
+import { Container, createPlayer, Menu } from '@videojs/react';
+import { PlaybackRateRadioGroup } from '@videojs/react/ui/playback-rate-radio-group';
 import { Video, videoFeatures } from '@videojs/react/video';
 import type { ReactNode } from 'react';
 
@@ -93,24 +103,27 @@ const { Player } = createPlayer({ features: videoFeatures });
 function SpeedMenu(): ReactNode {
   return (
     <Menu.Root side="top" align="end">
-      <Menu.Trigger className="settings-trigger" render={<button type="button" />}>
-        Speed
-      </Menu.Trigger>
-      <Menu.Popup className="menu">
-        <Menu.Content>
-          <PlaybackRateRadioGroup
-            className="menu-group"
-            renderItem={(props, item) => (
-              <Menu.RadioItem {...props} className="menu-item">
-                {item.label}
-                <Menu.ItemIndicator checked={item.checked} forceMount className="menu-indicator">
-                  ✓
-                </Menu.ItemIndicator>
-              </Menu.RadioItem>
-            )}
-          />
-        </Menu.Content>
-      </Menu.Popup>
+      <PlaybackRateRadioGroup.Root>
+        <Menu.Trigger className="settings-trigger" render={<button type="button" />}>
+          Speed
+          <PlaybackRateRadioGroup.Value className="menu-hint" />
+        </Menu.Trigger>
+        <Menu.Popup className="menu">
+          <Menu.Content>
+            <PlaybackRateRadioGroup.Options
+              className="menu-group"
+              renderItem={(props, item) => (
+                <Menu.RadioItem {...props} className="menu-item">
+                  {item.label}
+                  <Menu.ItemIndicator checked={item.checked} forceMount className="menu-indicator">
+                    ✓
+                  </Menu.ItemIndicator>
+                </Menu.RadioItem>
+              )}
+            />
+          </Menu.Content>
+        </Menu.Popup>
+      </PlaybackRateRadioGroup.Root>
     </Menu.Root>
   );
 }
@@ -153,6 +166,15 @@ export default function BasicUsage() {
   backdrop-filter: blur(10px);
 }
 
+.menu-hint {
+  margin-left: 8px;
+  color: rgba(0, 0, 0, 0.6);
+}
+
+.menu-hint:empty {
+  display: none;
+}
+
 .menu {
   --media-menu-side-offset: 8px;
   box-sizing: border-box;
@@ -210,6 +232,242 @@ export default function BasicUsage() {
 
 ### 
 
+Root
+
+Owns playback-rate option state and shares it with an enclosing menu. Does not render a DOM element.
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`disabled`
+
+`boolean`
+
+`false`
+
+▸
+
+Description
+
+Whether playback rate selection is disabled.
+
+`formatRate`
+
+`function`
+
+`formatPlaybackRate`
+
+▸
+
+Description
+
+Custom formatter for visible playback rate labels.
+
+Type
+
+`((rate: number) => string)`
+
+`label`
+
+`object`
+
+`''`
+
+▸
+
+Description
+
+Custom label for the options group.
+
+Type
+
+`{ key: string; text: string } | string | ((state: PlaybackRateRadioGroupState) => Text | string)`
+
+#### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+Property
+
+Type
+
+Details
+
+`label`
+
+`{ key: string; text: string } | string`
+
+`value`
+
+`string`
+
+▸
+
+Description
+
+Current radio-group value.
+
+`options`
+
+`readonly Option[]`
+
+▸
+
+Description
+
+Ordered options displayed by platform adapters.
+
+`disabled`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the entire option group is disabled.
+
+`hidden`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the option group is hidden because no meaningful selection is available.
+
+`availability`
+
+`'available' | 'unavailable'`
+
+▸
+
+Description
+
+Whether the media exposes a meaningful selection.
+
+`rate`
+
+`number`
+
+#### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-rate`
+
+`number`
+
+▸
+
+Description
+
+Current playback rate.
+
+`data-disabled`
+
+▸
+
+Description
+
+Present when playback rate selection is disabled.
+
+`data-hidden`
+
+▸
+
+Description
+
+Present when playback rate selection is unavailable.
+
+`data-availability`
+
+`'available' | 'unavailable'`
+
+▸
+
+Description
+
+Indicates playback rate availability (`available` or `unavailable`).
+
+### 
+
+Options
+
+Renders menu radio items for the player's available playback rates.
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`className`
+
+`string | ((state: PlaybackRateRadioGroupCore.State) => string | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Class name or function returning class name from state.
+
+`render`
+
+`ReactElement | ((props: HTMLProps, state: PlaybackRateRadioGroupCore.State) => ReactElement | null)`
+
+`—`
+
+▸
+
+Description
+
+Render prop for custom element.
+
+`renderItem`
+
+`((props: PlaybackRateRadioGroupItemProps, state: PlaybackRateRadioGroupItemState) => ReactElement)`
+
+`—`
+
+▸
+
+Description
+
+Render one consumer-owned menu radio item for every playback rate.
+
+`style`
+
+`CSSProperties | ((state: PlaybackRateRadioGroupCore.State) => CSSProperties | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Style or function returning style from state.
+
+### 
+
 Value
 
 Displays the selected playback-rate label.

package/docs/reference/poster.md

@@ -15,7 +15,9 @@ import { Poster } from '@videojs/react';
 tsx
 
 ```
-<Poster />
+<Poster.Root>
+  <Poster.Image />
+</Poster.Root>
 ```
 
 ## Behavior
@@ -34,24 +36,28 @@ tsx
 
 The component fills in a source only when you leave one out. `srcset`, `sizes`, `loading`, `<picture>`, and framework image components all stay available.
 
-The component is the `<img>`, so image attributes go straight on it:
+`Poster.Root` owns visibility and loading state. Image attributes go on `Poster.Image`:
 
 tsx
 
 ```
-<Poster srcSet="poster-480.jpg 480w, poster-1080.jpg 1080w" sizes="100vw" />
+<Poster.Root>
+  <Poster.Image srcSet="poster-480.jpg 480w, poster-1080.jpg 1080w" sizes="100vw" />
+</Poster.Root>
 ```
 
-To render something else, use `render`. It receives the poster URL as `src`, undefined until one resolves:
+To render a different image component, use `render` on `Poster.Image`. It receives the poster URL as `src`, undefined until one resolves:
 
 tsx
 
 ```
-<Poster
-  render={({ src, ...props }: ComponentProps<'img'>) =>
-    src ? <Image {...props} src={src} alt="" fill /> : null
-  }
-/>
+<Poster.Root>
+  <Poster.Image
+    render={({ src, ...props }: ComponentProps<'img'>) =>
+      src ? <Image {...props} src={src} alt="" fill /> : null
+    }
+  />
+</Poster.Root>
 ```
 
 Inside a skin, pass the same function as `renderPoster`. The skin draws your image in place of its own:
@@ -102,7 +108,17 @@ Present when the image failed
 
 The three load attributes track the image on screen, including one you supplied yourself.
 
-React renders an `<img>` element. Add a `className` to style it:
+React renders a root `<div>` around the `<img>`. The state attributes are on `Poster.Root`, so other presentation layers can use the same lifecycle:
+
+tsx
+
+```
+<Poster.Root className="media-poster">
+  <img className="media-poster-blur" src={blurDataURL} alt="" aria-hidden />
+  <Poster.Image className="media-poster-image" />
+  <div className="media-poster-overlay" aria-hidden />
+</Poster.Root>
+```
 
 css
 
@@ -110,6 +126,10 @@ css
 .media-poster:not([data-visible]) {
   opacity: 0;
 }
+
+.media-poster:not([data-loading]) .media-poster-blur {
+  opacity: 0;
+}
 ```
 
 ## Accessibility
@@ -121,7 +141,9 @@ The image is decorative by default (`alt=""`), since a URL says nothing about wh
 tsx
 
 ```
-<Poster alt="Keynote speaker at a conference" />
+<Poster.Root>
+  <Poster.Image alt="Keynote speaker at a conference" />
+</Poster.Root>
 ```
 
 Whether a poster is informative or decorative is your judgment, per the [WAI guidelines](https://www.w3.org/WAI/tutorials/images/decorative/).
@@ -130,7 +152,9 @@ Whether a poster is informative or decorative is your judgment, per the [WAI gui
 
 ### Basic Usage
 
-![](https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg)Play
+![](https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg)
+
+Play
 
 App.tsx
 
@@ -148,7 +172,9 @@ export default function BasicUsage() {
       <Container className="media-container">
         <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" playsInline />
 
-        <Poster className="media-poster" />
+        <Poster.Root className="media-poster">
+          <Poster.Image className="media-poster-image" />
+        </Poster.Root>
 
         <PlayButton
           className="media-play-button"
@@ -174,7 +200,6 @@ export default function BasicUsage() {
   width: 100%;
   height: 100%;
   pointer-events: none;
-  object-fit: cover;
   transition: opacity 0.25s;
 }
 
@@ -182,6 +207,12 @@ export default function BasicUsage() {
   opacity: 0;
 }
 
+.media-poster-image {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
 .media-play-button {
   position: absolute;
   bottom: 10px;
@@ -199,23 +230,15 @@ export default function BasicUsage() {
 
 ## API Reference
 
-### Props
+### 
 
-Prop
+Root
 
-Type
+Manages poster visibility and image loading state.
 
-Default
+Renders a `div` and exposes `data-visible`, `data-loading`, `data-loaded`, and `data-error` for styling every layer in the poster presentation. Render `Poster.Image` inside it for the image that supplies the loading lifecycle.
 
-Details
-
-`src`
-
-`string`
-
-`—`
-
-### State
+#### State
 
 State is accessible via the `render`, `className`, and `style` props.
 
@@ -275,7 +298,7 @@ Description
 
 Whether the poster image failed.
 
-### Data attributes
+#### Data attributes
 
 Attribute
 
@@ -313,4 +336,58 @@ Present once the poster image has decoded.
 
 Description
 
-Present when the poster image failed.
+Present when the poster image failed.
+
+### 
+
+Image
+
+Displays the poster image managed by `Poster.Root`.
+
+Renders an `img`, so `srcSet`, `sizes`, `loading`, and the rest of the native image attributes remain available. Leave the source off and the player's resolved poster fills it in. The image is decorative unless you supply `alt`.
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`className`
+
+`string | ((state: PosterCore.State) => string | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Class name or function returning class name from state.
+
+`render`
+
+`ReactElement | ((props: HTMLProps, state: PosterCore.State) => ReactElement | null)`
+
+`—`
+
+▸
+
+Description
+
+Render prop for custom element.
+
+`style`
+
+`CSSProperties | ((state: PosterCore.State) => CSSProperties | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Style or function returning style from state.