xxf_react 0.8.5 → 0.8.7

package/dist/layout/button/XButton.d.ts

@@ -0,0 +1,99 @@
+import React, { ButtonHTMLAttributes, ReactNode } from 'react';
+/**
+ * 加载指示器位置
+ * - `start`: 指示器在内容左侧
+ * - `center`: 指示器居中，内容隐藏（保持宽度）
+ * - `end`: 指示器在内容右侧
+ */
+export type LoadingGravity = 'start' | 'center' | 'end';
+/**
+ * XButton 组件属性
+ * @extends ButtonHTMLAttributes<HTMLButtonElement> 继承原生 button 所有属性
+ */
+export interface XButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    /**
+     * 加载状态
+     * - 为 `true` 时按钮不可点击，显示加载指示器
+     * @default false
+     */
+    loading?: boolean;
+    /**
+     * 加载指示器位置
+     * - `start`: 左侧
+     * - `center`: 居中（隐藏内容，保持宽度避免抖动）
+     * - `end`: 右侧
+     * @default 'start'
+     */
+    loadingGravity?: LoadingGravity;
+    /**
+     * 自定义加载指示器（回调形式，懒创建）
+     * - 只有 loading=true 时才会调用
+     * - 不传则使用默认的 XSpinner
+     * - 尺寸建议使用 `em` 单位以跟随字体大小
+     * @example () => <MySpinner className="w-5 h-5" />
+     */
+    loadingIndicator?: () => ReactNode;
+    /**
+     * 指示器与内容的间距（像素）
+     * - 仅在 `loadingGravity` 为 `start` 或 `end` 时生效
+     * @default 8
+     */
+    loadingGap?: number;
+    /**
+     * 点击防抖等待时间（毫秒）
+     * - 防止用户快速连续点击
+     * - 使用 leading 模式：首次点击立即执行，后续点击在等待时间内被忽略
+     * - 设为 0 时禁用防抖
+     * @default 500
+     */
+    debounceWait?: number;
+    /**
+     * 是否阻止事件冒泡
+     * @default false
+     */
+    stopPropagation?: boolean;
+    /** 按钮内容，支持任意 ReactNode（文本、元素、组件等） */
+    children?: ReactNode;
+}
+/**
+ * XButton - 支持加载状态的按钮组件
+ *
+ * @description
+ * 封装了常见的按钮加载交互：
+ * - 加载时自动禁用点击
+ * - 支持自定义加载指示器位置（左/中/右）
+ * - 居中模式保持按钮宽度，避免布局抖动
+ * - 支持 ref 转发
+ * - 支持点击防抖，防止重复提交
+ * - 不依赖外部库，纯内联样式实现
+ *
+ * @example
+ * ```tsx
+ * // 基本用法
+ * <XButton loading={isLoading} onClick={handleSubmit}>
+ *   提交
+ * </XButton>
+ *
+ * // 加载指示器在左侧
+ * <XButton loading loadingGravity="start">
+ *   加载中...
+ * </XButton>
+ *
+ * // 自定义加载指示器（回调形式，懒创建）
+ * <XButton loading loadingIndicator={() => <MySpinner />}>
+ *   处理中
+ * </XButton>
+ *
+ * // 防抖点击（500ms 内只响应第一次）
+ * <XButton debounceWait={500} onClick={handleSubmit}>
+ *   提交订单
+ * </XButton>
+ *
+ * // 阻止冒泡 + 防抖
+ * <XButton debounceWait={500} stopPropagation onClick={handleSubmit}>
+ *   提交
+ * </XButton>
+ * ```
+ */
+export declare const XButton: React.ForwardRefExoticComponent<XButtonProps & React.RefAttributes<HTMLButtonElement>>;
+//# sourceMappingURL=XButton.d.ts.map

package/dist/layout/button/XButton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"XButton.d.ts","sourceRoot":"","sources":["../../../src/layout/button/XButton.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,EAAa,oBAAoB,EAAE,SAAS,EAAgB,MAAM,OAAO,CAAC;AAIxF;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;AAExD;;;GAGG;AACH,MAAM,WAAW,YAAa,SAAQ,oBAAoB,CAAC,iBAAiB,CAAC;IACzE;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,SAAS,CAAC;IAEnC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B,qCAAqC;IACrC,QAAQ,CAAC,EAAE,SAAS,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,OAAO,wFA6InB,CAAC"}

package/dist/layout/button/XButton.js

@@ -0,0 +1,131 @@
+'use client';
+import React, { forwardRef } from 'react';
+import { useDebouncedCallback } from 'use-debounce';
+import { XSpinner } from "../spinner/XSpinner";
+/**
+ * XButton - 支持加载状态的按钮组件
+ *
+ * @description
+ * 封装了常见的按钮加载交互：
+ * - 加载时自动禁用点击
+ * - 支持自定义加载指示器位置（左/中/右）
+ * - 居中模式保持按钮宽度，避免布局抖动
+ * - 支持 ref 转发
+ * - 支持点击防抖，防止重复提交
+ * - 不依赖外部库，纯内联样式实现
+ *
+ * @example
+ * ```tsx
+ * // 基本用法
+ * <XButton loading={isLoading} onClick={handleSubmit}>
+ *   提交
+ * </XButton>
+ *
+ * // 加载指示器在左侧
+ * <XButton loading loadingGravity="start">
+ *   加载中...
+ * </XButton>
+ *
+ * // 自定义加载指示器（回调形式，懒创建）
+ * <XButton loading loadingIndicator={() => <MySpinner />}>
+ *   处理中
+ * </XButton>
+ *
+ * // 防抖点击（500ms 内只响应第一次）
+ * <XButton debounceWait={500} onClick={handleSubmit}>
+ *   提交订单
+ * </XButton>
+ *
+ * // 阻止冒泡 + 防抖
+ * <XButton debounceWait={500} stopPropagation onClick={handleSubmit}>
+ *   提交
+ * </XButton>
+ * ```
+ */
+export const XButton = forwardRef(function XButton({ loading = false, loadingGravity = 'start', loadingIndicator, loadingGap = 8, debounceWait = 500, stopPropagation = false, children, onClick, disabled, style, type = 'button', ...rest }, ref) {
+    /**
+     * 获取加载指示器（懒创建）
+     * - 只在 loading=true 时才实际创建节点
+     */
+    const getIndicator = () => { var _a; return (_a = loadingIndicator === null || loadingIndicator === void 0 ? void 0 : loadingIndicator()) !== null && _a !== void 0 ? _a : React.createElement(XSpinner, null); };
+    /**
+     * 防抖处理后的点击回调
+     * - leading: true  首次点击立即执行
+     * - trailing: false  等待时间结束后不再执行
+     */
+    const debouncedOnClick = useDebouncedCallback((e) => {
+        onClick === null || onClick === void 0 ? void 0 : onClick(e);
+    }, debounceWait, { leading: true, trailing: false });
+    /**
+     * 点击事件处理
+     * - 阻止冒泡（可选）
+     * - loading 或 disabled 时拦截
+     * - debounceWait > 0 时使用防抖回调
+     */
+    const handleClick = (e) => {
+        // 阻止冒泡
+        if (stopPropagation) {
+            e.stopPropagation();
+        }
+        // loading 或 disabled 时拦截
+        if (loading || disabled) {
+            e.preventDefault();
+            return;
+        }
+        // 根据 debounceWait 决定是否使用防抖
+        if (debounceWait > 0) {
+            debouncedOnClick(e);
+        }
+        else {
+            onClick === null || onClick === void 0 ? void 0 : onClick(e);
+        }
+    };
+    /** 按钮基础样式，使用 flexbox 布局 */
+    const baseStyle = {
+        display: 'inline-flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        position: 'relative',
+        // 仅在 start/end 模式下应用 gap
+        gap: loading && loadingGravity !== 'center' ? loadingGap : undefined,
+        ...style,
+    };
+    /**
+     * 渲染按钮内容
+     * - 非加载状态：直接渲染 children
+     * - start：指示器 + children
+     * - end：children + 指示器
+     * - center：children 隐藏占位 + 指示器绝对定位居中
+     */
+    const renderContent = () => {
+        if (!loading) {
+            return children;
+        }
+        const indicator = getIndicator();
+        switch (loadingGravity) {
+            case 'start':
+                return (React.createElement(React.Fragment, null,
+                    indicator,
+                    children));
+            case 'end':
+                return (React.createElement(React.Fragment, null,
+                    children,
+                    indicator));
+            case 'center':
+            default:
+                // children 保持可见，indicator 绝对定位叠加在上面
+                // 背景透明，可以看到 children 内容
+                return (React.createElement(React.Fragment, null,
+                    children,
+                    React.createElement("div", { style: {
+                            position: 'absolute',
+                            inset: 0,
+                            display: 'flex',
+                            alignItems: 'center',
+                            justifyContent: 'center',
+                            backgroundColor: 'transparent',
+                        } }, indicator)));
+        }
+    };
+    return (React.createElement("button", { ref: ref, type: type, ...rest, style: baseStyle, disabled: disabled || loading, onClick: handleClick, "aria-busy": loading, "aria-disabled": disabled || loading }, renderContent()));
+});

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

@@ -0,0 +1,147 @@
+import React, { ReactNode, HTMLAttributes } from 'react';
+/**
+ * XHover 组件属性
+ */
+export interface XHoverProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onMouseEnter' | 'onMouseLeave'> {
+    /**
+     * 子组件
+     */
+    children: ReactNode;
+    /**
+     * 悬浮触发延迟时间（毫秒）
+     *
+     * 鼠标进入后，需要持续悬浮该时间才会触发 onHover 回调和显示 hoverLayer。
+     * - 设为 0 或不设置：鼠标进入立即触发
+     * - 设为正数：鼠标需要停留指定毫秒后才触发
+     *
+     * @example
+     * ```tsx
+     * // 悬浮 2 秒后触发
+     * <XHover hoverDelay={2000} onHover={handleHover}>
+     *
+     * // 立即触发（默认）
+     * <XHover onHover={handleHover}>
+     * ```
+     *
+     * @default 0
+     */
+    hoverDelay?: number;
+    /**
+     * 鼠标进入时立即触发的回调（不等待 hoverDelay）
+     *
+     * 适用于需要在鼠标进入时立即做一些事情的场景，如显示边框高亮等
+     */
+    onEnter?: () => void;
+    /**
+     * 悬浮回调
+     *
+     * 当鼠标悬浮达到 hoverDelay 时间后触发
+     */
+    onHover?: () => void;
+    /**
+     * 鼠标离开回调
+     *
+     * @param triggered - 是否已触发过 onHover（用于判断是否需要隐藏 tooltip 等）
+     */
+    onLeave?: (triggered: boolean) => void;
+    /**
+     * 悬浮覆盖层
+     *
+     * 当悬浮触发（达到 hoverDelay 时间）后，显示在 children 上方的内容。
+     * 鼠标离开后自动隐藏。
+     *
+     * @example
+     * ```tsx
+     * <XHover
+     *   hoverDelay={1000}
+     *   hoverLayer={() => (
+     *     <div className="absolute inset-0 bg-black/50 flex items-center justify-center">
+     *       <span className="text-white">悬浮提示</span>
+     *     </div>
+     *   )}
+     * >
+     *   <img src="..." />
+     * </XHover>
+     * ```
+     */
+    hoverLayer?: () => ReactNode;
+    /**
+     * 是否禁用悬浮检测
+     *
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * 容器元素类型
+     *
+     * @default 'div'
+     */
+    as?: 'div' | 'span';
+}
+/**
+ * 悬浮触发组件
+ *
+ * 支持延迟触发悬浮回调，适用于需要用户停留一段时间后才响应的场景。
+ *
+ * @example
+ * ```tsx
+ * // 基础用法：鼠标悬浮 2 秒后触发
+ * <XHover hoverDelay={2000} onHover={() => console.log('悬浮触发')}>
+ *   <div>悬浮我</div>
+ * </XHover>
+ *
+ * // 无延迟：立即触发
+ * <XHover onHover={() => console.log('立即触发')}>
+ *   <div>悬浮我</div>
+ * </XHover>
+ *
+ * // 带离开回调，判断是否触发过
+ * <XHover
+ *   hoverDelay={1000}
+ *   onHover={() => setShowTooltip(true)}
+ *   onLeave={(triggered) => {
+ *     if (triggered) setShowTooltip(false)
+ *   }}
+ * >
+ *   <Button>悬浮显示提示</Button>
+ * </XHover>
+ *
+ * // 使用 hoverLayer 显示悬浮覆盖层
+ * <XHover
+ *   hoverDelay={1000}
+ *   hoverLayer={() => (
+ *     <div className="absolute inset-0 bg-black/50 flex items-center justify-center">
+ *       <PlayIcon className="text-white w-12 h-12" />
+ *     </div>
+ *   )}
+ * >
+ *   <img src="thumbnail.jpg" />
+ * </XHover>
+ *
+ * // 使用 span 作为容器（适用于 inline 场景）
+ * <XHover as="span" hoverDelay={500} onHover={handleHover}>
+ *   <span>inline 文本</span>
+ * </XHover>
+ *
+ * // 禁用状态
+ * <XHover disabled={isLoading} hoverDelay={1000} onHover={handleHover}>
+ *   <div>内容</div>
+ * </XHover>
+ *
+ * // 使用 onEnter 立即响应 + onHover 延迟响应
+ * <XHover
+ *   hoverDelay={1000}
+ *   onEnter={() => setHighlight(true)}
+ *   onHover={() => setShowDetail(true)}
+ *   onLeave={() => {
+ *     setHighlight(false)
+ *     setShowDetail(false)
+ *   }}
+ * >
+ *   <Card />
+ * </XHover>
+ * ```
+ */
+export declare const XHover: React.ForwardRefExoticComponent<XHoverProps & React.RefAttributes<HTMLElement>>;
+export default XHover;
+//# sourceMappingURL=XHover.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"XHover.d.ts","sourceRoot":"","sources":["../../../src/layout/hover/XHover.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAuD,SAAS,EAAE,cAAc,EAAC,MAAM,OAAO,CAAA;AAE5G;;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,eAAO,MAAM,MAAM,iFAyFjB,CAAA;AAEF,eAAe,MAAM,CAAA"}

package/dist/layout/hover/XHover.js

@@ -0,0 +1,128 @@
+import React, { forwardRef, useCallback, useRef, useEffect, useState } from 'react';
+/**
+ * 悬浮触发组件
+ *
+ * 支持延迟触发悬浮回调，适用于需要用户停留一段时间后才响应的场景。
+ *
+ * @example
+ * ```tsx
+ * // 基础用法：鼠标悬浮 2 秒后触发
+ * <XHover hoverDelay={2000} onHover={() => console.log('悬浮触发')}>
+ *   <div>悬浮我</div>
+ * </XHover>
+ *
+ * // 无延迟：立即触发
+ * <XHover onHover={() => console.log('立即触发')}>
+ *   <div>悬浮我</div>
+ * </XHover>
+ *
+ * // 带离开回调，判断是否触发过
+ * <XHover
+ *   hoverDelay={1000}
+ *   onHover={() => setShowTooltip(true)}
+ *   onLeave={(triggered) => {
+ *     if (triggered) setShowTooltip(false)
+ *   }}
+ * >
+ *   <Button>悬浮显示提示</Button>
+ * </XHover>
+ *
+ * // 使用 hoverLayer 显示悬浮覆盖层
+ * <XHover
+ *   hoverDelay={1000}
+ *   hoverLayer={() => (
+ *     <div className="absolute inset-0 bg-black/50 flex items-center justify-center">
+ *       <PlayIcon className="text-white w-12 h-12" />
+ *     </div>
+ *   )}
+ * >
+ *   <img src="thumbnail.jpg" />
+ * </XHover>
+ *
+ * // 使用 span 作为容器（适用于 inline 场景）
+ * <XHover as="span" hoverDelay={500} onHover={handleHover}>
+ *   <span>inline 文本</span>
+ * </XHover>
+ *
+ * // 禁用状态
+ * <XHover disabled={isLoading} hoverDelay={1000} onHover={handleHover}>
+ *   <div>内容</div>
+ * </XHover>
+ *
+ * // 使用 onEnter 立即响应 + onHover 延迟响应
+ * <XHover
+ *   hoverDelay={1000}
+ *   onEnter={() => setHighlight(true)}
+ *   onHover={() => setShowDetail(true)}
+ *   onLeave={() => {
+ *     setHighlight(false)
+ *     setShowDetail(false)
+ *   }}
+ * >
+ *   <Card />
+ * </XHover>
+ * ```
+ */
+export const XHover = forwardRef(function XHover({ children, hoverDelay = 0, onEnter, onHover, onLeave, hoverLayer, disabled = false, as: Component = 'div', style, ...rest }, ref) {
+    const timerRef = useRef(null);
+    const hasTriggeredRef = useRef(false);
+    // 只有 hoverLayer 存在时才需要状态
+    const [showLayer, setShowLayer] = useState(false);
+    const clearTimer = useCallback(() => {
+        if (timerRef.current) {
+            clearTimeout(timerRef.current);
+            timerRef.current = null;
+        }
+    }, []);
+    // 组件卸载时清理定时器
+    useEffect(() => {
+        return clearTimer;
+    }, [clearTimer]);
+    // disabled 变化时清理定时器和状态
+    useEffect(() => {
+        if (disabled) {
+            clearTimer();
+            if (hoverLayer) {
+                setShowLayer(false);
+            }
+        }
+    }, [disabled, clearTimer, hoverLayer]);
+    const handleMouseEnter = useCallback(() => {
+        if (disabled)
+            return;
+        hasTriggeredRef.current = false;
+        clearTimer();
+        // 立即触发 onEnter
+        onEnter === null || onEnter === void 0 ? void 0 : onEnter();
+        if (hoverDelay <= 0) {
+            hasTriggeredRef.current = true;
+            if (hoverLayer)
+                setShowLayer(true);
+            onHover === null || onHover === void 0 ? void 0 : onHover();
+        }
+        else {
+            timerRef.current = setTimeout(() => {
+                hasTriggeredRef.current = true;
+                if (hoverLayer)
+                    setShowLayer(true);
+                onHover === null || onHover === void 0 ? void 0 : onHover();
+            }, hoverDelay);
+        }
+    }, [hoverDelay, onEnter, onHover, clearTimer, disabled, hoverLayer]);
+    const handleMouseLeave = useCallback(() => {
+        if (disabled)
+            return;
+        clearTimer();
+        if (hoverLayer)
+            setShowLayer(false);
+        onLeave === null || onLeave === void 0 ? void 0 : onLeave(hasTriggeredRef.current);
+    }, [clearTimer, onLeave, disabled, hoverLayer]);
+    // 如果有 hoverLayer，需要使用 relative 定位（用户 style 可覆盖）
+    const containerStyle = hoverLayer
+        ? { position: 'relative', ...style }
+        : style;
+    return (React.createElement(Component, { ref: ref, ...rest, style: containerStyle, onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave },
+        children,
+        hoverLayer && showLayer && hoverLayer()));
+});
+export default XHover;

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

@@ -0,0 +1,35 @@
+import React from "react";
+import type { XImageProps } from "./XImage.types";
+/**
+ * 生产级图片组件
+ *
+ * 基于 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 declare const XImage: React.NamedExoticComponent<XImageProps & React.RefAttributes<HTMLDivElement | HTMLImageElement>>;
+export default XImage;
+//# sourceMappingURL=XImage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"XImage.d.ts","sourceRoot":"","sources":["../../../src/layout/image/XImage.tsx"],"names":[],"mappings":"AAEA,OAAO,KASN,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EAAE,WAAW,EAAgB,MAAM,gBAAgB,CAAC;AAIhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,MAAM,kGAoUlB,CAAC;AAEF,eAAe,MAAM,CAAC"}

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

@@ -0,0 +1,16 @@
+/**
+ * XImage 效果样式管理
+ * 自动注入 CSS 到 document.head，用户无需手动导入
+ */
+/**
+ * 注入效果 CSS 到 document.head
+ * - 仅在浏览器环境执行
+ * - 只执行一次（多个 XImage 实例共享）
+ * - SSR 安全
+ */
+export declare function injectEffectStyles(): void;
+/**
+ * 移除已注入的效果 CSS（用于测试或清理）
+ */
+export declare function removeEffectStyles(): void;
+//# sourceMappingURL=XImage.effects.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"XImage.effects.d.ts","sourceRoot":"","sources":["../../../src/layout/image/XImage.effects.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA8CH;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAczC;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAQzC"}

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

@@ -0,0 +1,77 @@
+/**
+ * XImage 效果样式管理
+ * 自动注入 CSS 到 document.head，用户无需手动导入
+ */
+// ============ 效果 CSS 定义 ============
+const EFFECT_STYLES = `
+.lazy-load-image-background.blur {
+  filter: blur(15px);
+}
+.lazy-load-image-background.blur.lazy-load-image-loaded {
+  filter: blur(0);
+  transition: filter .3s;
+}
+.lazy-load-image-background.blur > img {
+  opacity: 0;
+}
+.lazy-load-image-background.blur.lazy-load-image-loaded > img {
+  opacity: 1;
+  transition: opacity .3s;
+}
+.lazy-load-image-background.opacity {
+  opacity: 0;
+}
+.lazy-load-image-background.opacity.lazy-load-image-loaded {
+  opacity: 1;
+  transition: opacity .3s;
+}
+.lazy-load-image-background.black-and-white {
+  filter: grayscale(1);
+}
+.lazy-load-image-background.black-and-white.lazy-load-image-loaded {
+  filter: grayscale(0);
+  transition: filter .3s;
+}
+.lazy-load-image-background.black-and-white > img {
+  opacity: 0;
+}
+.lazy-load-image-background.black-and-white.lazy-load-image-loaded > img {
+  opacity: 1;
+  transition: opacity .3s;
+}
+`;
+const STYLE_ID = "ximage-effect-styles";
+// CSS 注入标记，确保只注入一次
+let stylesInjected = false;
+/**
+ * 注入效果 CSS 到 document.head
+ * - 仅在浏览器环境执行
+ * - 只执行一次（多个 XImage 实例共享）
+ * - SSR 安全
+ */
+export function injectEffectStyles() {
+    if (stylesInjected || typeof document === "undefined")
+        return;
+    // 双重检查：防止多实例并发注入
+    if (document.getElementById(STYLE_ID)) {
+        stylesInjected = true;
+        return;
+    }
+    const styleElement = document.createElement("style");
+    styleElement.id = STYLE_ID;
+    styleElement.textContent = EFFECT_STYLES;
+    document.head.appendChild(styleElement);
+    stylesInjected = true;
+}
+/**
+ * 移除已注入的效果 CSS（用于测试或清理）
+ */
+export function removeEffectStyles() {
+    if (typeof document === "undefined")
+        return;
+    const styleElement = document.getElementById(STYLE_ID);
+    if (styleElement) {
+        styleElement.remove();
+        stylesInjected = false;
+    }
+}