react-kui 3.0.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 (481) 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 +4591 -3846
  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 +29 -15
  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 +378 -437
  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 +2 -2
  24. package/es/back-top/index.js +3 -3
  25. package/es/badge/index.js +6 -2
  26. package/es/base/teleport.js +19 -30
  27. package/es/base/transition-props.js +1 -1
  28. package/es/base/transition.js +3 -3
  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 +2 -2
  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 +104 -170
  42. package/es/check-card/check-card-group.js +1 -1
  43. package/es/check-card/check-card.js +143 -143
  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 +131 -112
  48. package/es/checkbox/index.js +1 -1
  49. package/es/collapse/collapse-panel.js +2 -2
  50. package/es/collapse/collapse.js +96 -103
  51. package/es/color-picker/alpha.js +81 -63
  52. package/es/color-picker/hue.js +69 -51
  53. package/es/color-picker/index.js +79 -128
  54. package/es/color-picker/mode.js +1 -1
  55. package/es/color-picker/paint.js +85 -67
  56. package/es/color-picker/presets.js +1 -1
  57. package/es/components.js +4 -2
  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 +591 -678
  65. package/es/descriptions/descriptions-item.js +1 -1
  66. package/es/descriptions/descriptions.js +2 -2
  67. package/es/divider/index.js +1 -1
  68. package/es/drawer/index.js +193 -190
  69. package/es/dropdown/dropdown-button.js +1 -1
  70. package/es/dropdown/dropdown-context.js +1 -1
  71. package/es/dropdown/dropdown.js +173 -331
  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 +2 -2
  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 +2 -2
  93. package/es/image/utils.js +1 -1
  94. package/es/index.js +3 -2
  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 +2 -2
  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 +2 -1
  103. package/es/input-tag/index.js +13 -43
  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 +341 -387
  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 +3 -3
  128. package/es/menu/menu-keyboard.js +1 -1
  129. package/es/menu/menu.js +215 -220
  130. package/es/menu/recursive-menu.js +1 -1
  131. package/es/menu/sub-menu.js +3 -3
  132. package/es/message/index.js +1 -1
  133. package/es/modal/api.js +1 -1
  134. package/es/modal/modal.js +247 -244
  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 +101 -78
  142. package/es/page/responsive.js +96 -0
  143. package/es/page-header/index.js +1 -1
  144. package/es/popconfirm/index.js +89 -241
  145. package/es/poptip/index.js +83 -243
  146. package/es/popup/index.js +429 -0
  147. package/es/popup/layers.js +33 -0
  148. package/es/progress/index.js +1 -1
  149. package/es/qrcode/index.js +1 -1
  150. package/es/radio/radio-button.js +53 -53
  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 +110 -91
  154. package/es/rate/index.js +58 -57
  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 +69 -61
  163. package/es/select/select.js +78 -213
  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 +89 -55
  171. package/es/slider/thumb.js +2 -1
  172. package/es/space/index.js +2 -2
  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 +8 -4
  177. package/es/stat-card/rollup.js +122 -0
  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 +2 -2
  181. package/es/stat-card/utils/odometer.js +104 -107
  182. package/es/steps/index.js +1 -1
  183. package/es/switch/index.js +7 -6
  184. package/es/table/column-setting.js +1 -1
  185. package/es/table/index.js +33 -29
  186. package/es/table/utils.js +1 -1
  187. package/es/tabs/tab-panel.js +1 -1
  188. package/es/tabs/tabs.js +15 -6
  189. package/es/tag/index.js +9 -5
  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 +127 -248
  193. package/es/tour/index.js +198 -193
  194. package/es/transfer/index.js +245 -246
  195. package/es/tree/index.js +72 -67
  196. package/es/tree/utils.js +1 -1
  197. package/es/tree-select/index.js +562 -655
  198. package/es/typography/index.js +1 -1
  199. package/es/upload/file-list.js +3 -1
  200. package/es/upload/index.js +8 -8
  201. package/es/upload/picture-sort.js +1 -1
  202. package/es/upload/selector.js +121 -116
  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 +42 -0
  208. package/es/utils/react-node.js +1 -1
  209. package/es/utils/selection-tags.js +55 -0
  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 +35 -29
  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 +2 -2
  236. package/types/affix/index.d.cts +1 -1
  237. package/types/affix/index.d.ts +1 -1
  238. package/types/alert/index.d.cts +2 -1
  239. package/types/alert/index.d.ts +2 -1
  240. package/types/anchor/anchor-link.d.cts +1 -1
  241. package/types/anchor/anchor-link.d.ts +1 -1
  242. package/types/anchor/anchor.d.cts +1 -1
  243. package/types/anchor/anchor.d.ts +1 -1
  244. package/types/auto-complete/index.d.cts +1 -2
  245. package/types/auto-complete/index.d.ts +1 -2
  246. package/types/avatar/avatar-group.d.cts +1 -1
  247. package/types/avatar/avatar-group.d.ts +1 -1
  248. package/types/avatar/avatar.d.cts +1 -1
  249. package/types/avatar/avatar.d.ts +1 -1
  250. package/types/back-top/index.d.cts +1 -1
  251. package/types/back-top/index.d.ts +1 -1
  252. package/types/badge/index.d.cts +1 -1
  253. package/types/badge/index.d.ts +1 -1
  254. package/types/base/transition.d.cts +1 -0
  255. package/types/base/transition.d.ts +1 -0
  256. package/types/breadcrumb/breadcrumb-item.d.cts +1 -1
  257. package/types/breadcrumb/breadcrumb-item.d.ts +1 -1
  258. package/types/breadcrumb/breadcrumb.d.cts +1 -1
  259. package/types/breadcrumb/breadcrumb.d.ts +1 -1
  260. package/types/button/button-group.d.cts +1 -1
  261. package/types/button/button-group.d.ts +1 -1
  262. package/types/button/button.d.cts +1 -1
  263. package/types/button/button.d.ts +1 -1
  264. package/types/calendar/index.d.cts +1 -1
  265. package/types/calendar/index.d.ts +1 -1
  266. package/types/card/index.d.cts +2 -2
  267. package/types/card/index.d.ts +2 -2
  268. package/types/carousel/carousel-item.d.cts +1 -1
  269. package/types/carousel/carousel-item.d.ts +1 -1
  270. package/types/carousel/carousel.d.cts +2 -1
  271. package/types/carousel/carousel.d.ts +2 -1
  272. package/types/carousel/drag.d.cts +19 -0
  273. package/types/carousel/drag.d.ts +19 -0
  274. package/types/cascader/index.d.cts +1 -1
  275. package/types/cascader/index.d.ts +1 -1
  276. package/types/cascader/types.d.cts +1 -2
  277. package/types/cascader/types.d.ts +1 -2
  278. package/types/check-card/types.d.cts +2 -3
  279. package/types/check-card/types.d.ts +2 -3
  280. package/types/checkbox/checkbox-group.d.cts +1 -1
  281. package/types/checkbox/checkbox-group.d.ts +1 -1
  282. package/types/checkbox/checkbox.d.cts +1 -2
  283. package/types/checkbox/checkbox.d.ts +1 -2
  284. package/types/checkbox/index.d.cts +1 -1
  285. package/types/checkbox/index.d.ts +1 -1
  286. package/types/collapse/collapse-panel.d.cts +1 -1
  287. package/types/collapse/collapse-panel.d.ts +1 -1
  288. package/types/collapse/collapse.d.cts +1 -2
  289. package/types/collapse/collapse.d.ts +1 -2
  290. package/types/color-picker/alpha.d.cts +2 -1
  291. package/types/color-picker/alpha.d.ts +2 -1
  292. package/types/color-picker/hue.d.cts +2 -1
  293. package/types/color-picker/hue.d.ts +2 -1
  294. package/types/color-picker/index.d.cts +3 -4
  295. package/types/color-picker/index.d.ts +3 -4
  296. package/types/color-picker/paint.d.cts +2 -1
  297. package/types/color-picker/paint.d.ts +2 -1
  298. package/types/components.d.cts +17 -13
  299. package/types/components.d.ts +17 -13
  300. package/types/date-picker/index.d.cts +3 -4
  301. package/types/date-picker/index.d.ts +3 -4
  302. package/types/descriptions/descriptions.d.cts +1 -1
  303. package/types/descriptions/descriptions.d.ts +1 -1
  304. package/types/divider/index.d.cts +1 -1
  305. package/types/divider/index.d.ts +1 -1
  306. package/types/drawer/index.d.cts +0 -1
  307. package/types/drawer/index.d.ts +0 -1
  308. package/types/dropdown/dropdown-button.d.cts +1 -1
  309. package/types/dropdown/dropdown-button.d.ts +1 -1
  310. package/types/dropdown/dropdown.d.cts +1 -2
  311. package/types/dropdown/dropdown.d.ts +1 -2
  312. package/types/empty/index.d.cts +1 -1
  313. package/types/empty/index.d.ts +1 -1
  314. package/types/feature-card/index.d.cts +1 -1
  315. package/types/feature-card/index.d.ts +1 -1
  316. package/types/feedback-panel/index.d.cts +1 -1
  317. package/types/feedback-panel/index.d.ts +1 -1
  318. package/types/flex/index.d.cts +1 -1
  319. package/types/flex/index.d.ts +1 -1
  320. package/types/form/form.d.cts +1 -1
  321. package/types/form/form.d.ts +1 -1
  322. package/types/grid/grid-item.d.cts +1 -1
  323. package/types/grid/grid-item.d.ts +1 -1
  324. package/types/grid/grid.d.cts +1 -1
  325. package/types/grid/grid.d.ts +1 -1
  326. package/types/icon/index.d.cts +1 -1
  327. package/types/icon/index.d.ts +1 -1
  328. package/types/image/group.d.cts +1 -1
  329. package/types/image/group.d.ts +1 -1
  330. package/types/image/image.d.cts +1 -1
  331. package/types/image/image.d.ts +1 -1
  332. package/types/input/index.d.cts +1 -1
  333. package/types/input/index.d.ts +1 -1
  334. package/types/input/input-base.d.cts +31 -0
  335. package/types/input/input-base.d.ts +31 -0
  336. package/types/input/input-box.d.cts +1 -1
  337. package/types/input/input-box.d.ts +1 -1
  338. package/types/input/input-group.d.cts +1 -1
  339. package/types/input/input-group.d.ts +1 -1
  340. package/types/input/input.d.cts +2 -25
  341. package/types/input/input.d.ts +2 -25
  342. package/types/input/textarea.d.cts +1 -1
  343. package/types/input/textarea.d.ts +1 -1
  344. package/types/input-number/index.d.cts +1 -1
  345. package/types/input-number/index.d.ts +1 -1
  346. package/types/input-otp/index.d.cts +1 -1
  347. package/types/input-otp/index.d.ts +1 -1
  348. package/types/input-tag/index.d.cts +1 -1
  349. package/types/input-tag/index.d.ts +1 -1
  350. package/types/kanban/index.d.cts +1 -1
  351. package/types/kanban/index.d.ts +1 -1
  352. package/types/layout/index.d.cts +2 -2
  353. package/types/layout/index.d.ts +2 -2
  354. package/types/list-panel/index.d.cts +1 -1
  355. package/types/list-panel/index.d.ts +1 -1
  356. package/types/mentions/index.d.cts +1 -1
  357. package/types/mentions/index.d.ts +1 -1
  358. package/types/menu/menu.d.cts +1 -2
  359. package/types/menu/menu.d.ts +1 -2
  360. package/types/modal/modal.d.cts +1 -2
  361. package/types/modal/modal.d.ts +1 -2
  362. package/types/page/index.d.cts +2 -1
  363. package/types/page/index.d.ts +2 -1
  364. package/types/page/responsive.d.cts +1 -0
  365. package/types/page/responsive.d.ts +1 -0
  366. package/types/page-header/index.d.cts +1 -1
  367. package/types/page-header/index.d.ts +1 -1
  368. package/types/popconfirm/index.d.cts +1 -2
  369. package/types/popconfirm/index.d.ts +1 -2
  370. package/types/poptip/index.d.cts +1 -2
  371. package/types/poptip/index.d.ts +1 -2
  372. package/types/popup/index.d.cts +48 -0
  373. package/types/popup/index.d.ts +48 -0
  374. package/types/popup/layers.d.cts +9 -0
  375. package/types/popup/layers.d.ts +9 -0
  376. package/types/popup/types.d.cts +15 -0
  377. package/types/popup/types.d.ts +15 -0
  378. package/types/progress/index.d.cts +1 -1
  379. package/types/progress/index.d.ts +1 -1
  380. package/types/qrcode/index.d.cts +1 -1
  381. package/types/qrcode/index.d.ts +1 -1
  382. package/types/radio/index.d.cts +1 -0
  383. package/types/radio/index.d.ts +1 -0
  384. package/types/radio/radio-button.d.cts +1 -2
  385. package/types/radio/radio-button.d.ts +1 -2
  386. package/types/radio/radio-group.d.cts +1 -1
  387. package/types/radio/radio-group.d.ts +1 -1
  388. package/types/radio/radio.d.cts +1 -2
  389. package/types/radio/radio.d.ts +1 -2
  390. package/types/rate/index.d.cts +1 -1
  391. package/types/rate/index.d.ts +1 -1
  392. package/types/result/index.d.cts +1 -1
  393. package/types/result/index.d.ts +1 -1
  394. package/types/row-col/col.d.cts +1 -1
  395. package/types/row-col/col.d.ts +1 -1
  396. package/types/row-col/row.d.cts +1 -1
  397. package/types/row-col/row.d.ts +1 -1
  398. package/types/segmented/index.d.cts +1 -1
  399. package/types/segmented/index.d.ts +1 -1
  400. package/types/select/index.d.cts +2 -2
  401. package/types/select/index.d.ts +2 -2
  402. package/types/select/option.d.cts +1 -1
  403. package/types/select/option.d.ts +1 -1
  404. package/types/select/select.d.cts +1 -2
  405. package/types/select/select.d.ts +1 -2
  406. package/types/skeleton/skeleton-avatar.d.cts +1 -1
  407. package/types/skeleton/skeleton-avatar.d.ts +1 -1
  408. package/types/skeleton/skeleton-button.d.cts +1 -1
  409. package/types/skeleton/skeleton-button.d.ts +1 -1
  410. package/types/skeleton/skeleton-image.d.cts +1 -1
  411. package/types/skeleton/skeleton-image.d.ts +1 -1
  412. package/types/skeleton/skeleton-text.d.cts +1 -1
  413. package/types/skeleton/skeleton-text.d.ts +1 -1
  414. package/types/skeleton/skeleton.d.cts +1 -1
  415. package/types/skeleton/skeleton.d.ts +1 -1
  416. package/types/slider/index.d.cts +1 -1
  417. package/types/slider/index.d.ts +1 -1
  418. package/types/space/index.d.cts +1 -1
  419. package/types/space/index.d.ts +1 -1
  420. package/types/spin/index.d.cts +1 -1
  421. package/types/spin/index.d.ts +1 -1
  422. package/types/splitter/splitter-panel.d.cts +1 -1
  423. package/types/splitter/splitter-panel.d.ts +1 -1
  424. package/types/splitter/splitter.d.cts +1 -1
  425. package/types/splitter/splitter.d.ts +1 -1
  426. package/types/stat-card/countup.d.cts +1 -1
  427. package/types/stat-card/countup.d.ts +1 -1
  428. package/types/stat-card/rollup.d.cts +3 -2
  429. package/types/stat-card/rollup.d.ts +3 -2
  430. package/types/stat-card/stat-card.d.cts +1 -1
  431. package/types/stat-card/stat-card.d.ts +1 -1
  432. package/types/stat-card/stat-number.d.cts +1 -1
  433. package/types/stat-card/stat-number.d.ts +1 -1
  434. package/types/stat-card/utils/countup.d.cts +1 -1
  435. package/types/stat-card/utils/countup.d.ts +1 -1
  436. package/types/stat-card/utils/odometer.d.cts +7 -4
  437. package/types/stat-card/utils/odometer.d.ts +7 -4
  438. package/types/steps/index.d.cts +1 -1
  439. package/types/steps/index.d.ts +1 -1
  440. package/types/switch/index.d.cts +1 -2
  441. package/types/switch/index.d.ts +1 -2
  442. package/types/table/index.d.cts +1 -1
  443. package/types/table/index.d.ts +1 -1
  444. package/types/table/types.d.cts +2 -4
  445. package/types/table/types.d.ts +2 -4
  446. package/types/tabs/index.d.cts +1 -0
  447. package/types/tabs/index.d.ts +1 -0
  448. package/types/tabs/tab-panel.d.cts +1 -1
  449. package/types/tabs/tab-panel.d.ts +1 -1
  450. package/types/tabs/tabs.d.cts +1 -1
  451. package/types/tabs/tabs.d.ts +1 -1
  452. package/types/tag/index.d.cts +2 -1
  453. package/types/tag/index.d.ts +2 -1
  454. package/types/time-line/timeline-item.d.cts +1 -1
  455. package/types/time-line/timeline-item.d.ts +1 -1
  456. package/types/time-line/timeline.d.cts +1 -1
  457. package/types/time-line/timeline.d.ts +1 -1
  458. package/types/tooltip/index.d.cts +2 -2
  459. package/types/tooltip/index.d.ts +2 -2
  460. package/types/tour/index.d.cts +0 -2
  461. package/types/tour/index.d.ts +0 -2
  462. package/types/transfer/index.d.cts +2 -3
  463. package/types/transfer/index.d.ts +2 -3
  464. package/types/tree/index.d.cts +2 -4
  465. package/types/tree/index.d.ts +2 -4
  466. package/types/tree-select/index.d.cts +2 -3
  467. package/types/tree-select/index.d.ts +2 -3
  468. package/types/typography/index.d.cts +1 -1
  469. package/types/typography/index.d.ts +1 -1
  470. package/types/upload/index.d.cts +1 -2
  471. package/types/upload/index.d.ts +1 -2
  472. package/types/upload/selector.d.cts +1 -1
  473. package/types/upload/selector.d.ts +1 -1
  474. package/types/utils/popup.d.cts +11 -0
  475. package/types/utils/popup.d.ts +11 -0
  476. package/types/utils/selection-tags.d.cts +19 -0
  477. package/types/utils/selection-tags.d.ts +19 -0
  478. package/types/virtual-list/index.d.cts +1 -1
  479. package/types/virtual-list/index.d.ts +1 -1
  480. package/types/watermark/index.d.cts +1 -1
  481. package/types/watermark/index.d.ts +1 -1
package/AI.en-US.md CHANGED
@@ -1,10 +1,61 @@
1
1
  # React KUI AI integration
2
2
 
3
+ Icon prop contract: Button.icon takes IconType[] data imported from kui-icons: import { Search } from 'kui-icons'; use <Button icon={Search} />. Never pass a JSX element (<Icon type={Search} />), a component function, or an icon-name string to icon. For custom rendered content, put <Icon type={Search} /> in Button children. Input prefix/suffix are renderable nodes and must not be confused with Button.icon.
4
+
3
5
  For building React 19.2+ applications with `react-kui`. This is not a Vue plugin.
4
6
 
5
7
  Install `react-kui` and `kui-icons`, then run `pnpm exec react-kui-ai init`. It appends project guidance to AGENTS.md without overwriting existing content or duplicating its section. Install the optional Skill from `node_modules/react-kui/ai/skills/react-kui` using your client's Skill mechanism.
6
8
 
7
- Configure a stdio MCP service with command `pnpm` and args `["exec", "react-kui-mcp"]`, running from the consuming project's directory. Configuration locations vary by client.
9
+ ## MCP server
10
+
11
+ Install `react-kui` and its dependencies in the consuming project first.
12
+ Confirm that the installed version includes `node_modules/react-kui/ai/mcp.mjs`.
13
+ Do not copy the script alone: it needs the package's metadata and dependencies.
14
+
15
+ Run `node -p "process.execPath"` in the project terminal to obtain the Node
16
+ executable's absolute path. For clients using the mcpServers JSON format:
17
+
18
+ ```json
19
+ {
20
+ "mcpServers": {
21
+ "react-kui": {
22
+ "command": "/absolute/path/to/node",
23
+ "args": ["/absolute/path/to/project/node_modules/react-kui/ai/mcp.mjs"]
24
+ }
25
+ }
26
+ }
27
+ ```
28
+
29
+ Replace both placeholders with real absolute paths. A path containing spaces
30
+ remains one string argument. On Windows use forward slashes or escaped
31
+ backslashes in JSON, for example `C:/Program Files/nodejs/node.exe`.
32
+ Other clients may use another configuration format; enter the same command and
33
+ args through their MCP settings instead of copying this JSON unchanged.
34
+
35
+ This configuration does not depend on the client's working directory or pnpm.
36
+ Use `"command": "node"` only if the client can find Node.
37
+ The alternative command `pnpm` with args `["exec", "react-kui-mcp"]` requires
38
+ pnpm on the client's PATH and an explicit working directory pointing to the
39
+ consuming project with the package installed.
40
+
41
+ ### Verify and troubleshoot
42
+
43
+ 1. Launch the absolute Node/script paths in a terminal first. This is a stdio
44
+ service, not a web server. It normally waits silently for input; press Ctrl+C
45
+ to stop. Silence alone does not prove a successful MCP connection.
46
+ 2. Save the client configuration and reconnect. Check successful initialization
47
+ and a tool list containing search_components and get_component_api.
48
+ 3. Call `get_component_api({ "name": "Button" })` and confirm an API response.
49
+ This tests connectivity and resources, not all component interactions.
50
+
51
+ If Node/pnpm cannot be found, check the executable path and client environment.
52
+ If the script cannot be found, check the project path, installation and package
53
+ version. Missing dependencies/metadata require restoring the complete package
54
+ installation with the project's package manager, not copying individual files.
55
+ If terminal startup works but the client fails, inspect client startup and
56
+ handshake logs. Update configuration after moving the project or Node installation.
57
+
58
+ ## Component usage
8
59
 
9
60
  Use named imports and load `react-kui/style/index.css` once. Input onChange receives a value, not a DOM event. Switch uses checked/onChange; Modal uses open/onOpenChange. A Form model supplied by the application must be updated through onChange(nextModel); onSubmit receives { valid }. Button uses htmlType for submit/reset. The image export is KImage. Do not use Vue v-model, slots or app.use.
10
61
 
@@ -21,3 +72,37 @@ Search/example lists accept offset and limit (default 10, max 20). Full resource
21
72
  Versioned npm resources: react-kui/metadata, react-kui/metadata/schema, react-kui/skill. Site builds publish llms.txt, llms-full.txt, kui-components.json and schema/kui-components.schema.json. Prefer installed-version metadata over the latest website.
22
73
 
23
74
  Run `pnpm generate:ai`, `pnpm check:ai-assets` and `pnpm check:ai`. AI tasks cap Node heap and use a single test worker. Templates can be saved as App.tsx in an application with library CSS loaded; replace local mocks with production APIs. Metadata is derived from public React exports, TypeScript props and documentation examples. Explicit behavior contracts supplement inferred types; absent defaults do not imply a particular runtime behavior.
75
+
76
+ ## Installed resources and command-line queries (without MCP)
77
+
78
+ `react-kui/metadata` and `react-kui/skill` are package export specifiers, not
79
+ directories. Resolve them with `node -p "require.resolve('react-kui/metadata')"`
80
+ or run `pnpm exec react-kui-ai paths`. Read the Skill at the returned path before
81
+ implementing unfamiliar APIs.
82
+
83
+ ```bash
84
+ pnpm exec react-kui-ai paths
85
+ pnpm exec react-kui-ai search Input --limit 5
86
+ pnpm exec react-kui-ai api Input --section props
87
+ pnpm exec react-kui-ai api Input --section behavior
88
+ pnpm exec react-kui-ai examples Input
89
+ pnpm exec react-kui-ai templates
90
+ pnpm exec react-kui-ai migration vue-to-react
91
+ pnpm exec react-kui-ai migration react-to-vue
92
+ pnpm exec react-kui-ai validate src/App.tsx
93
+ ```
94
+
95
+ Use `example Input <id>` with an ID from examples; use `template <id>` to read
96
+ one business template. `query <tool-name> '<JSON>'` uses the same engine and
97
+ argument validation as MCP. Results are JSON; invalid usage and errors exit
98
+ nonzero. Source can be piped into `validate -`. Validation remains partial.
99
+
100
+ Run `init` again after upgrading. It refreshes a marked managed block and
101
+ preserves text outside it. For pre-marker guidance, only exact known generated
102
+ lines are migrated; customized wording remains for review. Put project-specific
103
+ rules outside managed markers. Malformed markers cause an error without writes.
104
+
105
+ Metadata describes components, not every package export. For utilities such as
106
+ theme, inspect the installed declarations too. Before migrating, read
107
+ `migration vue-to-react` or `migration react-to-vue`, then compare callbacks, state synchronization,
108
+ slots/render props and interaction behavior—not just typecheck results.
package/AI.md CHANGED
@@ -1,5 +1,7 @@
1
1
  # React KUI AI 辅助开发
2
2
 
3
+ 图标属性注意:`Button.icon` 接收从 `kui-icons` 导入的 `IconType[]` 图标数据。例如 `import { Search } from 'kui-icons'` 后使用 `<Button icon={Search} />`,不要传 `<Icon type={Search} />`、组件函数或图标名称字符串。自定义 JSX 放在 Button 的 children 中;Input 的 prefix/suffix 接收渲染内容,与 Button.icon 不是同一种接口。
4
+
3
5
  用于帮助 AI **使用 react-kui 开发 React 应用**。支持 React 19.2+,npm 包名为 `react-kui`;不是 `kui-react`,也不是 Vue 插件。
4
6
 
5
7
  ## 接入
@@ -11,20 +13,51 @@ pnpm exec react-kui-ai init
11
13
 
12
14
  初始化会追加项目 `AGENTS.md` 的 React KUI 使用约定,保留已有内容,重复执行不重复写入。Agent Skill 位于 `node_modules/react-kui/ai/skills/react-kui`,可按所用客户端的 Skill 安装方式接入。
13
15
 
14
- 在支持 stdio MCP 的客户端中添加服务,并将工作目录设置为已安装 react-kui 的应用目录:
16
+ 先在应用项目中安装 `react-kui` 及其依赖(见上面的安装命令),并确认安装版本包含
17
+ `node_modules/react-kui/ai/mcp.mjs`。不要只复制这个脚本,它还需要同包的元数据和依赖。
18
+
19
+ 在项目终端中运行以下命令,取得 Node 的绝对路径:
20
+
21
+ ```bash
22
+ node -p "process.execPath"
23
+ ```
24
+
25
+ 在支持 stdio MCP 的客户端中配置服务。下面是支持 `mcpServers` 格式的客户端示例;
26
+ 其他客户端请通过 MCP 设置填写相同的 command 和 args,不要直接照搬整个 JSON:
15
27
 
16
28
  ```json
17
29
  {
18
30
  "mcpServers": {
19
31
  "react-kui": {
20
- "command": "pnpm",
21
- "args": ["exec", "react-kui-mcp"]
32
+ "command": "/absolute/path/to/node",
33
+ "args": ["/absolute/path/to/project/node_modules/react-kui/ai/mcp.mjs"]
22
34
  }
23
35
  }
24
36
  }
25
37
  ```
26
38
 
27
- 不同客户端的配置位置不同;以上是服务启动参数,不要求编辑某个固定的全局配置文件。
39
+ 将 command 替换为上面输出的 Node 路径,将 args 替换为你项目中脚本的绝对路径。
40
+ 路径含空格也仍是一个字符串参数。Windows JSON 路径使用正斜杠或转义反斜杠,例如
41
+ `C:/Program Files/nodejs/node.exe`。该方式不依赖客户端的启动工作目录,也不要求使用 pnpm。
42
+
43
+ 如果客户端能找到 Node,也可以使用 `"command": "node"`。
44
+ 只有在客户端能找到 pnpm、且明确将工作目录设为已安装该包的项目目录时,
45
+ 才使用 `"command": "pnpm"` 和 `"args": ["exec", "react-kui-mcp"]`。
46
+
47
+ ### 验证与排错
48
+
49
+ 1. 先在终端用上述 Node 和脚本路径启动服务。它通过标准输入/输出通信,
50
+ 不会打开网页,也不会主动打印“启动成功”;等待输入是正常状态,按 Ctrl+C 退出。
51
+ 2. 保存客户端配置并重新连接服务。确认初始化成功、工具列表包含
52
+ `search_components` 和 `get_component_api`。
53
+ 3. 查询 `get_component_api({ "name": "Button" })`,确认能返回组件 API。
54
+ 这验证连接和资源读取,不代表所有组件交互都已验证。
55
+
56
+ 若提示找不到 node/pnpm,请检查 command 的绝对路径及客户端环境;
57
+ 找不到脚本,请检查项目路径、依赖安装和包版本;
58
+ 脚本缺少依赖或元数据,请用项目的包管理器恢复完整安装,不要单独搬运脚本。
59
+ 终端可运行但客户端失败时,查看客户端日志中的启动命令和握手错误。
60
+ 项目路径或 Node 安装路径变更后也需要更新配置。
28
61
 
29
62
  ## React 的使用约定
30
63
 
@@ -74,3 +107,34 @@ pnpm check:ai
74
107
  元数据从 React 的公开导出、TypeScript Props 和真实文档示例生成。默认表达式只在可确定提取时提供,不代表所有运行时默认行为。行为约定重点覆盖表单、输入、弹层、表格、分页、菜单等核心组件。
75
108
 
76
109
  AI 生成与校验命令限制 Node 堆,测试按单工作进程运行,避免在低内存机器上并发启动重任务。无需运行完整构建即可更新 AI 资源。
110
+
111
+ ## 不配置 MCP 也可以查询
112
+
113
+ `react-kui/metadata` 和 `react-kui/skill` 是 npm 包的导出路径,**不是目录**。
114
+ 可以运行 `node -p "require.resolve('react-kui/metadata')"` 定位文件,也可以使用
115
+ 下面的 `paths` 命令。开始实现前先阅读返回路径中的 Skill。
116
+
117
+ ```bash
118
+ pnpm exec react-kui-ai paths
119
+ pnpm exec react-kui-ai search Input --limit 5
120
+ pnpm exec react-kui-ai api Input --section props
121
+ pnpm exec react-kui-ai api Input --section behavior
122
+ pnpm exec react-kui-ai examples Input
123
+ pnpm exec react-kui-ai templates
124
+ pnpm exec react-kui-ai migration vue-to-react
125
+ pnpm exec react-kui-ai migration react-to-vue
126
+ pnpm exec react-kui-ai validate src/App.tsx
127
+ ```
128
+
129
+ 从 examples 结果取得 ID 后,用 `example Input <id>` 读取单个示例;
130
+ 用 `template <id>` 读取业务模板。`query <工具名> '<JSON>'` 与 MCP 共用查询逻辑
131
+ 和参数校验,无需启动 MCP。结果为 JSON;参数错误或校验不通过返回非零退出码。
132
+ `validate -` 可以读取标准输入,仍不能替代类型检查和交互测试。
133
+
134
+ 升级依赖后重新执行 `init`,会更新 AGENTS.md 中带标记的托管区域,保留区域外的
135
+ 项目规则。旧版没有标记的段落仅迁移能精确识别的生成行;修改过的自定义文本保留,
136
+ 需要自行检查是否过时。项目规则应放在托管区域外,标记损坏时命令报错且不写入。
137
+
138
+ 组件元数据不覆盖所有工具导出,例如 theme 还需查安装版本的声明。
139
+ 迁移前按方向运行 `migration vue-to-react` 或 `migration react-to-vue` 阅读差异指南,核对绑定、回调、插槽与交互,
140
+ 不要把类型检查通过当作迁移验收。
package/ai/behaviors.json CHANGED
@@ -1,16 +1,116 @@
1
1
  {
2
- "Form": { "rules": ["When model is supplied, update React state with onChange(nextModel); the library does not mutate the caller's model object. Without model, Form keeps an internal model.", "FormItem prop selects a model field; supported child controls receive the field value and change handler automatically.", "onSubmit receives { valid }, not a DOM submit event. Save only when valid is true. Button htmlType=submit triggers validation.", "disabled and readOnly are inherited by supported form controls; explicit child props override inherited state.", "reset clears registered fields to null and emits onChange/onReset; it does not restore an original snapshot."], "methods": ["ref.current.validate(): Promise<{ valid: boolean }>", "ref.current.reset(): void", "ref.current.submit(): Promise<void>"] },
3
- "FormItem": { "rules": ["Use inside Form. prop is the field path, not the field value. Do not copy Vue v-model bindings."] },
4
- "Input": { "rules": ["Use value and onChange(nextValue). onChange receives a string, not a DOM event.", "Input uses synchronized local state: edits can stay local until the parent supplies a different value. Do not promise strict native controlled-input semantics. Keep application state updated through onChange."] },
5
- "Button": { "rules": ["Use htmlType=submit/reset for form actions; type is visual intent, not native button type.", "icon takes an icon definition imported from kui-icons."] },
6
- "Switch": { "rules": ["Use checked and onChange, or defaultChecked. When checked is supplied, the parent must update it.", "checked is boolean. onChange returns boolean/string/number according to valueType; default valueType is boolean."] },
7
- "Modal": { "rules": ["Use open plus onOpenChange, or defaultOpen. When open is supplied, update it in the parent.", "onOk does not automatically save or close. Validate/save first, then set open=false. loading blocks user dismissal during saving.", "Use children or content and footer props, not Vue named slots."] },
8
- "Drawer": { "rules": ["Use open plus onOpenChange for controlled visibility. Keep the state in React; do not use v-model."] },
9
- "Page": { "rules": ["Pages are one-based. onChange(page, pageSize) reports both values. Update application page/pageSize state and fetch data explicitly."] },
10
- "Table": { "rules": ["Pass data and columns. Set rowKey to a stable unique field; the default is key.", "The component does not call your backend. For remote paging, combine Page with explicit loading/error state and protect against stale responses.", "Use render callbacks/ReactNode props from the API; Vue slot syntax is invalid."] },
11
- "Menu": { "rules": ["Use selectedKeys or value with onChange for selection; openKeys with onOpenChange controls expanded submenus. Do not use Vue update events."] },
12
- "ConfigProvider": { "rules": ["Wrap children to supply locale, size, theme and shape. Explicit component props override provider values. Import locales from react-kui/locale/<locale>."] },
13
- "Select": { "rules": ["Use value and onChange, not v-model. Multiple selection requires an array; consult the onChange signature for the value and option data."] },
14
- "KImage": { "rules": ["The public React export is KImage, not the Vue Image component name."] },
15
- "Space": { "rules": ["Use children and compact. Vertical compact layout supports Button groups. Use className, not class."] }
2
+ "Form": {
3
+ "rules": [
4
+ "When model is supplied, update React state with onChange(nextModel); the library does not mutate the caller's model object. Without model, Form keeps an internal model.",
5
+ "FormItem prop selects a model field; supported child controls receive the field value and change handler automatically.",
6
+ "onSubmit receives { valid }, not a DOM submit event. Save only when valid is true. Button htmlType=submit triggers validation.",
7
+ "disabled and readOnly are inherited by supported form controls; explicit child props override inherited state.",
8
+ "reset clears registered fields to null and emits onChange/onReset; it does not restore an original snapshot."
9
+ ],
10
+ "methods": [
11
+ "ref.current.validate(): Promise<{ valid: boolean }>",
12
+ "ref.current.reset(): void",
13
+ "ref.current.submit(): Promise<void>"
14
+ ]
15
+ },
16
+ "FormItem": {
17
+ "rules": [
18
+ "Use inside Form. prop is the field path, not the field value. Do not copy Vue v-model bindings."
19
+ ]
20
+ },
21
+ "Input": {
22
+ "rules": [
23
+ "Use value and onChange(nextValue). onChange receives a string, not a DOM event.",
24
+ "Input uses synchronized local state: edits can stay local until the parent supplies a different value. Do not promise strict native controlled-input semantics. Keep application state updated through onChange."
25
+ ]
26
+ },
27
+ "Button": {
28
+ "rules": [
29
+ "Use htmlType=submit/reset for form actions; type is visual intent, not native button type.",
30
+ "Button.icon takes IconType[] data imported from kui-icons: import { Search } from 'kui-icons'; use <Button icon={Search} />. Never pass a JSX element (<Icon type={Search} />), a component function, or an icon-name string to icon. For custom rendered content, put <Icon type={Search} /> in Button children. Input prefix/suffix are renderable nodes and must not be confused with Button.icon."
31
+ ]
32
+ },
33
+ "Switch": {
34
+ "rules": [
35
+ "Use checked and onChange. checked initializes local state; interactions update it internally, and changed checked props synchronize it.",
36
+ "checked is boolean. onChange returns boolean/string/number according to valueType; default valueType is boolean."
37
+ ]
38
+ },
39
+ "Modal": {
40
+ "rules": [
41
+ "Use open and onOpenChange. open initializes local visibility; interactions update it internally, and changed open props synchronize it.",
42
+ "onOk does not automatically save or close. Validate/save first, then set open=false. loading blocks user dismissal during saving.",
43
+ "Use children or content and footer props, not Vue named slots."
44
+ ]
45
+ },
46
+ "Drawer": {
47
+ "rules": [
48
+ "Use open and onOpenChange. open initializes local visibility, allows interaction, and synchronizes changed props. Do not use v-model."
49
+ ]
50
+ },
51
+ "Page": {
52
+ "rules": [
53
+ "Pages are one-based. onChange(page, pageSize) reports both values. Update application page/pageSize state and fetch data explicitly."
54
+ ]
55
+ },
56
+ "Table": {
57
+ "rules": [
58
+ "Pass data and columns. Set rowKey to a stable unique field; the default is key.",
59
+ "The component does not call your backend. For remote paging, combine Page with explicit loading/error state and protect against stale responses.",
60
+ "Use render callbacks/ReactNode props from the API; Vue slot syntax is invalid."
61
+ ]
62
+ },
63
+ "Menu": {
64
+ "rules": [
65
+ "Use selectedKeys or value with onChange for selection; openKeys with onOpenChange controls expanded submenus. Do not use Vue update events."
66
+ ]
67
+ },
68
+ "ConfigProvider": {
69
+ "rules": [
70
+ "Wrap children to supply locale, size, theme and shape. Explicit component props override provider values. Import locales from react-kui/locale/<locale>."
71
+ ]
72
+ },
73
+ "Select": {
74
+ "rules": [
75
+ "Use value and onChange(value), not v-model. Multiple selection uses an array.",
76
+ "onSelect(option) supplies the selected option and selected flag; onChange does not supply an option as a second argument."
77
+ ]
78
+ },
79
+ "KImage": {
80
+ "rules": [
81
+ "The public React export is KImage, not the Vue Image component name."
82
+ ]
83
+ },
84
+ "Space": {
85
+ "rules": [
86
+ "Use children and compact. Vertical compact layout supports Button groups. Use className, not class."
87
+ ]
88
+ },
89
+ "Dropdown": {
90
+ "rules": [
91
+ "children is the trigger; overlay supplies popup content. Do not place the menu in children as a translation of the Vue overlay slot."
92
+ ]
93
+ },
94
+ "DatePicker": {
95
+ "rules": [
96
+ "Use value/onChange for a single date or a range array when the selected mode is a range. startDate/endDate with onStartDateChange/onEndDateChange are an alternative binding channel, not the only API.",
97
+ "onChange receives (date, dateStr); output depends on valueType and mode. Handle clear/null values explicitly and avoid supplying conflicting binding channels."
98
+ ]
99
+ },
100
+ "Checkbox": {
101
+ "rules": [
102
+ "Use checked for the checked state; value identifies an item in a CheckboxGroup. onChange receives an object with checked and optional value/label, not the Switch scalar callback."
103
+ ]
104
+ },
105
+ "Popup": {
106
+ "rules": [
107
+ "Use children for the trigger and overlay for the popup content. open/onOpenChange synchronizes visibility; query the callback detail type for dismissal reasons.",
108
+ "The shared Popup manages nested layers; do not implement an extra document-click closer that can close parent pickers during nested selections."
109
+ ]
110
+ },
111
+ "MenuItem": {
112
+ "rules": [
113
+ "Use itemKey to identify the menu item. React key alone is not forwarded as itemKey."
114
+ ]
115
+ }
16
116
  }
package/ai/cli.mjs CHANGED
@@ -2,26 +2,189 @@
2
2
  import fs from "node:fs";
3
3
  import path from "node:path";
4
4
  import process from "node:process";
5
+ import { fileURLToPath } from "node:url";
6
+ import { executeTool, metadata } from "./query.mjs";
5
7
 
6
- const command = process.argv[2] || "help";
7
- const cwd = process.cwd();
8
- const marker = "## React KUI\n";
9
- const instructions = `${marker}
10
- - This project uses React 19.2+ and React KUI. Prefer components and public APIs documented at https://react.k-ui.cn.
11
- - Import components from \`react-kui\` and icons from \`kui-icons\`; import \`react-kui/style/index.css\` once.
12
- - Read the installed \`react-kui/metadata\` before using unfamiliar props, callbacks, or render props. Do not invent component APIs. Use React state and callbacks, never Vue v-model or slots.
13
- - Keep \`theme\`, \`size\`, and \`shape\` consistent and run typecheck/lint after edits.
14
- `;
8
+ const packageName = "react-kui";
9
+ const heading = "## React KUI";
10
+ const legacyLines = [
11
+ "- This project uses React 19.2+ and React KUI. Prefer components and public APIs documented at https://react.k-ui.cn.",
12
+ "- Import components from `react-kui` and icons from `kui-icons`; import `react-kui/style/index.css` once.",
13
+ "- Read the installed `react-kui/metadata` before using unfamiliar props, callbacks, or render props. Do not invent component APIs. Use React state and callbacks, never Vue v-model or slots.",
14
+ "- Keep `theme`, `size`, and `shape` consistent and run typecheck/lint after edits.",
15
+ "- Button.icon takes IconType[] data imported from kui-icons: import { Search } from 'kui-icons'; use <Button icon={Search} />. Never pass a JSX element (<Icon type={Search} />), a component function, or an icon-name string to icon. For custom rendered content, put <Icon type={Search} /> in Button children. Input prefix/suffix are renderable nodes and must not be confused with Button.icon.",
16
+ ];
17
+ const begin = `<!-- ${packageName}:start -->`;
18
+ const end = `<!-- ${packageName}:end -->`;
19
+ const bin = `${packageName}-ai`;
20
+ const root = fileURLToPath(new URL("../", import.meta.url));
21
+ const help = `Usage: ${bin} <command>
22
+ init Update managed guidance in ./AGENTS.md
23
+ paths Show installed version and resource paths
24
+ search <query> [--offset N] [--limit N]
25
+ api <component> [--section NAME] API without example source
26
+ examples <component> [--offset N] [--limit N]
27
+ example <component> <id> Read one example from examples output
28
+ templates [query]
29
+ template <id>
30
+ validate <file|-> Check a source file or stdin; exit 1 if invalid
31
+ migration [vue-to-react|react-to-vue] Read migration guidance (default: vue-to-react)
32
+ query <MCP-tool-name> '<JSON>' Same query engine, no MCP setup required
33
+ help
34
+ All queries return JSON. Limits: 1–20, default 10. Errors exit nonzero.
35
+ Package export specifiers (e.g. ${packageName}/metadata) are not directories.`;
15
36
 
16
- if (command === "init") {
17
- const target = path.join(cwd, "AGENTS.md");
37
+ function guidance() {
38
+ return `${begin}
39
+ Installed ${packageName} guidance (version ${metadata.version}; managed by ${bin} init).
40
+ - Read the installed Skill before implementation: node_modules/${packageName}/ai/skills/${packageName}/SKILL.md. If this path is unavailable, run pnpm exec ${bin} paths to resolve it.
41
+ - ${packageName}/metadata and ${packageName}/skill are package export specifiers, NOT directories. Resolve them with node -p "require.resolve('${packageName}/metadata')" or use pnpm exec ${bin} paths.
42
+ - Without MCP, use pnpm exec ${bin} search Input, api Input --section props, api Input --section behavior, examples Input, and example Input <id>. Run help for arguments. Do not read the entire metadata JSON at once.
43
+ - For migration, read pnpm exec ${bin} migration vue-to-react or migration react-to-vue and query both installed libraries. Confirm both versions; declarations verify types, examples and behavior contracts verify usage.
44
+ - Import components from ${packageName}, icons from kui-icons, and ${packageName}/style/index.css once. Button.icon accepts imported icon data, not a rendered Icon element.
45
+ - Run pnpm exec ${bin} validate <file>, then application typecheck and interaction tests. Validation is partial; inspect skipped/complete and do not equate typecheck success with behavioral parity.
46
+ - Prefer installed-version resources over online docs. Do not invent APIs. Project-specific instructions outside this managed block are preserved.
47
+ ${end}`;
48
+ }
49
+
50
+ function init() {
51
+ const target = path.resolve("AGENTS.md");
18
52
  const current = fs.existsSync(target) ? fs.readFileSync(target, "utf8") : "";
19
- if (!current.includes(marker.trim())) {
20
- fs.writeFileSync(target, `${current.trim()}${current.trim() ? "\n\n" : ""}${instructions}`);
21
- console.log(`Added React KUI guidance to ${target}`);
53
+ const start = current.indexOf(begin);
54
+ const finish = current.indexOf(end);
55
+ let next;
56
+ if (start >= 0 || finish >= 0) {
57
+ if (
58
+ start < 0 ||
59
+ finish < start ||
60
+ current.indexOf(begin, start + begin.length) >= 0 ||
61
+ current.indexOf(end, finish + end.length) >= 0
62
+ ) {
63
+ throw new Error("Malformed or duplicate managed markers in AGENTS.md; no changes made.");
64
+ }
65
+ next = current.slice(0, start) + guidance() + current.slice(finish + end.length);
66
+ } else {
67
+ // Upgrade only exact lines emitted by the previous initializer in its own
68
+ // section. Never replace an entire user-maintained heading or paragraph.
69
+ const lines = current.split(/(?<=\n)/);
70
+ let inSection = false;
71
+ next = lines
72
+ .filter((line) => {
73
+ const trimmed = line.trim();
74
+ if (/^##\s/.test(trimmed)) inSection = trimmed === heading;
75
+ return !(inSection && legacyLines.includes(trimmed));
76
+ })
77
+ .join("");
78
+ const headingMatch = new RegExp("^" + heading + "\\r?$", "m").exec(next);
79
+ if (headingMatch) {
80
+ const position = headingMatch.index + headingMatch[0].length;
81
+ next = next.slice(0, position) + "\n\n" + guidance() + next.slice(position);
82
+ } else {
83
+ next +=
84
+ (next ? (next.endsWith("\n") ? "\n" : "\n\n") : "") + heading + "\n\n" + guidance() + "\n";
85
+ }
86
+ }
87
+ if (next !== current) fs.writeFileSync(target, next);
88
+ console.log(
89
+ JSON.stringify({ file: target, updated: next !== current, version: metadata.version }, null, 2),
90
+ );
91
+ }
92
+
93
+ function parseOptions(tokens) {
94
+ const args = [];
95
+ const options = {};
96
+ for (let i = 0; i < tokens.length; i++) {
97
+ const token = tokens[i];
98
+ if (!token.startsWith("--")) {
99
+ args.push(token);
100
+ continue;
101
+ }
102
+ const key = token.slice(2);
103
+ if (
104
+ !["offset", "limit", "section"].includes(key) ||
105
+ key in options ||
106
+ tokens[i + 1] === undefined
107
+ )
108
+ throw new Error(`Invalid option: ${token}`);
109
+ const value = tokens[++i];
110
+ options[key] = key === "section" ? value : Number(value);
111
+ }
112
+ return { args, options };
113
+ }
114
+
115
+ try {
116
+ const [command = "help", ...tokens] = process.argv.slice(2);
117
+ if (["help", "--help", "-h"].includes(command)) {
118
+ console.log(help);
119
+ } else if (command === "init") {
120
+ if (tokens.length) throw new Error("init takes no arguments");
121
+ init();
122
+ } else if (command === "paths") {
123
+ if (tokens.length) throw new Error("paths takes no arguments");
124
+ console.log(
125
+ JSON.stringify(
126
+ {
127
+ library: packageName,
128
+ version: metadata.version,
129
+ metadata: path.join(root, "ai/kui-components.json"),
130
+ skill: path.join(root, `ai/skills/${packageName}/SKILL.md`),
131
+ migration: path.join(root, `ai/skills/${packageName}/references/vue-to-react.md`),
132
+ reverseMigration: path.join(root, `ai/skills/${packageName}/references/react-to-vue.md`),
133
+ },
134
+ null,
135
+ 2,
136
+ ),
137
+ );
138
+ } else if (command === "migration") {
139
+ const direction = tokens[0] || "vue-to-react";
140
+ if (tokens.length > 1 || !["vue-to-react", "react-to-vue"].includes(direction))
141
+ throw new Error("migration expects vue-to-react or react-to-vue");
142
+ const guide = direction === "react-to-vue" ? "react-to-vue.md" : "vue-to-react.md";
143
+ console.log(
144
+ JSON.stringify(
145
+ {
146
+ version: metadata.version,
147
+ source: fs.readFileSync(
148
+ path.join(root, `ai/skills/${packageName}/references/${guide}`),
149
+ "utf8",
150
+ ),
151
+ },
152
+ null,
153
+ 2,
154
+ ),
155
+ );
156
+ } else if (command === "query") {
157
+ if (tokens.length !== 2) throw new Error("query requires a tool name and JSON arguments");
158
+ const result = executeTool(tokens[0], JSON.parse(tokens[1]));
159
+ console.log(JSON.stringify(result, null, 2));
160
+ if (tokens[0] === "validate_kui_usage" && !result.valid) process.exitCode = 1;
22
161
  } else {
23
- console.log("React KUI guidance already exists in AGENTS.md");
162
+ const { args, options } = parseOptions(tokens);
163
+ const commands = {
164
+ search: ["search_components", ["query"]],
165
+ api: ["get_component_api", ["name"]],
166
+ examples: ["list_component_examples", ["name"]],
167
+ example: ["get_component_example", ["name", "id"]],
168
+ templates: ["list_templates", ["query"]],
169
+ template: ["get_template", ["id"]],
170
+ validate: ["validate_kui_usage", ["source"]],
171
+ };
172
+ const entry = commands[command];
173
+ if (!entry) throw new Error(`Unknown command: ${command}. Run ${bin} help.`);
174
+ const [tool, keys] = entry;
175
+ if (args.length !== keys.length && !(command === "templates" && !args.length))
176
+ throw new Error(`${command} expects ${keys.join(", ")}; quote arguments containing spaces.`);
177
+ const params = { ...options };
178
+ args.forEach((value, i) => {
179
+ params[keys[i]] = value;
180
+ });
181
+ if (command === "validate")
182
+ params.source = fs.readFileSync(args[0] === "-" ? 0 : args[0], "utf8");
183
+ const result = executeTool(tool, params);
184
+ console.log(JSON.stringify(result, null, 2));
185
+ if (command === "validate" && !result.valid) process.exitCode = 1;
24
186
  }
25
- } else {
26
- console.log("Usage: react-kui-ai init");
187
+ } catch (error) {
188
+ console.error(JSON.stringify({ error: error.message }));
189
+ process.exitCode = 1;
27
190
  }