@allkit/use 0.0.1

package/skill/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/skill/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/skill/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/skill/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/skill/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/skill/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
+
+- 无限滚动列表，滚动到底部加载更多
+- 吸顶导航栏，滚动超过一定距离显示
+- 滚动进度指示器
+- 虚拟列表滚动位置追踪

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './useCtxState'
+export * from './usePageVisibility'
+export * from './useEventListener'
+export * from './useScroll'
+export * from './onMountedOrActivated'

package/src/onMountedOrActivated/index.ts

@@ -0,0 +1,18 @@
+import { nextTick, onMounted, onActivated } from 'vue'
+
+export function onMountedOrActivated(hook: () => any) {
+  let mounted: boolean
+
+  onMounted(() => {
+    hook()
+    nextTick(() => {
+      mounted = true
+    })
+  })
+
+  onActivated(() => {
+    if (mounted) {
+      hook()
+    }
+  })
+}

package/src/types.ts

@@ -0,0 +1,23 @@
+import { type MaybeRef, type ComponentPublicInstance, type MaybeRefOrGetter } from 'vue'
+
+export interface ConfigurableWindow {
+  /*
+   * Specify a custom `window` instance, e.g. working with iframes or in testing environments.
+   */
+  window?: Window
+}
+
+export interface ConfigurableDocument {
+  /*
+   * Specify a custom `document` instance, e.g. working with iframes or in testing environments.
+   */
+  document?: Document
+}
+
+export type VueInstance = ComponentPublicInstance
+export type MaybeElement = Window | Document | HTMLElement | SVGElement | undefined | null
+
+export type MaybeElementRef<T extends MaybeElement = MaybeElement> = MaybeRef<T>
+export type MaybeComputedElementRef<T extends MaybeElement = MaybeElement> = MaybeRefOrGetter<T>
+
+export type TargetRef = MaybeElementRef<MaybeElement> | MaybeRef<EventTarget>

package/src/useCtxState/index.ts

@@ -0,0 +1,87 @@
+import { getCurrentInstance, reactive } from 'vue'
+import type { ComponentInternalInstance } from 'vue'
+
+type CtxComponentInternalInstance = ComponentInternalInstance & {
+  provides: Record<string, any>
+  type: {
+    name?: string
+    __scopeId?: string
+    __name?: string
+  }
+}
+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,
+]
+/**
+ * 定义当前组件作用域的共享数据
+ * @param data - 需要共享的数据
+ * @returns  [state, setState]
+ * @example
+ * ```ts
+ * // state: 共享数据的只读代理
+ * const [state, setState] = defineCtxState({ count: 0 })
+ *
+ * //setState: 更新共享数据的方法,会合并旧数据
+ * setState({ count: 2 })
+ * //推荐函数写法
+ * setState((state) => {state.count = 2})
+ *
+ * ```
+ *
+ */
+export const defineCtxState = <T extends Record<string, any>>(data: T) => {
+  const state = reactive(data) as T
+  const setState = (newState: DeepPartial<T> | ((newState: T) => void)) => {
+    if (typeof newState === 'function') {
+      newState(state as T)
+      return
+    }
+    Object.assign(state, newState)
+  }
+  const stateTuple = [state as T, setState] as const
+  const instance = getCurrentInstance() as CtxComponentInternalInstance
+  if (!instance) {
+    console.error('useCtxState must be called within a setup function')
+    return stateTuple
+  }
+  const { provides = {}, uid, type } = instance
+  const key = `state_${uid}_${type.name || type.__name || ''}`
+  provides[key] = stateTuple
+  return stateTuple
+}
+
+/**
+ * 获取当前组件作用域{@link defineCtxState}定义的共享数据
+ *
+ * @see defineCtxState
+ * @returns  [state, setState]
+ * @example
+ *
+ * ```ts
+ * // state: 共享数据的只读代理
+ * const [state, setState] = usCtxState({ count: 0 })
+ *
+ * //setState: 更新共享数据的方法
+ * setState({ count: 2 })
+ * setState((state) => {state.count = 2})
+ *
+ * ```
+ *
+ */
+export const useCtxState = <T = Record<string, any>>() => {
+  const instance = getCurrentInstance() as CtxComponentInternalInstance
+  if (!instance) {
+    throw new Error(
+      'useCtxState is called when there is no active component instance to be associated with. Lifecycle injection APIs can only be used during execution of setup()',
+    )
+  }
+  const { provides = {}, uid, type } = instance
+  const key = `state_${uid}_${type.name || type.__name || ''}`
+  const stateTuple = provides[key] || []
+  return stateTuple as IStateTuple<T>
+}

package/src/useEventListener/index.ts

@@ -0,0 +1,91 @@
+import { isRef, onDeactivated, onUnmounted, unref, watch, type WatchStopHandle } from 'vue'
+import { isClient } from '@allkit/shared'
+import { onMountedOrActivated } from '../onMountedOrActivated'
+import { type TargetRef } from '../types'
+
+export type UseEventListenerOptions = {
+  target?: TargetRef
+  capture?: boolean
+  passive?: boolean
+}
+
+export function useEventListener<K extends keyof DocumentEventMap>(
+  type: K,
+  listener: (event: DocumentEventMap[K]) => void,
+  options?: UseEventListenerOptions,
+): () => void
+export function useEventListener(
+  type: string,
+  listener: EventListener,
+  options?: UseEventListenerOptions,
+): () => void
+
+/**
+ * useEventListener 事件监听,支持vue缓存,页面销毁自动回收
+ * @param type - 事件类型(scroll, resize, click, etc.)
+ * @param listener - 监听函数
+ * @param options - 选项
+ */
+export function useEventListener(
+  type: string,
+  listener: EventListener,
+  options: UseEventListenerOptions = {},
+) {
+  if (!isClient) {
+    return
+  }
+
+  const { target = window, passive = false, capture = false } = options
+
+  let cleaned = false
+  let attached: boolean
+
+  const add = (target?: TargetRef) => {
+    if (cleaned) {
+      return
+    }
+
+    const element = unref(target)
+    if (element && !attached) {
+      element.addEventListener(type, listener, {
+        capture,
+        passive,
+      })
+      attached = true
+    }
+  }
+
+  const remove = (target?: TargetRef) => {
+    if (cleaned) {
+      return
+    }
+    const element = unref(target)
+
+    if (element && attached) {
+      element.removeEventListener(type, listener, capture)
+      attached = false
+    }
+  }
+
+  onUnmounted(() => remove(target))
+  onDeactivated(() => remove(target))
+  onMountedOrActivated(() => add(target))
+
+  let stopWatch: WatchStopHandle
+
+  if (isRef(target)) {
+    stopWatch = watch(target, (val, oldVal) => {
+      remove(oldVal)
+      add(val)
+    })
+  }
+
+  /**
+   * Clean up the event listener
+   */
+  return () => {
+    stopWatch?.()
+    remove(target)
+    cleaned = true
+  }
+}

package/src/usePageVisibility/index.ts

@@ -0,0 +1,46 @@
+import { onBeforeUnmount, onMounted } from 'vue'
+
+type visibleCbFunc = () => void
+
+/**
+ * 判断页面是否可见或者不可见
+ * @example
+ * ```ts
+ *   let {onPageShow,onPageHidden}=usePageVisibility()
+ *   //页面显示可见
+ *   onPageShow(()=>{})
+ *   //页面隐藏
+ *   onPageHidden(()=>{})
+ * ```
+ */
+export const usePageVisibility = () => {
+  let onShowCb: visibleCbFunc
+  let onHiddenCb: visibleCbFunc
+  const onPageShow = (cb: visibleCbFunc) => {
+    onShowCb = cb
+  }
+  const onPageHidden = (cb: visibleCbFunc) => {
+    onHiddenCb = cb
+  }
+
+  const onVisibilitychangeListener = () => {
+    if (document.visibilityState === 'hidden') {
+      onHiddenCb && onHiddenCb()
+      return
+    }
+    onShowCb && onShowCb()
+  }
+
+  onMounted(() => {
+    document.addEventListener('visibilitychange', onVisibilitychangeListener)
+  })
+
+  onBeforeUnmount(() => {
+    document.removeEventListener('visibilitychange', onVisibilitychangeListener)
+  })
+
+  return {
+    onPageShow,
+    onPageHidden,
+  }
+}