@aozi6666/bee-design 0.1.0 → 0.1.2

package/README.md

@@ -1,73 +1,182 @@
-# React + TypeScript + Vite
+## Bee Design
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+React UI Component Library inspired by Honeycomb 🐝  
+一个基于 React + TypeScript 的轻量级组件库，用来练习和演示现代前端工程化（组件开发、单元测试、Storybook、CI 等）实践。
 
-Currently, two official plugins are available:
+### GitHub
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+`https://github.com/aozi6666/Bee-Design`
 
-## React Compiler
+### Install
 
-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+```bash
+npm install @aozi6666/bee-design
+# or
+yarn add @aozi6666/bee-design
+```
+
+### Quick Start
+
+```tsx
+import React from "react";
+import { createRoot } from "react-dom/client";
+import BeeButton from "@aozi6666/bee-design/build/components/Button";
+import "@aozi6666/bee-design/build/index.css";
+
+const App = () => (
+  <div style={{ padding: 24 }}>
+    <BeeButton>Bee Design Button</BeeButton>
+  </div>
+);
+
+createRoot(document.getElementById("root")!).render(<App />);
+```
+
+> **提示**：发布到 npm 后，推荐在业务项目中通过别名导入，如 `import { Button } from '@aozi6666/bee-design'`。当前版本的打包入口为 `build/index.js`，已经在 `package.json` 中配置好。
+
+---
+
+## Features
+
+- **基于 React + TypeScript**：完整的类型定义，开发体验友好。
+- **现代工程化**：使用 Vite 开发体验、本地 Storybook 文档、Jest + Testing Library 单元测试、ESLint 规范代码。
+- **常用基础组件**：涵盖表单、导航、反馈等常见场景。
+- **渐进式学习**：代码中包含一定注释，适合学习组件封装、hooks 抽离以及 TS 类型设计。
+
+---
+
+## Components
 
-## Expanding the ESLint configuration
+Bee Design 当前提供以下组件（持续扩展中）：
 
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+- **Button 按钮**
+  - 类型：`primary` / `default` / `danger` / `link`
+  - 支持 `href` / `target`、禁用状态等
+- **Input 输入框**
+  - 支持前后缀图标、禁用状态、清空等能力
+- **AutoComplete 自动完成**
+  - 根据输入关键字异步 / 同步返回候选项
+  - 支持自定义下拉项渲染（`renderOption`）
+- **Upload 上传**
+  - 支持点击上传、拖拽上传（`drag`）、上传进度展示、文件列表
+  - 提供原生表单上传示例和 `axios` 上传方式
+- **Menu 菜单**
+  - 水平 / 垂直导航菜单
+  - 支持子菜单展开、选中高亮
+- **Icon 图标**
+  - 基于 Font Awesome 封装
+  - 支持主题颜色、尺寸、旋转动画等
+- **Progress 进度条**
+  - 支持不同主题颜色和高度
+- **Transition 动画**
+  - 对 `react-transition-group` 的简单封装，用于出入场动画
+- **Hooks**
+  - `useClickOutside`：点击组件外区域的处理
+  - `useDebounce`：防抖输入处理
 
-```js
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
+具体用法可以查看 `src/components` 下各个组件的 `*.stories.tsx` 示例和测试用例。
 
-      // Remove tseslint.configs.recommended and replace with this
-      tseslint.configs.recommendedTypeChecked,
-      // Alternatively, use this for stricter rules
-      tseslint.configs.strictTypeChecked,
-      // Optionally, add this for stylistic rules
-      tseslint.configs.stylisticTypeChecked,
+---
 
-      // Other configs...
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
+## Usage Example
+
+以 `AutoComplete` 为例：
+
+```tsx
+import React, { useCallback } from "react";
+import AutoComplete, {
+  type DataSourceType,
+} from "@aozi6666/bee-design/build/components/AutoComplete";
+import "@aozi6666/bee-design/build/index.css";
+
+interface LakerPlayer {
+  value: string;
+  number: number;
+}
+
+const players: Array<DataSourceType<LakerPlayer>> = [
+  { value: "bradley", number: 11 },
+  { value: "james", number: 23 },
+  // ...
+];
+
+const Demo = () => {
+  const fetchSuggestions = useCallback(
+    (query: string) => players.filter((p) => p.value.toLowerCase().includes(query.toLowerCase())),
+    [],
+  );
+
+  return (
+    <AutoComplete fetchSuggestions={fetchSuggestions} placeholder="输入湖人队球员英文名试试" />
+  );
+};
 ```
 
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
-
-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
-
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-      // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
-      // Enable lint rules for React DOM
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
+> **建议**：`fetchSuggestions` 推荐使用 `useCallback` 包裹，避免在父组件重复渲染时创建新函数，从而触发不必要的副作用或额外请求。
+
+更多示例请参考仓库中的 `src/App.tsx` 和 Storybook 故事文件。
+
+---
+
+## Local Development
+
+克隆仓库：
+
+```bash
+git clone https://github.com/aozi6666/Bee-Design.git
+cd Bee-Design
+npm install
 ```
+
+本地开发预览：
+
+```bash
+npm run dev
+```
+
+运行 Storybook：
+
+```bash
+npm run storybook
+```
+
+运行单元测试：
+
+```bash
+npm run test
+# CI 模式（用于 prepublish）
+npm run test:ci
+```
+
+构建组件库（打包到 `build/` 目录）：
+
+```bash
+npm run build
+```
+
+发布前检查脚本（测试 + lint + build）：
+
+```bash
+npm run prepublishOnly
+```
+
+---
+
+## Scripts
+
+- **`npm run dev`**: 使用 Vite 启动开发服务器
+- **`npm run build`**: 构建 TypeScript 和样式到 `build/`
+- **`npm run lint`**: 使用 ESLint 检查 `src` 下的代码
+- **`npm run test` / `npm run test:ci`**: 使用 Jest + Testing Library 运行单元测试
+- **`npm run storybook` / `npm run build-storybook`**: 启动或构建 Storybook 文档站点
+
+---
+
+## Roadmap
+
+- [ ] 完善文档站点与在线 Demo
+- [ ] 增加更多表单组件（`Select` / `Checkbox` / `Radio` 等）
+- [ ] 增加 Layout、Modal 等业务常用组件
+- [ ] 打包为更符合行业习惯的 API 形式（`import { Button } from '@aozi6666/bee-design'`）
+
+欢迎在 GitHub 上提 issue 或 PR，一起完善 Bee Design 🐝。

package/build/components/AutoComplete/autoComplete.d.ts

@@ -1,5 +1,5 @@
-import type { AutoCompleteProps } from './autoComplete.types';
-export type { AutoCompleteProps, DataSourceType } from './autoComplete.types';
+import type { AutoCompleteProps } from "./autoComplete.types";
+export type { AutoCompleteProps, DataSourceType } from "./autoComplete.types";
 /**
  * 输入框自动完成功能。当输入值需要自动完成时使用，支持同步和异步两种方式
  * 支持 Input 组件的所有属性 支持键盘事件选择

package/build/components/AutoComplete/autoComplete.js

@@ -1,10 +1,10 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // AutoComplete 组件： 带搜索建议的 Input
-import { useState, useEffect, useRef } from 'react';
-import Input from '../Input/input';
-import useDebounce from '../../hooks/useDebounce';
-import useClickOutside from '../../hooks/useClickOutside';
-import AutoCompleteDropdown from './autoCompleteDropdown';
+import { useState, useEffect, useRef } from "react";
+import Input from "../Input/input";
+import useDebounce from "../../hooks/useDebounce";
+import useClickOutside from "../../hooks/useClickOutside";
+import AutoCompleteDropdown from "./autoCompleteDropdown";
 /**
  * 输入框自动完成功能。当输入值需要自动完成时使用，支持同步和异步两种方式
  * 支持 Input 组件的所有属性 支持键盘事件选择
@@ -17,53 +17,80 @@ import AutoCompleteDropdown from './autoCompleteDropdown';
 export const AutoComplete = (props) => {
     const { fetchSuggestions, onSelect, onChange, value, renderOption, ...restProps } = props;
     // 输入框当前显示的文本
-    const [inputValue, setInputValue] = useState(value || '');
-    // 下拉建议列表的数据源（渲染 `<li>` 就靠它）
+    const [inputValue, setInputValue] = useState(value || "");
+    // 候选项列表:下拉建议列表的数据源（渲染 `<li>` 就靠它）
     const [suggestions, setSugestions] = useState([]);
-    // 异步请求进行中就显示 loading
+    // 加载状态:异步请求进行中就显示 loading
     const [loading, setLoading] = useState(false);
     // 是否展示下拉（配合 `Transition` 动画）
     const [showDropdown, setShowDropdown] = useState(false);
-    // 键盘上下选择时，哪一项高亮（对应 class `is-active`）
+    // 高亮索引:键盘上下选择时，哪一项高亮（对应 class `is-active`）
     const [highlightIndex, setHighlightIndex] = useState(-1);
     // 两个关键 ref：
     // 用来区分“用户打字触发搜索” vs “用户选中后把值塞回去（不应该再搜一次）”
+    // 用户打字时:true，用户选中：false
     const triggerSearch = useRef(false);
     // 挂到最外层 div 上，给 `useClickOutside` 判断“点击是否发生在组件外”
     const componentRef = useRef(null);
     // 防抖Hook：把“频繁输入”变成“停顿后再触发一次”
     const debouncedValue = useDebounce(inputValue, 300);
-    // 自定义Hook：点击组件外部时关闭下拉
+    // 自定义Hook：点击组件外部时,触发自定义的回调
     /* 在 `document` 上挂一个 `click` 监听
      * @param componentRef 组件的 ref
      * @param callback 点击外部时执行的回调
      */
+    // componentRef： 指向 AutoComplete 最外层 DOM
     useClickOutside(componentRef, () => {
         setSugestions([]);
         setShowDropdown(false);
     });
-    // 监听 `debouncedValue` 变化
+    // 监听 `debouncedValue防抖后的值` 变化
+    // fetchSuggestions这个函数本身的引用地址变没变，改变时，监听变化
+    // 因为：React在 effect 里用到了这个函数，避免：闭包拿到旧函数
     useEffect(() => {
-        if (debouncedValue && triggerSearch.current) {
-            setSugestions([]);
-            const results = fetchSuggestions(debouncedValue);
-            if (results instanceof Promise) {
-                setLoading(true);
-                results.then(data => {
-                    setLoading(false);
-                    setSugestions(data);
-                    setShowDropdown(data.length > 0);
-                });
-            }
-            else {
-                setSugestions(results);
-                setShowDropdown(results.length > 0);
-            }
+        // 调度函数: 把 函数 放入微任务队列（执行）
+        // 页面更新等逻辑处理完再更新 UI，减少闪烁、时序混乱的问题
+        const schedule = (fn) => {
+            queueMicrotask(fn);
+        };
+        /* 停止搜索，关闭下拉框
+         * 两种情况：
+         * 1. 输入框为空（防抖后的值为空）
+         * 2. 用户选中下拉建议某一项后，输入框值会变为选中项的值（不应该再搜一次）
+         */
+        if (!debouncedValue || !triggerSearch.current) {
+            // 调用 调度函数: 把函数放入微任务队列（执行）
+            schedule(() => {
+                setShowDropdown(false); // 关闭下拉框 展示
+                setHighlightIndex(-1); // 重置高亮索引
+            });
+            return;
+        }
+        // 搜索执行
+        // 1. 拿当前输入内容，获取 建议项
+        const results = fetchSuggestions(debouncedValue);
+        // 异步返回：
+        if (results instanceof Promise) {
+            schedule(() => {
+                setLoading(true); // 显示“加载中”
+                setHighlightIndex(-1); // 不高亮任何项
+            });
+            // 异步返回： 拿到数据后，更新状态
+            results.then((data) => {
+                setLoading(false); // 关闭 “加载中”
+                setSugestions(data); // 更新建议项列表
+                setShowDropdown(data.length > 0); // 有数据，就显示下拉框
+            });
         }
         else {
-            setShowDropdown(false);
+            // 同步返回： 本地有个数组，直接筛选
+            schedule(() => {
+                setLoading(false); // 关闭 “加载中”
+                setSugestions(results);
+                setShowDropdown(results.length > 0);
+                setHighlightIndex(-1);
+            });
         }
-        setHighlightIndex(-1);
     }, [debouncedValue, fetchSuggestions]);
     const highlight = (index) => {
         if (index < 0)

package/build/components/AutoComplete/autoComplete.types.d.ts

@@ -1,10 +1,10 @@
-import type { ReactElement } from 'react';
-import type { InputProps } from '../Input/input.types';
+import type { ReactElement } from "react";
+import type { InputProps } from "../Input/input.types";
 interface DataSourceObject {
     value: string;
 }
-export type DataSourceType<T = {}> = T & DataSourceObject;
-export interface AutoCompleteProps extends Omit<InputProps, 'onSelect' | 'onChange'> {
+export type DataSourceType<T = Record<string, unknown>> = T & DataSourceObject;
+export interface AutoCompleteProps extends Omit<InputProps, "onSelect" | "onChange"> {
     /**
      * 返回输入建议的方法，可以拿到当前的输入，然后返回同步的数组或者是异步的 Promise
      */

package/build/components/AutoComplete/index.d.ts

@@ -1,4 +1,4 @@
 import AutoComplete from './autoComplete';
 export default AutoComplete;
-export * from './autoComplete';
-export type * from './autoComplete.types';
+export { AutoComplete } from './autoComplete';
+export type { AutoCompleteProps, DataSourceType } from './autoComplete.types';

package/build/components/AutoComplete/index.js

@@ -1,3 +1,3 @@
 import AutoComplete from './autoComplete';
 export default AutoComplete;
-export * from './autoComplete';
+export { AutoComplete } from './autoComplete';

package/build/components/Menu/menu.d.ts

@@ -1,4 +1,3 @@
-import React from 'react';
 import type { FC, CSSProperties, ReactNode } from 'react';
 type MenuMode = 'horizontal' | 'vertical';
 export interface MenuProps {
@@ -14,13 +13,6 @@ export interface MenuProps {
     defaultOpenSubMenus?: string[];
     children?: ReactNode;
 }
-interface IMenuContext {
-    index: string;
-    onSelect?: (selectedIndex: string) => void;
-    mode?: MenuMode;
-    defaultOpenSubMenus?: string[];
-}
-export declare const MenuContext: React.Context<IMenuContext>;
 /**
  * 为网站提供导航功能的菜单。支持横向纵向两种模式，支持下拉菜单。
  *

package/build/components/Menu/menu.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import React, { useState, createContext } from 'react';
+import React, { useState } from 'react';
 import classNames from 'classnames';
-export const MenuContext = createContext({ index: '0' });
+import { MenuContext } from './menuContext';
 /**
  * 为网站提供导航功能的菜单。支持横向纵向两种模式，支持下拉菜单。
  *

package/build/components/Menu/menuContext.d.ts

@@ -0,0 +1,9 @@
+type MenuMode = 'horizontal' | 'vertical';
+export interface IMenuContext {
+    index: string;
+    onSelect?: (selectedIndex: string) => void;
+    mode?: MenuMode;
+    defaultOpenSubMenus?: string[];
+}
+export declare const MenuContext: import("react").Context<IMenuContext>;
+export {};

package/build/components/Menu/menuContext.js

@@ -0,0 +1,2 @@
+import { createContext } from 'react';
+export const MenuContext = createContext({ index: '0' });

package/build/components/Menu/menuItem.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import React, { useContext } from 'react';
 import classNames from 'classnames';
-import { MenuContext } from './menu';
+import { MenuContext } from './menuContext';
 export const MenuItem = (props) => {
     const { index, disabled, className, style, children } = props;
     const context = useContext(MenuContext);

package/build/components/Menu/subMenu.js

@@ -1,12 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React, { useContext, useState } from 'react';
 import classNames from 'classnames';
-import { MenuContext } from './menu';
+import { MenuContext } from './menuContext';
 import Icon from '../Icon/icon';
 import Transition from '../Transition/transition';
 export const SubMenu = ({ index, title, children, className }) => {
     const context = useContext(MenuContext);
-    const openedSubMenus = context.defaultOpenSubMenus;
+    const openedSubMenus = (context.defaultOpenSubMenus ?? []);
     const isOpend = (index && context.mode === 'vertical') ? openedSubMenus.includes(index) : false;
     const [menuOpen, setOpen] = useState(isOpend);
     const classes = classNames('menu-item submenu-item', className, {
@@ -20,7 +20,8 @@ export const SubMenu = ({ index, title, children, className }) => {
     };
     let timer;
     const handleMouse = (e, toggle) => {
-        clearTimeout(timer);
+        if (timer)
+            clearTimeout(timer);
         e.preventDefault();
         timer = setTimeout(() => {
             setOpen(toggle);

package/build/components/Transition/transition.js

@@ -2,17 +2,9 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useRef } from 'react';
 import { CSSTransition } from 'react-transition-group';
 const Transition = (props) => {
-    const { children, classNames: classNamesProp, animation, wrapper = false, unmountOnExit = true, appear = true, addEndListener, ...restProps } = props;
+    const { children, classNames: classNamesProp, animation, wrapper = false, unmountOnExit = true, appear = true, timeout, ...restProps } = props;
     const cls = animation ? animation : classNamesProp;
     const nodeRef = useRef(null);
-    const transitionProps = {
-        classNames: cls,
-        unmountOnExit,
-        appear,
-        ...restProps,
-    };
-    if (addEndListener)
-        transitionProps.addEndListener = addEndListener;
-    return (_jsx(CSSTransition, { nodeRef: nodeRef, ...transitionProps, children: _jsx("div", { ref: nodeRef, "data-transition-wrapper": wrapper ? 'true' : 'false', children: children }) }));
+    return (_jsx(CSSTransition, { nodeRef: nodeRef, classNames: cls, unmountOnExit: unmountOnExit, appear: appear, timeout: timeout, ...restProps, children: _jsx("div", { ref: nodeRef, "data-transition-wrapper": wrapper ? 'true' : 'false', children: children }) }));
 };
 export default Transition;

package/build/components/Transition/transition.types.d.ts

@@ -1,10 +1,9 @@
 import type { ReactNode } from 'react';
 import type { CSSTransitionProps } from 'react-transition-group/CSSTransition';
 export type AnimationName = 'zoom-in-top' | 'zoom-in-left' | 'zoom-in-bottom' | 'zoom-in-right';
-export type TransitionProps = Omit<CSSTransitionProps<HTMLElement>, 'addEndListener' | 'timeout'> & {
+export type TransitionProps = Omit<CSSTransitionProps<HTMLElement>, 'timeout'> & {
     animation?: AnimationName;
     wrapper?: boolean;
     children?: ReactNode;
-    timeout: CSSTransitionProps<HTMLElement>['timeout'];
-    addEndListener?: (node: HTMLElement, done: () => void) => void;
+    timeout: NonNullable<CSSTransitionProps<HTMLElement>['timeout']>;
 };

package/build/components/Upload/upload.js

@@ -68,7 +68,7 @@ export const Upload = (props) => {
     // （beforeUpload： “上传前钩子”）
     const uploadFiles = (files, test) => {
         // 传来的文件列表 FileList类型，不是数组  =》 转为数组
-        let postFiles = Array.from(files);
+        const postFiles = Array.from(files);
         // 
         if (test) {
             console.log('drag', postFiles[0]);
@@ -103,7 +103,7 @@ export const Upload = (props) => {
     // 函数： 发axios请求
     const post = (file) => {
         // 改造浏览器原生File，创建 内部文件对象 `_file` （文件本体 + 上传状态）
-        let _file = {
+        const _file = {
             uid: Date.now() + 'upload-file',
             status: 'ready',
             name: file.name,

package/build/components/Upload/upload.types.d.ts

@@ -6,8 +6,8 @@ export interface UploadFile {
     status?: UploadFileStatus;
     percent: number;
     raw?: File;
-    response?: any;
-    error?: any;
+    response?: unknown;
+    error?: unknown;
 }
 export interface UploadProps {
     /** 必选参数, 上传的地址 */
@@ -19,23 +19,19 @@ export interface UploadProps {
     /** 文件上传时的钩子 */
     onProgress?: (percentage: number, file: UploadFile) => void;
     /** 文件上传成功时的钩子 */
-    onSuccess?: (data: any, file: UploadFile) => void;
+    onSuccess?: (data: unknown, file: UploadFile) => void;
     /** 文件上传失败时的钩子 */
-    onError?: (err: any, file: UploadFile) => void;
+    onError?: (err: unknown, file: UploadFile) => void;
     /** 文件状态改变时的钩子，上传成功或者失败时都会被调用 */
     onChange?: (file: UploadFile) => void;
     /** 文件列表移除文件时的钩子 */
     onRemove?: (file: UploadFile) => void;
     /** 设置上传的请求头部 */
-    headers?: {
-        [key: string]: any;
-    };
+    headers?: Record<string, string>;
     /** 上传的文件字段名 */
     name?: string;
     /** 上传时附带的额外参数 */
-    data?: {
-        [key: string]: any;
-    };
+    data?: Record<string, string>;
     /** 是否发送 cookie 凭证信息 */
     withCredentials?: boolean;
     /** 可选参数, 接受上传的文件类型 */

package/build/hooks/useClickOutside.d.ts

@@ -1,3 +1,3 @@
-import type { RefObject } from 'react';
-declare function useClickOutside<T extends HTMLElement>(ref: RefObject<T | null>, handler: (event: MouseEvent) => void): void;
+import type { RefObject } from "react";
+declare function useClickOutside<T extends HTMLElement>(ref: RefObject<T | null>, handler: (event: MouseEvent) => void, eventType?: "click" | "mousedown"): void;
 export default useClickOutside;

package/build/hooks/useClickOutside.js

@@ -1,18 +1,38 @@
-import { useEffect } from 'react';
-function useClickOutside(ref, handler) {
+// “点击某个区域外面时，执行一些事情。”
+/*监听整个页面点击，
+   -如果点击目标不在 ref 指向的 DOM 里，就执行回调。
+*/
+import { useEffect, useRef } from "react";
+function useClickOutside(ref, handler, eventType = "click") {
+    const handlerRef = useRef(handler);
     useEffect(() => {
+        handlerRef.current = handler;
+    }, [handler]);
+    useEffect(() => {
+        // 监听 document 的 click 事件
+        // 点击回调：页面每次被点击时，要执行的函数
         const listener = (event) => {
+            // 拿到真实 边界DOM
             const el = ref?.current;
+            // 空值保护： 当前拿不到 DOM，直接return
             if (!el)
                 return;
+            // 点击发生在组件内部, 直接return
+            /*
+                event.target:  实际点到的元素
+                el.contains：DOM 原生 API，判断 el元素是否包含某个节点
+            */
+            // 复杂场景下如果下拉框通过 portal 渲染到 body 等其他 DOM 树中，单纯依赖 contains 判断可能不够，需要更通用的命中判断策略
             if (el.contains(event.target))
                 return;
-            handler(event);
+            handlerRef.current(event); // 执行回调函数
         };
-        document.addEventListener('click', listener);
+        // 监听挂在 document整个页面上
+        document.addEventListener(eventType, listener);
+        // 清理函数: 卸载组件时，移除监听（防止内存泄漏/重复监听）
         return () => {
-            document.removeEventListener('click', listener);
+            document.removeEventListener(eventType, listener);
         };
-    }, [ref, handler]);
+    }, [ref, eventType]);
 }
 export default useClickOutside;

package/build/hooks/useDebounce.d.ts

@@ -1,2 +1,2 @@
-declare function useDebounce(value: any, delay?: number): any;
+declare function useDebounce<T>(value: T, delay?: number): T;
 export default useDebounce;

package/build/hooks/useDebounce.js

@@ -1,10 +1,24 @@
-import { useState, useEffect } from 'react';
+/*
+防抖（debounce）Hook:
+  -频繁触发的操作 → 只在最后一次停顿后执行
+  - 只要输入还在继续，就一直取消定时器；
+  - 只有用户停下来 delay 毫秒，才把值更新出去。
+
+  若后续常用于对象 / 数组：
+  可以配合 useMemo 或 useCallback 使用，减少下游无谓重渲
+*/
+import { useState, useEffect } from "react";
 function useDebounce(value, delay = 300) {
+    // 初始值为 value
     const [debouncedValue, setDebouncedValue] = useState(value);
+    // 当 value值与 delay改变时，执行
     useEffect(() => {
+        // 启动一个定时器，300ms后执行
         const handler = window.setTimeout(() => {
             setDebouncedValue(value);
         }, delay);
+        // 清理函数：value 又变了，就取消上一次定时器
+        // 只要一直触发，就一直取消；直到停下来，才执行最后一次。
         return () => {
             clearTimeout(handler);
         };

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "@aozi6666/bee-design",
   "private": false,
-  "version": "0.1.0",
+  "version": "0.1.2",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aozi6666/Bee-Design.git"
+  },
+  "homepage": "https://github.com/aozi6666/Bee-Design",
+  "bugs": {
+    "url": "https://github.com/aozi6666/Bee-Design/issues"
+  },
   "type": "module",
   "files": [
     "build",
@@ -12,37 +20,54 @@
   "types": "build/index.d.ts",
   "scripts": {
     "dev": "vite",
-    "clean":"rimraf ./build",
+    "clean": "rimraf ./build",
+    "lint": "eslint --ext js,ts,tsx src --max-warnings 5",
+    "lint:fix": "npm run lint -- --fix",
+    "stylelint": "stylelint \"src/**/*.{css,scss}\"",
+    "stylelint:fix": "npm run stylelint -- --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint:staged": "lint-staged",
     "build": "npm run clean && npm run build-ts && npm run build-css",
-    "build:site": "vite build",
     "build-ts": "tsc -p tsconfig.build.json",
     "build-css": "sass ./src/styles/index.scss ./build/index.css",
     "webpack:dev": "webpack",
     "webpack:build": "NODE_ENV=production webpack",
-    "lint": "eslint .",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build",
+    "build:site": "vite build",
     "preview": "vite preview",
     "test": "jest",
-    "storybook": "storybook dev -p 6006",
-    "build-storybook": "storybook build"
+    "test:ci": "cross-env CI=true jest",
+    "prepublishOnly": "npm run test:ci && npm run lint && npm run build",
+    "prepare": "husky"
+  },
+  "lint-staged": {
+    "*.{js,jsx,ts,tsx}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{css,scss}": [
+      "stylelint --fix",
+      "prettier --write"
+    ],
+    "*.{json,md,mdx,yml,yaml}": [
+      "prettier --write"
+    ]
+  },
+  "peerDependencies": {
+    "react": "^18 || ^19",
+    "react-dom": "^18 || ^19"
   },
   "dependencies": {
     "@fortawesome/fontawesome-svg-core": "^6.7.2",
     "@fortawesome/free-solid-svg-icons": "^6.7.2",
     "@fortawesome/react-fontawesome": "^3.2.0",
-    "@types/classnames": "^2.3.0",
-    "@types/jest": "^30.0.0",
-    "@types/react-transition-group": "^4.4.12",
     "axios": "^1.13.6",
     "classnames": "^2.5.1",
-    "css-loader": "^7.1.4",
-    "html-webpack-plugin": "^5.6.6",
+    "cross-env": "^10.1.0",
     "lodash": "^4.17.23",
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
-    "react-transition-group": "^4.4.5",
-    "rimraf": "^6.1.3",
-    "style-loader": "^4.0.0",
-    "webpack-dev-server": "^5.2.3"
+    "react-transition-group": "^4.4.5"
   },
   "devDependencies": {
     "@chromatic-com/storybook": "^5.0.1",
@@ -56,24 +81,41 @@
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",
+    "@types/classnames": "^2.3.0",
+    "@types/jest": "^30.0.0",
     "@types/node": "^24.10.1",
     "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
+    "@types/react-transition-group": "^4.4.12",
     "@vitejs/plugin-react": "^5.1.1",
     "@vitest/browser-playwright": "^4.0.18",
     "@vitest/coverage-v8": "^4.0.18",
+    "css-loader": "^7.1.4",
     "eslint": "^9.39.1",
     "eslint-plugin-react-hooks": "^7.0.1",
     "eslint-plugin-react-refresh": "^0.4.24",
     "eslint-plugin-storybook": "^10.2.17",
     "globals": "^16.5.0",
+    "html-webpack-plugin": "^5.6.6",
+    "husky": "^9.1.7",
     "jest": "^30.3.0",
     "jest-environment-jsdom": "^30.3.0",
     "playwright": "^1.58.2",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "rimraf": "^6.1.3",
     "sass": "^1.97.3",
     "sass-embedded": "^1.97.3",
     "storybook": "^10.2.17",
+    "style-loader": "^4.0.0",
+    "stylelint": "^17.4.0",
+    "stylelint-config-standard": "^40.0.0",
+    "stylelint-config-standard-scss": "^16.0.0",
+    "stylelint-scss": "^7.0.0",
     "terser-webpack-plugin": "^5.4.0",
+    "postcss-scss": "^4.0.9",
+    "prettier": "3.8.1",
+    "lint-staged": "^16.4.0",
     "ts-jest": "^29.4.6",
     "ts-loader": "^9.5.4",
     "typescript": "~5.9.3",
@@ -81,7 +123,8 @@
     "vite": "^7.3.1",
     "vitest": "^4.0.18",
     "webpack": "^5.105.4",
-    "webpack-cli": "^7.0.0"
+    "webpack-cli": "^7.0.0",
+    "webpack-dev-server": "^5.2.3"
   },
   "jest": {
     "preset": "ts-jest/presets/default-esm",