weifuwu 0.85.0 → 0.87.0

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 (655) hide show
  1. package/README.md +56 -45
  2. package/content/apps/admin.md +55 -0
  3. package/content/apps/agent-platform.md +35 -0
  4. package/content/apps/auth.md +49 -0
  5. package/content/apps/multi.md +44 -0
  6. package/content/apps/todo.md +51 -0
  7. package/content/backend/ai.md +28 -0
  8. package/content/backend/auth.md +20 -0
  9. package/content/backend/email.md +23 -0
  10. package/content/backend/graphql.md +23 -0
  11. package/content/backend/http.md +23 -0
  12. package/content/backend/limit.md +23 -0
  13. package/content/backend/middleware.md +17 -0
  14. package/content/backend/queue.md +23 -0
  15. package/content/backend/redis.md +26 -0
  16. package/content/backend/router.md +23 -0
  17. package/content/backend/schedule.md +23 -0
  18. package/content/backend/sql.md +27 -0
  19. package/content/backend/sse.md +26 -0
  20. package/content/backend/ws.md +26 -0
  21. package/content/capabilities/app-node.md +21 -0
  22. package/content/capabilities/data.md +21 -0
  23. package/content/capabilities/events.md +21 -0
  24. package/content/capabilities/hooks.md +22 -0
  25. package/content/capabilities/i18n.md +21 -0
  26. package/content/capabilities/popup.md +21 -0
  27. package/content/capabilities/render-only.md +23 -0
  28. package/content/capabilities/router.md +22 -0
  29. package/content/capabilities/self-id.md +21 -0
  30. package/content/capabilities/store.md +21 -0
  31. package/content/capabilities/theme.md +21 -0
  32. package/content/capabilities/two-phase.md +21 -0
  33. package/content/components/accordion.md +50 -0
  34. package/content/components/actionsheet.md +46 -0
  35. package/content/components/affix.md +51 -0
  36. package/content/components/aichat.md +57 -0
  37. package/content/components/alert.md +52 -0
  38. package/content/components/alertgroup.md +45 -0
  39. package/content/components/anchor.md +52 -0
  40. package/content/components/app.md +37 -0
  41. package/content/components/approvalcard.md +56 -0
  42. package/content/components/appshell.md +50 -0
  43. package/content/components/aspectratio.md +47 -0
  44. package/content/components/authpage.md +61 -0
  45. package/content/components/autocomplete-v2.md +40 -0
  46. package/content/components/autocomplete.md +56 -0
  47. package/content/components/avatar.md +51 -0
  48. package/content/components/avatargroup.md +47 -0
  49. package/content/components/backtop.md +53 -0
  50. package/content/components/badge.md +55 -0
  51. package/content/components/breadcrumb.md +49 -0
  52. package/content/components/button.md +63 -0
  53. package/content/components/calendar-v2.md +40 -0
  54. package/content/components/calendar.md +50 -0
  55. package/content/components/card.md +58 -0
  56. package/content/components/carousel.md +52 -0
  57. package/content/components/cascader-v2.md +39 -0
  58. package/content/components/cascader.md +54 -0
  59. package/content/components/chart.md +53 -0
  60. package/content/components/chatinput.md +63 -0
  61. package/content/components/checkbox.md +51 -0
  62. package/content/components/checkboxgroup.md +52 -0
  63. package/content/components/citationcard.md +48 -0
  64. package/content/components/codeblock.md +48 -0
  65. package/content/components/codeeditor.md +47 -0
  66. package/content/components/collapse.md +49 -0
  67. package/content/components/colorpicker.md +50 -0
  68. package/content/components/command.md +50 -0
  69. package/content/components/confirm.md +57 -0
  70. package/content/components/contextmenu.md +48 -0
  71. package/content/components/copybutton.md +51 -0
  72. package/content/components/datepicker.md +52 -0
  73. package/content/components/descriptions-v2.md +39 -0
  74. package/content/components/descriptions.md +52 -0
  75. package/content/components/diffview-v2.md +39 -0
  76. package/content/components/diffview.md +50 -0
  77. package/content/components/divider.md +48 -0
  78. package/content/components/drawer.md +55 -0
  79. package/content/components/dropdown.md +53 -0
  80. package/content/components/editor.md +49 -0
  81. package/content/components/emptystate.md +51 -0
  82. package/content/components/exportcsv.md +38 -0
  83. package/content/components/field.md +54 -0
  84. package/content/components/filepreview-office.md +37 -0
  85. package/content/components/filepreview.md +49 -0
  86. package/content/components/filetree.md +56 -0
  87. package/content/components/fileupload-v2.md +39 -0
  88. package/content/components/fileupload.md +57 -0
  89. package/content/components/floatbutton.md +52 -0
  90. package/content/components/form-v2.md +41 -0
  91. package/content/components/form.md +60 -0
  92. package/content/components/grid.md +51 -0
  93. package/content/components/highlight-v2.md +39 -0
  94. package/content/components/highlight.md +46 -0
  95. package/content/components/hovercard.md +51 -0
  96. package/content/components/icon.md +50 -0
  97. package/content/components/imagecropper.md +45 -0
  98. package/content/components/img.md +56 -0
  99. package/content/components/infinitescroll-v2.md +40 -0
  100. package/content/components/infinitescroll.md +54 -0
  101. package/content/components/input.md +65 -0
  102. package/content/components/inputnumber.md +58 -0
  103. package/content/components/inview.md +56 -0
  104. package/content/components/jsonschemaform.md +53 -0
  105. package/content/components/jsonviewer-v2.md +39 -0
  106. package/content/components/jsonviewer.md +49 -0
  107. package/content/components/kanban.md +46 -0
  108. package/content/components/label.md +48 -0
  109. package/content/components/layout.md +54 -0
  110. package/content/components/layoutcontent.md +43 -0
  111. package/content/components/layoutheader.md +43 -0
  112. package/content/components/layoutsider.md +43 -0
  113. package/content/components/link.md +52 -0
  114. package/content/components/list.md +44 -0
  115. package/content/components/loading.md +45 -0
  116. package/content/components/logviewer-v2.md +39 -0
  117. package/content/components/logviewer.md +53 -0
  118. package/content/components/markdown.md +51 -0
  119. package/content/components/markdowneditor.md +47 -0
  120. package/content/components/math.md +42 -0
  121. package/content/components/mentions-v2.md +39 -0
  122. package/content/components/mentions.md +52 -0
  123. package/content/components/menu.md +56 -0
  124. package/content/components/menubar.md +44 -0
  125. package/content/components/messagebubble.md +50 -0
  126. package/content/components/modal.md +59 -0
  127. package/content/components/navmenu.md +47 -0
  128. package/content/components/notification.md +51 -0
  129. package/content/components/pageheader.md +53 -0
  130. package/content/components/pagination.md +49 -0
  131. package/content/components/paragraph.md +45 -0
  132. package/content/components/passwordinput.md +57 -0
  133. package/content/components/pininput-v2.md +39 -0
  134. package/content/components/pininput.md +50 -0
  135. package/content/components/pipeline.md +49 -0
  136. package/content/components/popconfirm.md +58 -0
  137. package/content/components/popover.md +61 -0
  138. package/content/components/progressbar.md +50 -0
  139. package/content/components/prompttemplate.md +49 -0
  140. package/content/components/qrcode.md +50 -0
  141. package/content/components/radiogroup.md +53 -0
  142. package/content/components/rate.md +53 -0
  143. package/content/components/reasoningblock.md +47 -0
  144. package/content/components/relationgraph.md +52 -0
  145. package/content/components/resizable.md +53 -0
  146. package/content/components/result.md +49 -0
  147. package/content/components/scrollbar.md +49 -0
  148. package/content/components/searchinput.md +51 -0
  149. package/content/components/segmentedcontrol.md +59 -0
  150. package/content/components/select-searchable.md +47 -0
  151. package/content/components/select.md +66 -0
  152. package/content/components/sessionlist.md +52 -0
  153. package/content/components/sheetgrid.md +44 -0
  154. package/content/components/skeleton.md +55 -0
  155. package/content/components/slidecanvas.md +44 -0
  156. package/content/components/slider.md +62 -0
  157. package/content/components/sortablelist.md +39 -0
  158. package/content/components/space.md +52 -0
  159. package/content/components/sparkline.md +52 -0
  160. package/content/components/statcard-countdown.md +39 -0
  161. package/content/components/statcard.md +56 -0
  162. package/content/components/steps.md +48 -0
  163. package/content/components/switch.md +50 -0
  164. package/content/components/tabbar.md +45 -0
  165. package/content/components/table-v2.md +40 -0
  166. package/content/components/table.md +66 -0
  167. package/content/components/tabs.md +56 -0
  168. package/content/components/tag.md +51 -0
  169. package/content/components/tagsinput-v2.md +39 -0
  170. package/content/components/tagsinput.md +54 -0
  171. package/content/components/text.md +45 -0
  172. package/content/components/textarea.md +57 -0
  173. package/content/components/themeswitch.md +69 -0
  174. package/content/components/timeline.md +50 -0
  175. package/content/components/title.md +45 -0
  176. package/content/components/toast.md +52 -0
  177. package/content/components/toggle-togglegroup.md +52 -0
  178. package/content/components/togglegroup.md +47 -0
  179. package/content/components/toolcallcard.md +51 -0
  180. package/content/components/tooltip.md +50 -0
  181. package/content/components/tour.md +50 -0
  182. package/content/components/transfer.md +52 -0
  183. package/content/components/tree-v2.md +39 -0
  184. package/content/components/tree.md +59 -0
  185. package/content/components/treeselect.md +54 -0
  186. package/content/components/typography.md +51 -0
  187. package/content/components/videoplayer.md +52 -0
  188. package/content/components/virtuallist.md +52 -0
  189. package/content/components/virtualtable-v2.md +39 -0
  190. package/content/components/virtualtable.md +55 -0
  191. package/content/components/watermark.md +53 -0
  192. package/content/components/wave.md +43 -0
  193. package/content/guides/ai-chat-family.md +24 -0
  194. package/content/guides/choose.md +67 -0
  195. package/content/guides/component-model.md +32 -0
  196. package/content/guides/component-standards.md +123 -0
  197. package/{docs/components.md → content/guides/components-guide.md} +153 -7
  198. package/{docs/custom-components.md → content/guides/custom-component.md} +70 -55
  199. package/{docs/data.md → content/guides/data-guide.md} +5 -2
  200. package/content/guides/file-preview-family.md +18 -0
  201. package/{docs → content/guides}/frontend.md +122 -52
  202. package/content/guides/layout-choice.md +64 -0
  203. package/{docs/layout.md → content/guides/layout-guide.md} +12 -8
  204. package/{docs/frontend-middleware.md → content/guides/middleware.md} +34 -3
  205. package/{docs/mobile.md → content/guides/mobile-guide.md} +20 -24
  206. package/content/guides/page-building.md +98 -0
  207. package/content/guides/production.md +37 -0
  208. package/content/guides/quality.md +60 -0
  209. package/{docs/realtime.md → content/guides/realtime-guide.md} +6 -3
  210. package/content/guides/render-only.md +44 -0
  211. package/{docs/saas.md → content/guides/saas-guide.md} +8 -5
  212. package/{docs/server.md → content/guides/server-guide.md} +5 -2
  213. package/content/guides/start.md +41 -0
  214. package/{docs → content/guides}/styling.md +5 -1
  215. package/{docs/frontend-ui-dom.md → content/guides/ui-dom-guide.md} +7 -1
  216. package/content/index.json +4344 -0
  217. package/content/index.md +181 -0
  218. package/content/layout/align.md +20 -0
  219. package/content/layout/anchor.md +19 -0
  220. package/content/layout/app-shell.md +23 -0
  221. package/content/layout/border.md +20 -0
  222. package/content/layout/center.md +19 -0
  223. package/content/layout/cluster.md +19 -0
  224. package/content/layout/container.md +19 -0
  225. package/content/layout/fill.md +19 -0
  226. package/content/layout/grid.md +19 -0
  227. package/content/layout/hidden.md +22 -0
  228. package/content/layout/layer.md +19 -0
  229. package/content/layout/position.md +22 -0
  230. package/content/layout/row.md +23 -0
  231. package/content/layout/safe-area.md +20 -0
  232. package/content/layout/scroll.md +21 -0
  233. package/content/layout/spacing.md +22 -0
  234. package/content/layout/split.md +19 -0
  235. package/content/layout/stack.md +19 -0
  236. package/content/layout/surface.md +23 -0
  237. package/content/layout/text.md +22 -0
  238. package/content/patterns/app-shell.md +34 -0
  239. package/content/patterns/dashboard.md +36 -0
  240. package/content/patterns/data-screen.md +30 -0
  241. package/content/patterns/detail-page.md +31 -0
  242. package/content/patterns/docs.md +34 -0
  243. package/content/patterns/focus-task.md +34 -0
  244. package/content/patterns/landing.md +35 -0
  245. package/content/patterns/list-page.md +32 -0
  246. package/content/patterns/mobile.md +31 -0
  247. package/content/patterns/settings-page.md +33 -0
  248. package/content/patterns/workspace.md +32 -0
  249. package/dist/cli/apps-typecheck.test.d.ts +11 -0
  250. package/dist/cli/docs.d.ts +2 -0
  251. package/dist/cli/docs.mjs +10961 -0
  252. package/dist/cli/home-flash.test.d.ts +1 -0
  253. package/dist/{components → client/components}/Accordion/Accordion.d.ts +1 -1
  254. package/dist/client/components/ActionSheet/ActionSheet.d.ts +37 -0
  255. package/dist/{components → client/components}/Affix/Affix.d.ts +1 -1
  256. package/dist/{components → client/components}/AiChat/AiChat.d.ts +3 -3
  257. package/dist/{components → client/components}/Alert/Alert.d.ts +1 -1
  258. package/dist/{components → client/components}/AlertGroup/AlertGroup.d.ts +1 -1
  259. package/dist/{components → client/components}/Anchor/Anchor.d.ts +1 -1
  260. package/dist/client/components/AppShell/AppShell.d.ts +55 -0
  261. package/dist/{components → client/components}/ApprovalCard/ApprovalCard.d.ts +2 -2
  262. package/dist/{components → client/components}/AspectRatio/AspectRatio.d.ts +1 -1
  263. package/dist/{components → client/components}/AuthPage/AuthPage.d.ts +2 -2
  264. package/dist/{components → client/components}/AutoComplete/AutoComplete.d.ts +1 -1
  265. package/dist/{components → client/components}/Avatar/Avatar.d.ts +1 -1
  266. package/dist/{components → client/components}/AvatarGroup/AvatarGroup.d.ts +1 -1
  267. package/dist/{components → client/components}/BackTop/BackTop.d.ts +1 -1
  268. package/dist/{components → client/components}/Badge/Badge.d.ts +1 -1
  269. package/dist/{components → client/components}/Breadcrumb/Breadcrumb.d.ts +1 -1
  270. package/dist/{components → client/components}/Button/Button.d.ts +1 -1
  271. package/dist/{components → client/components}/Calendar/Calendar.d.ts +1 -1
  272. package/dist/{components → client/components}/Card/Card.d.ts +1 -1
  273. package/dist/{components → client/components}/Carousel/Carousel.d.ts +1 -1
  274. package/dist/{components → client/components}/Cascader/Cascader.d.ts +1 -1
  275. package/dist/{components → client/components}/Chart/Chart.d.ts +1 -1
  276. package/dist/{components → client/components}/Chart/chart-utils.d.ts +5 -1
  277. package/dist/{components → client/components}/ChatInput/ChatInput.d.ts +7 -7
  278. package/dist/{components → client/components}/Checkbox/Checkbox.d.ts +1 -1
  279. package/dist/{components → client/components}/CheckboxGroup/CheckboxGroup.d.ts +1 -1
  280. package/dist/{components → client/components}/CitationCard/CitationCard.d.ts +3 -3
  281. package/dist/{components → client/components}/CodeBlock/CodeBlock.d.ts +1 -1
  282. package/dist/client/components/CodeEditor/CodeEditor.d.ts +18 -0
  283. package/dist/{components → client/components}/Collapse/Collapse.d.ts +1 -1
  284. package/dist/{components → client/components}/ColorPicker/ColorPicker.d.ts +1 -1
  285. package/dist/{components → client/components}/Command/Command.d.ts +1 -1
  286. package/dist/{components → client/components}/Confirm/Confirm.d.ts +2 -7
  287. package/dist/{components → client/components}/ContextMenu/ContextMenu.d.ts +1 -1
  288. package/dist/{components → client/components}/CopyButton/CopyButton.d.ts +1 -1
  289. package/dist/{components → client/components}/DatePicker/DatePicker.d.ts +2 -2
  290. package/dist/{components → client/components}/Descriptions/Descriptions.d.ts +1 -1
  291. package/dist/{components → client/components}/DiffView/DiffView.d.ts +1 -1
  292. package/dist/{components → client/components}/Divider/Divider.d.ts +1 -1
  293. package/dist/{components → client/components}/Drawer/Drawer.d.ts +1 -1
  294. package/dist/{components → client/components}/Dropdown/Dropdown.d.ts +1 -1
  295. package/dist/client/components/Editor/Editor.d.ts +14 -0
  296. package/dist/client/components/Editor/edit-events.d.ts +27 -0
  297. package/dist/client/components/Editor/model/apply.d.ts +23 -0
  298. package/dist/client/components/Editor/model/diff.d.ts +25 -0
  299. package/dist/client/components/Editor/model/dom.d.ts +27 -0
  300. package/dist/client/components/Editor/model/history.d.ts +21 -0
  301. package/dist/client/components/Editor/model/html.d.ts +16 -0
  302. package/dist/client/components/Editor/model/inverse.d.ts +20 -0
  303. package/dist/client/components/Editor/model/types.d.ts +116 -0
  304. package/dist/client/components/Editor/tools/table.d.ts +10 -0
  305. package/dist/{components → client/components}/Editor/tools/toolbar.d.ts +2 -2
  306. package/dist/client/components/Editor/tools/types.d.ts +40 -0
  307. package/dist/{components → client/components}/EmptyState/EmptyState.d.ts +1 -1
  308. package/dist/client/components/ExportCSV/ExportCSV.d.ts +30 -0
  309. package/dist/{components → client/components}/Field/Field.d.ts +1 -1
  310. package/dist/client/components/FilePreview/FilePreview.d.ts +42 -0
  311. package/dist/client/components/FilePreview/markdown.d.ts +23 -0
  312. package/dist/client/components/FileTree/FileTree.d.ts +57 -0
  313. package/dist/{components → client/components}/FileUpload/FileUpload.d.ts +1 -1
  314. package/dist/{components → client/components}/FloatButton/FloatButton.d.ts +1 -1
  315. package/dist/{components → client/components}/Form/Form.d.ts +1 -1
  316. package/dist/{components → client/components}/Grid/Grid.d.ts +1 -1
  317. package/dist/{components → client/components}/Highlight/Highlight.d.ts +1 -1
  318. package/dist/{components → client/components}/HoverCard/HoverCard.d.ts +5 -4
  319. package/dist/{components → client/components}/Icon/Icon.d.ts +2 -2
  320. package/dist/client/components/ImageCropper/ImageCropper.d.ts +17 -0
  321. package/dist/{components → client/components}/Img/Img.d.ts +1 -1
  322. package/dist/{components → client/components}/InView/InView.d.ts +1 -1
  323. package/dist/{components → client/components}/InfiniteScroll/InfiniteScroll.d.ts +1 -1
  324. package/dist/{components → client/components}/Input/Input.d.ts +1 -1
  325. package/dist/{components → client/components}/InputNumber/InputNumber.d.ts +1 -1
  326. package/dist/{components → client/components}/JSONViewer/JSONViewer.d.ts +1 -1
  327. package/dist/{components → client/components}/JsonSchemaForm/JsonSchemaForm.d.ts +3 -3
  328. package/dist/{components → client/components}/Kanban/Kanban.d.ts +1 -1
  329. package/dist/{components → client/components}/Label/Label.d.ts +1 -1
  330. package/dist/{components → client/components}/Layout/Layout.d.ts +1 -1
  331. package/dist/{components → client/components}/Link/Link.d.ts +1 -1
  332. package/dist/{components → client/components}/List/List.d.ts +1 -1
  333. package/dist/{components → client/components}/Loading/Loading.d.ts +1 -1
  334. package/dist/{components → client/components}/LogViewer/LogViewer.d.ts +1 -1
  335. package/dist/{components → client/components}/Markdown/Markdown.d.ts +1 -1
  336. package/dist/client/components/MarkdownEditor/MarkdownEditor.d.ts +18 -0
  337. package/dist/client/components/Math/Math.d.ts +15 -0
  338. package/dist/{components → client/components}/Mentions/Mentions.d.ts +1 -1
  339. package/dist/{components → client/components}/Menu/Menu.d.ts +1 -1
  340. package/dist/{components → client/components}/Menubar/Menubar.d.ts +1 -1
  341. package/dist/{components → client/components}/MessageBubble/MessageBubble.d.ts +1 -1
  342. package/dist/{components → client/components}/Modal/Modal.d.ts +1 -1
  343. package/dist/{components → client/components}/NavMenu/NavMenu.d.ts +2 -2
  344. package/dist/{components → client/components}/Notification/Notification.d.ts +7 -2
  345. package/dist/client/components/OfficeEditor/ai/ai-bridge.d.ts +39 -0
  346. package/dist/client/components/OfficeEditor/model/apply.d.ts +25 -0
  347. package/dist/client/components/OfficeEditor/model/types.d.ts +224 -0
  348. package/dist/{components → client/components}/PageHeader/PageHeader.d.ts +1 -1
  349. package/dist/{components → client/components}/Pagination/Pagination.d.ts +1 -1
  350. package/dist/{components → client/components}/PasswordInput/PasswordInput.d.ts +1 -1
  351. package/dist/{components → client/components}/PinInput/PinInput.d.ts +1 -1
  352. package/dist/{components → client/components}/Pipeline/Pipeline.d.ts +1 -1
  353. package/dist/{components → client/components}/Popconfirm/Popconfirm.d.ts +2 -2
  354. package/dist/{components → client/components}/Popover/Popover.d.ts +5 -4
  355. package/dist/{components → client/components}/ProgressBar/ProgressBar.d.ts +1 -1
  356. package/dist/client/components/PromptTemplate/PromptTemplate.d.ts +37 -0
  357. package/dist/{components → client/components}/QRCode/QRCode.d.ts +1 -1
  358. package/dist/{components → client/components}/RadioGroup/RadioGroup.d.ts +1 -1
  359. package/dist/{components → client/components}/Rate/Rate.d.ts +1 -1
  360. package/dist/{components → client/components}/ReasoningBlock/ReasoningBlock.d.ts +3 -3
  361. package/dist/client/components/RelationGraph/RelationGraph.d.ts +59 -0
  362. package/dist/{components → client/components}/Resizable/Resizable.d.ts +1 -1
  363. package/dist/{components → client/components}/Result/Result.d.ts +1 -1
  364. package/dist/{components → client/components}/Scrollbar/Scrollbar.d.ts +1 -1
  365. package/dist/{components → client/components}/SearchInput/SearchInput.d.ts +1 -1
  366. package/dist/{components → client/components}/SegmentedControl/SegmentedControl.d.ts +1 -1
  367. package/dist/{components → client/components}/Select/Select.d.ts +1 -1
  368. package/dist/{components → client/components}/SessionList/SessionList.d.ts +3 -3
  369. package/dist/client/components/SheetGrid/SheetGrid.d.ts +30 -0
  370. package/dist/{components → client/components}/Skeleton/Skeleton.d.ts +1 -1
  371. package/dist/client/components/SlideCanvas/SlideCanvas.d.ts +28 -0
  372. package/dist/client/components/Slider/Slider.d.ts +27 -0
  373. package/dist/client/components/SortableList/SortableList.d.ts +23 -0
  374. package/dist/{components → client/components}/Space/Space.d.ts +1 -1
  375. package/dist/{components → client/components}/Sparkline/Sparkline.d.ts +1 -1
  376. package/dist/{components → client/components}/StatCard/StatCard.d.ts +1 -1
  377. package/dist/{components → client/components}/Steps/Steps.d.ts +1 -1
  378. package/dist/{components → client/components}/Switch/Switch.d.ts +1 -1
  379. package/dist/client/components/TabBar/TabBar.d.ts +35 -0
  380. package/dist/{components → client/components}/Table/Table.d.ts +7 -1
  381. package/dist/client/components/Tabs/Tabs.d.ts +22 -0
  382. package/dist/{components → client/components}/Tag/Tag.d.ts +1 -1
  383. package/dist/{components → client/components}/TagsInput/TagsInput.d.ts +1 -1
  384. package/dist/{components → client/components}/Textarea/Textarea.d.ts +1 -1
  385. package/dist/{components → client/components}/ThemeSwitch/ThemeSwitch.d.ts +1 -1
  386. package/dist/{components → client/components}/Timeline/Timeline.d.ts +1 -1
  387. package/dist/{components → client/components}/Toast/Toast.d.ts +1 -1
  388. package/dist/{components → client/components}/ToggleGroup/ToggleGroup.d.ts +1 -1
  389. package/dist/{components → client/components}/ToolCallCard/ToolCallCard.d.ts +2 -2
  390. package/dist/{components → client/components}/Tooltip/Tooltip.d.ts +4 -3
  391. package/dist/{components → client/components}/Tour/Tour.d.ts +1 -1
  392. package/dist/{components → client/components}/Transfer/Transfer.d.ts +1 -1
  393. package/dist/{components → client/components}/Tree/Tree.d.ts +5 -1
  394. package/dist/{components → client/components}/TreeSelect/TreeSelect.d.ts +5 -1
  395. package/dist/{components → client/components}/Typography/Typography.d.ts +1 -1
  396. package/dist/client/components/VideoPlayer/VideoPlayer.d.ts +25 -0
  397. package/dist/{components → client/components}/VirtualList/VirtualList.d.ts +1 -1
  398. package/dist/{components → client/components}/VirtualTable/VirtualTable.d.ts +1 -1
  399. package/dist/{components → client/components}/Watermark/Watermark.d.ts +1 -1
  400. package/dist/client/components/Wave/Wave.d.ts +15 -0
  401. package/dist/{components → client/components}/index.d.ts +48 -2
  402. package/dist/client/components/index.js +57 -0
  403. package/dist/{components → client/components}/style.css +3554 -1896
  404. package/dist/{layout → client/layout}/weifuwu-layout.css +60 -6
  405. package/dist/client/office/docx.d.ts +33 -0
  406. package/dist/client/office/pptx.d.ts +24 -0
  407. package/dist/client/office/xlsx.d.ts +25 -0
  408. package/dist/client/office/xml-serialize.d.ts +18 -0
  409. package/dist/client/office/xml.d.ts +21 -0
  410. package/dist/client/office/zip.d.ts +21 -0
  411. package/dist/client/vdom/browser/Browser.d.ts +73 -0
  412. package/dist/client/vdom/browser/create-client-browser.d.ts +11 -0
  413. package/dist/client/vdom/commands.d.ts +19 -0
  414. package/dist/client/vdom/context/UIContext.d.ts +61 -0
  415. package/dist/client/vdom/context/data.d.ts +17 -0
  416. package/dist/client/vdom/core/async-guard.d.ts +20 -0
  417. package/dist/client/vdom/core/build.d.ts +36 -0
  418. package/dist/client/vdom/core/command/create.d.ts +25 -0
  419. package/dist/client/vdom/core/command/index.d.ts +15 -0
  420. package/dist/client/vdom/core/command/insert.d.ts +32 -0
  421. package/dist/client/vdom/core/command/lifecycle.d.ts +47 -0
  422. package/dist/client/vdom/core/command/props.d.ts +22 -0
  423. package/dist/client/vdom/core/diff/attrs.d.ts +10 -0
  424. package/dist/client/vdom/core/diff/children.d.ts +29 -0
  425. package/dist/client/vdom/core/diff/cleanup.d.ts +44 -0
  426. package/dist/client/vdom/core/diff/index.d.ts +22 -0
  427. package/dist/client/vdom/core/diff/output.d.ts +30 -0
  428. package/dist/client/vdom/core/diff/same.d.ts +22 -0
  429. package/dist/client/vdom/core/field/attributes.d.ts +15 -0
  430. package/dist/client/vdom/core/field/events.d.ts +54 -0
  431. package/dist/client/vdom/core/field/index.d.ts +19 -0
  432. package/dist/client/vdom/core/field/key.d.ts +16 -0
  433. package/dist/client/vdom/core/field/props.d.ts +15 -0
  434. package/dist/client/vdom/core/field/ref.d.ts +38 -0
  435. package/dist/client/vdom/core/field/style.d.ts +17 -0
  436. package/dist/client/vdom/core/node/children.d.ts +20 -0
  437. package/dist/client/vdom/core/node/component.d.ts +93 -0
  438. package/dist/client/vdom/core/node/fragment.d.ts +14 -0
  439. package/dist/client/vdom/core/node/hole.d.ts +22 -0
  440. package/dist/client/vdom/core/node/index.d.ts +35 -0
  441. package/dist/client/vdom/core/node/keyed.d.ts +64 -0
  442. package/dist/client/vdom/core/node/native.d.ts +20 -0
  443. package/dist/client/vdom/core/node/portal.d.ts +11 -0
  444. package/dist/client/vdom/core/patch/fields.d.ts +15 -0
  445. package/dist/client/vdom/core/patch/index.d.ts +51 -0
  446. package/dist/client/vdom/core/patch/processors.d.ts +75 -0
  447. package/dist/client/vdom/core/patch/state-machine.d.ts +38 -0
  448. package/dist/client/vdom/core/patch/verify.d.ts +17 -0
  449. package/dist/client/vdom/core/router.d.ts +31 -0
  450. package/dist/client/vdom/core/serve.d.ts +75 -0
  451. package/dist/client/vdom/core/ssr/absorb.d.ts +53 -0
  452. package/dist/client/vdom/core/ssr/html.d.ts +32 -0
  453. package/dist/client/vdom/core/ssr/index.d.ts +25 -0
  454. package/dist/client/vdom/core/transform/component.d.ts +23 -0
  455. package/dist/client/vdom/core/transform/element.d.ts +21 -0
  456. package/dist/client/vdom/core/transform/fragment.d.ts +21 -0
  457. package/dist/client/vdom/core/transform/hole.d.ts +13 -0
  458. package/dist/client/vdom/core/transform/index.d.ts +46 -0
  459. package/dist/client/vdom/core/transform/states.d.ts +22 -0
  460. package/dist/client/vdom/core/transform/table.d.ts +28 -0
  461. package/dist/client/vdom/core/transform/text.d.ts +10 -0
  462. package/dist/client/vdom/core/vnode.d.ts +45 -0
  463. package/dist/client/vdom/dev/effect-guard.d.ts +8 -0
  464. package/dist/client/vdom/hooks/ai-stream.d.ts +46 -0
  465. package/dist/client/vdom/hooks/basic.d.ts +42 -0
  466. package/dist/client/vdom/hooks/chat.d.ts +91 -0
  467. package/dist/client/vdom/hooks/controlled.d.ts +27 -0
  468. package/dist/client/vdom/hooks/drag-media.d.ts +52 -0
  469. package/dist/client/vdom/hooks/env.d.ts +119 -0
  470. package/dist/client/vdom/hooks/input.d.ts +43 -0
  471. package/dist/client/vdom/hooks/observe.d.ts +60 -0
  472. package/dist/client/vdom/hooks/popup-manager.d.ts +92 -0
  473. package/dist/client/vdom/hooks/popup.d.ts +52 -0
  474. package/dist/client/vdom/hooks/stable.d.ts +45 -0
  475. package/dist/client/vdom/index.d.ts +67 -0
  476. package/dist/client/vdom/index.js +8 -0
  477. package/dist/client/vdom/jsx-runtime.d.ts +28 -0
  478. package/dist/client/vdom/jsx-runtime.js +1 -0
  479. package/dist/client/vdom/middlewares/api.d.ts +38 -0
  480. package/dist/client/vdom/middlewares/auth-i18n.d.ts +66 -0
  481. package/dist/client/vdom/middlewares/ws.d.ts +37 -0
  482. package/dist/client/vdom/store.d.ts +49 -0
  483. package/dist/client/vdom/testing.d.ts +46 -0
  484. package/dist/client/vdom/testing.js +2 -0
  485. package/dist/dev/index.d.ts +12 -0
  486. package/dist/dev/index.js +4 -4
  487. package/dist/{ai → server/ai}/contracts.d.ts +1 -1
  488. package/dist/{ai → server/ai}/index.d.ts +2 -2
  489. package/dist/{ai → server/ai}/types.d.ts +1 -1
  490. package/dist/{core → server/core}/router.d.ts +2 -4
  491. package/dist/{db → server/db}/contracts.d.ts +1 -1
  492. package/dist/server/db/postgres-server.d.ts +37 -0
  493. package/dist/server/db/redis-server.d.ts +32 -0
  494. package/dist/server/db/server.d.ts +30 -0
  495. package/dist/server/db/test-servers.d.ts +21 -0
  496. package/dist/{email → server/email}/contracts.d.ts +1 -1
  497. package/dist/{index.js → server/index.js} +3147 -2462
  498. package/dist/{ui → server/ui}/index.d.ts +2 -2
  499. package/dist/{user → server/user}/token.d.ts +1 -1
  500. package/dist/shared/router/trie.d.ts +61 -0
  501. package/docs/components-map.md +16 -4
  502. package/docs/style-guide.md +14 -2
  503. package/examples/apps/admin/README.md +23 -0
  504. package/examples/apps/admin/api.ts +27 -0
  505. package/examples/apps/admin/app.tsx +144 -0
  506. package/examples/apps/admin/main.tsx +8 -0
  507. package/examples/apps/admin/server.ts +37 -0
  508. package/examples/apps/auth/README.md +23 -0
  509. package/examples/apps/auth/api.ts +49 -0
  510. package/examples/apps/auth/app.tsx +137 -0
  511. package/examples/apps/auth/main.tsx +8 -0
  512. package/examples/apps/auth/server.ts +37 -0
  513. package/examples/apps/multi/README.md +23 -0
  514. package/examples/apps/multi/app.tsx +83 -0
  515. package/examples/apps/multi/main.tsx +8 -0
  516. package/examples/apps/multi/server.ts +33 -0
  517. package/examples/apps/todo/README.md +23 -0
  518. package/examples/apps/todo/api.ts +26 -0
  519. package/examples/apps/todo/app.tsx +128 -0
  520. package/examples/apps/todo/main.tsx +9 -0
  521. package/examples/apps/todo/server.ts +39 -0
  522. package/examples/hello-world/README.md +9 -0
  523. package/examples/hello-world/client.ts +14 -0
  524. package/examples/hello-world/routes.tsx +26 -0
  525. package/examples/hello-world/server.ts +46 -0
  526. package/examples/patterns/AppShell.tsx +224 -0
  527. package/examples/patterns/Dashboard.tsx +153 -0
  528. package/examples/patterns/DataScreen.tsx +104 -0
  529. package/examples/patterns/DetailPage.tsx +79 -0
  530. package/examples/patterns/Docs.tsx +105 -0
  531. package/examples/patterns/FocusTask.tsx +67 -0
  532. package/examples/patterns/Landing.tsx +90 -0
  533. package/examples/patterns/ListPage.tsx +77 -0
  534. package/examples/patterns/Mobile.tsx +154 -0
  535. package/examples/patterns/SettingsPage.tsx +98 -0
  536. package/examples/patterns/SplitWorkspace.tsx +113 -0
  537. package/package.json +61 -29
  538. package/dist/components/Editor/Editor.d.ts +0 -13
  539. package/dist/components/Editor/tools/format.d.ts +0 -11
  540. package/dist/components/Editor/tools/table.d.ts +0 -7
  541. package/dist/components/Editor/tools/types.d.ts +0 -15
  542. package/dist/components/Slider/Slider.d.ts +0 -19
  543. package/dist/components/Tabs/Tabs.d.ts +0 -12
  544. package/dist/components/index.js +0 -15
  545. package/dist/ui-dom/Confirm.d.ts +0 -8
  546. package/dist/ui-dom/Notification.d.ts +0 -8
  547. package/dist/ui-dom/Toast.d.ts +0 -8
  548. package/dist/ui-dom/ai.d.ts +0 -59
  549. package/dist/ui-dom/browser.d.ts +0 -10
  550. package/dist/ui-dom/debug.d.ts +0 -21
  551. package/dist/ui-dom/hooks/chat.d.ts +0 -11
  552. package/dist/ui-dom/hooks/events.d.ts +0 -30
  553. package/dist/ui-dom/hooks/external.d.ts +0 -20
  554. package/dist/ui-dom/hooks/index.d.ts +0 -29
  555. package/dist/ui-dom/hooks/input.d.ts +0 -33
  556. package/dist/ui-dom/hooks/media.d.ts +0 -17
  557. package/dist/ui-dom/hooks/popup.d.ts +0 -30
  558. package/dist/ui-dom/hooks/stable.d.ts +0 -35
  559. package/dist/ui-dom/hooks/types.d.ts +0 -77
  560. package/dist/ui-dom/i18n.d.ts +0 -31
  561. package/dist/ui-dom/index.d.ts +0 -47
  562. package/dist/ui-dom/index.js +0 -41
  563. package/dist/ui-dom/jsx-runtime.d.ts +0 -4
  564. package/dist/ui-dom/jsx-runtime.js +0 -1
  565. package/dist/ui-dom/locale/en_US.d.ts +0 -55
  566. package/dist/ui-dom/locale/zh_CN.d.ts +0 -55
  567. package/dist/ui-dom/middleware/api.d.ts +0 -91
  568. package/dist/ui-dom/middleware/auth.d.ts +0 -30
  569. package/dist/ui-dom/middleware/ws.d.ts +0 -33
  570. package/dist/ui-dom/motion.d.ts +0 -8
  571. package/dist/ui-dom/popup-tracker.d.ts +0 -36
  572. package/dist/ui-dom/popup.d.ts +0 -42
  573. package/dist/ui-dom/store.d.ts +0 -24
  574. package/dist/ui-dom/testing.d.ts +0 -68
  575. package/dist/ui-dom/testing.js +0 -7
  576. package/dist/ui-dom/types.d.ts +0 -632
  577. package/dist/ui-dom/use-chat.d.ts +0 -95
  578. package/dist/ui-dom/vdom3/README.d.ts +0 -32
  579. package/dist/ui-dom/vdom3/app.d.ts +0 -20
  580. package/dist/ui-dom/vdom3/audit.d.ts +0 -29
  581. package/dist/ui-dom/vdom3/build.d.ts +0 -20
  582. package/dist/ui-dom/vdom3/commands.d.ts +0 -21
  583. package/dist/ui-dom/vdom3/comp-index.d.ts +0 -18
  584. package/dist/ui-dom/vdom3/delegate.d.ts +0 -48
  585. package/dist/ui-dom/vdom3/events.d.ts +0 -17
  586. package/dist/ui-dom/vdom3/index.d.ts +0 -42
  587. package/dist/ui-dom/vdom3/jsx.d.ts +0 -32
  588. package/dist/ui-dom/vdom3/record.d.ts +0 -16
  589. package/dist/ui-dom/vdom3/registry.d.ts +0 -30
  590. package/dist/ui-dom/vdom3/render.d.ts +0 -39
  591. package/dist/ui-dom/vdom3/replay.d.ts +0 -28
  592. package/dist/ui-dom/vdom3/root.d.ts +0 -24
  593. package/dist/ui-dom/vdom3/router.d.ts +0 -31
  594. package/dist/ui-dom/vdom3/scheduler.d.ts +0 -23
  595. package/dist/ui-dom/vdom3/ssr.d.ts +0 -27
  596. package/dist/ui-dom/vdom3/sync.d.ts +0 -22
  597. package/dist/ui-dom/vdom3/types.d.ts +0 -173
  598. package/dist/ui-dom/vdom3/ui.d.ts +0 -16
  599. package/dist/ui-dom/vdom3.js +0 -41
  600. package/dist/ui-dom/vnode.d.ts +0 -13
  601. /package/dist/{make-executable-schema.test.d.ts → cli/content-sync.test.d.ts} +0 -0
  602. /package/dist/{ui-dom/testing.test.d.ts → cli/docs-cli.test.d.ts} +0 -0
  603. /package/dist/{components → client/components}/CodeBlock/highlight.d.ts +0 -0
  604. /package/dist/{components → client/components}/DatePicker/calendar-utils.d.ts +0 -0
  605. /package/dist/{components → client/components}/DiffView/diff-utils.d.ts +0 -0
  606. /package/dist/{components → client/components}/Markdown/parser.d.ts +0 -0
  607. /package/dist/{components → client/components}/Pipeline/dag-utils.d.ts +0 -0
  608. /package/dist/{components → client/components}/QRCode/qr.d.ts +0 -0
  609. /package/dist/{components → client/components}/Sparkline/sparkline-utils.d.ts +0 -0
  610. /package/dist/{ai → server/ai}/agent.d.ts +0 -0
  611. /package/dist/{ai → server/ai}/client.d.ts +0 -0
  612. /package/dist/{ai → server/ai}/sse.d.ts +0 -0
  613. /package/dist/{core → server/core}/serve.d.ts +0 -0
  614. /package/dist/{core → server/core}/ws.d.ts +0 -0
  615. /package/dist/{db → server/db}/errors.d.ts +0 -0
  616. /package/dist/{db → server/db}/memory-redis.d.ts +0 -0
  617. /package/dist/{db → server/db}/memory-sql.d.ts +0 -0
  618. /package/dist/{db → server/db}/postgres/connection.d.ts +0 -0
  619. /package/dist/{db → server/db}/postgres/pool.d.ts +0 -0
  620. /package/dist/{db → server/db}/postgres/protocol.d.ts +0 -0
  621. /package/dist/{db → server/db}/postgres/schema.d.ts +0 -0
  622. /package/dist/{db → server/db}/query-builder.d.ts +0 -0
  623. /package/dist/{db → server/db}/query.d.ts +0 -0
  624. /package/dist/{db → server/db}/redis/client.d.ts +0 -0
  625. /package/dist/{db → server/db}/redis/commands.d.ts +0 -0
  626. /package/dist/{db → server/db}/redis/connection.d.ts +0 -0
  627. /package/dist/{db → server/db}/redis/pipeline.d.ts +0 -0
  628. /package/dist/{db → server/db}/redis/pool.d.ts +0 -0
  629. /package/dist/{db → server/db}/redis/resp.d.ts +0 -0
  630. /package/dist/{db → server/db}/redis/subscriber.d.ts +0 -0
  631. /package/dist/{db → server/db}/sql-parser.d.ts +0 -0
  632. /package/dist/{email → server/email}/index.d.ts +0 -0
  633. /package/dist/{email → server/email}/smtp.d.ts +0 -0
  634. /package/dist/{graphql.d.ts → server/graphql.d.ts} +0 -0
  635. /package/dist/{index.d.ts → server/index.d.ts} +0 -0
  636. /package/dist/{make-executable-schema.d.ts → server/make-executable-schema.d.ts} +0 -0
  637. /package/dist/{messager → server/messager}/index.d.ts +0 -0
  638. /package/dist/{middleware → server/middleware}/cors.d.ts +0 -0
  639. /package/dist/{middleware → server/middleware}/rate-limit.d.ts +0 -0
  640. /package/dist/{middleware → server/middleware}/static.d.ts +0 -0
  641. /package/dist/{postgres → server/postgres}/client.d.ts +0 -0
  642. /package/dist/{postgres → server/postgres}/index.d.ts +0 -0
  643. /package/dist/{postgres → server/postgres}/types.d.ts +0 -0
  644. /package/dist/{queue → server/queue}/index.d.ts +0 -0
  645. /package/dist/{redis → server/redis}/client.d.ts +0 -0
  646. /package/dist/{redis → server/redis}/index.d.ts +0 -0
  647. /package/dist/{redis → server/redis}/types.d.ts +0 -0
  648. /package/dist/{request.d.ts → server/request.d.ts} +0 -0
  649. /package/dist/{response.d.ts → server/response.d.ts} +0 -0
  650. /package/dist/{scheduler → server/scheduler}/cron.d.ts +0 -0
  651. /package/dist/{scheduler → server/scheduler}/index.d.ts +0 -0
  652. /package/dist/{types.d.ts → server/types.d.ts} +0 -0
  653. /package/dist/{ui → server/ui}/html-safe.d.ts +0 -0
  654. /package/dist/{user → server/user}/index.d.ts +0 -0
  655. /package/dist/{user → server/user}/password.d.ts +0 -0
@@ -0,0 +1,123 @@
1
+ # 组件编写标准(强制)
2
+
3
+ > 本文是 weifuwu 组件的**强制标准**——不是建议。每条标准标注强制执行机制:
4
+ > **L1 类型强制**(编译期失败)/ **L2 运行时检测**(dev error/warn——写错即报)/
5
+ > **L3 契约测试**(引擎行为——vdom-x.test.ts 验收)/ **文档红线**(引擎无法检测——靠审查)。
6
+ > 配套:[自定义组件指南](custom-component.md)(流程)· [质量标准](quality.md)(质量)
7
+
8
+ ---
9
+
10
+ ## S1 组件形态
11
+
12
+ | # | 标准 | 强制 | 违反时 |
13
+ |---|------|------|--------|
14
+ | S1.1 | 两阶段签名 `Component<P, C>`——外层 mount 一次,内层 renderFn 每次渲染 | **L1** | 编译失败(类型) |
15
+ | S1.2 | **render-only**:改状态后显式 `ctx.render()`——无自动渲染 | 文档红线 | 交互不更新(审查/测试抓) |
16
+ | S1.3 | renderFn 的 await 只允许 `ctx.data`(管道保证 resolve) | 文档红线 | 挂起(永不 resolve) |
17
+ | S1.4 | 工厂(mount)内禁止副作用/昂贵操作——数据走 `ctx.data` | 文档红线 | 重复执行(N 实例 = N 次) |
18
+
19
+ ## S2 children 结构(值域协议)
20
+
21
+ **children 只接受四类值**:vnode / 数组(隐式 Fragment——任意嵌套递归展开)/
22
+ string·number(文本)/ 空洞(`false`·`null`·`undefined`·`true`——占位不渲染)。
23
+
24
+ | # | 标准 | 强制 | 违反时 |
25
+ |---|------|------|--------|
26
+ | S2.1 | children 值域协议(对象/函数/Symbol = 非法输入) | **L2** | `console.warn` + 诊断占位 |
27
+ | S2.2 | 数组 = 隐式 Fragment(嵌套递归展开——路径稳定) | **L3** | 契约测试 X-B5 |
28
+ | S2.3 | 条件渲染:三元优先(`cond ? <X/> : null`);`cond && <X/>` 的 cond 保证 boolean | 文档红线 | `0 && <X/>` 渲染 "0" |
29
+ | S2.4 | **禁 `x || <Fallback/>`**(0/''/NaN 脏值泄漏)——用 `x != null ? ... : null` | 文档红线 | 渲染 "0"/空文本 |
30
+ | S2.5 | **children 数组禁 `filter(Boolean)`**——占位法已处理空洞(长度恒定保位置) | **L2** | A 级检测 dev error |
31
+ | S2.6 | 条件渲染的 false 是占位(同构——不塌缩兄弟) | **L3** | 契约测试 X-B4 |
32
+
33
+ ## S3 列表
34
+
35
+ | # | 标准 | 强制 | 违反时 |
36
+ |---|------|------|--------|
37
+ | S3.1 | **有状态组件实例列表必须显式 key**(业务身份——增删/重排状态跟随) | **L2** | A 级检测 dev error(长度变化 + 无 key 组件项——portal 槽豁免) |
38
+ | S3.2 | 无内部状态元素列表无 key(位置身份——patch 正确) | 文档红线 | 状态错位(误加 key 噪音) |
39
+ | S3.3 | keyed 项路径 `.k{key}` 稳定(单 keyed 项不翻转) | **L3** | 契约测试 X-B3 |
40
+
41
+ ## S4 状态与受控
42
+
43
+ | # | 标准 | 强制 | 违反时 |
44
+ |---|------|------|--------|
45
+ | S4.1 | **受控 props 必须配回调**(active/value/checkedKeys 等——父独占状态,回调是唯一出口) | **L2** | `console.warn`(按 name 幂等) |
46
+ | S4.2 | 受控输入用 `ctx.ui.useControlledInput`(输入态不依赖受控 value 回流——防焦点丢失) | 文档红线 | 输入失焦 |
47
+ | S4.3 | 共享状态 `createStore` + `ctx.ui.useExternal` | 文档红线 | — |
48
+ | S4.4 | 内部状态闭包 `let` + 显式 render(不触发渲染的缓存用 let 不 render) | 文档红线 | — |
49
+ | S4.5 | **props 里的对象变更必须换引用**(不可变更新——`[...items, x]` 而非 `items.push(x)`)——剪枝是引用比较——同引用内容变化永远不触发重渲染(deepFreeze 豁免对象——含函数属性——不被冻结) | 文档红线 | 内容变了 UI 不更新 |
50
+
51
+ ## S5 浮层
52
+
53
+ | # | 标准 | 强制 | 违反时 |
54
+ |---|------|------|--------|
55
+ | S5.1 | **浮层唯一入口 `ctx.ui.openPopup`**(命令式——toast 心智)——portal 机制已删除 | **L3** + 文档红线 | 契约 + 场景 |
56
+ | S5.2 | 浮层根 `position: fixed` + JS 坐标 + `#__wf_portal`(禁 absolute 相对父容器) | 文档红线 | overflow/transform 裁剪 |
57
+ | S5.3 | 新弹层组件先查 openPopup 能力(定位/Escape/外部点击/presence/mask——anchor 必传) | 文档红线 | 重复造轮子 |
58
+
59
+ ## S6 生命周期
60
+
61
+ | # | 标准 | 强制 | 违反时 |
62
+ |---|------|------|--------|
63
+ | S6.1 | **ref 定义在 mount 作用域**(内联 ref 每渲染新函数 → 旧 ref(null) 反复触发清理) | 文档红线 | 清理逻辑反复执行 |
64
+ | S6.2 | 卸载清理:`onUnmount`(退订/清定时器/removeEventListener) | **L3** | 契约 X-G1 |
65
+ | S6.3 | 浏览器能力走 `ctx.browser`(禁裸 `window.`/`document.`/`localStorage` 等) | 审计基线 | grep 审计(CI 噪音) |
66
+
67
+ ## S7 环境
68
+
69
+ | # | 标准 | 强制 | 违反时 |
70
+ |---|------|------|--------|
71
+ | S7.1 | 工厂层取数走 `ctx.data`(三场景:SSR 收集/hydration 种子/SPA fetch + 并发合并) | **L3** | 契约 X-A5/X-G3 |
72
+ | S7.2 | 个性化/会话数据不进 ctx.data(SSR 序列化泄漏)——留客户端 let + fetch | 文档红线 | 数据泄露 |
73
+
74
+ ---
75
+
76
+ ## S8 路由与 SSR(引擎标准——每个 vdom 必须实现——vdom-x 验收)
77
+
78
+ | # | 标准 | 强制 | 违反时 |
79
+ |---|------|------|--------|
80
+ | S8.1 | **UIRouter**:`get(path, handler)` / `notFound`——Trie 匹配(静态段优先参数段优先通配段——`:id` 参数 + `*` 通配)——类比后端 Router | **L3** | 契约 X-R1 |
81
+ | S8.2 | **uiServe**(客户端):SSR 首帧收养(hydrate——路径 id 精确吸收零重建)+ 导航(navigate/链接拦截/popstate) | **L3** | 契约 X-R2/X-R3 |
82
+ | S8.3 | **uiSsr**(服务端):match → 页面 → SSR HTML + 数据种子——同一 UIRouter 实例两端共享(匹配/参数同源) | **L3** | 契约 X-R3 |
83
+ | S8.4 | 导航渲染:根级异类型 = 整树原子替换;同类型(params 变化)= 实例复用 | **L3** | 契约 X-R2 |
84
+ | S8.5 | 页面组件 ctx.route(path/params——共享可变对象——导航更新内容引用恒定) | 文档红线 | 复用组件读旧 params |
85
+
86
+ > **引擎兼容契约**:UIRouter/uiServe/uiSsr 是每个 vdom 的**必选项**(公共面
87
+ > `weifuwu/ui-dom` 导出——vdom5 替换实现即切换——X-R1~R3 验收)。
88
+ > **vdom3 退役条件**:vdom4 通过全部 vdom-x 契约(含 X-R)→ vdom3 删除
89
+ > (组件库测试引擎切换 + 公共面去 v3 导出——见 design/vdom4-risk.md)。
90
+
91
+ ## S9 公共面稳定契约(weifuwu/ui-dom index.ts——对外接口)
92
+
93
+ | # | 标准 | 强制 | 违反时 |
94
+ |---|------|------|--------|
95
+ | S9.1 | **`weifuwu/ui-dom` 公共面 = 对外契约**——内部引擎实现(vdom4/vdom5)切换**不影响功能**——应用/组件只依赖公共面 | **L3** | 契约 X-S1/X-S2 |
96
+ | S9.2 | 契约 API 清单(vdom 无关面):`h/jsx/jsxs/jsxDEV` + `createStore` + `createClientBrowser` + 中间件(`api/auth/ws/i18n`)——**结构符号内化:`Fragment` 不在公共面**(数组 = 隐式 Fragment;浮层 = openPopup 命令式;`<></>` 经 jsx-runtime 子路径自动导入) | **L3** | X-S1 |
97
+ | S9.3 | 引擎契约面:`createRoot`(handle: ready/engine/unmount)+ `UIRouter/uiServe/uiSsr`(S8) | **L3** | X-S2/X-R |
98
+ | S9.4 | **禁止公共面泄漏引擎专属实现**(v3 专属导出过渡期标注——vdom3 退役时移除——不得成为契约) | 文档红线 | 切换时功能变化 |
99
+
100
+ > **公共面 = 兼容性承诺**:vdom-x 全部测试(X-A~R + X-S)经公共面取引擎入口——
101
+ > vdom5 只改 index.ts 的 v4 面实现——测试零改动——全绿 = 公共面功能不变。
102
+
103
+ ## 强制执行机制总览
104
+
105
+ | 机制 | 覆盖 | 位置 |
106
+ |------|------|------|
107
+ | **L1 类型** | S1.1 | `Component`/`RenderFn` 类型(contracts/vnode.ts) |
108
+ | **L2 运行时检测** | S2.1/S2.5/S3.1/S4.1 | vdom4 diff.ts(A 级检测/非法输入/受控 warn——幂等) |
109
+ | **L3 契约测试** | S2.2/S2.6/S3.3/S5.1/S6.2/S7.1 | `src/test/vdom-x.test.ts`(41 测试——vdom5 验收) |
110
+ | **审计测试** | L2 检测自身工作 | `src/test/component-standards.test.ts` |
111
+ | **审计基线** | S6.3 | `grep -rnE '\bwindow\.|document\.' src/components/`(0 允许) |
112
+
113
+ ## 开发流程(强制)
114
+
115
+ 1. 写组件 → 类型检查(L1 编译期)
116
+ 2. dev 运行 → L2 检测报错即修(受控缺回调/key 缺失/非法 children/filter)
117
+ 3. 提测 → 契约测试(L3——引擎行为)
118
+ 4. 发布 → 全量(1538+)
119
+
120
+ ## 与引擎的契约(vdom5 必须满足)
121
+
122
+ vdom-x.test.ts 的 41 测试 = 上述 L3 条目的可执行化。新引擎一行替换入口——
123
+ 全绿 = 组件库零改动迁移 + 标准自动满足。
@@ -1,15 +1,18 @@
1
- # 组件库(weifuwu/components)
1
+ # 组件库使用示例速查
2
+
3
+ > 从 docs/components.md 迁移(content/ 文档库——随 npm 包发布,与框架版本同步)。
4
+ > 本页为叙述性指南——组件/能力逐项参考见 content/ 各域目录。
2
5
 
3
- > 本页为 weifuwu 官方文档拆分页 · [返回 README](../README.md)
6
+ # 组件库(weifuwu/components)
4
7
 
5
- 115 个 HTML 原语组件。每个是 `async (initProps, ctx) => (props) => Promise<VNode>`(两阶段组件,与前端框架同一模型——外层工厂 + 内层 renderFn 强制异步),引用 `--wf-*` CSS 变量做主题。另含 `confirm()` / `toast()` 命令式中间件。
8
+ 129 个 HTML 原语组件。每个是 `async (initProps, ctx) => (props) => Promise<VNode>`(两阶段组件,与前端框架同一模型——外层工厂 + 内层 renderFn 强制异步),引用 `--wf-*` CSS 变量做主题。另含 `confirm()` / `toast()` 命令式中间件。
6
9
 
7
- > **组件速查(weifuwu 组件 ↔ antd / Element Plus / shadcn-ui 对应 + 迁移示例)**:见 [`docs/components-map.md`](components-map.md)——从其他组件库迁来的开发者按功能直接找对应组件。
8
- > **自定义组件开发**:见 [docs/custom-components.md](custom-components.md)——usePopup/useControlled/对话框/AI 组件/类型纪律逐步指南。
10
+ > **组件速查(weifuwu 组件 ↔ antd / Element Plus / shadcn-ui 对应 + 迁移示例)**:见 [`组件速查`](../../docs/components-map.md)——从其他组件库迁来的开发者按功能直接找对应组件。
11
+ > **自定义组件开发**:见 [custom-component.md](custom-component.md)——openPopup/useControlled/对话框/AI 组件/类型纪律逐步指南。
9
12
 
10
13
  ```ts
11
14
  import { Button, Input, Table, Modal, Toast } from 'weifuwu/components'
12
- import 'weifuwu/components/style.css' // 包含 Token + 66 布局原语 + 156 工具类 + 组件样式,一次性引入
15
+ import 'weifuwu/components/style.css' // 包含 Token + 66 布局原语 + 157 工具类 + 组件样式,一次性引入
13
16
  ```
14
17
 
15
18
  ### 使用示例
@@ -634,7 +637,129 @@ props 变化 ──────────────────────
634
637
  |-----|--------|-----------|------|
635
638
  | Chart | `Chart` | `type: ChartType`, `data`, `options`, `title`, `area` | SVG 图表(line/bar/pie)|
636
639
  | DatePicker | `DatePicker` | `mode: DatePickerMode`, `value`, `onChange`, `placeholder`, `disabled` | 日期选择器(date/datetime/time/range)|
637
- | Editor | `Editor` | `value`, `onChange`, `toolbar`, `placeholder`, `disabled` | 富文本编辑器,零依赖 |
640
+ | Editor | `Editor` | `value`, `onChange`, `toolbar`, `placeholder`, `disabled`, `ai?` | 富文本编辑器(事件流事务层:撤销/重做/时光机;AI 协作可选) |
641
+ | FilePreview | `FilePreview` | `type`, `content?`, `url?`, `editable?`, `ai?`, `onSave?` | 文件预览(md/html/pdf/office/text)——基于事件流,md/text 可编辑 |
642
+
643
+ ### Editor(富文本编辑器 + AI 协作)
644
+
645
+ 基于 contentEditable 的富文本编辑器,**事件流事务层**:语义操作(格式/链接/图片/表格/AI 替换)→ `edit:commit`(before 快照 + 事件)→ 撤销/重做/时光机精确到任意版本。
646
+
647
+ ```tsx
648
+ import { Editor } from 'weifuwu/components'
649
+
650
+ <Editor value={html} onChange={v => setHtml(v)} placeholder="输入内容..." />
651
+ ```
652
+
653
+ **Props**:
654
+
655
+ | Prop | 类型 | 说明 |
656
+ |------|------|------|
657
+ | `value` / `onChange` | `string` / `(html) => void` | 受控 HTML(内部模型为准——输出经序列化归一化) |
658
+ | `toolbar` | `ToolbarItem[]` | 工具栏项(bold/italic/h1-3/align/link/image/table/clear/source…);默认 18 项 |
659
+ | `placeholder` / `disabled` / `minHeight` | | 占位符 / 禁用 / 最小高度 |
660
+ | `onUpload` | `(file) => Promise<string>` | 图片上传(返回 URL);不传则 URL 输入 |
661
+ | `ai` | `EditorAiOptions` | **AI 协作(可选)**——见下 |
662
+ | `draftKey` | `string` | **草稿持久化(可选)**:内容自动保存(防抖 500ms),挂载时 `value` 为空且存在草稿 → 自动恢复(刷新/崩溃不丢) |
663
+
664
+ **撤销/重做/时光机**:
665
+
666
+ - `Ctrl+Z` / `Ctrl+Y`:一步撤销/重做**语义操作**(输入合并为单步——连续打字一次撤销全退)
667
+ - 工具栏 🕘 **操作历史**:commit 列表(标签 + 时间)→ 点击回到任意版本(redo 保留可重做回来)
668
+
669
+ **AI 协作**(`ai` prop——不传则无 AI 能力):
670
+
671
+ ```tsx
672
+ <Editor
673
+ value={html}
674
+ onChange={v => setHtml(v)}
675
+ ai={{ url: '/api/ai-editor' }} // wf: SSE 端点([ai-contract](../../docs/ai-contract.md))
676
+ />
677
+ ```
678
+
679
+ - 工具栏 AI 动作组(默认:润色/翻译/缩写/扩写/纠错)——选中文本(无选区 = 全文)→ 点击 → 浮层**流式**生成建议(原文 diff 对比)→ **接受**(替换 = 一个原子撤销步)/ **拒绝**
680
+ - `Ctrl+Enter`:快速触发最近使用的 AI 动作
681
+ - 自定义动作:`ai.actions`(prompt 模板注入 `{selection}`)
682
+
683
+ ```tsx
684
+ <Editor value={html} onChange={v => setHtml(v)}
685
+ ai={{
686
+ url: '/api/ai-editor',
687
+ actions: [{
688
+ id: 'tone', label: '改语气',
689
+ prompt: ({ selection }) => `请把以下文本改为正式语气:\n\n${selection}`,
690
+ }],
691
+ }} />
692
+ ```
693
+
694
+ ### FilePreview(文件预览——基于事件流)
695
+
696
+ md/html/pdf/office/text 文件预览——**文档 = fold(事件流)**(复用 Editor 文档模型):
697
+ md/text 解析为 DocState——预览/编辑/撤销/AI 同一模型;编辑后可序列化回 md 保存。
698
+
699
+ ```tsx
700
+ import { FilePreview } from 'weifuwu/components'
701
+
702
+ // md 预览 + 编辑 + AI 协作(润色文档 = 原子撤销)
703
+ <FilePreview type="md" content={md} editable ai={{ url: '/api/ai' }}
704
+ onSave={(md) => saveToSandbox(md)} fileName="README.md" />
705
+ ```
706
+
707
+ **类型支持矩阵**:
708
+
709
+ | 类型 | 预览 | 编辑 | 说明 |
710
+ |------|------|------|------|
711
+ | `md` | ✅ 复用 `<Markdown>`(安全 token 渲染:表格/任务列表/URL 白名单) | ✅ 复用 `<Editor>`(事件流事务层——撤销/时光机/AI) | 编辑保存 = 序列化回 Markdown |
712
+ | `text` | `<pre>` | ✅ 复用 `<Editor>` | 纯文本 |
713
+ | `html` | ✅ iframe `sandbox`(安全隔离——不直插 DOM) | ❌(安全边界) | 只读 |
714
+ | `pdf` | ✅ iframe(浏览器原生查看器) | ❌ | 只读 |
715
+ | `office` | ✅ iframe(服务端转换产物 URL) | ❌ | 转换由服务端提供(前端零依赖——诚实裁剪) |
716
+
717
+ **Props**:`type`(可选——按 `fileName`/`url` 扩展名自动探测:md/txt/html/pdf/
718
+ docx 等)、`content`(md/html/text)、`url`(远程加载/文件服务路径)、
719
+ `editable`(md/text 切换 Editor)、`ai`(编辑模式透传 Editor AI 协作)、
720
+ `onSave(content, type)`(保存回写)、`onLoad`(解析完成)、`height`。
721
+
722
+ **交互**:工具条「复制」(原始内容——`ctx.browser.copyText`)+「保存」;
723
+ 编辑模式 `Ctrl+S` 保存。远程文件(sandbox 路径):`url` 加载 + `onSave` 回写。
724
+
725
+ ### SheetGrid(xlsx 网格编辑器——ODES 事件流)
726
+
727
+ **Props**:`workbook`(受控 WorkbookState——稀疏 cells Map)、`onChange`、
728
+ `ai`(AI 公式——SSE wf:)、`readonly`、`height`。
729
+
730
+ **能力**:单元格编辑(点击 → input → Enter/focusout 提交)、行列增删(引用平移)、
731
+ 撤销(Ctrl+Z——commit 快照)、sheet 标签切换、**AI 公式**(选中单元格 → 相邻数据
732
+ 上下文提示 → 浮层确认 → 接受 = cell-set commit 原子撤销)。
733
+
734
+ **事件流**:每个编辑 = `OfficeOp` → `__edit_tail(50, 'office')` 审计;AI 接受带
735
+ `target=messageId`(跨端关联 `__ai_events`)。
736
+
737
+ ### SlideCanvas(pptx 画布编辑器——ODES 事件流)
738
+
739
+ **Props**:`deck`(受控 DeckState——slide → shape 几何集合)、`onChange`、
740
+ `ai`(AI 润色)、`readonly`、`height`。
741
+
742
+ **能力**:960×540 画布(scale 适配)、shape 拖拽移动/右下角缩放(pointerup 原子
743
+ 提交)、双击文本编辑、幻灯片增删、Delete 删除、撤销、**AI 润色**(选中 shape →
744
+ 浮层确认 → 接受 = shape-set commit)。
745
+
746
+ ### Office 前端转换(零依赖——无需后端)
747
+
748
+ `weifuwu/office`(源码 `src/office/`——打包进 components):docx/xlsx/pptx ↔
749
+ ODES 模型(DocState/WorkbookState/DeckState)双向转换——自研 ZIP(EOCD→central→
750
+ local + `DecompressionStream('deflate-raw')`)+ 轻量 XML 解析器 + VNode 组件化
751
+ 生成 OOXML(OOXML 也是 VNode——与前端 VNode → DOM 同构)。
752
+
753
+ **用法**(FilePreview 内置):`editable` office 类型 → 打开本地 docx/xlsx/pptx →
754
+ 对应编辑器(Editor/SheetGrid/SlideCanvas)→ 下载导出。裁剪:复杂分节/公式计算/
755
+ 动画母版——诚实提示。
756
+
757
+ **事件流**:预览加载 `editEmit('preview')`(`__edit_tail` 可审计);编辑走 Editor
758
+ commit 事件流(同一时间线)。**sandbox 集成**:`url` 加载 + `onSave` 回写由消费方接
759
+ 文件读写工具。
760
+
761
+ **裁剪**:docx/xlsx/pptx 前端解析不做(零依赖——office 由服务端转换);代码块/
762
+ 表格编辑时降级(超 Editor 模型——见 md 转换文档)。
638
763
 
639
764
  ### 布局
640
765
 
@@ -665,3 +790,24 @@ props 变化 ──────────────────────
665
790
 
666
791
  ---
667
792
 
793
+ ---
794
+
795
+ ## 易混组件对照(选型必读——名字相近或功能重叠时的一句话决策)
796
+
797
+ | 易混组 | 选型规则(一句话) |
798
+ |--------|------------------|
799
+ | Toast vs Notification | 操作反馈(轻、自动消失) vs 系统通知(重、持久列表)——命令式 API 同源 |
800
+ | Menu vs Menubar vs NavMenu | 侧栏菜单(分组+方向键) vs 水平菜单栏(顶层+子菜单) vs 页面主导航(子菜单折叠态) |
801
+ | List vs VirtualList | 数据量 <500 用 List;>500 或未知用 VirtualList(固定行高) |
802
+ | Table vs VirtualTable | 同 List 规则(VirtualTable 虚拟行渲染) |
803
+ | Select vs AutoComplete vs SearchInput | 固定选项单选 vs 自由输入联想(带下拉) vs 搜索框(无下拉语义) |
804
+ | Editor vs CodeEditor vs MarkdownEditor | 轻量 markdown vs 代码(行号/Tab) vs 分屏实时预览 |
805
+ | Collapse vs Accordion | 多开(互不干扰) vs 单开(互斥语义) |
806
+ | Alert vs AlertGroup | 单条静态 vs 多条轮播(自动/手动切换) |
807
+ | ToggleGroup vs SegmentedControl | pressed 状态语义(shadcn) vs 选中态样式(antd Segmented) |
808
+ | Img vs ImageCropper vs Avatar | 展示+预览 vs 裁剪流程 vs 头像(名字哈希色) |
809
+ | Tree vs TreeSelect vs Cascader | 树形展示/勾选 vs 树形选择(下拉) vs 级联选择(路径语义) |
810
+ | SheetGrid vs SlideCanvas(FilePreview.Sheet/.Slide) | xlsx 网格编辑 vs pptx 画布编辑——均从 FilePreview 入口发现 |
811
+
812
+ > **家族导航**:`FilePreview`(预览入口)→ `FilePreview.Sheet`(xlsx)/ `FilePreview.Slide`(pptx);
813
+ > AI 会话族(AiChat/ChatInput/MessageBubble/SessionList/ReasoningBlock/ToolCallCard/CitationCard/ApprovalCard)统一归 ai 分类。
@@ -1,9 +1,17 @@
1
1
  # 自定义组件开发指南
2
2
 
3
+ > 从 docs/custom-components.md 迁移(2026-08)——自定义组件全流程:骨架/状态/弹层/对话框/AI/异步/类型/测试/受控/动画/浏览器纪律/样式纪律。
4
+ > 逐步指南配套:[选型](choose.md) · [组件模型](component-model.md) · [质量标准](quality.md)
5
+ >
6
+ > ⚠️ **先读 [组件编写标准(强制)](component-standards.md)**——L1 类型/L2 运行时检测/L3 契约测试
7
+ > 三层强制——本文是流程,标准是红线。
3
8
 
4
- > ⚠️ **weifuwu/client 已并入 `weifuwu/ui-dom`**(`src/client/` 已删除)——前端运行时唯一入口为 `weifuwu/ui-dom`,见 [frontend-ui-dom.md](frontend-ui-dom.md)。
9
+ # 自定义组件开发指南
10
+
11
+
12
+ > ⚠️ **weifuwu/client 已并入 `weifuwu/ui-dom`**(`src/client/` 已删除)——前端运行时唯一入口为 `weifuwu/ui-dom`,见 [ui-dom 指南](ui-dom-guide.md)。
5
13
  > 用 weifuwu/ui-dom 写自己的组件——与内置组件同权:同渲染引擎、同弹层原语、同类型安全。
6
- > 前置:[前端概念](frontend.md)(两阶段模型/ctx.ui)+ [组件列表](components.md)。
14
+ > 前置:[前端概念](frontend.md)(两阶段模型/ctx.ui)+ [组件速查](components-guide.md)。
7
15
 
8
16
  ---
9
17
 
@@ -62,71 +70,78 @@ const Toggle: Component = async (_init, ctx) => {
62
70
 
63
71
  ## 2. 带弹层的组件(最高频的自定义场景)
64
72
 
65
- 用 `ctx.ui.usePopup`——一个组合器收敛 open 状态 + 触发(hover→tap 降级/longpress)+ Escape + 外部点击 + 定位/视口 clamp + portal:
73
+ 用 `ctx.ui.openPopup`——命令式弹窗(toast 心智——调用点构建内容——内核
74
+ 自管理挂载/更新/卸载——返回 handle `{ close, update, open }`——定位/外部点击
75
+ /Escape/视口夹紧/presence/mask 全内置)——组件输出纯业务(无槽)
66
76
 
67
77
  ```tsx
68
78
  const MyPopover: Component<{ content: string }> = async (_init, ctx) => {
69
79
  let open = false
70
80
  let wrapEl: HTMLElement | null = null
71
81
  const wrapRef = (el: HTMLElement | null) => { wrapEl = el }
82
+ let handle: PopupHandle | null = null
83
+
84
+ // 句柄同步样板(受控 + 内容更新 + 关闭清理——每次渲染恒调用)
85
+ const syncPopup = (content: string) => {
86
+ if (open && !handle)
87
+ handle = ctx.ui.openPopup({
88
+ anchor: () => wrapEl, // **anchor 必传**(触发区是锚点——否则被当外部点击关闭)
89
+ content: () => h('div', { class: 'wf-panel' }, content),
90
+ onClose: () => { handle = null; open = false; ctx.ui.render() },
91
+ })
92
+ else if (!open && handle) { handle.close(); handle = null }
93
+ else if (handle) handle.update(h('div', { class: 'wf-panel' }, content))
94
+ }
72
95
 
73
- const popup = ctx.ui.usePopup({
74
- trigger: 'hover', // 触屏自动降级 tap(useHoverCapable 内部判定)
75
- el: () => wrapEl, // 锚点
76
- isOpen: () => open,
77
- setOpen: (v) => { open = v; ctx.ui.render() }, // 改状态 + render
78
- width: 320, // 自动 clamp 视口
79
- closeOnOutside: true, // 外部点击关闭(默认)
80
- closeOnEscape: true, // Escape 关闭(默认,document 级——portal 焦点也生效)
81
- })
82
-
83
- return async (props) =>
84
- h('span', { class: 'anchor', ref: wrapRef, ...popup.wrapProps },
85
- props.children,
86
- popup.portal(h('div', { class: 'wf-panel' }, props.content)),
87
- )
96
+ return async (props) => {
97
+ syncPopup(props.content)
98
+ return h('span', {
99
+ class: 'anchor', ref: wrapRef,
100
+ onMouseEnter: () => { open = true; ctx.ui.render() }, // hover 触发(组件自管)
101
+ onMouseLeave: () => { open = false; ctx.ui.render() },
102
+ }, props.children)
103
+ }
88
104
  }
89
105
  ```
90
106
 
91
- > **受控弹层**:传 `open` getter + `onOpenChange` 即受控(父组件独占开关);缺 onOpenChange 时 usePopup 内部 warn 提示。
107
+ > **受控弹层**:open 状态由父组件独占(props.open + onOpenChange)——组件内部
108
+ > 只做句柄同步;非受控(无 open prop)时组件自管状态(`let open` + 触发事件)。
109
+ > **关闭路径**:内核 onClose 回调(外部点击/Escape 触发)同步句柄 + 状态——
110
+ > 组件无需显式清空(内核 dispose 全权)。
92
111
 
93
112
  ## 3. 对话框类组件(Modal 系)
94
113
 
95
- 全屏对话框(焦点 trap + 滚动锁 + 退场动画)是 usePopup 的**会话级模态模式**(`presence/trapFocus/lockScroll/positioning: 'none'`——Modal/Drawer 同款):
114
+ 全屏对话框(焦点 trap + 滚动锁 + 退场动画)是 openPopup 的**会话级模态模式**
115
+ (`presence/trapFocus/lockScroll/positioning: 'none'`——Modal/Drawer 同款):
96
116
 
97
117
  ```tsx
98
118
  const MyDialog: Component<{ open: boolean; onClose: () => void }> = async (_init, ctx) => {
99
- let latestOpen = false
100
- const popup = ctx.ui.usePopup({
101
- presence: true, // 退场状态机(open → exit → closed + animationend)
102
- trapFocus: true, // 焦点 trap(面板挂载锁定/卸载归还)
103
- lockScroll: true, // 滚动锁(打开锁 / 面板卸载释放)
104
- positioning: 'none', // 组件自定义定位(.wf-modal inset:0 居中)
105
- closeOnOutside: false, closeOnEscape: false, // 关闭语义组件自控
106
- isOpen: () => latestOpen,
107
- setOpen: () => {},
108
- }) // mount 创建
109
-
119
+ let handle: PopupHandle | null = null
110
120
  return async (props) => {
111
- latestOpen = !!props.open
112
- const phase = popup.sync!(latestOpen) // render 同步 open
113
- if (phase === 'closed') return null
114
-
115
- return popup.portal(h('div', {
116
- class: 'wf-overlay',
117
- onClick: (e: any) => { if (e.target === e.currentTarget) props.onClose() },
118
- }, h('div', {
119
- class: `wf-modal ${phase === 'exit' ? 'wf-modal--exit' : 'wf-modal--enter'}`,
120
- onKeyDown: (e: any) => { if (e.key === 'Escape') props.onClose() }, // Escape 语义组件层
121
- }, props.children)), 'modal') // portalKey 语义化(#__wf_portal 容器标记)
121
+ // 命令式同步(受控 + 退场:关闭前先渲染 exit class → close 播动画)
122
+ if (props.open && !handle)
123
+ handle = ctx.ui.openPopup({
124
+ key: 'dialog',
125
+ presence: true, // 退场状态机(open → exit → closed + animationend)
126
+ trapFocus: true, // 焦点 trap(面板挂载锁定/卸载归还)
127
+ lockScroll: true, // 滚动锁(打开锁 / 卸载释放)
128
+ positioning: 'none', // 组件自定义定位(.wf-modal inset:0 居中)
129
+ closeOnOutside: false, closeOnEscape: false, // 关闭语义组件自控
130
+ content: () => h('div', { class: 'wf-overlay', onClick: (e: any) => { if (e.target === e.currentTarget) props.onClose() } },
131
+ h('div', { class: `wf-modal ${props.open ? 'wf-modal--enter' : 'wf-modal--exit'}`,
132
+ onKeyDown: (e: any) => { if (e.key === 'Escape') props.onClose() } }, props.children)),
133
+ onClose: () => { handle = null },
134
+ })
135
+ else if (!props.open && handle) { handle.update(rootVn); handle.close(); handle = null }
136
+ else if (handle) handle.update(rootVn)
137
+ return null // 主树零输出
122
138
  }
123
139
  }
124
140
  ```
125
141
 
126
- > **ref 接线**:`trapFocus`/`lockScroll`/presence 退场监听全部由 usePopup 内部接线到 portal 面板
127
- > (`portalPanelRef`——content 的 `ref` prop 会被转发调用)——组件层无需手挂 `rootRef`/`panelRef`。
128
- > 低层原语 `trapFocus`/`lockScroll` 已收编为 usePopup 内部实现(**不对外导出**——AGENTS.md §5.4);
129
- > `animateOut` 仍从 `weifuwu/ui-dom` 导出(非弹窗动画场景用)。
142
+ > **ref 接线**:`trapFocus`/`lockScroll`/presence 退场监听全部由 openPopup 内核接线
143
+ > (面板根元素自动挂 ref——组件层无需手挂)——低层原语已收编为内核实现(不对外导出)。
144
+ > `animateOut` 仍可用(非弹窗动画场景)。
130
145
 
131
146
  ## 4. AI 组件
132
147
 
@@ -208,8 +223,8 @@ render() // 初始
208
223
  render() // 重渲染,状态保留
209
224
  ```
210
225
 
211
- - 弹层组件:`createPopupMock(isOpen)` 注入 `createTestCtx({ ui: { usePopup: () => popup } })`
212
- - 类型流测试:`@ts-expect-error` 负例(见 [type-flow.test.ts](../src/components/type-flow.test.ts))
226
+ - 弹层组件:`createPopupMock(isOpen)` 注入 `createTestCtx({ ui: { openPopup: (opts) => popup } })`
227
+ - 类型流测试:`@ts-expect-error` 负例(见 [type-flow.test.ts](../../src/components/type-flow.test.ts))
213
228
  - 组件测试跑在 node --test;DOM 事件级测试需 `document.body.appendChild(container)`
214
229
 
215
230
  ## 8. 受控组件标准
@@ -282,12 +297,12 @@ const MyComp: Component = async (_init, ctx) => {
282
297
 
283
298
  | 想要的能力 | 参考源码 |
284
299
  |-----------|---------|
285
- | 弹层组合(hover/click/longpress) | [Tooltip.ts](../src/components/Tooltip/Tooltip.ts) / [ContextMenu.ts](../src/components/ContextMenu/ContextMenu.ts) |
286
- | 对话框状态机 | [Modal.ts](../src/components/Modal/Modal.ts) / [Drawer.ts](../src/components/Drawer/Drawer.ts) |
287
- | AI 会话 | [AiChat.ts](../src/components/AiChat/AiChat.ts) |
288
- | 受控 + 键盘导航 | [Collapse.ts](../src/components/Collapse/Collapse.ts) / [Tabs.ts](../src/components/Tabs/Tabs.ts) |
289
- | 异步数据 | [UserProfile](../src/components/Img/Img.ts) 的 factory 模式 |
290
- | 命令式 API(toast/confirm) | [Toast.ts](../src/components/Toast/Toast.ts) |
300
+ | 弹层组合(hover/click/longpress) | [Tooltip.ts](../../src/components/Tooltip/Tooltip.ts) / [ContextMenu.ts](../../src/components/ContextMenu/ContextMenu.ts) |
301
+ | 对话框状态机 | [Modal.ts](../../src/components/Modal/Modal.ts) / [Drawer.ts](../../src/components/Drawer/Drawer.ts) |
302
+ | AI 会话 | [AiChat.ts](../../src/components/AiChat/AiChat.ts) |
303
+ | 受控 + 键盘导航 | [Collapse.ts](../../src/components/Collapse/Collapse.ts) / [Tabs.ts](../../src/components/Tabs/Tabs.ts) |
304
+ | 异步数据 | [UserProfile](../../src/components/Img/Img.ts) 的 factory 模式 |
305
+ | 命令式 API(toast/confirm) | [Toast.ts](../../src/components/Toast/Toast.ts) |
291
306
 
292
307
  ## 已知边界(诚实裁剪)
293
308
 
@@ -299,7 +314,7 @@ const MyComp: Component = async (_init, ctx) => {
299
314
  - 断言/快照测试注意:`outerHTML` 包含这些属性与占位注释;按类选择器/子项数量断言不受影响
300
315
  - **列表 key 纪律**:渲染的列表是**有内部状态的组件实例 + 动态增删/重排**(如可输入的卡片)→ 必须显式 key(项 id),否则默认下标位置复用会让后续项继承被删项的内部状态;纯元素列表(格子/行/节点 div)默认下标即可——通用列表组件对外提供 `keyBy`(如 `List`)
301
316
 
302
- - `usePopup` 是**统一弹窗能力层**:锚定浮层(Tooltip/Popover/Dropdown/Select/AutoComplete/Mentions/Cascader/ContextMenu/NavMenu/Popconfirm/TreeSelect)+ 会话级模态(Modal/Drawer/Confirm——presence/trapFocus/lockScroll/positioning 'none',Escape 语义留组件层)+ mask 模式(Command/Img preview/Tour——mask/maskCentered/自定义 mask VNode)+ focus 触发(DatePicker)+ positioning 'none' 常驻容器(Toast/Notification)——**全部弹窗单一入口**
317
+ - `openPopup` 是**统一弹窗能力层**(命令式——toast 心智):锚定浮层(Tooltip/Popover/Dropdown/Select/AutoComplete/Mentions/Cascader/ContextMenu/NavMenu/Popconfirm/TreeSelect)+ 会话级模态(Modal/Drawer/Confirm——presence/trapFocus/lockScroll/positioning 'none',Escape 语义留组件层)+ mask 模式(Command/Img preview/Tour)+ positioning 'none' 常驻容器(Toast/Notification)——**全部弹窗单一入口**(组件内部句柄同步样板 ~10 行——anchor 必传)
303
318
  - **事件监听纪律**:组件库内部浏览器事件监听**统一走 `ctx.ui.useXXX`**——滚动/观察/弹层/对话框/快捷键/拖拽/DnD 全覆盖:
304
319
  `useInView`(InfiniteScroll)、`useScrollPosition`(AiChat/Affix/BackTop/VirtualList)、`usePopupPosition`(Affix 阈值重算)、`usePopup`(弹窗统一——ContextMenu 自由定位 + Modal/Drawer 模态模式 + mask 遮罩)、`useGlobalKey`(Command 快捷键/Img preview Escape)、`useDrag`(Resizable)、`useDragDrop`(FileUpload)、`useControlled`/`useStableRef`(状态/ref)
305
320
  - **唯一保留 usePopupPosition 独立使用**:Affix / Chart(坐标工具——非弹窗组合器,滚动跟随自动)
@@ -1,9 +1,12 @@
1
+ # 数据层指南(sql/redis)
2
+
3
+ > 从 docs/data.md 迁移(content/ 文档库——随 npm 包发布,与框架版本同步)。
4
+ > 本页为叙述性指南——组件/能力逐项参考见 content/ 各域目录。
5
+
1
6
  # 数据层 — postgres / redis(weifuwu)
2
7
 
3
8
  自研 PG v3 / RESP2 协议客户端,真实库测试(CS-04),故障恢复见各节。
4
9
 
5
- > 本页为 weifuwu 官方文档拆分页 · [返回 README](../README.md)
6
-
7
10
  ## postgres — PostgreSQL 客户端(自研)
8
11
 
9
12
  > **自研 PG v3 协议**(零第三方依赖)——支持 SCRAM-SHA-256 认证、扩展查询(参数化)、类型映射(int8 超范围自动 string 防丢精度)、事务、连接池(acquire 超时防饿死)、schema 写前校验、statement_timeout 慢查询保护。
@@ -0,0 +1,18 @@
1
+ # FilePreview 家族 · components
2
+
3
+ > Office 文档域组件——单入口发现全部能力(07 命名治理:家族归并)。
4
+ > 顶层 `SheetGrid` / `SlideCanvas` 导出保留(向后兼容),新代码推荐命名空间访问。
5
+
6
+ | 成员 | 命名空间访问 | 顶层别名 | 能力 |
7
+ |------|------------|---------|------|
8
+ | FilePreview | `FilePreview` | — | 多类型预览/编辑入口(md/html/pdf/office/text + 图片) |
9
+ | SheetGrid | `FilePreview.Sheet` | `SheetGrid` | xlsx 网格编辑器(ODES 事件流——单元格编辑/公式/样式) |
10
+ | SlideCanvas | `FilePreview.Slide` | `SlideCanvas` | pptx 画布编辑器(幻灯片/元素/转换) |
11
+
12
+ ## 选型
13
+
14
+ ```
15
+ 未知类型文件 → FilePreview(自动识别 + 降级)
16
+ xlsx 数据编辑 → FilePreview.Sheet(或 SheetGrid)
17
+ pptx 画布编辑 → FilePreview.Slide(或 SlideCanvas)
18
+ ```