feat(playground): ✨ 新增示例项目

packages/vue3/src/hooks/list/index.ts

@@ -1,9 +1,9 @@
 /*
  * @file /src/hooks/list.ts
- * @description
+ * @description 列表加载更多Hook
  * @author tsl (randy1924@163.com)
  * @date 2026-03-19 11:11:11
- * @lastModified 2026-03-20 10:43:38
+ * @lastModified 2026-06-30 10:57:44
  * @lastModifiedBy tsl (randy1924@163.com)
  */
 

packages/vue3/src/vue-helper/index.ts

@@ -1,9 +1,37 @@
+/*
+ * @file \src\vue-helper\index.ts
+ * @description vue3 帮助工具
+ * @author tsl (randy1924@163.com)
+ * @date 2026-05-28 11:13:40
+ * @lastModified 2026-06-30 11:00:29
+ * @lastModifiedBy tsl (randy1924@163.com)
+ */
+
 import { ComponentPublicInstance } from "vue";
 
+/** Vue class 对象格式，键为类名，值为布尔值表示是否生效 */
 type CustomClassObj = Record<string, boolean>;
+/** Vue class 支持的类型：字符串、字符串数组或对象 */
 type CustomClass = string | Array<string> | CustomClassObj;
+/** 分解后的 Vue class 对象，所有类名值为 true */
 type DistCustomClass = Record<string, true>;
 
+/**
+ * 将字符串或字符串数组转换为 Vue class 对象
+ *
+ * 将类名字符串或数组转换为 `{ className: true }` 格式的对象，
+ * 适用于 Vue 的 class 绑定。
+ *
+ * @example
+ * ```ts
+ * createCustomClassObj('foo bar')  // { foo: true, bar: true }
+ * createCustomClassObj(['foo', 'bar'])  // { foo: true, bar: true }
+ * ```
+ *
+ * @param customClass 类名字符串或字符串数组
+ * @returns 类名对象，所有值为 true
+ * @throws 若 customClass 不是字符串或数组则抛出 TypeError
+ */
 export function createCustomClassObj(customClass: string): DistCustomClass;
 export function createCustomClassObj(
   customClass: Array<string>,
@@ -35,9 +63,21 @@ export function createCustomClassObj(
 }
 
 /**
- * 转换 vue class 为 vue class 对象
- * @param sourceClass 原始 class
- * @returns
+ * 转换 Vue class 为 Vue class 对象
+ *
+ * 支持字符串、数组和对象三种 Vue class 格式，统一转换为
+ * `{ className: boolean }` 格式的对象。
+ *
+ * @example
+ * ```ts
+ * convertCustomClass('foo bar')     // { foo: true, bar: true }
+ * convertCustomClass(['foo', 'bar']) // { foo: true, bar: true }
+ * convertCustomClass({ foo: true, bar: false }) // { foo: true, bar: false }
+ * ```
+ *
+ * @param sourceClass 原始 Vue class 值，支持字符串、数组或对象
+ * @returns Vue class 对象
+ * @throws 若 sourceClass 不是有效的 Vue class 则抛出 TypeError
  */
 export function convertCustomClass(sourceClass: CustomClass): CustomClassObj {
   let customClassObj = <CustomClassObj>{};
@@ -66,9 +106,19 @@ export function convertCustomClass(sourceClass: CustomClass): CustomClassObj {
 }
 
 /**
- * 合并 class
- * @param customClass vue class
- * @returns
+ * 合并多个 Vue class 值为一个对象
+ *
+ * 将多个 Vue class（字符串、数组或对象）统一转换为对象后合并，
+ * 后面的 class 值会覆盖前面的同名属性。
+ *
+ * @example
+ * ```ts
+ * mergeClass('foo', ['bar'], { baz: true })
+ * // { foo: true, bar: true, baz: true }
+ * ```
+ *
+ * @param customClass 一个或多个 Vue class 值
+ * @returns 合并后的 Vue class 对象
  */
 export function mergeClass(...customClass: CustomClass[]) {
   return customClass
@@ -77,12 +127,21 @@ export function mergeClass(...customClass: CustomClass[]) {
 }
 
 /**
- * 发送祖先组件事件
- * @param thisArg 调用的源组件实例
- * @param componentName 需要触发事件的组件名
- * @param eventName 事件名称
- * @param params 参数
- * @returns
+ * 向上遍历祖先组件，找到指定名称的组件并触发其事件
+ *
+ * 类似 Vue2 的 dispatch 模式，从当前组件开始沿父组件链向上查找，
+ * 直到找到 componentName 匹配的祖先组件，然后触发其指定事件。
+ *
+ * @example
+ * ```ts
+ * dispatch(this, 'FormComponent', 'validate', { field: 'name' })
+ * // 向上查找名为 FormComponent 的祖先组件，触发其 validate 事件
+ * ```
+ *
+ * @param thisArg 调用源的组件实例
+ * @param componentName 目标祖先组件的 componentName 选项值
+ * @param eventName 要触发的事件名称
+ * @param params 传递给事件的参数
  */
 export function dispatch(
   thisArg: ComponentPublicInstance,