@h-ai/ui 0.1.0-alpha9 → 1.0.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (367) hide show
  1. package/README.en.md +1036 -0
  2. package/README.ja.md +1036 -0
  3. package/README.md +670 -119
  4. package/auto-import.d.ts +45 -0
  5. package/auto-import.js +46 -69
  6. package/dist/components/compounds/Accordion.svelte +30 -3
  7. package/dist/components/compounds/Accordion.svelte.d.ts +37 -1
  8. package/dist/components/compounds/ActionSheet.svelte +35 -8
  9. package/dist/components/compounds/ActionSheet.svelte.d.ts +41 -1
  10. package/dist/components/compounds/Alert.svelte +24 -15
  11. package/dist/components/compounds/Alert.svelte.d.ts +14 -3
  12. package/dist/components/compounds/AppBar.svelte +37 -9
  13. package/dist/components/compounds/AppBar.svelte.d.ts +36 -1
  14. package/dist/components/compounds/BottomNav.svelte +68 -8
  15. package/dist/components/compounds/BottomNav.svelte.d.ts +51 -1
  16. package/dist/components/compounds/Breadcrumb.svelte +18 -5
  17. package/dist/components/compounds/Breadcrumb.svelte.d.ts +23 -2
  18. package/dist/components/compounds/Calendar.svelte +31 -12
  19. package/dist/components/compounds/Calendar.svelte.d.ts +23 -7
  20. package/dist/components/compounds/Card.svelte +17 -5
  21. package/dist/components/compounds/Card.svelte.d.ts +13 -2
  22. package/dist/components/compounds/Combobox.svelte +124 -42
  23. package/dist/components/compounds/Combobox.svelte.d.ts +42 -20
  24. package/dist/components/compounds/Confirm.svelte +32 -9
  25. package/dist/components/compounds/Confirm.svelte.d.ts +24 -2
  26. package/dist/components/compounds/DataTable.svelte +317 -33
  27. package/dist/components/compounds/DataTable.svelte.d.ts +28 -14
  28. package/dist/components/compounds/DatePicker.svelte +62 -18
  29. package/dist/components/compounds/DatePicker.svelte.d.ts +27 -8
  30. package/dist/components/compounds/Drawer.svelte +179 -22
  31. package/dist/components/compounds/Drawer.svelte.d.ts +24 -2
  32. package/dist/components/compounds/Dropdown.svelte +19 -5
  33. package/dist/components/compounds/Dropdown.svelte.d.ts +13 -2
  34. package/dist/components/compounds/Empty.svelte +22 -9
  35. package/dist/components/compounds/Empty.svelte.d.ts +23 -2
  36. package/dist/components/compounds/FilterBar.svelte +82 -0
  37. package/dist/components/compounds/FilterBar.svelte.d.ts +39 -0
  38. package/dist/components/compounds/Form.svelte +59 -16
  39. package/dist/components/compounds/Form.svelte.d.ts +23 -2
  40. package/dist/components/compounds/FormField.svelte +99 -16
  41. package/dist/components/compounds/FormField.svelte.d.ts +23 -2
  42. package/dist/components/compounds/FormLayout.svelte +71 -0
  43. package/dist/components/compounds/FormLayout.svelte.d.ts +17 -0
  44. package/dist/components/compounds/InfiniteScroll.svelte +34 -7
  45. package/dist/components/compounds/InfiniteScroll.svelte.d.ts +37 -1
  46. package/dist/components/compounds/JsonViewer.svelte +214 -0
  47. package/dist/components/compounds/JsonViewer.svelte.d.ts +26 -0
  48. package/dist/components/compounds/MessageBoxContainer.svelte +34 -0
  49. package/dist/components/compounds/MessageBoxContainer.svelte.d.ts +25 -0
  50. package/dist/components/compounds/MessageBoxDialog.svelte +209 -0
  51. package/dist/components/compounds/MessageBoxDialog.svelte.d.ts +29 -0
  52. package/dist/components/compounds/MessageContainer.svelte +24 -0
  53. package/dist/components/compounds/MessageContainer.svelte.d.ts +18 -0
  54. package/dist/components/compounds/Modal.svelte +348 -73
  55. package/dist/components/compounds/Modal.svelte.d.ts +13 -2
  56. package/dist/components/compounds/PageHeader.svelte +44 -20
  57. package/dist/components/compounds/PageHeader.svelte.d.ts +24 -9
  58. package/dist/components/compounds/Pagination.svelte +139 -105
  59. package/dist/components/compounds/Pagination.svelte.d.ts +23 -2
  60. package/dist/components/compounds/Popover.svelte +124 -25
  61. package/dist/components/compounds/Popover.svelte.d.ts +23 -2
  62. package/dist/components/compounds/PullRefresh.svelte +35 -8
  63. package/dist/components/compounds/PullRefresh.svelte.d.ts +35 -1
  64. package/dist/components/compounds/Result.svelte +17 -4
  65. package/dist/components/compounds/Result.svelte.d.ts +23 -2
  66. package/dist/components/compounds/SafeArea.svelte +30 -3
  67. package/dist/components/compounds/SafeArea.svelte.d.ts +35 -1
  68. package/dist/components/compounds/Skeleton.svelte +19 -7
  69. package/dist/components/compounds/Skeleton.svelte.d.ts +13 -2
  70. package/dist/components/compounds/Steps.svelte +17 -4
  71. package/dist/components/compounds/Steps.svelte.d.ts +23 -2
  72. package/dist/components/compounds/SwipeCell.svelte +30 -3
  73. package/dist/components/compounds/SwipeCell.svelte.d.ts +40 -1
  74. package/dist/components/compounds/TableToolbar.svelte +289 -0
  75. package/dist/components/compounds/TableToolbar.svelte.d.ts +69 -0
  76. package/dist/components/compounds/Tabs.svelte +84 -14
  77. package/dist/components/compounds/Tabs.svelte.d.ts +13 -2
  78. package/dist/components/compounds/TagInput.svelte +51 -33
  79. package/dist/components/compounds/TagInput.svelte.d.ts +23 -2
  80. package/dist/components/compounds/Timeline.svelte +30 -3
  81. package/dist/components/compounds/Timeline.svelte.d.ts +37 -1
  82. package/dist/components/compounds/ToastContainer.svelte +386 -28
  83. package/dist/components/compounds/ToastContainer.svelte.d.ts +27 -1
  84. package/dist/components/compounds/Tooltip.svelte +143 -9
  85. package/dist/components/compounds/Tooltip.svelte.d.ts +25 -2
  86. package/dist/components/compounds/accordion-types.d.ts +10 -1
  87. package/dist/components/compounds/action-sheet-types.d.ts +9 -0
  88. package/dist/components/compounds/bottom-nav-types.d.ts +9 -0
  89. package/dist/components/compounds/index.d.ts +7 -0
  90. package/dist/components/compounds/index.js +11 -0
  91. package/dist/components/compounds/swipe-cell-types.d.ts +9 -0
  92. package/dist/components/compounds/timeline-types.d.ts +9 -0
  93. package/dist/components/control-size.d.ts +35 -0
  94. package/dist/components/control-size.js +26 -0
  95. package/dist/components/primitives/Avatar.svelte +19 -5
  96. package/dist/components/primitives/Avatar.svelte.d.ts +13 -2
  97. package/dist/components/primitives/Badge.svelte +16 -4
  98. package/dist/components/primitives/Badge.svelte.d.ts +13 -2
  99. package/dist/components/primitives/BareButton.svelte +26 -12
  100. package/dist/components/primitives/BareButton.svelte.d.ts +23 -2
  101. package/dist/components/primitives/BareInput.svelte +57 -35
  102. package/dist/components/primitives/BareInput.svelte.d.ts +23 -2
  103. package/dist/components/primitives/Button.svelte +30 -9
  104. package/dist/components/primitives/Button.svelte.d.ts +13 -2
  105. package/dist/components/primitives/Checkbox.svelte +24 -5
  106. package/dist/components/primitives/Checkbox.svelte.d.ts +23 -2
  107. package/dist/components/primitives/IconButton.svelte +35 -10
  108. package/dist/components/primitives/IconButton.svelte.d.ts +23 -2
  109. package/dist/components/primitives/Input.svelte +56 -26
  110. package/dist/components/primitives/Input.svelte.d.ts +13 -2
  111. package/dist/components/primitives/Progress.svelte +17 -4
  112. package/dist/components/primitives/Progress.svelte.d.ts +23 -2
  113. package/dist/components/primitives/Radio.svelte +17 -4
  114. package/dist/components/primitives/Radio.svelte.d.ts +22 -2
  115. package/dist/components/primitives/Range.svelte +31 -4
  116. package/dist/components/primitives/Range.svelte.d.ts +37 -1
  117. package/dist/components/primitives/Rating.svelte +32 -5
  118. package/dist/components/primitives/Rating.svelte.d.ts +37 -1
  119. package/dist/components/primitives/Select.svelte +404 -47
  120. package/dist/components/primitives/Select.svelte.d.ts +23 -2
  121. package/dist/components/primitives/Spinner.svelte +17 -4
  122. package/dist/components/primitives/Spinner.svelte.d.ts +23 -2
  123. package/dist/components/primitives/Switch.svelte +22 -4
  124. package/dist/components/primitives/Switch.svelte.d.ts +23 -2
  125. package/dist/components/primitives/Tag.svelte +17 -4
  126. package/dist/components/primitives/Tag.svelte.d.ts +23 -2
  127. package/dist/components/primitives/Textarea.svelte +75 -30
  128. package/dist/components/primitives/Textarea.svelte.d.ts +24 -2
  129. package/dist/components/primitives/ToggleCheckbox.svelte +24 -10
  130. package/dist/components/primitives/ToggleCheckbox.svelte.d.ts +23 -2
  131. package/dist/components/primitives/ToggleInput.svelte +24 -10
  132. package/dist/components/primitives/ToggleInput.svelte.d.ts +23 -2
  133. package/dist/components/primitives/ToggleRadio.svelte +24 -10
  134. package/dist/components/primitives/ToggleRadio.svelte.d.ts +23 -2
  135. package/dist/components/scenes/ai/AiDocumentDownloadMenu.svelte +54 -23
  136. package/dist/components/scenes/ai/AiDocumentDownloadMenu.svelte.d.ts +30 -1
  137. package/dist/components/scenes/ai/AiDocumentEditor.svelte +3428 -693
  138. package/dist/components/scenes/ai/AiDocumentEditor.svelte.d.ts +26 -1
  139. package/dist/components/scenes/ai/MarkdownRenderer.svelte +119 -116
  140. package/dist/components/scenes/ai/MarkdownRenderer.svelte.d.ts +31 -1
  141. package/dist/components/scenes/ai/code-preview.d.ts +46 -0
  142. package/dist/components/scenes/ai/code-preview.js +141 -0
  143. package/dist/components/scenes/ai/document-download.d.ts +52 -0
  144. package/dist/components/scenes/ai/document-download.js +296 -77
  145. package/dist/components/scenes/ai/document-parse.d.ts +101 -11
  146. package/dist/components/scenes/ai/document-parse.js +212 -48
  147. package/dist/components/scenes/ai/document-types.d.ts +292 -75
  148. package/dist/components/scenes/ai/editor-markdown-extensions.d.ts +27 -0
  149. package/dist/components/scenes/ai/editor-markdown-extensions.js +215 -0
  150. package/dist/components/scenes/ai/highlight.d.ts +37 -0
  151. package/dist/components/scenes/ai/highlight.js +162 -0
  152. package/dist/components/scenes/ai/index.d.ts +5 -2
  153. package/dist/components/scenes/ai/index.js +3 -0
  154. package/dist/components/scenes/ai/markdown-parse.d.ts +11 -3
  155. package/dist/components/scenes/ai/markdown-parse.js +42 -31
  156. package/dist/components/scenes/ai/mermaid-host-sync.d.ts +72 -0
  157. package/dist/components/scenes/ai/mermaid-host-sync.js +65 -0
  158. package/dist/components/scenes/ai/mermaid-render.d.ts +30 -0
  159. package/dist/components/scenes/ai/mermaid-render.js +61 -0
  160. package/dist/components/scenes/ai/safe-html.d.ts +64 -0
  161. package/dist/components/scenes/ai/safe-html.js +345 -0
  162. package/dist/components/scenes/ai/table/AiTableEditor.svelte +1692 -0
  163. package/dist/components/scenes/ai/table/AiTableEditor.svelte.d.ts +32 -0
  164. package/dist/components/scenes/ai/table/table-types.d.ts +181 -0
  165. package/dist/components/scenes/ai/table/table-types.js +1 -0
  166. package/dist/components/scenes/app/FeedbackDetail.svelte +236 -0
  167. package/dist/components/scenes/app/FeedbackDetail.svelte.d.ts +40 -0
  168. package/dist/components/scenes/app/FeedbackForm.svelte +337 -0
  169. package/dist/components/scenes/app/FeedbackForm.svelte.d.ts +72 -0
  170. package/dist/components/scenes/app/FeedbackList.svelte +150 -0
  171. package/dist/components/scenes/app/FeedbackList.svelte.d.ts +28 -0
  172. package/dist/components/scenes/app/FeedbackModal.svelte +65 -139
  173. package/dist/components/scenes/app/FeedbackModal.svelte.d.ts +14 -39
  174. package/dist/components/scenes/app/FeedbackRecorder.svelte +154 -0
  175. package/dist/components/scenes/app/FeedbackRecorder.svelte.d.ts +9 -0
  176. package/dist/components/scenes/app/FeedbackReplay.svelte +142 -0
  177. package/dist/components/scenes/app/FeedbackReplay.svelte.d.ts +7 -0
  178. package/dist/components/scenes/app/FeedbackScreenshot.svelte +120 -0
  179. package/dist/components/scenes/app/FeedbackScreenshot.svelte.d.ts +8 -0
  180. package/dist/components/scenes/app/LanguageSwitch.svelte +38 -21
  181. package/dist/components/scenes/app/LanguageSwitch.svelte.d.ts +33 -20
  182. package/dist/components/scenes/app/SettingsLayout.svelte +115 -0
  183. package/dist/components/scenes/app/SettingsLayout.svelte.d.ts +54 -0
  184. package/dist/components/scenes/app/SettingsModal.svelte +33 -7
  185. package/dist/components/scenes/app/SettingsModal.svelte.d.ts +27 -1
  186. package/dist/components/scenes/app/ThemeColorPicker.svelte +240 -0
  187. package/dist/components/scenes/app/ThemeColorPicker.svelte.d.ts +57 -0
  188. package/dist/components/scenes/app/ThemeSelector.svelte +87 -26
  189. package/dist/components/scenes/app/ThemeSelector.svelte.d.ts +26 -7
  190. package/dist/components/scenes/app/ThemeToggle.svelte +27 -6
  191. package/dist/components/scenes/app/ThemeToggle.svelte.d.ts +24 -5
  192. package/dist/components/scenes/app/WorkspaceLayout.svelte +64 -0
  193. package/dist/components/scenes/app/WorkspaceLayout.svelte.d.ts +36 -0
  194. package/dist/components/scenes/app/feedback-functions.d.ts +57 -0
  195. package/dist/components/scenes/app/feedback-functions.js +107 -0
  196. package/dist/components/scenes/app/feedback-types.d.ts +224 -0
  197. package/dist/components/scenes/app/feedback-types.js +1 -0
  198. package/dist/components/scenes/app/index.d.ts +8 -1
  199. package/dist/components/scenes/app/index.js +7 -1
  200. package/dist/components/scenes/charts/Chart.svelte +163 -0
  201. package/dist/components/scenes/charts/Chart.svelte.d.ts +25 -0
  202. package/dist/components/scenes/charts/chart-theme.d.ts +47 -0
  203. package/dist/components/scenes/charts/chart-theme.js +68 -0
  204. package/dist/components/scenes/charts/chart-types.d.ts +153 -0
  205. package/dist/components/scenes/charts/chart-types.js +7 -0
  206. package/dist/components/scenes/charts/index.d.ts +8 -0
  207. package/dist/components/scenes/charts/index.js +7 -0
  208. package/dist/components/scenes/charts/renderers/AreaChart.svelte +18 -0
  209. package/dist/components/scenes/charts/renderers/AreaChart.svelte.d.ts +5 -0
  210. package/dist/components/scenes/charts/renderers/BarChart.svelte +18 -0
  211. package/dist/components/scenes/charts/renderers/BarChart.svelte.d.ts +5 -0
  212. package/dist/components/scenes/charts/renderers/LineChart.svelte +624 -0
  213. package/dist/components/scenes/charts/renderers/LineChart.svelte.d.ts +32 -0
  214. package/dist/components/scenes/charts/renderers/PieChart.svelte +18 -0
  215. package/dist/components/scenes/charts/renderers/PieChart.svelte.d.ts +5 -0
  216. package/dist/components/scenes/charts/renderers/ScatterChart.svelte +18 -0
  217. package/dist/components/scenes/charts/renderers/ScatterChart.svelte.d.ts +5 -0
  218. package/dist/components/scenes/crud/CrudDeleteConfirm.svelte +29 -11
  219. package/dist/components/scenes/crud/CrudDeleteConfirm.svelte.d.ts +13 -1
  220. package/dist/components/scenes/crud/CrudDetailDrawer.svelte +77 -22
  221. package/dist/components/scenes/crud/CrudDetailDrawer.svelte.d.ts +19 -4
  222. package/dist/components/scenes/crud/CrudDetailPanel.svelte +242 -0
  223. package/dist/components/scenes/crud/CrudDetailPanel.svelte.d.ts +66 -0
  224. package/dist/components/scenes/crud/CrudEditPanel.svelte +365 -0
  225. package/dist/components/scenes/crud/CrudEditPanel.svelte.d.ts +48 -0
  226. package/dist/components/scenes/crud/CrudFilterBar.svelte +17 -85
  227. package/dist/components/scenes/crud/CrudFilterBar.svelte.d.ts +13 -25
  228. package/dist/components/scenes/crud/CrudPage.svelte +564 -185
  229. package/dist/components/scenes/crud/CrudPage.svelte.d.ts +137 -51
  230. package/dist/components/scenes/crud/crud-controller.svelte.d.ts +335 -0
  231. package/dist/components/scenes/crud/crud-controller.svelte.js +276 -0
  232. package/dist/components/scenes/crud/crud-form-validation.d.ts +16 -0
  233. package/dist/components/scenes/crud/crud-form-validation.js +51 -0
  234. package/dist/components/scenes/crud/crud-types.d.ts +136 -43
  235. package/dist/components/scenes/crud/index.d.ts +9 -3
  236. package/dist/components/scenes/crud/index.js +8 -3
  237. package/dist/components/scenes/crud/nav-adapter.d.ts +50 -0
  238. package/dist/components/scenes/crud/nav-adapter.js +39 -0
  239. package/dist/components/scenes/crypto/EncryptedInput.svelte +63 -28
  240. package/dist/components/scenes/crypto/EncryptedInput.svelte.d.ts +38 -3
  241. package/dist/components/scenes/crypto/HashDisplay.svelte +30 -22
  242. package/dist/components/scenes/crypto/HashDisplay.svelte.d.ts +24 -1
  243. package/dist/components/scenes/crypto/SignatureDisplay.svelte +41 -40
  244. package/dist/components/scenes/crypto/SignatureDisplay.svelte.d.ts +24 -1
  245. package/dist/components/scenes/error/ErrorPage.svelte +135 -0
  246. package/dist/components/scenes/error/ErrorPage.svelte.d.ts +50 -0
  247. package/dist/components/scenes/error/error-presets.d.ts +60 -0
  248. package/dist/components/scenes/error/error-presets.js +51 -0
  249. package/dist/components/scenes/error/index.d.ts +8 -0
  250. package/dist/components/scenes/error/index.js +8 -0
  251. package/dist/components/scenes/guide/GuideHost.svelte +56 -0
  252. package/dist/components/scenes/guide/GuideHost.svelte.d.ts +35 -0
  253. package/dist/components/scenes/guide/GuideHostContent.svelte +136 -0
  254. package/dist/components/scenes/guide/GuideHostContent.svelte.d.ts +43 -0
  255. package/dist/components/scenes/guide/HelpCenter.svelte +135 -0
  256. package/dist/components/scenes/guide/HelpCenter.svelte.d.ts +40 -0
  257. package/dist/components/scenes/guide/index.d.ts +2 -0
  258. package/dist/components/scenes/guide/index.js +2 -0
  259. package/dist/components/scenes/iam/AgreementNotice.svelte +48 -0
  260. package/dist/components/scenes/iam/AgreementNotice.svelte.d.ts +7 -0
  261. package/dist/components/scenes/iam/AuthPanel.svelte +226 -0
  262. package/dist/components/scenes/iam/AuthPanel.svelte.d.ts +29 -0
  263. package/dist/components/scenes/iam/AuthShell.svelte +160 -0
  264. package/dist/components/scenes/iam/AuthShell.svelte.d.ts +56 -0
  265. package/dist/components/scenes/iam/ChangePasswordForm.svelte +84 -63
  266. package/dist/components/scenes/iam/ChangePasswordForm.svelte.d.ts +13 -1
  267. package/dist/components/scenes/iam/ForgotPasswordForm.svelte +113 -89
  268. package/dist/components/scenes/iam/ForgotPasswordForm.svelte.d.ts +24 -1
  269. package/dist/components/scenes/iam/LoginForm.svelte +215 -117
  270. package/dist/components/scenes/iam/LoginForm.svelte.d.ts +13 -1
  271. package/dist/components/scenes/iam/PasswordInput.svelte +79 -32
  272. package/dist/components/scenes/iam/PasswordInput.svelte.d.ts +30 -4
  273. package/dist/components/scenes/iam/PermGuard.svelte +21 -11
  274. package/dist/components/scenes/iam/PermGuard.svelte.d.ts +30 -0
  275. package/dist/components/scenes/iam/ReauthenticationDialog.svelte +68 -0
  276. package/dist/components/scenes/iam/ReauthenticationDialog.svelte.d.ts +17 -0
  277. package/dist/components/scenes/iam/RegisterForm.svelte +129 -116
  278. package/dist/components/scenes/iam/RegisterForm.svelte.d.ts +13 -1
  279. package/dist/components/scenes/iam/ResetPasswordForm.svelte +101 -88
  280. package/dist/components/scenes/iam/ResetPasswordForm.svelte.d.ts +13 -1
  281. package/dist/components/scenes/iam/SensitiveOperationsForm.svelte +76 -0
  282. package/dist/components/scenes/iam/SensitiveOperationsForm.svelte.d.ts +21 -0
  283. package/dist/components/scenes/iam/SessionRecoveryDialog.svelte +64 -0
  284. package/dist/components/scenes/iam/SessionRecoveryDialog.svelte.d.ts +22 -0
  285. package/dist/components/scenes/iam/UserProfile.svelte +47 -21
  286. package/dist/components/scenes/iam/UserProfile.svelte.d.ts +24 -1
  287. package/dist/components/scenes/iam/auth-captcha.d.ts +21 -0
  288. package/dist/components/scenes/iam/auth-captcha.js +23 -0
  289. package/dist/components/scenes/iam/auth-error-message.d.ts +13 -0
  290. package/dist/components/scenes/iam/auth-error-message.js +65 -0
  291. package/dist/components/scenes/iam/index.d.ts +10 -0
  292. package/dist/components/scenes/iam/index.js +9 -1
  293. package/dist/components/scenes/iam/password-utils.d.ts +33 -6
  294. package/dist/components/scenes/iam/password-utils.js +61 -8
  295. package/dist/components/scenes/iam/permission-context.svelte.d.ts +33 -23
  296. package/dist/components/scenes/iam/permission-context.svelte.js +20 -22
  297. package/dist/components/scenes/iam/sensitive-actions.svelte.d.ts +68 -0
  298. package/dist/components/scenes/iam/sensitive-actions.svelte.js +101 -0
  299. package/dist/components/scenes/iam/session-recovery.svelte.d.ts +44 -0
  300. package/dist/components/scenes/iam/session-recovery.svelte.js +57 -0
  301. package/dist/components/scenes/index.d.ts +3 -0
  302. package/dist/components/scenes/index.js +5 -0
  303. package/dist/components/scenes/storage/AvatarUpload.svelte +82 -68
  304. package/dist/components/scenes/storage/AvatarUpload.svelte.d.ts +23 -1
  305. package/dist/components/scenes/storage/FileList.svelte +19 -5
  306. package/dist/components/scenes/storage/FileList.svelte.d.ts +23 -1
  307. package/dist/components/scenes/storage/FileUpload.svelte +151 -96
  308. package/dist/components/scenes/storage/FileUpload.svelte.d.ts +24 -1
  309. package/dist/components/scenes/storage/ImageUpload.svelte +93 -94
  310. package/dist/components/scenes/storage/ImageUpload.svelte.d.ts +24 -1
  311. package/dist/components/scenes/types.d.ts +574 -42
  312. package/dist/guide-storage.d.ts +18 -0
  313. package/dist/guide-storage.js +79 -0
  314. package/dist/guide-types.d.ts +143 -0
  315. package/dist/guide-types.js +1 -0
  316. package/dist/guide.d.ts +3 -0
  317. package/dist/guide.js +3 -0
  318. package/dist/guide.svelte.d.ts +29 -0
  319. package/dist/guide.svelte.js +506 -0
  320. package/dist/i18n.svelte.d.ts +67 -4
  321. package/dist/i18n.svelte.js +106 -21
  322. package/dist/index.d.ts +6 -0
  323. package/dist/index.js +7 -0
  324. package/dist/internal/browser-safety.d.ts +88 -0
  325. package/dist/internal/browser-safety.js +140 -0
  326. package/dist/internal/dialog-focus.d.ts +21 -0
  327. package/dist/internal/dialog-focus.js +77 -0
  328. package/dist/internal/form-context.d.ts +92 -0
  329. package/dist/internal/form-context.js +70 -0
  330. package/dist/internal/form-validation.svelte.d.ts +70 -0
  331. package/dist/internal/form-validation.svelte.js +142 -0
  332. package/dist/internal/icon-safety.d.ts +14 -0
  333. package/dist/internal/icon-safety.js +40 -0
  334. package/dist/internal/locale.d.ts +21 -0
  335. package/dist/internal/locale.js +43 -0
  336. package/dist/message.svelte.d.ts +138 -0
  337. package/dist/message.svelte.js +149 -0
  338. package/dist/messagebox.svelte.d.ts +130 -0
  339. package/dist/messagebox.svelte.js +171 -0
  340. package/dist/messages/en-US.json +297 -16
  341. package/dist/messages/ja-JP.json +523 -0
  342. package/dist/messages/zh-CN.json +297 -16
  343. package/dist/messages.d.ts +25 -3
  344. package/dist/messages.js +23 -6
  345. package/dist/styles/design-tokens.css +4 -2
  346. package/dist/styles/formal.css +55 -0
  347. package/dist/styles/global.css +86 -18
  348. package/dist/styles/guide.css +88 -0
  349. package/dist/styles/high-contrast.css +64 -0
  350. package/dist/styles/mobile.css +28 -0
  351. package/dist/styles/theme.css +42 -0
  352. package/dist/theme-config.d.ts +263 -10
  353. package/dist/theme-config.js +252 -17
  354. package/dist/toast.svelte.d.ts +210 -2
  355. package/dist/toast.svelte.js +296 -19
  356. package/dist/types.d.ts +787 -63
  357. package/dist/utils/platform.svelte.d.ts +28 -15
  358. package/dist/utils/platform.svelte.js +23 -16
  359. package/dist/utils.d.ts +121 -1
  360. package/dist/utils.js +208 -13
  361. package/dist/workspace-context.d.ts +20 -0
  362. package/dist/workspace-context.js +9 -0
  363. package/package.json +120 -24
  364. package/vite.d.ts +13 -0
  365. package/vite.js +96 -0
  366. package/dist/components/scenes/crud/CrudEditDrawer.svelte +0 -225
  367. package/dist/components/scenes/crud/CrudEditDrawer.svelte.d.ts +0 -48
package/README.en.md ADDED
@@ -0,0 +1,1036 @@
1
+ # @h-ai/ui
2
+
3
+ [简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
4
+
5
+ [Framework home](../../README.en.md) · Related modules: [@h-ai/core](../core/README.en.md)
6
+
7
+ ## Introduction
8
+
9
+ Built-in messages support `zh-CN`, `en-US` and `ja-JP`; the language selector offers all three by default.
10
+
11
+ A cross-platform Svelte 5 Runes component library with DaisyUI v5 + Tailwind CSS v4 styling and Bits UI v2 headless interactions. Includes built-in i18n (zh-CN / en-US / ja-JP) and 15 curated DaisyUI themes plus high contrast and square business themes.
12
+
13
+ ## Core features
14
+
15
+ - Forms, tables, dialogs, navigation, charts and application components.
16
+ - Authentication, CRUD, AI content, onboarding and a help center.
17
+ - Svelte 5, themes, responsive layouts and Chinese/English/Japanese component messages.
18
+
19
+ ## Getting started
20
+
21
+ ### Installation
22
+
23
+ ```bash
24
+ npm install @h-ai/ui @h-ai/core
25
+ ```
26
+
27
+ For a Node server, declare both UI and core as production dependencies so the adapter preserves native logging and runtime dependencies.
28
+
29
+ ### Quick start
30
+
31
+ #### 1. Configure svelte.config.js
32
+
33
+ ```js
34
+ import { autoImportHaiUi } from '@h-ai/ui/auto-import'
35
+ import adapter from '@sveltejs/adapter-node'
36
+ import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'
37
+
38
+ /** @type {import('@sveltejs/kit').Config} */
39
+ const config = {
40
+ preprocess: [autoImportHaiUi(), vitePreprocess()],
41
+ compilerOptions: { runes: true },
42
+ kit: { adapter: adapter() },
43
+ }
44
+
45
+ export default config
46
+ ```
47
+
48
+ #### 2. Configure vite.config.ts
49
+
50
+ ```ts
51
+ import { haiOptimizeExclude, haiPrebundledDeps } from '@h-ai/ui/vite'
52
+ import { sveltekit } from '@sveltejs/kit/vite'
53
+ import tailwindcss from '@tailwindcss/vite'
54
+ import { defineConfig } from 'vite'
55
+
56
+ export default defineConfig({
57
+ plugins: [sveltekit(), tailwindcss()],
58
+ optimizeDeps: {
59
+ // bits-ui 含 .svelte 源码须 exclude;@internationalized/date 须与 bits-ui 同为原始副本,
60
+ // 否则日期组件会因双实例 instanceof 失败抛 "Unknown date type"
61
+ exclude: [...haiOptimizeExclude],
62
+ // 预打包 @h-ai/ui 的重型纯 JS 依赖(语法高亮 / Mermaid / PDF 等),
63
+ // 避免首次进入业务路由时触发依赖再优化与整页刷新
64
+ include: [...haiPrebundledDeps],
65
+ },
66
+ ssr: { noExternal: ['@h-ai/ui', '@h-ai/kit'], external: ['@h-ai/core', 'sm-crypto'] },
67
+ })
68
+ ```
69
+
70
+ When using Crypto or Kit/IAM, include `sm-crypto@0.5.7` in application production dependencies. CLI projects already do this; for manual setup, run `pnpm add sm-crypto@0.5.7`. The external option alone is insufficient: adapter-node also uses direct production dependencies to preserve native package loading.
71
+
72
+ #### 3. Configure src/app.css
73
+
74
+ ```css
75
+ @import 'tailwindcss';
76
+ @import '@h-ai/ui/styles/global.css';
77
+ @import '@h-ai/ui/styles/theme.css';
78
+ @source "../node_modules/@h-ai/ui/dist/**/*.{svelte,js,ts}";
79
+ @source "../../../node_modules/@h-ai/ui/dist/**/*.{svelte,js,ts}";
80
+
81
+ @plugin "daisyui" {
82
+ themes: light --default, dark --prefersdark, cupcake, emerald, corporate, nord, dracula, night;
83
+ }
84
+
85
+ /* 图标(可选) */
86
+ @plugin "@iconify/tailwind4" {
87
+ prefixes: tabler;
88
+ }
89
+ ```
90
+
91
+ > `@source` makes TailwindCSS scan classes in `@h-ai/ui`; without it, component styles are missing. In nested monorepo apps, dependencies may be hoisted to root `node_modules`, so retain both paths.
92
+
93
+ #### 4. Use components
94
+
95
+ ```svelte
96
+ <script>
97
+ import { Button, Input, Card } from '@h-ai/ui'
98
+ </script>
99
+
100
+ <Card title="示例表单">
101
+ <Input placeholder="请输入用户名" />
102
+ <Button variant="primary" onclick={handleSubmit}>提交</Button>
103
+ </Card>
104
+ ```
105
+
106
+ With auto-import enabled, use components directly in templates without individual imports:
107
+
108
+ ```svelte
109
+ <!-- 无需 import { Button } from '@h-ai/ui' -->
110
+ <Button variant="primary">提交</Button>
111
+ ```
112
+
113
+ > `@h-ai/ui/auto-import` injects all public Svelte components except `toast`, type imports, and `Range` (which conflicts with the DOM `Range` constructor).
114
+
115
+ Pages using a subset of components, such as administration screens, can import public component-directory entry points directly. Import theme utilities from the lightweight `@h-ai/ui/theme` entry so theme consumers do not load the root entry's AI and chart components. Use `@h-ai/ui/i18n` for locale utilities in stores without loading components or tour CSS. Check the installed package's exports; do not import its internal `src/` or `dist/` paths.
116
+
117
+ The preprocessor recognizes semicolon-free, multiline and aliased imports without injecting components already bound locally. Type-only imports do not replace runtime components.
118
+
119
+ ```ts
120
+ import { Card } from '@h-ai/ui/components/compounds/index'
121
+ import { Button } from '@h-ai/ui/components/primitives/index'
122
+ import { getThemeInfo, THEMES } from '@h-ai/ui/theme'
123
+ ```
124
+
125
+ #### data-\* attribute forwarding
126
+
127
+ Public Svelte components forward caller-supplied `data-*` attributes to their root or primary interactive element for tests, analytics, and automation. Other unknown attributes are not forwarded.
128
+
129
+ ```svelte
130
+ <Button data-testid='save-button' data-analytics-id='settings.save'>保存</Button>
131
+ <Input data-testid='username-input' bind:value={username} />
132
+ <Modal data-testid='confirm-modal' bind:open={open}>...</Modal>
133
+ ```
134
+
135
+ No extra button, input, or overlay wrappers are needed just for `data-testid`.
136
+
137
+ ### Component architecture
138
+
139
+ Three layers (primitives → compounds → scenes):
140
+
141
+ ```
142
+ components/
143
+ ├── primitives/ # Indivisible base UI elements
144
+ ├── compounds/ # Primitives + Bits UI headless composition
145
+ └── scenes/ # Complete UI workflows for business scenarios
146
+ ├── ai/ # AI documents / spreadsheets / Markdown preview
147
+ ├── app/ # Settings / feedback / themes / language
148
+ ├── crud/ # CRUD pages / drawers / filters / delete confirmation
149
+ ├── iam/ # Authentication
150
+ ├── storage/ # Storage management
151
+ └── crypto/ # Cryptographic display
152
+ ```
153
+
154
+ ### Component catalog
155
+
156
+ #### Primitives (20)
157
+
158
+ | Component | Description | Key props |
159
+ | ---------------- | ------------------- | ------------------------------------------------------------------------------ |
160
+ | `Button` | Button | `variant`, `size`, `loading`, `disabled`, `outline`, `circle` |
161
+ | `IconButton` | Icon button | `icon: trusted SVG string \| Snippet`, `variant`, `size`, `tooltip`, `loading` |
162
+ | `BareButton` | Unstyled button | `class`, `ariaLabel`, `role`, `tabindex` |
163
+ | `Input` | Input | `type`, `value`, `size`, `error`, `validationMessage` |
164
+ | `BareInput` | Unstyled input | `type`, `class`, `accept`, `multiple` |
165
+ | `Textarea` | Text area | `value`, `rows`, `size`, `autoResize`, `error` |
166
+ | `Select` | Select | `options`, `value`, `placeholder`, `size`, `clearable`, `filterable` |
167
+ | `Checkbox` | Checkbox | `checked`, `label`, `size`, `indeterminate` |
168
+ | `Switch` | Switch | `checked`, `label`, `size` |
169
+ | `Radio` | Radio group | `options`, `value`, `direction`, `size` |
170
+ | `ToggleCheckbox` | Native switch input | `checked`, `name`, `onchange` |
171
+ | `ToggleInput` | Native toggle input | `checked`, `name` |
172
+ | `ToggleRadio` | Native radio input | `checked`, `name`, `onchange` |
173
+ | `Range` | Slider | `value`, `min`, `max`, `step` |
174
+ | `Rating` | Rating | `value`, `max` |
175
+ | `Badge` | Badge | `variant`, `size`, `outline` |
176
+ | `Avatar` | Avatar | `src`, `name`, `size`, `shape`, `ring` |
177
+ | `Tag` | Tag | `text`, `variant`, `size`, `closable` |
178
+ | `Spinner` | Loading animation | `size`, `variant` |
179
+ | `Progress` | Progress bar | `value`, `max`, `variant`, `striped`, `animated` |
180
+
181
+ For `BareInput` with `type="file"`, read `event.currentTarget.files` in `onchange` and leave the file path `value` unbound. Other input types support `bind:value`.
182
+
183
+ #### Compounds (37)
184
+
185
+ ##### Forms
186
+
187
+ | Component | Description | Key props |
188
+ | ----------- | -------------- | -------------------------------------------- |
189
+ | `Form` | Form container | `columns`, `labelPosition`, `labelWidth`, `loading`, `disabled`, `onsubmit` |
190
+ | `FormField` | Form field | `label`, `for`, `colSpan`, `labelPosition`, `error`, `hint`, `required` |
191
+ | `FormLayout` | Form layout | `columns`, `labelPosition`, `labelWidth` |
192
+ | `TagInput` | Tag input | `tags`, `maxTags`, `allowDuplicates`, `size` |
193
+
194
+ ##### Form layouts and validation
195
+
196
+ `Form` and `FormLayout` (for native `<form>` elements) share `columns={1 | 2}`, `labelPosition="top" | "left"` and `labelWidth` (default `8rem`). Defaults are one column and stacked labels. Two columns collapse below a container width of `36rem`; inline labels stack below `28rem`.
197
+
198
+ `FormField.colSpan` defaults to `'auto'`: textareas, file/image uploads, TagInput and multiple Combobox controls span both columns. Use `1` or `2` to override, or mark a custom wide control with `data-form-wide`. Non-field content, including headings, error summaries and actions, spans the full row. Fields may override `labelPosition` / `labelWidth`.
199
+
200
+ Labels connect to nested UI controls automatically; use `<FormField for="control-id">` for explicit IDs or native controls. Errors and hints use `aria-describedby`, invalid controls use `aria-invalid`, and field errors appear once. `label` / `error` / `hint` accept strings or deferred translation functions.
201
+
202
+ `Input`, `Textarea`, `Select` and `PasswordInput` provide Chinese/English/Japanese native validation messages. `validationMessage` overrides failures without keeping valid input invalid. Sync locale with the UI `setGlobalLocale` / `createLocaleStore` to update visible validation errors immediately. `Textarea` supports `minlength` / `maxlength`; `Select` supports `name`, required validation and FormData serialization.
203
+
204
+ Field errors appear through Toast. Submitting the same invalid input again shows the error even after the previous notification was dismissed or expired. Correcting input clears the stale notification. Controls retain error borders, `aria-invalid` and linked screen-reader descriptions.
205
+
206
+ Text controls validate on blur after input and update errors as input is corrected. Pristine empty fields validate on submit, so leaving default focus does not shift actions. CRUD create/edit forms also validate on blur after input or on submit, honor custom messages and reset validation when reopened. `Select` validates when focus leaves both its trigger and options. `PasswordInput.minLength` enforces length and informs strength; omitting it leaves login password length unrestricted while strength uses an eight-character baseline.
207
+
208
+ `UserProfile.fieldConstraints` accepts per-field `required`, `minlength`, `maxlength`, `pattern` and `validationMessage` (`pattern` applies to single-line inputs), so application rules such as username formats share blur validation. `validationMessage` also accepts a deferred translation function.
209
+
210
+ `CrudEditPanel.onsubmit` receives only writable fields declared by the form. Fields marked `readonly` are omitted when editing and remain available when creating. Primary keys, related display values and audit timestamps are not copied from the entire row. Null values, `false` and `0` are preserved. Keep strict schema validation on the server.
211
+
212
+ `LoginForm`, `RegisterForm`, `ChangePasswordForm`, `ForgotPasswordForm`, `ResetPasswordForm`, `AuthPanel`, `UserProfile` and `FeedbackModal` accept the same layout options. Pass them through `CrudPage.form` or directly to `CrudEditPanel`. CRUD fields support `colSpan` and deferred `validation.message`. Buttons and Enter both validate before submission; corrections clear errors. Server validation remains required.
213
+
214
+ ```svelte
215
+ <!-- m、save、name、notes 为应用自己的翻译、提交回调和状态 -->
216
+ <Form columns={2} labelPosition="left" labelWidth="6rem" onsubmit={save}>
217
+ <FormField label={() => m.name()} required>
218
+ <Input name="name" bind:value={name} required />
219
+ </FormField>
220
+ <FormField label={() => m.notes()}>
221
+ <Textarea name="notes" bind:value={notes} />
222
+ </FormField>
223
+ <Button type="submit">{m.save()}</Button>
224
+ </Form>
225
+ ```
226
+
227
+ ##### Feedback
228
+
229
+ | Component | Description | Key props |
230
+ | ---------------- | --------------- | ------------------------------------------------- |
231
+ | `Alert` | Alert | `variant`, `title`, `dismissible` |
232
+ | `ToastContainer` | Toast container | Place globally and use with the `toast` singleton |
233
+
234
+ ##### Overlays
235
+
236
+ | Component | Description | Key props |
237
+ | --------- | ------------------- | ---------------------------------------------------------------------------- |
238
+ | `Modal` | Modal with dialog semantics, focus trap and restoration | `open`, `title`, `size`, `radius`, `bodyOverflow`, `showClose` |
239
+ | `Drawer` | Drawer | `open`, `position`, `title`, `size`, `width`, `resizable`, `widthStorageKey` |
240
+ | `Confirm` | Confirmation dialog | `open`, `title`, `message`, `variant`, `onconfirm` |
241
+ | `Popover` | Popover | `open`, `position`, `trigger`, `offset`, `portal` |
242
+
243
+ ##### Data display
244
+
245
+ | Component | Description | Key props |
246
+ | ----------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
247
+ | `Card` | Card container | `title`, `bordered`, `shadow`, `padding` |
248
+ | `JsonViewer` | JSON tree viewer | `value`, `defaultExpandedDepth`, `maxScalarLength`, `showCopy`, `onCopy`; circular references are replaced with a placeholder |
249
+ | `DataTable` | Data table | `data`, `columns`, `keyField`, `loading`, `sortKey`, `sortDir`, `onsort`; `cell` slot and `onrowclick` (`sortable` columns support sorting) |
250
+ | `Accordion` | Accordion | `items: AccordionItem[]` |
251
+ | `Timeline` | Timeline | `items: TimelineItem[]` |
252
+
253
+ ##### Bits UI headless interactions
254
+
255
+ | Component | Description | Key props |
256
+ | ------------ | ----------------------------------- | ----------------------------------------------------------- |
257
+ | `Combobox` | Searchable select (single/multiple) | `options`, `value`, `multiple`, `placeholder`, `size` |
258
+ | `Calendar` | Standalone calendar | `value: DateValue`, `minValue`, `maxValue` |
259
+ | `DatePicker` | Date input with popover | `value: DateValue`, `minValue`, `maxValue`, `error`, `size` |
260
+
261
+ > Dates use `DateValue` / `CalendarDate` from `@internationalized/date`.
262
+
263
+ ##### Mobile / enhanced interactions
264
+
265
+ | Component | Description | Key props |
266
+ | ---------------- | ------------------- | ------------------------------------------------------ |
267
+ | `ActionSheet` | Bottom action sheet | `open`, `title`, `items`, `cancelText`, `onselect` |
268
+ | `AppBar` | Top navigation | `title`, `backHref`, `onback`, `fixed`, `safeArea` |
269
+ | `BottomNav` | Bottom navigation | `items`, `active`, `centered`, `maxWidth` |
270
+ | `InfiniteScroll` | Infinite scrolling | `loading`, `finished`, `threshold`, `onload` |
271
+ | `PullRefresh` | Pull to refresh | `refreshing`, `threshold`, `onrefresh` |
272
+ | `SafeArea` | Safe area container | `top`, `bottom`, `left`, `right` |
273
+ | `SwipeCell` | Swipe actions | `leftActions`, `rightActions`, `threshold`, `onaction` |
274
+
275
+ ##### Navigation
276
+
277
+ | Component | Description | Key props |
278
+ | ------------ | ------------------------------- | ---------------------------------------------------------------------------------------------------------- |
279
+ | `Tabs` | Tabs | `items`, `active`, `type`, `size`, `lazy`, `onactivate` |
280
+ | `Pagination` | Pagination (shared table style) | `page`, `total`, `pageSize`, `showTotal`, `showJumper`, `showSizeChanger`, `showPageInfo`, `showFirstLast` |
281
+ | `Breadcrumb` | Breadcrumbs | `items`, `separator` |
282
+ | `Steps` | Steps | `items`, `current`, `direction`, `clickable` |
283
+ | `Dropdown` | Dropdown menu | `items`, `trigger`, `triggerClass`, `position` |
284
+ | `Tooltip` | Tooltip | `content`, `position`, `delay` |
285
+
286
+ ##### State placeholders
287
+
288
+ | Component | Description | Key props |
289
+ | ---------- | ----------- | ------------------------------------- |
290
+ | `Skeleton` | Skeleton | `variant`, `width`, `height`, `count` |
291
+ | `Empty` | Empty state | `title`, `description`, `icon` |
292
+ | `Result` | Result page | `status`, `title`, `description` |
293
+
294
+ ##### Page-level
295
+
296
+ | Component | Description | Key props |
297
+ | ------------ | ----------- | ----------------------------------------------- |
298
+ | `PageHeader` | Page header | `title`, `description`; supports `actions` slot |
299
+
300
+ #### Scenes (43)
301
+
302
+ ##### Guide (2)
303
+
304
+ | Component | Description | Key props |
305
+ | --- | --- | --- |
306
+ | `GuideHost` | First-use invitations, tours and help dialog host | `guide`, `locale`, `scope`, `autoStart` |
307
+ | `HelpCenter` | Standalone searchable help center | `articles`, `tours`, `locale`, `selectedId`, `onstart` |
308
+
309
+ ##### App (11)
310
+
311
+ | Component | Description | Key props |
312
+ | ------------------ | ---------------------------------------------- | -------------------------------------------------------- |
313
+ | `FeedbackModal` | Feedback modal | `open`, `onsubmit` |
314
+ | `FeedbackForm` | Standalone feedback form | `attachments`, `evidenceSummary`, `onsubmit`, `onfileschange` |
315
+ | `FeedbackList` | Server pagination, filters and processing actions | `data`, `query`, `permissions`, `onquerychange`, `onstatus` |
316
+ | `FeedbackDetail` | Diagnostic evidence, history and exports | `report`, `evidence`, `attachments`, `history`, `webhook`, `onretry`, `onexport` |
317
+ | `FeedbackScreenshot` | Image preview, highlighting and masking | `attachment`, `onannotate` |
318
+ | `SettingsModal` | Settings modal | `open`, `onclose` |
319
+ | `SettingsLayout` | Settings layout (section navigation + content) | `title`, `description`, `sections`, `active`, `onselect` |
320
+ | `LanguageSwitch` | Language switcher | No props required |
321
+ | `ThemeColorPicker` | Theme color picker | `value`, `presets`, `onchange` |
322
+ | `ThemeSelector` | Full theme selector | No props required |
323
+ | `ThemeToggle` | Light/dark toggle | No props required |
324
+
325
+ Pass the type: webhook task from report jobs into FeedbackDetail.webhook to show status, attempts and safe error codes; onretry calls the authenticated retry API. The Business evidence tab paginates kind: business, and archives download from the scene tab.
326
+
327
+ Descriptions are optional. Call `prepare()` from `@h-ai/feedback/client` before opening the modal. Connect `onfileschange` to attachment preparation and `onannotate` to image editing that burns annotations into the pixels. Failed submissions retain input and support local export. The list shows the description or server summary and requests pages through `onquerychange`; UI permissions do not replace server authorization. See the [feedback module](../feedback/README.en.md) for integration and offline tools.
328
+
329
+ ##### IAM authentication (11)
330
+
331
+ | Component | Description | Key props |
332
+ | -------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
333
+ | `AuthPanel` | Configuration driven authentication | `config`, `actions`, `loginHeader/loginFields/loginFooter`, `registerHeader/registerFields/registerFooter` |
334
+ | `AuthShell` | Auth page layout (centered card / split columns) | `variant`, `title`, `subtitle`, `brandTitle`, `brandText`, `illustration`, `description`, `highlights` |
335
+ | `LoginForm` | Login form | `loading`, `errors`, `showForgotPassword`, `onsubmit` |
336
+ | `RegisterForm` | Registration form | `loading`, `errors`, `fields`, `onsubmit` |
337
+ | `ForgotPasswordForm` | Forgot password | `mode`, `loading`, `errors`, `onsubmit` |
338
+ | `ResetPasswordForm` | Reset password | `loading`, `errors`, `showCode`, `onsubmit` |
339
+ | `ChangePasswordForm` | Change password | `loading`, `errors`, `requireOldPassword`, `onsubmit` |
340
+ | `PasswordInput` | Password input | `value`, `showToggle`, `showStrength`, `minLength` |
341
+ | `ReauthenticationDialog` | Sensitive action confirmation | `open`, `loading`, `error`, `onsubmit`, `onclose` |
342
+ | `PermGuard` | Permission guard | `permissions`, `mode`, `fallback` |
343
+ | `UserProfile` | User profile | `user`, `editable`, `fields`, `avatarAccept`, `avatarHint`, `onsubmit` |
344
+ | `SessionRecoveryDialog` | In-place session recovery | `recovery`, `actions` |
345
+ | `SensitiveOperationsForm` | Permission operation editor | `operations`, `onsubmit`, `ondone` |
346
+
347
+ ##### Storage (4)
348
+
349
+ | Component | Description | Key props |
350
+ | -------------- | ------------- | ------------------------------------------------------------ |
351
+ | `FileUpload` | File upload | `accept`, `maxSize`, `maxFiles`, `multiple`, `uploadHandler` |
352
+ | `ImageUpload` | Image upload | `value`, `accept`, `maxSize`, `aspectRatio`, `uploadHandler` |
353
+ | `AvatarUpload` | Avatar upload | `value`, `size`, `maxSize`, `fallback`, `uploadHandler` |
354
+ | `FileList` | File list | `files`, `layout`, `showDelete`, `showDownload` |
355
+
356
+ Upload components do not embed presigning, headers, or PUT/POST protocols. Applications call their service through `uploadHandler(file, { signal, onProgress })` and return `{ url?, response? }`. Image/avatar uploads require a displayable `url`. Without a handler, `FileUpload` only selects files, and image/avatar components generate local previews only.
357
+
358
+ ##### Crypto display (3)
359
+
360
+ Input changes immediately clear `encryptedValue`; only successful results for current input are restored. Clearing, callback replacement, and unmounting invalidate old requests. Failures show built-in errors and leave ciphertext empty. Submit encrypted inputs only when current ciphertext is nonempty.
361
+
362
+ Callers must connect `EncryptedInput` to a real encryption service through `onencrypt`; `algorithm` describes that service's algorithm only. Without a callback, the component shows unavailability and generates no ciphertext, with no Base64 fallback.
363
+
364
+ | Component | Description | Key props |
365
+ | ------------------ | ----------------- | ------------------------------------------------------- |
366
+ | `EncryptedInput` | Encrypted input | `value`, `encryptedValue`, `algorithm`, `showEncrypted` |
367
+ | `HashDisplay` | Hash display | `value`, `algorithm`, `copyable`, `truncate` |
368
+ | `SignatureDisplay` | Signature display | `signature`, `publicKey`, `algorithm`, `verified` |
369
+
370
+ Defaults match `@h-ai/crypto`: `SM4` for encrypted inputs, `SM3` for hashes, and `SM2` for signatures.
371
+
372
+ ##### AI documents and spreadsheets (4)
373
+
374
+ | Component | Description | Key props / capabilities |
375
+ | ------------------------ | ---------------------- | ---------------------------------------------------------------------------------------------------------- |
376
+ | `MarkdownRenderer` | Markdown renderer | `content`, `fontSize`, `allowHtmlTags`, `showCopyButton`, `enableHighlight` |
377
+ | `AiDocumentDownloadMenu` | Document download menu | `actions`, `ondownload` |
378
+ | `AiDocumentEditor` | AI document editor | `content`, `fontSize`, `allowHtmlTags`, `showRunButton`, `showCodePreviewToggle`, `allowUnsafeCodePreview` |
379
+ | `AiTableEditor` | AI spreadsheet editor | `columns`, `rows`, `editable`, `ondownload` |
380
+
381
+ > `AiDocumentEditor` permits only built-in Markdown preview by default. High-risk HTML / JS / CSS previews require explicit `allowUnsafeCodePreview` or controlled results from `oncoderun`.
382
+ >
383
+ > Mermaid works out of the box: ` ```mermaid ` blocks in documents (`sourceKind='document'`) render automatically in reading mode. Code mode (`sourceKind='code'` + `showCodePreviewToggle`) supports code/preview switching. Mermaid uses `securityLevel: 'strict'` and sanitized SVG without `allowUnsafeCodePreview`.
384
+ >
385
+ > `MarkdownRenderer` and `AiDocumentEditor` also support presentation options:
386
+ >
387
+ > - `fontSize` accepts a `number` in px or any CSS length such as `1.125rem`.
388
+ > - `allowHtmlTags` is off by default; when enabled, tags such as `<b>` / `<i>` / `<u>` / `<mark>` use a safe allowlist, with dangerous tags/attributes still sanitized.
389
+ > - Text entities in safe HTML retain one level of meaning, so quotes, comparison operators and `&` in configuration snippets remain readable. Encoded tags remain text and are never reparsed as markup.
390
+ > - Raw `<img>` tags retain `width` / `height` as positive integer pixel values from 1 to 99999. These reserve space before lazy images load and keep document layout and anchor positions stable. Percentages, negatives, decimals, events, and arbitrary `style` are removed.
391
+
392
+ ```svelte
393
+ <MarkdownRenderer content={markdown} fontSize='1.125rem' allowHtmlTags />
394
+
395
+ <AiDocumentEditor
396
+ title='方案文档'
397
+ content={documentMarkdown}
398
+ fontSize={18}
399
+ allowHtmlTags
400
+ showToolbar
401
+ showOutline={false}
402
+ />
403
+ ```
404
+
405
+ ##### Charts
406
+
407
+ `Chart type='line'` uses LayerChart's native line chart by default. For monitoring dashboards with segmented lines, points, nearest-point hover, and vertical reference lines, use `lineVariant='segmented-point'`:
408
+
409
+ ```svelte
410
+ <Chart
411
+ type='line'
412
+ data={trendData}
413
+ x='label'
414
+ y={['rateLimit', 'circuitBreak']}
415
+ series={trendSeries}
416
+ lineVariant='segmented-point'
417
+ tooltipMode='nearest'
418
+ showCrosshair
419
+ legend
420
+ grid
421
+ />
422
+ ```
423
+
424
+ ##### CRUD scenes (5)
425
+
426
+ | Component | Description | Key props / capabilities |
427
+ | ------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
428
+ | `CrudPage` | CRUD page | `crud`, `data`, `permissions`, `form`, `pagination`, `density`, `detailColumns`, `showHeader`, `toolbarLeading`, `toolbarActions`, `card`, `tableCell`, `onrowclick`, `sortableColumns`, `nav`, `loading`, `loaded`, `error`, `onRetry`, `keepPreviousData` |
429
+ | `CrudFilterBar` | Filter toolbar (search + typed filters + reset) | `filterFields`, `searchValue`, `onsearch`, `onfilterchange`, `onreset` |
430
+ | `CrudDetailPanel` | Details panel (drawer/modal) | `open`, `item`, `fields`, `variant`, `drawerWidth`, `modalSize` |
431
+ | `CrudEditPanel` | Edit panel (drawer/modal) | `open`, `fields`, `variant`, `drawerWidth`, `modalSize`, `onsubmit` |
432
+ | `CrudDeleteConfirm` | Delete confirmation | `open`, `loading`, `onconfirm` |
433
+
434
+ > `CrudPage` and `FeedbackList` share a query bar inside the list card, an independently scrolling table and bottom pagination. Search, Query and Reset stay visible; extra filters start collapsed and retain their drafts. Query or Enter submits all conditions once; editing fields does not query automatically. Paging and sorting use applied conditions. Reset clears search, filters and sorting and returns to page one. Sorting buttons appear in column headers; `sortableColumns` must contain only fields supported by the backend. `detailColumns` configures detail links, `toolbarLeading` / `toolbarActions` add content above the card, and `card` / `tableCell` customize records. Filters support `select`, `boolean`, `number`, `date`, `date-range` and `text`. Without `sortableColumns`, CrudPage shows no sort buttons; list pages must declare backend-supported fields.
435
+ >
436
+ > The page fills available parent height. Tables fill remaining space even without data; only the data area scrolls, with headers fixed at its top and pagination fixed at the list card bottom.
437
+ > Pass remaining height through every host container, for example with `flex flex-1 min-h-0 flex-col`, from the viewport shell to the content area. Intermediate wrappers must not size only to their content. Pagination stays at the bottom for empty, short and scrolling lists.
438
+ >
439
+ > Columns first shrink to 7rem and truncate long text; horizontal scrolling appears only if total width still exceeds the container. The action column stays fixed on the right.
440
+
441
+ ##### Error pages (1)
442
+
443
+ | Component | Description | Key props / capabilities |
444
+ | ----------- | --------------------------------------------------- | ----------------------------------------------------------------------- |
445
+ | `ErrorPage` | Generic error page with 401/403/404/500/503 presets | `status`, `code`, `title`, `description`, `homeUrl`, `onhome`, `onback` |
446
+
447
+ > `CrudPage` uses `form` to configure create/edit presentation: Without `sortableColumns`, CrudPage shows no sort buttons; list pages must declare backend-supported fields.
448
+ >
449
+ > - `form.variant`: `'drawer'` (default) or `'modal'`.
450
+ > - Drawer: `form.drawerSize` selects a preset; `form.drawerWidth` accepts any CSS width and takes precedence. The left edge is resizable by default and remembered per resource; disable with `form.drawerResizable=false`.
451
+ > - Modal: `form.modalSize` selects a preset; `form.modalWidth` / `form.modalHeight` accept CSS sizes.
452
+ >
453
+ > `pagination` configures the always-visible pagination bar. `showSizeChanger`, `pageSizeOptions`, `showJumper`, and `showTotal` are on by default. For compact views, disable page text with `showPageInfo` and first/last buttons with `showFirstLast`.
454
+ >
455
+ > `density` is `'normal'` (default) or `'compact'`. It affects list rows/actions, pagination, and create/edit/detail forms, not headers or filters.
456
+ >
457
+ > Controlled loading: `loading` / `loaded` / `error` / `onRetry` / `keepPreviousData`. Empty state appears only when `loaded && total === 0`, avoiding false empty results before the first response. Initial queries show loading; failures without usable data show errors/retry (`onRetry`). `keepPreviousData` (default true) retains old data during refresh/failure.
458
+ >
459
+ > Pure clients without SvelteKit SSR can use framework `defineCrud` + `createCrudController` to manage `data` and `nav`, with latest-wins (seq + AbortSignal), old-data retention on failure, lazy loading, and concurrent deduplication:
460
+ >
461
+ > ```svelte
462
+ > <script>
463
+ > import { CrudPage, createCrudController, defineCrud } from '@h-ai/ui'
464
+ > const crud = defineCrud({ name: 'user', label: '用户', fields: [/* ... */], api: { list: params => listUsers(params) } })
465
+ > const c = createCrudController(crud) // 惰性页签传 { autoLoad: false },首次激活时 c.load()
466
+ > </script>
467
+ > <CrudPage {crud} data={c.data} nav={c.nav} loading={c.loading} loaded={c.loaded} error={c.error} onRetry={c.reload} />
468
+ > ```
469
+ >
470
+ > `Tabs` supports lazy content. With `lazy`, never-activated panes are not rendered (`children` receives `isActivated(key)`); `onactivate(key)` runs once on first activation. Combine with `createCrudController({ autoLoad: false })` to load only when first visible.
471
+
472
+ ### Examples
473
+
474
+ #### Toast notifications
475
+
476
+ ```svelte
477
+ <script>
478
+ import { toast, ToastContainer } from '@h-ai/ui'
479
+
480
+ function notify() {
481
+ toast.success('操作成功')
482
+ toast.error('操作失败')
483
+ toast.warning('请注意')
484
+ toast.info('提示信息', 5000) // 自定义持续时间
485
+ }
486
+ </script>
487
+
488
+ <button onclick={notify}>通知</button>
489
+ <ToastContainer />
490
+ ```
491
+
492
+ Toasts float at the bottom right by default without shifting layout, using UI-owned semantic colors for information, success, warning and error, with a soft tinted background, a narrow color border, a distinct icon and a subtle shadow. They can be dismissed manually. Notifications share one FIFO queue and appear one at a time; each timer starts when its notification is shown (3 seconds by default, `duration: 0` waits for dismissal). Mount `<ToastContainer />` once in the root layout. Set a position with `toast.add({ message: m.saved(), variant: 'success', position: 'bottom-center' })`, where `m.saved()` is an application translation. Positions: `bottom-right` (default), `top-right`, `bottom-center`, `top-center`, `bottom-left`, `top-left`. Use Toast for login, password changes, saves, deletes and uploads, including failures. All warnings and errors, including field validation, use ToastContainer. Fields retain invalid markers and accessible descriptions; persistent status and recovery actions remain in place. `Alert` only accepts info/success.
493
+
494
+ Press F8 to focus the current notification and F8 again to return. Escape dismisses a dismissible notification and restores focus; Enter activates its dismiss button. This also works inside Modal without closing the dialog. Non-dismissible notifications can be focused for reading and exited with F8; automatic dismissal restores focus too.
495
+
496
+ > Built-in `notifySuccess` / `notifyError` / `notifyInfo` / `notifyWarning` remove the need for application wrappers. `notifyError(err, fallback?)` hides an ordinary Error's internal message, displays a fallback and preserves traceId. String arguments must be safe localized messages; do not pass an unknown `err.message`. Success lasts 3s and errors 5s by default.
497
+
498
+ When a Promise-based component requires an exception, preserve the complete failure with `throw new Error(result.error.message, { cause: result.error })`. `errorMessage` / `notifyError` follow the bounded, cycle-safe Error.cause chain to recover a safe business message and traceId. Server errors and unknown exceptions still use a safe fallback; internal exception text is not displayed.
499
+
500
+ Reactive components can call `useToastFeedback(() => error)` during initialization with safe localized messages. Queued duplicates of the same type are merged; notifications survive component unmount. Updating or clearing a source replaces or removes its previous notification; duplicate matching also includes traceId. The `message` API shares this queue, style and dismissal behavior. `MessageContainer` renders `ToastContainer`; choose one container in the root layout.
501
+
502
+ State modules can import `toast`, `useToastFeedback`, `notifySuccess` / `notifyError` / `notifyInfo` / `notifyWarning` and `errorMessage` from the lightweight `@h-ai/ui/toast` entry without loading components or tour CSS. Import `ToastContainer` from a component entry and mount it in the root layout.
503
+
504
+ The traceId is hidden by default. Use `toast.add({ message: m.retry(), variant: 'warning', traceId })`; existing safe messages containing `(traceId: …)` are separated automatically. The diagnostic icon reveals an issue reference ID, a copy action, and guidance to provide it to customer support or the development team. If copying fails, the ID can be selected manually. Hovering, focusing or expanding pauses the timer; closing the details and leaving resumes the remaining time. `toast.pause(id)` / `toast.resume(id)` are also available. Migrate warning/error Alert components to Toast; field errors retain aria-invalid and accessible descriptions, with recovery actions in place.
505
+
506
+ #### Choosing a Toast position
507
+
508
+ The application provides the `m.saved()` translation below. Notifications at different positions still share one queue and appear in order.
509
+
510
+ ```ts
511
+ import { toast } from '@h-ai/ui/toast'
512
+
513
+ toast.add({ message: m.saved(), variant: 'success', position: 'top-right' })
514
+ toast.add({ message: m.saved(), position: 'bottom-center' })
515
+ ```
516
+
517
+ #### Typical CRUD page
518
+
519
+ ```svelte
520
+ <script>
521
+ import {
522
+ PageHeader, Card, DataTable, Button,
523
+ Modal, Input, Select, toast, ToastContainer,
524
+ } from '@h-ai/ui'
525
+
526
+ let items = $state([])
527
+ let showModal = $state(false)
528
+ let loading = $state(false)
529
+ let formData = $state({ name: '', type: '' })
530
+
531
+ const columns = [
532
+ { key: 'name', label: '名称' },
533
+ { key: 'type', label: '类型' },
534
+ { key: 'createdAt', label: '创建时间' },
535
+ ]
536
+
537
+ async function handleCreate() {
538
+ loading = true
539
+ try {
540
+ await fetch('/api/items', { method: 'POST', body: JSON.stringify(formData) })
541
+ showModal = false
542
+ toast.success('创建成功')
543
+ } finally {
544
+ loading = false
545
+ }
546
+ }
547
+ </script>
548
+
549
+ <PageHeader title="项目管理" description="管理所有项目">
550
+ {#snippet actions()}
551
+ <Button onclick={() => showModal = true}>新建</Button>
552
+ {/snippet}
553
+ </PageHeader>
554
+
555
+ <Card>
556
+ <DataTable data={items} {columns} keyField="id" {loading}>
557
+ {#snippet actions(item)}
558
+ <Button size="xs">编辑</Button>
559
+ <Button size="xs" variant="error">删除</Button>
560
+ {/snippet}
561
+ </DataTable>
562
+ </Card>
563
+
564
+ <Modal bind:open={showModal} title="新建项目">
565
+ <form onsubmit={(e) => { e.preventDefault(); handleCreate() }} class="space-y-4">
566
+ <Input placeholder="名称" bind:value={formData.name} required />
567
+ <Select
568
+ placeholder="选择类型"
569
+ bind:value={formData.type}
570
+ options={[
571
+ { value: 'a', label: '类型 A' },
572
+ { value: 'b', label: '类型 B' },
573
+ ]}
574
+ />
575
+ </form>
576
+ {#snippet footer()}
577
+ <Button variant="ghost" onclick={() => showModal = false}>取消</Button>
578
+ <Button {loading} onclick={handleCreate}>创建</Button>
579
+ {/snippet}
580
+ </Modal>
581
+
582
+ <ToastContainer />
583
+ ```
584
+
585
+ `Modal` retains the top-right close button without a `title` / `header`, but does not render a full header row. Use `radius="1.4rem"` for rounded corners and `bodyOverflow="visible"` when internal dropdowns/overlays need to extend outside.
586
+
587
+ #### Declarative CRUD page (CrudPage)
588
+
589
+ ```svelte
590
+ <script lang='ts'>
591
+ import { createSvelteKitNavAdapter } from '@h-ai/kit/client'
592
+ import { CrudPage } from '@h-ai/ui'
593
+
594
+ let { data } = $props()
595
+ const nav = createSvelteKitNavAdapter()
596
+ </script>
597
+
598
+ <CrudPage
599
+ crud={roleCrud}
600
+ {data}
601
+ permissions={{ create: true, update: true, delete: true }}
602
+ form={{ variant: 'modal', modalSize: '3xl', columns: 2, labelPosition: 'top' }}
603
+ pagination={{ showSizeChanger: true, showJumper: true, pageSizeOptions: [10, 20, 50] }}
604
+ density='compact'
605
+ detailColumns={['name']}
606
+ sortableColumns={[{ key: 'createdAt', label: '创建时间' }]}
607
+ {nav}
608
+ />
609
+ ```
610
+
611
+ > Use `form={{ variant: 'drawer', drawerWidth: '40rem' }}` for drawers. User resizing overrides the initial width and is remembered per resource.
612
+
613
+ #### Login page
614
+
615
+ ```svelte
616
+ <script>
617
+ import { LoginForm } from '@h-ai/ui'
618
+
619
+ let loading = $state(false)
620
+ let errors = $state({})
621
+
622
+ async function handleLogin(data) {
623
+ loading = true
624
+ errors = {}
625
+ try {
626
+ await fetch('/api/login', { method: 'POST', body: JSON.stringify(data) })
627
+ } catch {
628
+ errors = { general: '登录失败,请检查用户名和密码' }
629
+ } finally {
630
+ loading = false
631
+ }
632
+ }
633
+ </script>
634
+
635
+ <!-- 场景组件内置 i18n,无需传入翻译 props -->
636
+ <LoginForm {loading} {errors} onsubmit={handleLogin} showRegisterLink />
637
+ ```
638
+
639
+ #### Controlled PasswordInput
640
+
641
+ ```svelte
642
+ <script>
643
+ import { PasswordInput } from '@h-ai/ui'
644
+
645
+ let password = $state('')
646
+ </script>
647
+
648
+ <PasswordInput
649
+ value={password}
650
+ oninput={(e) => { password = e.currentTarget.value }}
651
+ placeholder="请输入密码"
652
+ showStrength
653
+ />
654
+ ```
655
+
656
+ ### Feedback capture and delivery checks
657
+
658
+ Feedback `evidence` shows sanitized material contents. `oncapture(id?)` hides the modal for navigation and adds or replaces a screenshot. With `onfileschange`, native silent screen recording produces a previewable, removable WebM/MP4 attachment (up to 60 seconds / 5 MiB; video is not automatically masked). `FeedbackDetail.onreplay` loads complete page events on demand for playback and seeking; logs and environment remain paginated.
659
+
660
+ Feedback materials scroll independently while action buttons remain visible, so expanded content never crosses the action bar. `FeedbackList` retains an accessible name; its host provides the page heading to avoid duplicate titles.
661
+
662
+ ### Style dependencies
663
+
664
+ Components use TailwindCSS v4 + DaisyUI. Configure application `app.css` as follows:
665
+
666
+ ```css
667
+ /* 必须 */
668
+ @import 'tailwindcss';
669
+ @import '@h-ai/ui/styles/global.css'; /* 基础重置、滚动条、焦点样式 */
670
+ @import '@h-ai/ui/styles/theme.css'; /* Tailwind v4 @theme Token(品牌色/阴影/动效) */
671
+ @source "../node_modules/@h-ai/ui/dist/**/*.{svelte,js,ts}";
672
+ @source "../../../node_modules/@h-ai/ui/dist/**/*.{svelte,js,ts}";
673
+
674
+ /* 移动端项目追加(可选) */
675
+ @import '@h-ai/ui/styles/design-tokens.css'; /* CSS 自定义属性 */
676
+ @import '@h-ai/ui/styles/mobile.css'; /* 安全区域/触摸优化 */
677
+
678
+ /* DaisyUI 主题 */
679
+ @plugin "daisyui" {
680
+ themes: light --default, dark --prefersdark, cupcake, emerald, corporate, nord, dracula, night;
681
+ }
682
+ ```
683
+
684
+ - `global.css`: base HTML reset, scrollbars, and form focus rings.
685
+ - `theme.css`: Tailwind v4 `@theme` with brand colors, shadows, animation curves, and font features.
686
+ - `design-tokens.css`: spacing/radius/z-index/transition custom properties; recommended for mobile.
687
+ - `mobile.css`: safe-area padding, momentum scrolling, keyboard adaptation, and mobile shells (`hai-mobile-viewport` / `hai-mobile-shell` / `hai-mobile-main`).
688
+
689
+ On mobile pages, match `BottomNav` width to the page shell to avoid spanning the entire desktop preview viewport:
690
+
691
+ ```svelte
692
+ <div class="hai-mobile-viewport">
693
+ <div class="hai-mobile-shell max-w-lg">
694
+ <AppBar title="Home" fixed={false} safeArea />
695
+ <main class="hai-mobile-main">...</main>
696
+ <BottomNav items={items} active="home" centered maxWidth="lg" safeArea />
697
+ </div>
698
+ </div>
699
+ ```
700
+
701
+ #### Icons
702
+
703
+ Components use Iconify (Tabler Icons):
704
+
705
+ ```bash
706
+ npm install -D @iconify/tailwind4 @iconify-json/tabler
707
+ ```
708
+
709
+ ```css
710
+ /* app.css 中追加 */
711
+ @plugin "@iconify/tailwind4" {
712
+ prefixes: tabler;
713
+ }
714
+ ```
715
+
716
+ #### Theme switching
717
+
718
+ Manage 15 curated DaisyUI themes plus high contrast and square business themes through built-in utilities:
719
+
720
+ `high-contrast` ships in shared theme.css with bright text on dark surfaces, clear borders/focus, and stronger muted text/placeholders. ThemeSelector has localized labels; examples and default generated projects offer it. Explicit fullstack themes lists remain host controlled. Palette checks target 7:1 for normal text; arbitrary application content still needs accessibility review.
721
+
722
+ `formal` provides square corners for business buttons, fields, cards and dialogs, with localized labels in examples and default templates. Button submitHint displays the native Enter action only for type=submit; it adds no global shortcut. LoginForm focuses its identifier on desktop when ready and no element has focus; autoFocus=false opts out. Search Enter submits immediately while respecting IME composition. Theme choices support arrows/Home/End, Enter/Space and Escape focus restoration. Confirmation dialogs initially focus Cancel and synchronize Escape cancellation.
723
+
724
+ ```ts
725
+ import {
726
+ applyTheme, // 应用主题(自动持久化到 localStorage)
727
+ createThemeBootstrapScript, // 生成可注入 app.html 的首屏主题恢复脚本
728
+ getCurrentTheme, // 获取当前主题
729
+ getSavedTheme, // Read saved appearance, with an optional application default
730
+ getThemeInitScript, // 返回可注入到 HTML shell 的防闪烁脚本文本
731
+ isDarkTheme, // 检查是否暗色主题
732
+ normalizeHexColor, // 归一化 #RGB / #RRGGBB 主题色
733
+ normalizeThemeId, // 校验主题 ID 并自动回退
734
+ THEME_GROUPS, // 按亮色/暗色分组
735
+ THEMES, // ThemeInfo[] — 17 个主题元数据
736
+ } from '@h-ai/ui/theme'
737
+ ```
738
+
739
+ Use `getThemeInitScript()` for simple cases. For custom storage keys, theme color CSS variables, or language preferences, generate `createThemeBootstrapScript()` on the server and inject it into `app.html`.
740
+
741
+ Place a placeholder in SvelteKit `app.html`:
742
+
743
+ ```html
744
+ <head>
745
+ <script>%theme_bootstrap%</script>
746
+ </head>
747
+ ```
748
+
749
+ Then inject it from `hooks.server.ts`:
750
+
751
+ ```ts
752
+ import { createThemeBootstrapScript, DEFAULT_THEME_COLOR_CSS_VAR } from '@h-ai/ui/theme'
753
+
754
+ const themeBootstrapScript = createThemeBootstrapScript({
755
+ storageKey: 'hai-demo-preferences',
756
+ legacyThemeStorageKey: 'hai-demo-theme',
757
+ defaultThemeColor: '#5765f0',
758
+ colorCssVar: DEFAULT_THEME_COLOR_CSS_VAR,
759
+ })
760
+
761
+ transformPageChunk: ({ html }) => html.replace('%theme_bootstrap%', themeBootstrapScript)
762
+ ```
763
+
764
+ ### Internationalization (i18n)
765
+
766
+ @h-ai/ui uses **built-in component translations**:
767
+
768
+ - Scene components (`scenes/`) include Chinese/English/Japanese translations (zh-CN / en-US / ja-JP) out of the box.
769
+ - Components respond automatically to global locale changes, synchronized through `@h-ai/core`.
770
+ - Applications handle **page text** only; @h-ai/ui manages internal component text.
771
+ - Override specific text with props such as `submitText` or `labels`.
772
+
773
+ #### createLocaleStore
774
+
775
+ Client locale state management, automatically synchronized with the `@h-ai/core` global locale manager:
776
+
777
+ ```svelte
778
+ <script>
779
+ import { createLocaleStore, setGlobalLocale } from '@h-ai/ui/i18n'
780
+ import { setLocale } from '$lib/paraglide/runtime'
781
+
782
+ const localeStore = createLocaleStore()
783
+
784
+ function changeLocale(code) {
785
+ localeStore.set(code) // 更新 UI store + 同步到 @h-ai/core
786
+ setLocale(code) // 同步到 Paraglide(应用层)
787
+ }
788
+ </script>
789
+
790
+ <select value={localeStore.current} onchange={(e) => changeLocale(e.currentTarget.value)}>
791
+ {#each localeStore.supported as l}
792
+ <option value={l.code}>{l.label}</option>
793
+ {/each}
794
+ </select>
795
+ ```
796
+
797
+ `createLocaleStore` from `@h-ai/ui/i18n` selects a resolvable saved locale, then the complete navigator.languages list (followed by navigator.language), then defaultLocale and the first supported entry. An unsupported candidate never triggers an early default. Matching handles case, language shorthand and progressively less specific region/script tags, returning the configured code. Same-language variants follow supportedLocales order. detectBrowserLocale returns null without an actual match; an empty supported list ultimately keeps the caller default. SSR neither reads browser candidates nor changes global locale. Paraglide applications must still synchronize their own setLocale; custom store entries do not add built-in UI dictionaries.
798
+
799
+ #### Exported i18n utilities
800
+
801
+ ```ts
802
+ import {
803
+ createLocaleStore, // Svelte 响应式 locale store
804
+ DEFAULT_LOCALE, // 默认 locale: 'zh-CN'
805
+ DEFAULT_LOCALES, // 支持的 locale 列表
806
+ detectBrowserLocale, // 检测浏览器语言
807
+ getGlobalLocale, // 获取当前全局 locale
808
+ interpolate, // 字符串插值(如 "Hello {name}")
809
+ isLocaleSupported, // 检查 locale 是否支持
810
+ resolveLocale, // 解析 locale(支持回退)
811
+ setGlobalLocale, // 设置全局 locale(同步 @h-ai/core)
812
+ } from '@h-ai/ui/i18n'
813
+ ```
814
+
815
+ ### Configuration driven authentication
816
+
817
+ State modules can import `authErrorMessage` from the lightweight `@h-ai/ui/i18n` entry without loading scene components. Admin profile password changes, mobile/desktop examples and generated templates share these messages.
818
+
819
+ Password login submits only `identifier` and `password`; `AuthPanel` maps the `LoginForm` field `username` to `identifier`. Server settings `session.maxAge` / `session.refreshTokenMaxAge` control session lifetimes. The login form has no per-login persistent-session option.
820
+
821
+ Agreement content can be configured as `agreements.userAgreementMarkdown` and `privacyPolicyMarkdown` using YAML `|`. The modal safely renders configured Markdown and prefers it over the URL of the same agreement. URL-only content stays in a sandboxed iframe.
822
+
823
+ ```yaml
824
+ agreements:
825
+ showOnRegister: true
826
+ showOnLogin: false
827
+ userAgreementMarkdown: |
828
+ # 用户协议
829
+
830
+ **账户使用条款**
831
+
832
+ - 请妥善保管账户凭据。
833
+ privacyPolicyMarkdown: |
834
+ # 隐私政策
835
+
836
+ 注册资料用于账户管理,会话信息用于身份认证。
837
+ # 可选 URL;同主题同时配置 Markdown 和 URL 时,弹窗优先显示 Markdown。
838
+ # userAgreementUrl: https://example.com/terms
839
+ # privacyPolicyUrl: https://example.com/privacy
840
+ ```
841
+
842
+
843
+
844
+ AuthPanel accepts public IAM config and actions for password/LDAP/email/SMS login, registration and recovery. config.ui supplies layout, branding and images. LoginForm supports methods, onsendotp, otpLength and resendInterval; password forms accept passwordPolicy. Network and token storage remain in actions.
845
+
846
+ Use `authErrorMessage(error)` from `@h-ai/ui/components/scenes/iam/index` for authentication failures. It maps public codes to the current UI language, combines username/password failures, hides raw unknown/server errors and preserves a valid `traceId`. AuthPanel, OTP sending, sensitive confirmation and fullstack password changes share this mapping. Initial/expired passwords, reuse of the current password (`hai:iam:034`) and session limits have actionable messages. Authentication errors and successful operations use the unified Toast. Password confirmation compares exact strings without Unicode normalization or trimming and reports mismatches through Toast while retaining field associations.
847
+
848
+ AuthPanel disables native form controls during SSR and enables input after client mount binds events, preventing early input from being lost during hydration. Applications need no extra readiness code. E2E tests wait for editable controls and cover delayed client scripts.
849
+
850
+ When an authentication link points to the current complete URL, AuthPanel switches scenes without navigating again, so input entered after returning to login is preserved. Links with a different path, query, or hash use application routing. Modified clicks such as Ctrl/Cmd retain browser behavior.
851
+
852
+ `createSensitiveActions` can refresh database rules before an action through standard `actions.publicConfig()`. `SensitiveOperationsForm` shares line-based input, deduplication, validation and errors. Pass `operations`, async `onsubmit(operations)` returning HaiResult, and optional `ondone` for successful saves. Clearing database additions does not remove file rules.
853
+
854
+ Use `createSessionRecovery()` with `SessionRecoveryDialog` for expired sessions. Configure it with the public config and original `{ id, username }`, pass `recovery.recover` as Kit/API client's `recoverSession`, and give the dialog the same controller and standard actions. Call `cancel()` on teardown. The UI stores no passwords or business requests. `expectedUserId` restricts server session issuance to the original principal; captcha, lockout, access and password-renewal policies remain active. Cancellation preserves input and stops continuation; ambiguous network writes are never replayed. Reloaded/closed documents cannot recover lost in-memory drafts.
855
+
856
+ `createSensitiveActions(actions)` accepts Kit/API client authentication actions and shares confirmation, cancellation, retry, duplicate-submit and late-response handling. Create one per application root layout, update it with `configure(publicPolicy)`, and call `cancel()` on teardown. `authorize(operation)` returns undefined when confirmation is unnecessary, null when cancelled/busy, or the proof for that action. Do not send the business request on cancellation; pass a proof only to its intended request, never to global headers or persistent storage. Bind `ReauthenticationDialog` to the controller’s `open/loading/error/submit/cancel`; confirmation grants no permissions. `Input` supports `datetime-local`: convert its browser-local value to an explicit timestamp in the service layer.
857
+
858
+ ```svelte
859
+ <!-- actions comes from Kit/API client; policy is the public IAM reauthentication policy. -->
860
+ <script lang='ts'>
861
+ import type { SensitiveActionsOptions } from '@h-ai/ui'
862
+ import { createSensitiveActions, ReauthenticationDialog } from '@h-ai/ui'
863
+
864
+ const { actions, policy }: { actions: SensitiveActionsOptions, policy: { enabled: boolean, operations: string[] } } = $props()
865
+ const confirmation = createSensitiveActions(actions)
866
+ $effect(() => {
867
+ confirmation.configure(policy)
868
+ return () => confirmation.cancel()
869
+ })
870
+ // Await confirmation.authorize(operation) in the business action; stop on null.
871
+ </script>
872
+ <ReauthenticationDialog
873
+ open={confirmation.open}
874
+ loading={confirmation.loading}
875
+ error={confirmation.error}
876
+ onsubmit={password => confirmation.submit(password)}
877
+ onclose={() => confirmation.cancel()}
878
+ />
879
+ ```
880
+
881
+ [完整 IAM 配置 / IAM configuration](../iam/README.en.md)
882
+
883
+ ### Onboarding and help center
884
+
885
+ Import `createGuide`, `GuideHost` and `HelpCenter` from `@h-ai/ui/guide`. No init/close is required. The tour engine loads when a tour starts; controls follow the current theme and include Chinese/English/Japanese translations. Business text uses application i18n callbacks.
886
+
887
+ The same entry exports `resolveGuideText(text?)` to evaluate strings or i18n callbacks; host components resolve text automatically.
888
+
889
+ Create the controller inside a layout component, register tours with id/title/steps and optional route/version, then mount `<GuideHost {guide} {locale} scope={user.id} autoStart='overview' />`. Add `data-guide` to existing target components. Supply the application's NavAdapter for SPA navigation.
890
+
891
+ ```svelte
892
+ <script lang='ts'>
893
+ import { createGuide, GuideHost } from '@h-ai/ui/guide'
894
+
895
+ const guide = createGuide({
896
+ nav,
897
+ persistKey: 'my-app-guide',
898
+ tours: [{
899
+ id: 'users',
900
+ version: 1,
901
+ route: '/users',
902
+ title: () => m.guide_users_title(),
903
+ description: () => m.guide_users_description(),
904
+ steps: [{
905
+ target: 'users-create',
906
+ title: () => m.guide_create_title(),
907
+ description: () => m.guide_create_description(),
908
+ }],
909
+ }],
910
+ articles: [{
911
+ id: 'users-help',
912
+ title: () => m.guide_users_title(),
913
+ content: () => m.guide_users_markdown(),
914
+ tourId: 'users',
915
+ }],
916
+ })
917
+ </script>
918
+
919
+ <GuideHost {guide} {locale} scope={user.id} autoStart='users' />
920
+ <Button onclick={() => guide.openHelp()}>{m.help()}</Button>
921
+ <!-- 在目标页面为现有按钮添加锚点,无需额外包装。 -->
922
+ <Button data-guide='users-create' onclick={createUser}>{m.create_user()}</Button>
923
+ ```
924
+
925
+ `start(id)` returns Promise<boolean> and always allows replay; failure returns false and sets error. `startIfNeeded(id)` returns boolean and offers a first-use invitation. `openHelp(articleId?)` opens searchable Markdown help; `stop()` cancels without marking completion; `reset(id)` clears the current user's preference.
926
+
927
+ The close button, Escape, and overlay clicks cancel pending highlighting and clear `busy` even before the first positioning frame completes. A pending `start()` resolves to false without recording completion.
928
+
929
+ Persistence supports cookie (default), localStorage and memory, with an in-instance fallback when storage is restricted. Preferences are isolated by user and version. Later delays reminders for one day; Cookie preferences expire after one year. The default full-page navigation uses a short-lived sessionStorage record to start on the destination page.
930
+
931
+ Use `() => m.key()` for localized content and pass the current locale. Steps render as plain text; help uses the existing safe Markdown renderer with raw HTML disabled. Targets wait up to 3000ms by default; before(signal) prepares tabs or drawers, optional skips nonessential missing targets, and missing required targets stop the tour. Unmounting cancels pending work. Never share controllers across SSR users.
932
+
933
+ HelpCenter can also render a standalone page using articles, optional tours, locale, selectedId and onstart. The admin-console example and CLI fullstack Web/App/Desktop include first-use invitations, help and profile tours by default. See the [complete integration guide](../cli/templates/skills/hai-ui/guide.md).
934
+
935
+ ### Other exports
936
+
937
+ ```ts
938
+ // 类型
939
+ import type { ButtonProps, InputProps, ModalProps } from '@h-ai/ui'
940
+ ```
941
+
942
+ ```ts
943
+ // 样式工具
944
+ import { cn, generateId, getSizeClass, getVariantClass } from '@h-ai/ui'
945
+ ```
946
+
947
+ ```ts
948
+ // Toast 单例
949
+ import { toast } from '@h-ai/ui'
950
+ ```
951
+
952
+ Agreements open in a Modal and preserve form input. Pages must allow iframe embedding; scripts are disabled and a new-window fallback is provided. LoginForm/RegisterForm expose `header/extraFields/footer`. AuthPanel forwards `loginHeader/loginFields/loginFooter` and `registerHeader/registerFields/registerFooter` while preserving navigation. Bind additional fields to application state and handle them in custom actions; they are not automatically sent to IAM. Use `type="button"` for extension buttons.
953
+
954
+ ```svelte
955
+ <!-- config 来自 IAM 公开配置,actions 来自 Kit/API client;m 为应用翻译。 -->
956
+ <AuthPanel {config} {actions}>
957
+ {#snippet loginHeader()}
958
+ <p>{m.loginHelp()}</p>
959
+ {/snippet}
960
+ {#snippet registerFields()}
961
+ <label><input type='checkbox' bind:checked={subscribe} />{m.subscribe()}</label>
962
+ {/snippet}
963
+ </AuthPanel>
964
+ ```
965
+
966
+
967
+ Component subpaths expose only explicit barrels in package.exports, such as `@h-ai/ui/components/primitives/index`. Component internals and storage helpers stay private; host clipboard registration remains public.
968
+
969
+ ### Request locale isolation
970
+
971
+ Wrap Node requests and SSR in `core.i18n.runWithLocale(locale, () => handleRequest())`. SvelteKit can use `kit.i18n.runWithLocale(locale, () => resolve(event))`; serv creates the scope automatically from request headers. Async descendants inherit it. Explicit `MessageOptions.locale` takes precedence over the request locale and the startup default. Within a scope, `setGlobalLocale` only changes that request; outside a scope it configures the startup default and must not be called by request hooks.
972
+
973
+ Browsers keep application-level `setGlobalLocale` / `createLocaleStore`. During SSR, UI store initialization and setters only update the store; messages read the request scope. `runWithLocale` requires the Node entry; browser translations use explicit locale options or application state.
974
+
975
+ ## Input limits and HTTP capabilities
976
+
977
+ Object keys are limited to 1024 UTF-8 bytes and reject absolute paths, backslashes, control characters and dot segments. Each public HTTP batch delete accepts 1–1000 entries. `@h-ai/storage/schemas` exposes the shared browser-safe rules. Presign expiry is an integer from 1 to 604800 seconds (Node default 3600, HTTP default 900). Upload signing accepts only key/contentType/expiresIn; contentLength/maxSize/metadata/checksum are unsupported. Invalid input returns HTTP 400 and the typed client maps it to VALIDATION_FAILED. FileUpload limits guide file selection; applications must validate actual objects on the server. Node streaming/checksum/conditional-write options have no default HTTP endpoints. See the [capability and authorization matrix (Chinese)](../storage/README.md#存储输入约束与跨端能力).
978
+
979
+ ## Compact workspaces and collapsible filters
980
+
981
+ `WorkspaceLayout` shares a compact navigation header, a content area with 12/16px padding and an optional footer. An omitted footer reserves no space. title is the page title in navigation; leading/actions/footer are snippets. data-* attributes reach the content main. The host must pass down available height and min-height: 0.
982
+
983
+ A matching `PageHeader` omits the repeated title and retains its description and actions; `SettingsLayout` shares this behavior. Inside a workspace, `CrudPage` defaults to one navigation title and keeps actions in its toolbar. Standalone usage retains its title; showHeader explicitly overrides the default.
984
+
985
+ `FilterBar` keeps leading and actions visible, with children collapsed by default. bind:expanded controls disclosure, activeCount reports active conditions, and onreset supplies the built-in localized reset button. Collapsing preserves controls and values. The host resets state and performs queries. `TableToolbar` reuses this layout with a native query form; `CrudFilterBar` shares its implementation. `onsearch` submits the current bound search and filter drafts; `onfilterchange` only reports draft changes. `onreset` (`onclearfilters` on TableToolbar) must clear applied host conditions and query again. The old `toolbarStyle`, sorting popup and TableToolbar sorting props were removed; use DataTable `sortKey`, `sortDir` and `onsort`. Expanded filters adapt to 1/2/4/6 columns with 20px horizontal and 16px vertical gaps, aligned labels and equal control heights. Date ranges span two columns or the full row on narrow screens.
986
+
987
+ In this example, m, statusOptions, clearFilters and loadRows belong to the host application. The reset callback must clear search and all conditions.
988
+
989
+ ```svelte
990
+ <script lang="ts">
991
+ import { Button, FilterBar, Input, Select, WorkspaceLayout } from '@h-ai/ui'
992
+ let search = $state('')
993
+ let status = $state('')
994
+ </script>
995
+
996
+ <div class="flex h-dvh min-h-0">
997
+ <WorkspaceLayout title={m.page_title()}>
998
+ <FilterBar activeCount={status ? 1 : 0} onreset={clearFilters}>
999
+ {#snippet leading()}<Input size="sm" bind:value={search} placeholder={m.search()} />{/snippet}
1000
+ {#snippet actions()}<Button size="sm" onclick={loadRows}>{m.search()}</Button>{/snippet}
1001
+ <div class="w-40"><Select size="sm" bind:value={status} options={statusOptions} /></div>
1002
+ </FilterBar>
1003
+ </WorkspaceLayout>
1004
+ </div>
1005
+ ```
1006
+
1007
+ ## Design and interaction acceptance
1008
+
1009
+ Use [hai-ui-design](../cli/templates/skills/hai-ui-design/SKILL.md) for page decisions, [hai-ui](../cli/templates/skills/hai-ui/SKILL.md) for implementation, and [hai-ui-review](../cli/templates/skills/hai-ui-review/SKILL.md) for rendered UI review. See the [shared design guidance](../../.agents/instructions/ui-design.md).
1010
+
1011
+ Tabs support arrow/Home/End navigation, disabled items and one Tab stop. Tables expose sort/loading state and keyboard row activation. Pagination labels follow locale and external page changes update the jump input. Expanded filters follow document focus order and view buttons expose selection. Empty/Alert wrap long content. theme.css imports shared tokens; focus follows the current theme and global.css respects reduced motion. Applications still implement filtering, sorting, paging and recovery.
1012
+
1013
+ ## Error messages and correlated logs
1014
+
1015
+ HTTP errors carry safe localized messages and a reference ID. ToastContainer shows only the readable message by default; its diagnostic icon reveals the ID and copy action. The same ID remains in `error.traceId` and `X-Trace-Id`. The framework reuses the request ID to correlate browser and server logs. Sanitized exceptions, stacks and operation context remain in logs; internal cause/ext are not exposed. Field validation returns localized field names and messages only.
1016
+
1017
+ Use `core.error.toPublic(error, traceId?)` at HTTP/UI boundaries and `core.error.formatMessage(error)` after translating messages; formatting is idempotent. Pass complete Error objects to logs instead of discarding their context. Database failures log driver codes, sanitized messages/stacks and table/column context; SQL text, bound values and connection credentials are excluded.
1018
+
1019
+ ## Optional interactive challenges
1020
+
1021
+ AuthPanel uses actions.createCaptcha to automatically create and asynchronously solve self-hosted ALTCHA when config.captcha.enabled, submitting one-use proofs for login/register/sendOtp/passwordReset/renewPassword. The solver is not loaded when disabled. createAuthActions supplies the action; custom actions must preserve captcha and missing actions fail closed. Proofs stay in request memory and are always verified/consumed on the server.
1022
+
1023
+ See policy, defaults and recovery boundaries in [IAM](../iam/README.en.md).
1024
+
1025
+ ## Development and testing
1026
+
1027
+ ```sh
1028
+ pnpm --filter @h-ai/ui typecheck
1029
+ pnpm --filter @h-ai/ui lint
1030
+ pnpm --filter @h-ai/ui build
1031
+ pnpm --filter @h-ai/ui test
1032
+ ```
1033
+
1034
+ ## License
1035
+
1036
+ Apache-2.0