@video-lab/react-config 4.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Video Lab Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,18 @@
+# @video-lab/react-config
+
+React inline 与 React Frame 共用的 `PlayerProvider` 上下文。业务通常从 `@video-lab/react` 或 `@video-lab/react-frame` 导入 `PlayerProvider`、`usePlayerI18n`，无需直接安装本包。
+
+公开 API 与示例：[全局播放器配置与语言切换](../../docs/guides/PLAYER-GLOBAL-CONFIG.md)。
+
+```tsx
+import { PlayerProvider, usePlayerI18n } from '@video-lab/react-config'
+
+function LanguageLabel() {
+  const { locale } = usePlayerI18n()
+  return <span>{locale}</span>
+}
+
+export function App() {
+  return <PlayerProvider defaultLocale="zh-CN"><LanguageLabel /></PlayerProvider>
+}
+```

package/dist/index.cjs

@@ -0,0 +1,97 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _video_lab_protocol = require("@video-lab/protocol");
+let react = require("react");
+let react_jsx_runtime = require("react/jsx-runtime");
+//#region src/index.tsx
+const Context = (0, react.createContext)(null);
+function PlayerProvider(props) {
+	const parent = (0, react.useContext)(Context);
+	const [internalLocale, setInternalLocale] = (0, react.useState)(() => (0, _video_lab_protocol.normalizeLocaleTag)(props.defaultLocale ?? parent?.locale ?? "zh-CN"));
+	const inheritsLocale = props.locale === void 0 && props.defaultLocale === void 0 && parent !== null;
+	const value = {
+		locale: inheritsLocale ? parent.locale : (0, _video_lab_protocol.normalizeLocaleTag)(props.locale ?? internalLocale),
+		resources: (0, _video_lab_protocol.mergeMessageResources)(parent?.resources, props.resources),
+		messageOverrides: (0, _video_lab_protocol.mergeMessageResources)(parent?.messageOverrides, props.messageOverrides),
+		fallbackLocales: props.fallbackLocales ?? parent?.fallbackLocales ?? [],
+		defaults: (0, _video_lab_protocol.mergePlayerDefaults)(parent?.defaults, props.defaults),
+		frameDefaults: (0, _video_lab_protocol.mergeFrameDefaults)(parent?.frameDefaults, props.frameDefaults),
+		changeLanguage(next) {
+			const normalized = (0, _video_lab_protocol.normalizeLocaleTag)(next);
+			if (inheritsLocale) return parent.changeLanguage(normalized);
+			if (props.locale !== void 0) {
+				if (!props.onLocaleChange) return false;
+				props.onLocaleChange(normalized);
+				return true;
+			}
+			setInternalLocale(normalized);
+			props.onLocaleChange?.(normalized);
+			return true;
+		}
+	};
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Context.Provider, {
+		value,
+		children: props.children
+	});
+}
+/** 播放器组件使用的可选配置；脱离 Provider 时保留原有默认行为。 */
+function useOptionalPlayerConfig() {
+	return (0, react.useContext)(Context);
+}
+const LIVE_DEFAULTS = [
+	"muted",
+	"interactive",
+	"showErrorOverlay",
+	"showDefaultLoadingOverlay",
+	"showLoadingText",
+	"errorButtonColors"
+];
+/** 构造期默认值固定于首次渲染；语言及已声明的实时字段跟随 Provider。 */
+function useResolvedPlayerProps(props, frame = false) {
+	const configProps = props;
+	const context = useOptionalPlayerConfig();
+	const initialDefaults = (0, react.useRef)(null);
+	const initialFrameDefaults = (0, react.useRef)(null);
+	const localeCache = (0, react.useRef)(null);
+	if (!context) return props;
+	if (!initialDefaults.current) initialDefaults.current = context.defaults;
+	if (!initialFrameDefaults.current) initialFrameDefaults.current = context.frameDefaults;
+	const defaults = { ...initialDefaults.current };
+	for (const key of LIVE_DEFAULTS) defaults[key] = context.defaults[key];
+	const resolved = (0, _video_lab_protocol.applyPlayerDefaults)(configProps, defaults);
+	if (frame) {
+		for (const key of [
+			"origin",
+			"iframeVersion",
+			"debug"
+		]) if (resolved[key] === void 0) resolved[key] = initialFrameDefaults.current[key];
+	}
+	const key = JSON.stringify([
+		configProps.locale,
+		context.locale,
+		context.resources,
+		context.messageOverrides,
+		context.fallbackLocales
+	]);
+	if (localeCache.current?.key !== key) localeCache.current = {
+		key,
+		value: (0, _video_lab_protocol.applyProviderLocale)(configProps.locale, context.locale, context.resources, context.messageOverrides, context.fallbackLocales)
+	};
+	resolved.locale = localeCache.current.value;
+	return resolved;
+}
+/** 业务子组件读取翻译并请求切换语言。 */
+function usePlayerI18n() {
+	const context = (0, react.useContext)(Context);
+	if (!context) throw new Error("usePlayerI18n 必须在 PlayerProvider 内使用");
+	const messages = (0, _video_lab_protocol.resolveLocaleMessages)((0, _video_lab_protocol.applyProviderLocale)(void 0, context.locale, context.resources, context.messageOverrides, context.fallbackLocales)).messages;
+	return {
+		locale: context.locale,
+		t: (key) => messages[key] ?? key,
+		changeLanguage: context.changeLanguage
+	};
+}
+//#endregion
+exports.PlayerProvider = PlayerProvider;
+exports.useOptionalPlayerConfig = useOptionalPlayerConfig;
+exports.usePlayerI18n = usePlayerI18n;
+exports.useResolvedPlayerProps = useResolvedPlayerProps;

package/dist/index.d.cts

@@ -0,0 +1,39 @@
+import { FrameDefaults, LocaleConfig, MessageResources, PlayerDefaults } from "@video-lab/protocol";
+import { ReactNode } from "react";
+//#region src/index.d.ts
+interface PlayerProviderProps {
+  children?: ReactNode;
+  locale?: string;
+  defaultLocale?: string;
+  onLocaleChange?: (locale: string) => void;
+  resources?: MessageResources;
+  messageOverrides?: MessageResources;
+  fallbackLocales?: string[];
+  defaults?: PlayerDefaults;
+  frameDefaults?: FrameDefaults;
+}
+interface PlayerConfigContext {
+  locale: string;
+  resources: MessageResources;
+  messageOverrides: MessageResources;
+  fallbackLocales: string[];
+  defaults: PlayerDefaults;
+  frameDefaults: FrameDefaults;
+  changeLanguage(next: string): boolean;
+}
+declare function PlayerProvider(props: PlayerProviderProps): ReactNode;
+/** 播放器组件使用的可选配置；脱离 Provider 时保留原有默认行为。 */
+declare function useOptionalPlayerConfig(): PlayerConfigContext | null;
+/** 构造期默认值固定于首次渲染；语言及已声明的实时字段跟随 Provider。 */
+declare function useResolvedPlayerProps<T extends object>(props: T, frame?: boolean): T & {
+  locale?: LocaleConfig;
+};
+/** 业务子组件读取翻译并请求切换语言。 */
+declare function usePlayerI18n(): {
+  locale: string;
+  t(key: string): string;
+  changeLanguage(next: string): boolean;
+};
+//#endregion
+export { PlayerConfigContext, PlayerProvider, PlayerProviderProps, useOptionalPlayerConfig, usePlayerI18n, useResolvedPlayerProps };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -0,0 +1,39 @@
+import { FrameDefaults, LocaleConfig, MessageResources, PlayerDefaults } from "@video-lab/protocol";
+import { ReactNode } from "react";
+//#region src/index.d.ts
+interface PlayerProviderProps {
+  children?: ReactNode;
+  locale?: string;
+  defaultLocale?: string;
+  onLocaleChange?: (locale: string) => void;
+  resources?: MessageResources;
+  messageOverrides?: MessageResources;
+  fallbackLocales?: string[];
+  defaults?: PlayerDefaults;
+  frameDefaults?: FrameDefaults;
+}
+interface PlayerConfigContext {
+  locale: string;
+  resources: MessageResources;
+  messageOverrides: MessageResources;
+  fallbackLocales: string[];
+  defaults: PlayerDefaults;
+  frameDefaults: FrameDefaults;
+  changeLanguage(next: string): boolean;
+}
+declare function PlayerProvider(props: PlayerProviderProps): ReactNode;
+/** 播放器组件使用的可选配置；脱离 Provider 时保留原有默认行为。 */
+declare function useOptionalPlayerConfig(): PlayerConfigContext | null;
+/** 构造期默认值固定于首次渲染；语言及已声明的实时字段跟随 Provider。 */
+declare function useResolvedPlayerProps<T extends object>(props: T, frame?: boolean): T & {
+  locale?: LocaleConfig;
+};
+/** 业务子组件读取翻译并请求切换语言。 */
+declare function usePlayerI18n(): {
+  locale: string;
+  t(key: string): string;
+  changeLanguage(next: string): boolean;
+};
+//#endregion
+export { PlayerConfigContext, PlayerProvider, PlayerProviderProps, useOptionalPlayerConfig, usePlayerI18n, useResolvedPlayerProps };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,95 @@
+import { applyPlayerDefaults, applyProviderLocale, mergeFrameDefaults, mergeMessageResources, mergePlayerDefaults, normalizeLocaleTag, resolveLocaleMessages } from "@video-lab/protocol";
+import { createContext, useContext, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/index.tsx
+const Context = createContext(null);
+function PlayerProvider(props) {
+	const parent = useContext(Context);
+	const [internalLocale, setInternalLocale] = useState(() => normalizeLocaleTag(props.defaultLocale ?? parent?.locale ?? "zh-CN"));
+	const inheritsLocale = props.locale === void 0 && props.defaultLocale === void 0 && parent !== null;
+	const value = {
+		locale: inheritsLocale ? parent.locale : normalizeLocaleTag(props.locale ?? internalLocale),
+		resources: mergeMessageResources(parent?.resources, props.resources),
+		messageOverrides: mergeMessageResources(parent?.messageOverrides, props.messageOverrides),
+		fallbackLocales: props.fallbackLocales ?? parent?.fallbackLocales ?? [],
+		defaults: mergePlayerDefaults(parent?.defaults, props.defaults),
+		frameDefaults: mergeFrameDefaults(parent?.frameDefaults, props.frameDefaults),
+		changeLanguage(next) {
+			const normalized = normalizeLocaleTag(next);
+			if (inheritsLocale) return parent.changeLanguage(normalized);
+			if (props.locale !== void 0) {
+				if (!props.onLocaleChange) return false;
+				props.onLocaleChange(normalized);
+				return true;
+			}
+			setInternalLocale(normalized);
+			props.onLocaleChange?.(normalized);
+			return true;
+		}
+	};
+	return /* @__PURE__ */ jsx(Context.Provider, {
+		value,
+		children: props.children
+	});
+}
+/** 播放器组件使用的可选配置；脱离 Provider 时保留原有默认行为。 */
+function useOptionalPlayerConfig() {
+	return useContext(Context);
+}
+const LIVE_DEFAULTS = [
+	"muted",
+	"interactive",
+	"showErrorOverlay",
+	"showDefaultLoadingOverlay",
+	"showLoadingText",
+	"errorButtonColors"
+];
+/** 构造期默认值固定于首次渲染；语言及已声明的实时字段跟随 Provider。 */
+function useResolvedPlayerProps(props, frame = false) {
+	const configProps = props;
+	const context = useOptionalPlayerConfig();
+	const initialDefaults = useRef(null);
+	const initialFrameDefaults = useRef(null);
+	const localeCache = useRef(null);
+	if (!context) return props;
+	if (!initialDefaults.current) initialDefaults.current = context.defaults;
+	if (!initialFrameDefaults.current) initialFrameDefaults.current = context.frameDefaults;
+	const defaults = { ...initialDefaults.current };
+	for (const key of LIVE_DEFAULTS) defaults[key] = context.defaults[key];
+	const resolved = applyPlayerDefaults(configProps, defaults);
+	if (frame) {
+		for (const key of [
+			"origin",
+			"iframeVersion",
+			"debug"
+		]) if (resolved[key] === void 0) resolved[key] = initialFrameDefaults.current[key];
+	}
+	const key = JSON.stringify([
+		configProps.locale,
+		context.locale,
+		context.resources,
+		context.messageOverrides,
+		context.fallbackLocales
+	]);
+	if (localeCache.current?.key !== key) localeCache.current = {
+		key,
+		value: applyProviderLocale(configProps.locale, context.locale, context.resources, context.messageOverrides, context.fallbackLocales)
+	};
+	resolved.locale = localeCache.current.value;
+	return resolved;
+}
+/** 业务子组件读取翻译并请求切换语言。 */
+function usePlayerI18n() {
+	const context = useContext(Context);
+	if (!context) throw new Error("usePlayerI18n 必须在 PlayerProvider 内使用");
+	const messages = resolveLocaleMessages(applyProviderLocale(void 0, context.locale, context.resources, context.messageOverrides, context.fallbackLocales)).messages;
+	return {
+		locale: context.locale,
+		t: (key) => messages[key] ?? key,
+		changeLanguage: context.changeLanguage
+	};
+}
+//#endregion
+export { PlayerProvider, useOptionalPlayerConfig, usePlayerI18n, useResolvedPlayerProps };
+
+//# sourceMappingURL=index.mjs.map

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@video-lab/react-config",
+  "version": "4.0.0",
+  "license": "MIT",
+  "description": "Video Lab Player 的 React 全局配置与语言上下文",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": ">=19.0.0"
+  },
+  "dependencies": {
+    "@video-lab/protocol": "4.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.0.0",
+    "@types/react": "^19.2.17",
+    "jsdom": "^24.0.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "tsdown": "^0.22.9",
+    "typescript": "~5.9.0",
+    "vitest": "^4.1.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown src/index.tsx --format esm,cjs --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json --noEmit"
+  }
+}