chore: 补充部分注释

internal/vite-config/package.json

@@ -46,7 +46,7 @@
     "picocolors": "^1.0.0",
     "pkg-types": "^1.0.2",
     "rollup-plugin-visualizer": "^5.9.0",
-    "sass": "^1.60.0",
+    "sass": "^1.61.0",
     "unocss": "^0.50.6",
     "unplugin-vue-define-options": "^1.3.3",
     "vite-plugin-compression": "^0.5.1",

packages/hooks/src/useAttrs.ts

@@ -1,9 +1,21 @@
 import { type Recordable } from '@vben/types';
-import { getCurrentInstance, reactive, shallowRef, watchEffect } from 'vue';
+import { getCurrentInstance, reactive, type ShallowRef, shallowRef, watchEffect } from 'vue';
 
 interface UseAttrsOptions {
+  /**
+   * 排除监听事件
+   * @default false
+   */
   excludeListeners?: boolean;
+  /**
+   * 排除部分对象 key值
+   * @default []
+   */
   excludeKeys?: string[];
+  /**
+   * 排除默认值 key 值 ['class', 'style']
+   * @default true
+   */
   excludeDefaultKeys?: boolean;
 }
 
@@ -14,12 +26,19 @@ function entries<T>(obj: Recordable<T>): [string, T][] {
   return Object.keys(obj).map((key: string) => [key, obj[key]]);
 }
 
-function useAttrs(options: UseAttrsOptions = {}): Recordable<any> {
+/**
+ * 获取当前组件的 Attrs 属性
+ * @param UseAttrsOptions
+ */
+function useAttrs<T = any>(options: UseAttrsOptions = {}): ShallowRef<Recordable<T>> {
   const instance = getCurrentInstance();
-  if (!instance) return {};
+  const attrs = shallowRef({});
+
+  if (!instance) {
+    return attrs;
+  }
 
   const { excludeListeners = false, excludeKeys = [], excludeDefaultKeys = true } = options;
-  const attrs = shallowRef({});
   const allExcludeKeys = excludeKeys.concat(excludeDefaultKeys ? DEFAULT_EXCLUDE_KEYS : []);
 
   // Since attrs are not reactive, make it reactive instead of doing in `onUpdated` hook for better performance

packages/hooks/src/useRefs.ts

@@ -1,9 +1,19 @@
-import type { Ref } from 'vue';
-import { onBeforeUpdate, shallowRef } from 'vue';
+import { type ComponentPublicInstance, onBeforeUpdate, type Ref, shallowRef } from 'vue';
 
+type SetRefsFunctionRef = Element | ComponentPublicInstance | null;
+
+interface SetRefsFunction {
+  (ref: SetRefsFunctionRef, refs: Record<string, any>): void;
+}
+
+/**
+ * 用于模版循环获取 refs
+ * <div :ref="setRefs(index)"></div>
+ * @returns
+ */
 function useRefs(): {
   refs: Ref<HTMLElement[]>;
-  setRefs: (index: number) => (el: HTMLElement) => void;
+  setRefs: (index: number) => SetRefsFunction;
 } {
   const refs = shallowRef([]) as Ref<HTMLElement[]>;
 
@@ -11,8 +21,8 @@ function useRefs(): {
     refs.value = [];
   });
 
-  const setRefs = (index: number) => (el: HTMLElement) => {
-    refs.value[index] = el;
+  const setRefs = (index: number) => (ref: SetRefsFunctionRef, refs: Record<string, any>) => {
+    refs.value[index] = ref;
   };
 
   return {

packages/hooks/src/useScrollTo.ts

@@ -1,10 +1,23 @@
 import { shallowRef, unref } from 'vue';
 
 interface UseScrollToOptions {
-  el: any;
+  /**
+   * 需要滚动的 el dom节点
+   */
+  el: HTMLElement;
+  /**
+   * 滚动的目标值
+   */
   to: number;
+  /**
+   * 滚动时间
+   */
   duration?: number;
-  callback?: () => any;
+  /**
+   * 执行完成之后的回调函数
+   * @returns
+   */
+  callback?: () => void;
 }
 
 function easeInOutQuad(t: number, b: number, c: number, d: number) {
@@ -20,12 +33,14 @@ function move(el: HTMLElement, amount: number) {
   el.scrollTop = amount;
 }
 
-const position = (el: HTMLElement) => {
-  return el.scrollTop;
-};
+/**
+ * dom节点滚动到指定位置
+ * @param UseScrollToOptions
+ * @returns
+ */
 function useScrollTo({ el, to, duration = 500, callback }: UseScrollToOptions) {
   const isActiveRef = shallowRef(false);
-  const start = position(el);
+  const start = el.scrollTop;
   const change = to - start;
   const increment = 20;
   let currentTime = 0;
@@ -40,11 +55,10 @@ function useScrollTo({ el, to, duration = 500, callback }: UseScrollToOptions) {
     if (currentTime < duration && unref(isActiveRef)) {
       requestAnimationFrame(animateScroll);
     } else {
-      if (callback && typeof callback === 'function') {
-        callback();
-      }
+      callback?.();
     }
   };
+
   const run = () => {
     isActiveRef.value = true;
     animateScroll();

packages/hooks/src/useWindowSizeFn.ts

@@ -2,19 +2,31 @@ import { type AnyFunction } from '@vben/types';
 import { tryOnMounted, tryOnUnmounted, useDebounceFn } from '@vueuse/core';
 
 interface UseWindowSizeOptions {
+  /**
+   * 节流时间
+   * @default 150
+   */
   wait?: number;
-  once?: boolean;
+  /**
+   * 立即执行
+   * @default false
+   */
   immediate?: boolean;
-  listenerOptions?: AddEventListenerOptions | boolean;
+  /**
+   * 只执行一次
+   * @default false
+   */
+  once?: boolean;
 }
 
 function useWindowSizeFn(fn: AnyFunction, options: UseWindowSizeOptions = {}) {
   const { wait = 150, immediate } = options;
+
   let handler = () => {
     fn();
   };
-  const handleSize = useDebounceFn(handler, wait);
-  handler = handleSize;
+
+  handler = useDebounceFn(handler, wait);
 
   const start = () => {
     if (immediate) {

packages/shared/.eslintrc.js

@@ -0,0 +1,4 @@
+module.exports = {
+  root: true,
+  extends: ['@vben/eslint-config/strict'],
+};

packages/shared/build.config.ts

@@ -0,0 +1,10 @@
+import { defineBuildConfig } from 'unbuild';
+
+export default defineBuildConfig({
+  clean: true,
+  entries: ['src/index'],
+  declaration: true,
+  rollup: {
+    emitCJS: true,
+  },
+});

packages/shared/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@vben/shared",
+  "version": "1.0.0",
+  "homepage": "https://github.com/vbenjs/vue-vben-admin",
+  "bugs": {
+    "url": "https://github.com/vbenjs/vue-vben-admin/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vbenjs/vue-vben-admin.git",
+    "directory": "packages/hooks"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "default": "./src/index.ts"
+    }
+  },
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "//build": "pnpm unbuild",
+    "//stub": "pnpm unbuild --stub",
+    "clean": "pnpm rimraf .turbo node_modules dist",
+    "lint": "pnpm eslint ."
+  },
+  "dependencies": {},
+  "devDependencies": {}
+}

packages/shared/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@vben/ts-config/vue-app.json",
+  "include": ["src"]
+}

packages/types/package.json

@@ -27,5 +27,8 @@
     "//stub": "pnpm unbuild --stub",
     "clean": "pnpm rimraf .turbo node_modules dist",
     "lint": "pnpm eslint ."
+  },
+  "dependencies": {
+    "vue": "^3.2.47"
   }
 }

packages/types/src/index.ts

@@ -1 +1 @@
-export * from './utils';
+export * from './tools';

packages/types/src/tools.ts

@@ -1,17 +1,22 @@
+import { type ComputedRef, type Ref } from 'vue';
+
 /**
  * 任意类型的异步函数
  */
-type AnyPromiseFunction = (...arg: any[]) => PromiseLike<any>;
+
+type AnyPromiseFunction<T extends any[] = any[], R = void> = (...arg: T) => PromiseLike<R>;
 
 /**
  * 任意类型的普通函数
  */
-type AnyNormalFunction = (...arg: any[]) => any;
+type AnyNormalFunction<T extends any[] = any[], R = void> = (...arg: T) => R;
 
 /**
  * 任意类型的函数
  */
-type AnyFunction = AnyNormalFunction | AnyPromiseFunction;
+type AnyFunction<T extends any[] = any[], R = void> =
+  | AnyNormalFunction<T, R>
+  | AnyPromiseFunction<T, R>;
 
 /**
  *  T | null 包装
@@ -45,11 +50,32 @@ type TimeoutHandle = ReturnType<typeof setTimeout>;
  */
 type IntervalHandle = ReturnType<typeof setInterval>;
 
+/**
+ * 也许它是一个Ref，或者一个普通的值
+ *
+ */
+type MaybeRef<T> = T | Ref<T>;
+
+/**
+ * 也许它是一个 ref，或者一个普通值，或者一个 getter 函数
+ *
+ */
+type MaybeComputedRef<T> = MaybeReadonlyRef<T> | MaybeRef<T>;
+
+/**
+ * 也许它是一个计算的 ref，或者一个 getter 函数
+ *
+ */
+type MaybeReadonlyRef<T> = (() => T) | ComputedRef<T>;
+
 export {
   type AnyFunction,
   type AnyNormalFunction,
   type AnyPromiseFunction,
   type IntervalHandle,
+  type MaybeComputedRef,
+  type MaybeReadonlyRef,
+  type MaybeRef,
   type NonNullable,
   type Nullable,
   type ReadonlyRecordable,

pnpm-lock.yaml

@@ -229,7 +229,7 @@ importers:
         version: 1.3.3(rollup@2.79.1)(vue@3.2.47)
       vite:
         specifier: ^4.3.0-beta.2
-        version: 4.3.0-beta.2(@types/node@18.15.11)(less@4.1.3)(sass@1.60.0)
+        version: 4.3.0-beta.2(@types/node@18.15.11)(less@4.1.3)(sass@1.61.0)
       vite-plugin-mock:
         specifier: ^2.9.6
         version: 2.9.6(mockjs@1.1.0)(rollup@2.79.1)(vite@4.3.0-beta.2)
@@ -386,7 +386,7 @@ importers:
         version: 1.3.3(rollup@2.79.1)(vue@3.2.47)
       vite:
         specifier: ^4.3.0-beta.2
-        version: 4.3.0-beta.2(@types/node@18.15.11)(less@4.1.3)(sass@1.60.0)
+        version: 4.3.0-beta.2(@types/node@18.15.11)(less@4.1.3)(sass@1.61.0)
 
   internal/vite-config:
     dependencies:
@@ -395,7 +395,7 @@ importers:
         version: 7.0.0
       vite:
         specifier: ^4.3.0-beta.2
-        version: 4.3.0-beta.2(@types/node@18.15.11)(less@4.1.3)(sass@1.60.0)
+        version: 4.3.0-beta.2(@types/node@18.15.11)(less@4.1.3)(sass@1.61.0)
     devDependencies:
       '@types/fs-extra':
         specifier: ^11.0.1
@@ -431,8 +431,8 @@ importers:
         specifier: ^5.9.0
         version: 5.9.0(rollup@2.79.1)
       sass:
-        specifier: ^1.60.0
-        version: 1.60.0
+        specifier: ^1.61.0
+        version: 1.61.0
       unocss:
         specifier: ^0.50.6
         version: 0.50.6(postcss@8.4.21)(rollup@2.79.1)(vite@4.3.0-beta.2)
@@ -471,7 +471,13 @@ importers:
         specifier: workspace:*
         version: link:../types
 
-  packages/types: {}
+  packages/shared: {}
+
+  packages/types:
+    dependencies:
+      vue:
+        specifier: ^3.2.47
+        version: 3.2.47
 
 packages:
 
@@ -2378,7 +2384,7 @@ packages:
       chokidar: 3.5.3
       fast-glob: 3.2.12
       magic-string: 0.30.0
-      vite: 4.3.0-beta.2(@types/node@18.15.11)(less@4.1.3)(sass@1.60.0)
+      vite: 4.3.0-beta.2(@types/node@18.15.11)(less@4.1.3)(sass@1.61.0)
     transitivePeerDependencies:
       - rollup
     dev: true
@@ -2393,7 +2399,7 @@ packages:
       '@babel/core': 7.21.4
       '@babel/plugin-transform-typescript': 7.21.3(@babel/core@7.21.4)
       '@vue/babel-plugin-jsx': 1.1.1(@babel/core@7.21.4)
-      vite: 4.3.0-beta.2(@types/node@18.15.11)(less@4.1.3)(sass@1.60.0)
+      vite: 4.3.0-beta.2(@types/node@18.15.11)(less@4.1.3)(sass@1.61.0)
       vue: 3.2.47
     transitivePeerDependencies:
       - supports-color
@@ -2406,7 +2412,7 @@ packages:
       vite: ^4.0.0
       vue: ^3.2.25
     dependencies:
-      vite: 4.3.0-beta.2(@types/node@18.15.11)(less@4.1.3)(sass@1.60.0)
+      vite: 4.3.0-beta.2(@types/node@18.15.11)(less@4.1.3)(sass@1.61.0)
       vue: 3.2.47
     dev: true
 
@@ -8089,9 +8095,9 @@ packages:
   /safer-buffer@2.1.2:
     resolution: {integrity: sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==}
 
-  /sass@1.60.0:
-    resolution: {integrity: sha512-updbwW6fNb5gGm8qMXzVO7V4sWf7LMXnMly/JEyfbfERbVH46Fn6q02BX7/eHTdKpE7d+oTkMMQpFWNUMfFbgQ==}
-    engines: {node: '>=12.0.0'}
+  /sass@1.61.0:
+    resolution: {integrity: sha512-PDsN7BrVkNZK2+dj/dpKQAWZavbAQ87IXqVvw2+oEYI+GwlTWkvbQtL7F2cCNbMqJEYKPh1EcjSxsnqIb/kyaQ==}
+    engines: {node: '>=14.0.0'}
     hasBin: true
     dependencies:
       chokidar: 3.5.3
@@ -9558,7 +9564,7 @@ packages:
       chalk: 4.1.2
       debug: 4.3.4
       fs-extra: 10.1.0
-      vite: 4.3.0-beta.2(@types/node@18.15.11)(less@4.1.3)(sass@1.60.0)
+      vite: 4.3.0-beta.2(@types/node@18.15.11)(less@4.1.3)(sass@1.61.0)
     transitivePeerDependencies:
       - supports-color
     dev: true
@@ -9579,7 +9585,7 @@ packages:
       kolorist: 1.7.0
       magic-string: 0.29.0
       ts-morph: 17.0.1
-      vite: 4.3.0-beta.2(@types/node@18.15.11)(less@4.1.3)(sass@1.60.0)
+      vite: 4.3.0-beta.2(@types/node@18.15.11)(less@4.1.3)(sass@1.61.0)
     transitivePeerDependencies:
       - '@types/node'
       - rollup
@@ -9603,7 +9609,7 @@ packages:
       html-minifier-terser: 6.1.0
       node-html-parser: 5.4.2
       pathe: 0.2.0
-      vite: 4.3.0-beta.2(@types/node@18.15.11)(less@4.1.3)(sass@1.60.0)
+      vite: 4.3.0-beta.2(@types/node@18.15.11)(less@4.1.3)(sass@1.61.0)
     dev: true
 
   /vite-plugin-mock@2.9.6(mockjs@1.1.0)(rollup@2.79.1)(vite@4.3.0-beta.2):
@@ -9623,7 +9629,7 @@ packages:
       fast-glob: 3.2.12
       mockjs: 1.1.0
       path-to-regexp: 6.2.1
-      vite: 4.3.0-beta.2(@types/node@18.15.11)(less@4.1.3)(sass@1.60.0)
+      vite: 4.3.0-beta.2(@types/node@18.15.11)(less@4.1.3)(sass@1.61.0)
     transitivePeerDependencies:
       - rollup
       - supports-color
@@ -9638,7 +9644,7 @@ packages:
       '@purge-icons/core': 0.9.1
       '@purge-icons/generated': 0.9.0
       rollup-plugin-purge-icons: 0.9.1
-      vite: 4.3.0-beta.2(@types/node@18.15.11)(less@4.1.3)(sass@1.60.0)
+      vite: 4.3.0-beta.2(@types/node@18.15.11)(less@4.1.3)(sass@1.61.0)
     transitivePeerDependencies:
       - encoding
       - supports-color
@@ -9657,12 +9663,12 @@ packages:
       pathe: 0.2.0
       svg-baker: 1.7.0
       svgo: 2.8.0
-      vite: 4.3.0-beta.2(@types/node@18.15.11)(less@4.1.3)(sass@1.60.0)
+      vite: 4.3.0-beta.2(@types/node@18.15.11)(less@4.1.3)(sass@1.61.0)
     transitivePeerDependencies:
       - supports-color
     dev: true
 
-  /vite@4.3.0-beta.2(@types/node@18.15.11)(less@4.1.3)(sass@1.60.0):
+  /vite@4.3.0-beta.2(@types/node@18.15.11)(less@4.1.3)(sass@1.61.0):
     resolution: {integrity: sha512-RRghM7RiRnwknCG3hS+NE8C+N3CNX4yKfVhFxO3NqrtYErN6htac//De9IwIHWqgV8DdKoNPeK8Yb/FOlZvjoQ==}
     engines: {node: ^14.18.0 || >=16.0.0}
     hasBin: true
@@ -9693,7 +9699,7 @@ packages:
       postcss: 8.4.21
       resolve: 1.22.1
       rollup: 3.20.2
-      sass: 1.60.0
+      sass: 1.61.0
     optionalDependencies:
       fsevents: 2.3.2