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

package/docs/reference/render-element.md

@@ -0,0 +1,196 @@
+# renderElement
+
+Utility for rendering UI component elements with state-driven props and render prop support
+
+`renderElement` renders a UI component element, handling default tag rendering, render props (element or function), props merging, ref composition, and state-driven `className`/`style`.
+
+PlayButton.tsx
+
+```
+import { renderElement } from "@videojs/react";
+
+function PlayButton({ className, style, render, ...props }) {
+  const state = { paused: true };
+
+  return renderElement(
+    "button",
+    { className, style, render },
+    {
+      state,
+      ref: buttonRef,
+      props: [{ type: "button", "aria-label": "Play" }, props],
+    },
+  );
+}
+```
+
+The `className` and `style` component props accept either static values or functions that receive the current state:
+
+tsx
+
+```
+<PlayButton
+  className={(state) => (state.paused ? "paused" : "playing")}
+  style={(state) => ({ opacity: state.paused ? 0.5 : 1 })}
+/>
+```
+
+The `render` prop lets consumers fully customize the rendered element while preserving all internal props and refs:
+
+tsx
+
+```
+<PlayButton
+  render={(props, state) => (
+    <button {...props}>{state.paused ? "Play" : "Pause"}</button>
+  )}
+/>
+```
+
+## Examples
+
+### Basic Usage
+
+Activate
+
+Default <span>**Element <strong>***Inactive*
+
+App.tsx
+
+App.css
+
+```
+import { renderElement } from '@videojs/react';
+import { type ReactNode, useState } from 'react';
+
+interface TagState {
+  active: boolean;
+}
+
+function Tag({
+  className,
+  style,
+  render,
+  active,
+  children,
+}: renderElement.ComponentProps<TagState> & { active: boolean; children?: ReactNode }) {
+  const state: TagState = { active };
+
+  return renderElement(
+    'span',
+    { className, style, render },
+    {
+      state,
+      props: { children },
+      stateAttrMap: { active: 'data-active' },
+    }
+  );
+}
+
+export default function BasicUsage() {
+  const [active, setActive] = useState(false);
+
+  const className = (state: TagState) => `tag${state.active ? ' tag--active' : ''}`;
+
+  const style = (state: TagState) => ({
+    fontSize: state.active ? '1.125rem' : '0.875rem',
+  });
+
+  return (
+    <div className="demo">
+      <button type="button" className="toggle" onClick={() => setActive((prev) => !prev)}>
+        {active ? 'Deactivate' : 'Activate'}
+      </button>
+
+      <div className="tags">
+        <Tag active={active} className={className} style={style}>
+          Default &lt;span&gt;
+        </Tag>
+
+        <Tag active={active} className={className} style={style} render={<strong />}>
+          Element &lt;strong&gt;
+        </Tag>
+
+        <Tag
+          active={active}
+          className={className}
+          style={style}
+          render={(props, state) => <em {...props}>{state.active ? 'Active!' : 'Inactive'}</em>}
+        />
+      </div>
+    </div>
+  );
+}
+```
+```
+.demo {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  padding: 16px;
+}
+
+.toggle {
+  align-self: flex-start;
+  padding: 6px 16px;
+  cursor: pointer;
+  background: #f5f5f5;
+  border: 1px solid #ccc;
+  border-radius: 6px;
+}
+
+.tags {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px;
+}
+
+.tag {
+  display: inline-flex;
+  align-items: center;
+  padding: 6px 12px;
+  color: #374151;
+  background: #e5e7eb;
+  border-radius: 9999px;
+  transition: all 0.2s ease;
+}
+
+.tag--active {
+  color: white;
+  background: #3b82f6;
+}
+```
+
+## API Reference
+
+### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`element*`
+
+`TagName`
+
+`—`
+
+`componentProps*`
+
+`UseRenderComponentProps<object>`
+
+`—`
+
+`params*`
+
+`UseRenderParameters<object, Element>`
+
+`—`
+
+### Return Value
+
+`ReactElement | null`

package/docs/reference/seek-button.md

@@ -0,0 +1,213 @@
+# SeekButton
+
+Accessible seek button for skipping forward or backward by a configurable number of seconds
+
+## Anatomy
+
+tsx
+
+```
+<SeekButton />
+```
+
+## Behavior
+
+Seeks media by a configurable number of `seconds` (default 30). Positive values seek forward, negative values seek backward. The seek is clamped to media bounds (0 to duration).
+
+## Accessibility
+
+Renders a `<button>` with an automatic `aria-label` describing the action, e.g. “Seek forward 30 seconds” or “Seek backward 10 seconds”. Override with the `label` prop. Keyboard activation: Enter / Space.
+
+## Examples
+
+### Basic Usage
+
+⏪ 5s10s ⏩
+
+App.tsx
+
+App.css
+
+```
+import { createPlayer, SeekButton } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const Player = createPlayer({ features: videoFeatures });
+
+export default function BasicUsage() {
+  return (
+    <Player.Provider>
+      <Player.Container className="media-container">
+        <Video
+          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
+          autoPlay
+          muted
+          playsInline
+          loop
+        />
+        <div className="buttons">
+          <SeekButton
+            seconds={-5}
+            className="media-seek-button"
+            render={(props, state) => (
+              <button {...props}>
+                {state.direction === 'backward' ? '\u23EA' : '\u23E9'} {5}s
+              </button>
+            )}
+          />
+          <SeekButton
+            seconds={10}
+            className="media-seek-button"
+            render={(props, state) => (
+              <button {...props}>
+                {10}s {state.direction === 'forward' ? '\u23E9' : '\u23EA'}
+              </button>
+            )}
+          />
+        </div>
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.buttons {
+  position: absolute;
+  bottom: 10px;
+  left: 10px;
+  display: flex;
+  gap: 8px;
+}
+
+.media-seek-button {
+  padding-block: 8px;
+  padding-inline: 20px;
+  color: black;
+  white-space: nowrap;
+  cursor: pointer;
+  background: rgba(255, 255, 255, 0.7);
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+```
+
+## API Reference
+
+### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`disabled`
+
+`boolean`
+
+`false`
+
+▸
+
+Description
+
+Whether the button is disabled.
+
+`label`
+
+`string | function`
+
+`''`
+
+▸
+
+Description
+
+Custom label for the button.
+
+Type
+
+`string | ((state: SeekButtonState) => string)`
+
+`seconds`
+
+`number`
+
+`30`
+
+▸
+
+Description
+
+Seconds to seek. Positive = forward, negative = backward. Default `30`.
+
+### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+Property
+
+Type
+
+Details
+
+`seeking`
+
+`boolean`
+
+▸
+
+Description
+
+Whether a seek is in progress.
+
+`direction`
+
+`'forward' | 'backward'`
+
+▸
+
+Description
+
+Whether the button seeks forward or backward.
+
+`label`
+
+`string`
+
+### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-seeking`
+
+▸
+
+Description
+
+Present when a seek is in progress.
+
+`data-direction`
+
+`'forward' | 'backward'`
+
+▸
+
+Description
+
+Indicates the seek direction: `"forward"` or `"backward"`.