@videojs/react 10.0.0-beta.31 → 10.0.0-beta.32

package/docs/reference/controls.md

@@ -2,6 +2,14 @@
 
 Container component for composing and auto-hiding video player controls on user interaction
 
+## Import
+
+tsx
+
+```
+import { Controls } from '@videojs/react';
+```
+
 ## Anatomy
 
 Import the component and assemble its parts:
@@ -10,7 +18,10 @@ tsx
 
 ```
 <Controls.Root>
-  <Controls.Group />
+  <Controls.Backdrop />
+  <Controls.Content>
+    <Controls.Group />
+  </Controls.Content>
 </Controls.Root>
 ```
 
@@ -22,6 +33,10 @@ User activity is tracked via pointer movement, keyboard input, and focus events
 
 ## Styling
 
+`Controls.Root` is a state and context provider. `Controls.Content` / `<media-controls-content>` renders the interactive controls surface and receives its DOM props, ref, and controls state data attributes.
+
+`Controls.Backdrop` / `<media-controls-backdrop>` is an optional presentational sibling of Content. It receives the same controls state data attributes, allowing its styling and transitions to be authored independently from the controls surface.
+
 By default, controls have the following styles:
 
 React renders `<div>` elements. Add a `className` to style them:
@@ -38,6 +53,12 @@ css
   pointer-events: auto;
 }
 
+.controls-backdrop {
+  position: absolute;
+  inset: 0;
+  transition: opacity 0.35s;
+}
+
 /* Fade transition */
 .controls {
   transition: opacity 0.25s;
@@ -46,11 +67,15 @@ css
 .controls:not([data-visible]) {
   opacity: 0;
 }
+
+.controls-backdrop:not([data-visible]) {
+  opacity: 0;
+}
 ```
 
 ## Accessibility
 
-No ARIA role is applied to `Controls.Root` — it is a layout wrapper, not a landmark. `Controls.Group` automatically receives `role="group"` when an `aria-label` or `aria-labelledby` attribute is provided; otherwise no role is assigned.
+`Controls.Root` renders no element. No ARIA role is applied to `Controls.Content` because it is a layout surface, not a landmark. `Controls.Backdrop` is always hidden from assistive technology. `Controls.Group` automatically receives `role="group"` when an `aria-label` or `aria-labelledby` attribute is provided; otherwise no role is assigned.
 
 ## Examples
 
@@ -74,15 +99,18 @@ export default function BasicUsage() {
       <Container className="media-container">
         <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
 
-        <Controls.Root className="media-controls">
-          <Controls.Group className="controls-group" aria-label="Playback controls">
-            <PlayButton
-              className="button"
-              render={(props, state) => <button {...props}>{state.paused ? 'Play' : 'Pause'}</button>}
-            />
-
-            <Time.Value type="current" className="time" />
-          </Controls.Group>
+        <Controls.Root>
+          <Controls.Backdrop className="controls-backdrop" />
+          <Controls.Content className="media-controls">
+            <Controls.Group className="controls-group" aria-label="Playback controls">
+              <PlayButton
+                className="button"
+                render={(props, state) => <button {...props}>{state.paused ? 'Play' : 'Pause'}</button>}
+              />
+
+              <Time.Value type="current" className="time" />
+            </Controls.Group>
+          </Controls.Content>
         </Controls.Root>
       </Container>
     </Player>
@@ -105,15 +133,28 @@ export default function BasicUsage() {
   align-items: flex-end;
   padding: 12px;
   pointer-events: none;
-  background: linear-gradient(to top, rgba(0, 0, 0, 0.45), transparent 45%);
   transition: opacity 0.25s;
 }
 
+.controls-backdrop {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+  background: linear-gradient(to top, rgba(0, 0, 0, 0.45), transparent 45%);
+  opacity: 1;
+  transition: opacity 0.35s;
+}
+
+.controls-backdrop:not([data-visible]),
 .media-controls:not([data-visible]) {
   opacity: 0;
 }
 
 .controls-group {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
   pointer-events: auto;
 }
 
@@ -131,13 +172,6 @@ export default function BasicUsage() {
   backdrop-filter: blur(10px);
 }
 
-.controls-group {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  width: 100%;
-}
-
 .button {
   padding-block: 8px;
   padding-inline: 16px;
@@ -157,7 +191,7 @@ export default function BasicUsage() {
 
 Root
 
-Root container for player controls state and rendered control content.
+Manages controls state and provides it to the compound parts. Does not render an element.
 
 #### State
 
@@ -203,10 +237,208 @@ Present when the user has recently interacted.
 
 ### 
 
+Backdrop
+
+Presentational layer behind player controls. Renders a `<div>` with the controls state data attributes so skins can style it without reaching across sibling components.
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`className`
+
+`string | ((state: ControlsCore.State) => string | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Class name or function returning class name from state.
+
+`render`
+
+`ReactElement | ((props: HTMLProps, state: ControlsCore.State) => ReactElement | null)`
+
+`—`
+
+▸
+
+Description
+
+Render prop for custom element.
+
+`style`
+
+`CSSProperties | ((state: ControlsCore.State) => CSSProperties | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Style or function returning style from state.
+
+#### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-visible`
+
+▸
+
+Description
+
+Present when controls are visible.
+
+`data-user-active`
+
+▸
+
+Description
+
+Present when the user has recently interacted.
+
+### 
+
+Content
+
+Renders the interactive controls surface.
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`className`
+
+`string | ((state: ControlsCore.State) => string | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Class name or function returning class name from state.
+
+`render`
+
+`ReactElement | ((props: HTMLProps, state: ControlsCore.State) => ReactElement | null)`
+
+`—`
+
+▸
+
+Description
+
+Render prop for custom element.
+
+`style`
+
+`CSSProperties | ((state: ControlsCore.State) => CSSProperties | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Style or function returning style from state.
+
+#### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-visible`
+
+▸
+
+Description
+
+Present when controls are visible.
+
+`data-user-active`
+
+▸
+
+Description
+
+Present when the user has recently interacted.
+
+### 
+
 Group
 
 Layout group for related controls; sets `role="group"` when labeled.
 
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`className`
+
+`string | ((state: ControlsCore.State) => string | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Class name or function returning class name from state.
+
+`render`
+
+`ReactElement | ((props: HTMLProps, state: ControlsCore.State) => ReactElement | null)`
+
+`—`
+
+▸
+
+Description
+
+Render prop for custom element.
+
+`style`
+
+`CSSProperties | ((state: ControlsCore.State) => CSSProperties | undefined)`
+
+`—`
+
+▸
+
+Description
+
+Style or function returning style from state.
+
 #### Data attributes
 
 Attribute

package/docs/reference/create-i18n.md

@@ -43,7 +43,7 @@ Details
 
 `options`
 
-`CreateI18nOptions`
+`object`
 
 `—`
 
@@ -53,6 +53,10 @@ Description
 
 Optional hooks such as custom built-in locale loading.
 
+Type
+
+`{ loader?: ((tag: string) => Promise<Partial<FlatTranslations> | undefined>) }`
+
 ### Return Value
 
 Property
@@ -77,8 +81,8 @@ Type
 
 `useTranslator`
 
-`useTranslator`
+`typeof useTranslator`
 
 `useLocale`
 
-`useLocale`
+`typeof useLocale`

package/docs/reference/create-player.md

@@ -106,7 +106,7 @@ Details
 
 `config*`
 
-`CreatePlayerConfig<VideoFeatures>`
+`object`
 
 `—`
 
@@ -116,6 +116,10 @@ Description
 
 Player configuration with features and optional display name.
 
+Type
+
+`{ features: VideoFeatures; displayName?: string }`
+
 #### Return Value
 
 Property
@@ -126,11 +130,27 @@ Details
 
 `Player`
 
-`React.FC<PlayerProps<{ title: MediaContentValue; poster: MediaContentValue }>>`
+`FC<PlayerProps<InferPlayerConfig<VideoPlayerStore>>>`
+
+▸
+
+Description
+
+Provides a new player store to its descendants without adding a layout element.
 
 `usePlayer`
 
-`UsePlayerHook<VideoPlayerStore>`
+`function`
+
+▸
+
+Description
+
+Accesses the configured store, or subscribes to a selected value from it.
+
+Type
+
+`{ (): Store;; <R>(selector: (state: InferStoreState<Store>) => R): R; }`
 
 `useMedia`
 
@@ -138,6 +158,10 @@ Details
 
 ▸
 
+Description
+
+Returns the media currently attached beneath the generated Player, or `null` before attachment.
+
 Type
 
 `(() => Media | null)`
@@ -158,7 +182,7 @@ Details
 
 `config*`
 
-`CreatePlayerConfig<AudioFeatures>`
+`object`
 
 `—`
 
@@ -168,6 +192,10 @@ Description
 
 Player configuration with features and optional display name.
 
+Type
+
+`{ features: AudioFeatures; displayName?: string }`
+
 #### Return Value
 
 Property
@@ -178,11 +206,27 @@ Details
 
 `Player`
 
-`React.FC<PlayerProps<{ title: MediaContentValue; poster: MediaContentValue }>>`
+`FC<PlayerProps<InferPlayerConfig<AudioPlayerStore>>>`
+
+▸
+
+Description
+
+Provides a new player store to its descendants without adding a layout element.
 
 `usePlayer`
 
-`UsePlayerHook<AudioPlayerStore>`
+`function`
+
+▸
+
+Description
+
+Accesses the configured store, or subscribes to a selected value from it.
+
+Type
+
+`{ (): Store;; <R>(selector: (state: InferStoreState<Store>) => R): R; }`
 
 `useMedia`
 
@@ -190,6 +234,10 @@ Details
 
 ▸
 
+Description
+
+Returns the media currently attached beneath the generated Player, or `null` before attachment.
+
 Type
 
 `(() => Media | null)`
@@ -210,7 +258,7 @@ Details
 
 `config*`
 
-`CreatePlayerConfig<AnyPlayerFeature[]>`
+`object`
 
 `—`
 
@@ -220,6 +268,10 @@ Description
 
 Player configuration with features and optional display name.
 
+Type
+
+`{ features: Features; displayName?: string }`
+
 #### Return Value
 
 Property
@@ -230,11 +282,27 @@ Details
 
 `Player`
 
-`React.FC<PlayerProps<Config | object>>`
+`FC<PlayerProps<InferPlayerConfig<PlayerStore<Features>>>>`
+
+▸
+
+Description
+
+Provides a new player store to its descendants without adding a layout element.
 
 `usePlayer`
 
-`UsePlayerHook<PlayerStore<AnyPlayerFeature[]>>`
+`function`
+
+▸
+
+Description
+
+Accesses the configured store, or subscribes to a selected value from it.
+
+Type
+
+`{ (): Store;; <R>(selector: (state: InferStoreState<Store>) => R): R; }`
 
 `useMedia`
 
@@ -242,6 +310,10 @@ Details
 
 ▸
 
+Description
+
+Returns the media currently attached beneath the generated Player, or `null` before attachment.
+
 Type
 
 `(() => Media | null)`

package/docs/reference/create-selector.md

@@ -46,14 +46,12 @@ The slice to create a selector for.
 
 ### Return Value
 
+Property
+
 Type
 
 Details
 
-`Selector<object, InferSliceState<S> |...`
-
-▸
-
-Type
+`displayName`
 
-`Selector<object, InferSliceState<S> | undefined>`
+`string`

package/docs/reference/create-translator.md

@@ -28,7 +28,7 @@ Details
 
 `translations*`
 
-`object & Record<string, string | unde...`
+`object`
 
 `—`
 
@@ -40,11 +40,11 @@ Merged translation map for the active locale.
 
 Type
 
-`object & Record<string, string | undefined>`
+`{ [Key in TranslationKey]?: TranslationParams[Key] extends never ? string : Key extends keyof ParametricTranslations ? ParametricTranslations[Key] : string; } & Record<string, string | undefined>`
 
 `locale*`
 
-`string & object | 'ar' | 'az' | 'bs' ...`
+`(typeof LOCALES)[number] | string & o...`
 
 `—`
 
@@ -56,8 +56,18 @@ BCP 47 tag associated with the map (reserved for future locale-aware behavior).
 
 Type
 
-`string & object | 'ar' | 'az' | 'bs' | 'bg' | 'bn' | 'ca' | 'cs' | 'cy' | 'da' | 'de' | 'el' | 'es' | 'et' | 'eu' | 'fa' | 'fi' | 'fr' | 'gd' | 'gl' | 'he' | 'hi' | 'hr' | 'hu' | 'id' | 'it' | 'ja' | 'ko' | 'lt' | 'lv' | 'mr' | 'nb' | 'nl' | 'nn' | 'ne' | 'oc' | 'pl' | 'pt-BR' | 'pt-PT' | 'ro' | 'ru' | 'sk' | 'sl' | 'sr' | 'sv' | 'te' | 'th' | 'tr' | 'uk' | 'vi' | 'zh-CN' | 'zh-TW'`
+`(typeof LOCALES)[number] | string & object`
 
 ### Return Value
 
-`Translator`
+Type
+
+Details
+
+`object`
+
+▸
+
+Type
+
+`{ <Key extends string>( key: Key, ...args: Key extends TranslationKey ? TranslationParams[Key] extends never ? [params?: TranslationOptions] : [params: TranslationParams[Key] & TranslationOptions] : [params?: TextParams & TranslationOptions] ): string;; (text: Text, params?: TextParams): string; }`

package/docs/reference/dash-video.md

@@ -42,7 +42,7 @@ Details
 
 `source`
 
-`DashSource | null`
+`{ src?: string; engine?: DashEngineConfig } | null`
 
 `null`
 
@@ -52,7 +52,7 @@ Description
 
 Structured source: the MPD URL in `src`, plus dash.js settings in `engine.dashJs`. Replacing it re-derives `src`.
 
-dash.js takes settings on a live player, so changing `engine.dashJs` re-applies them in place instead of recreating the engine.
+Dash.js takes settings on a live player, so changing `engine.dashJs` re-applies them in place instead of recreating the engine.
 
 `src`
 
@@ -93,7 +93,7 @@ Details
 
 Type
 
-`{ logLevel?: LogLevel; dispatchEvent?: boolean; }`
+`{ logLevel?: LogLevel; dispatchEvent?: boolean } | undefined`
 
 `errors`
 
@@ -103,7 +103,7 @@ Type
 
 Type
 
-`{ recoverAttempts?: { mediaErrorDecode?: number; }; }`
+`{ recoverAttempts?: { mediaErrorDecode?: number } } | undefined`
 
 `streaming`
 
@@ -113,7 +113,7 @@ Type
 
 Type
 
-`{ abandonLoadTimeout?: number; wallclockTimeUpdateInterval?: number; manifestUpdateRetryInterval?: number; liveUpdateTimeThresholdInMilliseconds?: number; cacheInitSegments?: boolean; ... 40 more ...; dvbReporting?: { ...; }; }`
+`{ abandonLoadTimeout?: number; wallclockTimeUpdateInterval?: number; manifestUpdateRetryInterval?: number; liveUpdateTimeThresholdInMilliseconds?: number; cacheInitSegments?: boolean; cacheInitSegmentsLimit?: number; applyServiceDescription?: boolean; applyProducerReferenceTime?: boolean; applyContentSteering?: boolean; enableManifestDurationMismatchFix?: boolean; parseInbandPrft?: boolean; enableManifestTimescaleMismatchFix?: boolean; capabilities?: { filterUnsupportedEssentialProperties?: boolean; supportedEssentialProperties?: [{ schemeIdUri?: string; value?: RegExp }]; useMediaCapabilitiesApi?: boolean; filterHDRMetadataFormatEssentialProperties?: boolean; filterVideoColorimetryEssentialProperties?: boolean; filterAudioChannelConfiguration?: boolean }; events?: { eventControllerRefreshDelay?: number; deleteEventMessageDataTimeout?: number }; timeShiftBuffer?: { calcFromSegmentTimeline?: boolean; fallbackToSegmentTimeline?: boolean }; metrics?: { maxListDepth?: number }; delay?: { liveDelayFragmentCount?: number; liveDelay?: number; useSuggestedPresentationDelay?: boolean }; protection?: { keepProtectionMediaKeys?: boolean; keepProtectionMediaKeysMaximumOpenSessions?: number; ignoreEmeEncryptedEvent?: boolean; detectPlayreadyMessageFormat?: boolean; ignoreKeyStatuses?: boolean }; buffer?: { enableSeekDecorrelationFix?: boolean; fastSwitchEnabled?: boolean; flushBufferAtTrackSwitch?: boolean; reuseExistingSourceBuffers?: boolean; bufferPruningInterval?: number; bufferToKeep?: number; bufferTimeAtTopQuality?: number; bufferTimeAtTopQualityLongForm?: number; initialBufferLevel?: number; bufferTimeDefault?: number; longFormContentDurationThreshold?: number; stallThreshold?: number; lowLatencyStallThreshold?: number; useAppendWindow?: boolean; setStallState?: boolean; avoidCurrentTimeRangePruning?: boolean; useChangeType?: boolean; mediaSourceDurationInfinity?: boolean; resetSourceBuffersForTrackSwitch?: boolean; syntheticStallEvents?: { enabled?: boolean; ignoreReadyState?: boolean } }; gaps?: { jumpGaps?: boolean; jumpLargeGaps?: boolean; smallGapLimit?: number; threshold?: number; enableSeekFix?: boolean; enableStallFix?: boolean; stallSeek?: number; seekOffset?: number }; utcSynchronization?: { enabled?: boolean; useManifestDateHeaderTimeSource?: boolean; backgroundAttempts?: number; timeBetweenSyncAttempts?: number; maximumTimeBetweenSyncAttempts?: number; minimumTimeBetweenSyncAttempts?: number; timeBetweenSyncAttemptsAdjustmentFactor?: number; maximumAllowedDrift?: number; enableBackgroundSyncAfterSegmentDownloadError?: boolean; defaultTimingSource?: { scheme?: string; value?: string }; artificialTimeOffsetToApply?: number }; scheduling?: { defaultTimeout?: number; lowLatencyTimeout?: number; scheduleWhilePaused?: boolean }; text?: { defaultEnabled?: boolean; dispatchForManualRendering?: boolean; extendSegmentedCues?: boolean; imsc?: { displayForcedOnlyMode?: boolean; enableRollUp?: boolean }; webvtt?: { customRenderingEnabled?: number } }; liveCatchup?: { maxDrift?: number; liveThreshold?: number; playbackRate?: { min?: number; max?: number }; playbackBufferMin?: number; enabled?: boolean; mode?: string; step?: { start: { min?: number; max?: number }; stop: { min?: number; max?: number } } }; lastBitrateCachingInfo?: { enabled?: boolean; ttl?: number }; lastMediaSettingsCachingInfo?: { enabled?: boolean; ttl?: number }; saveLastMediaSettingsForCurrentStreamingSession?: boolean; cacheLoadThresholds?: { video?: number; audio?: number }; trackSwitchMode?: { video?: TrackSwitchMode; audio?: TrackSwitchMode }; includePreselectionsInMediainfo?: boolean; includePreselectionsForInitialTrackSelection?: boolean; ignoreSelectionPriority?: boolean; prioritizeRoleMain?: boolean; assumeDefaultRoleAsMain?: boolean; selectionModeForInitialTrack?: TrackSelectionMode; blacklistExpiryTime?: number; fragmentRequestTimeout?: number; fragmentRequestProgressTimeout?: number; manifestRequestTimeout?: number; retryIntervals?: { MPD?: number; XLinkExpansion?: number; MediaSegment?: number; InitializationSegment?: number; BitstreamSwitchingSegment?: number; IndexSegment?: number; FragmentInfoSegment?: number; license?: number; licenseCertificate?: number; other?: number; lowLatencyReductionFactor?: number }; retryAttempts?: { MPD?: number; XLinkExpansion?: number; MediaSegment?: number; InitializationSegment?: number; BitstreamSwitchingSegment?: number; IndexSegment?: number; FragmentInfoSegment?: number; license?: number; licenseCertificate?: number; other?: number; lowLatencyMultiplyFactor?: number }; abr?: { limitBitrateByPortal?: boolean; usePixelRatioInLimitBitrateByPortal?: boolean; limitBitrateByPortalMinimum?: number; enableSupplementalPropertyAdaptationSetSwitching?: boolean; rules?: { throughputRule?: { active?: boolean }; bolaRule?: { active?: boolean }; insufficientBufferRule?: { active?: boolean; parameters?: { throughputSafetyFactor?: number; segmentIgnoreCount?: number } }; switchHistoryRule?: { active?: boolean; parameters?: { sampleSize?: number; switchPercentageThreshold?: number } }; droppedFramesRule?: { active?: boolean; parameters?: { minimumSampleSize?: number; droppedFramesPercentageThreshold?: number } }; abandonRequestsRule?: { active?: boolean; parameters?: { abandonDurationMultiplier?: number; minSegmentDownloadTimeThresholdInMs?: number; minThroughputSamplesThreshold?: number } }; l2ARule?: { active?: boolean }; loLPRule?: { active?: boolean } }; throughput?: { averageCalculationMode?: ThroughputCalculationModes; lowLatencyDownloadTimeCalculationMode?: LowLatencyDownloadTimeCalculationModes; useResourceTimingApi?: boolean; useNetworkInformationApi?: { xhr?: boolean; fetch?: boolean }; useDeadTimeLatency?: boolean; bandwidthSafetyFactor?: number; sampleSettings: { live?: number; vod?: number; enableSampleSizeAdjustment?: boolean; decreaseScale?: number; increaseScale?: number; maxMeasurementsToKeep?: number; averageLatencySampleAmount?: number }; ewma: { throughputSlowHalfLifeSeconds?: number; throughputFastHalfLifeSeconds?: number; latencySlowHalfLifeCount?: number; latencyFastHalfLifeCount?: number; weightDownloadTmeMultiplicationFactor?: number } }; maxBitrate?: { audio?: number; video?: number }; minBitrate?: { audio?: number; video?: number }; initialBitrate?: { audio?: number; video?: number }; autoSwitchBitrate?: { audio?: boolean; video?: boolean } }; cmcd?: { applyParametersFromMpd?: boolean; enabled?: boolean; sid?: string | null; cid?: string | null; rtp?: number | null; rtpSafetyFactor?: number; mode?: 'query' | 'header'; enabledKeys?: Array<string>; includeInRequests?: Array<string>; version?: number; eventTargets?: Array<{ enabled?: boolean; url?: string; events?: Array<string>; interval?: number; enabledKeys?: Array<string>; includeInRequests?: Array<string>; batchSize?: number }> }; cmsd?: { enabled?: boolean; abr?: { applyMb: boolean; etpWeightRatio?: number } }; defaultSchemeIdUri?: { viewpoint?: string; audioChannelConfiguration?: string; role?: string; accessibility?: string }; dvbReporting?: { reportingUrl?: string | null } } | undefined`
 
 ### Ref