@ug666/ui-react 0.3.0-beta.2 → 0.3.0-beta.4

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 (279) hide show
  1. package/LICENSE +21 -0
  2. package/dist/RELEASE_PROVENANCE.json +8 -0
  3. package/dist/ai/SKILL.md +245 -0
  4. package/dist/ai/manifest.json +819 -0
  5. package/dist/ai/references/components/accordion.md +41 -0
  6. package/dist/ai/references/components/admin-shell.md +27 -0
  7. package/dist/ai/references/components/alert.md +40 -0
  8. package/dist/ai/references/components/app-tabs.md +27 -0
  9. package/dist/ai/references/components/attachment-list.md +27 -0
  10. package/dist/ai/references/components/autocomplete.md +41 -0
  11. package/dist/ai/references/components/avatar-group.md +39 -0
  12. package/dist/ai/references/components/avatar.md +39 -0
  13. package/dist/ai/references/components/backtop.md +40 -0
  14. package/dist/ai/references/components/badge.md +43 -0
  15. package/dist/ai/references/components/bar-chart.md +41 -0
  16. package/dist/ai/references/components/breadcrumb.md +41 -0
  17. package/dist/ai/references/components/button.md +39 -0
  18. package/dist/ai/references/components/calendar.md +42 -0
  19. package/dist/ai/references/components/card.md +39 -0
  20. package/dist/ai/references/components/carousel.md +41 -0
  21. package/dist/ai/references/components/cascader.md +43 -0
  22. package/dist/ai/references/components/checkbox.md +40 -0
  23. package/dist/ai/references/components/collapse.md +41 -0
  24. package/dist/ai/references/components/color-picker.md +42 -0
  25. package/dist/ai/references/components/config-provider.md +39 -0
  26. package/dist/ai/references/components/confirm-dialog.md +27 -0
  27. package/dist/ai/references/components/container.md +39 -0
  28. package/dist/ai/references/components/context-menu.md +40 -0
  29. package/dist/ai/references/components/conversation-list.md +27 -0
  30. package/dist/ai/references/components/copy-field.md +27 -0
  31. package/dist/ai/references/components/data-panel.md +43 -0
  32. package/dist/ai/references/components/data-table-identity.md +27 -0
  33. package/dist/ai/references/components/data-table-toolbar.md +27 -0
  34. package/dist/ai/references/components/data-table.md +32 -0
  35. package/dist/ai/references/components/date-picker.md +42 -0
  36. package/dist/ai/references/components/date-range-picker.md +43 -0
  37. package/dist/ai/references/components/date-time-picker.md +40 -0
  38. package/dist/ai/references/components/descriptions.md +40 -0
  39. package/dist/ai/references/components/dialog.md +40 -0
  40. package/dist/ai/references/components/dock.md +41 -0
  41. package/dist/ai/references/components/donut-chart.md +41 -0
  42. package/dist/ai/references/components/drawer.md +41 -0
  43. package/dist/ai/references/components/dropdown.md +42 -0
  44. package/dist/ai/references/components/empty-state.md +40 -0
  45. package/dist/ai/references/components/fab.md +41 -0
  46. package/dist/ai/references/components/feature-grid.md +27 -0
  47. package/dist/ai/references/components/fieldset.md +41 -0
  48. package/dist/ai/references/components/file-input.md +41 -0
  49. package/dist/ai/references/components/form.md +42 -0
  50. package/dist/ai/references/components/gauge-chart.md +41 -0
  51. package/dist/ai/references/components/heatmap-chart.md +41 -0
  52. package/dist/ai/references/components/icon.md +39 -0
  53. package/dist/ai/references/components/image.md +41 -0
  54. package/dist/ai/references/components/index.md +171 -0
  55. package/dist/ai/references/components/indicator.md +41 -0
  56. package/dist/ai/references/components/infinite-scroll.md +42 -0
  57. package/dist/ai/references/components/input.md +42 -0
  58. package/dist/ai/references/components/join.md +40 -0
  59. package/dist/ai/references/components/kbd.md +40 -0
  60. package/dist/ai/references/components/label.md +39 -0
  61. package/dist/ai/references/components/landing-hero.md +27 -0
  62. package/dist/ai/references/components/layout.md +39 -0
  63. package/dist/ai/references/components/link.md +41 -0
  64. package/dist/ai/references/components/list.md +41 -0
  65. package/dist/ai/references/components/loading.md +40 -0
  66. package/dist/ai/references/components/message.md +27 -0
  67. package/dist/ai/references/components/modal.md +42 -0
  68. package/dist/ai/references/components/navbar.md +41 -0
  69. package/dist/ai/references/components/navigation-menu.md +41 -0
  70. package/dist/ai/references/components/notification.md +41 -0
  71. package/dist/ai/references/components/number-input.md +40 -0
  72. package/dist/ai/references/components/otp-input.md +40 -0
  73. package/dist/ai/references/components/page-header.md +27 -0
  74. package/dist/ai/references/components/pagination.md +42 -0
  75. package/dist/ai/references/components/popconfirm.md +42 -0
  76. package/dist/ai/references/components/popover.md +41 -0
  77. package/dist/ai/references/components/progress.md +41 -0
  78. package/dist/ai/references/components/prompt-composer.md +27 -0
  79. package/dist/ai/references/components/quick-access.md +30 -0
  80. package/dist/ai/references/components/radar-chart.md +41 -0
  81. package/dist/ai/references/components/radial-progress.md +41 -0
  82. package/dist/ai/references/components/radio.md +40 -0
  83. package/dist/ai/references/components/ranking-list.md +41 -0
  84. package/dist/ai/references/components/rating.md +42 -0
  85. package/dist/ai/references/components/result.md +40 -0
  86. package/dist/ai/references/components/scrollbar.md +39 -0
  87. package/dist/ai/references/components/select.md +41 -0
  88. package/dist/ai/references/components/selection-list.md +29 -0
  89. package/dist/ai/references/components/separator.md +39 -0
  90. package/dist/ai/references/components/sheet.md +40 -0
  91. package/dist/ai/references/components/sidebar.md +46 -0
  92. package/dist/ai/references/components/skeleton.md +40 -0
  93. package/dist/ai/references/components/slider.md +40 -0
  94. package/dist/ai/references/components/space.md +39 -0
  95. package/dist/ai/references/components/spinner.md +41 -0
  96. package/dist/ai/references/components/splitter.md +39 -0
  97. package/dist/ai/references/components/stack.md +41 -0
  98. package/dist/ai/references/components/stacked-bar-chart.md +41 -0
  99. package/dist/ai/references/components/statistic-card.md +41 -0
  100. package/dist/ai/references/components/statistic.md +41 -0
  101. package/dist/ai/references/components/steps.md +40 -0
  102. package/dist/ai/references/components/switch.md +40 -0
  103. package/dist/ai/references/components/table.md +41 -0
  104. package/dist/ai/references/components/tabs.md +41 -0
  105. package/dist/ai/references/components/tag.md +39 -0
  106. package/dist/ai/references/components/text.md +39 -0
  107. package/dist/ai/references/components/textarea.md +40 -0
  108. package/dist/ai/references/components/theme-configurator-dialog.md +27 -0
  109. package/dist/ai/references/components/theme-configurator.md +27 -0
  110. package/dist/ai/references/components/theme-controller.md +41 -0
  111. package/dist/ai/references/components/time-picker.md +42 -0
  112. package/dist/ai/references/components/time-range-picker.md +41 -0
  113. package/dist/ai/references/components/time-select.md +40 -0
  114. package/dist/ai/references/components/timeline.md +41 -0
  115. package/dist/ai/references/components/toast.md +39 -0
  116. package/dist/ai/references/components/tooltip.md +39 -0
  117. package/dist/ai/references/components/transfer.md +41 -0
  118. package/dist/ai/references/components/tree-select.md +45 -0
  119. package/dist/ai/references/components/tree-table.md +27 -0
  120. package/dist/ai/references/components/tree.md +43 -0
  121. package/dist/ai/references/components/trend-chart.md +41 -0
  122. package/dist/ai/references/components/upload.md +43 -0
  123. package/dist/ai/references/components.md +97 -0
  124. package/dist/ai/references/examples/data-table.md +50 -0
  125. package/dist/ai/references/release.md +159 -0
  126. package/dist/ai/ui-react.zip +0 -0
  127. package/dist/blocks/index.cjs +1 -1
  128. package/dist/blocks/index.js +1 -1
  129. package/dist/{chunk-NRCPYVJW.js → chunk-36XR4DWY.js} +1 -1
  130. package/dist/chunk-36XR4DWY.js.map +1 -0
  131. package/dist/chunk-3G4F4FBP.js +1 -0
  132. package/dist/chunk-3G4F4FBP.js.map +1 -0
  133. package/dist/chunk-6CAP3PTC.cjs +1 -0
  134. package/dist/chunk-6CAP3PTC.cjs.map +1 -0
  135. package/dist/chunk-EZEVLBUH.cjs +1 -0
  136. package/dist/chunk-EZEVLBUH.cjs.map +1 -0
  137. package/dist/chunk-G7UYIR6Z.js +1 -0
  138. package/dist/chunk-G7UYIR6Z.js.map +1 -0
  139. package/dist/chunk-JJA2B3JL.cjs +1 -0
  140. package/dist/chunk-JJA2B3JL.cjs.map +1 -0
  141. package/dist/chunk-LNVPMWCL.cjs +1 -0
  142. package/dist/chunk-LNVPMWCL.cjs.map +1 -0
  143. package/dist/chunk-NIQAVPSL.js +1 -0
  144. package/dist/chunk-NIQAVPSL.js.map +1 -0
  145. package/dist/chunk-PGJ5O3CM.cjs +1 -0
  146. package/dist/chunk-PGJ5O3CM.cjs.map +1 -0
  147. package/dist/chunk-RLPW73WX.js +1 -0
  148. package/dist/chunk-RLPW73WX.js.map +1 -0
  149. package/dist/chunk-RZSNVJZO.cjs +1 -0
  150. package/dist/chunk-RZSNVJZO.cjs.map +1 -0
  151. package/dist/chunk-Z4MRC4LZ.js +1 -0
  152. package/dist/chunk-Z4MRC4LZ.js.map +1 -0
  153. package/dist/components/alert.d.ts +4 -5
  154. package/dist/components/alert.d.ts.map +1 -1
  155. package/dist/components/avatar.d.ts +4 -5
  156. package/dist/components/avatar.d.ts.map +1 -1
  157. package/dist/components/badge.d.ts +5 -2
  158. package/dist/components/badge.d.ts.map +1 -1
  159. package/dist/components/button.d.ts +10 -5
  160. package/dist/components/button.d.ts.map +1 -1
  161. package/dist/components/checkbox.d.ts +4 -2
  162. package/dist/components/checkbox.d.ts.map +1 -1
  163. package/dist/components/date-picker.d.ts +1 -1
  164. package/dist/components/date-picker.d.ts.map +1 -1
  165. package/dist/components/date-time-picker.d.ts +2 -2
  166. package/dist/components/date-time-picker.d.ts.map +1 -1
  167. package/dist/components/dialog.d.ts.map +1 -1
  168. package/dist/components/drawer.d.ts.map +1 -1
  169. package/dist/components/index.cjs +1 -1
  170. package/dist/components/index.cjs.map +1 -1
  171. package/dist/components/index.js +1 -1
  172. package/dist/components/input.d.ts +2 -0
  173. package/dist/components/input.d.ts.map +1 -1
  174. package/dist/components/number-input.d.ts +4 -2
  175. package/dist/components/number-input.d.ts.map +1 -1
  176. package/dist/components/radio.d.ts +4 -6
  177. package/dist/components/radio.d.ts.map +1 -1
  178. package/dist/components/select.d.ts +4 -0
  179. package/dist/components/select.d.ts.map +1 -1
  180. package/dist/components/sidebar.d.ts +17 -8
  181. package/dist/components/sidebar.d.ts.map +1 -1
  182. package/dist/components/skeleton.d.ts +4 -5
  183. package/dist/components/skeleton.d.ts.map +1 -1
  184. package/dist/components/spinner.d.ts +5 -6
  185. package/dist/components/spinner.d.ts.map +1 -1
  186. package/dist/components/switch.d.ts +2 -0
  187. package/dist/components/switch.d.ts.map +1 -1
  188. package/dist/components/tag.d.ts +5 -2
  189. package/dist/components/tag.d.ts.map +1 -1
  190. package/dist/components/time-picker.d.ts +1 -1
  191. package/dist/components/time-picker.d.ts.map +1 -1
  192. package/dist/essentials.cjs +1 -0
  193. package/dist/essentials.cjs.map +1 -0
  194. package/dist/essentials.css +2 -0
  195. package/dist/essentials.d.ts +9 -0
  196. package/dist/essentials.d.ts.map +1 -0
  197. package/dist/essentials.js +1 -0
  198. package/dist/essentials.js.map +1 -0
  199. package/dist/index.cjs +1 -1
  200. package/dist/index.cjs.map +1 -1
  201. package/dist/index.js +1 -1
  202. package/dist/internal/data-table-header.d.ts.map +1 -1
  203. package/dist/internal/date-time/date-mode-panel.d.ts.map +1 -0
  204. package/dist/internal/{date-time-control.d.ts → date-time/date-time-control.d.ts} +1 -1
  205. package/dist/internal/date-time/date-time-control.d.ts.map +1 -0
  206. package/dist/internal/date-time/date-time-range-control.d.ts.map +1 -0
  207. package/dist/internal/date-time/time-panel.d.ts.map +1 -0
  208. package/dist/internal/{admin-horizontal-navigation.d.ts → navigation/admin-horizontal-navigation.d.ts} +1 -1
  209. package/dist/internal/navigation/admin-horizontal-navigation.d.ts.map +1 -0
  210. package/dist/internal/navigation/sidebar-navigation.d.ts.map +1 -0
  211. package/dist/internal/overlay/use-floating-layout-observer.d.ts.map +1 -0
  212. package/dist/internal/overlay/use-overlay-focus.d.ts.map +1 -0
  213. package/dist/internal/overlay/use-portal-container.d.ts.map +1 -0
  214. package/dist/internal/overlay/use-presence.d.ts.map +1 -0
  215. package/dist/internal/selection/option-window.d.ts.map +1 -0
  216. package/dist/internal/{use-cascader-lazy.d.ts → selection/use-cascader-lazy.d.ts} +1 -1
  217. package/dist/internal/selection/use-cascader-lazy.d.ts.map +1 -0
  218. package/dist/internal/{use-transfer-remote.d.ts → selection/use-transfer-remote.d.ts} +1 -1
  219. package/dist/internal/selection/use-transfer-remote.d.ts.map +1 -0
  220. package/dist/internal/{use-tree-data.d.ts → selection/use-tree-data.d.ts} +1 -1
  221. package/dist/internal/selection/use-tree-data.d.ts.map +1 -0
  222. package/dist/patterns/admin-shell.d.ts +4 -0
  223. package/dist/patterns/admin-shell.d.ts.map +1 -1
  224. package/dist/patterns/data-table.d.ts +18 -7
  225. package/dist/patterns/data-table.d.ts.map +1 -1
  226. package/dist/patterns/index.cjs +1 -1
  227. package/dist/patterns/index.cjs.map +1 -1
  228. package/dist/patterns/index.js +1 -1
  229. package/dist/patterns/index.js.map +1 -1
  230. package/dist/patterns/page-header.d.ts +4 -0
  231. package/dist/patterns/page-header.d.ts.map +1 -1
  232. package/dist/primitives/index.cjs +1 -1
  233. package/dist/primitives/index.js +1 -1
  234. package/dist/styles.css +1 -1
  235. package/dist/themes/dense.css +1 -0
  236. package/dist/tokens.css +1 -1
  237. package/package.json +18 -5
  238. package/dist/chunk-J4NAYP4L.cjs +0 -1
  239. package/dist/chunk-J4NAYP4L.cjs.map +0 -1
  240. package/dist/chunk-JY5S7YLF.cjs +0 -1
  241. package/dist/chunk-JY5S7YLF.cjs.map +0 -1
  242. package/dist/chunk-NRCPYVJW.js.map +0 -1
  243. package/dist/chunk-PXVCZ6AZ.js +0 -1
  244. package/dist/chunk-PXVCZ6AZ.js.map +0 -1
  245. package/dist/chunk-UBZ2ZCEJ.cjs +0 -1
  246. package/dist/chunk-UBZ2ZCEJ.cjs.map +0 -1
  247. package/dist/chunk-UEJM2SLH.js +0 -1
  248. package/dist/chunk-UEJM2SLH.js.map +0 -1
  249. package/dist/chunk-UESSLLSC.js +0 -1
  250. package/dist/chunk-UESSLLSC.js.map +0 -1
  251. package/dist/chunk-VDBATAZ3.js +0 -1
  252. package/dist/chunk-VDBATAZ3.js.map +0 -1
  253. package/dist/chunk-XVFRKGM7.cjs +0 -1
  254. package/dist/chunk-XVFRKGM7.cjs.map +0 -1
  255. package/dist/chunk-ZDO5A2IZ.cjs +0 -1
  256. package/dist/chunk-ZDO5A2IZ.cjs.map +0 -1
  257. package/dist/internal/admin-horizontal-navigation.d.ts.map +0 -1
  258. package/dist/internal/date-mode-panel.d.ts.map +0 -1
  259. package/dist/internal/date-time-control.d.ts.map +0 -1
  260. package/dist/internal/date-time-range-control.d.ts.map +0 -1
  261. package/dist/internal/option-window.d.ts.map +0 -1
  262. package/dist/internal/sidebar-navigation.d.ts.map +0 -1
  263. package/dist/internal/time-panel.d.ts.map +0 -1
  264. package/dist/internal/use-cascader-lazy.d.ts.map +0 -1
  265. package/dist/internal/use-floating-layout-observer.d.ts.map +0 -1
  266. package/dist/internal/use-overlay-focus.d.ts.map +0 -1
  267. package/dist/internal/use-portal-container.d.ts.map +0 -1
  268. package/dist/internal/use-presence.d.ts.map +0 -1
  269. package/dist/internal/use-transfer-remote.d.ts.map +0 -1
  270. package/dist/internal/use-tree-data.d.ts.map +0 -1
  271. /package/dist/internal/{date-mode-panel.d.ts → date-time/date-mode-panel.d.ts} +0 -0
  272. /package/dist/internal/{date-time-range-control.d.ts → date-time/date-time-range-control.d.ts} +0 -0
  273. /package/dist/internal/{time-panel.d.ts → date-time/time-panel.d.ts} +0 -0
  274. /package/dist/internal/{sidebar-navigation.d.ts → navigation/sidebar-navigation.d.ts} +0 -0
  275. /package/dist/internal/{use-floating-layout-observer.d.ts → overlay/use-floating-layout-observer.d.ts} +0 -0
  276. /package/dist/internal/{use-overlay-focus.d.ts → overlay/use-overlay-focus.d.ts} +0 -0
  277. /package/dist/internal/{use-portal-container.d.ts → overlay/use-portal-container.d.ts} +0 -0
  278. /package/dist/internal/{use-presence.d.ts → overlay/use-presence.d.ts} +0 -0
  279. /package/dist/internal/{option-window.d.ts → selection/option-window.d.ts} +0 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 UG666
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,8 @@
1
+ {
2
+ "schema": 1,
3
+ "package": "@ug666/ui-react",
4
+ "version": "0.3.0-beta.4",
5
+ "revision": "88faeb75f0507dc9f270c55b3ec8591b06307b18",
6
+ "tag": "next",
7
+ "dirty": false
8
+ }
@@ -0,0 +1,245 @@
1
+ ---
2
+ name: ui-react
3
+ description: >
4
+ Use @ug666/ui-react in React applications. Trigger for UG UI component imports,
5
+ styles, themes, hooks, forms, overlays, patterns, blocks, migration from
6
+ local UI code, or questions about the React adapter and its public entrypoints.
7
+ ---
8
+
9
+ # @ug666/ui-react 使用指南
10
+
11
+ > @ug666/ui-react@0.3.0-beta.4 · npm 包匹配文档。使用前核对项目实际消费的包。
12
+
13
+
14
+ ## 先确认当前发布
15
+
16
+ 在线指南、npm 版本文档与离线 ZIP 中的 `references/release.md` 由 `packages/ui-react/package.json`、
17
+ `configs/registry/entrypoints.ts` 和 `configs/registry/registry.ts` 自动生成,包含当前版本、真实公开入口和组件目录。
18
+
19
+ 回答具体 Props、事件、组件是否存在等问题时:
20
+
21
+ 1. 先读 `references/release.md`。
22
+ 2. 再使用当前包的 TypeScript 类型或 UG UI 文档站确认细节。
23
+ 3. 不根据旧业务代码、记忆或其他 UI 框架猜 API。
24
+
25
+ 仓库源码版尚未打包时,以 `configs/registry/registry.ts` 和 `packages/ui-react/package.json` 为事实源。
26
+
27
+ ## 组件发现协议
28
+
29
+ `references/components/index.md` 是由 Catalog 自动生成的 AI 组件目录,
30
+ `references/components/<slug>.md` 是单组件选择指南。生成或修改 UI 前必须:
31
+
32
+ 1. 先理解任务意图、行为和信息结构,不只按用户说出的字面组件名匹配。
33
+ 2. 从组件目录筛选多个可能的候选;选择存在歧义时,读取所有候选组件文档后再决定。
34
+ 3. 对照适用场景、不适用场景、相关候选、公开入口和使用规则。
35
+ 4. 再读取当前包 TypeScript 类型确认 Props、事件、ref 和默认值,不凭记忆发明 API。
36
+ 5. 优先组合现有 UG 组件;缺少能力时先确认是否是公共缺口,不用原生元素和临时样式复制已有组件。
37
+ 6. 完成后检查响应式、长文本、键盘、焦点、disabled、loading 和错误状态。
38
+
39
+ ## 安装
40
+
41
+ 已有项目先核对锁文件。新项目按 [发布参考](references/release.md) 确认对应版本,安装时显式指定版本。
42
+
43
+ 应用入口只需导入一次完整样式:
44
+
45
+ ```tsx
46
+ import '@ug666/ui-react/styles.css'
47
+ ```
48
+
49
+ 仅使用 `UGButton`、`UGInput`、`UGTextarea` 时,成对使用 `@ug666/ui-react/essentials` 与 `@ug666/ui-react/essentials.css` 缩小 JS/CSS 体积;出现其他组件的真实需求后必须同时切回主入口与 `styles.css`,不能把精简入口当作全量样式。
50
+
51
+ `react`、`react-dom` 是 peer dependencies,由业务项目维护。
52
+
53
+ ## 入口选择
54
+
55
+ ```tsx
56
+ import { UGButton, UGInput } from '@ug666/ui-react'
57
+ import { UGButton as PrimitiveButton } from '@ug666/ui-react/primitives'
58
+ import { UGPageHeader } from '@ug666/ui-react/patterns'
59
+ import { UGFeatureGrid } from '@ug666/ui-react/blocks'
60
+ import { useDebounce } from '@ug666/ui-react/hooks'
61
+ ```
62
+
63
+ 只使用三个基础控件时改用精简运行入口:
64
+
65
+ ```tsx
66
+ import { UGButton, UGInput, UGTextarea } from '@ug666/ui-react/essentials'
67
+ ```
68
+
69
+ - 高频稳定组件和 hooks 可以使用主入口。
70
+ - 只使用 Button、Input、Textarea 的应用使用 `essentials`;控件集合变化时切回主入口。
71
+ - `patterns`、`blocks` 使用对应子入口,不假定它们全部从主入口导出。
72
+ - 不从 `dist/`、`src/` 或未公开内部文件导入。
73
+ - 完整子入口以 `references/release.md` 为准。
74
+
75
+ 会话型产品优先组合 `/patterns`:
76
+
77
+ ```tsx
78
+ import {
79
+ UGAttachmentList,
80
+ UGConversationList,
81
+ UGMessage,
82
+ UGMessageList,
83
+ UGPromptComposer,
84
+ } from '@ug666/ui-react/patterns'
85
+ ```
86
+
87
+ 这些 Pattern 只维护输入、消息、附件和会话列表的公共 Anatomy。模型协议、Markdown、上传、任务状态和产品文案由业务项目提供。
88
+
89
+ 后台壳层使用 `UGAdminShell`。`UGSidebar` 的父项只展开子菜单,叶子项才使用 `href` 导航;活动叶子的图标保持普通图标色,折叠叶子复用全局 Tooltip,多级菜单显示可操作浮层。平台、租户、工作区或环境选择不是导航层级,使用默认关闭的 `sidebarContextSwitcher` + `sidebarContextSwitcherVisible`,不要伪装成第一个一级菜单;和搜索同时使用时通过 `sidebarContextSwitcherPlacement` 控制先后。活动菜单默认自动滚入侧栏可视区域,只在业务明确接管定位时关闭 `sidebarScrollActiveItemIntoView`。`sidebarCollapsible={false}` 可整体关闭桌面折叠入口而不移除组件能力;启用时,桌面折叠按钮可通过 `sidebarTogglePlacement="sidebar|topbar|bottom"` 放在品牌区、主顶栏或侧栏底部,并通过 `sidebarCollapsedHeader` 提供折叠后保留的紧凑品牌标识。`sidebarResizable` 默认关闭,开启后可拖动右边界或使用方向键调整整数像素宽度;`sidebarWidth / defaultSidebarWidth` 即使不启用拖拽也会控制展开宽度。品牌对齐/下分隔线、搜索显隐/文案/上下分隔线分别使用 `sidebarHeaderAlign`、`sidebarHeaderDivider`、`sidebarSearchable`、`sidebarSearchPlaceholder` 与 `sidebarSearchDividers`。`sidebarFooter` 不传即不显示,也可传入任意账户或业务操作内容;不要在业务 CSS 中重画侧栏、顶栏或修补内部结构。
90
+
91
+ 后台页面标签使用 `/patterns` 的 `UGAppTabs` 并放入 `UGAdminShell.secondaryBar`。组件只负责浏览器式外观、当前页、关闭入口和内部滚动;路由跳转、权限、持久化与关闭后的后继页面仍由应用在 `onValueChange / onClose` 中处理。圆角跟随主题 `radius`,不要在业务 CSS 中覆盖页签 Anatomy。
92
+
93
+ `UGAttachmentList` 的 `status` 统一表达 `ready / uploading / success / error`,并提供可见与可访问状态;业务只传递附件数据和上传结果,不要重写状态图标、颜色或动画。
94
+
95
+ ## 基础使用
96
+
97
+ ```tsx
98
+ import { useState } from 'react'
99
+ import { UGButton, UGSelect, UGSpace, type SelectValue } from '@ug666/ui-react'
100
+
101
+ const options = [
102
+ { label: '开发环境', value: 'dev' },
103
+ { label: '生产环境', value: 'prod' },
104
+ ]
105
+
106
+ export function EnvironmentField() {
107
+ const [value, setValue] = useState<SelectValue>()
108
+
109
+ return (
110
+ <UGSpace direction="vertical" align="stretch" size="lg">
111
+ <UGSelect
112
+ options={options}
113
+ value={value}
114
+ onValueChange={(nextValue) => {
115
+ if (!Array.isArray(nextValue)) setValue(nextValue)
116
+ }}
117
+ />
118
+ <UGButton variant="solid" tone="primary" loading={false}>
119
+ 保存
120
+ </UGButton>
121
+ </UGSpace>
122
+ )
123
+ }
124
+ ```
125
+
126
+ 关键规则:
127
+
128
+ - React Select 的业务值变更使用 `onValueChange`;原生隐藏字段事件才使用 `onChange`。
129
+ - `UGSelect` 和 `UGSwitch` 默认按下时过渡底色。传 `pressMotion="offset"` 可选用轻微下移,`pressMotion="none"` 关闭附加反馈;不影响焦点、下拉展开或滑块左右移动。
130
+ - `UGSelect filterable` 的触发位置就是可输入的搜索框,候选弹层不另设输入;受控空值可传 `value={undefined}`,点清空应得到无选择,不是回到前一项。横向标签搜索表单使用 `UGForm` 的 `layout="horizontal"` 与 `UGFormField / UGFormItem / UGFormLabel / UGFormControl`,同行控件共用 `size`。
131
+ - Button 的外观与语义色分别由 `variant`、`tone` 表达。
132
+ - Badge、Tag、Alert 等 soft 语义色使用组件 `variant` / `tone` 和共享 Token,不在业务侧覆盖前景色或背景透明度,以保留正文 AA 对比度。
133
+ - Spinner 的语义颜色使用 `tone`;Progress 的粗细和 EmptyState 的留白层级使用 `size`,不要用 `className` 重做这些基础外观。
134
+ - Card、Tabs、Table、Modal 已公开的尺寸、密度、边框和变体必须使用组件属性,不通过 `className` 重做基础外观。
135
+ - 只展示二维数据使用 `UGTable`;需要加载、失败、空状态、排序、勾选、操作列和分页的后台列表使用 `/patterns` 的 `UGDataTable`,请求与权限仍由业务层管理。
136
+ - 列宽、最小宽度、对齐和固定用 `columns.width/minWidth/align/fixed`,固定偏移按真实列宽。完整嵌套记录使用 `/patterns` 的 `UGTreeTable`,`getRowId/getChildren` 保留原记录身份;`expandedIds/onExpandedChange` 或 `defaultExpandedIds/defaultExpandAll` 管理展开,不隐含分页。它不提供虚拟化、懒加载或授权勾选级联。
137
+ - 层级数据选择使用 `UGTree`:业务将数据映射为 `key/label/children`,用 `value/onValueChange` 控制选择。展开与选择独立,`query` 搜索仅临时显示匹配路径;清空后恢复展开状态。部门等非文件层级可用 `renderNodeIcon={({ node, expanded, hasChildren }) => <Building2 size={16} />}` 替换默认装饰;只放静态图标,不放按钮等交互节点。空返回值保留 16px 装饰槽,`showNodeIcons={false}` 同时关闭默认与自定义图标,保留箭头、缩进和全部交互。侧栏尺寸与折叠组合 `UGSplitter`,不手写节点按钮。
138
+ - `UGDataTable fill` 用于高度受限的后台页面:父容器必须提供确定高度,组件填满父容器,表格区域内部滚动,分页留在底部。默认 `fill={false}` 保持内容高度;不要穿透内部结构定位分页。
139
+ - 可选的 `pageSizeOptions` + `onPageSizeChange` 在底部分页区显示受控每页条数选择器;回调中更新列表查询、将页码重置为 1,并按业务需要清空跨页勾选。未传选项时不显示,不要在工具栏再复制选择器。
140
+ - `UGDataTable` 操作列会按实际按钮或菜单内容自适应宽度并保持单行;业务侧直接提供 `rowActions`,不要覆盖表头或单元格内部样式。
141
+ - `UGDataTable` 默认单行列,窄屏只在有名称的表格区域内横滚;姓名、账号等独立字段分列显示。确需多行说明时为该列显式放开换行,并接受数据行高于表头,不在页面 CSS 中改公共表格密度。
142
+ - 独立表格需要标题、结果摘要和筛选工具栏时可用 `/patterns` 的 `UGDataTableToolbar`;整页后台列表将搜索、创建和刷新放在表格外,表格从列标题开始,总数由底部分页摘要呈现。头像或图标后的主副文本使用 `UGDataTableIdentity`。查询状态与业务字段仍由调用方负责。
143
+ - 互斥的标题/说明型选项使用 `UGRadioGroup` + `UGRadio variant="card"`,不要用多个 Button 和 `aria-pressed` 模拟单选卡片。
144
+ - `UGAccordion` 嵌入已有 `UGCard` 等带边界容器时使用 `variant="subtle"`,避免折叠区再画一层完整外边框。
145
+ - 受控和非受控用法以组件类型声明为准,不同时传入互相冲突的状态来源。
146
+ - 表单、弹窗、分页等能力优先组合 UG 组件,不在业务侧长期复制一套基础 UI。
147
+
148
+ ## 主题
149
+
150
+ ```tsx
151
+ import '@ug666/ui-react/styles.css'
152
+ import '@ug666/ui-react/themes/minimal.css'
153
+ import { UGThemeProvider } from '@ug666/ui-react/theme'
154
+
155
+ export function Root() {
156
+ return (
157
+ <UGThemeProvider preset="minimal" mode="system" surface="workspace">
158
+ <App />
159
+ </UGThemeProvider>
160
+ )
161
+ }
162
+ ```
163
+
164
+ - 主题运行时从 `@ug666/ui-react/theme` 导入。
165
+ - 主题 CSS 使用包公开的 `themes/*.css` 子入口。
166
+ - `data-ug`、`data-ug-slot`、`data-state` 等 anatomy 属性由组件库维护,业务代码不要手写。
167
+ - 局部样式优先使用语义 Token;不要复制组件内部结构选择器。
168
+
169
+ ## 组合与扩展
170
+
171
+ 优先级:
172
+
173
+ 1. 直接使用现有 UG 组件。
174
+ 2. 组合 `primitives` / `components`。
175
+ 3. 使用或补充 `patterns`。
176
+ 4. 只有真实复用场景才进入 `blocks`。
177
+ 5. 公共能力尚未稳定时先在业务项目验证;确认可复用且 API 清晰后再反馈给 `ug-ui`,不要依赖猜测性实验入口。
178
+
179
+ 业务封装可以加入领域数据适配,但不要修改 UG 组件的可访问性、焦点和键盘合同。
180
+
181
+ ## 表单和交互
182
+
183
+ - 日期范围输入使用 `UGDateRangePicker`,值为 `readonly [string, string]`,本地 `YYYY-MM-DD` 与空端点不转 UTC;手动非法或反向输入是草稿,在提交入口统一校验。`error={true}` 只标 invalid,错误文案才生成提示;隐藏查询区域时通过公开 `open=false` 关闭浮层并保留草稿。
184
+ 外部表单标签通过 `UGFormLabel htmlFor={inputId}` 与 `startInputId={inputId}`(或 `endInputId`)原生关联输入;`id/ref` 仍指向外层根,调用方使用 `useId` 等方式保证各 id 唯一,不猜内部派生后缀。
185
+
186
+ - 使用组件公开的值事件,不从 DOM 文本反推业务值。
187
+ - 表单校验通过当前 `useForm` / Form 控制器合同接入,具体方法读类型声明。
188
+ - 使用 `UGThemeProvider` / `UGThemeScope` 时,Modal、Select、Tooltip 等 Portal 会复制最近的主题作用域;未使用 Provider 的自定义主题应用则从 `document` 根节点继承语义 Token,不需要为浮层补写样式。
189
+ - Select、Dropdown、Popover、Tooltip、ContextMenu 已内置视口边界处理和进入、离场动效;Dropdown、Popover、Tooltip 会在动态内容尺寸变化后重新定位,并按实际方向执行动效,业务层不要再用定位偏移、固定高度或动画 CSS 修补其浮层。
190
+ - Tooltip 默认悬停延迟为 200ms;需要即时反馈时使用 `delayDuration={0}`,不要在业务组件中另画一套提示气泡。
191
+ - Drawer 正文使用 `UGDrawerBody`,由组件统一提供滚动、收缩和语义内边距;不要在 Header 与 Footer 之间重复手写 `flex-1 overflow-y-auto px-* py-*`。
192
+ - 有可见标题的 Modal 按官方 Demo 组合。将 `UGModalTitle` 与 `UGModalCloseButton` 放在同一个 `UGModalHeader`,再接 `UGModalBody` 和可选的 `UGModalFooter`。关闭按钮独立放在 Header 后会成为单独一行。无可见标题的搜索框等场景应保留可访问名称和关闭路径。
193
+ - Modal 正文使用 `UGModalBody`,滚动、收缩和内边距由组件负责。桌面 WebView 的遮罩只覆盖网页内容,原生窗口标题栏由应用宿主联动处理。
194
+ - 需要指定表单宽度或靠顶部显示时使用 `UGModal width={600} placement="top" topOffset="6vh"`;普通弹窗继续使用 `size` 与默认居中,不用业务 CSS 改内容宽度、分隔线或定位。
195
+ - `UGDialog` 打开后会优先聚焦取消按钮;不要在业务层强制把初始焦点移到危险确认操作。
196
+ - `toast.success/info` 使用非打断式状态播报,`toast.error` 使用即时警报;自动关闭在悬停或键盘焦点进入时暂停,确需常驻时传 `{ duration: null }`。
197
+ - `UGToaster compact` 可选将多条通知默认折叠成一行数量和摘要,用户展开读取完整消息及逐条关闭;全文仍按严重度播报。summary 支持 Enter/Space,展开时 Escape 先收起通知,不关闭后方编辑器。应用只用公开根 `className/style` 安排通知位置,给弹层标题、关闭按钮和首个输入留出空间;不要靠业务截断或内部 CSS 隐藏长错误。
198
+ - `UGSheet` 通过 `closeOnOverlay`、`closeOnEsc` 和 `showCloseButton` 控制关闭入口;禁用内置关闭入口时必须由业务提供等价的可访问关闭操作。
199
+ - 异步提交用 `loading`/禁用状态阻止重复操作,并保留错误反馈。
200
+ - 图标按钮必须提供可访问名称。
201
+ - Input/Textarea 内置的清空和 Input 密码切换已支持键盘聚焦,不要用 `tabIndex={-1}` 或业务样式移除这些操作。
202
+ - `UGInput` 和 `UGSelect` 聚焦时默认只改变现有边框颜色;需要更醒目时用 `focusRingWidth={1}`、`{2}` 或 `{3}` 添加外环,`{0}` 可显式关闭外环。
203
+ - Input 内置字数提示由组件保持右侧留白;Textarea 内置计数会避开原生拖拽角。表单需要跨列时包装组件根节点,不把网格类传给 `className`(它作用于内部原生控件)。
204
+ - Select 的可访问名称会传给真实触发器,键盘移动会保持高亮项可见;业务封装不要改写其焦点、滚动或隐藏原生字段合同。
205
+
206
+
207
+ ## Element 风格组件族选型
208
+
209
+ - 新增通用表单能力用 Autocomplete/Cascader/Transfer/ColorPicker/Upload 与日期时间族公开组件;具体 API 先查当前 references,不能凭 Element 的属性名称猜 UG API。UG 不要求安装 Element 运行时。
210
+ - 文本允许自由输入且需建议用 Autocomplete;固定集合用 Select;完整层级路径用 Cascader;单节点 key 用 TreeSelect;左右移动用 Transfer。不要把同一用户任务在页面里拼成另一种临时操作模型。
211
+ - Cascader 值是完整路径(多选为路径数组),name 提交 JSON 路径;Transfer name 提交 JSON key,保留字符串/数字身份与禁用/未知既有值。
212
+ - ColorPicker 的活动颜色是预览草稿,确认/清空才更新最终值;取消/Escape 不保存。
213
+ - Upload 通过业务 request 注入 File、AbortSignal、onProgress;未提供请求只选择文件。fileList 承载 File,原生 multipart 字段使用 FileInput;页面不补写内部任务状态、重试或拖放 CSS。
214
+ - 日期和时间保持本地字符串,手动非法值是可修正草稿,valueCommit 只报告合法/清空结果;API 时区与字段格式由应用适配。范围标签关联公开端点 id。
215
+ - useForm 的 blur/change trigger 控制即时校验,最终提交会执行全部规则。不能把点击保存和未失焦等同校验已完成。
216
+ - Notification 受控 items 使用稳定 id,close/action 按 id 消费;Popconfirm 使用可等待的 confirmAction,confirm 仅通知成功。Loading 保留布局并阻止旧内容操作,Image/Viewer 保留原生 alt 和模态键盘/焦点合同。
217
+ - InfiniteScroll 使用 onLoad/onRetry 可等待回调,loading/finished/error 显式表达状态,业务维护请求、数据和游标。
218
+
219
+ ## 样式边界
220
+
221
+ - `styles.css` 已包含组件样式和 Token,业务项目不需要扫描 UG UI 源码。
222
+ - `essentials.css` 只覆盖 `UGButton`、`UGInput`、`UGTextarea` 所需的基础样式;其他组件没有对应合同保证。组件集合变化时先切回 `styles.css`,再按包体预算评估是否扩展精简入口。
223
+ - `styles.css` 不注入全局 Preflight,但组件自有原生节点已完成隔离;业务项目无需为 UG 组件补写按钮、表单或段落 reset。
224
+ - `styles.css` 已为组件作用域提供字体基线;不要用业务全局字体或 Tailwind 配置补救组件默认字体。
225
+ - `tokens.css` 只用于明确需要原始 Token 的高级场景。
226
+ - 允许通过 `className`、`style` 和公开 CSS Token 调整页面布局、内容排版或局部业务语义。
227
+ - 布局优先利用实际容器宽度:能清楚同行的字段与操作不无故分行,减少整行占位、空白栏和顶部堆叠,给表格等主内容保留可视高度。空间不足按组自然换行,长说明和错误反馈按需独占行;不压小字号、命中区域或隐藏必要信息,组件尺寸与密度使用公开 API。
228
+ - 不覆盖组件内部私有类名,不手写 `data-ug-slot` anatomy。
229
+ - 先核对实际安装版本、公开属性和宿主 CSS。错误调用与业务布局在应用修;正确使用仍有的公共尺寸、状态、交互、主题或无障碍缺陷回 UG UI 源码修,不靠复制组件、内部选择器或包装器补丁交付。业务请求、权限和字段不进入 UI 包。
230
+ - 修复后通过匹配版本的包或获准联调接入,确认当前依赖实际包含修复;不手改 vendor、node_modules 或 dist,不把本地链接当成发布。按影响复用既有检查,用户自行验收界面时不代为启动浏览器或截图。
231
+
232
+ ## 版本升级
233
+
234
+ UG UI 在 `0.x` 阶段仍可能通过 minor 版本调整公开合同。升级时:
235
+
236
+ 1. 查看 `references/release.md` 的版本和入口。
237
+ 2. 查看 CHANGELOG。
238
+ 3. 运行类型检查和生产构建。
239
+ 4. 实测表单、Portal、亮暗模式和响应式页面。
240
+
241
+ 更多分层和使用策略见 `references/components.md`。
242
+
243
+ ## 可搜索分组选择
244
+
245
+ `UGSelectionList` 从 `@ug666/ui-react/patterns` 导入,`options` 的 `id/label/group?/description?/disabled?` 与 `value/onValueChange` 或 `defaultValue` 组合;支持 `searchable/searchPlaceholder/emptyLabel/disabled/size/name/form`。`id` 必须唯一稳定,`group` 是稳定分组标签。全选与半选只计算当前可见可操作项,批量操作保留筛选外、禁用既有和暂不在 options 的值;不可在应用层重新过滤这些值。未知既有项需解释时补 `disabled` 选项和 `description`,说明通过 aria-describedby 关联而不改变选项名称。业务权限目录、请求与授权判定留在应用。受控父级可拒绝/转换更新,原生表单 reset 不改写受控业务值。