@guiwzh/small-design 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 guiwzh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,230 @@
+# @guiwz/small-design
+
+一套轻量级 React 组件库，基于 React 18 + TypeScript + SCSS 构建。
+
+## 安装
+
+```bash
+npm install @guiwz/small-design
+```
+
+### Peer Dependencies
+
+需要确保项目中已安装以下依赖：
+
+```bash
+npm install react react-dom
+```
+
+部分组件需要额外依赖（可选）：
+
+```bash
+# Upload 组件需要
+npm install axios
+
+# KeepAlive 组件需要
+npm install react-router-dom
+```
+
+## 使用
+
+```tsx
+import { Button, Menu, AutoComplete } from '@guiwz/small-design'
+import '@guiwz/small-design/dist/index.css'
+```
+
+## 组件列表
+
+### Button
+
+页面中最常用的按钮元素，支持 HTML 中 button 和 a 链接的所有属性。
+
+```tsx
+<Button btnType="primary" size="lg">Primary Button</Button>
+<Button btnType="link" href="https://example.com">Link</Button>
+```
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| btnType | 按钮类型 | `'primary' \| 'default' \| 'danger' \| 'link'` | `'default'` |
+| size | 按钮尺寸 | `'lg' \| 'sm'` | - |
+| disabled | 是否禁用 | `boolean` | `false` |
+| href | 链接地址（btnType 为 link 时生效） | `string` | - |
+
+### Menu
+
+导航菜单，支持横向与纵向两种模式，支持下拉子菜单。
+
+```tsx
+<Menu defaultIndex="0" mode="horizontal" onSelect={(index) => {}}>
+  <Menu.Item>首页</Menu.Item>
+  <Menu.Item>文档</Menu.Item>
+  <Menu.SubMenu title="更多">
+    <Menu.Item>选项一</Menu.Item>
+    <Menu.Item>选项二</Menu.Item>
+  </Menu.SubMenu>
+</Menu>
+```
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| mode | 菜单方向 | `'horizontal' \| 'vertical'` | `'horizontal'` |
+| defaultIndex | 默认激活项索引 | `string` | `'0'` |
+| defaultOpenSubMenus | 默认展开的子菜单（纵向模式） | `string[]` | `[]` |
+| onSelect | 选中回调 | `(index: string, e: MouseEvent) => void` | - |
+
+### AutoComplete
+
+搜索输入框，支持异步建议、防抖、缓存、键盘导航。
+
+```tsx
+<AutoComplete
+  fetchSuggestions={(query) => fetch(`/api/search?q=${query}`).then(r => r.json())}
+  onSelect={(item) => console.log(item)}
+  debounceTime={300}
+/>
+```
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| fetchSuggestions | 获取建议的函数 | `(str: string) => DataSourceType[] \| Promise<DataSourceType[]>` | 必填 |
+| onSelect | 选中建议回调 | `(item: DataSourceType) => void` | - |
+| onChange | 输入变化回调 | `(str: string) => void` | - |
+| onError | 请求错误回调 | `(error: unknown) => void` | - |
+| renderOption | 自定义建议项渲染 | `(item: DataSourceType) => ReactElement` | - |
+| debounceTime | 防抖时间(ms) | `number` | `300` |
+| expireTime | 缓存过期时间(ms) | `number` | `3600000` |
+
+### Upload
+
+文件上传组件，支持点击和拖拽上传，带进度展示和取消功能。
+
+```tsx
+<Upload
+  action="https://api.example.com/upload"
+  onSuccess={(data, file) => {}}
+  onError={(err, file) => {}}
+  multiple
+  drag
+>
+  拖拽文件到此处上传
+</Upload>
+```
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| action | 上传地址 | `string` | 必填 |
+| beforeUpload | 上传前校验 | `(file: File) => boolean \| Promise<File>` | - |
+| onprogress | 上传进度回调 | `(percentage: number, file: UploadFile) => void` | - |
+| onSuccess | 上传成功回调 | `(data: any, file: UploadFile) => void` | - |
+| onError | 上传失败回调 | `(err: any, file: UploadFile) => void` | - |
+| onExceed | 超出限制回调 | `(message: string) => void` | - |
+| drag | 是否启用拖拽上传 | `boolean` | `false` |
+| multiple | 是否支持多文件 | `boolean` | `false` |
+| maxsize | 文件大小限制(MB) | `number` | - |
+| maxnum | 文件数量限制 | `number` | - |
+
+### Icon
+
+基于 FontAwesome 的图标组件，支持主题色。
+
+```tsx
+<Icon icon="coffee" theme="primary" size="2x" />
+```
+
+### Input
+
+增强输入框，支持前缀、后缀和图标。
+
+```tsx
+<Input prepend="https://" append=".com" />
+<Input icon="search" />
+```
+
+### Progress
+
+进度条组件。
+
+```tsx
+<Progress percent={60} theme="success" />
+```
+
+### Signature
+
+基于 Canvas 的手写签名板，支持笔触切换、清除和保存。
+
+```tsx
+<Signature onSave={(dataUrl) => {}} width={400} height={200} />
+```
+
+### VirtualList
+
+虚拟滚动列表，只渲染可视区域内的列表项。
+
+```tsx
+<VirtualList containerHeight={400} itemHeight={50} itemCount={10000}>
+  <MyListItem />
+</VirtualList>
+```
+
+### LazyLoad
+
+懒加载组件，子元素进入可视区域时才渲染。
+
+```tsx
+<LazyLoad>
+  <img src="large-image.jpg" />
+</LazyLoad>
+```
+
+### KeepAlive
+
+路由级组件缓存，类似 Vue 的 `<keep-alive>`。
+
+```tsx
+<KeepAliveLayout keepPaths={['/home', /^\/detail/]}>
+  <Outlet />
+</KeepAliveLayout>
+```
+
+### Transition
+
+动画过渡封装组件。
+
+```tsx
+<Transition in={show} timeout={300} animation="zoom-in-top">
+  <div>内容</div>
+</Transition>
+```
+
+## Hooks
+
+### useDebounce
+
+```tsx
+const debouncedValue = useDebounce(inputValue, 300)
+```
+
+### useClickOutside
+
+```tsx
+const ref = useRef(null)
+useClickOutside(ref, () => { /* 点击外部时触发 */ })
+```
+
+## 开发
+
+```bash
+# 启动开发服务器
+npm start
+
+# 构建库
+npm run build
+
+# 运行测试
+npm test
+```
+
+## License
+
+MIT