@allkit/use 0.0.1 → 0.0.3

package/dist/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@allkit/use",
-    "version": "0.0.1",
-    "description": "this is a vue3use package",
+    "version": "0.0.3",
+    "description": "this is a vue3 use package",
     "type": "module",
     "main": "./shared.umd.js",
     "module":"./shared.es.js",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@allkit/use",
-  "version": "0.0.1",
-  "description": "this is a vue3use package",
+  "version": "0.0.3",
+  "description": "this is a vue3 use package",
   "main": "./src/index.ts",
   "module": "./src/index.ts",
   "type": "module",

package/scripts/build.mjs

@@ -7,7 +7,7 @@ import fse from 'fs-extra'
 import { build } from 'vite'
 import { viteLibConfig } from '@allkit/vite-config'
 
-const { outputFile } = fse
+const { outputFile, copy } = fse
 
 const require = createRequire(import.meta.url)
 
@@ -86,14 +86,17 @@ const buildAll = async () => {
 // copy文件
 // README.md
 // 样式 index.css
-const copyFiles = () => {
+// skills 目录
+const copyFiles = async () => {
   const markdown = createReadStream(resolve(__dirname, '../README.md'))
   markdown.pipe(createWriteStream(resolve(__dirname, '../dist/README.md')))
+
+  await copy(resolve(__dirname, '../skills'), resolve(__dirname, '../dist/skills'))
 }
 
 const buildLib = async () => {
   await buildAll()
-  copyFiles()
+  await copyFiles()
 }
 
 buildLib()

package/skills/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: use
+description: Vue 3 组合式 API 工具函数库，提供状态管理、事件监听和常用 UI 模式 / Vue 3 Composition API hooks library
+author: allkit
+category: vue
+---
+
+# @allkit/use
+
+Vue 3 组合式 API 工具函数库
+
+## Install
+
+```bash
+pnpm add @allkit/use
+```
+
+## Hooks
+
+| Hook | Description |
+|------|-------------|
+| [defineCtxState](./references/defineCtxState.md) | 定义组件作用域共享数据 |
+| [useCtxState](./references/useCtxState.md) | 获取共享数据 |
+| [useEventListener](./references/useEventListener.md) | 事件监听 |
+| [usePageVisibility](./references/usePageVisibility.md) | 页面可见性 |
+| [useScroll](./references/useScroll.md) | 滚动监听 |
+| [onMountedOrActivated](./references/onMountedOrActivated.md) | keep-alive 组件初始化 |
+
+## Usage
+
+```ts
+import { defineCtxState, useCtxState, useEventListener } from '@allkit/use'
+
+const [state, setState] = defineCtxState({
+  loading: false,
+  list: []
+})
+
+useEventListener('scroll', handleScroll)
+```

package/skills/examples/demo.tsx

@@ -0,0 +1,83 @@
+import { defineComponent, ref, computed } from 'vue'
+import {
+  defineCtxState,
+  useCtxState,
+  useEventListener,
+  usePageVisibility,
+  useScroll,
+  onMountedOrActivated
+} from '@allkit/use'
+
+interface UserListState {
+  loading: boolean
+  list: Array<{ id: number; name: string }>
+  pagination: { current: number; size: number; total: number }
+}
+
+const useSearchForm = () => {
+  const [state, setState] = useCtxState<UserListState>()
+
+  const handleSearch = () => {
+    setState(s => {
+      s.loading = true
+      s.pagination.current = 1
+    })
+  }
+
+  return () => (
+    <div className="search-form">
+      <button onClick={handleSearch} disabled={state.loading}>
+        {state.loading ? '搜索中...' : '搜索'}
+      </button>
+    </div>
+  )
+}
+
+const useList = () => {
+  const [state, setState] = useCtxState<UserListState>()
+
+  return () => (
+    <div className="user-list">
+      {state.list.map(item => (
+        <div key={item.id}>{item.name}</div>
+      ))}
+    </div>
+  )
+}
+
+export default defineComponent({
+  setup() {
+    const [state, setState] = defineCtxState<UserListState>({
+      loading: false,
+      list: [],
+      pagination: { current: 1, size: 20, total: 0 }
+    })
+
+    const renderSearch = useSearchForm()
+    const renderList = useList()
+
+    useEventListener('resize', () => {
+      console.log('window resized')
+    })
+
+    const { onPageShow, onPageHidden } = usePageVisibility()
+    onPageShow(() => console.log('page show'))
+    onPageHidden(() => console.log('page hidden'))
+
+    const { y, arrivedState } = useScroll(window, { throttle: 100 })
+    const isBottom = computed(() => arrivedState.bottom)
+
+    onMountedOrActivated(() => {
+      console.log('mounted or activated')
+    })
+
+    return () => (
+      <div>
+        {renderSearch()}
+        {renderList()}
+        <p>scroll: {Math.round(y.value)}px</p>
+        <p>bottom: {isBottom.value ? 'yes' : 'no'}</p>
+      </div>
+    )
+  }
+})

package/skills/references/defineCtxState.md

@@ -0,0 +1,61 @@
+# defineCtxState
+
+定义当前组件作用域的共享数据，配合 `useCtxState` 在子 hooks 中获取。
+
+## Type Signature
+
+```ts
+type DeepPartial<T> = {
+  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P]
+}
+
+type IStateTuple<T> = readonly [
+  Readonly<T>,
+  (state: DeepPartial<T> | ((newState: T) => void)) => void,
+]
+
+function defineCtxState<T extends Record<string, any>>(data: T): IStateTuple<T>
+```
+
+## Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `data` | `T` | 需要共享的初始数据 |
+
+## Returns
+
+返回元组 `[state, setState]`:
+- `state`: 共享数据的只读代理
+- `setState`: 更新共享数据的方法
+
+## Example
+
+```ts
+import { defineCtxState } from '@allkit/use'
+
+const [state, setState] = defineCtxState({
+  listLoading: false,
+  userList: [],
+  pagination: {
+    current: 1,
+    size: 20,
+    total: 0
+  }
+})
+
+// 对象写法
+setState({ listLoading: true })
+
+// 函数写法
+setState((state) => {
+  state.listLoading = true
+  state.pagination.current = 2
+})
+```
+
+## Use Cases
+
+- 功能模块入口页面需要与多个子 hooks 共享状态
+- 避免通过 props 层层传递数据
+- 实现 hooks 之间的数据通信

package/skills/references/onMountedOrActivated.md

@@ -0,0 +1,33 @@
+# onMountedOrActivated
+
+在 `mounted` 或 `activated` (keep-alive 缓存激活) 时执行回调。
+
+## Type Signature
+
+```ts
+function onMountedOrActivated(hook: () => any): void
+```
+
+## Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `hook` | `() => any` | 要执行的回调函数 |
+
+## Example
+
+```ts
+import { onMountedOrActivated } from '@allkit/use'
+
+// 在 mounted 和每次 activated 时执行
+onMountedOrActivated(() => {
+  console.log('组件已挂载或激活')
+  // 刷新数据等操作
+})
+```
+
+## Use Cases
+
+- keep-alive 缓存组件需要在每次激活时刷新数据
+- 需要在 mounted 和 activated 时都执行的初始化逻辑
+- 配合 `useEventListener` 实现事件监听的自动管理

package/skills/references/useCtxState.md

@@ -0,0 +1,36 @@
+# useCtxState
+
+获取当前组件作用域 `defineCtxState` 定义的共享数据。
+
+## Type Signature
+
+```ts
+function useCtxState<T = Record<string, any>>(): IStateTuple<T>
+```
+
+## Returns
+
+返回元组 `[state, setState]`，与 `defineCtxState` 相同。
+
+## Example
+
+```ts
+import { useCtxState } from '@allkit/use'
+
+export const useList = () => {
+  const [state, setState] = useCtxState<ListState>()
+
+  const handleReset = () => {
+    setState((state) => {
+      state.searchForm = {}
+    })
+  }
+
+  return () => <div>{state.userList.length}</div>
+}
+```
+
+## Notes
+
+- 必须在 `setup()` 函数中调用
+- 只能获取同一组件实例中 `defineCtxState` 定义的数据

package/skills/references/useEventListener.md

@@ -0,0 +1,65 @@
+# useEventListener
+
+事件监听，支持 Vue 缓存（keep-alive），页面销毁自动回收。
+
+## Type Signature
+
+```ts
+type UseEventListenerOptions = {
+  target?: TargetRef
+  capture?: boolean
+  passive?: boolean
+}
+
+function useEventListener<K extends keyof DocumentEventMap>(
+  type: K,
+  listener: (event: DocumentEventMap[K]) => void,
+  options?: UseEventListenerOptions,
+): () => void
+```
+
+## Parameters
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `string` | - | 事件类型 (scroll, resize, click 等) |
+| `listener` | `EventListener` | - | 监听函数 |
+| `options.target` | `TargetRef` | `window` | 监听目标 |
+| `options.capture` | `boolean` | `false` | 是否捕获 |
+| `options.passive` | `boolean` | `false` | 是否被动 |
+
+## Returns
+
+返回清理函数，调用后移除事件监听。
+
+## Example
+
+```ts
+import { useEventListener } from '@allkit/use'
+
+// 监听 window 滚动
+const cleanup = useEventListener('scroll', () => {
+  console.log('scrolling')
+})
+
+// 监听指定元素
+const boxRef = ref<HTMLElement>()
+useEventListener('click', (e) => {
+  console.log('clicked', e)
+}, { target: boxRef })
+
+// 监听键盘事件
+useEventListener('keydown', (e: KeyboardEvent) => {
+  if (e.key === 'Escape') {
+    // handle escape
+  }
+})
+
+// 组件卸载时自动清理
+```
+
+## Use Cases
+
+- 监听 window/document 事件（resize、scroll、keydown 等）
+- 监听 DOM 元素事件
+- keep-alive 组件需要自动添加/移除事件监听

package/skills/references/usePageVisibility.md

@@ -0,0 +1,45 @@
+# usePageVisibility
+
+判断页面是否可见或不可见，用于处理用户切换标签页的场景。
+
+## Type Signature
+
+```ts
+function usePageVisibility(): {
+  onPageShow: (cb: () => void) => void
+  onPageHidden: (cb: () => void) => void
+}
+```
+
+## Returns
+
+| Method | Description |
+|--------|-------------|
+| `onPageShow` | 页面显示时执行的回调 |
+| `onPageHidden` | 页面隐藏时执行的回调 |
+
+## Example
+
+```ts
+import { usePageVisibility } from '@allkit/use'
+
+const { onPageShow, onPageHidden } = usePageVisibility()
+
+// 页面显示可见
+onPageShow(() => {
+  console.log('页面可见')
+  // 恢复轮询、视频播放等
+})
+
+// 页面隐藏
+onPageHidden(() => {
+  console.log('页面隐藏')
+  // 暂停轮询、视频播放等
+})
+```
+
+## Use Cases
+
+- 用户切换浏览器标签页时暂停/恢复操作
+- 页面隐藏时停止轮询请求，显示时恢复
+- 视频播放器在页面隐藏时自动暂停

package/skills/references/useScroll.md

@@ -0,0 +1,90 @@
+# useScroll
+
+监听页面布局滚动事件，提供滚动位置、方向、状态等信息。
+
+## Type Signature
+
+```ts
+interface UseScrollOptions {
+  throttle?: number
+  idle?: number
+  offset?: {
+    left?: number
+    right?: number
+    top?: number
+    bottom?: number
+  }
+  onScroll?: (e: Event) => void
+  onStop?: (e: Event) => void
+  eventListenerOptions?: AddEventListenerOptions
+  behavior?: ScrollBehavior
+  onError?: (error: unknown) => void
+}
+
+function useScroll(
+  element: MaybeElementRef<MaybeElement>,
+  options?: UseScrollOptions
+): {
+  x: ComputedRef<number>
+  y: ComputedRef<number>
+  isScrolling: Ref<boolean>
+  arrivedState: Reactive<{ left: boolean; right: boolean; top: boolean; bottom: boolean }>
+  directions: Reactive<{ left: boolean; right: boolean; top: boolean; bottom: boolean }>
+  measure: () => void
+}
+```
+
+## Parameters
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `element` | `MaybeElementRef` | - | 监听的元素，支持 window、document、HTMLElement 及 Ref |
+| `options.throttle` | `number` | `0` | 节流时间 |
+| `options.idle` | `number` | `200` | 滚动结束检测时间 |
+| `options.offset` | `object` | `{}` | 边界偏移 |
+| `options.onScroll` | `function` | - | 滚动时回调 |
+| `options.onStop` | `function` | - | 滚动结束时回调 |
+
+## Returns
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `x` | `ComputedRef<number>` | 水平滚动距离 |
+| `y` | `ComputedRef<number>` | 垂直滚动距离 |
+| `isScrolling` | `Ref<boolean>` | 是否正在滚动 |
+| `arrivedState` | `Reactive` | 是否到达边界 `{ left, right, top, bottom }` |
+| `directions` | `Reactive` | 滚动方向 `{ left, right, top, bottom }` |
+| `measure` | `function` | 手动测量滚动状态 |
+
+## Example
+
+```ts
+import { useScroll } from '@allkit/use'
+
+// 监听 window 滚动
+const { y, isScrolling, arrivedState } = useScroll(window)
+
+// 监听指定元素
+const containerRef = ref<HTMLElement>()
+const scrollState = useScroll(containerRef, {
+  throttle: 100,
+  onScroll: (e) => {
+    console.log('scrolling')
+  },
+  onStop: (e) => {
+    console.log('scroll stopped')
+  }
+})
+
+// 判断是否滚动到底部
+if (arrivedState.bottom) {
+  // 加载更多数据
+}
+```
+
+## Use Cases
+
+- 无限滚动列表，滚动到底部加载更多
+- 吸顶导航栏，滚动超过一定距离显示
+- 滚动进度指示器
+- 虚拟列表滚动位置追踪