king-design-analyzer 1.0.0

package/README.md

@@ -0,0 +1,151 @@
+# king-design-analyzer
+
+AST-based code analyzer for King Design Vue components with on-demand modular imports.
+
+## Installation
+
+```bash
+npm install king-design-analyzer
+```
+
+## Features
+
+| Module | Import Path | Description |
+|--------|-------------|-------------|
+| Static Check | `king-design-analyzer/static` | SFC structure & syntax validation |
+| AST Analysis | `king-design-analyzer/ast` | Component rules, props, events, slots checking |
+| Runtime | `king-design-analyzer/runtime` | Script execution pre-check |
+| Full | `king-design-analyzer/full` | All three layers combined |
+
+## Usage
+
+### On-demand Import (Recommended)
+
+```typescript
+// Only static check - minimal bundle size
+import { validateCompilation, compileSFC } from 'king-design-analyzer/static';
+
+// Only AST analysis
+import { analyzeCodeWithAST, componentRegistry } from 'king-design-analyzer/ast';
+
+// Only runtime detection
+import { validateRuntimePrecheck } from 'king-design-analyzer/runtime';
+
+// Full validation (compilation + AST + runtime)
+import { validateCode, validateCodeSync } from 'king-design-analyzer/full';
+```
+
+### Full Import
+
+```typescript
+import { 
+  validateCode,
+  analyzeCodeWithAST,
+  compileSFC,
+  validateCompilation,
+  validateRuntimePrecheck
+} from 'king-design-analyzer';
+```
+
+## API Reference
+
+### Static Module (`/static`)
+
+```typescript
+// Validate SFC structure and syntax
+function validateCompilation(code: string): ValidationLayer;
+
+// Compile Vue SFC, extract template/script/style
+function compileSFC(code: string, scopeId: string): CompilationResult;
+
+interface ValidationLayer {
+  name: string;
+  passed: boolean;
+  errors: string[];
+}
+```
+
+### AST Module (`/ast`)
+
+```typescript
+// Analyze code for component rule violations
+async function analyzeCodeWithAST(code: string): Promise<RuleViolation[]>;
+
+// Component metadata registry
+const componentRegistry: ComponentRegistry;
+
+interface RuleViolation {
+  rule: string;
+  match: string;
+  suggestion: string;
+}
+```
+
+### Runtime Module (`/runtime`)
+
+```typescript
+// Pre-check if script can execute correctly
+function validateRuntimePrecheck(code: string): ValidationLayer;
+```
+
+### Full Module (`/full`)
+
+```typescript
+// Full validation with all three layers (async)
+async function validateCode(code: string): Promise<UnifiedValidationResult>;
+
+// Sync version without AST check
+function validateCodeSync(code: string): SyncValidationResult;
+
+interface UnifiedValidationResult {
+  passed: boolean;
+  layers: {
+    compilation: ValidationLayer;
+    ast: ValidationLayer;
+    runtime: ValidationLayer;
+  };
+  summary: string;
+}
+```
+
+## Example
+
+```typescript
+import { validateCode } from 'king-design-analyzer/full';
+
+const code = `
+<script setup lang="ts">
+import { Button } from '@king-design/vue';
+import { ref } from 'vue';
+const count = ref(0);
+</script>
+<template>
+  <Button @click="count++">{{ count }}</Button>
+</template>
+`;
+
+const result = await validateCode(code);
+
+if (result.passed) {
+  console.log('✅ All checks passed');
+} else {
+  console.log('❌ Validation failed:', result.summary);
+  result.layers.compilation.errors.forEach(e => console.log('  Compile:', e));
+  result.layers.ast.errors.forEach(e => console.log('  AST:', e));
+  result.layers.runtime.errors.forEach(e => console.log('  Runtime:', e));
+}
+```
+
+## Peer Dependencies
+
+For full functionality, install these peer dependencies:
+
+```bash
+npm install @vue/compiler-sfc typescript
+```
+
+> Note: `@vue/compiler-sfc` is required for AST analysis. `typescript` is optional.
+
+## License
+
+MIT

package/components/affix.json

@@ -0,0 +1,178 @@
+{
+    "id": "affix",
+    "name": "Affix",
+    "displayName": "图钉",
+    "category": "navigation",
+    "description": "将页面元素固定在可视窗口的某个位置。常用于侧边菜单、侧边导航等。",
+    "importStatement": "import { Affix } from '@king-design/vue';",
+    "props": [
+        {
+            "name": "top",
+            "description": "距离窗口顶部的偏移量，设置为 undefined 则不生效",
+            "type": {
+                "raw": "number",
+                "kind": "number"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Affix :top=\"100\">"
+        },
+        {
+            "name": "bottom",
+            "description": "距离窗口底部的偏移量，设置为 undefined 则不生效",
+            "type": {
+                "raw": "number",
+                "kind": "number"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Affix :bottom=\"50\">"
+        },
+        {
+            "name": "shouldFix",
+            "description": "自定义是否需要固定的函数，返回 boolean",
+            "type": {
+                "raw": "Function",
+                "kind": "function"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Affix :shouldFix=\"checkFix\">"
+        },
+        {
+            "name": "exclude",
+            "description": "自定义排除固定的函数，返回 boolean 表示不固定",
+            "type": {
+                "raw": "Function",
+                "kind": "function"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Affix :exclude=\"checkExclude\">"
+        },
+        {
+            "name": "disabled",
+            "description": "是否禁用固定功能",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Affix disabled>"
+        }
+    ],
+    "events": [
+        {
+            "name": "change",
+            "description": "固定状态改变时触发",
+            "params": [
+                {
+                    "name": "isFixed",
+                    "type": "boolean",
+                    "description": "当前是否处于固定状态"
+                }
+            ],
+            "usageExample": "<Affix @change=\"handleChange\">"
+        }
+    ],
+    "methods": [],
+    "slots": [
+        {
+            "name": "default",
+            "description": "需要被固定的元素",
+            "vueTemplate": "#default",
+            "usageExample": "<Affix><Button>Fixed Button</Button></Affix>"
+        }
+    ],
+    "examples": [
+        {
+            "id": "affix_top",
+            "title": "固定在顶部",
+            "description": "设置 distance-top",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { Affix, Button } from '@king-design/vue';\n</script>\n<template>\n  <Affix :top=\"10\">\n    <Button type=\"primary\">距离顶部 10px 固定</Button>\n  </Affix>\n</template>",
+            "tags": [
+                "top",
+                "basic"
+            ],
+            "usedProps": [
+                "top"
+            ],
+            "usedEvents": [],
+            "usedSlots": [
+                "default"
+            ],
+            "usedMethods": [],
+            "scenario": "将导航或工具栏固定在页面顶部"
+        },
+        {
+            "id": "affix_bottom",
+            "title": "固定在底部",
+            "description": "设置 distance-bottom",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { Affix, Button } from '@king-design/vue';\n</script>\n<template>\n  <Affix :bottom=\"10\">\n    <Button type=\"primary\">距离底部 10px 固定</Button>\n  </Affix>\n</template>",
+            "tags": [
+                "bottom",
+                "basic"
+            ],
+            "usedProps": [
+                "bottom"
+            ],
+            "usedEvents": [],
+            "usedSlots": [
+                "default"
+            ],
+            "usedMethods": [],
+            "scenario": "将帮助按钮或操作栏固定在页面底部"
+        },
+        {
+            "id": "affix_change",
+            "title": "监听状态改变",
+            "description": "监听 change 事件获取固定状态",
+            "difficulty": "medium",
+            "code": "<script setup lang=\"ts\">\nimport { Affix, Button } from '@king-design/vue';\n\nconst onChange = (isFixed: boolean) => {\n  console.log('Fixed state:', isFixed);\n};\n</script>\n<template>\n  <Affix :top=\"100\" @change=\"onChange\">\n    <Button>滚动页面触发固定</Button>\n  </Affix>\n</template>",
+            "tags": [
+                "event",
+                "change"
+            ],
+            "usedProps": [
+                "top"
+            ],
+            "usedEvents": [
+                "change"
+            ],
+            "usedSlots": [
+                "default"
+            ],
+            "usedMethods": [],
+            "scenario": "根据固定状态改变样式"
+        }
+    ],
+    "commonMistakes": [
+        {
+            "id": "affix_container_scroll",
+            "description": "父容器滚动问题",
+            "wrongCode": "<div style=\"overflow: auto; height: 200px;\">\n  <Affix :top=\"10\">...</Affix>\n</div>",
+            "correctCode": "<!-- Affix 默认基于 window 滚动，如果需要在特定容器内滚动固定，Affix实现可能不支持或需要特殊配置，通常 Affix基于 window -->",
+            "explanation": "Affix 一般是基于 window 滚动的，如果放在有 overflow 滚动的这容器内，可能 won't work expectedly。目前组件文档未明确支持 target 容器，需注意。",
+            "relatedProps": []
+        }
+    ],
+    "searchKeywords": [
+        "图钉",
+        "affix",
+        "fix",
+        "sticky",
+        "固定",
+        "顶部",
+        "底部"
+    ],
+    "useCases": [
+        "侧边导航栏固定",
+        "顶部工具栏固定",
+        "底部操作栏固定",
+        "悬浮按钮"
+    ],
+    "relatedComponents": []
+}

package/components/az.json

@@ -0,0 +1,86 @@
+{
+    "id": "az",
+    "name": "AZ",
+    "displayName": "可用区选择",
+    "category": "form",
+    "description": "可用区（Availability Zone）选择组件。",
+    "importStatement": "import { AZ } from '@ksyun-internal/versatile';",
+    "props": [
+        {
+            "name": "modelValue",
+            "description": "选中的可用区编码",
+            "type": {
+                "raw": "string",
+                "kind": "string"
+            },
+            "required": false,
+            "usageExample": "<AZ v-model=\"azCode\" />"
+        },
+        {
+            "name": "regionCode",
+            "description": "所属地域编码",
+            "type": {
+                "raw": "string",
+                "kind": "string"
+            },
+            "required": false,
+            "usageExample": "<AZ regionCode=\"cn-beijing-6\" />"
+        },
+        {
+            "name": "packages",
+            "description": "可用区配置列表（通常从Region组件联动获取，或通过API获取）",
+            "type": {
+                "raw": "AZ[]",
+                "kind": "array"
+            },
+            "required": false,
+            "usageExample": "<AZ :packages=\"packages\" />"
+        },
+        {
+            "name": "showLearnMore",
+            "description": "是否显示了解更多",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "true"
+        },
+        {
+            "name": "learnMoreUrl",
+            "description": "了解更多链接ID",
+            "type": {
+                "raw": "number",
+                "kind": "number"
+            },
+            "required": false
+        }
+    ],
+    "events": [
+        {
+            "name": "change",
+            "vueEventName": "update:modelValue",
+            "description": "可用区改变时触发",
+            "payload": [
+                {
+                    "name": "value",
+                    "type": "string",
+                    "description": "新的AZCode"
+                }
+            ],
+            "usageExample": "<AZ @update:modelValue=\"v => console.log(v)\" />",
+            "handlerExample": "(val) => { console.log(val); }"
+        }
+    ],
+    "methods": [],
+    "examples": [],
+    "searchKeywords": [
+        "az",
+        "zone",
+        "可用区",
+        "机房"
+    ],
+    "useCases": [
+        "购买页选择可用区"
+    ]
+}

package/components/badge.json

@@ -0,0 +1,162 @@
+{
+    "id": "badge",
+    "name": "Badge",
+    "displayName": "徽标",
+    "category": "data",
+    "description": "出现在按钮、图标旁的数字或状态标记。",
+    "importStatement": "import { Badge } from '@king-design/vue';",
+    "props": [
+        {
+            "name": "text",
+            "description": "显示的文本内容或数字。如果不传，则显示为一个小红点。",
+            "type": {
+                "raw": "string | number",
+                "kind": "union"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Badge :text=\"10\">"
+        },
+        {
+            "name": "max",
+            "description": "显示的最大数值，超过最大值会显示为 max+。仅在 text 为 numeric 时生效。",
+            "type": {
+                "raw": "number",
+                "kind": "number"
+            },
+            "required": false,
+            "default": "undefined",
+            "usageExample": "<Badge :text=\"100\" :max=\"99\">"
+        },
+        {
+            "name": "disabled",
+            "description": "是否隐藏徽标",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<Badge disabled>"
+        }
+    ],
+    "events": [],
+    "methods": [],
+    "slots": [
+        {
+            "name": "default",
+            "description": "徽标包裹的元素",
+            "vueTemplate": "#default",
+            "usageExample": "<Badge><Button>Button</Button></Badge>"
+        }
+    ],
+    "examples": [
+        {
+            "id": "badge_basic",
+            "title": "基础用法",
+            "description": "包裹其他元素，显示数字或红点",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { Badge, Button } from '@king-design/vue';\n</script>\n<template>\n  <Badge :text=\"5\">\n    <Button>评论</Button>\n  </Badge>\n  <Badge>\n    <Button>新消息</Button>\n  </Badge>\n</template>",
+            "tags": [
+                "basic",
+                "dot"
+            ],
+            "usedProps": [
+                "text"
+            ],
+            "usedEvents": [],
+            "usedSlots": [
+                "default"
+            ],
+            "usedMethods": [],
+            "scenario": "在按钮右上角显示未读消息数"
+        },
+        {
+            "id": "badge_max",
+            "title": "最大值限制",
+            "description": "超过 max 值显示为 max+",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { Badge, Button } from '@king-design/vue';\n</script>\n<template>\n  <Badge :text=\"200\" :max=\"99\">\n    <Button>消息</Button>\n  </Badge>\n</template>",
+            "tags": [
+                "max",
+                "limit"
+            ],
+            "usedProps": [
+                "text",
+                "max"
+            ],
+            "usedEvents": [],
+            "usedSlots": [
+                "default"
+            ],
+            "usedMethods": [],
+            "scenario": "消息数过多时显示 99+"
+        },
+        {
+            "id": "badge_text",
+            "title": "自定义文字",
+            "description": "text 属性可以是字符串",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { Badge, Button } from '@king-design/vue';\n</script>\n<template>\n  <Badge text=\"new\">\n    <Button>功能</Button>\n  </Badge>\n  <Badge text=\"hot\">\n    <Button>活动</Button>\n  </Badge>\n</template>",
+            "tags": [
+                "text",
+                "custom"
+            ],
+            "usedProps": [
+                "text"
+            ],
+            "usedEvents": [],
+            "usedSlots": [
+                "default"
+            ],
+            "usedMethods": [],
+            "scenario": "标记新功能或热门活动"
+        },
+        {
+            "id": "badge_independent",
+            "title": "独立使用",
+            "description": "不包裹任何元素，独立展示",
+            "difficulty": "easy",
+            "code": "<script setup lang=\"ts\">\nimport { Badge } from '@king-design/vue';\n</script>\n<template>\n  <span>新消息</span>\n  <Badge :text=\"10\" />\n</template>",
+            "tags": [
+                "independent"
+            ],
+            "usedProps": [
+                "text"
+            ],
+            "usedEvents": [],
+            "usedSlots": [],
+            "usedMethods": [],
+            "scenario": "在列表行尾显示数量"
+        }
+    ],
+    "commonMistakes": [
+        {
+            "id": "badge_number_string",
+            "description": "数字作为字符串传入",
+            "wrongCode": "<Badge text=\"10\" :max=\"9\">",
+            "correctCode": "<Badge :text=\"10\" :max=\"9\">",
+            "explanation": "如果 text 传入的是字符串 \"10\"，max 属性可能无法正确比较。建议数字类型使用 v-bind 传入。",
+            "relatedProps": [
+                "text",
+                "max"
+            ]
+        }
+    ],
+    "searchKeywords": [
+        "徽标",
+        "badge",
+        "mark",
+        "notify",
+        "notification",
+        "count",
+        "number"
+    ],
+    "useCases": [
+        "消息通知数量",
+        "待办事项数量",
+        "新功能标记",
+        "状态点"
+    ],
+    "relatedComponents": []
+}

package/components/billtypes.json

@@ -0,0 +1,90 @@
+{
+    "id": "billtypes",
+    "name": "BillTypes",
+    "displayName": "计费类型选择",
+    "category": "form",
+    "description": "计费类型选择组件，支持按量付费、包年包月等多种计费模式展示与选择。",
+    "importStatement": "import { BillTypes } from '@ksyun-internal/versatile';",
+    "props": [
+        {
+            "name": "modelValue",
+            "description": "选中的计费类型ID",
+            "type": {
+                "raw": "number",
+                "kind": "number"
+            },
+            "required": false,
+            "usageExample": "<BillTypes v-model=\"billType\" />"
+        },
+        {
+            "name": "packages",
+            "description": "计费类型配置列表",
+            "type": {
+                "raw": "BillType[]",
+                "kind": "array"
+            },
+            "required": false,
+            "usageExample": "<BillTypes :packages=\"packages\" />"
+        },
+        {
+            "name": "showTrial",
+            "description": "是否显示试用选项",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "false",
+            "usageExample": "<BillTypes showTrial />"
+        },
+        {
+            "name": "showLearnMore",
+            "description": "是否显示了解更多链接",
+            "type": {
+                "raw": "boolean",
+                "kind": "boolean"
+            },
+            "required": false,
+            "default": "true",
+            "usageExample": "<BillTypes showLearnMore />"
+        },
+        {
+            "name": "learnMoreUrl",
+            "description": "了解更多链接的帮助文档ID",
+            "type": {
+                "raw": "number",
+                "kind": "number"
+            },
+            "required": false,
+            "usageExample": "<BillTypes :learnMoreUrl=\"123\" />"
+        }
+    ],
+    "events": [
+        {
+            "name": "change",
+            "vueEventName": "update:modelValue",
+            "description": "选中值改变时触发",
+            "payload": [
+                {
+                    "name": "value",
+                    "type": "number",
+                    "description": "新的计费类型ID"
+                }
+            ],
+            "usageExample": "<BillTypes @update:modelValue=\"v => console.log(v)\" />",
+            "handlerExample": "(val) => { console.log(val); }"
+        }
+    ],
+    "methods": [],
+    "examples": [],
+    "searchKeywords": [
+        "bill",
+        "price",
+        "charge",
+        "计费",
+        "价格"
+    ],
+    "useCases": [
+        "购买页选择计费模式"
+    ]
+}