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

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 (380) hide show
  1. package/README.en.md +1062 -0
  2. package/README.ja.md +1062 -0
  3. package/README.md +696 -119
  4. package/auto-import.d.ts +49 -0
  5. package/auto-import.js +51 -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 +397 -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 +300 -79
  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 +216 -0
  150. package/dist/components/scenes/ai/highlight.d.ts +37 -0
  151. package/dist/components/scenes/ai/highlight.js +177 -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 +85 -47
  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 +186 -0
  201. package/dist/components/scenes/charts/Chart.svelte.d.ts +24 -0
  202. package/dist/components/scenes/charts/ChartLoadError.svelte +13 -0
  203. package/dist/components/scenes/charts/ChartLoadError.svelte.d.ts +6 -0
  204. package/dist/components/scenes/charts/DashboardGrid.svelte +34 -0
  205. package/dist/components/scenes/charts/DashboardGrid.svelte.d.ts +15 -0
  206. package/dist/components/scenes/charts/MetricCard.svelte +52 -0
  207. package/dist/components/scenes/charts/MetricCard.svelte.d.ts +15 -0
  208. package/dist/components/scenes/charts/ReportCard.svelte +48 -0
  209. package/dist/components/scenes/charts/ReportCard.svelte.d.ts +15 -0
  210. package/dist/components/scenes/charts/chart-presets.d.ts +15 -0
  211. package/dist/components/scenes/charts/chart-presets.js +19 -0
  212. package/dist/components/scenes/charts/chart-theme.d.ts +47 -0
  213. package/dist/components/scenes/charts/chart-theme.js +68 -0
  214. package/dist/components/scenes/charts/chart-types.d.ts +164 -0
  215. package/dist/components/scenes/charts/chart-types.js +7 -0
  216. package/dist/components/scenes/charts/dashboard-types.d.ts +79 -0
  217. package/dist/components/scenes/charts/dashboard-types.js +1 -0
  218. package/dist/components/scenes/charts/index.d.ts +12 -0
  219. package/dist/components/scenes/charts/index.js +10 -0
  220. package/dist/components/scenes/charts/renderers/AreaChart.svelte +19 -0
  221. package/dist/components/scenes/charts/renderers/AreaChart.svelte.d.ts +6 -0
  222. package/dist/components/scenes/charts/renderers/BarChart.svelte +19 -0
  223. package/dist/components/scenes/charts/renderers/BarChart.svelte.d.ts +6 -0
  224. package/dist/components/scenes/charts/renderers/LineChart.svelte +625 -0
  225. package/dist/components/scenes/charts/renderers/LineChart.svelte.d.ts +33 -0
  226. package/dist/components/scenes/charts/renderers/PieChart.svelte +19 -0
  227. package/dist/components/scenes/charts/renderers/PieChart.svelte.d.ts +6 -0
  228. package/dist/components/scenes/charts/renderers/ScatterChart.svelte +19 -0
  229. package/dist/components/scenes/charts/renderers/ScatterChart.svelte.d.ts +6 -0
  230. package/dist/components/scenes/crud/CrudDeleteConfirm.svelte +29 -11
  231. package/dist/components/scenes/crud/CrudDeleteConfirm.svelte.d.ts +13 -1
  232. package/dist/components/scenes/crud/CrudDetailDrawer.svelte +77 -22
  233. package/dist/components/scenes/crud/CrudDetailDrawer.svelte.d.ts +19 -4
  234. package/dist/components/scenes/crud/CrudDetailPanel.svelte +242 -0
  235. package/dist/components/scenes/crud/CrudDetailPanel.svelte.d.ts +66 -0
  236. package/dist/components/scenes/crud/CrudEditPanel.svelte +365 -0
  237. package/dist/components/scenes/crud/CrudEditPanel.svelte.d.ts +48 -0
  238. package/dist/components/scenes/crud/CrudFilterBar.svelte +17 -85
  239. package/dist/components/scenes/crud/CrudFilterBar.svelte.d.ts +13 -25
  240. package/dist/components/scenes/crud/CrudPage.svelte +564 -185
  241. package/dist/components/scenes/crud/CrudPage.svelte.d.ts +137 -51
  242. package/dist/components/scenes/crud/crud-controller.svelte.d.ts +335 -0
  243. package/dist/components/scenes/crud/crud-controller.svelte.js +276 -0
  244. package/dist/components/scenes/crud/crud-form-validation.d.ts +16 -0
  245. package/dist/components/scenes/crud/crud-form-validation.js +51 -0
  246. package/dist/components/scenes/crud/crud-types.d.ts +136 -43
  247. package/dist/components/scenes/crud/index.d.ts +9 -3
  248. package/dist/components/scenes/crud/index.js +8 -3
  249. package/dist/components/scenes/crud/nav-adapter.d.ts +50 -0
  250. package/dist/components/scenes/crud/nav-adapter.js +39 -0
  251. package/dist/components/scenes/crypto/EncryptedInput.svelte +63 -28
  252. package/dist/components/scenes/crypto/EncryptedInput.svelte.d.ts +38 -3
  253. package/dist/components/scenes/crypto/HashDisplay.svelte +30 -22
  254. package/dist/components/scenes/crypto/HashDisplay.svelte.d.ts +24 -1
  255. package/dist/components/scenes/crypto/SignatureDisplay.svelte +41 -40
  256. package/dist/components/scenes/crypto/SignatureDisplay.svelte.d.ts +24 -1
  257. package/dist/components/scenes/error/ErrorPage.svelte +135 -0
  258. package/dist/components/scenes/error/ErrorPage.svelte.d.ts +50 -0
  259. package/dist/components/scenes/error/error-presets.d.ts +60 -0
  260. package/dist/components/scenes/error/error-presets.js +51 -0
  261. package/dist/components/scenes/error/index.d.ts +8 -0
  262. package/dist/components/scenes/error/index.js +8 -0
  263. package/dist/components/scenes/guide/GuideHost.svelte +56 -0
  264. package/dist/components/scenes/guide/GuideHost.svelte.d.ts +35 -0
  265. package/dist/components/scenes/guide/GuideHostContent.svelte +136 -0
  266. package/dist/components/scenes/guide/GuideHostContent.svelte.d.ts +43 -0
  267. package/dist/components/scenes/guide/HelpCenter.svelte +135 -0
  268. package/dist/components/scenes/guide/HelpCenter.svelte.d.ts +40 -0
  269. package/dist/components/scenes/guide/index.d.ts +2 -0
  270. package/dist/components/scenes/guide/index.js +2 -0
  271. package/dist/components/scenes/iam/AgreementNotice.svelte +48 -0
  272. package/dist/components/scenes/iam/AgreementNotice.svelte.d.ts +7 -0
  273. package/dist/components/scenes/iam/AuthPanel.svelte +226 -0
  274. package/dist/components/scenes/iam/AuthPanel.svelte.d.ts +29 -0
  275. package/dist/components/scenes/iam/AuthShell.svelte +160 -0
  276. package/dist/components/scenes/iam/AuthShell.svelte.d.ts +56 -0
  277. package/dist/components/scenes/iam/ChangePasswordForm.svelte +84 -63
  278. package/dist/components/scenes/iam/ChangePasswordForm.svelte.d.ts +13 -1
  279. package/dist/components/scenes/iam/ForgotPasswordForm.svelte +113 -89
  280. package/dist/components/scenes/iam/ForgotPasswordForm.svelte.d.ts +24 -1
  281. package/dist/components/scenes/iam/LoginForm.svelte +215 -117
  282. package/dist/components/scenes/iam/LoginForm.svelte.d.ts +13 -1
  283. package/dist/components/scenes/iam/PasswordInput.svelte +79 -32
  284. package/dist/components/scenes/iam/PasswordInput.svelte.d.ts +30 -4
  285. package/dist/components/scenes/iam/PermGuard.svelte +21 -11
  286. package/dist/components/scenes/iam/PermGuard.svelte.d.ts +30 -0
  287. package/dist/components/scenes/iam/ReauthenticationDialog.svelte +68 -0
  288. package/dist/components/scenes/iam/ReauthenticationDialog.svelte.d.ts +17 -0
  289. package/dist/components/scenes/iam/RegisterForm.svelte +129 -116
  290. package/dist/components/scenes/iam/RegisterForm.svelte.d.ts +13 -1
  291. package/dist/components/scenes/iam/ResetPasswordForm.svelte +101 -88
  292. package/dist/components/scenes/iam/ResetPasswordForm.svelte.d.ts +13 -1
  293. package/dist/components/scenes/iam/SensitiveOperationsForm.svelte +76 -0
  294. package/dist/components/scenes/iam/SensitiveOperationsForm.svelte.d.ts +21 -0
  295. package/dist/components/scenes/iam/SessionRecoveryDialog.svelte +64 -0
  296. package/dist/components/scenes/iam/SessionRecoveryDialog.svelte.d.ts +22 -0
  297. package/dist/components/scenes/iam/UserProfile.svelte +47 -21
  298. package/dist/components/scenes/iam/UserProfile.svelte.d.ts +24 -1
  299. package/dist/components/scenes/iam/auth-captcha.d.ts +21 -0
  300. package/dist/components/scenes/iam/auth-captcha.js +23 -0
  301. package/dist/components/scenes/iam/auth-error-message.d.ts +13 -0
  302. package/dist/components/scenes/iam/auth-error-message.js +65 -0
  303. package/dist/components/scenes/iam/index.d.ts +10 -0
  304. package/dist/components/scenes/iam/index.js +9 -1
  305. package/dist/components/scenes/iam/password-utils.d.ts +33 -6
  306. package/dist/components/scenes/iam/password-utils.js +61 -8
  307. package/dist/components/scenes/iam/permission-context.svelte.d.ts +33 -23
  308. package/dist/components/scenes/iam/permission-context.svelte.js +20 -22
  309. package/dist/components/scenes/iam/sensitive-actions.svelte.d.ts +68 -0
  310. package/dist/components/scenes/iam/sensitive-actions.svelte.js +101 -0
  311. package/dist/components/scenes/iam/session-recovery.svelte.d.ts +44 -0
  312. package/dist/components/scenes/iam/session-recovery.svelte.js +57 -0
  313. package/dist/components/scenes/index.d.ts +3 -0
  314. package/dist/components/scenes/index.js +5 -0
  315. package/dist/components/scenes/storage/AvatarUpload.svelte +82 -68
  316. package/dist/components/scenes/storage/AvatarUpload.svelte.d.ts +23 -1
  317. package/dist/components/scenes/storage/FileList.svelte +19 -5
  318. package/dist/components/scenes/storage/FileList.svelte.d.ts +23 -1
  319. package/dist/components/scenes/storage/FileUpload.svelte +151 -96
  320. package/dist/components/scenes/storage/FileUpload.svelte.d.ts +24 -1
  321. package/dist/components/scenes/storage/ImageUpload.svelte +93 -94
  322. package/dist/components/scenes/storage/ImageUpload.svelte.d.ts +24 -1
  323. package/dist/components/scenes/types.d.ts +574 -42
  324. package/dist/guide-storage.d.ts +18 -0
  325. package/dist/guide-storage.js +79 -0
  326. package/dist/guide-types.d.ts +143 -0
  327. package/dist/guide-types.js +1 -0
  328. package/dist/guide.d.ts +3 -0
  329. package/dist/guide.js +3 -0
  330. package/dist/guide.svelte.d.ts +29 -0
  331. package/dist/guide.svelte.js +506 -0
  332. package/dist/i18n.svelte.d.ts +67 -4
  333. package/dist/i18n.svelte.js +106 -21
  334. package/dist/index.d.ts +6 -0
  335. package/dist/index.js +7 -0
  336. package/dist/internal/browser-safety.d.ts +88 -0
  337. package/dist/internal/browser-safety.js +140 -0
  338. package/dist/internal/dialog-focus.d.ts +21 -0
  339. package/dist/internal/dialog-focus.js +77 -0
  340. package/dist/internal/form-context.d.ts +92 -0
  341. package/dist/internal/form-context.js +70 -0
  342. package/dist/internal/form-validation.svelte.d.ts +70 -0
  343. package/dist/internal/form-validation.svelte.js +142 -0
  344. package/dist/internal/icon-safety.d.ts +14 -0
  345. package/dist/internal/icon-safety.js +40 -0
  346. package/dist/internal/locale.d.ts +21 -0
  347. package/dist/internal/locale.js +43 -0
  348. package/dist/message.svelte.d.ts +138 -0
  349. package/dist/message.svelte.js +149 -0
  350. package/dist/messagebox.svelte.d.ts +130 -0
  351. package/dist/messagebox.svelte.js +171 -0
  352. package/dist/messages/en-US.json +303 -16
  353. package/dist/messages/ja-JP.json +529 -0
  354. package/dist/messages/zh-CN.json +303 -16
  355. package/dist/messages.d.ts +25 -3
  356. package/dist/messages.js +23 -6
  357. package/dist/styles/design-tokens.css +4 -2
  358. package/dist/styles/eye-care.css +55 -0
  359. package/dist/styles/formal.css +55 -0
  360. package/dist/styles/global.css +86 -18
  361. package/dist/styles/guide.css +88 -0
  362. package/dist/styles/high-contrast.css +64 -0
  363. package/dist/styles/mobile.css +28 -0
  364. package/dist/styles/theme.css +43 -0
  365. package/dist/theme-config.d.ts +263 -10
  366. package/dist/theme-config.js +253 -17
  367. package/dist/toast.svelte.d.ts +210 -2
  368. package/dist/toast.svelte.js +305 -19
  369. package/dist/types.d.ts +787 -63
  370. package/dist/utils/platform.svelte.d.ts +28 -15
  371. package/dist/utils/platform.svelte.js +23 -16
  372. package/dist/utils.d.ts +121 -1
  373. package/dist/utils.js +208 -13
  374. package/dist/workspace-context.d.ts +20 -0
  375. package/dist/workspace-context.js +9 -0
  376. package/package.json +120 -24
  377. package/vite.d.ts +13 -0
  378. package/vite.js +96 -0
  379. package/dist/components/scenes/crud/CrudEditDrawer.svelte +0 -225
  380. package/dist/components/scenes/crud/CrudEditDrawer.svelte.d.ts +0 -48
@@ -7,6 +7,12 @@
7
7
  import type { UIMessageKey } from './messages.js';
8
8
  /**
9
9
  * 主题信息
10
+ *
11
+ * @example
12
+ * ```ts
13
+ * import type { ThemeInfo } from '@h-ai/ui'
14
+ * const example: ThemeInfo = { id: 'light', name: 'Light', dark: false, primaryColor: '#2563eb', bgColor: '#ffffff' }
15
+ * ```
10
16
  */
11
17
  export interface ThemeInfo {
12
18
  /** 主题标识符 */
@@ -20,8 +26,29 @@ export interface ThemeInfo {
20
26
  /** 背景色(用于预览) */
21
27
  bgColor: string;
22
28
  }
29
+ /**
30
+ * 主题色预设定义
31
+ *
32
+ * @example
33
+ * ```ts
34
+ * import type { ThemeColorPreset } from '@h-ai/ui'
35
+ * const example: ThemeColorPreset = { value: '#2563eb', labelKey: 'theme_color_ocean' }
36
+ * ```
37
+ */
38
+ export interface ThemeColorPreset {
39
+ /** 颜色值(Hex) */
40
+ value: string;
41
+ /** 预设标签 i18n key */
42
+ labelKey: UIMessageKey;
43
+ }
23
44
  /**
24
45
  * 主题分组
46
+ *
47
+ * @example
48
+ * ```ts
49
+ * import type { ThemeGroup } from '@h-ai/ui'
50
+ * const example: ThemeGroup = { id: 'light', nameKey: 'theme_group_light', themes: [{ id: 'light', name: 'Light', dark: false, primaryColor: '#2563eb', bgColor: '#ffffff' }] }
51
+ * ```
25
52
  */
26
53
  export interface ThemeGroup {
27
54
  /** 分组标识 */
@@ -32,53 +59,272 @@ export interface ThemeGroup {
32
59
  themes: ThemeInfo[];
33
60
  }
34
61
  /**
35
- * DaisyUI 内置主题配置(精选)
62
+ * 精选 DaisyUI 主题及 UI 共享样式提供的高对比、直角商务与护眼主题。
63
+ *
64
+ * @example
65
+ * ```ts
66
+ * import { THEMES } from '@h-ai/ui'
67
+ * const choices = THEMES.map(theme => ({ value: theme.id, label: theme.name }))
68
+ * ```
36
69
  */
37
70
  export declare const THEMES: ThemeInfo[];
38
71
  /**
39
72
  * 主题分组配置
73
+ *
74
+ * @example
75
+ * ```ts
76
+ * import { THEME_GROUPS } from '@h-ai/ui'
77
+ * const light = THEME_GROUPS.find(group => group.id === 'light')
78
+ * const choices = light?.themes
79
+ * ```
40
80
  */
41
81
  export declare const THEME_GROUPS: ThemeGroup[];
42
82
  /**
43
83
  * 暗色主题列表
84
+ *
85
+ * @example
86
+ * ```ts
87
+ * import { DARK_THEMES } from '@h-ai/ui'
88
+ * const dark = DARK_THEMES.includes('dark')
89
+ * ```
44
90
  */
45
91
  export declare const DARK_THEMES: string[];
46
92
  /**
47
- * 获取主题信息
93
+ * 支持的主题 ID 列表
94
+ *
95
+ * @example
96
+ * ```ts
97
+ * import { SUPPORTED_THEME_IDS } from '@h-ai/ui'
98
+ * const supported = SUPPORTED_THEME_IDS.includes('light')
99
+ * ```
48
100
  */
49
- export declare function getThemeInfo(themeId: string): ThemeInfo | undefined;
101
+ export declare const SUPPORTED_THEME_IDS: string[];
50
102
  /**
51
- * 检查是否为暗色主题
103
+ * 默认主题色
104
+ *
105
+ * @example
106
+ * ```ts
107
+ * import { DEFAULT_THEME_COLOR } from '@h-ai/ui'
108
+ * const style = { '--brand-color': DEFAULT_THEME_COLOR }
109
+ * ```
52
110
  */
53
- export declare function isDarkTheme(themeId: string): boolean;
111
+ export declare const DEFAULT_THEME_COLOR = "#5765f0";
112
+ /**
113
+ * 主题色 CSS 变量名
114
+ *
115
+ * @example
116
+ * ```ts
117
+ * import { DEFAULT_THEME_COLOR_CSS_VAR } from '@h-ai/ui'
118
+ * document.documentElement.style.setProperty(DEFAULT_THEME_COLOR_CSS_VAR, '#2563eb')
119
+ * ```
120
+ */
121
+ export declare const DEFAULT_THEME_COLOR_CSS_VAR = "--hai-theme-color-default";
122
+ /**
123
+ * 内置主题色预设
124
+ *
125
+ * @example
126
+ * ```ts
127
+ * import { THEME_COLOR_PRESETS } from '@h-ai/ui'
128
+ * const options = THEME_COLOR_PRESETS.map(preset => ({ value: preset.value, labelKey: preset.labelKey }))
129
+ * ```
130
+ */
131
+ export declare const THEME_COLOR_PRESETS: ThemeColorPreset[];
54
132
  /**
55
133
  * 默认主题
134
+ *
135
+ * @example
136
+ * ```ts
137
+ * import { DEFAULT_THEME, applyTheme } from '@h-ai/ui'
138
+ * applyTheme(DEFAULT_THEME, false)
139
+ * ```
56
140
  */
57
141
  export declare const DEFAULT_THEME = "light";
58
142
  /**
59
143
  * 主题存储键名
144
+ *
145
+ * @example
146
+ * ```ts
147
+ * import { THEME_STORAGE_KEY, getSavedTheme } from '@h-ai/ui'
148
+ * const preference = { key: THEME_STORAGE_KEY, value: getSavedTheme('light') }
149
+ * // 通过公开安全读取函数消费偏好,不直接访问受限存储。
150
+ * ```
60
151
  */
61
152
  export declare const THEME_STORAGE_KEY = "theme";
62
153
  /**
63
- * 获取主题初始化脚本(用于 app.html 防闪烁)
154
+ * 获取主题信息
155
+ * @param themeId - 主题候选 ID。
156
+ * @returns 匹配的主题元数据,不存在时返回 undefined。
64
157
  *
65
- * 使用方式:在 app.html 的 <head> 中添加 <script>{getThemeInitScript()}</script>
158
+ * @example
159
+ * ```ts
160
+ * import { getThemeInfo } from '@h-ai/ui'
161
+ * const theme = getThemeInfo('light')
162
+ * const background = theme?.bgColor
163
+ * ```
164
+ */
165
+ export declare function getThemeInfo(themeId: string): ThemeInfo | undefined;
166
+ /**
167
+ * 检查是否为暗色主题
168
+ * @param themeId - 主题候选 ID。
169
+ * @returns 是否属于内置暗色主题。
170
+ *
171
+ * @example
172
+ * ```ts
173
+ * import { isDarkTheme } from '@h-ai/ui'
174
+ * const dark = isDarkTheme('dark')
175
+ * ```
176
+ */
177
+ export declare function isDarkTheme(themeId: string): boolean;
178
+ /**
179
+ * 归一化主题 ID,不支持的值回退到默认主题。
180
+ * @param themeId - 主题候选 ID。
181
+ * @param fallbackThemeId - 候选不支持时尝试的主题。
182
+ * @returns 支持的主题 ID;无效输入按候选和默认主题回退。
183
+ *
184
+ * @example
185
+ * ```ts
186
+ * import { normalizeThemeId } from '@h-ai/ui'
187
+ * const theme = normalizeThemeId('unknown-theme', 'light')
188
+ * ```
189
+ */
190
+ export declare function normalizeThemeId(themeId: string | null | undefined, fallbackThemeId?: string): string;
191
+ /**
192
+ * 归一化 Hex 颜色;无效值返回 null。
193
+ * @param value - 待处理或校验的值。
194
+ * @returns 小写六位 Hex 颜色;无效输入返回 null。
195
+ *
196
+ * @example
197
+ * ```ts
198
+ * import { normalizeHexColor } from '@h-ai/ui'
199
+ * const color = normalizeHexColor('#abc')
200
+ * ```
201
+ */
202
+ export declare function normalizeHexColor(value: string | null | undefined): string | null;
203
+ /**
204
+ * 解析主题对应的浏览器色调。
205
+ * @param themeId - 主题候选 ID。
206
+ * @returns 供浏览器控件配色使用的 light/dark 值。
207
+ *
208
+ * @example
209
+ * ```ts
210
+ * import { resolveThemeTone } from '@h-ai/ui'
211
+ * const tone = resolveThemeTone('dark')
212
+ * ```
213
+ */
214
+ export declare function resolveThemeTone(themeId: string): 'light' | 'dark';
215
+ /**
216
+ * 主题首屏恢复脚本里可选的语言字段配置。
217
+ *
218
+ * 业务侧如果把语言和主题一起落到同一个偏好对象里,可用这组配置在首屏阶段同步恢复语言值,
219
+ * 避免 HTML shell 和 hydrate 后的语言状态短暂不一致。
220
+ *
221
+ * @example
222
+ * ```ts
223
+ * import type { ThemeBootstrapLocaleConfig } from '@h-ai/ui'
224
+ * const example: ThemeBootstrapLocaleConfig = { key: 'demo-locale', defaultValue: 'zh-CN', supportedValues: ['zh-CN', 'en-US'] }
225
+ * ```
226
+ */
227
+ export interface ThemeBootstrapLocaleConfig {
228
+ /** 偏好对象中的语言字段名。 */
229
+ key: string;
230
+ /** 默认语言。 */
231
+ defaultValue: string;
232
+ /** 允许的语言列表。 */
233
+ supportedValues: string[];
234
+ }
235
+ /**
236
+ * 生成首屏主题恢复脚本时使用的宿主侧配置。
237
+ *
238
+ * 这组配置刻意只保留“HTML shell 首屏恢复”所需的信息,避免把运行时 helper 或 UI 组件状态
239
+ * 泄漏到脚本字符串里,方便不同应用在 `app.html` / 服务端模板中复用同一套恢复逻辑。
240
+ *
241
+ * @example
242
+ * ```ts
243
+ * import type { ThemeBootstrapScriptOptions } from '@h-ai/ui'
244
+ * const example: ThemeBootstrapScriptOptions = { storageKey: 'demo-theme', defaultThemeId: 'light', defaultThemeColor: '#2563eb' }
245
+ * ```
246
+ */
247
+ export interface ThemeBootstrapScriptOptions {
248
+ /** 偏好存储 key。 */
249
+ storageKey: string;
250
+ /** 历史主题 key;传 null 表示不做迁移。 */
251
+ legacyThemeStorageKey?: string | null;
252
+ /** 默认主题 ID。 */
253
+ defaultThemeId?: string;
254
+ /** 默认主题色;传 null 表示不处理主题色。 */
255
+ defaultThemeColor?: string | null;
256
+ /** 主题色写入的 CSS 变量;传 null 表示不写。 */
257
+ colorCssVar?: string | null;
258
+ /** 主题 tone 写入的 dataset key;传 null 表示不写。 */
259
+ toneDatasetKey?: string | null;
260
+ /** 可选的语言字段配置。 */
261
+ locale?: ThemeBootstrapLocaleConfig | null;
262
+ }
263
+ /**
264
+ * 生成首屏主题恢复脚本,适合注入到 SvelteKit `app.html` 的 `<script>` 中。
265
+ * @param options - 本次操作的行为与显示选项。
266
+ * @returns 可放入受控 HTML shell 的初始化脚本文本。
267
+ *
268
+ * @example
269
+ * ```ts
270
+ * import { createThemeBootstrapScript } from '@h-ai/ui'
271
+ * const script = createThemeBootstrapScript({ storageKey: 'demo-theme', defaultThemeId: 'light' })
272
+ * // 在应用 HTML shell 中作为受控脚本使用,避免首屏主题闪烁。
273
+ * ```
274
+ */
275
+ export declare function createThemeBootstrapScript(options: ThemeBootstrapScriptOptions): string;
276
+ /**
277
+ * 获取主题初始化脚本(用于 HTML shell 防闪烁)
278
+ *
279
+ * 返回值是“脚本标签内的文本内容”,适合宿主在构建阶段或服务端模板中注入。
280
+ * 对于 SvelteKit `app.html`,请直接粘贴这段脚本字符串的内容,不能写 `{@html getThemeInitScript()}`。
281
+ * @returns 使用默认存储约定的主题初始化脚本。
282
+ *
283
+ * @example
284
+ * ```ts
285
+ * import { getThemeInitScript } from '@h-ai/ui'
286
+ * const script = getThemeInitScript()
287
+ * ```
66
288
  */
67
289
  export declare function getThemeInitScript(): string;
68
290
  /**
69
- * 应用主题
291
+ * 应用主题,并同步原生表单控件配色;自定义主题由宿主 CSS 决定配色。
70
292
  * @param theme - 主题 ID
71
293
  * @param persist - 是否持久化到 localStorage
294
+ * @returns {void} 无返回值;更新当前文档,并按 persist 决定是否保存偏好。
295
+ *
296
+ * @example
297
+ * ```ts
298
+ * import { applyTheme } from '@h-ai/ui'
299
+ * applyTheme('dark', false)
300
+ * // false 仅更新当前 DOM,不写入持久化偏好。
301
+ * ```
72
302
  */
73
303
  export declare function applyTheme(theme: string, persist?: boolean): void;
74
304
  /**
75
305
  * 获取当前主题
306
+ * @returns 当前文档主题;无 DOM 时使用默认值。
307
+ *
308
+ * @example
309
+ * ```ts
310
+ * import { getCurrentTheme } from '@h-ai/ui'
311
+ * const theme = getCurrentTheme()
312
+ * ```
76
313
  */
77
314
  export declare function getCurrentTheme(): string;
78
315
  /**
79
- * 获取保存的主题(从 localStorage)
316
+ * 获取保存的主题;存储为空或不可用时使用宿主默认主题。
317
+ *
318
+ * @param fallbackTheme - 未保存主题时的默认值,默认 light
319
+ * @returns 安全读取并归一化的主题偏好。
320
+ *
321
+ * @example
322
+ * ```ts
323
+ * import { getSavedTheme } from '@h-ai/ui'
324
+ * const theme = getSavedTheme('light')
325
+ * ```
80
326
  */
81
- export declare function getSavedTheme(): string;
327
+ export declare function getSavedTheme(fallbackTheme?: string): string;
82
328
  /**
83
329
  * DaisyUI 主题配置字符串(用于 app.css)
84
330
  *
@@ -88,5 +334,12 @@ export declare function getSavedTheme(): string;
88
334
  * @plugin "daisyui" {
89
335
  * themes: light --default, dark --prefersdark, cupcake, bumblebee, ...
90
336
  * }
337
+ *
338
+ * @example
339
+ * ```ts
340
+ * import { DAISYUI_THEMES_CONFIG } from '@h-ai/ui'
341
+ * const css = '@plugin "daisyui" { themes: ' + DAISYUI_THEMES_CONFIG + '; }'
342
+ * // 将生成的配置用于构建时 CSS,不在浏览器动态安装主题。
343
+ * ```
91
344
  */
92
345
  export declare const DAISYUI_THEMES_CONFIG: string;
@@ -4,8 +4,15 @@
4
4
  * DaisyUI 主题元数据和配置
5
5
  * @module theme-config
6
6
  */
7
+ import { readStoredValue, writeStoredValue } from './internal/browser-safety.js';
7
8
  /**
8
- * DaisyUI 内置主题配置(精选)
9
+ * 精选 DaisyUI 主题及 UI 共享样式提供的高对比、直角商务与护眼主题。
10
+ *
11
+ * @example
12
+ * ```ts
13
+ * import { THEMES } from '@h-ai/ui'
14
+ * const choices = THEMES.map(theme => ({ value: theme.id, label: theme.name }))
15
+ * ```
9
16
  */
10
17
  export const THEMES = [
11
18
  // 亮色主题
@@ -16,6 +23,8 @@ export const THEMES = [
16
23
  { id: 'lofi', name: 'Lo-Fi', dark: false, primaryColor: '#0d0d0d', bgColor: '#ffffff' },
17
24
  { id: 'winter', name: 'Winter', dark: false, primaryColor: '#047aff', bgColor: '#ffffff' },
18
25
  { id: 'nord', name: 'Nord', dark: false, primaryColor: '#5e81ac', bgColor: '#eceff4' },
26
+ { id: 'formal', name: 'Formal', dark: false, primaryColor: '#123d70', bgColor: '#ffffff' },
27
+ { id: 'eye-care', name: 'Eye care', dark: false, primaryColor: '#365e3d', bgColor: '#e8f0df' },
19
28
  // 暗色主题
20
29
  { id: 'dark', name: 'Dark', dark: true, primaryColor: '#661ae6', bgColor: '#1d232a' },
21
30
  { id: 'dracula', name: 'Dracula', dark: true, primaryColor: '#ff79c6', bgColor: '#282a36' },
@@ -25,9 +34,17 @@ export const THEMES = [
25
34
  { id: 'sunset', name: 'Sunset', dark: true, primaryColor: '#ff865b', bgColor: '#1a1919' },
26
35
  { id: 'luxury', name: 'Luxury', dark: true, primaryColor: '#c9a53d', bgColor: '#171618' },
27
36
  { id: 'coffee', name: 'Coffee', dark: true, primaryColor: '#db924b', bgColor: '#20161f' },
37
+ { id: 'high-contrast', name: 'High contrast', dark: true, primaryColor: '#ffe04d', bgColor: '#000000' },
28
38
  ];
29
39
  /**
30
40
  * 主题分组配置
41
+ *
42
+ * @example
43
+ * ```ts
44
+ * import { THEME_GROUPS } from '@h-ai/ui'
45
+ * const light = THEME_GROUPS.find(group => group.id === 'light')
46
+ * const choices = light?.themes
47
+ * ```
31
48
  */
32
49
  export const THEME_GROUPS = [
33
50
  {
@@ -43,52 +60,257 @@ export const THEME_GROUPS = [
43
60
  ];
44
61
  /**
45
62
  * 暗色主题列表
63
+ *
64
+ * @example
65
+ * ```ts
66
+ * import { DARK_THEMES } from '@h-ai/ui'
67
+ * const dark = DARK_THEMES.includes('dark')
68
+ * ```
46
69
  */
47
70
  export const DARK_THEMES = THEMES.filter(t => t.dark).map(t => t.id);
71
+ /**
72
+ * 支持的主题 ID 列表
73
+ *
74
+ * @example
75
+ * ```ts
76
+ * import { SUPPORTED_THEME_IDS } from '@h-ai/ui'
77
+ * const supported = SUPPORTED_THEME_IDS.includes('light')
78
+ * ```
79
+ */
80
+ export const SUPPORTED_THEME_IDS = THEMES.map(theme => theme.id);
81
+ /**
82
+ * 默认主题色
83
+ *
84
+ * @example
85
+ * ```ts
86
+ * import { DEFAULT_THEME_COLOR } from '@h-ai/ui'
87
+ * const style = { '--brand-color': DEFAULT_THEME_COLOR }
88
+ * ```
89
+ */
90
+ export const DEFAULT_THEME_COLOR = '#5765f0';
91
+ /**
92
+ * 主题色 CSS 变量名
93
+ *
94
+ * @example
95
+ * ```ts
96
+ * import { DEFAULT_THEME_COLOR_CSS_VAR } from '@h-ai/ui'
97
+ * document.documentElement.style.setProperty(DEFAULT_THEME_COLOR_CSS_VAR, '#2563eb')
98
+ * ```
99
+ */
100
+ export const DEFAULT_THEME_COLOR_CSS_VAR = '--hai-theme-color-default';
101
+ /**
102
+ * 内置主题色预设
103
+ *
104
+ * @example
105
+ * ```ts
106
+ * import { THEME_COLOR_PRESETS } from '@h-ai/ui'
107
+ * const options = THEME_COLOR_PRESETS.map(preset => ({ value: preset.value, labelKey: preset.labelKey }))
108
+ * ```
109
+ */
110
+ export const THEME_COLOR_PRESETS = [
111
+ { value: DEFAULT_THEME_COLOR, labelKey: 'theme_color_tech_purple' },
112
+ { value: '#13b981', labelKey: 'theme_color_grid_green' },
113
+ { value: '#1f5eff', labelKey: 'theme_color_ocean' },
114
+ ];
115
+ const HEX_COLOR_REGEX = /^#[0-9a-f]{6}$/i;
116
+ const SHORT_HEX_COLOR_REGEX = /^#[0-9a-f]{3}$/i;
117
+ const SUPPORTED_THEME_ID_SET = new Set(SUPPORTED_THEME_IDS);
118
+ /**
119
+ * 默认主题
120
+ *
121
+ * @example
122
+ * ```ts
123
+ * import { DEFAULT_THEME, applyTheme } from '@h-ai/ui'
124
+ * applyTheme(DEFAULT_THEME, false)
125
+ * ```
126
+ */
127
+ export const DEFAULT_THEME = 'light';
128
+ /**
129
+ * 主题存储键名
130
+ *
131
+ * @example
132
+ * ```ts
133
+ * import { THEME_STORAGE_KEY, getSavedTheme } from '@h-ai/ui'
134
+ * const preference = { key: THEME_STORAGE_KEY, value: getSavedTheme('light') }
135
+ * // 通过公开安全读取函数消费偏好,不直接访问受限存储。
136
+ * ```
137
+ */
138
+ export const THEME_STORAGE_KEY = 'theme';
48
139
  /**
49
140
  * 获取主题信息
141
+ * @param themeId - 主题候选 ID。
142
+ * @returns 匹配的主题元数据,不存在时返回 undefined。
143
+ *
144
+ * @example
145
+ * ```ts
146
+ * import { getThemeInfo } from '@h-ai/ui'
147
+ * const theme = getThemeInfo('light')
148
+ * const background = theme?.bgColor
149
+ * ```
50
150
  */
51
151
  export function getThemeInfo(themeId) {
52
152
  return THEMES.find(t => t.id === themeId);
53
153
  }
54
154
  /**
55
155
  * 检查是否为暗色主题
156
+ * @param themeId - 主题候选 ID。
157
+ * @returns 是否属于内置暗色主题。
158
+ *
159
+ * @example
160
+ * ```ts
161
+ * import { isDarkTheme } from '@h-ai/ui'
162
+ * const dark = isDarkTheme('dark')
163
+ * ```
56
164
  */
57
165
  export function isDarkTheme(themeId) {
58
166
  return DARK_THEMES.includes(themeId);
59
167
  }
60
- // ─── 主题初始化工具 ───
61
168
  /**
62
- * 默认主题
169
+ * 归一化主题 ID,不支持的值回退到默认主题。
170
+ * @param themeId - 主题候选 ID。
171
+ * @param fallbackThemeId - 候选不支持时尝试的主题。
172
+ * @returns 支持的主题 ID;无效输入按候选和默认主题回退。
173
+ *
174
+ * @example
175
+ * ```ts
176
+ * import { normalizeThemeId } from '@h-ai/ui'
177
+ * const theme = normalizeThemeId('unknown-theme', 'light')
178
+ * ```
63
179
  */
64
- export const DEFAULT_THEME = 'light';
180
+ export function normalizeThemeId(themeId, fallbackThemeId = DEFAULT_THEME) {
181
+ const normalized = `${themeId ?? ''}`;
182
+ if (SUPPORTED_THEME_ID_SET.has(normalized)) {
183
+ return normalized;
184
+ }
185
+ return SUPPORTED_THEME_ID_SET.has(fallbackThemeId) ? fallbackThemeId : DEFAULT_THEME;
186
+ }
65
187
  /**
66
- * 主题存储键名
188
+ * 归一化 Hex 颜色;无效值返回 null。
189
+ * @param value - 待处理或校验的值。
190
+ * @returns 小写六位 Hex 颜色;无效输入返回 null。
191
+ *
192
+ * @example
193
+ * ```ts
194
+ * import { normalizeHexColor } from '@h-ai/ui'
195
+ * const color = normalizeHexColor('#abc')
196
+ * ```
67
197
  */
68
- export const THEME_STORAGE_KEY = 'theme';
198
+ export function normalizeHexColor(value) {
199
+ const normalized = value?.trim().toLowerCase() ?? '';
200
+ if (HEX_COLOR_REGEX.test(normalized)) {
201
+ return normalized;
202
+ }
203
+ if (SHORT_HEX_COLOR_REGEX.test(normalized)) {
204
+ return `#${normalized[1]}${normalized[1]}${normalized[2]}${normalized[2]}${normalized[3]}${normalized[3]}`;
205
+ }
206
+ return null;
207
+ }
208
+ /**
209
+ * 解析主题对应的浏览器色调。
210
+ * @param themeId - 主题候选 ID。
211
+ * @returns 供浏览器控件配色使用的 light/dark 值。
212
+ *
213
+ * @example
214
+ * ```ts
215
+ * import { resolveThemeTone } from '@h-ai/ui'
216
+ * const tone = resolveThemeTone('dark')
217
+ * ```
218
+ */
219
+ export function resolveThemeTone(themeId) {
220
+ return isDarkTheme(themeId) ? 'dark' : 'light';
221
+ }
222
+ function escapeJsonForScript(value) {
223
+ return JSON.stringify(value)
224
+ .replace(/</g, '\\u003C')
225
+ .replace(/>/g, '\\u003E')
226
+ .replace(/\u2028/g, '\\u2028')
227
+ .replace(/\u2029/g, '\\u2029');
228
+ }
229
+ /**
230
+ * 生成首屏主题恢复脚本,适合注入到 SvelteKit `app.html` 的 `<script>` 中。
231
+ * @param options - 本次操作的行为与显示选项。
232
+ * @returns 可放入受控 HTML shell 的初始化脚本文本。
233
+ *
234
+ * @example
235
+ * ```ts
236
+ * import { createThemeBootstrapScript } from '@h-ai/ui'
237
+ * const script = createThemeBootstrapScript({ storageKey: 'demo-theme', defaultThemeId: 'light' })
238
+ * // 在应用 HTML shell 中作为受控脚本使用,避免首屏主题闪烁。
239
+ * ```
240
+ */
241
+ export function createThemeBootstrapScript(options) {
242
+ const defaultThemeId = normalizeThemeId(options.defaultThemeId ?? DEFAULT_THEME);
243
+ const defaultThemeColor = options.defaultThemeColor == null
244
+ ? null
245
+ : normalizeHexColor(options.defaultThemeColor) ?? DEFAULT_THEME_COLOR;
246
+ const locale = options.locale
247
+ ? {
248
+ key: options.locale.key,
249
+ defaultValue: options.locale.defaultValue,
250
+ supportedValues: [...options.locale.supportedValues],
251
+ }
252
+ : null;
253
+ const defaultPreferences = {
254
+ themeId: defaultThemeId,
255
+ };
256
+ if (defaultThemeColor) {
257
+ defaultPreferences.themeColor = defaultThemeColor;
258
+ }
259
+ if (locale) {
260
+ defaultPreferences[locale.key] = locale.defaultValue;
261
+ }
262
+ return `(function(){var d=${escapeJsonForScript(defaultPreferences)};var s=${escapeJsonForScript(options.storageKey)};var l=${escapeJsonForScript(options.legacyThemeStorageKey ?? null)};var u=new Set(${escapeJsonForScript(SUPPORTED_THEME_IDS)});var k=new Set(${escapeJsonForScript(DARK_THEMES)});var c=${escapeJsonForScript(options.colorCssVar ?? null)};var y=${escapeJsonForScript(options.toneDatasetKey ?? null)};var i=${escapeJsonForScript(locale)};function n(e){var r=''+(e??'');return u.has(r)?r:d.themeId}function h(e){var r=(''+(e??'')).trim().toLowerCase();if(/^#[0-9a-f]{6}$/i.test(r))return r;if(/^#[0-9a-f]{3}$/i.test(r))return '#'+r[1]+r[1]+r[2]+r[2]+r[3]+r[3];return Object.prototype.hasOwnProperty.call(d,'themeColor')?d.themeColor:null}function g(e){var r={...d,themeId:n(e?.themeId)};if(Object.prototype.hasOwnProperty.call(d,'themeColor'))r.themeColor=h(e?.themeColor);if(i)r[i.key]=i.supportedValues.includes(e?.[i.key])?e[i.key]:d[i.key];return r}function a(e){var r=document.documentElement;var o=k.has(e.themeId)?'dark':'light';r.setAttribute('data-theme',e.themeId);if(y)r.dataset[y]=o;if(c){if(e.themeColor){r.style.setProperty(c,e.themeColor)}else{r.style.removeProperty(c)}}r.style.setProperty('color-scheme',o)}var p=d;try{var f=window.localStorage.getItem(s);if(f){p=g(JSON.parse(f))}else if(l){p=g({themeId:window.localStorage.getItem(l)})}else{p=g(d)}a(p);window.localStorage.setItem(s,JSON.stringify(p));if(l)window.localStorage.removeItem(l)}catch{a(d)}})()`;
263
+ }
69
264
  /**
70
- * 获取主题初始化脚本(用于 app.html 防闪烁)
265
+ * 获取主题初始化脚本(用于 HTML shell 防闪烁)
71
266
  *
72
- * 使用方式:在 app.html 的 <head> 中添加 <script>{getThemeInitScript()}</script>
267
+ * 返回值是“脚本标签内的文本内容”,适合宿主在构建阶段或服务端模板中注入。
268
+ * 对于 SvelteKit `app.html`,请直接粘贴这段脚本字符串的内容,不能写 `{@html getThemeInitScript()}`。
269
+ * @returns 使用默认存储约定的主题初始化脚本。
270
+ *
271
+ * @example
272
+ * ```ts
273
+ * import { getThemeInitScript } from '@h-ai/ui'
274
+ * const script = getThemeInitScript()
275
+ * ```
73
276
  */
74
277
  export function getThemeInitScript() {
75
- return `(function(){var t=localStorage.getItem('${THEME_STORAGE_KEY}')||'${DEFAULT_THEME}';document.documentElement.setAttribute('data-theme',t)})()`;
278
+ return createThemeBootstrapScript({
279
+ storageKey: THEME_STORAGE_KEY,
280
+ defaultThemeId: DEFAULT_THEME,
281
+ });
76
282
  }
77
283
  /**
78
- * 应用主题
284
+ * 应用主题,并同步原生表单控件配色;自定义主题由宿主 CSS 决定配色。
79
285
  * @param theme - 主题 ID
80
286
  * @param persist - 是否持久化到 localStorage
287
+ * @returns {void} 无返回值;更新当前文档,并按 persist 决定是否保存偏好。
288
+ *
289
+ * @example
290
+ * ```ts
291
+ * import { applyTheme } from '@h-ai/ui'
292
+ * applyTheme('dark', false)
293
+ * // false 仅更新当前 DOM,不写入持久化偏好。
294
+ * ```
81
295
  */
82
296
  export function applyTheme(theme, persist = true) {
83
297
  if (typeof document === 'undefined')
84
298
  return;
85
299
  document.documentElement.setAttribute('data-theme', theme);
86
- if (persist && typeof localStorage !== 'undefined') {
87
- localStorage.setItem(THEME_STORAGE_KEY, theme);
300
+ document.documentElement.style.setProperty('color-scheme', getThemeInfo(theme) ? resolveThemeTone(theme) : '');
301
+ if (persist) {
302
+ writeStoredValue(THEME_STORAGE_KEY, theme);
88
303
  }
89
304
  }
90
305
  /**
91
306
  * 获取当前主题
307
+ * @returns 当前文档主题;无 DOM 时使用默认值。
308
+ *
309
+ * @example
310
+ * ```ts
311
+ * import { getCurrentTheme } from '@h-ai/ui'
312
+ * const theme = getCurrentTheme()
313
+ * ```
92
314
  */
93
315
  export function getCurrentTheme() {
94
316
  if (typeof document === 'undefined')
@@ -96,12 +318,19 @@ export function getCurrentTheme() {
96
318
  return document.documentElement.getAttribute('data-theme') ?? DEFAULT_THEME;
97
319
  }
98
320
  /**
99
- * 获取保存的主题(从 localStorage)
321
+ * 获取保存的主题;存储为空或不可用时使用宿主默认主题。
322
+ *
323
+ * @param fallbackTheme - 未保存主题时的默认值,默认 light
324
+ * @returns 安全读取并归一化的主题偏好。
325
+ *
326
+ * @example
327
+ * ```ts
328
+ * import { getSavedTheme } from '@h-ai/ui'
329
+ * const theme = getSavedTheme('light')
330
+ * ```
100
331
  */
101
- export function getSavedTheme() {
102
- if (typeof localStorage === 'undefined')
103
- return DEFAULT_THEME;
104
- return localStorage.getItem(THEME_STORAGE_KEY) ?? DEFAULT_THEME;
332
+ export function getSavedTheme(fallbackTheme = DEFAULT_THEME) {
333
+ return readStoredValue(THEME_STORAGE_KEY) ?? fallbackTheme;
105
334
  }
106
335
  /**
107
336
  * DaisyUI 主题配置字符串(用于 app.css)
@@ -112,6 +341,13 @@ export function getSavedTheme() {
112
341
  * @plugin "daisyui" {
113
342
  * themes: light --default, dark --prefersdark, cupcake, bumblebee, ...
114
343
  * }
344
+ *
345
+ * @example
346
+ * ```ts
347
+ * import { DAISYUI_THEMES_CONFIG } from '@h-ai/ui'
348
+ * const css = '@plugin "daisyui" { themes: ' + DAISYUI_THEMES_CONFIG + '; }'
349
+ * // 将生成的配置用于构建时 CSS,不在浏览器动态安装主题。
350
+ * ```
115
351
  */
116
352
  export const DAISYUI_THEMES_CONFIG = THEMES.map((t, i) => {
117
353
  if (i === 0)