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

package/dist/dev/utils/use-render.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-render.js","names":[],"sources":["../../../src/utils/use-render.tsx"],"sourcesContent":["import { getStateDataAttrs, type StateAttrMap } from '@videojs/core/dom';\nimport { isFunction } from '@videojs/utils/predicate';\nimport { resolveClassName } from '@videojs/utils/style';\nimport type { CSSProperties, ReactElement, Ref } from 'react';\nimport { cloneElement, createElement, isValidElement } from 'react';\n\nimport { mergeProps } from './merge-props';\nimport type { HTMLProps, RenderProp } from './types';\nimport { composeRefs } from './use-composed-refs';\n\n/** Check if a value is a render prop (function or React element). */\nexport function isRenderProp(value: unknown): value is RenderProp<unknown> {\n  return isFunction(value) || isValidElement(value);\n}\n\ntype IntrinsicTagName = keyof React.JSX.IntrinsicElements;\n\nexport interface UseRenderComponentProps<State> {\n  className?: string | ((state: State) => string | undefined) | undefined;\n  style?: CSSProperties | ((state: State) => CSSProperties | undefined) | undefined;\n  render?: RenderProp<State> | undefined;\n}\n\nexport interface UseRenderParameters<State, RenderedElementType extends Element> {\n  state: State;\n  ref?: Ref<RenderedElementType> | Ref<RenderedElementType>[] | undefined;\n  props?: object | object[] | undefined;\n  stateAttrMap?: StateAttrMap<State> | undefined;\n}\n\nfunction resolveStyle<State>(\n  style: CSSProperties | ((state: State) => CSSProperties | undefined) | undefined,\n  state: State\n): CSSProperties | undefined {\n  return isFunction(style) ? style(state) : style;\n}\n\nfunction getElementRef(element: ReactElement): Ref<unknown> | undefined {\n  // React 19+ uses element.props.ref, older versions use element.ref\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const elementAny = element as any;\n\n  return elementAny.ref ?? elementAny.props?.ref;\n}\n\nfunction mergeRefs<T>(...refs: (Ref<T> | Ref<T>[] | undefined)[]): Ref<T> | undefined {\n  const flatRefs = refs.flat().filter((ref): ref is Ref<T> => ref !== null && ref !== undefined);\n  if (flatRefs.length === 0) return undefined;\n\n  if (flatRefs.length === 1) return flatRefs[0];\n\n  return composeRefs(...flatRefs);\n}\n\n/**\n * Render a UI component element.\n *\n * Handles: - Default tag rendering - Render prop (element or function) - Props merging (event handlers chained,\n * className concatenated, style merged) - Ref composition - className/style as functions of state\n *\n * @example\n *   ```tsx\n *   return renderElement('button', componentProps, {\n *     state,\n *     ref: [forwardedRef, buttonRef],\n *     props: [{ type: 'button' }, elementProps, getButtonProps],\n *   });\n *   ```;\n *\n * @public\n */\nexport function renderElement<\n  State extends object,\n  RenderedElementType extends Element,\n  TagName extends IntrinsicTagName,\n>(\n  element: TagName,\n  componentProps: UseRenderComponentProps<State>,\n  params: UseRenderParameters<State, RenderedElementType>\n): ReactElement | null {\n  const { className: classNameProp, style: styleProp, render } = componentProps;\n  const { state, ref, props, stateAttrMap } = params;\n\n  // Resolve className and style if they're functions\n  const className = resolveClassName(classNameProp, state);\n  const style = resolveStyle(styleProp, state);\n\n  // Generate data attributes only when a component explicitly opts in with a\n  // mapping. State is still passed to render/className/style callbacks.\n  const stateDataAttrs = stateAttrMap ? getStateDataAttrs(state, stateAttrMap) : {};\n\n  // Merge: state data attrs first, then props (so props can override)\n  const propsArray = Array.isArray(props) ? props : props ? [props] : [];\n  const mergedProps = mergeProps(stateDataAttrs, ...(propsArray as Record<string, unknown>[]));\n\n  if (className !== undefined) {\n    // Add resolved className and style\n    mergedProps.className = mergedProps.className ? `${mergedProps.className} ${className}` : className;\n  }\n\n  if (style !== undefined) {\n    mergedProps.style = mergedProps.style ? { ...(mergedProps.style as CSSProperties), ...style } : style;\n  }\n\n  if (isFunction(render)) {\n    // Render function: call with props and state\n    const mergedRef = mergeRefs(ref, mergedProps.ref);\n\n    return render({ ...mergedProps, ref: mergedRef } as HTMLProps, state);\n  }\n\n  if (isValidElement(render)) {\n    const elementRef = getElementRef(render);\n\n    const mergedRef = mergeRefs(ref, mergedProps.ref, elementRef);\n\n    const elementProps = mergeProps(mergedProps, render.props as Record<string, unknown>);\n\n    elementProps.ref = mergedRef;\n\n    return cloneElement(render, elementProps);\n  }\n\n  // Default tag\n  const mergedRef = mergeRefs(ref, mergedProps.ref);\n\n  mergedProps.ref = mergedRef;\n\n  return createElement(element, mergedProps);\n}\n\nexport namespace renderElement {\n  export type ComponentProps<State> = UseRenderComponentProps<State>;\n  export type Parameters<State, RenderedElementType extends Element> = UseRenderParameters<State, RenderedElementType>;\n}\n"],"mappings":";;;;;;;AA8BA,SAAS,aACP,OACA,OAC2B;CAC3B,OAAO,WAAW,KAAK,IAAI,MAAM,KAAK,IAAI;AAC5C;AAEA,SAAS,cAAc,SAAiD;CAGtE,MAAM,aAAa;CAEnB,OAAO,WAAW,OAAO,WAAW,OAAO;AAC7C;AAEA,SAAS,UAAa,GAAG,MAA6D;CACpF,MAAM,WAAW,KAAK,KAAK,CAAC,CAAC,QAAQ,QAAuB,QAAQ,QAAQ,QAAQ,KAAA,CAAS;CAC7F,IAAI,SAAS,WAAW,GAAG,OAAO,KAAA;CAElC,IAAI,SAAS,WAAW,GAAG,OAAO,SAAS;CAE3C,OAAO,YAAY,GAAG,QAAQ;AAChC;;;;;;;;;;;;;;;;;;AAmBA,SAAgB,cAKd,SACA,gBACA,QACqB;CACrB,MAAM,EAAE,WAAW,eAAe,OAAO,WAAW,WAAW;CAC/D,MAAM,EAAE,OAAO,KAAK,OAAO,iBAAiB;CAG5C,MAAM,YAAY,iBAAiB,eAAe,KAAK;CACvD,MAAM,QAAQ,aAAa,WAAW,KAAK;CAI3C,MAAM,iBAAiB,eAAe,kBAAkB,OAAO,YAAY,IAAI,CAAC;CAIhF,MAAM,cAAc,WAAW,gBAAgB,GAD5B,MAAM,QAAQ,KAAK,IAAI,QAAQ,QAAQ,CAAC,KAAK,IAAI,CAAC,CACsB;CAE3F,IAAI,cAAc,KAAA,GAEhB,YAAY,YAAY,YAAY,YAAY,GAAG,YAAY,UAAU,GAAG,cAAc;CAG5F,IAAI,UAAU,KAAA,GACZ,YAAY,QAAQ,YAAY,QAAQ;EAAE,GAAI,YAAY;EAAyB,GAAG;CAAM,IAAI;CAGlG,IAAI,WAAW,MAAM,GAAG;EAEtB,MAAM,YAAY,UAAU,KAAK,YAAY,GAAG;EAEhD,OAAO,OAAO;GAAE,GAAG;GAAa,KAAK;EAAU,GAAgB,KAAK;CACtE;CAEA,IAAI,eAAe,MAAM,GAAG;EAC1B,MAAM,aAAa,cAAc,MAAM;EAEvC,MAAM,YAAY,UAAU,KAAK,YAAY,KAAK,UAAU;EAE5D,MAAM,eAAe,WAAW,aAAa,OAAO,KAAgC;EAEpF,aAAa,MAAM;EAEnB,OAAO,aAAa,QAAQ,YAAY;CAC1C;CAKA,YAAY,MAFM,UAAU,KAAK,YAAY,GAEnB;CAE1B,OAAO,cAAc,SAAS,WAAW;AAC3C"}
+{"version":3,"file":"use-render.js","names":[],"sources":["../../../src/utils/use-render.tsx"],"sourcesContent":["import { getStateDataAttrs, type StateAttrMap } from '@videojs/core/dom';\nimport { isFunction, isObject } from '@videojs/utils/predicate';\nimport { resolveClassName } from '@videojs/utils/style';\nimport type { CSSProperties, FunctionComponent, ReactElement, ReactNode, Ref } from 'react';\nimport { cloneElement, createElement, forwardRef, isValidElement, memo, version } from 'react';\n\nimport { mergeProps } from './merge-props';\nimport type { HTMLProps, RenderProp } from './types';\nimport { composeRefs } from './use-composed-refs';\n\n/** Check if a value is a render prop (function or React element). */\nexport function isRenderProp(value: unknown): value is RenderProp<unknown> {\n  return isFunction(value) || isValidElement(value);\n}\n\ntype IntrinsicTagName = keyof React.JSX.IntrinsicElements;\n\nexport interface UseRenderComponentProps<State> {\n  className?: string | ((state: State) => string | undefined) | undefined;\n  style?: CSSProperties | ((state: State) => CSSProperties | undefined) | undefined;\n  render?: RenderProp<State> | undefined;\n}\n\nexport interface UseRenderParameters<State, RenderedElementType extends Element> {\n  state: State;\n  ref?: Ref<RenderedElementType> | Ref<RenderedElementType>[] | undefined;\n  props?: object | object[] | undefined;\n  stateAttrMap?: StateAttrMap<State> | undefined;\n}\n\nfunction resolveStyle<State>(\n  style: CSSProperties | ((state: State) => CSSProperties | undefined) | undefined,\n  state: State\n): CSSProperties | undefined {\n  return isFunction(style) ? style(state) : style;\n}\n\nfunction getElementRef(element: ReactElement): Ref<unknown> | undefined {\n  // React 19+ uses element.props.ref, older versions use element.ref\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const elementAny = element as any;\n\n  return elementAny.ref ?? elementAny.props?.ref;\n}\n\n/**\n * React 19 passes `ref` to function components as a prop. React 18 and Preact compat only deliver it through\n * `forwardRef`, so a plain function used as a render target needs wrapping there.\n */\nconst REF_AS_PROP = Number.parseInt(version, 10) >= 19;\nconst REACT_MEMO_TYPE = Symbol.for('react.memo');\n\n/** What a React element's `type` can be: an intrinsic tag name or a component. */\ntype ComponentOrTag = ReactElement['type'];\ntype UnknownProps = Record<string, unknown>;\n\n/** The runtime shape of a `memo()` result. */\ninterface MemoComponent {\n  readonly type: ComponentOrTag;\n  readonly compare?: ((prev: Readonly<UnknownProps>, next: Readonly<UnknownProps>) => boolean) | undefined;\n}\n\n/** Original component, or memo wrapper, to the ref-forwarding component created for it. */\nconst refForwardingCache = new WeakMap<object, ComponentOrTag>();\n\nfunction isPlainFunctionComponent(type: unknown): type is FunctionComponent<UnknownProps> {\n  if (!isFunction(type) || '$$typeof' in type) return false;\n\n  const prototype: unknown = type.prototype;\n\n  return !(isObject(prototype) && 'isReactComponent' in prototype);\n}\n\nfunction isMemoComponent(type: unknown): type is object & MemoComponent {\n  return isObject(type) && '$$typeof' in type && type.$$typeof === REACT_MEMO_TYPE;\n}\n\n/** Wrap a plain function component in `forwardRef` so it receives `ref` inside its props, as it would on React 19. */\nfunction withForwardedRef(component: FunctionComponent<UnknownProps>): ComponentOrTag {\n  const cached = refForwardingCache.get(component);\n  if (cached) return cached;\n\n  const ForwardedComponent = forwardRef<unknown, UnknownProps>((props, ref) => {\n    // SAFETY: a render target is invoked synchronously during render, so it cannot be an async component.\n    return component({ ...props, ref }) as ReactNode;\n  });\n\n  if (__DEV__) ForwardedComponent.displayName = component.displayName ?? component.name;\n\n  refForwardingCache.set(component, ForwardedComponent);\n\n  return ForwardedComponent;\n}\n\n/**\n * Resolve the type to create a render element with so the host's composed ref reaches it. Intrinsic tags, classes, and\n * `forwardRef` components already accept refs. Plain function components, bare or wrapped in `memo`, only do on\n * renderers with ref-as-prop and are wrapped otherwise.\n */\nfunction ensureRefForwarding(type: ComponentOrTag): ComponentOrTag {\n  if (REF_AS_PROP) return type;\n\n  if (isPlainFunctionComponent(type)) return withForwardedRef(type);\n\n  if (!isMemoComponent(type) || !isPlainFunctionComponent(type.type)) return type;\n\n  const cached = refForwardingCache.get(type);\n  if (cached) return cached;\n\n  // SAFETY: the wrapper is a forwardRef component, which `memo` accepts wherever a function component is expected.\n  const forwarded = memo(withForwardedRef(type.type) as FunctionComponent<UnknownProps>, type.compare);\n\n  refForwardingCache.set(type, forwarded);\n\n  return forwarded;\n}\n\nfunction mergeRefs<T>(...refs: (Ref<T> | Ref<T>[] | undefined)[]): Ref<T> | undefined {\n  const flatRefs = refs.flat().filter((ref): ref is Ref<T> => ref !== null && ref !== undefined);\n  if (flatRefs.length === 0) return undefined;\n\n  if (flatRefs.length === 1) return flatRefs[0];\n\n  return composeRefs(...flatRefs);\n}\n\n/**\n * Render a UI component element.\n *\n * Handles: - Default tag rendering - Render prop (element or function) - Props merging (event handlers chained,\n * className concatenated, style merged) - Ref composition - className/style as functions of state\n *\n * @example\n *   ```tsx\n *   return renderElement('button', componentProps, {\n *     state,\n *     ref: [forwardedRef, buttonRef],\n *     props: [{ type: 'button' }, elementProps, getButtonProps],\n *   });\n *   ```;\n *\n * @public\n */\nexport function renderElement<\n  State extends object,\n  RenderedElementType extends Element,\n  TagName extends IntrinsicTagName,\n>(\n  element: TagName,\n  componentProps: UseRenderComponentProps<State>,\n  params: UseRenderParameters<State, RenderedElementType>\n): ReactElement | null {\n  const { className: classNameProp, style: styleProp, render } = componentProps;\n  const { state, ref, props, stateAttrMap } = params;\n\n  // Resolve className and style if they're functions\n  const className = resolveClassName(classNameProp, state);\n  const style = resolveStyle(styleProp, state);\n\n  // Generate data attributes only when a component explicitly opts in with a\n  // mapping. State is still passed to render/className/style callbacks.\n  const stateDataAttrs = stateAttrMap ? getStateDataAttrs(state, stateAttrMap) : {};\n\n  // Merge: state data attrs first, then props (so props can override)\n  const propsArray = Array.isArray(props) ? props : props ? [props] : [];\n  const mergedProps = mergeProps(stateDataAttrs, ...(propsArray as Record<string, unknown>[]));\n\n  if (className !== undefined) {\n    // Add resolved className and style\n    mergedProps.className = mergedProps.className ? `${mergedProps.className} ${className}` : className;\n  }\n\n  if (style !== undefined) {\n    mergedProps.style = mergedProps.style ? { ...(mergedProps.style as CSSProperties), ...style } : style;\n  }\n\n  if (isFunction(render)) {\n    // Render function: call with props and state\n    const mergedRef = mergeRefs(ref, mergedProps.ref);\n\n    return render({ ...mergedProps, ref: mergedRef } as HTMLProps, state);\n  }\n\n  if (isValidElement(render)) {\n    const elementRef = getElementRef(render);\n\n    const mergedRef = mergeRefs(ref, mergedProps.ref, elementRef);\n\n    const elementProps = mergeProps(mergedProps, render.props as Record<string, unknown>);\n\n    elementProps.ref = mergedRef;\n\n    const type = ensureRefForwarding(render.type);\n    if (type === render.type) return cloneElement(render, elementProps);\n\n    if (render.key != null) elementProps.key = render.key;\n\n    return createElement(type, elementProps);\n  }\n\n  // Default tag\n  const mergedRef = mergeRefs(ref, mergedProps.ref);\n\n  mergedProps.ref = mergedRef;\n\n  return createElement(element, mergedProps);\n}\n\nexport namespace renderElement {\n  export type ComponentProps<State> = UseRenderComponentProps<State>;\n  export type Parameters<State, RenderedElementType extends Element> = UseRenderParameters<State, RenderedElementType>;\n}\n"],"mappings":"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"}

package/dist/dev/utils/use-safe-id.js

@@ -1,3 +1,4 @@
+import { c } from "react-compiler-runtime";
 import { useId } from "react";
 //#region src/utils/use-safe-id.ts
 const UNSAFE_CHARS = /[^a-zA-Z0-9_-]/g;
@@ -9,7 +10,15 @@ const UNSAFE_CHARS = /[^a-zA-Z0-9_-]/g;
 * prepends a prefix.
 */
 function useSafeId(prefix) {
-	const raw = useId().replace(UNSAFE_CHARS, "");
+	const $ = c(2);
+	const t0 = useId();
+	let t1;
+	if ($[0] !== t0) {
+		t1 = t0.replace(UNSAFE_CHARS, "");
+		$[0] = t0;
+		$[1] = t1;
+	} else t1 = $[1];
+	const raw = t1;
 	return prefix ? `${prefix}-${raw}` : raw;
 }
 //#endregion

package/dist/dev/utils/use-safe-id.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-safe-id.js","names":[],"sources":["../../../src/utils/use-safe-id.ts"],"sourcesContent":["import { useId } from 'react';\n\nconst UNSAFE_CHARS = /[^a-zA-Z0-9_-]/g;\n\n/**\n * Generate a CSS-safe identifier from React's `useId()`.\n *\n * `useId()` returns values like `:r0:` which contain colons — invalid in CSS `<dashed-ident>` tokens (used by\n * `anchor-name` / `position-anchor`). This hook strips non-alphanumeric/underscore/hyphen characters and optionally\n * prepends a prefix.\n */\nexport function useSafeId(prefix?: string): string {\n  const raw = useId().replace(UNSAFE_CHARS, '');\n\n  return prefix ? `${prefix}-${raw}` : raw;\n}\n"],"mappings":";;AAEA,MAAM,eAAe;;;;;;;;AASrB,SAAgB,UAAU,QAAyB;CACjD,MAAM,MAAM,MAAM,CAAC,CAAC,QAAQ,cAAc,EAAE;CAE5C,OAAO,SAAS,GAAG,OAAO,GAAG,QAAQ;AACvC"}
+{"version":3,"file":"use-safe-id.js","names":["useId().replace(UNSAFE_CHARS, '')","useId()"],"sources":["../../../src/utils/use-safe-id.ts"],"sourcesContent":["import { useId } from 'react';\n\nconst UNSAFE_CHARS = /[^a-zA-Z0-9_-]/g;\n\n/**\n * Generate a CSS-safe identifier from React's `useId()`.\n *\n * `useId()` returns values like `:r0:` which contain colons — invalid in CSS `<dashed-ident>` tokens (used by\n * `anchor-name` / `position-anchor`). This hook strips non-alphanumeric/underscore/hyphen characters and optionally\n * prepends a prefix.\n */\nexport function useSafeId(prefix?: string): string {\n  const raw = useId().replace(UNSAFE_CHARS, '');\n\n  return prefix ? `${prefix}-${raw}` : raw;\n}\n"],"mappings":";;;AAEA,MAAM,eAAe;;;;;;;;AASrB,SAAgB,UAAU,QAAyB;;CACrC,MAAA,KAAA,MAAM;CAANA,IAAAA;;EAAQ,KAAA,GAAA,QAAQ,cAAc,EAAE;EAAhCC,EAAAA,KAAAA;;;CAAZ,MAAM,MAAMD;CAEZ,OAAO,SAAS,GAAG,OAAO,GAAG,QAAQ;AACvC"}

package/docs/README.md

@@ -1,6 +1,6 @@
 # @videojs/react documentation
 
-Bundled markdown documentation for `@videojs/react` v10.0.0-rc.2.
+Bundled markdown documentation for `@videojs/react` v10.0.0-rc.3.
 
 Start at [`./llms.txt`](./llms.txt) — it's the structured index of every page in this directory.
 

package/docs/guides/accessibility.md

@@ -0,0 +1,93 @@
+# Accessibility
+
+How Video.js approaches accessibility, and what you should consider if you're deeply customizing your player
+
+Video.js is built with accessibility in mind so your player can reach the widest possible audience.
+
+Here are some of the accessibility aspects we consider. You should consider them too if you’re performing deeper customization.
+
+## Standards we target
+
+- [**WAI-ARIA 1.2**](https://www.w3.org/TR/wai-aria-1.2/) defines roles, states, and properties that [assistive technologies](https://www.w3.org/WAI/people-use-web/tools-techniques/) use to understand controls.
+- [**WCAG 2.2**](https://www.w3.org/TR/WCAG22/) provides success criteria for perceivable, operable, understandable, and robust web content.
+- [**CVAA**](https://www.fcc.gov/consumers/guides/21st-century-communications-and-video-accessibility-act-cvaa) is a U.S. federal law requiring closed captioning and accessible controls for video content.
+- [**ADA**](https://www.ada.gov/) is a U.S. civil rights law that prohibits disability discrimination. Courts increasingly apply it to websites, including video players.
+- [**European Accessibility Act**](https://eur-lex.europa.eu/eli/dir/2019/882/oj) applies across the EU from June 28, 2025, and covers services such as e-commerce and audiovisual media. [**EN 301 549**](https://www.etsi.org/human-factors-accessibility/en-301-549-v3-the-harmonized-european-standard-for-ict-accessibility) is the European standard for meeting it, and it incorporates WCAG.
+
+These standards and laws are listed for context, not as legal advice. Check which ones apply to your product.
+
+## ARIA roles and labels
+
+Components set ARIA roles and attributes automatically. For example, sliders render with `role="slider"` and value attributes, buttons update their `aria-label` based on player state, and decorative elements like time separators are hidden with `aria-hidden="true"`.
+
+Built-in labels are translated. See [Internationalize the player](./internationalization.md) to add or switch locales, and verify that labels are contextually correct for your content. Each component’s reference page documents the attributes it sets.
+
+Tooltips are visual only. They are not linked to their trigger with `aria-describedby`, so a custom trigger needs its own accessible name. Built-in media buttons already have one.
+
+## Keyboard interaction
+
+All interactive components support keyboard control. For example, buttons activate with Enter and Space, sliders respond to Arrow keys, Home, End, and Page Up/Page Down, and popovers close with Escape. Each component’s reference page lists its full keyboard support. We follow the patterns in the [WAI-ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/).
+
+Player-wide shortcuts, such as Space to play or M to mute, and tap gestures come from hotkey and gesture components. The skins ship a full set, and custom UI declares its own. See [Add keyboard shortcuts and gestures](./keyboard-shortcuts.md).
+
+## Focus management
+
+Interactive elements are focusable when enabled and leave the [tab order](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex) when disabled. Popover triggers link to their popups with `aria-controls` and `aria-expanded`. Menus and popovers close when focus moves away.
+
+Dialogs move focus inside when they open, keep Tab within the dialog, and make the content behind them inert. Closing a dialog returns focus to its trigger, or to the element that had focus before it opened.
+
+The player container is focusable and labeled: it takes `role="group"`, `tabindex="0"`, and an `aria-label` you can override. Keyboard users can tab to the player as a whole, and screen readers announce it as a named group.
+
+## Status announcements
+
+The player announces confirmed state changes through a visually hidden live region (`role="status"`), so screen reader users hear when playback starts or pauses, captions turn on or off, fullscreen, picture-in-picture, playback rate, or volume change, and where a seek lands.
+
+Announcements follow confirmed state from the player store rather than requested changes, so routine time updates never reach the live region. Rapid volume and seek changes are grouped into a single announcement, and the player stays quiet while one of its sliders has focus, since the slider already announces its own value. The skins include the [status announcer](../reference/components/status-announcer.md). A custom layout needs to add it. State the store tracks is covered once it’s there; a custom control that tracks its own state needs its own live region.
+
+## Captions and subtitles
+
+The [text tracks feature](../reference/api/feature-text-tracks.md) supports captions and subtitles. Closed captions in the U.S. are governed by the [FCC](https://www.fcc.gov/) under the [CVAA](https://www.fcc.gov/consumers/guides/21st-century-communications-and-video-accessibility-act-cvaa), which requires both captioning and viewer control over caption appearance (font, size, color, opacity, and edge style). Non-compliance carries legal risk.
+
+Video.js leaves caption rendering to the browser, and you style cues with the `::cue` pseudo-element. It doesn’t include a menu for caption appearance, so viewers rely on the caption preferences their browser and operating system provide. The [WebKit Caption Display Settings explainer](https://github.com/WebKit/explainers/tree/main/CaptionDisplaySettings) tracks how browsers are bringing these preferences into the web platform. See [Show captions and subtitles](./captions.md) to add tracks and a captions control.
+
+## Transcripts and audio description
+
+Captions don’t cover every viewer. [WCAG 2.2](https://www.w3.org/WAI/WCAG22/Understanding/audio-description-or-media-alternative-prerecorded) also expects audio description or a text alternative for prerecorded video. A transcript can live inside the [player](../reference/components/player.md) but outside its container, so it reads player state without going fullscreen with the video. When a stream includes a described audio track, an [audio track menu](../reference/components/audio-track-radio-group.md) lets viewers choose it.
+
+## Color contrast
+
+Skins respond to [`prefers-contrast: more`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-contrast) by increasing background opacity on overlays and controls, and to [`prefers-reduced-transparency: reduce`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-transparency) by raising baseline opacity so text stays readable over video.
+
+Video is harder than most UI for contrast because the background is always changing. A control that passes checks over a dark frame can disappear over a bright title card. Automated tools won’t catch this, so test your controls against light, dark, and mixed video content. Custom components should test against [WCAG 1.4.3 (contrast minimum)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum) and [1.4.11 (non-text contrast)](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast).
+
+## Touch targets
+
+Skin controls size from `--media-scale-unit`, which defaults to `16px`, so they don’t grow with the user’s font size preference. Set it to `1rem` to scale with the document root font size. See [Customize skins](./customize-skins.md#scale-from-the-document-font-size).
+
+Skin buttons set [`touch-action: manipulation`](https://developer.mozilla.org/en-US/docs/Web/CSS/touch-action) to remove tap delay on touch devices, and sliders set `touch-action: none` so dragging doesn’t scroll the page. Skins use [`pointer: fine` and `pointer: coarse`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/pointer) to adapt transitions for mouse and touch input.
+
+If you build custom controls, target at least 24x24 CSS pixels per [WCAG 2.5.8 (target size minimum)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum). Larger is better on touch-first surfaces.
+
+## Color scheme
+
+The audio skins switch their palette for light and dark mode with [`light-dark()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/light-dark), which follows the inherited [`color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/color-scheme), not the user’s preference directly. Set `color-scheme: light dark` on the page or the player to follow the user’s setting. The video skins keep dark controls in both schemes; only their border follows it. See [Customize skins](./customize-skins.md#set-the-color-scheme).
+
+## Reduced motion
+
+Skins respect [`prefers-reduced-motion`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) by simplifying or removing animations and transitions. Follow the same pattern in custom components.
+
+That covers the controls, not the video. Video.js doesn’t pause or hide autoplaying video for reduced-motion users; your page decides that.
+
+## Autoplay and moving video
+
+[WCAG 2.2.2](https://www.w3.org/WAI/WCAG22/Understanding/pause-stop-hide) requires a way to pause, stop, or hide motion that starts automatically and lasts more than five seconds. A muted, looping hero video counts. Give it a pause control, or keep it short.
+
+A purely decorative video should be hidden from assistive technology with `aria-hidden="true"` on its wrapper. If the video carries information, give it an accessible name and controls, and use a regular player. See [Add a background video](./background-video.md) and [Autoplay](./autoplay.md).
+
+## Test with assistive technology
+
+Automated tools catch markup issues but miss real usability problems. Test your player with a [screen reader](https://www.w3.org/WAI/people-use-web/tools-techniques/) ([VoiceOver](https://support.apple.com/guide/voiceover/welcome/mac) on macOS, [NVDA](https://www.nvaccess.org/about-nvda/) or [JAWS](https://www.freedomscientific.com/products/software/jaws/) on Windows) and keyboard-only navigation. Verify that every control is reachable, operable, and announces its purpose and state. The [WAI “Easy Checks”](https://www.w3.org/WAI/test-evaluate/preliminary/) are a good starting point.
+
+## Further reading
+
+The W3C WAI guides on [making audio and video media accessible](https://www.w3.org/WAI/media/av/) and [accessible media players](https://www.w3.org/WAI/media/av/player/) go deeper on everything covered here.

package/docs/guides/architecture.md

@@ -0,0 +1,118 @@
+# Architecture
+
+How Video.js players are structured — state, UI, media, and extensions
+
+Video.js v10 separates player responsibilities into parts that work independently or together, so you can use as much or as little of Video.js as you need.
+
+For the reasoning behind this design, see [Why Video.js?](./why-videojs.md).
+
+## State management
+
+State is handled by a preset player component, which creates a central state store that all components can access. When you wrap your player in `VideoPlayer`, the components automatically connect to the state.
+
+```tsx
+{/* All components inside automatically connect to state */}
+<VideoPlayer>
+  <VideoSkin>
+    <Video src="video.mp4" />
+  </VideoSkin>
+</VideoPlayer>
+```
+
+You can access state and actions from anywhere within `VideoPlayer` with the [`usePlayer` hook](../reference/api/use-player.md).
+
+- [Learn more about state and actions](./features.md)
+
+## User interface
+
+Use a prebuilt **skin** or build your own from the individual **UI components**.
+
+### Skins
+
+Skins are complete, pre-designed player UIs that package components and styles together. They give you a polished starting point, with a small set of CSS custom properties for common visual changes. They don’t try to cover every player with options.
+
+```tsx
+<VideoPlayer>
+  <VideoSkin>
+    <Video src="video.mp4" />
+  </VideoSkin>
+</VideoPlayer>
+```
+
+- [Learn more about skins](./skins.md)
+
+### UI components
+
+If you want more control than a packaged skin offers, build your own UI from our components. Add, remove, and rearrange them to build the player you need.
+
+```tsx
+<VideoPlayer>
+  <Container>
+    <Video src="video.mp4" />
+    <Controls.Root>
+      <Controls.Content>
+        <PlayButton />
+        {/* ... */}
+      </Controls.Content>
+    </Controls.Root>
+  </Container>
+</VideoPlayer>
+```
+
+Skin source is a practical foundation for custom UI because it provides the same styled components as the packaged version. See [Customize skins](./customize-skins.md#style-skin-source) to add it to your project.
+
+- [Learn more about UI components](./ui-components.md)
+- [Build your own component](./build-your-own-component.md)
+
+## Media
+
+Media components are the components that actually display your media. They’re essentially “players with no UI”. They handle the video/audio rendering and expose a consistent API.
+
+Media components can be format specific (HLS, DASH), service specific (YouTube, Vimeo, Mux), or use case specific (background video).
+
+```tsx
+<VideoPlayer>
+  <VideoSkin>
+    <HlsJsVideo src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" />
+  </VideoSkin>
+</VideoPlayer>
+```
+
+- [Learn more about media](./media-sources.md)
+
+## Extensions
+
+Extensions add behavior to a player without rendering UI or playing media themselves.
+
+```tsx
+<VideoPlayer>
+  <VideoSkin>
+    <MuxVideo source={{ playbackId: 'PLAYBACK_ID' }} />
+    <MuxData />
+    <GoogleCast />
+  </VideoSkin>
+</VideoPlayer>
+```
+
+An extension can provide behavior that a UI component controls: GoogleCast supplies the configurable Cast route, and [CastButton](../reference/components/cast-button.md) renders the control that starts and ends a session.
+
+## Presets
+
+**Presets** preconfigure the state, UI, and media for a specific use case. Extensions stay opt-in, so add them to a preset player when you need them.
+
+The default presets are `@videojs/react/video` and `@videojs/react/audio`, covering the baseline set of controls you’d expect from the HTML `<video>` and `<audio>` tags.
+
+Beyond the defaults, presets target more specific use cases. The `/background` preset combines a media element with autoplay, mute, and loop built in, a skin with no controls, and only the features needed to power it.
+
+You can use it from `@videojs/react/background`.
+
+- [Learn more about presets](./presets.md)
+
+## Related pages
+
+### Guides
+
+- [Installation](./installation.md): Install Video.js packages and build an accessible, customizable video player with composable controls
+- [Features](./features.md): The state and actions each feature adds to the player
+- [Skins](./skins.md): Packaged player designs that include both UI components and their styles.
+- [Presets](./presets.md): Pre-packaged player configurations that bundle state management, skins, and media elements for specific use cases.

package/docs/guides/autoplay.md

@@ -0,0 +1,173 @@
+# Autoplay
+
+Start playback automatically and handle browser autoplay restrictions.
+
+For the best chance of autoplay succeeding, start playback muted and enable inline playback. Autoplay is a request, not a guarantee: browsers can block it based on audio state, prior interaction with your site, browser settings, and platform policy.
+
+## Recommended approach
+
+Set autoplay, muted, and inline playback on the media element, and keep a manual play control available for when autoplay is blocked.
+
+**App.tsx**
+
+```tsx
+import { Container, PlayButton } from '@videojs/react';
+import { Video, VideoPlayer } from '@videojs/react/video';
+
+export default function BasicUsage() {
+  return (
+    <VideoPlayer>
+      <Container className="media-container">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline />
+        <PlayButton
+          className="media-play-button"
+          render={(props, state) => (
+            <button {...props}>{state.ended ? 'Replay' : state.paused ? 'Play' : 'Pause'}</button>
+          )}
+        />
+      </Container>
+    </VideoPlayer>
+  );
+}
+```
+
+**App.css**
+
+```css
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+
+.media-play-button {
+  position: absolute;
+  bottom: 10px;
+  left: 10px;
+  padding-block: 8px;
+  padding-inline: 20px;
+  color: black;
+  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);
+}
+```
+
+## How it works
+
+The `autoPlay`, `muted`, and `playsInline` props on [`Video`](../reference/api/create-player.md) and similar media components pass through to the underlying media element. When the media element supports them, they’re applied, and playback is requested as soon as the media has enough data.
+
+The [playback feature](../reference/api/feature-playback.md) reflects the result in player state. When autoplay succeeds, `paused` becomes `false` and `started` becomes `true`. When the browser blocks autoplay, the player stays `paused: true` with `started: false`, and the [Play button](../reference/components/play-button.md) renders its play state. There is no separate autoplay failure event: a blocked autoplay looks like media that never started.
+
+Calling `play()` from player state returns the native promise from the media element. When the browser blocks playback, that promise rejects with a `NotAllowedError`.
+
+## Availability and constraints
+
+- Autoplay can fail. Browsers decide per page load based on audio state, whether the user has interacted with your site before, browser settings, and platform policy.
+- Muted autoplay is broadly allowed. Unmuted autoplay is blocked on first visit in most browsers; do not rely on it.
+- Without inline playback, iPhone Safari opens the video in fullscreen when playback starts.
+- Low-power mode and data-saver settings can block even muted autoplay. This is why the recommended approach keeps a manual play control.
+- Programmatic volume control is unsupported on some platforms. The [volume feature](../reference/api/feature-volume.md) exposes this as `volumeAvailability: 'available' | 'unavailable' | 'unsupported'`; iOS Safari reports `'unsupported'`, and `'unavailable'` means the feature hasn’t attached to a media element yet.
+- This guide applies to media components that render a video element (Video, HlsJsVideo, DashVideo, MuxVideo, and the like). Embed components (YouTube, Vimeo, TikTok, Twitch) forward autoplay to the third-party player, which applies its own autoplay rules; muted and inline behavior varies by provider.
+
+## Common variations
+
+### Background video
+
+Background video autoplays, loops, stays muted, and omits interactive controls. Use `HlsBackgroundVideo` instead of configuring these behaviors yourself: it applies them by default and streams an HLS source, picking one rendition that fits the screen for the whole session.
+
+Install the SPF adapter with the React façade:
+
+```bash
+pnpm add @videojs/react @videojs/spf
+```
+
+```tsx
+import { HlsBackgroundVideo } from '@videojs/react/media/hls-background-video';
+
+export default function Hero() {
+  return <HlsBackgroundVideo src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" />;
+}
+```
+
+If you have a progressive MP4 or WebM file instead of an HLS stream, `BackgroundVideo` is the same component without the streaming engine. See [BackgroundVideo](../reference/components/background-video.md) for opt-out props and sizing.
+
+### Autoplay with sound
+
+Do not rely on unmuted autoplay for a user’s first visit. Start playback from an explicit user action instead.
+
+Call `play()` from the player store returned by [`usePlayer`](../reference/api/use-player.md):
+
+```tsx
+import { Container } from '@videojs/react';
+import { usePlayer, Video, VideoPlayer } from '@videojs/react/video';
+
+function StartPlaybackButton() {
+  const store = usePlayer();
+
+  return (
+    <button type="button" onClick={() => store.play()}>
+      Play video
+    </button>
+  );
+}
+
+export default function App() {
+  return (
+    <VideoPlayer>
+      <Container>
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" playsInline />
+        <StartPlaybackButton />
+      </Container>
+    </VideoPlayer>
+  );
+}
+```
+
+Because playback starts from a user gesture, the browser allows it unmuted.
+
+## Troubleshooting
+
+### Playback does not start
+
+Confirm that:
+
+- The media is muted.
+- Inline playback is enabled.
+- The source loads (check the network panel).
+- A manual play control is available as a fallback.
+
+If autoplay is blocked, the player stays paused and the Play button remains in its play state; there is no error state to handle.
+
+### The video opens fullscreen on iPhone
+
+Enable inline playback with the `playsInline` prop on the media component.
+
+### The video starts without sound
+
+Expected with muted autoplay. Let the user unmute through a [Mute button](../reference/components/mute-button.md) or [Volume slider](../reference/components/volume-slider.md) rather than unmuting programmatically; programmatic volume changes are unsupported on some platforms.
+
+## Related pages
+
+### Components
+
+- [PlayButton](../reference/components/play-button.md): Accessible play/pause button with keyboard support and customizable rendering
+- [MuteButton](../reference/components/mute-button.md): Accessible mute/unmute button with keyboard support and volume state reflection
+- [BackgroundVideo](../reference/components/background-video.md): Decorative background video element with automatic muting and looping
+- [Controls](../reference/components/controls.md): Container component for composing and auto-hiding video player controls on user interaction
+
+### API
+
+- [Playback](../reference/api/feature-playback.md): Play/pause state and actions for the player store
+- [Volume](../reference/api/feature-volume.md): Volume level and mute state for the player store
+- [usePlayer](../reference/api/use-player.md): Hook to access the player store from within a Player
+
+### Guides
+
+- [Features](./features.md): The state and actions each feature adds to the player
+- [Browser support](./browser-support.md): Browsers and rendering environments supported by Video.js 10, and what the stylesheets need from them