xxf_react 0.8.3 → 0.8.5

package/dist/layout/resize/core/ResizeObserverHook.js

@@ -1,57 +0,0 @@
-import { useState, useEffect, useRef } from 'react';
-/**
- * 基于 ResizeObserver 监听容器尺寸变化
- *
- * @example
- * ```tsx
- * const { containerRef, containerWidth, containerHeight, isContainerReady } = useResizeObserver();
- *
- * return (
- *   <div ref={containerRef}>
- *     {isContainerReady && <Chart width={containerWidth} height={containerHeight} />}
- *   </div>
- * );
- * ```
- *
- * @example
- * ```tsx
- * // 带防抖
- * const { containerRef, containerHeight } = useResizeObserver({ debounce: 100 });
- * ```
- */
-export function useResizeObserver(options = {}) {
-    const { debounce = 0, initialSize = { width: 0, height: 0 } } = options;
-    const containerRef = useRef(null);
-    const [size, setSize] = useState(initialSize);
-    const timeoutRef = useRef(null);
-    useEffect(() => {
-        const element = containerRef.current;
-        if (!element)
-            return;
-        const updateSize = (entries) => {
-            var _a, _b;
-            const { width, height } = (_b = (_a = entries[0]) === null || _a === void 0 ? void 0 : _a.contentRect) !== null && _b !== void 0 ? _b : { width: 0, height: 0 };
-            if (debounce > 0) {
-                if (timeoutRef.current)
-                    clearTimeout(timeoutRef.current);
-                timeoutRef.current = setTimeout(() => setSize({ width, height }), debounce);
-            }
-            else {
-                setSize({ width, height });
-            }
-        };
-        const observer = new ResizeObserver(updateSize);
-        observer.observe(element);
-        return () => {
-            observer.disconnect();
-            if (timeoutRef.current)
-                clearTimeout(timeoutRef.current);
-        };
-    }, [debounce]);
-    return {
-        containerRef,
-        containerWidth: size.width,
-        containerHeight: size.height,
-        isContainerReady: size.width > 0 && size.height > 0,
-    };
-}

package/dist/layout/resize/core/SizedLayoutContext.d.ts

@@ -1,23 +0,0 @@
-import { LayoutSize } from "../../../foundation/LayoutSize";
-/** Context 中的尺寸状态 */
-export interface SizedLayoutContextValue extends LayoutSize {
-    /** 是否已获取到有效尺寸 */
-    isReady: boolean;
-}
-export declare const SizedLayoutContext: import("react").Context<SizedLayoutContextValue | null>;
-/**
- * 获取父级容器（SizedLayout 或 SizedContainer）的尺寸
- *
- * @throws 如果不在 SizedLayout 或 SizedContainer 内部使用会抛出错误
- *
- * @example
- * ```tsx
- * function ChildComponent() {
- *   const { width, height, isReady } = useContextLayoutSize();
- *   if (!isReady) return <Loading />;
- *   return <div style={{ width, height }}>...</div>;
- * }
- * ```
- */
-export declare function useContextLayoutSize(): SizedLayoutContextValue;
-//# sourceMappingURL=SizedLayoutContext.d.ts.map

package/dist/layout/resize/core/SizedLayoutContext.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"SizedLayoutContext.d.ts","sourceRoot":"","sources":["../../../../src/layout/resize/core/SizedLayoutContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAC,MAAM,gCAAgC,CAAC;AAG1D,qBAAqB;AACrB,MAAM,WAAW,uBAAwB,SAAQ,UAAU;IACvD,iBAAiB;IACjB,OAAO,EAAE,OAAO,CAAC;CACpB;AAED,eAAO,MAAM,kBAAkB,yDAAsD,CAAC;AAEtF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,IAAI,uBAAuB,CAM9D"}

package/dist/layout/resize/core/SizedLayoutContext.js

@@ -1,23 +0,0 @@
-import { createContext, useContext } from "react";
-export const SizedLayoutContext = createContext(null);
-/**
- * 获取父级容器（SizedLayout 或 SizedContainer）的尺寸
- *
- * @throws 如果不在 SizedLayout 或 SizedContainer 内部使用会抛出错误
- *
- * @example
- * ```tsx
- * function ChildComponent() {
- *   const { width, height, isReady } = useContextLayoutSize();
- *   if (!isReady) return <Loading />;
- *   return <div style={{ width, height }}>...</div>;
- * }
- * ```
- */
-export function useContextLayoutSize() {
-    const context = useContext(SizedLayoutContext);
-    if (!context) {
-        throw new Error('useContextLayoutSize must be used within a SizedLayout or SizedContainer');
-    }
-    return context;
-}

package/dist/layout/resize/core/SizedLayoutProps.d.ts

@@ -1,19 +0,0 @@
-import { CSSProperties, ElementType, ReactNode } from "react";
-import { LayoutSize } from "../../../foundation/LayoutSize";
-export interface SizedLayoutProps {
-    /** 子元素 */
-    children: ReactNode;
-    /** 容器的 className */
-    className?: string;
-    /** 容器的 style */
-    style?: CSSProperties;
-    /** 自定义容器元素类型，默认 div */
-    as?: ElementType;
-    /** 防抖延迟（毫秒） */
-    debounce?: number;
-    /** 尺寸未就绪时显示的占位内容 */
-    fallback?: ReactNode;
-    /** 尺寸变化时的回调 */
-    onResize?: (size: LayoutSize) => void;
-}
-//# sourceMappingURL=SizedLayoutProps.d.ts.map

package/dist/layout/resize/core/SizedLayoutProps.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"SizedLayoutProps.d.ts","sourceRoot":"","sources":["../../../../src/layout/resize/core/SizedLayoutProps.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,aAAa,EAAE,WAAW,EAAE,SAAS,EAAC,MAAM,OAAO,CAAC;AAC5D,OAAO,EAAC,UAAU,EAAC,MAAM,gCAAgC,CAAC;AAE1D,MAAM,WAAW,gBAAgB;IAC7B,UAAU;IACV,QAAQ,EAAE,SAAS,CAAC;IACpB,oBAAoB;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB;IAChB,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,uBAAuB;IACvB,EAAE,CAAC,EAAE,WAAW,CAAC;IACjB,eAAe;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oBAAoB;IACpB,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,eAAe;IACf,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;CACzC"}

package/dist/layout/resize/core/SizedLayoutProps.js

@@ -1 +0,0 @@
-export {};

package/dist/layout/resize/impl/SizedContainer.d.ts

@@ -1,45 +0,0 @@
-import React from "react";
-import { SizedLayoutProps } from "../core/SizedLayoutProps";
-/**
- * 自动测量尺寸的容器组件（基于 react-resize-detector）
- *
- * 子组件通过 useContextLayoutSize() 获取容器尺寸，适用于需要根据父容器尺寸
- * 进行布局的场景（如虚拟列表、图表、Canvas 等）。
- *
- * @example
- * ```tsx
- * // 基础用法
- * <SizedContainer className="h-full w-full">
- *   <ChartComponent />
- * </SizedContainer>
- *
- * // ChartComponent 内部
- * function ChartComponent() {
- *   const { width, height, isReady } = useContextLayoutSize();
- *   if (!isReady) return <Skeleton />;
- *   return <Chart width={width} height={height} />;
- * }
- * ```
- *
- * @example
- * ```tsx
- * // 带 fallback 的用法
- * <SizedContainer fallback={<Loading />} className="h-full">
- *   <VirtualList />
- * </SizedContainer>
- * ```
- *
- * @example
- * ```tsx
- * // 自定义元素类型 + 尺寸变化回调
- * <SizedContainer
- *   as="section"
- *   debounce={100}
- *   onResize={({ width, height }) => console.log(width, height)}
- * >
- *   <Content />
- * </SizedContainer>
- * ```
- */
-export declare function SizedContainer({ children, className, style, as: Component, debounce, fallback, onResize, }: SizedLayoutProps): React.JSX.Element;
-//# sourceMappingURL=SizedContainer.d.ts.map

package/dist/layout/resize/impl/SizedContainer.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"SizedContainer.d.ts","sourceRoot":"","sources":["../../../../src/layout/resize/impl/SizedContainer.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,MAAM,OAAO,CAAC;AAG1B,OAAO,EAAC,gBAAgB,EAAC,MAAM,0BAA0B,CAAC;AAK1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,cAAc,CAAC,EACI,QAAQ,EACR,SAAS,EACT,KAAK,EACL,EAAE,EAAE,SAAiB,EACrB,QAAQ,EACR,QAAQ,EACR,QAAQ,GACX,EAAE,gBAAgB,qBA2BjD"}

package/dist/layout/resize/impl/SizedContainer.js

@@ -1,65 +0,0 @@
-'use client';
-import { useResizeDetector } from 'react-resize-detector';
-import React from "react";
-import { SizedLayoutContext } from "../core/SizedLayoutContext";
-/**
- * 自动测量尺寸的容器组件（基于 react-resize-detector）
- *
- * 子组件通过 useContextLayoutSize() 获取容器尺寸，适用于需要根据父容器尺寸
- * 进行布局的场景（如虚拟列表、图表、Canvas 等）。
- *
- * @example
- * ```tsx
- * // 基础用法
- * <SizedContainer className="h-full w-full">
- *   <ChartComponent />
- * </SizedContainer>
- *
- * // ChartComponent 内部
- * function ChartComponent() {
- *   const { width, height, isReady } = useContextLayoutSize();
- *   if (!isReady) return <Skeleton />;
- *   return <Chart width={width} height={height} />;
- * }
- * ```
- *
- * @example
- * ```tsx
- * // 带 fallback 的用法
- * <SizedContainer fallback={<Loading />} className="h-full">
- *   <VirtualList />
- * </SizedContainer>
- * ```
- *
- * @example
- * ```tsx
- * // 自定义元素类型 + 尺寸变化回调
- * <SizedContainer
- *   as="section"
- *   debounce={100}
- *   onResize={({ width, height }) => console.log(width, height)}
- * >
- *   <Content />
- * </SizedContainer>
- * ```
- */
-export function SizedContainer({ children, className, style, as: Component = 'div', debounce, fallback, onResize, }) {
-    const { width, height, ref } = useResizeDetector({
-        refreshMode: debounce ? 'debounce' : undefined,
-        refreshRate: debounce,
-        onResize: onResize
-            ? ({ width: w, height: h }) => {
-                if (w !== null && h !== null) {
-                    onResize({ width: w, height: h });
-                }
-            }
-            : undefined,
-    });
-    const size = {
-        width: width !== null && width !== void 0 ? width : 0,
-        height: height !== null && height !== void 0 ? height : 0,
-    };
-    const isReady = size.width > 0 && size.height > 0;
-    return (React.createElement(Component, { ref: ref, className: className, style: style },
-        React.createElement(SizedLayoutContext.Provider, { value: { ...size, isReady } }, fallback && !isReady ? fallback : children)));
-}

package/dist/layout/resize/impl/SizedLayout.d.ts

@@ -1,45 +0,0 @@
-import React from "react";
-import { SizedLayoutProps } from "../core/SizedLayoutProps";
-/**
- * 自动测量尺寸的布局容器
- *
- * 子组件通过 useContextLayoutSize() 获取容器尺寸，适用于需要根据父容器尺寸
- * 进行布局的场景（如虚拟列表、图表、Canvas 等）。
- *
- * @example
- * ```tsx
- * // 基础用法
- * <SizedLayout className="h-full w-full">
- *   <ChartComponent />
- * </SizedLayout>
- *
- * // ChartComponent 内部
- * function ChartComponent() {
- *   const { width, height, isReady } = useContextLayoutSize();
- *   if (!isReady) return <Skeleton />;
- *   return <Chart width={width} height={height} />;
- * }
- * ```
- *
- * @example
- * ```tsx
- * // 带 fallback 的用法
- * <SizedLayout fallback={<Loading />} className="h-full">
- *   <VirtualList />
- * </SizedLayout>
- * ```
- *
- * @example
- * ```tsx
- * // 自定义元素类型 + 尺寸变化回调
- * <SizedLayout
- *   as="section"
- *   debounce={100}
- *   onResize={({ width, height }) => console.log(width, height)}
- * >
- *   <Content />
- * </SizedLayout>
- * ```
- */
-export declare function SizedLayout({ children, className, style, as: Component, debounce, fallback, onResize, }: SizedLayoutProps): React.JSX.Element;
-//# sourceMappingURL=SizedLayout.d.ts.map

package/dist/layout/resize/impl/SizedLayout.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"SizedLayout.d.ts","sourceRoot":"","sources":["../../../../src/layout/resize/impl/SizedLayout.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,MAAM,OAAO,CAAC;AAG1B,OAAO,EAAC,gBAAgB,EAAC,MAAM,0BAA0B,CAAC;AAG1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,WAAW,CAAC,EACI,QAAQ,EACR,SAAS,EACT,KAAK,EACL,EAAE,EAAE,SAAiB,EACrB,QAAQ,EACR,QAAQ,EACR,QAAQ,GACX,EAAE,gBAAgB,qBA2B9C"}

package/dist/layout/resize/impl/SizedLayout.js

@@ -1,65 +0,0 @@
-'use client';
-import { useEffect, useRef } from 'react';
-import { useResizeObserver } from '../core/ResizeObserverHook';
-import React from "react";
-import { SizedLayoutContext } from "../core/SizedLayoutContext";
-/**
- * 自动测量尺寸的布局容器
- *
- * 子组件通过 useContextLayoutSize() 获取容器尺寸，适用于需要根据父容器尺寸
- * 进行布局的场景（如虚拟列表、图表、Canvas 等）。
- *
- * @example
- * ```tsx
- * // 基础用法
- * <SizedLayout className="h-full w-full">
- *   <ChartComponent />
- * </SizedLayout>
- *
- * // ChartComponent 内部
- * function ChartComponent() {
- *   const { width, height, isReady } = useContextLayoutSize();
- *   if (!isReady) return <Skeleton />;
- *   return <Chart width={width} height={height} />;
- * }
- * ```
- *
- * @example
- * ```tsx
- * // 带 fallback 的用法
- * <SizedLayout fallback={<Loading />} className="h-full">
- *   <VirtualList />
- * </SizedLayout>
- * ```
- *
- * @example
- * ```tsx
- * // 自定义元素类型 + 尺寸变化回调
- * <SizedLayout
- *   as="section"
- *   debounce={100}
- *   onResize={({ width, height }) => console.log(width, height)}
- * >
- *   <Content />
- * </SizedLayout>
- * ```
- */
-export function SizedLayout({ children, className, style, as: Component = 'div', debounce, fallback, onResize, }) {
-    const { containerRef, containerWidth, containerHeight, isContainerReady } = useResizeObserver({
-        debounce,
-    });
-    const size = {
-        width: containerWidth,
-        height: containerHeight,
-    };
-    // 处理 onResize 回调
-    const onResizeRef = useRef(onResize);
-    onResizeRef.current = onResize;
-    useEffect(() => {
-        if (isContainerReady && onResizeRef.current) {
-            onResizeRef.current(size);
-        }
-    }, [containerWidth, containerHeight, isContainerReady]);
-    return (React.createElement(Component, { ref: containerRef, className: className, style: style },
-        React.createElement(SizedLayoutContext.Provider, { value: { ...size, isReady: isContainerReady } }, fallback && !isContainerReady ? fallback : children)));
-}

package/dist/layout/spinner/XSpinner.d.ts

@@ -1,43 +0,0 @@
-import React from "react";
-/**
- * XSpinner 组件属性
- */
-export interface XSpinnerProps {
-    /**
-     * 自定义样式类名
-     * - 可覆盖默认的尺寸、颜色、动画等样式
-     * @example "w-8 h-8 border-blue-500"
-     */
-    className?: string;
-}
-/**
- * XSpinner - 轻量级加载指示器组件
- *
- * @description
- * 使用 CSS border + rotate 动画实现的高性能 spinner：
- * - 基于 div + Tailwind CSS，无 SVG 解析开销
- * - 尺寸使用 `1em`，自动跟随父元素字体大小
- * - 默认白色边框，适合深色背景
- * - 可通过 className 完全自定义样式
- *
- * @example
- * ```tsx
- * // 基本用法（跟随父元素字体大小）
- * <XSpinner />
- *
- * // 自定义尺寸
- * <XSpinner className="w-8 h-8" />
- *
- * // 自定义颜色（深色主题）
- * <XSpinner className="border-gray-800 border-t-transparent" />
- *
- * // 在按钮中使用
- * <button className="text-lg">
- *   <XSpinner /> 加载中...
- * </button>
- * ```
- *
- * @see XButton - 内置 XSpinner 作为默认加载指示器
- */
-export declare const XSpinner: ({ className }?: XSpinnerProps) => React.JSX.Element;
-//# sourceMappingURL=XSpinner.d.ts.map

package/dist/layout/spinner/XSpinner.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"XSpinner.d.ts","sourceRoot":"","sources":["../../../src/layout/spinner/XSpinner.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,OAAO,CAAC;AAG1B;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,QAAQ,GAAI,gBAAa,aAAkB,sBAoBvD,CAAC"}

package/dist/layout/spinner/XSpinner.js

@@ -1,47 +0,0 @@
-'use client';
-import React from "react";
-import { cn } from "tailwind-variants";
-/**
- * XSpinner - 轻量级加载指示器组件
- *
- * @description
- * 使用 CSS border + rotate 动画实现的高性能 spinner：
- * - 基于 div + Tailwind CSS，无 SVG 解析开销
- * - 尺寸使用 `1em`，自动跟随父元素字体大小
- * - 默认白色边框，适合深色背景
- * - 可通过 className 完全自定义样式
- *
- * @example
- * ```tsx
- * // 基本用法（跟随父元素字体大小）
- * <XSpinner />
- *
- * // 自定义尺寸
- * <XSpinner className="w-8 h-8" />
- *
- * // 自定义颜色（深色主题）
- * <XSpinner className="border-gray-800 border-t-transparent" />
- *
- * // 在按钮中使用
- * <button className="text-lg">
- *   <XSpinner /> 加载中...
- * </button>
- * ```
- *
- * @see XButton - 内置 XSpinner 作为默认加载指示器
- */
-export const XSpinner = ({ className } = {}) => (React.createElement("div", { style: {
-        // 使用内联样式确保 em 单位正确跟随 font-size
-        width: '1em',
-        height: '1em',
-        // 边框粗细也跟随字体大小
-        borderWidth: '0.125em',
-    }, className: cn(
-    // 边框样式：白色圆环，顶部透明形成缺口
-    "border-solid border-current border-t-transparent rounded-full", 
-    // 动画：无限旋转
-    "animate-spin", 
-    // 透明度：略微降低避免过亮
-    "opacity-80", 
-    // 用户自定义类名
-    className) }));

package/dist/layout/virtualized/VirtualizedConfig.d.ts

@@ -1,16 +0,0 @@
-/**
- * Virtuoso 虚拟列表配置常量
- * overscan: 可视区域外预渲染的像素数量
- * - 值越大，预渲染越多，滚动越流畅，但内存占用增加
- */
-export declare const VirtualizedOverscan: {
-    /** 小型列表或慢速滚动场景 (200px) */
-    readonly SMALL: 200;
-    /** 中等列表或正常滚动场景 (800px) */
-    readonly MEDIUM: 800;
-    /** 大型列表或快速滚动场景 (1200px) */
-    readonly LARGE: 1200;
-    /** 超大列表或极快速滚动场景 (2000px) */
-    readonly EXTRA_LARGE: 2000;
-};
-//# sourceMappingURL=VirtualizedConfig.d.ts.map

package/dist/layout/virtualized/VirtualizedConfig.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"VirtualizedConfig.d.ts","sourceRoot":"","sources":["../../../src/layout/virtualized/VirtualizedConfig.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAO,MAAM,mBAAmB;IAC5B,0BAA0B;;IAE1B,0BAA0B;;IAE1B,2BAA2B;;IAE3B,4BAA4B;;CAEtB,CAAA"}

package/dist/layout/virtualized/VirtualizedConfig.js

@@ -1,15 +0,0 @@
-/**
- * Virtuoso 虚拟列表配置常量
- * overscan: 可视区域外预渲染的像素数量
- * - 值越大，预渲染越多，滚动越流畅，但内存占用增加
- */
-export const VirtualizedOverscan = {
-    /** 小型列表或慢速滚动场景 (200px) */
-    SMALL: 200,
-    /** 中等列表或正常滚动场景 (800px) */
-    MEDIUM: 800,
-    /** 大型列表或快速滚动场景 (1200px) */
-    LARGE: 1200,
-    /** 超大列表或极快速滚动场景 (2000px) */
-    EXTRA_LARGE: 2000,
-};

package/dist/layout/visibility/ElementVisibilityHooks.d.ts

@@ -1,13 +0,0 @@
-import { RefObject } from 'react';
-/**
- * 监听元素及其所有祖先的可见性
- * 支持检测 display: none、visibility: hidden、opacity: 0
- * 支持 Radix UI 的 data-state 属性变化（如 Tabs.Content）
- *
- * @param ref - 要监听的元素 ref
- * @param debounceMs - 防抖时间（毫秒），默认 16ms（约一帧）
- * @param ancestor - 是否同步检查祖先元素的可见性，默认 true
- * @returns boolean | null - null 表示还未检测到结果
- */
-export declare function useElementVisibility(ref: RefObject<HTMLElement | null>, debounceMs?: number, ancestor?: boolean): boolean | null;
-//# sourceMappingURL=ElementVisibilityHooks.d.ts.map

package/dist/layout/visibility/ElementVisibilityHooks.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ElementVisibilityHooks.d.ts","sourceRoot":"","sources":["../../../src/layout/visibility/ElementVisibilityHooks.tsx"],"names":[],"mappings":"AAEA,OAAO,EAA8B,SAAS,EAAC,MAAM,OAAO,CAAA;AAE5D;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAChC,GAAG,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAClC,UAAU,GAAE,MAAW,EACvB,QAAQ,GAAE,OAAc,GACzB,OAAO,GAAG,IAAI,CAyHhB"}

package/dist/layout/visibility/ElementVisibilityHooks.js

@@ -1,119 +0,0 @@
-'use client';
-import { useState, useEffect, useRef } from 'react';
-/**
- * 监听元素及其所有祖先的可见性
- * 支持检测 display: none、visibility: hidden、opacity: 0
- * 支持 Radix UI 的 data-state 属性变化（如 Tabs.Content）
- *
- * @param ref - 要监听的元素 ref
- * @param debounceMs - 防抖时间（毫秒），默认 16ms（约一帧）
- * @param ancestor - 是否同步检查祖先元素的可见性，默认 true
- * @returns boolean | null - null 表示还未检测到结果
- */
-export function useElementVisibility(ref, debounceMs = 16, ancestor = true) {
-    const [isVisible, setIsVisible] = useState(null);
-    const lastVisibleRef = useRef(null);
-    const timerRef = useRef(null);
-    const observerRef = useRef(null);
-    const debounceMsRef = useRef(debounceMs);
-    const mountedRef = useRef(true);
-    // 保持 debounceMs 最新，但不触发 effect 重新执行
-    debounceMsRef.current = debounceMs;
-    useEffect(() => {
-        // 重置状态（处理组件重新挂载的情况）
-        mountedRef.current = true;
-        lastVisibleRef.current = null;
-        // 检查元素及所有祖先是否可见
-        const checkVisibility = () => {
-            if (!mountedRef.current)
-                return;
-            const el = ref.current;
-            if (!el)
-                return;
-            let current = el;
-            let visible = true;
-            while (current) {
-                const style = getComputedStyle(current);
-                if (style.display === 'none' ||
-                    style.visibility === 'hidden' ||
-                    style.opacity === '0') {
-                    visible = false;
-                    break;
-                }
-                // 如果不检查祖先，只检查当前元素后退出
-                if (!ancestor)
-                    break;
-                current = current.parentElement;
-            }
-            // 只在值变化时更新
-            if (mountedRef.current && lastVisibleRef.current !== visible) {
-                lastVisibleRef.current = visible;
-                setIsVisible(visible);
-            }
-        };
-        // 带防抖的检查
-        const debouncedCheck = () => {
-            if (timerRef.current) {
-                clearTimeout(timerRef.current);
-            }
-            timerRef.current = setTimeout(checkVisibility, debounceMsRef.current);
-        };
-        // 设置 observer
-        const setupObserver = () => {
-            const el = ref.current;
-            if (!el)
-                return;
-            // 清理旧的 observer
-            if (observerRef.current) {
-                observerRef.current.disconnect();
-            }
-            const observer = new MutationObserver(debouncedCheck);
-            let parent = el;
-            while (parent) {
-                observer.observe(parent, {
-                    attributes: true,
-                    // 监听 style、class、以及 data-state（Radix UI）
-                    attributeFilter: ['style', 'class', 'data-state'],
-                });
-                // 如果不检查祖先，只监听当前元素后退出
-                if (!ancestor)
-                    break;
-                parent = parent.parentElement;
-            }
-            observerRef.current = observer;
-            checkVisibility(); // 初始检查
-        };
-        setupObserver();
-        // 监听 ref 变化（通过 RAF 轮询，处理 ref 延迟赋值的情况）
-        let rafId = null;
-        const checkRef = () => {
-            if (!mountedRef.current)
-                return;
-            if (ref.current && !observerRef.current) {
-                setupObserver();
-                rafId = null;
-                return;
-            }
-            rafId = requestAnimationFrame(checkRef);
-        };
-        if (!ref.current) {
-            rafId = requestAnimationFrame(checkRef);
-        }
-        return () => {
-            mountedRef.current = false;
-            if (observerRef.current) {
-                observerRef.current.disconnect();
-                observerRef.current = null;
-            }
-            if (timerRef.current) {
-                clearTimeout(timerRef.current);
-                timerRef.current = null;
-            }
-            if (rafId) {
-                cancelAnimationFrame(rafId);
-            }
-        };
-    }, [ref, ancestor]);
-    // null 表示还未检测到结果
-    return isVisible;
-}