king-design-analyzer 2.1.2 → 2.1.3

package/hooks/useIdEntity.json

@@ -0,0 +1,92 @@
+{
+    "id": "useIdEntity",
+    "name": "useIdEntity",
+    "displayName": "ID 实体映射",
+    "category": "state",
+    "description": "根据 ID 从列表中查找对应的实体对象。当 ID 或列表变化时自动更新实体，并可选择性地触发回调。常用于 Select 等组件中需要根据选中 ID 获取完整对象信息的场景。",
+    "importStatement": "import { useIdEntity } from '@ksyun-internal/versatile';",
+    "source": "@ksyun-internal/versatile",
+    "params": [
+        {
+            "name": "id",
+            "type": "Ref<string | number | undefined | null>",
+            "required": true,
+            "description": "要查找的实体 ID（响应式值）"
+        },
+        {
+            "name": "list",
+            "type": "Ref<Entity[] | undefined | null>",
+            "required": true,
+            "description": "实体列表（响应式值）"
+        },
+        {
+            "name": "key",
+            "type": "keyof Entity",
+            "required": true,
+            "description": "用于匹配的实体属性名（如 'id', 'WorkspaceId' 等）"
+        },
+        {
+            "name": "emit",
+            "type": "(entity: Entity | undefined) => void",
+            "required": false,
+            "description": "实体变化时的回调函数"
+        },
+        {
+            "name": "deps",
+            "type": "WatchSource[]",
+            "required": false,
+            "description": "额外的依赖项，当这些依赖变化时也会触发重新查找"
+        },
+        {
+            "name": "enable",
+            "type": "(item: Entity, index: number) => boolean",
+            "required": false,
+            "description": "过滤函数，用于筛选可用的实体"
+        }
+    ],
+    "returnType": "Ref<Entity | undefined>",
+    "examples": [
+        {
+            "id": "basic_usage",
+            "title": "基础用法",
+            "description": "根据选中的 ID 获取对应的工作空间对象",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { useIdEntity } from '@ksyun-internal/versatile';\n\nconst selectedId = ref('ws-001');\nconst workspaceList = ref([\n  { WorkspaceId: 'ws-001', WorkspaceName: '工作空间1' },\n  { WorkspaceId: 'ws-002', WorkspaceName: '工作空间2' },\n]);\n\nconst selectedWorkspace = useIdEntity(selectedId, workspaceList, 'WorkspaceId');\n// selectedWorkspace.value = { WorkspaceId: 'ws-001', WorkspaceName: '工作空间1' }\n</script>"
+        },
+        {
+            "id": "with_callback",
+            "title": "带回调函数",
+            "description": "当实体变化时触发回调",
+            "code": "<script setup lang=\"ts\">\nimport { useToState, useIdEntity } from '@ksyun-internal/versatile';\n\nconst props = defineProps<{ modelValue?: string }>();\nconst emit = defineEmits<{ (e: 'update:modelValue', v?: string): void }>();\n\nconst modelValue = useToState(props, 'modelValue', emit, '');\nconst { workspaceList } = useWorkspaces();\n\nuseIdEntity(modelValue, workspaceList, 'WorkspaceId', (entity) => {\n  emit('update:modelValue', entity?.WorkspaceId);\n});\n</script>"
+        },
+        {
+            "id": "with_enable_filter",
+            "title": "带过滤函数",
+            "description": "只在启用状态的实体中查找",
+            "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { useIdEntity } from '@ksyun-internal/versatile';\n\nconst selectedId = ref('item-1');\nconst itemList = ref([\n  { id: 'item-1', name: '项目1', enabled: true },\n  { id: 'item-2', name: '项目2', enabled: false },\n]);\n\n// 只在 enabled: true 的项目中查找\nconst entity = useIdEntity(\n  selectedId,\n  itemList,\n  'id',\n  undefined,\n  undefined,\n  (item) => item.enabled\n);\n</script>"
+        }
+    ],
+    "commonMistakes": [
+        {
+            "id": "non_ref_id",
+            "description": "id 参数传入非响应式值",
+            "wrongCode": "const entity = useIdEntity('ws-001', workspaceList, 'WorkspaceId');",
+            "correctCode": "const id = ref('ws-001');\nconst entity = useIdEntity(id, workspaceList, 'WorkspaceId');",
+            "explanation": "id 参数必须是 Ref 类型，否则无法监听变化"
+        },
+        {
+            "id": "wrong_key_name",
+            "description": "key 参数与实体属性名不匹配",
+            "wrongCode": "useIdEntity(id, workspaceList, 'id');  // 实体中是 WorkspaceId",
+            "correctCode": "useIdEntity(id, workspaceList, 'WorkspaceId');",
+            "explanation": "key 必须与实体对象中用作唯一标识的属性名完全匹配"
+        }
+    ],
+    "searchKeywords": [
+        "useIdEntity",
+        "id",
+        "entity",
+        "列表查找",
+        "实体映射",
+        "select"
+    ]
+}

package/hooks/usetoState.json

@@ -0,0 +1,97 @@
+{
+    "id": "useToState",
+    "name": "useToState",
+    "displayName": "Props 转 State",
+    "category": "state",
+    "description": "将 props 中的属性转换为响应式 state，支持 v-model 双向绑定。当 props 变化时自动更新 state，当 state 变化时自动触发 emit 更新父组件。",
+    "importStatement": "import { useToState } from '@ksyun-internal/versatile';",
+    "source": "@ksyun-internal/versatile",
+    "params": [
+        {
+            "name": "props",
+            "type": "P extends object",
+            "required": true,
+            "description": "组件的 props 对象（通过 defineProps 获取）"
+        },
+        {
+            "name": "key",
+            "type": "keyof P",
+            "required": true,
+            "description": "要监听的 prop 名称（字符串）"
+        },
+        {
+            "name": "emit",
+            "type": "Emits<K & string, P[K]>",
+            "required": true,
+            "description": "组件的 emit 函数（通过 defineEmits 获取），需要包含 update:key 事件"
+        },
+        {
+            "name": "defaults",
+            "type": "NonNullable<P[K]>",
+            "required": false,
+            "description": "默认值。如果提供，返回的 Ref 将保证不为 undefined"
+        }
+    ],
+    "returnType": "Ref<P[K]>",
+    "overloads": [
+        {
+            "signature": "useToState<P, K>(props: P, key: K, emit: Emits): Ref<P[K]>",
+            "description": "基础用法，返回可能为 undefined 的响应式值"
+        },
+        {
+            "signature": "useToState<P, K>(props: P, key: K, emit: Emits, defaults: NonNullable<P[K]>): Ref<NonNullable<P[K]>>",
+            "description": "带默认值用法，返回保证非 undefined 的响应式值"
+        }
+    ],
+    "examples": [
+        {
+            "id": "basic_usage",
+            "title": "基础用法",
+            "description": "将 modelValue prop 转换为响应式 state",
+            "code": "<script setup lang=\"ts\">\nimport { useToState } from '@ksyun-internal/versatile';\n\ntype Props = { modelValue?: string };\ntype Emits = { (e: 'update:modelValue', v?: string): void };\n\nconst props = defineProps<Props>();\nconst emit = defineEmits<Emits>();\n\nconst value = useToState(props, 'modelValue', emit);\n</script>\n<template>\n  <input v-model=\"value\" />\n</template>"
+        },
+        {
+            "id": "with_defaults",
+            "title": "带默认值用法",
+            "description": "提供默认值，确保返回值不为 undefined",
+            "code": "<script setup lang=\"ts\">\nimport { useToState } from '@ksyun-internal/versatile';\n\nconst props = defineProps<{ count?: number }>();\nconst emit = defineEmits(['update:count']);\n\n// 默认值为 0，count 永远不为 undefined\nconst count = useToState(props, 'count', emit, 0);\n</script>\n<template>\n  <div>{{ count }}</div>\n</template>"
+        },
+        {
+            "id": "object_value",
+            "title": "对象类型值",
+            "description": "将对象类型的 prop 转换为响应式 state",
+            "code": "<script setup lang=\"ts\">\nimport { useToState } from '@ksyun-internal/versatile';\n\ntype FormData = { name: string; age: number };\ntype Props = { modelValue?: FormData };\ntype Emits = { (e: 'update:modelValue', v?: FormData): void };\n\nconst props = defineProps<Props>();\nconst emit = defineEmits<Emits>();\n\nconst formData = useToState(props, 'modelValue', emit, { name: '', age: 0 });\n</script>\n<template>\n  <input v-model=\"formData.name\" />\n  <input v-model.number=\"formData.age\" />\n</template>"
+        }
+    ],
+    "commonMistakes": [
+        {
+            "id": "missing_emit",
+            "description": "忘记传递 emit 参数",
+            "wrongCode": "const value = useToState(props, 'modelValue');",
+            "correctCode": "const value = useToState(props, 'modelValue', emit);",
+            "explanation": "useToState 需要 emit 函数来实现双向绑定，缺少 emit 会导致编译错误"
+        },
+        {
+            "id": "wrong_emit_event",
+            "description": "emit 没有定义对应的 update:key 事件",
+            "wrongCode": "const emit = defineEmits(['change']);\nconst value = useToState(props, 'modelValue', emit);",
+            "correctCode": "const emit = defineEmits(['update:modelValue']);\nconst value = useToState(props, 'modelValue', emit);",
+            "explanation": "useToState 内部会调用 emit('update:key', newValue)，必须在 defineEmits 中声明对应事件"
+        },
+        {
+            "id": "key_not_in_props",
+            "description": "key 参数不是 props 中定义的属性",
+            "wrongCode": "const props = defineProps<{ name: string }>();\nconst value = useToState(props, 'age', emit);",
+            "correctCode": "const props = defineProps<{ name: string; age?: number }>();\nconst value = useToState(props, 'age', emit);",
+            "explanation": "key 必须是 props 中已定义的属性名"
+        }
+    ],
+    "searchKeywords": [
+        "useToState",
+        "props",
+        "state",
+        "v-model",
+        "双向绑定",
+        "响应式"
+    ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "king-design-analyzer",
-    "version": "2.1.2",
+    "version": "2.1.3",
     "description": "AST-based code analyzer for King Design Vue components with on-demand modular imports",
     "main": "./dist/index.js",
     "module": "./dist/index.mjs",
@@ -45,7 +45,8 @@
     "files": [
         "dist",
         "components",
-        "docs_for_llm"
+        "docs_for_llm",
+        "hooks"
     ],
     "scripts": {
         "build": "tsup",