@sunyard-szyy-ui/hooks 0.2.6 → 0.2.8

package/README.md

@@ -0,0 +1,233 @@
+# @sunyard-szyy-ui/hooks
+
+> Composition API Hooks - Vue 3 组合式 API 工具集
+
+## 📦 安装
+
+```bash
+# 推荐使用主包
+npm install sunyard-szyy-ui
+
+# 或者单独安装
+npm install @sunyard-szyy-ui/hooks
+```
+
+## 🎣 Hooks 列表
+
+### useNamespace
+
+BEM 命名空间工具，用于生成标准的 CSS 类名。
+
+**特性：**
+
+- ✅ 支持 BEM 命名规范
+- ✅ 自动添加前缀（默认 `sy-`）
+- ✅ 类型安全
+
+**使用示例：**
+
+```typescript
+import { useNamespace } from '@sunyard-szyy-ui/hooks';
+
+const ns = useNamespace('button');
+
+// Block
+ns.b(); // 'sy-button'
+
+// Element
+ns.e('icon'); // 'sy-button__icon'
+
+// Modifier
+ns.m('primary'); // 'sy-button--primary'
+
+// Block + Modifier
+ns.bm('large'); // 'sy-button sy-button--large'
+
+// Element + Modifier
+ns.em('icon', 'disabled'); // 'sy-button__icon sy-button__icon--disabled'
+
+// 状态
+ns.is('active'); // 'is-active'
+ns.is('disabled', true); // 'is-disabled'
+```
+
+### useDebounce
+
+防抖 Hook，用于防抖响应式值。
+
+**特性：**
+
+- ✅ 响应式防抖
+- ✅ 自动清理定时器
+- ✅ 支持自定义延迟
+
+**使用示例：**
+
+```typescript
+import { ref } from 'vue';
+import { useDebounce } from '@sunyard-szyy-ui/hooks';
+
+const input = ref('');
+const debouncedInput = useDebounce(input, 500);
+
+// input 变化后，debouncedInput 会在 500ms 后更新
+watch(debouncedInput, value => {
+  console.log('防抖后的值:', value);
+});
+```
+
+### useToggle
+
+切换布尔值的 Hook。
+
+**特性：**
+
+- ✅ 简化布尔值状态管理
+- ✅ 提供切换和设置方法
+- ✅ 类型安全
+
+**使用示例：**
+
+```typescript
+import { useToggle } from '@sunyard-szyy-ui/hooks';
+
+const { value: isOpen, toggle, setValue } = useToggle(false);
+
+// 切换
+toggle(); // isOpen.value = true
+toggle(); // isOpen.value = false
+
+// 设置特定值
+setValue(true); // isOpen.value = true
+```
+
+### useLocalStorage
+
+本地存储 Hook，支持响应式和跨标签页同步。
+
+**特性：**
+
+- ✅ 响应式本地存储
+- ✅ 自动序列化/反序列化
+- ✅ 跨标签页同步
+- ✅ TypeScript 类型支持
+
+**使用示例：**
+
+```typescript
+import { useLocalStorage } from '@sunyard-szyy-ui/hooks';
+
+// 基础用法
+const { value, setValue } = useLocalStorage('user', { name: 'Alice' });
+
+// 修改值（自动同步到 localStorage）
+setValue({ name: 'Bob' });
+
+// 响应式更新
+watch(value, newVal => {
+  console.log('用户信息变更:', newVal);
+});
+```
+
+## 🎯 使用方式
+
+### 方式一：从主包导入（推荐）
+
+```typescript
+import { useNamespace, useDebounce } from 'sunyard-szyy-ui';
+```
+
+### 方式二：从 Hooks 包导入
+
+```typescript
+import { useNamespace, useDebounce } from '@sunyard-szyy-ui/hooks';
+```
+
+### 方式三：直接从文件导入
+
+```typescript
+import { useNamespace } from '@sunyard-szyy-ui/hooks/use-namespace';
+```
+
+## 📖 完整 API
+
+| Hook              | 说明         | 参数                           | 返回值                        |
+| ----------------- | ------------ | ------------------------------ | ----------------------------- |
+| `useNamespace`    | BEM 命名工具 | `block: string`                | 命名空间方法对象              |
+| `useDebounce`     | 防抖值       | `value: Ref<T>, delay: number` | `Ref<T>`                      |
+| `useToggle`       | 布尔值切换   | `initialValue?: boolean`       | `{ value, toggle, setValue }` |
+| `useLocalStorage` | 本地存储     | `key: string, defaultValue: T` | `{ value, setValue }`         |
+
+## 🔧 开发
+
+```bash
+# 安装依赖
+pnpm install
+
+# 类型检查
+pnpm typecheck
+
+# 构建
+pnpm build
+
+# 清理构建产物
+pnpm clean
+```
+
+## 📦 构建产物
+
+```
+@sunyard-szyy-ui/hooks/
+└── dist/
+    ├── index.js        # ESM 格式
+    ├── index.cjs       # CJS 格式
+    ├── index.d.ts      # TypeScript 类型定义
+    └── index.d.cts     # CJS 类型定义
+```
+
+## 🤝 依赖
+
+- `@sunyard-szyy-ui/utils` - 工具函数
+- `vue` (peer) - Vue 3 框架
+
+## 📝 注意事项
+
+1. **Vue 3 专用**：所有 Hooks 基于 Vue 3 Composition API
+2. **自动清理**：Hooks 会在组件卸载时自动清理副作用
+3. **类型安全**：完整的 TypeScript 类型支持
+4. **Tree-shaking**：支持按需导入，减少打包体积
+
+## 💡 最佳实践
+
+### 1. 在 setup 中使用
+
+```typescript
+export default defineComponent({
+  setup() {
+    const ns = useNamespace('my-component');
+    const debouncedValue = useDebounce(inputValue, 300);
+
+    return { ns, debouncedValue };
+  }
+});
+```
+
+### 2. 结合响应式 API
+
+```typescript
+const input = ref('');
+const debouncedInput = useDebounce(input, 500);
+
+watchEffect(() => {
+  // 在这里使用防抖后的值
+  console.log(debouncedInput.value);
+});
+```
+
+### 3. 组合多个 Hooks
+
+```typescript
+const ns = useNamespace('form');
+const { value: isValid, toggle: toggleValid } = useToggle(false);
+const { value: formData, setValue } = useLocalStorage('form-draft', {});
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sunyard-szyy-ui/hooks",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -21,7 +21,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@sunyard-szyy-ui/utils": "0.2.6"
+    "@sunyard-szyy-ui/utils": "0.2.8"
   },
   "scripts": {
     "clean": "rimraf dist",