react-kui 3.1.0 → 3.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (247) hide show
  1. package/AI.en-US.md +86 -1
  2. package/AI.md +68 -4
  3. package/ai/behaviors.json +114 -14
  4. package/ai/cli.mjs +180 -17
  5. package/ai/descriptions.json +446 -0
  6. package/ai/kui-components.json +778 -305
  7. package/ai/mcp.mjs +2 -189
  8. package/ai/query.mjs +195 -0
  9. package/ai/skills/react-kui/SKILL.md +41 -9
  10. package/ai/skills/react-kui/references/mcp.md +11 -1
  11. package/ai/skills/react-kui/references/react-to-vue.md +110 -0
  12. package/ai/skills/react-kui/references/vue-to-react.md +86 -0
  13. package/ai/validate.mjs +18 -0
  14. package/es/_virtual/_rolldown/runtime.js +1 -1
  15. package/es/affix/index.js +1 -1
  16. package/es/alert/index.js +1 -1
  17. package/es/anchor/anchor-context.js +1 -1
  18. package/es/anchor/anchor-link.js +1 -1
  19. package/es/anchor/anchor.js +1 -1
  20. package/es/auto-complete/index.js +1 -1
  21. package/es/avatar/avatar-group-context.js +1 -1
  22. package/es/avatar/avatar-group.js +1 -1
  23. package/es/avatar/avatar.js +1 -1
  24. package/es/back-top/index.js +1 -1
  25. package/es/badge/index.js +1 -1
  26. package/es/base/teleport.js +1 -1
  27. package/es/base/transition-props.js +1 -1
  28. package/es/base/transition.js +1 -1
  29. package/es/breadcrumb/breadcrumb-context.js +1 -1
  30. package/es/breadcrumb/breadcrumb-item.js +1 -1
  31. package/es/breadcrumb/breadcrumb.js +1 -1
  32. package/es/button/button-group-context.js +1 -1
  33. package/es/button/button-group.js +1 -1
  34. package/es/button/button.js +1 -1
  35. package/es/calendar/index.js +1 -1
  36. package/es/card/index.js +1 -1
  37. package/es/carousel/carousel-context.js +1 -1
  38. package/es/carousel/carousel-item.js +1 -1
  39. package/es/carousel/carousel.js +522 -274
  40. package/es/carousel/drag.js +169 -0
  41. package/es/cascader/index.js +1 -1
  42. package/es/check-card/check-card-group.js +1 -1
  43. package/es/check-card/check-card.js +1 -1
  44. package/es/check-card/context.js +1 -1
  45. package/es/checkbox/checkbox-group-context.js +1 -1
  46. package/es/checkbox/checkbox-group.js +1 -1
  47. package/es/checkbox/checkbox.js +1 -1
  48. package/es/checkbox/index.js +1 -1
  49. package/es/collapse/collapse-panel.js +1 -1
  50. package/es/collapse/collapse.js +1 -1
  51. package/es/color-picker/alpha.js +1 -1
  52. package/es/color-picker/hue.js +1 -1
  53. package/es/color-picker/index.js +1 -1
  54. package/es/color-picker/mode.js +1 -1
  55. package/es/color-picker/paint.js +1 -1
  56. package/es/color-picker/presets.js +1 -1
  57. package/es/components.js +1 -1
  58. package/es/config/config-context.js +1 -1
  59. package/es/config/context.js +1 -1
  60. package/es/config/index.js +1 -1
  61. package/es/config/size-context.js +1 -1
  62. package/es/config/use-config-appearance.js +1 -1
  63. package/es/const/var.js +1 -1
  64. package/es/date-picker/index.js +1 -1
  65. package/es/descriptions/descriptions-item.js +1 -1
  66. package/es/descriptions/descriptions.js +1 -1
  67. package/es/divider/index.js +1 -1
  68. package/es/drawer/index.js +1 -1
  69. package/es/dropdown/dropdown-button.js +1 -1
  70. package/es/dropdown/dropdown-context.js +1 -1
  71. package/es/dropdown/dropdown.js +1 -1
  72. package/es/dropdown/trigger.js +1 -1
  73. package/es/empty/index.js +1 -1
  74. package/es/feature-card/index.js +1 -1
  75. package/es/feedback-panel/index.js +1 -1
  76. package/es/flame-wrap/index.js +1 -1
  77. package/es/flame-wrap/types.js +1 -1
  78. package/es/flex/index.js +1 -1
  79. package/es/form/field-context.js +1 -1
  80. package/es/form/form-context.js +1 -1
  81. package/es/form/form-item.js +1 -1
  82. package/es/form/form.js +1 -1
  83. package/es/form/utils.js +1 -1
  84. package/es/grid/grid-item.js +1 -1
  85. package/es/grid/grid.js +1 -1
  86. package/es/grid/useBreakpoint.js +1 -1
  87. package/es/icon/index.js +1 -1
  88. package/es/image/group.js +1 -1
  89. package/es/image/image-group-context.js +1 -1
  90. package/es/image/image.js +1 -1
  91. package/es/image/instance.js +1 -1
  92. package/es/image/preview.js +1 -1
  93. package/es/image/utils.js +1 -1
  94. package/es/index.js +1 -1
  95. package/es/input/index.js +1 -1
  96. package/es/input/input-base.js +202 -0
  97. package/es/input/input-box.js +1 -1
  98. package/es/input/input-group.js +1 -1
  99. package/es/input/input.js +19 -188
  100. package/es/input/textarea.js +1 -1
  101. package/es/input-number/index.js +4 -4
  102. package/es/input-otp/index.js +1 -1
  103. package/es/input-tag/index.js +1 -1
  104. package/es/kanban/index.js +1 -1
  105. package/es/layout/index.js +1 -1
  106. package/es/layout/layout-context.js +1 -1
  107. package/es/list-panel/index.js +1 -1
  108. package/es/loading/index.js +1 -1
  109. package/es/loading/loading-bar.js +1 -1
  110. package/es/locale/de.js +1 -1
  111. package/es/locale/el.js +1 -1
  112. package/es/locale/en.js +1 -1
  113. package/es/locale/fr.js +1 -1
  114. package/es/locale/it.js +1 -1
  115. package/es/locale/ja.js +1 -1
  116. package/es/locale/ko.js +1 -1
  117. package/es/locale/ru.js +1 -1
  118. package/es/locale/th.js +1 -1
  119. package/es/locale/uk.js +1 -1
  120. package/es/locale/vi.js +1 -1
  121. package/es/locale/zh-CN.js +1 -1
  122. package/es/locale/zh-TW.js +1 -1
  123. package/es/mentions/index.js +1 -1
  124. package/es/menu/menu-context.js +1 -1
  125. package/es/menu/menu-divider.js +1 -1
  126. package/es/menu/menu-group.js +1 -1
  127. package/es/menu/menu-item.js +1 -1
  128. package/es/menu/menu-keyboard.js +1 -1
  129. package/es/menu/menu.js +1 -1
  130. package/es/menu/recursive-menu.js +1 -1
  131. package/es/menu/sub-menu.js +1 -1
  132. package/es/message/index.js +1 -1
  133. package/es/modal/api.js +1 -1
  134. package/es/modal/modal.js +1 -1
  135. package/es/modal/toast.js +1 -1
  136. package/es/node_modules/.pnpm/kui-icons@5.0.0/node_modules/kui-icons/dist/kui-icons.esm.js +1 -1
  137. package/es/notice/container.js +1 -1
  138. package/es/notice/content.js +1 -1
  139. package/es/notice/index.js +1 -1
  140. package/es/notice/instance.js +1 -1
  141. package/es/page/index.js +99 -76
  142. package/es/page/responsive.js +96 -0
  143. package/es/page-header/index.js +1 -1
  144. package/es/popconfirm/index.js +1 -1
  145. package/es/poptip/index.js +1 -1
  146. package/es/popup/index.js +1 -1
  147. package/es/popup/layers.js +1 -1
  148. package/es/progress/index.js +1 -1
  149. package/es/qrcode/index.js +1 -1
  150. package/es/radio/radio-button.js +1 -1
  151. package/es/radio/radio-group-context.js +1 -1
  152. package/es/radio/radio-group.js +1 -1
  153. package/es/radio/radio.js +1 -1
  154. package/es/rate/index.js +1 -1
  155. package/es/rate/star.js +1 -1
  156. package/es/result/index.js +1 -1
  157. package/es/ripple/index.js +1 -1
  158. package/es/ripple/types.js +1 -1
  159. package/es/row-col/col.js +1 -1
  160. package/es/row-col/row.js +1 -1
  161. package/es/segmented/index.js +1 -1
  162. package/es/select/option.js +1 -1
  163. package/es/select/select.js +1 -1
  164. package/es/skeleton/skeleton-avatar.js +1 -1
  165. package/es/skeleton/skeleton-button.js +1 -1
  166. package/es/skeleton/skeleton-image.js +1 -1
  167. package/es/skeleton/skeleton-text.js +1 -1
  168. package/es/skeleton/skeleton.js +1 -1
  169. package/es/skeleton/use-skeleton-loading.js +1 -1
  170. package/es/slider/index.js +1 -1
  171. package/es/slider/thumb.js +1 -1
  172. package/es/space/index.js +1 -1
  173. package/es/spin/index.js +1 -1
  174. package/es/splitter/splitter-panel.js +1 -1
  175. package/es/splitter/splitter.js +1 -1
  176. package/es/stat-card/countup.js +1 -1
  177. package/es/stat-card/rollup.js +1 -1
  178. package/es/stat-card/stat-card.js +1 -1
  179. package/es/stat-card/stat-number.js +1 -1
  180. package/es/stat-card/utils/countup.js +1 -1
  181. package/es/stat-card/utils/odometer.js +1 -1
  182. package/es/steps/index.js +1 -1
  183. package/es/switch/index.js +1 -1
  184. package/es/table/column-setting.js +1 -1
  185. package/es/table/index.js +1 -1
  186. package/es/table/utils.js +1 -1
  187. package/es/tabs/tab-panel.js +1 -1
  188. package/es/tabs/tabs.js +1 -1
  189. package/es/tag/index.js +1 -1
  190. package/es/time-line/timeline-item.js +1 -1
  191. package/es/time-line/timeline.js +1 -1
  192. package/es/tooltip/index.js +1 -1
  193. package/es/tour/index.js +1 -1
  194. package/es/transfer/index.js +1 -1
  195. package/es/tree/index.js +1 -1
  196. package/es/tree/utils.js +1 -1
  197. package/es/tree-select/index.js +1 -1
  198. package/es/typography/index.js +1 -1
  199. package/es/upload/file-list.js +1 -1
  200. package/es/upload/index.js +1 -1
  201. package/es/upload/picture-sort.js +1 -1
  202. package/es/upload/selector.js +1 -1
  203. package/es/utils/checked.js +1 -1
  204. package/es/utils/color.js +1 -1
  205. package/es/utils/number.js +1 -1
  206. package/es/utils/placement.js +1 -1
  207. package/es/utils/popup.js +1 -1
  208. package/es/utils/react-node.js +1 -1
  209. package/es/utils/selection-tags.js +1 -1
  210. package/es/utils/share.js +1 -1
  211. package/es/utils/theme.js +1 -1
  212. package/es/utils/transition.js +1 -1
  213. package/es/utils/use-value.js +1 -1
  214. package/es/virtual-list/index.js +1 -1
  215. package/es/virtual-list/range.js +1 -1
  216. package/es/watermark/index.js +1 -1
  217. package/lib/index.cjs +2 -2
  218. package/lib/locale/de.cjs +1 -1
  219. package/lib/locale/el.cjs +1 -1
  220. package/lib/locale/en.cjs +1 -1
  221. package/lib/locale/fr.cjs +1 -1
  222. package/lib/locale/it.cjs +1 -1
  223. package/lib/locale/ja.cjs +1 -1
  224. package/lib/locale/ko.cjs +1 -1
  225. package/lib/locale/ru.cjs +1 -1
  226. package/lib/locale/th.cjs +1 -1
  227. package/lib/locale/uk.cjs +1 -1
  228. package/lib/locale/vi.cjs +1 -1
  229. package/lib/locale/zh-CN.cjs +1 -1
  230. package/lib/locale/zh-TW.cjs +1 -1
  231. package/package.json +6 -3
  232. package/style/base.css +1 -1
  233. package/style/components.css +2 -2
  234. package/style/index.css +2 -2
  235. package/style/theme.css +1 -1
  236. package/types/carousel/carousel.d.cts +2 -1
  237. package/types/carousel/carousel.d.ts +2 -1
  238. package/types/carousel/drag.d.cts +19 -0
  239. package/types/carousel/drag.d.ts +19 -0
  240. package/types/input/input-base.d.cts +31 -0
  241. package/types/input/input-base.d.ts +31 -0
  242. package/types/input/input.d.cts +2 -25
  243. package/types/input/input.d.ts +2 -25
  244. package/types/page/index.d.cts +1 -0
  245. package/types/page/index.d.ts +1 -0
  246. package/types/page/responsive.d.cts +1 -0
  247. package/types/page/responsive.d.ts +1 -0
package/ai/mcp.mjs CHANGED
@@ -1,143 +1,7 @@
1
1
  #!/usr/bin/env node
2
- import fs from "node:fs";
3
2
  import process from "node:process";
4
- import { validateUsage } from "./validate.mjs";
3
+ import { metadata, tools, prompts, promptText, byName, executeTool } from "./query.mjs";
5
4
 
6
- const metadata = JSON.parse(fs.readFileSync(new URL("./kui-components.json", import.meta.url)));
7
- const byName = new Map(metadata.components.map((item) => [item.name.toLowerCase(), item]));
8
- const templates = JSON.parse(fs.readFileSync(new URL("./templates/index.json", import.meta.url)));
9
- const tools = [
10
- ["search_components", "Search components by name, tag, or API description", "query"],
11
- ["get_component_api", "Get component API and behavior contracts without example source", "name"],
12
- ["list_component_examples", "List example IDs and titles for a component", "name"],
13
- [
14
- "get_component_example",
15
- "Read one complete example; pass its ID from list_component_examples",
16
- "name",
17
- ],
18
- ["list_templates", "List runnable business templates (optional search query)", "query"],
19
- ["get_template", "Read a complete runnable React business template", "id"],
20
- ["recommend_components", "Recommend components for a UI requirement", "requirement"],
21
- [
22
- "validate_kui_usage",
23
- "Check JSX/TSX imports, props, static values and Vue syntax mistakes; reports skipped checks, not full type safety",
24
- "source",
25
- ],
26
- ].map(([name, description, argument]) => ({
27
- name,
28
- description,
29
- inputSchema: {
30
- type: "object",
31
- properties: {
32
- [argument]: { type: "string" },
33
- ...(["search_components", "list_component_examples"].includes(name)
34
- ? {
35
- offset: { type: "integer", minimum: 0 },
36
- limit: { type: "integer", minimum: 1, maximum: 20 },
37
- }
38
- : {}),
39
- ...(name === "get_component_api"
40
- ? {
41
- section: {
42
- type: "string",
43
- enum: ["all", "props", "events", "renderProps", "behavior"],
44
- },
45
- }
46
- : {}),
47
- ...(name === "get_component_example" ? { id: { type: "string" } } : {}),
48
- },
49
- required:
50
- name === "list_templates"
51
- ? []
52
- : name === "get_component_example"
53
- ? [argument, "id"]
54
- : [argument],
55
- additionalProperties: false,
56
- },
57
- }));
58
- const prompts = [
59
- { name: "build_form", description: "Build a validated React KUI form", argument: "fields" },
60
- { name: "build_table", description: "Build a searchable React KUI table", argument: "columns" },
61
- { name: "build_modal_editor", description: "Build a modal form editor", argument: "entity" },
62
- ].map(({ name, description, argument }) => ({
63
- name,
64
- description,
65
- arguments: [{ name: argument, required: true }],
66
- }));
67
- const promptText = {
68
- build_form: ({ fields = "" }) =>
69
- `Adapt this runnable React KUI template for fields: ${fields}.\n${getTemplate("form").setup}\n${getTemplate("form").source}`,
70
- build_table: ({ columns = "" }) =>
71
- `Adapt this runnable React KUI template for columns: ${columns}.\n${getTemplate("table").setup}\n${getTemplate("table").source}`,
72
- build_modal_editor: ({ entity = "" }) =>
73
- `Adapt this runnable React KUI template for entity: ${entity}.\n${getTemplate("modal-editor").setup}\n${getTemplate("modal-editor").source}`,
74
- };
75
- const search = (query) => {
76
- const terms = String(query).toLowerCase().split(/\s+/).filter(Boolean);
77
- return metadata.components.filter((item) => {
78
- const text = JSON.stringify(item).toLowerCase();
79
- return terms.every((term) => text.includes(term));
80
- });
81
- };
82
- const recommend = (requirement) => {
83
- const groups = [
84
- [/(form|表单|edit|编辑)/i, ["Form", "FormItem", "Input", "Button"]],
85
- [/(table|列表|data|数据)/i, ["Table", "Page", "Input", "Button"]],
86
- [/(select|选择|dropdown|下拉)/i, ["Select", "Option", "TreeSelect"]],
87
- [/(modal|dialog|弹窗|对话框)/i, ["Modal", "Button"]],
88
- [/(upload|上传)/i, ["Upload"]],
89
- [/(layout|布局|admin|后台)/i, ["Layout", "Sider", "Header", "Content", "Menu"]],
90
- ];
91
- const names = new Set(
92
- groups.filter(([pattern]) => pattern.test(requirement)).flatMap(([, values]) => values),
93
- );
94
- if (!names.size)
95
- search(requirement)
96
- .slice(0, 8)
97
- .forEach((item) => names.add(item.name));
98
- return [...names].map((name) => byName.get(name.toLowerCase())).filter(Boolean);
99
- };
100
- const validate = (source) => validateUsage(source, metadata);
101
- const getComponent = (name) => {
102
- const item = byName.get(String(name).toLowerCase());
103
- if (!item) throw new Error(`Unknown component: ${name}`);
104
- return item;
105
- };
106
- const pageOf = (items, args) => ({
107
- total: items.length,
108
- offset: args.offset || 0,
109
- items: items.slice(args.offset || 0, (args.offset || 0) + (args.limit || 10)),
110
- });
111
- const getTemplate = (id) => {
112
- const entry = templates.find((item) => item.id === id);
113
- if (!entry) throw new Error(`Unknown template: ${id}`);
114
- return {
115
- ...entry,
116
- setup:
117
- "React 19.2+ with react-kui installed; import react-kui/style/index.css once in main.tsx. Save source as App.tsx. Mock requests are local and must be replaced for production.",
118
- source: fs.readFileSync(new URL(`./templates/${entry.file}`, import.meta.url), "utf8"),
119
- };
120
- };
121
- const validateArguments = (name, args) => {
122
- const tool = tools.find((item) => item.name === name);
123
- if (!tool) throw new Error(`Unknown tool: ${name}`);
124
- if (!args || typeof args !== "object" || Array.isArray(args))
125
- throw new Error("Arguments must be an object");
126
- for (const key of tool.inputSchema.required)
127
- if (!(key in args)) throw new Error(`Missing argument: ${key}`);
128
- for (const [key, value] of Object.entries(args)) {
129
- const spec = tool.inputSchema.properties[key];
130
- if (!spec) throw new Error(`Unknown argument: ${key}`);
131
- if (spec.type === "string" && typeof value !== "string")
132
- throw new Error(`${key} must be a string`);
133
- if (
134
- spec.type === "integer" &&
135
- (!Number.isInteger(value) || value < spec.minimum || (spec.maximum && value > spec.maximum))
136
- )
137
- throw new Error(`${key} is out of range`);
138
- if (spec.enum && !spec.enum.includes(value)) throw new Error(`Invalid ${key}`);
139
- }
140
- };
141
5
  const toolResult = (value) => ({
142
6
  content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
143
7
  structuredContent: { result: value },
@@ -214,58 +78,7 @@ process.stdin.on("data", (chunk) => {
214
78
  };
215
79
  } else if (request.method === "tools/call") {
216
80
  const { name, arguments: args = {} } = request.params || {};
217
- validateArguments(name, args);
218
- let value;
219
- if (name === "search_components") {
220
- value = pageOf(
221
- search(args.query).map(({ name, documentation }) => ({
222
- name,
223
- documentation,
224
- })),
225
- args,
226
- );
227
- } else if (name === "get_component_api") {
228
- const {
229
- examples,
230
- nativeProps,
231
- nativeValueTypes: _nativeTypes,
232
- ...api
233
- } = getComponent(args.name);
234
- value =
235
- args.section && args.section !== "all"
236
- ? { name: api.name, version: metadata.version, [args.section]: api[args.section] }
237
- : {
238
- ...api,
239
- version: metadata.version,
240
- exampleCount: examples.length,
241
- nativePropCount: nativeProps.length,
242
- };
243
- } else if (name === "list_component_examples") {
244
- value = pageOf(
245
- getComponent(args.name).examples.map(({ title, id }) => ({ id, title })),
246
- args,
247
- );
248
- } else if (name === "get_component_example") {
249
- const example = getComponent(args.name).examples.find((item) => item.id === args.id);
250
- if (!example) throw new Error(`Unknown example: ${args.id}`);
251
- value = example;
252
- } else if (name === "list_templates") {
253
- value = templates.filter(
254
- (item) =>
255
- !args.query || JSON.stringify(item).toLowerCase().includes(args.query.toLowerCase()),
256
- );
257
- } else if (name === "get_template") {
258
- value = getTemplate(args.id);
259
- } else if (name === "recommend_components") {
260
- value = recommend(args.requirement).map(({ name, documentation, parent, children }) => ({
261
- name,
262
- documentation,
263
- parent,
264
- children,
265
- }));
266
- } else if (name === "validate_kui_usage") value = validate(args.source);
267
- else value = { error: `Unknown tool: ${name}` };
268
- result = toolResult(value);
81
+ result = toolResult(executeTool(name, args));
269
82
  } else if (!["notifications/initialized", "ping"].includes(request.method)) {
270
83
  if (request.id !== undefined)
271
84
  send({
package/ai/query.mjs ADDED
@@ -0,0 +1,195 @@
1
+ import fs from "node:fs";
2
+ import { validateUsage } from "./validate.mjs";
3
+
4
+ const metadata = JSON.parse(fs.readFileSync(new URL("./kui-components.json", import.meta.url)));
5
+ const byName = new Map(metadata.components.map((item) => [item.name.toLowerCase(), item]));
6
+ const templates = JSON.parse(fs.readFileSync(new URL("./templates/index.json", import.meta.url)));
7
+ const tools = [
8
+ ["search_components", "Search components by name, tag, or API description", "query"],
9
+ ["get_component_api", "Get component API and behavior contracts without example source", "name"],
10
+ ["list_component_examples", "List example IDs and titles for a component", "name"],
11
+ [
12
+ "get_component_example",
13
+ "Read one complete example; pass its ID from list_component_examples",
14
+ "name",
15
+ ],
16
+ ["list_templates", "List runnable business templates (optional search query)", "query"],
17
+ ["get_template", "Read a complete runnable React business template", "id"],
18
+ ["recommend_components", "Recommend components for a UI requirement", "requirement"],
19
+ [
20
+ "validate_kui_usage",
21
+ "Check JSX/TSX imports, props, static values and Vue syntax mistakes; reports skipped checks, not full type safety",
22
+ "source",
23
+ ],
24
+ ].map(([name, description, argument]) => ({
25
+ name,
26
+ description,
27
+ inputSchema: {
28
+ type: "object",
29
+ properties: {
30
+ [argument]: { type: "string" },
31
+ ...(["search_components", "list_component_examples"].includes(name)
32
+ ? {
33
+ offset: { type: "integer", minimum: 0 },
34
+ limit: { type: "integer", minimum: 1, maximum: 20 },
35
+ }
36
+ : {}),
37
+ ...(name === "get_component_api"
38
+ ? {
39
+ section: {
40
+ type: "string",
41
+ enum: ["all", "props", "events", "renderProps", "behavior"],
42
+ },
43
+ }
44
+ : {}),
45
+ ...(name === "get_component_example" ? { id: { type: "string" } } : {}),
46
+ },
47
+ required:
48
+ name === "list_templates"
49
+ ? []
50
+ : name === "get_component_example"
51
+ ? [argument, "id"]
52
+ : [argument],
53
+ additionalProperties: false,
54
+ },
55
+ }));
56
+ const prompts = [
57
+ { name: "build_form", description: "Build a validated React KUI form", argument: "fields" },
58
+ { name: "build_table", description: "Build a searchable React KUI table", argument: "columns" },
59
+ { name: "build_modal_editor", description: "Build a modal form editor", argument: "entity" },
60
+ ].map(({ name, description, argument }) => ({
61
+ name,
62
+ description,
63
+ arguments: [{ name: argument, required: true }],
64
+ }));
65
+ const promptText = {
66
+ build_form: ({ fields = "" }) =>
67
+ `Adapt this runnable React KUI template for fields: ${fields}.\n${getTemplate("form").setup}\n${getTemplate("form").source}`,
68
+ build_table: ({ columns = "" }) =>
69
+ `Adapt this runnable React KUI template for columns: ${columns}.\n${getTemplate("table").setup}\n${getTemplate("table").source}`,
70
+ build_modal_editor: ({ entity = "" }) =>
71
+ `Adapt this runnable React KUI template for entity: ${entity}.\n${getTemplate("modal-editor").setup}\n${getTemplate("modal-editor").source}`,
72
+ };
73
+ const search = (query) => {
74
+ const terms = String(query).toLowerCase().split(/\s+/).filter(Boolean);
75
+ return metadata.components.filter((item) => {
76
+ const text = JSON.stringify(item).toLowerCase();
77
+ return terms.every((term) => text.includes(term));
78
+ });
79
+ };
80
+ const recommend = (requirement) => {
81
+ const groups = [
82
+ [/(form|表单|edit|编辑)/i, ["Form", "FormItem", "Input", "Button"]],
83
+ [/(table|列表|data|数据)/i, ["Table", "Page", "Input", "Button"]],
84
+ [/(select|选择|dropdown|下拉)/i, ["Select", "Option", "TreeSelect"]],
85
+ [/(modal|dialog|弹窗|对话框)/i, ["Modal", "Button"]],
86
+ [/(upload|上传)/i, ["Upload"]],
87
+ [/(layout|布局|admin|后台)/i, ["Layout", "Sider", "Header", "Content", "Menu"]],
88
+ ];
89
+ const names = new Set(
90
+ groups.filter(([pattern]) => pattern.test(requirement)).flatMap(([, values]) => values),
91
+ );
92
+ if (!names.size)
93
+ search(requirement)
94
+ .slice(0, 8)
95
+ .forEach((item) => names.add(item.name));
96
+ return [...names].map((name) => byName.get(name.toLowerCase())).filter(Boolean);
97
+ };
98
+ const validate = (source) => validateUsage(source, metadata);
99
+ const getComponent = (name) => {
100
+ const item = byName.get(String(name).toLowerCase());
101
+ if (!item) throw new Error(`Unknown component: ${name}`);
102
+ return item;
103
+ };
104
+ const pageOf = (items, args) => ({
105
+ total: items.length,
106
+ offset: args.offset || 0,
107
+ items: items.slice(args.offset || 0, (args.offset || 0) + (args.limit || 10)),
108
+ });
109
+ const getTemplate = (id) => {
110
+ const entry = templates.find((item) => item.id === id);
111
+ if (!entry) throw new Error(`Unknown template: ${id}`);
112
+ return {
113
+ ...entry,
114
+ setup:
115
+ "React 19.2+ with react-kui installed; import react-kui/style/index.css once in main.tsx. Save source as App.tsx. Mock requests are local and must be replaced for production.",
116
+ source: fs.readFileSync(new URL(`./templates/${entry.file}`, import.meta.url), "utf8"),
117
+ };
118
+ };
119
+ const validateArguments = (name, args) => {
120
+ const tool = tools.find((item) => item.name === name);
121
+ if (!tool) throw new Error(`Unknown tool: ${name}`);
122
+ if (!args || typeof args !== "object" || Array.isArray(args))
123
+ throw new Error("Arguments must be an object");
124
+ for (const key of tool.inputSchema.required)
125
+ if (!(key in args)) throw new Error(`Missing argument: ${key}`);
126
+ for (const [key, value] of Object.entries(args)) {
127
+ const spec = tool.inputSchema.properties[key];
128
+ if (!spec) throw new Error(`Unknown argument: ${key}`);
129
+ if (spec.type === "string" && typeof value !== "string")
130
+ throw new Error(`${key} must be a string`);
131
+ if (
132
+ spec.type === "integer" &&
133
+ (!Number.isInteger(value) || value < spec.minimum || (spec.maximum && value > spec.maximum))
134
+ )
135
+ throw new Error(`${key} is out of range`);
136
+ if (spec.enum && !spec.enum.includes(value)) throw new Error(`Invalid ${key}`);
137
+ }
138
+ };
139
+
140
+ export function executeTool(name, args = {}) {
141
+ validateArguments(name, args);
142
+ let value;
143
+ if (name === "search_components") {
144
+ value = pageOf(
145
+ search(args.query).map(({ name, documentation }) => ({
146
+ name,
147
+ documentation,
148
+ })),
149
+ args,
150
+ );
151
+ } else if (name === "get_component_api") {
152
+ const {
153
+ examples,
154
+ nativeProps,
155
+ nativeValueTypes: _nativeTypes,
156
+ ...api
157
+ } = getComponent(args.name);
158
+ value =
159
+ args.section && args.section !== "all"
160
+ ? { name: api.name, version: metadata.version, [args.section]: api[args.section] }
161
+ : {
162
+ ...api,
163
+ version: metadata.version,
164
+ exampleCount: examples.length,
165
+ nativePropCount: nativeProps.length,
166
+ };
167
+ } else if (name === "list_component_examples") {
168
+ value = pageOf(
169
+ getComponent(args.name).examples.map(({ title, id }) => ({ id, title })),
170
+ args,
171
+ );
172
+ } else if (name === "get_component_example") {
173
+ const example = getComponent(args.name).examples.find((item) => item.id === args.id);
174
+ if (!example) throw new Error(`Unknown example: ${args.id}`);
175
+ value = example;
176
+ } else if (name === "list_templates") {
177
+ value = templates.filter(
178
+ (item) =>
179
+ !args.query || JSON.stringify(item).toLowerCase().includes(args.query.toLowerCase()),
180
+ );
181
+ } else if (name === "get_template") {
182
+ value = getTemplate(args.id);
183
+ } else if (name === "recommend_components") {
184
+ value = recommend(args.requirement).map(({ name, documentation, parent, children }) => ({
185
+ name,
186
+ documentation,
187
+ parent,
188
+ children,
189
+ }));
190
+ } else if (name === "validate_kui_usage") value = validate(args.source);
191
+ else value = { error: `Unknown tool: ${name}` };
192
+ return value;
193
+ }
194
+
195
+ export { metadata, tools, prompts, promptText, byName };
@@ -5,12 +5,44 @@ description: Build React 19.2+ applications with react-kui. Use when creating, r
5
5
 
6
6
  # React KUI
7
7
 
8
- 1. Confirm the application uses React 19.2+. Use named component imports from `react-kui` and icon definitions from `kui-icons`.
9
- 2. Import `react-kui/style/index.css` once at the application entry.
10
- 3. Read installed-version metadata (`react-kui/metadata`) before choosing props or callback signatures. Prefer it over online documentation for another version.
11
- 4. Use JSX/TSX and React state. Never translate Vue v-model, named slots or app.use registration literally. The image export is `KImage`.
12
- 5. Input onChange receives a value, not a DOM event. Switch uses checked/onChange; Modal uses open/onOpenChange. A controlled Form model must be updated through onChange(nextModel).
13
- 6. Query MCP APIs by section. Read example summaries before fetching source. Use the form/table/modal-editor templates for business flows; their requests are local mocks, not production endpoints.
14
- 7. Run validate_kui_usage, read skipped checks, then run application typecheck, lint and relevant interaction tests. Static valid does not mean full type/runtime correctness.
15
-
16
- See `references/components.md` for versioned resources and `references/mcp.md` for tools and setup.
8
+ ## Read installed-version resources
9
+
10
+ Run `pnpm exec react-kui-ai paths` to locate the installed Skill and metadata.
11
+ `react-kui/metadata` is a package export, not a directory. It resolves with
12
+ `node -p "require.resolve('react-kui/metadata')"`. The physical fallback is
13
+ `node_modules/react-kui/ai/kui-components.json`.
14
+
15
+ Without MCP, query `pnpm exec react-kui-ai api Input --section props` and
16
+ `api Input --section behavior`. Use `search`, `examples`, and `example`
17
+ to fetch only relevant content; run `help` for exact arguments. Older releases
18
+ may only support init: use the metadata file or MCP rather than inventing commands.
19
+ Read [references/components.md](references/components.md) for resource boundaries;
20
+ read [references/mcp.md](references/mcp.md) only when configuring or using MCP.
21
+
22
+ ## Contracts that change implementation
23
+
24
+ - Import from `react-kui`, icons from `kui-icons`, and `react-kui/style/index.css` once.
25
+ - Button.icon takes IconType[] data (for example Search), not JSX, h(Icon), a VNode
26
+ or an icon-name string. Input prefix/suffix are renderable content, unlike icon.
27
+ - Use React 19.2+, JSX/TSX, className and React state/callbacks, not Vue bindings.
28
+ - Input onChange receives a string and uses synchronized local state; do not
29
+ assume strict native controlled-input semantics. Modal uses open/onOpenChange.
30
+ - A controlled Form model is updated through onChange(nextModel). Query callback
31
+ payloads instead of assuming all controls emit DOM events.
32
+ - Utilities and type-only exports are not all listed in component metadata.
33
+ Check installed declarations before concluding an export is missing.
34
+
35
+ ## Migration and verification
36
+
37
+ For React → Vue migration, read [references/react-to-vue.md](references/react-to-vue.md).
38
+ The CLI exposes it with `migration react-to-vue`; use `migration vue-to-react`
39
+ for the other direction. Follow only the guide matching the requested target.
40
+
41
+ For Vue → React migration, read [references/vue-to-react.md](references/vue-to-react.md)
42
+ before choosing target APIs. Query both installed versions. Preserve business
43
+ behavior as well as layout; do not treat a successful typecheck as parity.
44
+
45
+ Run `pnpm exec react-kui-ai validate <file>`, then application typecheck, lint and
46
+ relevant interaction tests. Inspect complete/skipped limitations. This validator
47
+ is partial and does not execute expressions. Templates are local mocks, not
48
+ production backends; adapt them only within the user's task.
@@ -1,6 +1,16 @@
1
1
  # React KUI MCP
2
2
 
3
- Start `pnpm exec react-kui-mcp` from the consuming project. Transport: stdio.
3
+ Transport: stdio. Use an absolute Node executable path and the absolute installed
4
+ `node_modules/react-kui/ai/mcp.mjs` path as its argument; this avoids depending
5
+ on the client's working directory. Keep the full package and dependencies installed.
6
+ Get the executable path with `node -p "process.execPath"`.
7
+
8
+ For configuration examples, prerequisites and troubleshooting, read
9
+ [AI.en-US.md](../../../../AI.en-US.md#mcp-server).
10
+ The alternative `pnpm exec react-kui-mcp` requires pnpm on the client's PATH
11
+ and an explicit working directory set to the consuming project.
12
+ Verify initialization, tools/list, and a get_component_api query after connecting.
13
+ Silent terminal startup only means the stdio process is waiting for input.
4
14
 
5
15
  - search_components({ query, offset?, limit? }): paginated component discovery, default 10/max 20.
6
16
  - recommend_components({ requirement }): candidate components.
@@ -0,0 +1,110 @@
1
+ # React → Vue migration with KUI
2
+
3
+ Use this guide when moving react-kui to kui-vue. Record both installed versions
4
+ using each package's `*-ai paths` command. Query the target API and examples
5
+ before changing each component; do not infer Vue contracts from React prop names.
6
+ This guide describes the accompanying source version, not every older release.
7
+
8
+ ## Resource lookup
9
+
10
+ Run `pnpm exec kui-vue-ai api Input --section props`, then
11
+ `api Input --section behavior` and `examples Input`. Read an example with
12
+ `example Input <id>`. The React CLI supports the same queries.
13
+ Older releases may only support init: read their installed metadata and
14
+ declarations instead. Package exports such as `kui-vue/metadata` are not folders;
15
+ resolve them with `node -p "require.resolve('kui-vue/metadata')"`.
16
+
17
+ Metadata inventories components, not every utility or type export. Check
18
+ declarations for theme, message, notice, modal and other helpers.
19
+
20
+ ## State and events are not mechanical renames
21
+
22
+ - React value/onChange often becomes Vue `v-model`, which binds modelValue
23
+ and its update event. It is not merely `:value`.
24
+ - On Vue value-initialized controls such as Input and Select, value is read for
25
+ initialization; later external changes belong in modelValue/v-model.
26
+ Do not apply that rule to item identifiers such as Checkbox.value or Option.value.
27
+ - `v-model` already writes emitted updates back to the binding. Add `@change`
28
+ only for a business side effect, not a redundant assignment. Payloads differ
29
+ by component: Input change supplies a string, not a DOM event.
30
+ - Choose one state channel. Do not simultaneously bind modelValue and a named
31
+ checked/range channel unless the installed API explicitly requires it.
32
+ - React refs use current; Vue script refs use value and templates unwrap refs.
33
+ Query the target's exposed methods; an element ref is not a component handle.
34
+
35
+ ## Source-checked mappings
36
+
37
+ | React | Vue | Important distinction |
38
+ | --- | --- | --- |
39
+ | Input value/onChange | Input v-model | Preserve external updates, clear, readonly and Form ownership. |
40
+ | prefix/suffix ReactNode | #prefix / #suffix | Prefer named templates in .vue files instead of constructing nodes with h. |
41
+ | Button icon={Search} | :icon="Search" | Import icon data from kui-icons. Neither accepts a rendered Icon for this prop. Native submit uses htmlType. |
42
+ | Dropdown children / overlay | default / #overlay slots | Default content triggers the popup; v-model:show controls visibility. |
43
+ | Modal open/onOpenChange | v-model | Modal uses the default model, NOT v-model:open. |
44
+ | Popup open/onOpenChange | v-model:open | Preserve trigger/dismissal rules; avoid extra document-click handlers. |
45
+ | Menu value/onChange or selectedKeys | v-model | Selection is an array; preserve item identity. |
46
+ | Menu openKeys/onOpenChange | v-model:openKeys | Expansion is independent of selection. |
47
+ | MenuItem itemKey | MenuItem :key | Vue reads the vnode key. React's reconciliation key is not itemKey. Data-driven menu items use their key field. |
48
+ | DatePicker value/onChange | v-model | Range model is a pair; named startDate/endDate bindings are an alternative. Verify valueType, clear values and mode. |
49
+ | Checkbox/Radio checked state | v-model or documented named checked binding | value identifies a group item, label is display text. Do not replace them with a boolean. Inspect change payloads individually. |
50
+ | Switch checked state | v-model:checked for boolean state | Default v-model can use valueType conversion; do not assume its payload is always boolean. |
51
+ | Form model/onChange | reactive model passed with :model | FormItem prop can own field binding; do not add a competing v-model. Submit payload contains valid. |
52
+ | Select onChange / onSelect | @change / @select | Selected value and option information are different events; inspect single/multiple types. |
53
+ | KImage | Image | Verify actual named exports. |
54
+ | Table column render callbacks | Target column API / documented slots | Query exact row/index/column signatures; preserve rowKey, selection, pagination, loading and empty state. |
55
+ | className | class | Preserve scoped/global style boundaries rather than copying JSX styling blindly. |
56
+
57
+ Reset is not cancel: clearing registered Form fields does not restore an original
58
+ edit snapshot. Preserve the application draft separately if cancel means revert.
59
+ Modal confirmation likewise needs the application's save/error/close policy.
60
+
61
+ ## Prefer Vue templates
62
+
63
+ ```vue
64
+ <script setup lang="ts">
65
+ import { ref } from "vue";
66
+ import { Input, Icon, Tag } from "kui-vue";
67
+ import { Search } from "kui-icons";
68
+ const keyword = ref("");
69
+ </script>
70
+
71
+ <template>
72
+ <Input v-model="keyword" placeholder="Search">
73
+ <template #prefix><Icon :type="Search" /></template>
74
+ <template #suffix><Tag theme="outline">⌘K</Tag></template>
75
+ </Input>
76
+ </template>
77
+ ```
78
+
79
+ Import `kui-vue/style/index.css` once in the application entry. Slots may carry
80
+ scoped parameters: inspect the target example before replacing render props.
81
+ For lists use stable keys, not array indices when rows can move or be removed.
82
+
83
+ ## Theme and runtime
84
+
85
+ Vue exports `theme.setThemeMode` too. Call it from a client click handler with
86
+ the native MouseEvent, for example `@click="theme.setThemeMode($event)"` after
87
+ importing theme from kui-vue. Do not copy React's event.nativeEvent access.
88
+ The helper toggles the root theme-mode attribute and persistence; keep one
89
+ source of theme state. ConfigProvider appearance is not global light/dark mode.
90
+ Do not call browser-only helpers during server rendering.
91
+
92
+ Keep business logic and backend contracts unchanged. React hooks cannot simply
93
+ be renamed to Vue lifecycle APIs: check reactive dependencies, cleanup, async
94
+ request cancellation, router integration and component unmount behavior.
95
+
96
+ ## Acceptance
97
+
98
+ Migrate one representative page before expanding the change. Run application
99
+ typecheck/lint and CLI validate; inspect skipped/complete because static checks
100
+ do not prove runtime or visual parity. Compare against the React baseline:
101
+
102
+ - form input, external value updates, validation, submit, reset and cancel;
103
+ - disabled/readonly controls, clear actions and focus;
104
+ - menu identity, expansion and navigation;
105
+ - date ranges, formatting and empty values;
106
+ - nested popups, outside click, Escape and placement;
107
+ - table pagination/selection/loading and light/dark appearance.
108
+
109
+ State which flows were actually executed and which still need manual checks.
110
+