@videojs/html 10.0.0-beta.8 → 10.0.0-rc.1

package/dist/dev/ui/volume-slider/volume-slider-element.js

@@ -1,22 +1,37 @@
+import { i18nContext } from "../../i18n/context.js";
+import { I18nController } from "../../i18n/controller.js";
 import { playerContext } from "../../player/context.js";
-import { MediaElement } from "../media-element.js";
 import { PlayerController } from "../../player/player-controller.js";
+import { UIElement } from "../ui-element.js";
 import { sliderContext } from "../slider/context.js";
-import { applyElementProps, applyStateDataAttrs, createSlider, getSliderCSSVars, logMissingFeature, selectVolume } from "@videojs/core/dom";
-import { ContextProvider } from "@videojs/element/context";
 import { VolumeSliderCore, VolumeSliderDataAttrs } from "@videojs/core";
-import { applyStyles, isRTL } from "@videojs/utils/dom";
-
+import { applyElementProps, applyStateDataAttrs, createSlider, createWheelStep, getSliderCSSVars, logMissingFeature, selectControls, selectVolume } from "@videojs/core/dom";
+import { ContextProvider } from "@videojs/element/context";
+import { translateText } from "@videojs/core/i18n";
+import { applyStyles } from "@videojs/utils/dom";
 //#region src/ui/volume-slider/volume-slider-element.ts
-var VolumeSliderElement = class extends MediaElement {
+/**
+* @fires drag-start - Fired when a pointer drag starts.
+* @fires drag-end - Fired when a pointer drag ends.
+*/
+var VolumeSliderElement = class extends UIElement {
 	constructor(..._args) {
 		super(..._args);
-		this.label = VolumeSliderCore.defaultProps.label;
+		this.label = "";
 		this.step = VolumeSliderCore.defaultProps.step;
 		this.largeStep = VolumeSliderCore.defaultProps.largeStep;
+		this.wheelStep = VolumeSliderCore.defaultProps.wheelStep;
 		this.orientation = VolumeSliderCore.defaultProps.orientation;
 		this.disabled = VolumeSliderCore.defaultProps.disabled;
 		this.thumbAlignment = VolumeSliderCore.defaultProps.thumbAlignment;
+		this.#core = new VolumeSliderCore();
+		this.#controlsState = new PlayerController(this, playerContext, selectControls);
+		this.#provider = new ContextProvider(this, { context: sliderContext });
+		this.#volumeState = new PlayerController(this, playerContext, selectVolume);
+		this.#i18n = new I18nController(this, i18nContext);
+		this.#slider = null;
+		this.#disconnect = null;
+		this.#releaseControlsLock = null;
 	}
 	static {
 		this.tagName = "media-volume-slider";
@@ -29,6 +44,10 @@ var VolumeSliderElement = class extends MediaElement {
 				type: Number,
 				attribute: "large-step"
 			},
+			wheelStep: {
+				type: Number,
+				attribute: "wheel-step"
+			},
 			orientation: { type: String },
 			disabled: { type: Boolean },
 			thumbAlignment: {
@@ -37,35 +56,40 @@ var VolumeSliderElement = class extends MediaElement {
 			}
 		};
 	}
-	#core = new VolumeSliderCore();
-	#provider = new ContextProvider(this, { context: sliderContext });
-	#volumeState = new PlayerController(this, playerContext, selectVolume);
-	#slider = null;
-	#disconnect = null;
+	#core;
+	#controlsState;
+	#provider;
+	#volumeState;
+	#i18n;
+	#slider;
+	#disconnect;
+	#releaseControlsLock;
 	connectedCallback() {
 		super.connectedCallback();
 		if (this.destroyed) return;
 		this.#disconnect = new AbortController();
 		const signal = this.#disconnect.signal;
+		const isDisabled = () => {
+			const volume = this.#volumeState.value;
+			return this.disabled || !volume || volume.volumeAvailability !== "available";
+		};
+		const getPercent = () => (this.#volumeState.value?.volume ?? 0) * 100;
+		const getStepPercent = () => this.#core.getStepPercent();
+		const setVolume = (percent) => this.#setVolume(percent);
 		this.#slider = createSlider({
 			getElement: () => this,
 			getThumbElement: () => this.querySelector("media-slider-thumb"),
 			getOrientation: () => this.orientation,
-			isRTL: () => isRTL(this),
-			isDisabled: () => this.disabled || !this.#volumeState.value,
-			getPercent: () => {
-				const media = this.#volumeState.value;
-				if (!media) return 0;
-				return media.volume * 100;
-			},
-			getStepPercent: () => this.#core.getStepPercent(),
+			isDisabled,
+			getPercent,
+			getStepPercent,
 			getLargeStepPercent: () => this.#core.getLargeStepPercent(),
-			onValueChange: (percent) => {
-				this.#setVolume(percent);
-			},
-			onValueCommit: (percent) => {
-				this.#setVolume(percent);
+			onValueChange: setVolume,
+			onValueCommit: setVolume,
+			onPressStart: () => {
+				this.#releaseControlsLock ??= this.#controlsState.value?.requestControlsLock() ?? null;
 			},
+			onPressEnd: () => this.#releaseControlsVisibilityLock(),
 			onDragStart: () => {
 				this.dispatchEvent(new CustomEvent("drag-start", { bubbles: true }));
 			},
@@ -75,23 +99,37 @@ var VolumeSliderElement = class extends MediaElement {
 			adjustPercent: (raw, thumbSize, trackSize) => this.#core.adjustPercentForAlignment(raw, thumbSize, trackSize),
 			onResize: () => this.requestUpdate()
 		});
+		const wheelProps = createWheelStep({
+			isDisabled,
+			getPercent,
+			getStepPercent: () => this.#core.getWheelStepPercent(),
+			onValueChange: setVolume
+		});
 		applyElementProps(this, this.#slider.rootProps, { signal });
+		applyElementProps(this, wheelProps, { signal });
 		applyStyles(this, this.#slider.rootStyle);
 		this.#slider.input.subscribe(() => this.requestUpdate(), { signal });
 		if (!this.#volumeState.value) logMissingFeature(this.localName, this.#volumeState.displayName);
 	}
 	disconnectedCallback() {
+		this.#releaseControlsVisibilityLock();
 		super.disconnectedCallback();
 		this.#disconnect?.abort();
 		this.#disconnect = null;
 	}
 	destroyCallback() {
+		this.#releaseControlsVisibilityLock();
 		this.#slider?.destroy();
 		super.destroyCallback();
 	}
+	#releaseControlsVisibilityLock() {
+		this.#releaseControlsLock?.();
+		this.#releaseControlsLock = null;
+	}
 	willUpdate(_changed) {
 		super.willUpdate(_changed);
 		this.#core.setProps(this);
+		this.#core.setFormatLocale(this.#i18n.locale);
 	}
 	update(_changed) {
 		super.update(_changed);
@@ -102,13 +140,19 @@ var VolumeSliderElement = class extends MediaElement {
 		this.#core.setMedia(media);
 		const state = this.#core.getState();
 		const cssVars = getSliderCSSVars(this.#slider.adjustForAlignment(state));
+		const thumbAttrs = this.#core.getAttrs(state);
 		applyStyles(this, cssVars);
 		applyStateDataAttrs(this, state, VolumeSliderDataAttrs);
+		applyElementProps(this, { hidden: state.hidden ? "" : void 0 });
 		this.#provider.setValue({
 			state,
 			stateAttrMap: VolumeSliderDataAttrs,
 			pointerValue: this.#core.valueFromPercent(state.pointerPercent),
-			thumbAttrs: this.#core.getAttrs(state),
+			thumbAttrs: {
+				...thumbAttrs,
+				"aria-label": translateText(thumbAttrs["aria-label"], this.#i18n.value),
+				"aria-valuetext": translateText(thumbAttrs["aria-valuetext"], this.#i18n.value, this.#core.getValueTextParams(state))
+			},
 			thumbProps: this.#slider.thumbProps,
 			formatValue: (value) => `${Math.round(value)}%`
 		});
@@ -117,7 +161,7 @@ var VolumeSliderElement = class extends MediaElement {
 		this.#volumeState.value?.setVolume(this.#core.valueFromPercent(percent) / 100);
 	}
 };
-
 //#endregion
 export { VolumeSliderElement };
+
 //# sourceMappingURL=volume-slider-element.js.map

package/dist/dev/ui/volume-slider/volume-slider-element.js.map

@@ -1 +1 @@
-{"version":3,"file":"volume-slider-element.js","names":["#core","#provider","#volumeState","#disconnect","#slider","#setVolume"],"sources":["../../../../src/ui/volume-slider/volume-slider-element.ts"],"sourcesContent":["import { VolumeSliderCore, VolumeSliderDataAttrs } from '@videojs/core';\nimport {\n  applyElementProps,\n  applyStateDataAttrs,\n  createSlider,\n  getSliderCSSVars,\n  logMissingFeature,\n  type SliderApi,\n  selectVolume,\n} from '@videojs/core/dom';\nimport type { PropertyDeclarationMap, PropertyValues } from '@videojs/element';\nimport { ContextProvider } from '@videojs/element/context';\nimport { applyStyles, isRTL } from '@videojs/utils/dom';\n\nimport { playerContext } from '../../player/context';\nimport { PlayerController } from '../../player/player-controller';\nimport { MediaElement } from '../media-element';\nimport { sliderContext } from '../slider/context';\n\nexport class VolumeSliderElement extends MediaElement {\n  static readonly tagName = 'media-volume-slider';\n\n  static override properties = {\n    label: { type: String },\n    step: { type: Number },\n    largeStep: { type: Number, attribute: 'large-step' },\n    orientation: { type: String },\n    disabled: { type: Boolean },\n    thumbAlignment: { type: String, attribute: 'thumb-alignment' },\n  } satisfies PropertyDeclarationMap<Exclude<keyof VolumeSliderCore.Props, 'value' | 'min' | 'max'>>;\n\n  label = VolumeSliderCore.defaultProps.label;\n  step = VolumeSliderCore.defaultProps.step;\n  largeStep = VolumeSliderCore.defaultProps.largeStep;\n  orientation = VolumeSliderCore.defaultProps.orientation;\n  disabled = VolumeSliderCore.defaultProps.disabled;\n  thumbAlignment = VolumeSliderCore.defaultProps.thumbAlignment;\n\n  readonly #core = new VolumeSliderCore();\n  readonly #provider = new ContextProvider(this, { context: sliderContext });\n  readonly #volumeState = new PlayerController(this, playerContext, selectVolume);\n\n  #slider: SliderApi | null = null;\n  #disconnect: AbortController | null = null;\n\n  override connectedCallback(): void {\n    super.connectedCallback();\n    if (this.destroyed) return;\n\n    this.#disconnect = new AbortController();\n    const signal = this.#disconnect.signal;\n\n    this.#slider = createSlider({\n      getElement: () => this,\n      getThumbElement: () => this.querySelector<HTMLElement>('media-slider-thumb'),\n      getOrientation: () => this.orientation,\n      isRTL: () => isRTL(this),\n      isDisabled: () => this.disabled || !this.#volumeState.value,\n      getPercent: () => {\n        const media = this.#volumeState.value;\n        if (!media) return 0;\n        return media.volume * 100;\n      },\n      getStepPercent: () => this.#core.getStepPercent(),\n      getLargeStepPercent: () => this.#core.getLargeStepPercent(),\n      onValueChange: (percent) => {\n        this.#setVolume(percent);\n      },\n      onValueCommit: (percent) => {\n        this.#setVolume(percent);\n      },\n      onDragStart: () => {\n        this.dispatchEvent(new CustomEvent('drag-start', { bubbles: true }));\n      },\n      onDragEnd: () => {\n        this.dispatchEvent(new CustomEvent('drag-end', { bubbles: true }));\n      },\n      adjustPercent: (raw, thumbSize, trackSize) => this.#core.adjustPercentForAlignment(raw, thumbSize, trackSize),\n      onResize: () => this.requestUpdate(),\n    });\n\n    applyElementProps(this, this.#slider.rootProps, { signal });\n    applyStyles(this, this.#slider.rootStyle);\n    this.#slider.input.subscribe(() => this.requestUpdate(), { signal });\n\n    if (__DEV__ && !this.#volumeState.value) {\n      logMissingFeature(this.localName, this.#volumeState.displayName!);\n    }\n  }\n\n  override disconnectedCallback(): void {\n    super.disconnectedCallback();\n    this.#disconnect?.abort();\n    this.#disconnect = null;\n  }\n\n  override destroyCallback(): void {\n    this.#slider?.destroy();\n    super.destroyCallback();\n  }\n\n  protected override willUpdate(_changed: PropertyValues): void {\n    super.willUpdate(_changed);\n    this.#core.setProps(this);\n  }\n\n  protected override update(_changed: PropertyValues): void {\n    super.update(_changed);\n    if (!this.#slider) return;\n\n    const media = this.#volumeState.value;\n    if (!media) return;\n\n    this.#core.setInput(this.#slider.input.current);\n    this.#core.setMedia(media);\n    const state = this.#core.getState();\n\n    const cssVars = getSliderCSSVars(this.#slider.adjustForAlignment(state));\n\n    applyStyles(this, cssVars);\n\n    // Apply data attributes to root.\n    applyStateDataAttrs(this, state, VolumeSliderDataAttrs);\n\n    // Provide context to child elements.\n    this.#provider.setValue({\n      state,\n      stateAttrMap: VolumeSliderDataAttrs,\n      pointerValue: this.#core.valueFromPercent(state.pointerPercent),\n      thumbAttrs: this.#core.getAttrs(state),\n      thumbProps: this.#slider.thumbProps,\n      formatValue: (value) => `${Math.round(value)}%`,\n    });\n  }\n\n  #setVolume(percent: number): void {\n    const media = this.#volumeState.value;\n    media?.setVolume(this.#core.valueFromPercent(percent) / 100);\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"volume-slider-element.js","names":["#core","#controlsState","#provider","#volumeState","#i18n","#disconnect","#setVolume","#slider","#releaseControlsLock","#releaseControlsVisibilityLock"],"sources":["../../../../src/ui/volume-slider/volume-slider-element.ts"],"sourcesContent":["import { VolumeSliderCore, VolumeSliderDataAttrs } from '@videojs/core';\nimport {\n  applyElementProps,\n  applyStateDataAttrs,\n  createSlider,\n  createWheelStep,\n  getSliderCSSVars,\n  logMissingFeature,\n  type SliderApi,\n  selectControls,\n  selectVolume,\n} from '@videojs/core/dom';\nimport { type Text, translateText } from '@videojs/core/i18n';\nimport type { PropertyDeclarationMap, PropertyValues } from '@videojs/element';\nimport { ContextProvider } from '@videojs/element/context';\nimport { applyStyles } from '@videojs/utils/dom';\n\nimport { i18nContext } from '../../i18n/context';\nimport { I18nController } from '../../i18n/controller';\nimport { playerContext } from '../../player/context';\nimport { PlayerController } from '../../player/player-controller';\nimport { sliderContext } from '../slider/context';\nimport { UIElement } from '../ui-element';\n\n/**\n * @fires drag-start - Fired when a pointer drag starts.\n * @fires drag-end - Fired when a pointer drag ends.\n */\nexport class VolumeSliderElement extends UIElement {\n  static readonly tagName = 'media-volume-slider';\n\n  static override properties = {\n    label: { type: String },\n    step: { type: Number },\n    largeStep: { type: Number, attribute: 'large-step' },\n    wheelStep: { type: Number, attribute: 'wheel-step' },\n    orientation: { type: String },\n    disabled: { type: Boolean },\n    thumbAlignment: { type: String, attribute: 'thumb-alignment' },\n  } satisfies PropertyDeclarationMap<Exclude<keyof VolumeSliderCore.Props, 'value' | 'min' | 'max'>>;\n\n  label: Text | string = '';\n  step = VolumeSliderCore.defaultProps.step;\n  largeStep = VolumeSliderCore.defaultProps.largeStep;\n  wheelStep = VolumeSliderCore.defaultProps.wheelStep;\n  orientation = VolumeSliderCore.defaultProps.orientation;\n  disabled = VolumeSliderCore.defaultProps.disabled;\n  thumbAlignment = VolumeSliderCore.defaultProps.thumbAlignment;\n\n  readonly #core = new VolumeSliderCore();\n  readonly #controlsState = new PlayerController(this, playerContext, selectControls);\n  readonly #provider = new ContextProvider(this, { context: sliderContext });\n  readonly #volumeState = new PlayerController(this, playerContext, selectVolume);\n  readonly #i18n = new I18nController(this, i18nContext);\n\n  #slider: SliderApi | null = null;\n  #disconnect: AbortController | null = null;\n  #releaseControlsLock: (() => void) | null = null;\n\n  override connectedCallback(): void {\n    super.connectedCallback();\n\n    if (this.destroyed) return;\n\n    this.#disconnect = new AbortController();\n    const signal = this.#disconnect.signal;\n\n    const isDisabled = () => {\n      const volume = this.#volumeState.value;\n\n      return this.disabled || !volume || volume.volumeAvailability !== 'available';\n    };\n\n    const getPercent = () => (this.#volumeState.value?.volume ?? 0) * 100;\n    const getStepPercent = () => this.#core.getStepPercent();\n    const setVolume = (percent: number) => this.#setVolume(percent);\n\n    this.#slider = createSlider({\n      getElement: () => this,\n      getThumbElement: () => this.querySelector<HTMLElement>('media-slider-thumb'),\n      getOrientation: () => this.orientation,\n      isDisabled,\n      getPercent,\n      getStepPercent,\n      getLargeStepPercent: () => this.#core.getLargeStepPercent(),\n      onValueChange: setVolume,\n      onValueCommit: setVolume,\n      onPressStart: () => {\n        this.#releaseControlsLock ??= this.#controlsState.value?.requestControlsLock() ?? null;\n      },\n      onPressEnd: () => this.#releaseControlsVisibilityLock(),\n      onDragStart: () => {\n        this.dispatchEvent(new CustomEvent('drag-start', { bubbles: true }));\n      },\n      onDragEnd: () => {\n        this.dispatchEvent(new CustomEvent('drag-end', { bubbles: true }));\n      },\n      adjustPercent: (raw, thumbSize, trackSize) => this.#core.adjustPercentForAlignment(raw, thumbSize, trackSize),\n      onResize: () => this.requestUpdate(),\n    });\n\n    const wheelProps = createWheelStep({\n      isDisabled,\n      getPercent,\n      getStepPercent: () => this.#core.getWheelStepPercent(),\n      onValueChange: setVolume,\n    });\n\n    applyElementProps(this, this.#slider.rootProps, { signal });\n    applyElementProps(this, wheelProps, { signal });\n    applyStyles(this, this.#slider.rootStyle);\n    this.#slider.input.subscribe(() => this.requestUpdate(), { signal });\n\n    if (__DEV__ && !this.#volumeState.value) {\n      logMissingFeature(this.localName, this.#volumeState.displayName!);\n    }\n  }\n\n  override disconnectedCallback(): void {\n    this.#releaseControlsVisibilityLock();\n    super.disconnectedCallback();\n    this.#disconnect?.abort();\n    this.#disconnect = null;\n  }\n\n  override destroyCallback(): void {\n    this.#releaseControlsVisibilityLock();\n    this.#slider?.destroy();\n    super.destroyCallback();\n  }\n\n  #releaseControlsVisibilityLock(): void {\n    this.#releaseControlsLock?.();\n    this.#releaseControlsLock = null;\n  }\n\n  protected override willUpdate(_changed: PropertyValues): void {\n    super.willUpdate(_changed);\n    this.#core.setProps(this);\n    this.#core.setFormatLocale(this.#i18n.locale);\n  }\n\n  protected override update(_changed: PropertyValues): void {\n    super.update(_changed);\n\n    if (!this.#slider) return;\n\n    const media = this.#volumeState.value;\n    if (!media) return;\n\n    this.#core.setInput(this.#slider.input.current);\n    this.#core.setMedia(media);\n    const state = this.#core.getState();\n\n    const cssVars = getSliderCSSVars(this.#slider.adjustForAlignment(state));\n    const thumbAttrs = this.#core.getAttrs(state);\n\n    applyStyles(this, cssVars);\n\n    // Apply data attributes to root.\n    applyStateDataAttrs(this, state, VolumeSliderDataAttrs);\n    applyElementProps(this, { hidden: state.hidden ? '' : undefined });\n\n    // Provide context to child elements.\n    this.#provider.setValue({\n      state,\n      stateAttrMap: VolumeSliderDataAttrs,\n      pointerValue: this.#core.valueFromPercent(state.pointerPercent),\n      thumbAttrs: {\n        ...thumbAttrs,\n        'aria-label': translateText(thumbAttrs['aria-label'], this.#i18n.value),\n        'aria-valuetext': translateText(\n          thumbAttrs['aria-valuetext'],\n          this.#i18n.value,\n          this.#core.getValueTextParams(state)\n        ),\n      },\n      thumbProps: this.#slider.thumbProps,\n      formatValue: (value) => `${Math.round(value)}%`,\n    });\n  }\n\n  #setVolume(percent: number): void {\n    const media = this.#volumeState.value;\n\n    media?.setVolume(this.#core.valueFromPercent(percent) / 100);\n  }\n}\n"],"mappings":"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"}

package/docs/README.md

@@ -0,0 +1,7 @@
+# @videojs/html documentation
+
+Bundled markdown documentation for `@videojs/html` v10.0.0-rc.1.
+
+Start at [`./llms.txt`](./llms.txt) — it's the structured index of every page in this directory.
+
+Canonical online version: https://videojs.org/docs/framework/html

package/docs/concepts/accessibility.md

@@ -0,0 +1,68 @@
+# 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.
+
+## 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"`.
+
+Verify that labels are contextually correct for your content and language. Each component’s reference page documents the attributes it sets.
+
+## 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/).
+
+## 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`.
+
+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.
+
+## 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
+
+Controls use rem-based sizing so they scale with the user’s font size preference. All interactive elements set [`touch-action: manipulation`](https://developer.mozilla.org/en-US/docs/Web/CSS/touch-action) to eliminate tap delay on touch devices. 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
+
+Skins adapt to [`prefers-color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme). Borders, backgrounds, and text colors adjust through CSS custom properties. Custom components can use the same design tokens. See [Skins](./skins.md) for details.
+
+## 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.
+
+## 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/concepts/browser-support.md

@@ -0,0 +1,45 @@
+# Browser support
+
+Browsers and rendering environments supported by Video.js 10
+
+Support starts with an evergreen browser baseline and extends to the rendering environments described below.
+
+## Browser baseline
+
+Video.js 10 currently targets **evergreen browsers**: the latest two stable versions of Chrome, Firefox, Safari, and Edge.
+
+Note
+
+Video.js 10 is in beta. The browser support matrix may expand as we approach GA based on community feedback and usage data.
+
+### Why evergreen?
+
+Video.js 10 builds directly on the web platform: custom elements, CSS custom properties, anchor positioning, and modern JavaScript APIs. Targeting evergreen browsers lets us:
+
+*   **Ship smaller bundles** by avoiding polyfills and transpilation for outdated syntax
+*   **Use platform-native features** like `popover` and anchor positioning instead of JavaScript equivalents
+*   **Keep the core slim** so platform-specific adapters (HTML, React) add only what they need
+
+### Progressive enhancement
+
+When we use a platform feature that hasn’t landed in all supported browsers yet, we provide a fallback. The player works either way; the experience may differ slightly in older browsers. For example, tooltips and popovers use CSS anchor positioning where available and fall back to JavaScript-computed positioning where it isn’t.
+
+## Rendering contexts
+
+### WebViews
+
+A [WebView](https://developer.mozilla.org/en-US/docs/Glossary/WebView) is a browser engine embedded inside a native app. WebViews on iOS (WKWebView) and Android (Android WebView) can behave differently from the full browser; autoplay policies, fullscreen APIs, and hardware acceleration can vary.
+
+Video.js 10 beta targets standard browser environments. If you embed a player inside a native app, test it on each platform and WebView version you support.
+
+### Progressive Web Apps
+
+Installed Progressive Web Apps (PWAs) use the browser engine, but their standalone display mode and platform policies can affect fullscreen, media sessions, and other browser integration. Test playback both in a browser tab and in the installed app.
+
+### Smart TVs and set-top boxes
+
+TV platforms run embedded browsers with limited standards support. Video.js 10’s core is not tied to any specific platform, which makes future TV adapters possible, but TV is not a supported target today.
+
+### Server-side rendering
+
+Video.js components render valid markup on the server. Interactivity — state management, media playback, and event handling — requires the browser and kicks in after hydration.

package/docs/concepts/bundlers.md

@@ -0,0 +1,43 @@
+# Bundlers
+
+Bundler requirements for Video.js package exports, CSS, and wrapper libraries
+
+Before the browser runs your application, a bundler such as Vite combines its imports into files the browser can load. Your bundler must understand the import paths published by Video.js packages.
+
+## Package exports
+
+Each Video.js package has an `exports` field in its `package.json`. This field lists the import paths that applications and libraries can use, such as `@videojs/html/video/player` and `@videojs/react/live-video`.
+
+If an older bundler reports that one of these paths is missing or not exported, upgrade the bundler before adding an alias that bypasses the package’s public API.
+
+## Vite compatibility
+
+Use a current Vite release. Testing confirmed that Vite 5.4.19 can load Video.js JavaScript and CSS package exports. Vite 3.2.8 can load the JavaScript, but it cannot load an exported stylesheet such as `@videojs/html/video/skin.css`.
+
+Packaged HTML skins import their own styles, so an HTML application using `@videojs/html/video/skin` doesn’t need to import `skin.css` separately. The CSS limitation matters only when your application imports that stylesheet directly.
+
+## Externalize Video.js in a wrapper library
+
+You can skip this section when building an application.
+
+If you publish a library that expects its users to install Video.js separately, leave Video.js out of your library’s bundle. Rollup calls a dependency left out of the bundle **external**.
+
+Rollup’s array form matches only the exact package name, so `external: ['@videojs/html']` misses imports such as `@videojs/html/video/player`.
+
+Match the package name and everything below it instead:
+
+rollup.config.js
+
+```
+const videojsPeers = ['@videojs/html'];
+
+export default {
+  external(id) {
+    return videojsPeers.some(
+      (packageName) => id === packageName || id.startsWith(`${packageName}/`)
+    );
+  }
+};
+```
+
+Add every `@videojs/*` package your library imports directly to `videojsPeers` and list it in `peerDependencies`.

package/docs/concepts/cdn.md

@@ -0,0 +1,119 @@
+# CDN
+
+The files the Video.js CDN serves and the layout rules behind their URLs
+
+Video.js can run straight from `<script>` tags. Our CDN serves `@videojs/html` in prebuilt, browser-ready bundles which register custom elements. For many pages, it takes only one script tag:
+
+index.html
+
+```
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.1/video.js"></script>
+
+<video-player>
+  <video-skin>
+    <video src="video.mp4"></video>
+  </video-skin>
+</video-player>
+```
+
+## URLs
+
+Every file the CDN serves follows one URL pattern:
+
+code
+
+```
+https://cdn.jsdelivr.net/npm/@videojs/cdn@<version>/<file>
+```
+
+Pin all your CDN URLs to the same version.
+
+Bundles share content-hashed chunks that change between releases. A tag like `@latest` re-resolves over time, so two files might come from different releases and load duplicate modules that no longer share state.
+
+## Player bundles
+
+Each installation [preset](./presets.md) ships its bundles at the package root: one per skin choice, plus a player-only bundle. For the video preset:
+
+File
+
+Registers
+
+`video.js`
+
+`<video-player>`, `<video-skin>`, and the UI elements the skin composes
+
+`video-minimal.js`
+
+`<video-player>`, `<video-minimal-skin>`, and the UI elements the minimal skin composes
+
+`video-player.js`
+
+`<video-player>` alone, for markup without a packaged skin
+
+The other presets follow the same pattern. Background video is the exception: one bundle, `background.js`, registers the player, the skin, and the `<background-video>` media element.
+
+A skin bundle registers every UI element its skin is built from. The CDN publishes no per-component bundles, though. If you have [ejected a skin](../how-to/customize-skins.md#eject-and-edit-a-skin) and need to add new components, install from npm instead of from the CDN.
+
+## Media bundles
+
+The default presets play through the browser’s own `<video>` and `<audio>`. Every other [media element](./media-sources.md) is its own bundle under `media/`, loaded beside the player bundle:
+
+html
+
+```
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.1/video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.1/media/hlsjs-video.js"></script>
+```
+
+Each path mirrors its npm subpath. Elements with more than one playback engine keep the extra flavors in a directory named for the element, such as `media/mux-video/spf.js`. Load one flavor per page: every flavor claims the same tag name, and the first registration wins.
+
+## Extension bundles
+
+Each [extension](./overview.md) is its own bundle under `extensions/`, loaded beside the player and media bundles:
+
+html
+
+```
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.1/video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.1/media/mux-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.1/extensions/mux-data.js"></script>
+```
+
+As with media, each path mirrors its npm subpath: `extensions/mux-data.js` registers the element that `@videojs/html/extensions/mux-data` does.
+
+## Locales
+
+English ships inside the skin bundles. Each other locale is a bundle under `locales/` that registers its translations on import. Load it before the player script to avoid a flash of English:
+
+html
+
+```
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.1/locales/es.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.1/video.js"></script>
+```
+
+One bundle exists per locale pack, plus bare-language aliases such as `pt`. For custom strings, see [Internationalize the player](../how-to/internationalize-the-player.md).
+
+## Stylesheets
+
+The skin bundles inline their CSS, so no `<link>` is required to render. The separate `.css` files do the jobs a bundle cannot:
+
+*   `global.css` holds the light-DOM rules. Link it in `<head>` and the player reserves its space before the elements upgrade. The background preset uses `background.css` instead.
+*   The skin sheets, such as `video.css` beside `video.js`, style declaratively rendered skins.
+*   `shared.css` is the base that hand-written shadow skins build on.
+
+[Self-host the player](../how-to/self-host-the-player.md) shows both in use.
+
+## Development bundles
+
+Every JavaScript entry has a `.dev.js` sibling, such as `video.dev.js`, built with development warnings on. Swap the suffix while debugging; swap it back to ship.
+
+## Shared chunks
+
+Everything else at the root, like the content-hashed `default-*.js` files, is a shared chunk the entries import by relative path. Entries share these chunks, so loading several bundles stays cheap. Chunk names change every release: never link a chunk directly, and never copy a lone entry file. To mirror the CDN, copy the whole package directory and keep its layout; [Self-host the player](../how-to/self-host-the-player.md) covers it.
+
+## Related guides
+
+*   [Installation](../how-to/installation.md)
+*   [Self-host the player](../how-to/self-host-the-player.md)
+*   [Internationalize the player](../how-to/internationalize-the-player.md)

package/docs/concepts/custom-element-lifecycle.md

@@ -0,0 +1,115 @@
+# Custom element lifecycle
+
+Choose the right Video.js HTML base class and clean up custom elements when they leave the page.
+
+This guide is for developers creating custom elements with `@videojs/html`. If you only compose or style Video.js’s built-in elements, you do not need to manage this lifecycle yourself.
+
+For most custom controls, extend `UIElement`, clean up listeners and observers in `disconnectedCallback()`, and call the matching superclass callbacks. Read the advanced sections if you are building a player root or media element, or if an element must remain alive while detached.
+
+## Clean up when the element disconnects
+
+The browser can call `connectedCallback()` and `disconnectedCallback()` many times for the same element. Start listeners, observers, and other connection-scoped work when the element connects. Stop that work when it disconnects. Call the superclass lifecycle methods so reactive controllers and inherited cleanup also run:
+
+ts
+
+```
+import { UIElement } from '@videojs/html';
+
+class StatusElement extends UIElement {
+  #disconnect: AbortController | null = null;
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.#disconnect = new AbortController();
+    window.addEventListener('resize', this.#onResize, {
+      signal: this.#disconnect.signal,
+    });
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.#disconnect?.abort();
+    this.#disconnect = null;
+  }
+
+  #onResize = () => this.requestUpdate();
+}
+```
+
+This cleanup runs every time the element leaves the document, including when an application moves the same element and later reconnects it.
+
+## Advanced lifecycle details
+
+The rest of this page covers permanent destruction, longer detached periods, player roots, and custom media elements. Most custom controls only need the connection cleanup above.
+
+### Release resources permanently
+
+`UIElement` waits for two animation frames after disconnection before it calls `destroy()`. Synchronous moves and brief reparenting that reconnect before the second frame keep the element alive.
+
+Reserve `destroyCallback()` for resources that should survive a temporary disconnect, such as an owned store or imperative player API. Call `super.destroyCallback()` so registered controllers also release their resources.
+
+After destruction, the mixin’s connection path and update execution no-op. Repeated `destroy()` calls also no-op. Do not reinsert a destroyed instance; create a new element instead. Subclass lifecycle code should still call its superclass methods and can check the public `destroyed` flag when it needs an explicit guard.
+
+### Keep an element alive while detached
+
+Add `keep-alive` to disable automatic destruction for an element that intentionally remains detached longer than two frames. The attribute does not disable manual cleanup: calling `destroy()` still permanently destroys the element.
+
+Caution
+
+`keep-alive` makes your code responsible for calling `destroy()` when the element is no longer needed.
+
+### Choose a specialized base
+
+Choose the narrowest base that provides the lifecycle your element needs:
+
+Base
+
+Lifecycle behavior
+
+Typical use
+
+`HTMLElement`
+
+Browser custom element callbacks only
+
+Elements that manage their own state and cleanup
+
+`ReactiveElement`
+
+Reactive properties, batched updates, and reactive controller callbacks
+
+Reactive elements that do not need permanent destruction
+
+`UIElement`
+
+`ReactiveElement` plus delayed permanent destruction
+
+Custom player controls and other interactive player UI
+
+`CustomMediaElement(...)` with `MediaAttachMixin`
+
+A media adapter lifecycle plus player registration
+
+Custom playback engines and media elements
+
+`PlayerElement`
+
+The `UIElement` lifecycle plus store context and attachment ownership
+
+Player roots
+
+Use `UIElement` for most custom controls. Use the specialized bases when your element owns a player store or media provider.
+
+### Specialized resource owners
+
+`PlayerElement` follows the `UIElement` lifecycle. It detaches the store’s current media target immediately in `disconnectedCallback()`, but keeps the store so a brief move can reconnect with its state intact. It destroys the store only from `destroyCallback()`.
+
+Built-in custom media elements compose `CustomMediaElement(...)` with [`MediaAttachMixin`](../reference/media-attach-mixin.md). `CustomMediaElement` queues one microtask after disconnection and destroys its media adapter only if it remains disconnected. This protects a synchronous move, but not a longer detached period. Its `keep-alive` attribute skips that automatic media-adapter destruction.
+
+Player roots use the configured [`PlayerElement`](../reference/player.md) returned by `createPlayer`.
+
+## See also
+
+*   [Build your own UI component](../how-to/build-your-own-component.md)
+*   [`PlayerElement`](../reference/player.md)
+*   [`MediaAttachMixin`](../reference/media-attach-mixin.md)