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

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

@@ -44,7 +44,7 @@ function renderElement(element, componentProps, params) {
 	const { state, ref, props, stateAttrMap } = params;
 	const className = resolveClassName(classNameProp, state);
 	const style = resolveStyle(styleProp, state);
-	const mergedProps = mergeProps(getStateDataAttrs(state, stateAttrMap), ...Array.isArray(props) ? props : props ? [props] : []);
+	const mergedProps = mergeProps(stateAttrMap ? getStateDataAttrs(state, stateAttrMap) : {}, ...Array.isArray(props) ? props : props ? [props] : []);
 	if (className !== void 0) mergedProps.className = mergedProps.className ? `${mergedProps.className} ${className}` : className;
 	if (style !== void 0) mergedProps.style = mergedProps.style ? {
 		...mergedProps.style,

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

@@ -1 +1 @@
-{"version":3,"file":"use-render.js","names":[],"sources":["../../../src/utils/use-render.tsx"],"sourcesContent":["'use client';\n\nimport { getStateDataAttrs, type StateAttrMap } from '@videojs/core/dom';\nimport { isFunction } from '@videojs/utils/predicate';\nimport type { CSSProperties, ReactElement, Ref } from 'react';\nimport { cloneElement, createElement, isValidElement } from 'react';\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 resolveClassName<State>(\n  className: string | ((state: State) => string | undefined) | undefined,\n  state: State\n): string | undefined {\n  return isFunction(className) ? className(state) : className;\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  return elementAny.ref ?? elementAny.props?.ref;\n}\n\n/**\n * Render a UI component element.\n *\n * Handles:\n * - Default tag rendering\n * - Render prop (element or function)\n * - Props merging (event handlers chained, className concatenated, style merged)\n * - Ref composition\n * - className/style as functions of state\n *\n * @public\n * @example\n * ```tsx\n * return renderElement('button', componentProps, {\n *   state,\n *   ref: [forwardedRef, buttonRef],\n *   props: [{ type: 'button' }, elementProps, getButtonProps],\n * });\n * ```\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 from state\n  const stateDataAttrs = 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 = composeRefs(ref, mergedProps.ref);\n    return render({ ...mergedProps, ref: mergedRef } as HTMLProps, state);\n  }\n\n  if (isValidElement(render)) {\n    const elementRef = getElementRef(render);\n\n    const mergedRef = composeRefs(ref, mergedProps.ref, elementRef);\n\n    const elementProps = mergeProps(mergedProps, render.props as Record<string, unknown>);\n    elementProps.ref = mergedRef;\n\n    return cloneElement(render, elementProps);\n  }\n\n  // Default tag\n  const mergedRef = composeRefs(ref, mergedProps.ref);\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":";;;;;;;;AAWA,SAAgB,aAAa,OAA8C;AACzE,QAAO,WAAW,MAAM,IAAI,eAAe,MAAM;;AAkBnD,SAAS,iBACP,WACA,OACoB;AACpB,QAAO,WAAW,UAAU,GAAG,UAAU,MAAM,GAAG;;AAGpD,SAAS,aACP,OACA,OAC2B;AAC3B,QAAO,WAAW,MAAM,GAAG,MAAM,MAAM,GAAG;;AAG5C,SAAS,cAAc,SAAiD;CAGtE,MAAM,aAAa;AACnB,QAAO,WAAW,OAAO,WAAW,OAAO;;;;;;;;;;;;;;;;;;;;;;AAuB7C,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,MAAM;CACxD,MAAM,QAAQ,aAAa,WAAW,MAAM;CAO5C,MAAM,cAAc,WAJG,kBAAkB,OAAO,aAAa,EAId,GAD5B,MAAM,QAAQ,MAAM,GAAG,QAAQ,QAAQ,CAAC,MAAM,GAAG,EAAE,CACsB;AAE5F,KAAI,cAAc,KAAA,EAEhB,aAAY,YAAY,YAAY,YAAY,GAAG,YAAY,UAAU,GAAG,cAAc;AAG5F,KAAI,UAAU,KAAA,EACZ,aAAY,QAAQ,YAAY,QAAQ;EAAE,GAAI,YAAY;EAAyB,GAAG;EAAO,GAAG;AAGlG,KAAI,WAAW,OAAO,EAAE;EAEtB,MAAM,YAAY,YAAY,KAAK,YAAY,IAAI;AACnD,SAAO,OAAO;GAAE,GAAG;GAAa,KAAK;GAAW,EAAe,MAAM;;AAGvE,KAAI,eAAe,OAAO,EAAE;EAC1B,MAAM,aAAa,cAAc,OAAO;EAExC,MAAM,YAAY,YAAY,KAAK,YAAY,KAAK,WAAW;EAE/D,MAAM,eAAe,WAAW,aAAa,OAAO,MAAiC;AACrF,eAAa,MAAM;AAEnB,SAAO,aAAa,QAAQ,aAAa;;AAK3C,aAAY,MADM,YAAY,KAAK,YAAY,IAAI;AAGnD,QAAO,cAAc,SAAS,YAAY"}
+{"version":3,"file":"use-render.js","names":[],"sources":["../../../src/utils/use-render.tsx"],"sourcesContent":["'use client';\n\nimport { getStateDataAttrs, type StateAttrMap } from '@videojs/core/dom';\nimport { isFunction } from '@videojs/utils/predicate';\nimport type { CSSProperties, ReactElement, Ref } from 'react';\nimport { cloneElement, createElement, isValidElement } from 'react';\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 resolveClassName<State>(\n  className: string | ((state: State) => string | undefined) | undefined,\n  state: State\n): string | undefined {\n  return isFunction(className) ? className(state) : className;\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  return elementAny.ref ?? elementAny.props?.ref;\n}\n\n/**\n * Render a UI component element.\n *\n * Handles:\n * - Default tag rendering\n * - Render prop (element or function)\n * - Props merging (event handlers chained, className concatenated, style merged)\n * - Ref composition\n * - className/style as functions of state\n *\n * @public\n * @example\n * ```tsx\n * return renderElement('button', componentProps, {\n *   state,\n *   ref: [forwardedRef, buttonRef],\n *   props: [{ type: 'button' }, elementProps, getButtonProps],\n * });\n * ```\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 = composeRefs(ref, mergedProps.ref);\n    return render({ ...mergedProps, ref: mergedRef } as HTMLProps, state);\n  }\n\n  if (isValidElement(render)) {\n    const elementRef = getElementRef(render);\n\n    const mergedRef = composeRefs(ref, mergedProps.ref, elementRef);\n\n    const elementProps = mergeProps(mergedProps, render.props as Record<string, unknown>);\n    elementProps.ref = mergedRef;\n\n    return cloneElement(render, elementProps);\n  }\n\n  // Default tag\n  const mergedRef = composeRefs(ref, mergedProps.ref);\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":";;;;;;;;AAWA,SAAgB,aAAa,OAA8C;CACzE,OAAO,WAAW,KAAK,KAAK,eAAe,KAAK;AAClD;AAiBA,SAAS,iBACP,WACA,OACoB;CACpB,OAAO,WAAW,SAAS,IAAI,UAAU,KAAK,IAAI;AACpD;AAEA,SAAS,aACP,OACA,OAC2B;CAC3B,OAAO,WAAW,KAAK,IAAI,MAAM,KAAK,IAAI;AAC5C;AAEA,SAAS,cAAc,SAAiD;CAGtE,MAAM,aAAa;CACnB,OAAO,WAAW,OAAO,WAAW,OAAO;AAC7C;;;;;;;;;;;;;;;;;;;;;AAsBA,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;CAQ3C,MAAM,cAAc,WAJG,eAAe,kBAAkB,OAAO,YAAY,IAAI,CAAC,GAIjC,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,YAAY,KAAK,YAAY,GAAG;EAClD,OAAO,OAAO;GAAE,GAAG;GAAa,KAAK;EAAU,GAAgB,KAAK;CACtE;CAEA,IAAI,eAAe,MAAM,GAAG;EAC1B,MAAM,aAAa,cAAc,MAAM;EAEvC,MAAM,YAAY,YAAY,KAAK,YAAY,KAAK,UAAU;EAE9D,MAAM,eAAe,WAAW,aAAa,OAAO,KAAgC;EACpF,aAAa,MAAM;EAEnB,OAAO,aAAa,QAAQ,YAAY;CAC1C;CAIA,YAAY,MADM,YAAY,KAAK,YAAY,GACrB;CAE1B,OAAO,cAAc,SAAS,WAAW;AAC3C"}

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":["'use client';\n\nimport { 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\n * in CSS `<dashed-ident>` tokens (used by `anchor-name` / `position-anchor`).\n * This hook strips non-alphanumeric/underscore/hyphen characters and\n * optionally prepends a prefix.\n */\nexport function useSafeId(prefix?: string): string {\n  const raw = useId().replace(UNSAFE_CHARS, '');\n  return prefix ? `${prefix}-${raw}` : raw;\n}\n"],"mappings":";;;AAIA,MAAM,eAAe;;;;;;;;;AAUrB,SAAgB,UAAU,QAAyB;CACjD,MAAM,MAAM,OAAO,CAAC,QAAQ,cAAc,GAAG;AAC7C,QAAO,SAAS,GAAG,OAAO,GAAG,QAAQ"}
+{"version":3,"file":"use-safe-id.js","names":[],"sources":["../../../src/utils/use-safe-id.ts"],"sourcesContent":["'use client';\n\nimport { 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\n * in CSS `<dashed-ident>` tokens (used by `anchor-name` / `position-anchor`).\n * This hook strips non-alphanumeric/underscore/hyphen characters and\n * optionally prepends a prefix.\n */\nexport function useSafeId(prefix?: string): string {\n  const raw = useId().replace(UNSAFE_CHARS, '');\n  return prefix ? `${prefix}-${raw}` : raw;\n}\n"],"mappings":";;;AAIA,MAAM,eAAe;;;;;;;;;AAUrB,SAAgB,UAAU,QAAyB;CACjD,MAAM,MAAM,MAAM,CAAC,CAAC,QAAQ,cAAc,EAAE;CAC5C,OAAO,SAAS,GAAG,OAAO,GAAG,QAAQ;AACvC"}

package/dist/dev/utils/use-sync-props.js

@@ -1,11 +1,20 @@
+import { useRef } from "react";
 import { isUndefined } from "@videojs/utils/predicate";
 //#region src/utils/use-sync-props.ts
 function useSyncProps(target, props, defaults) {
 	const rest = {};
-	for (const key in props) if (key in defaults) {
-		const value = isUndefined(props[key]) ? defaults[key] : props[key];
+	const synced = /* @__PURE__ */ new Set();
+	const prevSyncedRef = useRef(null);
+	const sync = (key, value) => {
 		if (target[key] !== value) target[key] = value;
+	};
+	for (const key of prevSyncedRef.current ?? []) if (isUndefined(props[key])) sync(key, defaults[key]);
+	for (const key in props) if (key in defaults) {
+		if (isUndefined(props[key])) continue;
+		synced.add(key);
+		sync(key, props[key]);
 	} else rest[key] = props[key];
+	prevSyncedRef.current = synced;
 	return rest;
 }
 //#endregion

package/dist/dev/utils/use-sync-props.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-sync-props.js","names":[],"sources":["../../../src/utils/use-sync-props.ts"],"sourcesContent":["import { isUndefined } from '@videojs/utils/predicate';\n\nexport function useSyncProps<Props extends object, Rest extends Record<string, unknown>>(\n  target: Props,\n  props: Partial<Props> & Rest,\n  defaults: Props\n): Omit<Rest, keyof Props> {\n  const rest: Record<string, unknown> = {};\n\n  for (const key in props) {\n    if (key in defaults) {\n      const value = isUndefined(props[key]) ? (defaults as Record<string, unknown>)[key] : props[key];\n      if (target[key as keyof typeof target] !== value) target[key as keyof typeof target] = value as any;\n    } else {\n      rest[key] = props[key];\n    }\n  }\n\n  return rest as Omit<Rest, keyof Props>;\n}\n"],"mappings":";;AAEA,SAAgB,aACd,QACA,OACA,UACyB;CACzB,MAAM,OAAgC,EAAE;AAExC,MAAK,MAAM,OAAO,MAChB,KAAI,OAAO,UAAU;EACnB,MAAM,QAAQ,YAAY,MAAM,KAAK,GAAI,SAAqC,OAAO,MAAM;AAC3F,MAAI,OAAO,SAAgC,MAAO,QAAO,OAA8B;OAEvF,MAAK,OAAO,MAAM;AAItB,QAAO"}
+{"version":3,"file":"use-sync-props.js","names":[],"sources":["../../../src/utils/use-sync-props.ts"],"sourcesContent":["import { isUndefined } from '@videojs/utils/predicate';\nimport { useRef } from 'react';\n\nexport function useSyncProps<Props extends object, Rest extends Record<string, unknown>>(\n  target: Props,\n  props: Partial<Props> & Rest,\n  defaults: Props\n): Omit<Rest, keyof Props> {\n  const rest: Record<string, unknown> = {};\n  const synced = new Set<string>();\n  const prevSyncedRef = useRef<Set<string> | null>(null);\n\n  const sync = (key: string, value: unknown) => {\n    if (target[key as keyof Props] !== value) target[key as keyof Props] = value as Props[keyof Props];\n  };\n\n  // Reset props the consumer stopped passing (or passed as `undefined`) back to\n  // their defaults before applying the current ones, so a reset can never wipe a\n  // value another prop derives in the same render (e.g. `source` deriving `src`).\n  // Mirrors react-dom removing absent attributes.\n  for (const key of prevSyncedRef.current ?? []) {\n    if (isUndefined((props as Record<string, unknown>)[key])) sync(key, (defaults as Record<string, unknown>)[key]);\n  }\n\n  for (const key in props) {\n    if (key in defaults) {\n      if (isUndefined(props[key])) continue;\n      synced.add(key);\n      sync(key, props[key]);\n    } else {\n      rest[key] = props[key];\n    }\n  }\n\n  prevSyncedRef.current = synced;\n\n  return rest as Omit<Rest, keyof Props>;\n}\n"],"mappings":";;;AAGA,SAAgB,aACd,QACA,OACA,UACyB;CACzB,MAAM,OAAgC,CAAC;CACvC,MAAM,yBAAS,IAAI,IAAY;CAC/B,MAAM,gBAAgB,OAA2B,IAAI;CAErD,MAAM,QAAQ,KAAa,UAAmB;EAC5C,IAAI,OAAO,SAAwB,OAAO,OAAO,OAAsB;CACzE;CAMA,KAAK,MAAM,OAAO,cAAc,WAAW,CAAC,GAC1C,IAAI,YAAa,MAAkC,IAAI,GAAG,KAAK,KAAM,SAAqC,IAAI;CAGhH,KAAK,MAAM,OAAO,OAChB,IAAI,OAAO,UAAU;EACnB,IAAI,YAAY,MAAM,IAAI,GAAG;EAC7B,OAAO,IAAI,GAAG;EACd,KAAK,KAAK,MAAM,IAAI;CACtB,OACE,KAAK,OAAO,MAAM;CAItB,cAAc,UAAU;CAExB,OAAO;AACT"}

package/docs/README.md

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

package/docs/concepts/accessibility.md

@@ -27,6 +27,14 @@ All interactive components support keyboard control. For example, buttons activa
 
 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`.
 
+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. State the store tracks is covered for you; a custom control that tracks its own state needs its own live region.
+
 ## Captions and subtitles
 
 The [text tracks feature](../reference/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. The [WebKit Caption Display Settings explainer](https://github.com/WebKit/explainers/tree/main/CaptionDisplaySettings) tracks how browsers are bringing these customization preferences into the web platform natively.

package/docs/concepts/browser-support.md

@@ -2,7 +2,7 @@
 
 Which browsers Video.js 10 supports and how it handles newer platform features
 
-Video.js 10 currently targets **evergreen browsers** : the latest two stable versions of Chrome, Firefox, Safari, and Edge.
+Video.js 10 currently targets **evergreen browsers**: the latest two stable versions of Chrome, Firefox, Safari, and Edge.
 
 Note
 

package/docs/concepts/cast.md

@@ -0,0 +1,131 @@
+# Google Cast
+
+Cast playback to Chromecast devices with the Google Cast component, and configure the receiver and load request
+
+Add Google Cast to any Video.js streaming media element (HLS and DASH) by placing the Google Cast component next to it. Pair it with a [CastButton](../reference/cast-button.md) and users can move playback to a Chromecast device while the browser stays in control:
+
+App.tsx
+
+```
+import { CastButton, createPlayer } from '@videojs/react';
+import { GoogleCast } from '@videojs/react/media/google-cast';
+import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
+import { videoFeatures } from '@videojs/react/video';
+
+const Player = createPlayer({ features: videoFeatures });
+
+export default function App() {
+  return (
+    <Player.Provider>
+      <Player.Container>
+        <HlsJsVideo
+          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"
+          autoPlay
+          muted
+          playsInline
+          loop
+        />
+        <GoogleCast />
+        <CastButton />
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+
+The component registers Google Cast with whichever media the player is using, so it works with any of the streaming media elements. The pre-built [skins](./skins.md) include a Cast button already. It appears when a Chromecast device is on the network and stays hidden otherwise.
+
+Caution
+
+Casting needs this component. Without it, [CastButton](../reference/cast-button.md) drives the browser’s native Remote Playback API rather than a Cast session, so receivers and load requests don’t apply.
+
+Note
+
+Cast only works in Chromium-based browsers (Chrome, Edge, and others built on Blink). On other browsers, `remotePlaybackAvailability` is `'unsupported'`.
+
+## How Cast works
+
+Cast uses a **sender / receiver** model:
+
+*   **Sender**: the browser tab. It sends the receiver a load request with the source URL and metadata, then issues playback commands (play, pause, seek, volume).
+*   **Receiver**: the Chromecast device running a receiver application, either Google’s default media receiver or a custom one you configure.
+
+### Session lifecycle
+
+A Cast session moves through three states, exposed by the [Remote Playback](../reference/feature-remote-playback.md) feature:
+
+State
+
+Meaning
+
+`'disconnected'`
+
+No active session
+
+`'connecting'`
+
+Device picked; session starting
+
+`'connected'`
+
+Session active; receiver has the media
+
+While `connected`, the media element’s `play`, `pause`, `currentTime`, `volume`, `muted`, and `playbackRate` all forward to the Cast receiver. Local playback is suspended.
+
+### The lazy-loaded SDK
+
+Video.js injects the Cast SDK (`cast_sender.js`) as a `<script>` tag the first time a Google Cast component is added in a Chromium browser. Browsers that can’t cast — and players without the component — never load the SDK.
+
+Set `disableRemotePlayback` on the media element to opt out of remote playback entirely:
+
+tsx
+
+```
+<HlsJsVideo disableRemotePlayback />
+```
+
+## Configure Cast
+
+By default, the receiver loads the same source the browser plays through Google’s [Default Media Receiver](https://developers.google.com/cast/docs/web_sender/integrate#default_media_web_receiver). Point Cast at your own receiver app, send a different source, attach custom data to the load request, or override the stream type through the component’s options:
+
+tsx
+
+```
+<HlsJsVideo src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" />
+<GoogleCast
+  receiver="YOUR_APP_ID"
+  src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"
+  contentType="application/x-mpegURL"
+/>
+```
+
+The [GoogleCast reference](../reference/google-cast.md) documents every option. HLS sources need no extra receiver setup: Video.js detects the segment format and configures the load request, and the Default Media Receiver plays HLS natively.
+
+## Read Cast state
+
+Cast session state lives in the [Remote Playback](../reference/feature-remote-playback.md) feature slice. Subscribe with `selectRemotePlayback`:
+
+tsx
+
+```
+import { selectRemotePlayback, usePlayer } from '@videojs/react';
+
+function CastStatus() {
+  const remotePlayback = usePlayer(selectRemotePlayback);
+  if (!remotePlayback) return null;
+
+  return <span>{remotePlayback.remotePlaybackState}</span>;
+}
+```
+
+## Browser availability
+
+The Remote Playback feature reports availability as `'available'` (a device is on the network), `'unavailable'` (no device found), or `'unsupported'` (the browser can’t cast). A [CastButton](../reference/cast-button.md) handles the presentation for you: it hides itself when Cast is unsupported, and shows a disabled state when Cast is supported but no device is reachable. See its reference for the data attributes and styling hooks.
+
+## See also
+
+[GoogleCast reference](../reference/google-cast.md)
+
+[CastButton component reference](../reference/cast-button.md)
+
+[Remote Playback feature reference](../reference/feature-remote-playback.md)

package/docs/concepts/features.md

@@ -21,7 +21,7 @@ import { videoFeatures } from '@videojs/react/video';
 const Player = createPlayer({ features: videoFeatures });
 ```
 
-Feature bundles are usually paired with specific skins and media elements in a **preset** . To learn more about this, and the available presets, you’ll want to check out the presets guide.
+Feature bundles are usually paired with specific skins and media elements in a **preset**. To learn more about this, and the available presets, you’ll want to check out the presets guide.
 
 [Learn more about presets](./presets.md)
 
@@ -106,13 +106,21 @@ Could work, not ready yet
 
 Platform can never do this
 
-Components that depend on availability (like [`PiPButton`](../reference/pip-button.md) and [`FullscreenButton`](../reference/fullscreen-button.md)) expose a `data-availability` attribute, so you can hide unsupported controls with CSS:
+Components that depend on availability (like [`PiPButton`](../reference/pip-button.md) and [`FullscreenButton`](../reference/fullscreen-button.md)) handle the three states for you:
+
+*   **`unsupported`** — the HTML custom element receives the native `hidden` attribute (and `data-hidden`); React buttons return `null`. No CSS needed.
+*   **`unavailable`** — the presentation controls stay hidden while capability detection is unresolved. Cast remains visible but disabled when its API is supported and no device is reachable.
+*   **`disabled` prop** — an available button stays visible and focusable with `aria-disabled="true"` plus `data-disabled` for styling.
+*   **`available`** — fully interactive.
+
+Use `data-disabled` to style the non-interactive state:
 
 css
 
 ```
-.pip-button[data-availability="unsupported"] {
-  display: none;
+.pip-button[data-disabled] {
+  opacity: 0.5;
+  cursor: not-allowed;
 }
 ```
 
@@ -124,7 +132,7 @@ PiPControl.tsx
 function PiPControl() {
   const availability = usePlayer((s) => s.pipAvailability);
 
-  if (availability === 'unsupported') return null;
+  if (availability !== 'available') return null;
 
   return <PiPButton />;
 }

package/docs/concepts/i18n.md

@@ -0,0 +1,327 @@
+# Internationalization
+
+How Video.js chooses a language and translates built-in player text
+
+Video.js displays its controls in English by default. Use internationalization when the player should match another language used by your site or application.
+
+Set the page language and add an internationalization provider around the player. Video.js then translates built-in labels, tooltips, status messages, and error text.
+
+## Choose the player language
+
+The provider reads the nearest `lang` attribute unless you give it a language directly. Setting `<html lang="es">` lets the page and player share Spanish.
+
+Mount `I18nProvider` inside the player `Provider`. Choose any shipped language to lazy-load its translations and update the player’s control labels.
+
+LanguageEnglishArabicAzerbaijaniBosnianBulgarianBanglaCatalanCzechWelshDanishGermanGreekSpanishEstonianBasquePersianFinnishFrenchScottish GaelicGalicianHebrewHindiCroatianHungarianItalianJapaneseKoreanLatvianMarathiNorwegian BokmålDutchNorwegian NynorskNepaliOccitanPolishBrazilian PortugueseEuropean PortugueseRomanianRussianSlovakSlovenianSerbianSwedishTeluguThaiTurkishUkrainianVietnameseChinese (China)Chinese (Taiwan)
+
+0:00
+
+0:00
+
+0:00
+
+0:00
+
+App.tsx
+
+App.css
+
+```
+import { createPlayer } from '@videojs/react';
+import { I18nProvider, LOCALES } from '@videojs/react/i18n';
+import { Video, VideoSkin, videoFeatures } from '@videojs/react/video';
+import { useState } from 'react';
+
+import '@videojs/react/video/skin.css';
+import './Language.css';
+
+const Player = createPlayer({ features: videoFeatures });
+const locales = ['en', ...LOCALES] as const;
+type Locale = (typeof locales)[number];
+const languageNames = new Intl.DisplayNames(['en'], { type: 'language' });
+
+export default function Language() {
+  const [locale, setLocale] = useState<Locale>('en');
+
+  return (
+    <div className="react-i18n-language">
+      <label>
+        Language
+        <select value={locale} onChange={(event) => setLocale(event.currentTarget.value as Locale)}>
+          {locales.map((value) => (
+            <option key={value} value={value}>
+              {languageNames.of(value) ?? value}
+            </option>
+          ))}
+        </select>
+      </label>
+      <Player.Provider>
+        <I18nProvider locale={locale}>
+          <VideoSkin className="react-i18n-language__player">
+            <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline />
+          </VideoSkin>
+        </I18nProvider>
+      </Player.Provider>
+    </div>
+  );
+}
+```
+```
+.react-i18n-language {
+  display: grid;
+  gap: 16px;
+  padding: 16px;
+}
+
+.react-i18n-language label {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+}
+
+.react-i18n-language select {
+  padding: 4px 8px;
+}
+
+.react-i18n-language__player {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+```
+
+Pass `locale="es"` to `I18nProvider` when one player needs a different language from the rest of the page.
+
+Changing the active language updates mounted controls without remounting the player. See [Switch locale dynamically](../how-to/i18n-switch-locale.md) for complete examples.
+
+## How translated text works
+
+Each built-in piece of text has two parts:
+
+*   A stable key that identifies its meaning, such as `buttons.play`
+*   English fallback text, such as `Play`
+
+Translation packs replace the fallback for a language:
+
+ts
+
+```
+{
+  buttons: {
+    play: 'Reproducir',
+  },
+}
+```
+
+You can count on this key staying the same, even if we change the English wording. For example, if we changed “Play” to “Banana” in the UI, the key would still be `buttons.play`.
+
+You don’t have to include every key in a translation. Missing keys display their readable English fallback.
+
+Some translations include values supplied by the component. For example, `seek.forward` uses the English fallback `Seek forward {seconds} seconds`. When you write a translation, make sure to include `{seconds}` where the number should appear.
+
+See [Translation keys](../reference/translation-phrases.md) for the complete list of keys, English defaults, and the controls that use them.
+
+## Where translations come from
+
+Video.js looks for translated text in these places:
+
+1.  Overrides supplied to the current player
+2.  Registered custom translations
+3.  A built-in locale pack
+4.  The component’s English fallback
+
+Choose a source, then hover the play button to see its resolved label.
+
+Player override
+
+Registered
+
+Built-in
+
+Fallback
+
+0:00
+
+0:00
+
+0:00
+
+0:00
+
+```
+import { createPlayer } from '@videojs/react';
+import { I18nProvider } from '@videojs/react/i18n';
+import { Video, VideoSkin, videoFeatures } from '@videojs/react/video';
+
+import '@videojs/react/video/skin.css';
+import './Sources.css';
+
+const Player = createPlayer({ features: videoFeatures });
+
+export default function Override() {
+  return (
+    <Player.Provider>
+      <I18nProvider locale="en" translations={{ buttons: { play: 'Player override' } }}>
+        <div className="react-i18n-source">
+          <VideoSkin className="react-i18n-source__player">
+            <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline preload="none" />
+          </VideoSkin>
+        </div>
+      </I18nProvider>
+    </Player.Provider>
+  );
+}
+```
+0:00
+
+0:00
+
+0:00
+
+0:00
+
+```
+import { createPlayer } from '@videojs/react';
+import { I18nProvider, registerI18n } from '@videojs/react/i18n';
+import { Video, VideoSkin, videoFeatures } from '@videojs/react/video';
+
+import '@videojs/react/video/skin.css';
+import './Sources.css';
+
+registerI18n('en-x-demo', {
+  buttons: {
+    play: 'Registered custom translation',
+  },
+});
+
+const Player = createPlayer({ features: videoFeatures });
+
+export default function Registered() {
+  return (
+    <Player.Provider>
+      <I18nProvider locale="en-x-demo">
+        <div className="react-i18n-source">
+          <VideoSkin className="react-i18n-source__player">
+            <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline preload="none" />
+          </VideoSkin>
+        </div>
+      </I18nProvider>
+    </Player.Provider>
+  );
+}
+```
+0:00
+
+0:00
+
+0:00
+
+0:00
+
+```
+import { createPlayer } from '@videojs/react';
+import { I18nProvider } from '@videojs/react/i18n';
+import { Video, VideoSkin, videoFeatures } from '@videojs/react/video';
+
+import '@videojs/react/video/skin.css';
+import './Sources.css';
+
+const Player = createPlayer({ features: videoFeatures });
+
+export default function BuiltIn() {
+  return (
+    <Player.Provider>
+      <I18nProvider locale="es">
+        <div className="react-i18n-source">
+          <VideoSkin className="react-i18n-source__player">
+            <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline preload="none" />
+          </VideoSkin>
+        </div>
+      </I18nProvider>
+    </Player.Provider>
+  );
+}
+```
+0:00
+
+0:00
+
+0:00
+
+0:00
+
+```
+import { createPlayer } from '@videojs/react';
+import { I18nProvider } from '@videojs/react/i18n';
+import { Video, VideoSkin, videoFeatures } from '@videojs/react/video';
+
+import '@videojs/react/video/skin.css';
+import './Sources.css';
+
+const Player = createPlayer({ features: videoFeatures });
+
+export default function Fallback() {
+  return (
+    <Player.Provider>
+      <I18nProvider locale="en">
+        <div className="react-i18n-source">
+          <VideoSkin className="react-i18n-source__player">
+            <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline preload="none" />
+          </VideoSkin>
+        </div>
+      </I18nProvider>
+    </Player.Provider>
+  );
+}
+```
+
+Built-in packs load when the provider first encounters their language. You do not need to import Spanish, French, or another shipped language for normal client-rendered players.
+
+The `translations` prop on `I18nProvider` overrides text for that provider subtree:
+
+tsx
+
+```
+<I18nProvider locale="es" translations={{ buttons: { play: 'Comenzar' } }}>
+  <VideoSkin>...</VideoSkin>
+</I18nProvider>
+```
+
+Use [`registerI18n`](../reference/register-i18n.md) when you have a custom locale or want an override to apply across players:
+
+ts
+
+```
+registerI18n('es', {
+  buttons: {
+    play: 'Comenzar',
+  },
+});
+```
+
+If registered and built-in translations still leave text missing, Video.js automatically tries Chrome’s [Browser Translation API](https://developer.mozilla.org/en-US/docs/Web/API/Translator). You do not need to call the API. This fallback only runs when Chrome exposes the API and the required on-device model is already installed. Video.js does not download the model. Use reviewed locale packs for production-critical text.
+
+## Locale fallback
+
+Language tags follow the [BCP 47](https://www.rfc-editor.org/rfc/rfc5646) parent chain. A player using Mexican Spanish checks `es-MX`, then `es`, before falling back to English:
+
+txt
+
+```
+es-MX → es → en
+```
+
+This lets a regional pack override only the text that differs from its parent language.
+
+## Avoid a flash of English
+
+Built-in packs normally load after the provider mounts. A player can briefly show English during server rendering or the first switch to a language.
+
+Preload or register translations before rendering when the first translated paint matters:
+
+[Render translated text during SSR](../how-to/i18n-ssr.md)
+
+[Preload languages before switching](../how-to/i18n-switch-locale.md)
+
+Tip
+
+Use [Override translations](../how-to/i18n-override-translations.md) to customize built-in text or provide your own visible component text.