xxf_react 0.6.1 → 0.6.3

package/README.md

@@ -1,12 +1,14 @@
 # @xxf/react
 
-To install dependencies:
+React 工具库，提供常用的组件、Hooks 和工具函数。
+
+## 安装
 
 ```bash
 bun install
 ```
 
-To run:
+## 运行
 
 ```bash
 bun run src/index.ts
@@ -14,6 +16,22 @@ bun run src/index.ts
 
 This project was created using `bun init` in bun v1.3.2. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
 
-## 文档
+## 模块文档
+
+| 模块 | 说明 |
+|------|------|
+| [event-bus](./src/event-bus/README.md) | 事件总线，支持跨 Tab 通信 |
+| [fetch](./src/fetch/README.md) | 带超时控制的 fetch 封装 |
+| [flow](./src/flow/README.md) | Promise 扩展，全局错误处理 |
+| [foundation](./src/foundation/README.md) | 基础工具，性能监控 |
+| [layout](./src/layout/README.md) | 布局组件，悬浮交互 |
+| [media](./src/media/README.md) | 媒体组件，视频播放 |
+| [models](./src/models/README.md) | 数据模型，API 响应类型 |
+| [refresh](./src/refresh/README.md) | 刷新加载，分页加载更多 |
+| [responsive](./src/responsive/README.md) | 响应式布局，设备检测 |
+| [sse](./src/sse/README.md) | Server-Sent Events 连接管理 |
+| [utils](./src/utils/README.md) | 工具函数，滚动定位、组件刷新 |
+
+## 详细文档
 
 - [PlaybackQueue 播放队列状态管理](./src/media/playback-queue-store.md)

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/index.d.ts

@@ -7,4 +7,6 @@ export * from './image/XImage';
 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

@@ -1 +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,gBAAgB,CAAA;AAC9B,cAAc,qCAAqC,CAAA;AACnD,cAAc,iCAAiC,CAAA;AAC/C,cAAc,gBAAgB,CAAA"}
+{"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,gBAAgB,CAAA;AAC9B,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

@@ -7,3 +7,5 @@ export * from './image/XImage';
 export * from './visibility/ElementVisibilityHooks';
 export * from './virtualized/VirtualizedConfig';
 export * from './hover/XHover';
+export * from './button/XButton';
+export * from './spinner/XSpinner';

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

@@ -0,0 +1,43 @@
+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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,47 @@
+'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/package.json

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