xxf_react 0.8.5 → 0.8.6

package/dist/layout/image/XImage.js

@@ -0,0 +1,261 @@
+"use client";
+import React, { useState, useEffect, useCallback, useRef, forwardRef, memo, useMemo, useContext, } from "react";
+import { LazyLoadImage } from "react-lazy-load-image-component";
+import { ScrollPositionContext } from "./XImageGallery";
+import { injectEffectStyles } from "./XImage.effects";
+/**
+ * 生产级图片组件
+ *
+ * 基于 react-lazy-load-image-component 实现，支持：
+ * - 懒加载 + IntersectionObserver
+ * - 多种加载效果 (blur/opacity/black-and-white) - CSS 已内置，无需导入
+ * - 错误处理 + 自动重试
+ * - fallback 备用图/组件
+ * - 性能优化 (配合 XImageGallery 使用 trackWindowScroll)
+ *
+ * @example
+ * ```tsx
+ * // 基础用法
+ * <XImage src="/photo.jpg" alt="Photo" width={400} height={300} />
+ *
+ * // 带模糊效果（提供 placeholder URL 自动启用 blur）
+ * <XImage src="/photo.jpg" placeholder="/photo-tiny.jpg" />
+ *
+ * // 自定义占位组件
+ * <XImage src="/photo.jpg" placeholder={<Skeleton />} effect="opacity" />
+ *
+ * // 带错误处理
+ * <XImage
+ *   src="/photo.jpg"
+ *   fallback="/fallback.jpg"
+ *   retryCount={2}
+ *   retryDelay={1000}
+ * />
+ * ```
+ */
+export const XImage = memo(forwardRef(function XImage({ 
+// 基础属性
+src, alt = "", width, height, className, style, objectFit, objectPosition, fill, 
+// 懒加载配置
+lazy = true, threshold = 100, effect, placeholder, useIntersectionObserver = true, delayMethod, delayTime, 
+// 错误处理
+fallback, retryCount = 0, retryDelay = 1000, 
+// 性能优化
+scrollPosition, visibleByDefault = false, 
+// 事件回调
+onLoad, onError, onVisible, onStatusChange, 
+// 包裹元素属性
+wrapperProps, wrapperClassName, 
+// 原生属性
+loading, decoding = "async", srcSet, sizes, crossOrigin, referrerPolicy, }, ref) {
+    // ============ 解析 placeholder 类型 ============
+    const isPlaceholderSrc = typeof placeholder === "string";
+    const placeholderSrc = isPlaceholderSrc ? placeholder : undefined;
+    const placeholderElement = !isPlaceholderSrc ? placeholder : undefined;
+    // ============ 智能默认 effect ============
+    // 只有当 placeholder 是字符串（URL）时才自动启用 blur
+    // ReactElement 类型不自动启用（因为没有图片可以模糊）
+    const effectiveEffect = effect !== null && effect !== void 0 ? effect : (isPlaceholderSrc ? "blur" : undefined);
+    // ============ 自动注入效果 CSS ============
+    // 使用 effect 属性时自动注入，确保 SSR 兼容
+    useEffect(() => {
+        if (effectiveEffect) {
+            injectEffectStyles();
+        }
+    }, [effectiveEffect]);
+    // ============ Context: 自动获取 Gallery 的 scrollPosition ============
+    const contextScrollPosition = useContext(ScrollPositionContext);
+    const effectiveScrollPosition = scrollPosition !== null && scrollPosition !== void 0 ? scrollPosition : contextScrollPosition;
+    // ============ 状态管理 ============
+    const [currentSrc, setCurrentSrc] = useState(src);
+    const [status, setStatus] = useState("idle");
+    const [hasError, setHasError] = useState(false);
+    const [retryAttempt, setRetryAttempt] = useState(0);
+    // Refs
+    const wrapperRef = useRef(null);
+    const retryTimerRef = useRef(null);
+    const hasCalledOnVisible = useRef(false);
+    // 使用 ref 存储回调，避免 effect 依赖问题
+    const onStatusChangeRef = useRef(onStatusChange);
+    onStatusChangeRef.current = onStatusChange;
+    // ============ src 变化重置状态 ============
+    useEffect(() => {
+        var _a;
+        setCurrentSrc(src);
+        setHasError(false);
+        setRetryAttempt(0);
+        setStatus("idle");
+        (_a = onStatusChangeRef.current) === null || _a === void 0 ? void 0 : _a.call(onStatusChangeRef, "idle");
+        hasCalledOnVisible.current = false;
+        // 清理重试定时器
+        if (retryTimerRef.current) {
+            clearTimeout(retryTimerRef.current);
+            retryTimerRef.current = null;
+        }
+    }, [src]);
+    // 清理定时器
+    useEffect(() => {
+        return () => {
+            if (retryTimerRef.current) {
+                clearTimeout(retryTimerRef.current);
+            }
+        };
+    }, []);
+    // ============ ref 转发：从 wrapper 中获取 img 元素 ============
+    useEffect(() => {
+        if (!ref || !wrapperRef.current)
+            return;
+        const imgElement = wrapperRef.current.querySelector("img");
+        if (imgElement) {
+            if (typeof ref === "function") {
+                ref(imgElement);
+            }
+            else {
+                ref.current = imgElement;
+            }
+        }
+        // 依赖 status 确保图片加载后能获取到正确的 img 元素
+    }, [ref, status]);
+    // ============ 状态更新辅助 ============
+    const updateStatus = useCallback((newStatus) => {
+        var _a;
+        setStatus(newStatus);
+        (_a = onStatusChangeRef.current) === null || _a === void 0 ? void 0 : _a.call(onStatusChangeRef, newStatus);
+    }, []);
+    // ============ 事件处理 ============
+    const handleLoad = useCallback((event) => {
+        updateStatus("loaded");
+        onLoad === null || onLoad === void 0 ? void 0 : onLoad(event);
+    }, [updateStatus, onLoad]);
+    const handleError = useCallback((event) => {
+        setRetryAttempt((currentRetry) => {
+            // 还有重试次数
+            if (currentRetry < retryCount) {
+                updateStatus("loading");
+                retryTimerRef.current = setTimeout(() => {
+                    // 通过修改 src 触发重新加载（添加时间戳绕过缓存）
+                    const separator = src.includes("?") ? "&" : "?";
+                    setCurrentSrc(`${src}${separator}_retry=${Date.now()}`);
+                }, retryDelay);
+                return currentRetry + 1;
+            }
+            // 重试耗尽，检查 fallback
+            setHasError((currentHasError) => {
+                if (fallback && !currentHasError) {
+                    if (typeof fallback === "string") {
+                        setCurrentSrc(fallback);
+                        updateStatus("loading");
+                    }
+                    return true;
+                }
+                // 最终失败
+                updateStatus("error");
+                onError === null || onError === void 0 ? void 0 : onError(event);
+                return currentHasError;
+            });
+            return currentRetry;
+        });
+    }, [retryCount, retryDelay, src, fallback, updateStatus, onError]);
+    // beforeLoad: 进入视口，开始加载前调用
+    const handleBeforeLoad = useCallback(() => {
+        if (!hasCalledOnVisible.current) {
+            hasCalledOnVisible.current = true;
+            updateStatus("loading");
+            onVisible === null || onVisible === void 0 ? void 0 : onVisible();
+        }
+    }, [updateStatus, onVisible]);
+    // ============ 计算样式 ============
+    const computedStyle = useMemo(() => {
+        const baseStyle = { ...style };
+        if (objectFit) {
+            baseStyle.objectFit = objectFit;
+        }
+        if (objectPosition) {
+            baseStyle.objectPosition = objectPosition;
+        }
+        // fill 模式：图片绝对定位填充
+        if (fill) {
+            baseStyle.position = "absolute";
+            baseStyle.width = "100%";
+            baseStyle.height = "100%";
+            baseStyle.inset = 0;
+            baseStyle.objectFit = objectFit || "cover";
+        }
+        return baseStyle;
+    }, [style, objectFit, objectPosition, fill]);
+    const wrapperStyle = useMemo(() => {
+        const base = { ...wrapperProps === null || wrapperProps === void 0 ? void 0 : wrapperProps.style };
+        // fill 模式下包裹元素需要绝对定位并填满父容器
+        if (fill) {
+            base.display = "block";
+            base.position = "absolute";
+            base.inset = 0;
+            base.width = "100%";
+            base.height = "100%";
+        }
+        return base;
+    }, [fill, wrapperProps === null || wrapperProps === void 0 ? void 0 : wrapperProps.style]);
+    // ============ 解析尺寸（简单计算，不需要 useMemo） ============
+    const parsedWidth = fill
+        ? undefined
+        : typeof width === "number"
+            ? width
+            : typeof width === "string"
+                ? parseInt(width, 10) || undefined
+                : undefined;
+    const parsedHeight = fill
+        ? undefined
+        : typeof height === "number"
+            ? height
+            : typeof height === "string"
+                ? parseInt(height, 10) || undefined
+                : undefined;
+    // ============ 合并 wrapperProps（处理 ref 合并） ============
+    const mergedWrapperProps = useMemo(() => {
+        // wrapperProps 可能包含 ref（通过类型扩展）
+        const userRef = wrapperProps === null || wrapperProps === void 0 ? void 0 : wrapperProps.ref;
+        // 合并 ref
+        const combinedRef = (node) => {
+            // 设置内部 ref
+            wrapperRef.current = node;
+            // 调用用户的 ref
+            if (userRef) {
+                if (typeof userRef === "function") {
+                    userRef(node);
+                }
+                else {
+                    userRef.current = node;
+                }
+            }
+        };
+        return {
+            ...wrapperProps,
+            ref: combinedRef,
+            style: wrapperStyle,
+            className: wrapperClassName,
+        };
+    }, [wrapperProps, wrapperStyle, wrapperClassName]);
+    // ============ 渲染 fallback ReactNode ============
+    if (hasError && fallback && typeof fallback !== "string") {
+        return (React.createElement("div", { ref: ref, className: className, style: {
+                width: parsedWidth,
+                height: parsedHeight,
+                position: fill ? "absolute" : undefined,
+                inset: fill ? 0 : undefined,
+                ...style,
+            } }, fallback));
+    }
+    // ============ 统一使用 LazyLoadImage ============
+    return (React.createElement(LazyLoadImage, { src: currentSrc, alt: alt, width: parsedWidth, height: parsedHeight, className: className, style: computedStyle, 
+        // 懒加载配置 - lazy=false 时禁用懒加载特性
+        threshold: lazy ? threshold : 0, effect: lazy ? effectiveEffect : undefined, placeholderSrc: lazy ? placeholderSrc : undefined, placeholder: lazy ? placeholderElement : undefined, useIntersectionObserver: lazy ? useIntersectionObserver : false, visibleByDefault: !lazy || visibleByDefault, delayMethod: delayMethod, delayTime: delayTime, 
+        // 性能优化
+        scrollPosition: lazy ? effectiveScrollPosition : undefined, 
+        // 事件
+        beforeLoad: lazy ? handleBeforeLoad : undefined, onLoad: handleLoad, onError: handleError, 
+        // 包裹元素
+        wrapperProps: mergedWrapperProps, 
+        // 原生属性
+        loading: lazy ? loading : "eager", decoding: decoding, srcSet: srcSet, sizes: sizes, crossOrigin: crossOrigin, referrerPolicy: referrerPolicy }));
+}));
+export default XImage;

package/dist/layout/image/XImage.types.d.ts

@@ -0,0 +1,130 @@
+import type { CSSProperties, ReactElement, ReactNode, SyntheticEvent } from "react";
+/**
+ * 懒加载效果类型
+ * - blur: 模糊渐变效果
+ * - opacity: 透明度渐变效果
+ * - black-and-white: 黑白到彩色渐变效果
+ */
+export type XImageEffect = "blur" | "opacity" | "black-and-white";
+/**
+ * 节流/防抖方法类型
+ */
+export type DelayMethod = "throttle" | "debounce";
+/**
+ * 图片加载状态
+ */
+export type XImageStatus = "idle" | "loading" | "loaded" | "error";
+/**
+ * 滚动位置类型 (用于 trackWindowScroll HOC)
+ */
+export interface ScrollPosition {
+    x: number;
+    y: number;
+}
+/**
+ * XImage 组件 Props
+ */
+export interface XImageProps {
+    /** 图片源地址 */
+    src: string;
+    /** 图片描述文本 */
+    alt?: string;
+    /** 图片宽度 */
+    width?: number | string;
+    /** 图片高度 */
+    height?: number | string;
+    /** CSS 类名 */
+    className?: string;
+    /** 内联样式 */
+    style?: CSSProperties;
+    /** 图片填充方式 */
+    objectFit?: CSSProperties["objectFit"];
+    /** 图片对齐方式 */
+    objectPosition?: CSSProperties["objectPosition"];
+    /** 是否使用 fill 模式（占满父容器） */
+    fill?: boolean;
+    /** 是否启用懒加载，默认 true */
+    lazy?: boolean;
+    /** 进入视口前多少像素开始加载，默认 100 */
+    threshold?: number;
+    /** 加载效果类型（如果提供了 placeholder URL 但未指定 effect，默认为 'blur'） */
+    effect?: XImageEffect;
+    /**
+     * 占位内容
+     * - string: 占位图片 URL（自动启用 blur 效果）
+     * - ReactElement: 自定义占位组件（如 Skeleton，需手动指定 effect）
+     */
+    placeholder?: string | ReactElement | null;
+    /** 是否使用 IntersectionObserver，默认 true */
+    useIntersectionObserver?: boolean;
+    /** 滚动/resize 事件的节流方法 */
+    delayMethod?: DelayMethod;
+    /** 节流延迟时间（毫秒） */
+    delayTime?: number;
+    /**
+     * 加载失败时显示的备用内容
+     * - string: 备用图片 URL
+     * - ReactNode: 自定义错误展示组件
+     */
+    fallback?: string | ReactNode;
+    /** 加载失败后的重试次数，默认 0 */
+    retryCount?: number;
+    /** 重试间隔（毫秒），默认 1000 */
+    retryDelay?: number;
+    /**
+     * 滚动位置（来自 trackWindowScroll HOC）
+     * 当父组件使用 withScrollTracking 包裹时自动传入
+     */
+    scrollPosition?: ScrollPosition;
+    /**
+     * 设为 true 则图片立即显示（不触发懒加载）
+     * 适用于已在浏览器缓存中的图片
+     */
+    visibleByDefault?: boolean;
+    /** 图片加载完成回调 */
+    onLoad?: (event: SyntheticEvent<HTMLImageElement>) => void;
+    /** 图片加载失败回调 */
+    onError?: (event: SyntheticEvent<HTMLImageElement>) => void;
+    /** 图片进入视口时回调 */
+    onVisible?: () => void;
+    /** 加载状态变化回调 */
+    onStatusChange?: (status: XImageStatus) => void;
+    /** 传递给包裹 span 元素的属性 */
+    wrapperProps?: React.HTMLAttributes<HTMLSpanElement>;
+    /** 包裹元素的类名 */
+    wrapperClassName?: string;
+    /** 图片加载优先级 */
+    loading?: "lazy" | "eager";
+    /** 解码方式 */
+    decoding?: "async" | "auto" | "sync";
+    /** 响应式图片源集 */
+    srcSet?: string;
+    /** 响应式尺寸 */
+    sizes?: string;
+    /** 跨域设置 */
+    crossOrigin?: "anonymous" | "use-credentials" | "";
+    /** referrer 策略 */
+    referrerPolicy?: React.HTMLAttributeReferrerPolicy;
+}
+/**
+ * XImageGallery 组件 Props
+ * 用于包裹多个 XImage 实现统一的滚动监听优化
+ */
+export interface XImageGalleryProps {
+    children: ReactNode;
+    /** 自定义容器类名 */
+    className?: string;
+    /** 自定义容器样式 */
+    style?: CSSProperties;
+    /** 节流方法: throttle 或 debounce */
+    delayMethod?: DelayMethod;
+    /** 节流/防抖延迟时间（毫秒） */
+    delayTime?: number;
+}
+/**
+ * withScrollTracking HOC 注入的 Props
+ */
+export interface WithScrollTrackingProps {
+    scrollPosition: ScrollPosition;
+}
+//# sourceMappingURL=XImage.types.d.ts.map

package/dist/layout/image/XImage.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"XImage.types.d.ts","sourceRoot":"","sources":["../../../src/layout/image/XImage.types.ts"],"names":[],"mappings":"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"}

package/dist/layout/image/XImage.types.js

@@ -0,0 +1,2 @@
+"use client";
+export {};

package/dist/layout/image/XImageGallery.d.ts

@@ -0,0 +1,76 @@
+import React, { ComponentType } from "react";
+import type { XImageGalleryProps, ScrollPosition, WithScrollTrackingProps } from "./XImage.types";
+/**
+ * ScrollPosition Context
+ * 用于在组件树中共享滚动位置，支持深层嵌套的 XImage 自动获取
+ */
+export declare const ScrollPositionContext: React.Context<ScrollPosition | undefined>;
+/**
+ * Hook: 获取当前的滚动位置
+ * 在 XImageGallery 内部的任意深度使用
+ */
+export declare function useScrollPosition(): ScrollPosition | undefined;
+/**
+ * XImageGallery - 图片画廊/列表性能优化组件
+ *
+ * 当页面中有大量图片需要懒加载时，使用此组件包裹可以：
+ * - 统一管理滚动监听，避免每个图片单独监听 scroll/resize 事件
+ * - 通过 trackWindowScroll HOC 实现性能优化
+ * - 通过 Context 自动向任意深度的子 XImage 组件传递 scrollPosition
+ *
+ * @example
+ * ```tsx
+ * // 基础用法 - 包裹多个 XImage（支持任意嵌套深度）
+ * <XImageGallery>
+ *   <div className="grid">
+ *     {images.map(img => (
+ *       <div key={img.id} className="card">
+ *         <XImage src={img.url} effect="blur" />
+ *       </div>
+ *     ))}
+ *   </div>
+ * </XImageGallery>
+ *
+ * // 自定义节流配置
+ * <XImageGallery delayMethod="debounce" delayTime={200}>
+ *   {images.map(img => (
+ *     <XImage key={img.id} src={img.url} />
+ *   ))}
+ * </XImageGallery>
+ * ```
+ *
+ * @note 注意事项：
+ * - 不要在 XImageGallery 内部嵌套另一个 XImageGallery
+ * - 内部的 XImage 会自动通过 Context 获取 scrollPosition，无需手动传递
+ */
+export declare const XImageGallery: React.NamedExoticComponent<XImageGalleryProps & React.RefAttributes<HTMLDivElement>>;
+/**
+ * HOC: 为任意组件添加滚动位置追踪能力
+ *
+ * 适用于需要自定义容器但又想使用 trackWindowScroll 优化的场景
+ *
+ * @example
+ * ```tsx
+ * // 自定义图片网格组件
+ * const ImageGrid = ({ images, scrollPosition }) => (
+ *   <div className="grid grid-cols-3">
+ *     {images.map(img => (
+ *       <XImage
+ *         key={img.id}
+ *         src={img.url}
+ *         scrollPosition={scrollPosition}
+ *       />
+ *     ))}
+ *   </div>
+ * );
+ *
+ * // 使用 HOC 包裹
+ * const OptimizedImageGrid = withScrollTracking(ImageGrid);
+ *
+ * // 使用
+ * <OptimizedImageGrid images={images} />
+ * ```
+ */
+export declare function withScrollTracking<P extends object>(WrappedComponent: ComponentType<P & WithScrollTrackingProps>): ComponentType<Omit<P, "scrollPosition">>;
+export default XImageGallery;
+//# sourceMappingURL=XImageGallery.d.ts.map

package/dist/layout/image/XImageGallery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"XImageGallery.d.ts","sourceRoot":"","sources":["../../../src/layout/image/XImageGallery.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,EAAQ,aAAa,EAAyC,MAAM,OAAO,CAAC;AAE1F,OAAO,KAAK,EACR,kBAAkB,EAClB,cAAc,EACd,uBAAuB,EAC1B,MAAM,gBAAgB,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,qBAAqB,2CAAuD,CAAC;AAE1F;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,GAAG,SAAS,CAE9D;AAgCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,aAAa,sFAiBzB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,EAC/C,gBAAgB,EAAE,aAAa,CAAC,CAAC,GAAG,uBAAuB,CAAC,GAC7D,aAAa,CAAC,IAAI,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAW1C;AAED,eAAe,aAAa,CAAC"}

package/dist/layout/image/XImageGallery.js

@@ -0,0 +1,94 @@
+"use client";
+import React, { memo, forwardRef, createContext, useContext } from "react";
+import { trackWindowScroll } from "react-lazy-load-image-component";
+/**
+ * ScrollPosition Context
+ * 用于在组件树中共享滚动位置，支持深层嵌套的 XImage 自动获取
+ */
+export const ScrollPositionContext = createContext(undefined);
+/**
+ * Hook: 获取当前的滚动位置
+ * 在 XImageGallery 内部的任意深度使用
+ */
+export function useScrollPosition() {
+    return useContext(ScrollPositionContext);
+}
+const InternalGallery = memo(forwardRef(function InternalGallery({ children, className, style, scrollPosition }, ref) {
+    return (React.createElement(ScrollPositionContext.Provider, { value: scrollPosition },
+        React.createElement("div", { ref: ref, className: className, style: style }, children)));
+}));
+/**
+ * 使用 trackWindowScroll HOC 包裹的 Gallery
+ */
+const TrackedGallery = trackWindowScroll(InternalGallery);
+/**
+ * XImageGallery - 图片画廊/列表性能优化组件
+ *
+ * 当页面中有大量图片需要懒加载时，使用此组件包裹可以：
+ * - 统一管理滚动监听，避免每个图片单独监听 scroll/resize 事件
+ * - 通过 trackWindowScroll HOC 实现性能优化
+ * - 通过 Context 自动向任意深度的子 XImage 组件传递 scrollPosition
+ *
+ * @example
+ * ```tsx
+ * // 基础用法 - 包裹多个 XImage（支持任意嵌套深度）
+ * <XImageGallery>
+ *   <div className="grid">
+ *     {images.map(img => (
+ *       <div key={img.id} className="card">
+ *         <XImage src={img.url} effect="blur" />
+ *       </div>
+ *     ))}
+ *   </div>
+ * </XImageGallery>
+ *
+ * // 自定义节流配置
+ * <XImageGallery delayMethod="debounce" delayTime={200}>
+ *   {images.map(img => (
+ *     <XImage key={img.id} src={img.url} />
+ *   ))}
+ * </XImageGallery>
+ * ```
+ *
+ * @note 注意事项：
+ * - 不要在 XImageGallery 内部嵌套另一个 XImageGallery
+ * - 内部的 XImage 会自动通过 Context 获取 scrollPosition，无需手动传递
+ */
+export const XImageGallery = memo(forwardRef(function XImageGallery({ children, className, style, delayMethod, delayTime }, ref) {
+    return (React.createElement(TrackedGallery, { ref: ref, className: className, style: style, delayMethod: delayMethod, delayTime: delayTime }, children));
+}));
+/**
+ * HOC: 为任意组件添加滚动位置追踪能力
+ *
+ * 适用于需要自定义容器但又想使用 trackWindowScroll 优化的场景
+ *
+ * @example
+ * ```tsx
+ * // 自定义图片网格组件
+ * const ImageGrid = ({ images, scrollPosition }) => (
+ *   <div className="grid grid-cols-3">
+ *     {images.map(img => (
+ *       <XImage
+ *         key={img.id}
+ *         src={img.url}
+ *         scrollPosition={scrollPosition}
+ *       />
+ *     ))}
+ *   </div>
+ * );
+ *
+ * // 使用 HOC 包裹
+ * const OptimizedImageGrid = withScrollTracking(ImageGrid);
+ *
+ * // 使用
+ * <OptimizedImageGrid images={images} />
+ * ```
+ */
+export function withScrollTracking(WrappedComponent) {
+    const WithScrollTracking = trackWindowScroll(WrappedComponent);
+    // 设置 displayName 便于调试
+    const wrappedName = WrappedComponent.displayName || WrappedComponent.name || "Component";
+    WithScrollTracking.displayName = `withScrollTracking(${wrappedName})`;
+    return WithScrollTracking;
+}
+export default XImageGallery;

package/dist/layout/image/index.d.ts

@@ -0,0 +1,12 @@
+export { XImage, default as XImageDefault } from "./XImage";
+export { XImageGallery, withScrollTracking, useScrollPosition, ScrollPositionContext, } from "./XImageGallery";
+export type { XImageProps, XImageEffect, XImageStatus, XImageGalleryProps, ScrollPosition, WithScrollTrackingProps, DelayMethod, } from "./XImage.types";
+/**
+ * XImage 效果 CSS 已内置，无需手动导入！
+ *
+ * 直接使用 effect 属性即可：
+ * <XImage src="..." effect="blur" />
+ * <XImage src="..." effect="opacity" />
+ * <XImage src="..." effect="black-and-white" />
+ */
+//# sourceMappingURL=index.d.ts.map

package/dist/layout/image/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/layout/image/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,UAAU,CAAC;AAC5D,OAAO,EACH,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,GACxB,MAAM,iBAAiB,CAAC;AAGzB,YAAY,EACR,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,uBAAuB,EACvB,WAAW,GACd,MAAM,gBAAgB,CAAC;AAGxB;;;;;;;GAOG"}

package/dist/layout/image/index.js

@@ -0,0 +1,4 @@
+"use client";
+// ============ 组件导出 ============
+export { XImage, default as XImageDefault } from "./XImage";
+export { XImageGallery, withScrollTracking, useScrollPosition, ScrollPositionContext, } from "./XImageGallery";

package/dist/layout/index.d.ts

@@ -0,0 +1,12 @@
+export * from './resize/core/SizedLayoutProps';
+export * from './resize/core/SizedLayoutContext';
+export * from './resize/core/ResizeObserverHook';
+export * from './resize/impl/SizedContainer';
+export * from './resize/impl/SizedLayout';
+export * from './image';
+export * from './visibility/ElementVisibilityHooks';
+export * from './virtualized/VirtualizedConfig';
+export * from './hover/XHover';
+export * from './button/XButton';
+export * from './spinner/XSpinner';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/layout/index.ts"],"names":[],"mappings":"AAAA,cAAc,gCAAgC,CAAA;AAC9C,cAAc,kCAAkC,CAAA;AAChD,cAAc,kCAAkC,CAAA;AAChD,cAAc,8BAA8B,CAAA;AAC5C,cAAc,2BAA2B,CAAA;AACzC,cAAc,SAAS,CAAA;AACvB,cAAc,qCAAqC,CAAA;AACnD,cAAc,iCAAiC,CAAA;AAC/C,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA"}

package/dist/layout/index.js

@@ -0,0 +1,11 @@
+export * from './resize/core/SizedLayoutProps';
+export * from './resize/core/SizedLayoutContext';
+export * from './resize/core/ResizeObserverHook';
+export * from './resize/impl/SizedContainer';
+export * from './resize/impl/SizedLayout';
+export * from './image';
+export * from './visibility/ElementVisibilityHooks';
+export * from './virtualized/VirtualizedConfig';
+export * from './hover/XHover';
+export * from './button/XButton';
+export * from './spinner/XSpinner';

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

@@ -0,0 +1,41 @@
+import { RefObject } from 'react';
+import { LayoutSize } from "../../../foundation/LayoutSize";
+interface UseResizeObserverOptions {
+    /** 防抖延迟，默认 0（不防抖） */
+    debounce?: number;
+    /** 初始尺寸 */
+    initialSize?: LayoutSize;
+}
+interface UseResizeObserverReturn<T extends HTMLElement> {
+    /** 绑定到容器元素的 ref */
+    containerRef: RefObject<T | null>;
+    /** 容器宽度 */
+    containerWidth: number;
+    /** 容器高度 */
+    containerHeight: number;
+    /** 是否已获取到尺寸 */
+    isContainerReady: boolean;
+}
+/**
+ * 基于 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 declare function useResizeObserver<T extends HTMLElement = HTMLDivElement>(options?: UseResizeObserverOptions): UseResizeObserverReturn<T>;
+export {};
+//# sourceMappingURL=ResizeObserverHook.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ResizeObserverHook.d.ts","sourceRoot":"","sources":["../../../../src/layout/resize/core/ResizeObserverHook.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,SAAS,EAAC,MAAM,OAAO,CAAC;AAC7D,OAAO,EAAC,UAAU,EAAC,MAAM,gCAAgC,CAAC;AAG1D,UAAU,wBAAwB;IAC9B,qBAAqB;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW;IACX,WAAW,CAAC,EAAE,UAAU,CAAC;CAC5B;AAED,UAAU,uBAAuB,CAAC,CAAC,SAAS,WAAW;IACnD,mBAAmB;IACnB,YAAY,EAAE,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAClC,WAAW;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW;IACX,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe;IACf,gBAAgB,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,WAAW,GAAG,cAAc,EACpE,OAAO,GAAE,wBAA6B,GACvC,uBAAuB,CAAC,CAAC,CAAC,CAqC5B"}