xxf_react 0.5.7 → 0.5.9

package/dist/layout/hover/XHover.d.ts

@@ -8,15 +8,26 @@ export interface XHoverProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onMou
      */
     children: ReactNode;
     /**
-     * 悬浮延迟时间（毫秒）
+     * 悬浮触发延迟时间（毫秒）
      *
-     * 鼠标悬浮指定时间后才触发 onHover 回调
+     * 鼠标进入后，需要持续悬浮该时间才会触发 onHover 回调和显示 hoverLayer。
+     * - 设为 0 或不设置：鼠标进入立即触发
+     * - 设为正数：鼠标需要停留指定毫秒后才触发
+     *
+     * @example
+     * ```tsx
+     * // 悬浮 2 秒后触发
+     * <XHover hoverDelay={2000} onHover={handleHover}>
+     *
+     * // 立即触发（默认）
+     * <XHover onHover={handleHover}>
+     * ```
      *
      * @default 0
      */
-    delay?: number;
+    hoverDelay?: number;
     /**
-     * 鼠标进入时立即触发的回调（不等待 delay）
+     * 鼠标进入时立即触发的回调（不等待 hoverDelay）
      *
      * 适用于需要在鼠标进入时立即做一些事情的场景，如显示边框高亮等
      */
@@ -24,7 +35,7 @@ export interface XHoverProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onMou
     /**
      * 悬浮回调
      *
-     * 当鼠标悬浮达到 delay 时间后触发
+     * 当鼠标悬浮达到 hoverDelay 时间后触发
      */
     onHover?: () => void;
     /**
@@ -36,13 +47,13 @@ export interface XHoverProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onMou
     /**
      * 悬浮覆盖层
      *
-     * 当悬浮触发（达到 delay 时间）后，显示在 children 上方的内容。
+     * 当悬浮触发（达到 hoverDelay 时间）后，显示在 children 上方的内容。
      * 鼠标离开后自动隐藏。
      *
      * @example
      * ```tsx
      * <XHover
-     *   delay={1000}
+     *   hoverDelay={1000}
      *   hoverLayer={() => (
      *     <div className="absolute inset-0 bg-black/50 flex items-center justify-center">
      *       <span className="text-white">悬浮提示</span>
@@ -75,7 +86,7 @@ export interface XHoverProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onMou
  * @example
  * ```tsx
  * // 基础用法：鼠标悬浮 2 秒后触发
- * <XHover delay={2000} onHover={() => console.log('悬浮触发')}>
+ * <XHover hoverDelay={2000} onHover={() => console.log('悬浮触发')}>
  *   <div>悬浮我</div>
  * </XHover>
  *
@@ -86,7 +97,7 @@ export interface XHoverProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onMou
  *
  * // 带离开回调，判断是否触发过
  * <XHover
- *   delay={1000}
+ *   hoverDelay={1000}
  *   onHover={() => setShowTooltip(true)}
  *   onLeave={(triggered) => {
  *     if (triggered) setShowTooltip(false)
@@ -97,7 +108,7 @@ export interface XHoverProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onMou
  *
  * // 使用 hoverLayer 显示悬浮覆盖层
  * <XHover
- *   delay={1000}
+ *   hoverDelay={1000}
  *   hoverLayer={() => (
  *     <div className="absolute inset-0 bg-black/50 flex items-center justify-center">
  *       <PlayIcon className="text-white w-12 h-12" />
@@ -108,18 +119,18 @@ export interface XHoverProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onMou
  * </XHover>
  *
  * // 使用 span 作为容器（适用于 inline 场景）
- * <XHover as="span" delay={500} onHover={handleHover}>
+ * <XHover as="span" hoverDelay={500} onHover={handleHover}>
  *   <span>inline 文本</span>
  * </XHover>
  *
  * // 禁用状态
- * <XHover disabled={isLoading} delay={1000} onHover={handleHover}>
+ * <XHover disabled={isLoading} hoverDelay={1000} onHover={handleHover}>
  *   <div>内容</div>
  * </XHover>
  *
  * // 使用 onEnter 立即响应 + onHover 延迟响应
  * <XHover
- *   delay={1000}
+ *   hoverDelay={1000}
  *   onEnter={() => setHighlight(true)}
  *   onHover={() => setShowDetail(true)}
  *   onLeave={() => {
@@ -131,6 +142,6 @@ export interface XHoverProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onMou
  * </XHover>
  * ```
  */
-export declare function XHover({ children, delay, onEnter, onHover, onLeave, hoverLayer, disabled, as: Component, style, ...rest }: XHoverProps): React.JSX.Element;
+export declare function XHover({ children, hoverDelay, onEnter, onHover, onLeave, hoverLayer, disabled, as: Component, style, ...rest }: XHoverProps): React.JSX.Element;
 export default XHover;
 //# sourceMappingURL=XHover.d.ts.map

package/dist/layout/hover/XHover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"XHover.d.ts","sourceRoot":"","sources":["../../../src/layout/hover/XHover.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAA2C,SAAS,EAAE,cAAc,EAAC,MAAM,OAAO,CAAA;AAEhG;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,cAAc,GAAG,cAAc,CAAC;IACtG;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAA;IAEnB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IAEpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IAEpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,CAAA;IAEtC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,UAAU,CAAC,EAAE,MAAM,SAAS,CAAA;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAElB;;;;OAIG;IACH,EAAE,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,wBAAgB,MAAM,CAAC,EACI,QAAQ,EACR,KAAS,EACT,OAAO,EACP,OAAO,EACP,OAAO,EACP,UAAU,EACV,QAAgB,EAChB,EAAE,EAAE,SAAiB,EACrB,KAAK,EACL,GAAG,IAAI,EACV,EAAE,WAAW,qBA0EpC;AAED,eAAe,MAAM,CAAA"}
+{"version":3,"file":"XHover.d.ts","sourceRoot":"","sources":["../../../src/layout/hover/XHover.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAA2C,SAAS,EAAE,cAAc,EAAC,MAAM,OAAO,CAAA;AAEhG;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,cAAc,GAAG,cAAc,CAAC;IACtG;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAA;IAEnB;;;;;;;;;;;;;;;;;OAiBG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IAEpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IAEpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,CAAA;IAEtC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,UAAU,CAAC,EAAE,MAAM,SAAS,CAAA;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAElB;;;;OAIG;IACH,EAAE,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,wBAAgB,MAAM,CAAC,EACnB,QAAQ,EACR,UAAc,EACd,OAAO,EACP,OAAO,EACP,OAAO,EACP,UAAU,EACV,QAAgB,EAChB,EAAE,EAAE,SAAiB,EACrB,KAAK,EACL,GAAG,IAAI,EACV,EAAE,WAAW,qBA0Eb;AAED,eAAe,MAAM,CAAA"}

package/dist/layout/hover/XHover.js

@@ -7,7 +7,7 @@ import React, { useCallback, useRef, useEffect, useState } from 'react';
  * @example
  * ```tsx
  * // 基础用法：鼠标悬浮 2 秒后触发
- * <XHover delay={2000} onHover={() => console.log('悬浮触发')}>
+ * <XHover hoverDelay={2000} onHover={() => console.log('悬浮触发')}>
  *   <div>悬浮我</div>
  * </XHover>
  *
@@ -18,7 +18,7 @@ import React, { useCallback, useRef, useEffect, useState } from 'react';
  *
  * // 带离开回调，判断是否触发过
  * <XHover
- *   delay={1000}
+ *   hoverDelay={1000}
  *   onHover={() => setShowTooltip(true)}
  *   onLeave={(triggered) => {
  *     if (triggered) setShowTooltip(false)
@@ -29,7 +29,7 @@ import React, { useCallback, useRef, useEffect, useState } from 'react';
  *
  * // 使用 hoverLayer 显示悬浮覆盖层
  * <XHover
- *   delay={1000}
+ *   hoverDelay={1000}
  *   hoverLayer={() => (
  *     <div className="absolute inset-0 bg-black/50 flex items-center justify-center">
  *       <PlayIcon className="text-white w-12 h-12" />
@@ -40,18 +40,18 @@ import React, { useCallback, useRef, useEffect, useState } from 'react';
  * </XHover>
  *
  * // 使用 span 作为容器（适用于 inline 场景）
- * <XHover as="span" delay={500} onHover={handleHover}>
+ * <XHover as="span" hoverDelay={500} onHover={handleHover}>
  *   <span>inline 文本</span>
  * </XHover>
  *
  * // 禁用状态
- * <XHover disabled={isLoading} delay={1000} onHover={handleHover}>
+ * <XHover disabled={isLoading} hoverDelay={1000} onHover={handleHover}>
  *   <div>内容</div>
  * </XHover>
  *
  * // 使用 onEnter 立即响应 + onHover 延迟响应
  * <XHover
- *   delay={1000}
+ *   hoverDelay={1000}
  *   onEnter={() => setHighlight(true)}
  *   onHover={() => setShowDetail(true)}
  *   onLeave={() => {
@@ -63,7 +63,7 @@ import React, { useCallback, useRef, useEffect, useState } from 'react';
  * </XHover>
  * ```
  */
-export function XHover({ children, delay = 0, onEnter, onHover, onLeave, hoverLayer, disabled = false, as: Component = 'div', style, ...rest }) {
+export function XHover({ children, hoverDelay = 0, onEnter, onHover, onLeave, hoverLayer, disabled = false, as: Component = 'div', style, ...rest }) {
     const timerRef = useRef(null);
     const hasTriggeredRef = useRef(false);
     // 只有 hoverLayer 存在时才需要状态
@@ -94,7 +94,7 @@ export function XHover({ children, delay = 0, onEnter, onHover, onLeave, hoverLa
         clearTimer();
         // 立即触发 onEnter
         onEnter === null || onEnter === void 0 ? void 0 : onEnter();
-        if (delay <= 0) {
+        if (hoverDelay <= 0) {
             hasTriggeredRef.current = true;
             if (hoverLayer)
                 setShowLayer(true);
@@ -106,9 +106,9 @@ export function XHover({ children, delay = 0, onEnter, onHover, onLeave, hoverLa
                 if (hoverLayer)
                     setShowLayer(true);
                 onHover === null || onHover === void 0 ? void 0 : onHover();
-            }, delay);
+            }, hoverDelay);
         }
-    }, [delay, onEnter, onHover, clearTimer, disabled, hoverLayer]);
+    }, [hoverDelay, onEnter, onHover, clearTimer, disabled, hoverLayer]);
     const handleMouseLeave = useCallback(() => {
         if (disabled)
             return;

package/dist/media/components/XVideo.d.ts

@@ -0,0 +1,176 @@
+import React, { ReactNode, VideoHTMLAttributes, RefObject } from 'react';
+/**
+ * XVideo 组件 Props
+ *
+ * 继承自原生 video 元素的所有属性（除了 poster，因为使用自定义实现）
+ * 支持 autoPlay、muted、loop、controls 等所有原生 video 属性
+ *
+ * @example
+ * ```tsx
+ * <XVideo
+ *   src={videoUrl}
+ *   poster={coverUrl}
+ *   autoPlay
+ *   muted
+ *   loop
+ * />
+ * ```
+ */
+export interface XVideoProps extends Omit<VideoHTMLAttributes<HTMLVideoElement>, 'poster'> {
+    /**
+     * 视频源 URL
+     *
+     * - 必填项
+     * - 支持任意视频格式（mp4、webm、ogg 等）
+     * - 如果为空字符串/null/undefined，只显示封面
+     * - src 变化时会自动重置组件状态
+     */
+    src: string;
+    /**
+     * 封面（可选）
+     *
+     * 支持两种类型：
+     * - string: 图片 URL，内部使用 XImage 组件渲染，自动处理懒加载和优化
+     * - ReactNode: 自定义封面组件，可完全控制封面渲染逻辑
+     *
+     * 封面会在视频第一帧渲染完成后淡出隐藏，解决原生 poster 闪烁问题
+     *
+     * @example
+     * ```tsx
+     * // 使用图片 URL
+     * <XVideo src={videoUrl} poster="https://example.com/cover.jpg" />
+     *
+     * // 使用自定义组件
+     * <XVideo src={videoUrl} poster={<CustomCover />} />
+     * ```
+     */
+    poster?: string | ReactNode;
+    /**
+     * 封面淡出动画时长（毫秒）
+     *
+     * - 默认值: 300ms
+     * - 视频第一帧渲染后，封面会以此时长淡出
+     * - 淡出完成后封面 DOM 会被移除，节省内存
+     * - 设为 0 可禁用淡出动画
+     */
+    posterFadeOutDuration?: number;
+    /**
+     * 缓冲指示器组件（可选）
+     *
+     * - 视频就绪后，如果播放中出现缓冲（网络慢、seek 等），显示此组件
+     * - 不传则使用默认的 loading spinner
+     * - 传 null 可禁用缓冲指示器
+     *
+     * @example
+     * ```tsx
+     * // 使用自定义缓冲指示器
+     * <XVideo
+     *   src={videoUrl}
+     *   bufferingIndicator={<MyCustomLoader />}
+     * />
+     *
+     * // 禁用缓冲指示器
+     * <XVideo src={videoUrl} bufferingIndicator={null} />
+     * ```
+     */
+    bufferingIndicator?: ReactNode;
+    /**
+     * 容器 className（可选）
+     *
+     * - 应用于最外层 div 容器
+     * - 容器默认带有 relative overflow-hidden
+     * - 可用于设置宽高、圆角等样式
+     *
+     * @example
+     * ```tsx
+     * <XVideo
+     *   src={videoUrl}
+     *   className="w-full aspect-video rounded-lg"
+     * />
+     * ```
+     */
+    className?: string;
+    /**
+     * 外部传入的 video 元素 ref（可选）
+     *
+     * - 如果传入，组件使用该 ref，外部可直接访问 video 元素
+     * - 如果不传，组件内部创建 ref
+     * - 外部可通过 useVideoState(videoRef) 获取视频状态（buffering、error、currentTime 等）
+     * - 外部可通过 videoRef.current 直接控制视频（play、pause、seek 等）
+     *
+     * @example
+     * ```tsx
+     * const videoRef = useRef<HTMLVideoElement>(null)
+     * const { playState } = useVideoState(videoRef)
+     *
+     * // 外部控制播放
+     * const handlePlay = () => videoRef.current?.play()
+     *
+     * // 监听状态
+     * console.log(playState.buffering, playState.currentTime)
+     *
+     * <XVideo src={videoUrl} videoRef={videoRef} />
+     * ```
+     */
+    videoRef?: RefObject<HTMLVideoElement | null>;
+    /**
+     * 就绪回调（第一帧渲染完成时触发）
+     *
+     * - 这是 XVideo 独有的能力，原生 video 和 useVideoState 无法提供
+     * - 仅在第一帧实际渲染到屏幕后触发，不是 canplay 事件
+     * - src 变化后会重新触发
+     * - 每次 src 最多触发一次
+     *
+     * 触发时机：
+     * 1. 优先使用 requestVideoFrameCallback（精确检测第一帧渲染）
+     * 2. 回退方案：currentTime > 0（兼容不支持的浏览器）
+     *
+     * @example
+     * ```tsx
+     * <XVideo
+     *   src={videoUrl}
+     *   onReady={() => console.log('第一帧已渲染，可以隐藏骨架屏')}
+     * />
+     * ```
+     */
+    onReady?: () => void;
+}
+/**
+ * XVideo - 通用视频组件
+ *
+ * 解决原生 video poster 的闪烁问题：原生 poster 会在视频开始播放时立即消失，
+ * 但此时第一帧可能还未渲染，导致短暂黑屏闪烁。
+ *
+ * 核心原理：
+ * 1. 使用自定义封面层覆盖在 video 上方
+ * 2. 通过 requestVideoFrameCallback 精确检测第一帧渲染时机
+ * 3. 第一帧渲染后才开始淡出封面，确保无缝过渡
+ *
+ * 特性：
+ * - 支持自定义封面（string URL 或 ReactNode 组件）
+ * - 使用 requestVideoFrameCallback 精确检测第一帧渲染（兼容 currentTime 回退）
+ * - 使用 useVideoState 统一管理视频状态
+ * - 支持外部传入 videoRef，方便外部监听和控制
+ * - 封面淡出动画，可自定义时长
+ * - 继承原生 video 所有属性
+ *
+ * 浏览器兼容性：
+ * - requestVideoFrameCallback: Chrome 83+, Edge 83+, Opera 69+
+ * - 不支持的浏览器自动回退到 currentTime > 0 检测
+ *
+ * @example
+ * ```tsx
+ * // 基础用法
+ * <XVideo src={videoUrl} poster={coverUrl} autoPlay muted />
+ *
+ * // 自定义封面组件
+ * <XVideo src={videoUrl} poster={<CustomCover />} autoPlay muted />
+ *
+ * // 外部控制
+ * const videoRef = useRef<HTMLVideoElement>(null)
+ * const { playState } = useVideoState(videoRef)
+ * <XVideo src={videoUrl} videoRef={videoRef} poster={coverUrl} />
+ * ```
+ */
+export declare function XVideo({ src, poster, posterFadeOutDuration, bufferingIndicator, className, videoRef: externalVideoRef, onReady, preload, playsInline, crossOrigin, ...videoProps }: XVideoProps): React.JSX.Element;
+//# sourceMappingURL=XVideo.d.ts.map

package/dist/media/components/XVideo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"XVideo.d.ts","sourceRoot":"","sources":["../../../src/media/components/XVideo.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,EAMV,SAAS,EACT,mBAAmB,EACnB,SAAS,EACZ,MAAM,OAAO,CAAA;AAKd;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,EAAE,QAAQ,CAAC;IACtF;;;;;;;OAOG;IACH,GAAG,EAAE,MAAM,CAAA;IAEX;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAE3B;;;;;;;OAOG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAE9B;;;;;;;;;;;;;;;;;;OAkBG;IACH,kBAAkB,CAAC,EAAE,SAAS,CAAA;IAE9B;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAA;IAE7C;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;CACvB;AAgBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,MAAM,CAAC,EACI,GAAG,EACH,MAAM,EACN,qBAA2B,EAC3B,kBAAkB,EAClB,SAAS,EACT,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EACP,OAAgB,EAChB,WAAkB,EAClB,WAAyB,EACzB,GAAG,UAAU,EAChB,EAAE,WAAW,qBA6TpC"}

package/dist/media/components/XVideo.js

@@ -0,0 +1,269 @@
+'use client';
+import React, { useRef, useState, useEffect, useCallback, useMemo, } from 'react';
+import { cn } from 'tailwind-variants';
+import { XImage } from 'xxf_react';
+import { useVideoState } from 'xxf_react/media';
+/**
+ * 默认缓冲指示器组件
+ *
+ * 显示一个居中的旋转 loading spinner
+ * 使用 React.memo 优化，避免不必要的重渲染
+ */
+const DefaultBufferingIndicator = React.memo(function DefaultBufferingIndicator() {
+    return (React.createElement("div", { className: "absolute inset-0 flex items-center justify-center pointer-events-none" },
+        React.createElement("div", { className: "w-8 h-8 border-4 border-white/30 border-t-white rounded-full animate-spin" })));
+});
+/**
+ * XVideo - 通用视频组件
+ *
+ * 解决原生 video poster 的闪烁问题：原生 poster 会在视频开始播放时立即消失，
+ * 但此时第一帧可能还未渲染，导致短暂黑屏闪烁。
+ *
+ * 核心原理：
+ * 1. 使用自定义封面层覆盖在 video 上方
+ * 2. 通过 requestVideoFrameCallback 精确检测第一帧渲染时机
+ * 3. 第一帧渲染后才开始淡出封面，确保无缝过渡
+ *
+ * 特性：
+ * - 支持自定义封面（string URL 或 ReactNode 组件）
+ * - 使用 requestVideoFrameCallback 精确检测第一帧渲染（兼容 currentTime 回退）
+ * - 使用 useVideoState 统一管理视频状态
+ * - 支持外部传入 videoRef，方便外部监听和控制
+ * - 封面淡出动画，可自定义时长
+ * - 继承原生 video 所有属性
+ *
+ * 浏览器兼容性：
+ * - requestVideoFrameCallback: Chrome 83+, Edge 83+, Opera 69+
+ * - 不支持的浏览器自动回退到 currentTime > 0 检测
+ *
+ * @example
+ * ```tsx
+ * // 基础用法
+ * <XVideo src={videoUrl} poster={coverUrl} autoPlay muted />
+ *
+ * // 自定义封面组件
+ * <XVideo src={videoUrl} poster={<CustomCover />} autoPlay muted />
+ *
+ * // 外部控制
+ * const videoRef = useRef<HTMLVideoElement>(null)
+ * const { playState } = useVideoState(videoRef)
+ * <XVideo src={videoUrl} videoRef={videoRef} poster={coverUrl} />
+ * ```
+ */
+export function XVideo({ src, poster, posterFadeOutDuration = 300, bufferingIndicator, className, videoRef: externalVideoRef, onReady, preload = 'auto', playsInline = true, crossOrigin = "anonymous", ...videoProps }) {
+    // ==================== Refs ====================
+    /**
+     * 内部 video ref
+     * 如果外部传入了 videoRef，则使用外部的；否则使用内部创建的
+     */
+    const internalVideoRef = useRef(null);
+    const videoRef = externalVideoRef !== null && externalVideoRef !== void 0 ? externalVideoRef : internalVideoRef;
+    // ==================== 外部 Hooks ====================
+    /**
+     * 使用 useVideoState 统一管理视频状态
+     * 提供 canPlay、buffering、currentTime、error 等状态
+     */
+    const { playState } = useVideoState(videoRef);
+    // ==================== 内部状态 ====================
+    /**
+     * 视频是否已就绪（第一帧已渲染）
+     * true: 开始淡出封面
+     * false: 显示封面
+     */
+    const [isReady, setIsReady] = useState(false);
+    /**
+     * 是否显示封面 DOM
+     * 淡出动画完成后设为 false，移除封面 DOM 节省内存
+     */
+    const [showPoster, setShowPoster] = useState(true);
+    // ==================== 内部 Refs ====================
+    /** 第一帧是否已渲染（通过 requestVideoFrameCallback 或 currentTime 检测） */
+    const firstFrameRenderedRef = useRef(false);
+    /** onReady 回调是否已调用（防止重复调用） */
+    const hasCalledOnReadyRef = useRef(false);
+    /** 封面淡出定时器引用（用于清理，防止内存泄漏） */
+    const fadeOutTimerRef = useRef(null);
+    /**
+     * onReady 回调的 ref
+     * 使用 ref 模式存储回调，避免 onReady 变化时触发 effect 重新执行
+     * 这是 React 中处理回调依赖的常用模式
+     */
+    const onReadyRef = useRef(onReady);
+    onReadyRef.current = onReady;
+    // ==================== 核心逻辑 ====================
+    /**
+     * 检查并更新就绪状态
+     *
+     * 触发条件：
+     * 1. canPlay 为 true（视频数据已加载足够播放）
+     * 2. firstFrameRendered 为 true（第一帧已渲染到屏幕）
+     * 3. isReady 为 false（尚未标记为就绪，防止重复执行）
+     *
+     * 执行动作：
+     * 1. 设置 isReady = true，触发封面淡出动画
+     * 2. 调用 onReady 回调（仅一次）
+     * 3. 启动定时器，淡出动画完成后移除封面 DOM
+     */
+    const checkAndSetReady = useCallback(() => {
+        var _a;
+        if (playState.canPlay && firstFrameRenderedRef.current && !isReady) {
+            setIsReady(true);
+            // 通知外部（确保只调用一次）
+            if (!hasCalledOnReadyRef.current) {
+                hasCalledOnReadyRef.current = true;
+                (_a = onReadyRef.current) === null || _a === void 0 ? void 0 : _a.call(onReadyRef);
+            }
+            // 延迟隐藏封面，等待 CSS 淡出动画完成后再移除 DOM
+            fadeOutTimerRef.current = setTimeout(() => {
+                setShowPoster(false);
+            }, posterFadeOutDuration);
+        }
+    }, [playState.canPlay, isReady, posterFadeOutDuration]);
+    /**
+     * 重置组件状态
+     *
+     * 调用时机：src 变化时
+     * 确保切换视频源时组件状态正确重置
+     */
+    const resetState = useCallback(() => {
+        // 清理定时器，防止内存泄漏
+        if (fadeOutTimerRef.current) {
+            clearTimeout(fadeOutTimerRef.current);
+            fadeOutTimerRef.current = null;
+        }
+        // 重置所有标记和状态
+        firstFrameRenderedRef.current = false;
+        hasCalledOnReadyRef.current = false;
+        setIsReady(false);
+        setShowPoster(true);
+    }, []);
+    // ==================== Effects ====================
+    /**
+     * Effect: 组件卸载清理
+     * 清理 fadeOut 定时器，防止组件卸载后更新状态导致内存泄漏
+     */
+    useEffect(() => {
+        return () => {
+            if (fadeOutTimerRef.current) {
+                clearTimeout(fadeOutTimerRef.current);
+            }
+        };
+    }, []);
+    /**
+     * Effect: src 变化时重置状态
+     * 确保切换视频时封面重新显示，状态正确初始化
+     */
+    useEffect(() => {
+        resetState();
+    }, [src, resetState]);
+    /**
+     * Effect: 监听 canPlay 状态变化
+     * 当视频可以播放时，检查是否可以标记为就绪
+     */
+    useEffect(() => {
+        checkAndSetReady();
+    }, [playState.canPlay, checkAndSetReady]);
+    /**
+     * Effect: 通过 currentTime 检测第一帧（回退方案）
+     *
+     * 对于不支持 requestVideoFrameCallback 的浏览器（Safari、Firefox），
+     * 使用 currentTime > 0 作为第一帧渲染的近似检测
+     *
+     * 原理：currentTime > 0 表示视频已开始播放，此时第一帧大概率已渲染
+     */
+    useEffect(() => {
+        if (!firstFrameRenderedRef.current && playState.currentTime > 0) {
+            firstFrameRenderedRef.current = true;
+            checkAndSetReady();
+        }
+    }, [playState.currentTime, checkAndSetReady]);
+    /**
+     * Effect: 第一帧检测 - 优先使用 requestVideoFrameCallback
+     *
+     * requestVideoFrameCallback 是浏览器提供的 API，在视频帧实际渲染到屏幕时触发
+     * 比 canplay、timeupdate 等事件更精确
+     *
+     * 工作流程：
+     * 1. 检查浏览器是否支持 requestVideoFrameCallback
+     * 2. 如果支持，注册回调等待第一帧渲染
+     * 3. 第一帧渲染时标记 firstFrameRendered 并检查就绪状态
+     * 4. cleanup 时取消回调，防止组件卸载后执行
+     *
+     * 注意：cleanedUp flag 用于防止组件卸载后的状态更新（React 严格模式下的竞态条件）
+     */
+    useEffect(() => {
+        const video = videoRef.current;
+        if (!video)
+            return;
+        // 如果已经检测到第一帧，无需重复检测
+        if (firstFrameRenderedRef.current)
+            return;
+        // 检查浏览器是否支持 requestVideoFrameCallback
+        const supportsVideoFrameCallback = 'requestVideoFrameCallback' in HTMLVideoElement.prototype;
+        if (supportsVideoFrameCallback) {
+            // 用于防止组件卸载后的回调执行
+            let cleanedUp = false;
+            // 注册第一帧渲染回调
+            const videoFrameCallbackId = video.requestVideoFrameCallback(() => {
+                // 双重检查：确保组件未卸载且第一帧未被其他方式检测到
+                if (!firstFrameRenderedRef.current && !cleanedUp) {
+                    firstFrameRenderedRef.current = true;
+                    checkAndSetReady();
+                }
+            });
+            // cleanup: 取消回调，防止内存泄漏和卸载后状态更新
+            return () => {
+                cleanedUp = true;
+                video.cancelVideoFrameCallback(videoFrameCallbackId);
+            };
+        }
+        // 不支持 requestVideoFrameCallback 的浏览器由 currentTime effect 处理
+    }, [src, videoRef, checkAndSetReady]);
+    // ==================== 渲染逻辑 ====================
+    /**
+     * 封面元素 - 使用 useMemo 优化
+     *
+     * 根据 poster 类型决定渲染方式：
+     * - string: 使用 XImage 渲染，自动处理懒加载和图片优化
+     * - ReactNode: 直接渲染用户传入的组件
+     * - undefined/null: 返回 null，不渲染封面
+     */
+    const posterElement = useMemo(() => {
+        if (!poster)
+            return null;
+        // string 类型：图片 URL，使用 XImage 渲染
+        if (typeof poster === 'string') {
+            return (React.createElement(XImage, { src: poster, alt: "", fill: true, className: "object-cover", sizes: "(max-width: 640px) 100vw, 50vw" }));
+        }
+        // ReactNode 类型：直接渲染用户传入的组件
+        return poster;
+    }, [poster]);
+    // ==================== 渲染 ====================
+    /**
+     * 边界情况：src 为空
+     * 只渲染容器和封面，不渲染 video 元素
+     */
+    if (!src) {
+        return (React.createElement("div", { className: cn('relative overflow-hidden', className) }, posterElement));
+    }
+    /**
+     * 主渲染结构：
+     *
+     * ┌─────────────────────────────────┐
+     * │ Container (relative)            │
+     * │ ┌─────────────────────────────┐ │
+     * │ │ Video (底层)                │ │
+     * │ └─────────────────────────────┘ │
+     * │ ┌─────────────────────────────┐ │
+     * │ │ Poster (覆盖层，淡出后移除) │ │
+     * │ └─────────────────────────────┘ │
+     * │ ┌─────────────────────────────┐ │
+     * │ │ BufferingIndicator (按需)   │ │
+     * │ └─────────────────────────────┘ │
+     * └─────────────────────────────────┘
+     */
+    return (React.createElement("div", { className: cn('relative overflow-hidden', className) },
+        React.createElement("video", { ref: videoRef, src: src, preload: preload, crossOrigin: crossOrigin, playsInline: playsInline, className: "w-full h-full object-cover", ...videoProps }),
+        posterElement && showPoster && (React.createElement("div", { className: cn('absolute inset-0 transition-opacity', isReady ? 'opacity-0 pointer-events-none' : 'opacity-100'), style: { transitionDuration: `${posterFadeOutDuration}ms` } }, posterElement)),
+        isReady && playState.buffering && (bufferingIndicator !== null && bufferingIndicator !== void 0 ? bufferingIndicator : React.createElement(DefaultBufferingIndicator, null))));
+}

package/dist/media/index.d.ts

@@ -1,3 +1,4 @@
 export * from './video-state';
 export * from './playback-queue-store';
+export * from './components/XVideo';
 //# sourceMappingURL=index.d.ts.map

package/dist/media/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/media/index.ts"],"names":[],"mappings":"AAEA,cAAc,eAAe,CAAC;AAC9B,cAAc,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/media/index.ts"],"names":[],"mappings":"AAEA,cAAc,eAAe,CAAC;AAC9B,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC"}

package/dist/media/index.js

@@ -1,3 +1,4 @@
 'use client';
 export * from './video-state';
 export * from './playback-queue-store';
+export * from './components/XVideo';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xxf_react",
-  "version": "0.5.7",
+  "version": "0.5.9",
   "private": false,
   "type": "module",
   "main": "dist/index.js",