@h-ai/ui 0.1.0-alpha.67 → 0.1.0-alpha.69

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 (300) hide show
  1. package/README.en.md +39 -7
  2. package/README.ja.md +39 -7
  3. package/README.md +72 -40
  4. package/auto-import.d.ts +3 -0
  5. package/auto-import.js +3 -0
  6. package/dist/components/compounds/Accordion.svelte +24 -0
  7. package/dist/components/compounds/Accordion.svelte.d.ts +34 -0
  8. package/dist/components/compounds/ActionSheet.svelte +24 -0
  9. package/dist/components/compounds/ActionSheet.svelte.d.ts +38 -0
  10. package/dist/components/compounds/Alert.svelte +15 -4
  11. package/dist/components/compounds/Alert.svelte.d.ts +10 -0
  12. package/dist/components/compounds/AppBar.svelte +24 -0
  13. package/dist/components/compounds/AppBar.svelte.d.ts +33 -0
  14. package/dist/components/compounds/BottomNav.svelte +37 -0
  15. package/dist/components/compounds/BottomNav.svelte.d.ts +43 -0
  16. package/dist/components/compounds/Breadcrumb.svelte +11 -0
  17. package/dist/components/compounds/Breadcrumb.svelte.d.ts +20 -0
  18. package/dist/components/compounds/Calendar.svelte +20 -6
  19. package/dist/components/compounds/Calendar.svelte.d.ts +20 -6
  20. package/dist/components/compounds/Card.svelte +10 -0
  21. package/dist/components/compounds/Card.svelte.d.ts +10 -0
  22. package/dist/components/compounds/Combobox.svelte +35 -18
  23. package/dist/components/compounds/Combobox.svelte.d.ts +35 -18
  24. package/dist/components/compounds/Confirm.svelte +11 -0
  25. package/dist/components/compounds/Confirm.svelte.d.ts +21 -0
  26. package/dist/components/compounds/DataTable.svelte +40 -17
  27. package/dist/components/compounds/DataTable.svelte.d.ts +9 -13
  28. package/dist/components/compounds/DatePicker.svelte +20 -6
  29. package/dist/components/compounds/DatePicker.svelte.d.ts +20 -6
  30. package/dist/components/compounds/Drawer.svelte +11 -0
  31. package/dist/components/compounds/Drawer.svelte.d.ts +21 -0
  32. package/dist/components/compounds/Dropdown.svelte +10 -0
  33. package/dist/components/compounds/Dropdown.svelte.d.ts +10 -0
  34. package/dist/components/compounds/Empty.svelte +16 -5
  35. package/dist/components/compounds/Empty.svelte.d.ts +20 -0
  36. package/dist/components/compounds/Form.svelte +37 -2
  37. package/dist/components/compounds/Form.svelte.d.ts +20 -0
  38. package/dist/components/compounds/FormField.svelte +11 -0
  39. package/dist/components/compounds/FormField.svelte.d.ts +20 -0
  40. package/dist/components/compounds/FormLayout.svelte +13 -1
  41. package/dist/components/compounds/FormLayout.svelte.d.ts +13 -0
  42. package/dist/components/compounds/InfiniteScroll.svelte +24 -0
  43. package/dist/components/compounds/InfiniteScroll.svelte.d.ts +34 -0
  44. package/dist/components/compounds/MessageBoxContainer.svelte +11 -0
  45. package/dist/components/compounds/MessageBoxContainer.svelte.d.ts +21 -0
  46. package/dist/components/compounds/MessageBoxDialog.svelte +14 -0
  47. package/dist/components/compounds/MessageBoxDialog.svelte.d.ts +21 -0
  48. package/dist/components/compounds/MessageContainer.svelte +11 -0
  49. package/dist/components/compounds/MessageContainer.svelte.d.ts +21 -0
  50. package/dist/components/compounds/Modal.svelte +10 -0
  51. package/dist/components/compounds/Modal.svelte.d.ts +10 -0
  52. package/dist/components/compounds/PageHeader.svelte +21 -8
  53. package/dist/components/compounds/PageHeader.svelte.d.ts +21 -8
  54. package/dist/components/compounds/Pagination.svelte +34 -8
  55. package/dist/components/compounds/Pagination.svelte.d.ts +20 -0
  56. package/dist/components/compounds/Popover.svelte +11 -0
  57. package/dist/components/compounds/Popover.svelte.d.ts +20 -0
  58. package/dist/components/compounds/PullRefresh.svelte +24 -0
  59. package/dist/components/compounds/PullRefresh.svelte.d.ts +32 -0
  60. package/dist/components/compounds/Result.svelte +11 -0
  61. package/dist/components/compounds/Result.svelte.d.ts +20 -0
  62. package/dist/components/compounds/SafeArea.svelte +24 -0
  63. package/dist/components/compounds/SafeArea.svelte.d.ts +32 -0
  64. package/dist/components/compounds/Skeleton.svelte +10 -0
  65. package/dist/components/compounds/Skeleton.svelte.d.ts +10 -0
  66. package/dist/components/compounds/Steps.svelte +11 -0
  67. package/dist/components/compounds/Steps.svelte.d.ts +20 -0
  68. package/dist/components/compounds/SwipeCell.svelte +24 -0
  69. package/dist/components/compounds/SwipeCell.svelte.d.ts +37 -0
  70. package/dist/components/compounds/TableToolbar.svelte +66 -28
  71. package/dist/components/compounds/TableToolbar.svelte.d.ts +29 -19
  72. package/dist/components/compounds/Tabs.svelte +58 -10
  73. package/dist/components/compounds/Tabs.svelte.d.ts +10 -0
  74. package/dist/components/compounds/TagInput.svelte +11 -0
  75. package/dist/components/compounds/TagInput.svelte.d.ts +20 -0
  76. package/dist/components/compounds/Timeline.svelte +24 -0
  77. package/dist/components/compounds/Timeline.svelte.d.ts +34 -0
  78. package/dist/components/compounds/ToastContainer.svelte +11 -0
  79. package/dist/components/compounds/ToastContainer.svelte.d.ts +26 -0
  80. package/dist/components/compounds/Tooltip.svelte +11 -0
  81. package/dist/components/compounds/Tooltip.svelte.d.ts +22 -0
  82. package/dist/components/compounds/accordion-types.d.ts +10 -1
  83. package/dist/components/compounds/action-sheet-types.d.ts +9 -0
  84. package/dist/components/compounds/bottom-nav-types.d.ts +9 -0
  85. package/dist/components/compounds/swipe-cell-types.d.ts +9 -0
  86. package/dist/components/compounds/timeline-types.d.ts +9 -0
  87. package/dist/components/control-size.d.ts +17 -0
  88. package/dist/components/control-size.js +8 -0
  89. package/dist/components/primitives/Avatar.svelte +10 -0
  90. package/dist/components/primitives/Avatar.svelte.d.ts +10 -0
  91. package/dist/components/primitives/Badge.svelte +10 -0
  92. package/dist/components/primitives/Badge.svelte.d.ts +10 -0
  93. package/dist/components/primitives/BareButton.svelte +11 -0
  94. package/dist/components/primitives/BareButton.svelte.d.ts +20 -0
  95. package/dist/components/primitives/BareInput.svelte +11 -0
  96. package/dist/components/primitives/BareInput.svelte.d.ts +20 -0
  97. package/dist/components/primitives/Button.svelte +10 -0
  98. package/dist/components/primitives/Button.svelte.d.ts +10 -0
  99. package/dist/components/primitives/Checkbox.svelte +11 -0
  100. package/dist/components/primitives/Checkbox.svelte.d.ts +20 -0
  101. package/dist/components/primitives/IconButton.svelte +11 -0
  102. package/dist/components/primitives/IconButton.svelte.d.ts +20 -0
  103. package/dist/components/primitives/Input.svelte +10 -0
  104. package/dist/components/primitives/Input.svelte.d.ts +10 -0
  105. package/dist/components/primitives/Progress.svelte +11 -0
  106. package/dist/components/primitives/Progress.svelte.d.ts +20 -0
  107. package/dist/components/primitives/Radio.svelte +11 -0
  108. package/dist/components/primitives/Radio.svelte.d.ts +20 -0
  109. package/dist/components/primitives/Range.svelte +24 -0
  110. package/dist/components/primitives/Range.svelte.d.ts +34 -0
  111. package/dist/components/primitives/Rating.svelte +24 -0
  112. package/dist/components/primitives/Rating.svelte.d.ts +34 -0
  113. package/dist/components/primitives/Select.svelte +11 -0
  114. package/dist/components/primitives/Select.svelte.d.ts +21 -0
  115. package/dist/components/primitives/Spinner.svelte +11 -0
  116. package/dist/components/primitives/Spinner.svelte.d.ts +20 -0
  117. package/dist/components/primitives/Switch.svelte +11 -0
  118. package/dist/components/primitives/Switch.svelte.d.ts +20 -0
  119. package/dist/components/primitives/Tag.svelte +11 -0
  120. package/dist/components/primitives/Tag.svelte.d.ts +20 -0
  121. package/dist/components/primitives/Textarea.svelte +11 -0
  122. package/dist/components/primitives/Textarea.svelte.d.ts +21 -0
  123. package/dist/components/primitives/ToggleCheckbox.svelte +11 -0
  124. package/dist/components/primitives/ToggleCheckbox.svelte.d.ts +20 -0
  125. package/dist/components/primitives/ToggleInput.svelte +11 -0
  126. package/dist/components/primitives/ToggleInput.svelte.d.ts +20 -0
  127. package/dist/components/primitives/ToggleRadio.svelte +11 -0
  128. package/dist/components/primitives/ToggleRadio.svelte.d.ts +20 -0
  129. package/dist/components/scenes/ai/AiDocumentDownloadMenu.svelte +27 -0
  130. package/dist/components/scenes/ai/AiDocumentDownloadMenu.svelte.d.ts +27 -0
  131. package/dist/components/scenes/ai/AiDocumentEditor.svelte +79 -0
  132. package/dist/components/scenes/ai/AiDocumentEditor.svelte.d.ts +23 -0
  133. package/dist/components/scenes/ai/MarkdownRenderer.svelte +11 -0
  134. package/dist/components/scenes/ai/MarkdownRenderer.svelte.d.ts +28 -0
  135. package/dist/components/scenes/ai/code-preview.d.ts +28 -0
  136. package/dist/components/scenes/ai/code-preview.js +20 -0
  137. package/dist/components/scenes/ai/document-download.d.ts +52 -0
  138. package/dist/components/scenes/ai/document-download.js +30 -2
  139. package/dist/components/scenes/ai/document-parse.d.ts +71 -14
  140. package/dist/components/scenes/ai/document-parse.js +19 -9
  141. package/dist/components/scenes/ai/document-types.d.ts +222 -88
  142. package/dist/components/scenes/ai/editor-markdown-extensions.d.ts +16 -0
  143. package/dist/components/scenes/ai/editor-markdown-extensions.js +16 -0
  144. package/dist/components/scenes/ai/highlight.d.ts +11 -0
  145. package/dist/components/scenes/ai/highlight.js +11 -0
  146. package/dist/components/scenes/ai/markdown-parse.d.ts +8 -2
  147. package/dist/components/scenes/ai/markdown-parse.js +2 -2
  148. package/dist/components/scenes/ai/mermaid-host-sync.d.ts +38 -0
  149. package/dist/components/scenes/ai/mermaid-host-sync.js +30 -0
  150. package/dist/components/scenes/ai/mermaid-render.d.ts +23 -0
  151. package/dist/components/scenes/ai/mermaid-render.js +23 -0
  152. package/dist/components/scenes/ai/safe-html.d.ts +54 -6
  153. package/dist/components/scenes/ai/safe-html.js +54 -6
  154. package/dist/components/scenes/ai/table/AiTableEditor.svelte +48 -0
  155. package/dist/components/scenes/ai/table/AiTableEditor.svelte.d.ts +24 -0
  156. package/dist/components/scenes/ai/table/table-types.d.ts +79 -0
  157. package/dist/components/scenes/app/FeedbackDetail.svelte +215 -0
  158. package/dist/components/scenes/app/FeedbackDetail.svelte.d.ts +32 -0
  159. package/dist/components/scenes/app/FeedbackForm.svelte +271 -0
  160. package/dist/components/scenes/app/FeedbackForm.svelte.d.ts +61 -0
  161. package/dist/components/scenes/app/FeedbackList.svelte +147 -0
  162. package/dist/components/scenes/app/FeedbackList.svelte.d.ts +28 -0
  163. package/dist/components/scenes/app/FeedbackModal.svelte +27 -163
  164. package/dist/components/scenes/app/FeedbackModal.svelte.d.ts +13 -41
  165. package/dist/components/scenes/app/FeedbackScreenshot.svelte +106 -0
  166. package/dist/components/scenes/app/FeedbackScreenshot.svelte.d.ts +8 -0
  167. package/dist/components/scenes/app/LanguageSwitch.svelte +29 -19
  168. package/dist/components/scenes/app/LanguageSwitch.svelte.d.ts +28 -19
  169. package/dist/components/scenes/app/SettingsLayout.svelte +21 -9
  170. package/dist/components/scenes/app/SettingsLayout.svelte.d.ts +21 -9
  171. package/dist/components/scenes/app/SettingsModal.svelte +23 -0
  172. package/dist/components/scenes/app/SettingsModal.svelte.d.ts +23 -0
  173. package/dist/components/scenes/app/ThemeColorPicker.svelte +31 -0
  174. package/dist/components/scenes/app/ThemeColorPicker.svelte.d.ts +31 -0
  175. package/dist/components/scenes/app/ThemeSelector.svelte +21 -6
  176. package/dist/components/scenes/app/ThemeSelector.svelte.d.ts +21 -6
  177. package/dist/components/scenes/app/ThemeToggle.svelte +21 -4
  178. package/dist/components/scenes/app/ThemeToggle.svelte.d.ts +21 -4
  179. package/dist/components/scenes/app/feedback-functions.d.ts +41 -0
  180. package/dist/components/scenes/app/feedback-functions.js +75 -0
  181. package/dist/components/scenes/app/feedback-types.d.ts +224 -0
  182. package/dist/components/scenes/app/feedback-types.js +1 -0
  183. package/dist/components/scenes/app/index.d.ts +5 -1
  184. package/dist/components/scenes/app/index.js +4 -1
  185. package/dist/components/scenes/charts/Chart.svelte +11 -0
  186. package/dist/components/scenes/charts/Chart.svelte.d.ts +20 -0
  187. package/dist/components/scenes/charts/chart-theme.d.ts +25 -1
  188. package/dist/components/scenes/charts/chart-theme.js +25 -1
  189. package/dist/components/scenes/charts/chart-types.d.ts +83 -7
  190. package/dist/components/scenes/charts/renderers/LineChart.svelte +53 -0
  191. package/dist/components/scenes/charts/renderers/LineChart.svelte.d.ts +13 -0
  192. package/dist/components/scenes/crud/CrudDeleteConfirm.svelte +10 -0
  193. package/dist/components/scenes/crud/CrudDeleteConfirm.svelte.d.ts +10 -0
  194. package/dist/components/scenes/crud/CrudDetailDrawer.svelte +8 -0
  195. package/dist/components/scenes/crud/CrudDetailDrawer.svelte.d.ts +8 -0
  196. package/dist/components/scenes/crud/CrudDetailPanel.svelte +18 -0
  197. package/dist/components/scenes/crud/CrudDetailPanel.svelte.d.ts +18 -0
  198. package/dist/components/scenes/crud/CrudEditPanel.svelte +10 -0
  199. package/dist/components/scenes/crud/CrudEditPanel.svelte.d.ts +10 -0
  200. package/dist/components/scenes/crud/CrudFilterBar.svelte +18 -0
  201. package/dist/components/scenes/crud/CrudFilterBar.svelte.d.ts +18 -0
  202. package/dist/components/scenes/crud/CrudPage.svelte +37 -5
  203. package/dist/components/scenes/crud/CrudPage.svelte.d.ts +35 -3
  204. package/dist/components/scenes/crud/crud-controller.svelte.d.ts +142 -23
  205. package/dist/components/scenes/crud/crud-controller.svelte.js +22 -11
  206. package/dist/components/scenes/crud/crud-form-validation.d.ts +12 -0
  207. package/dist/components/scenes/crud/crud-form-validation.js +12 -0
  208. package/dist/components/scenes/crud/crud-types.d.ts +79 -8
  209. package/dist/components/scenes/crud/nav-adapter.d.ts +14 -0
  210. package/dist/components/scenes/crud/nav-adapter.js +8 -0
  211. package/dist/components/scenes/crypto/EncryptedInput.svelte +24 -0
  212. package/dist/components/scenes/crypto/EncryptedInput.svelte.d.ts +34 -0
  213. package/dist/components/scenes/crypto/HashDisplay.svelte +11 -0
  214. package/dist/components/scenes/crypto/HashDisplay.svelte.d.ts +21 -0
  215. package/dist/components/scenes/crypto/SignatureDisplay.svelte +11 -0
  216. package/dist/components/scenes/crypto/SignatureDisplay.svelte.d.ts +21 -0
  217. package/dist/components/scenes/error/ErrorPage.svelte +8 -1
  218. package/dist/components/scenes/error/ErrorPage.svelte.d.ts +8 -1
  219. package/dist/components/scenes/error/error-presets.d.ts +40 -4
  220. package/dist/components/scenes/error/error-presets.js +22 -2
  221. package/dist/components/scenes/guide/GuideHost.svelte +27 -0
  222. package/dist/components/scenes/guide/GuideHost.svelte.d.ts +27 -0
  223. package/dist/components/scenes/guide/HelpCenter.svelte +27 -0
  224. package/dist/components/scenes/guide/HelpCenter.svelte.d.ts +27 -0
  225. package/dist/components/scenes/iam/AuthPanel.svelte +26 -2
  226. package/dist/components/scenes/iam/AuthPanel.svelte.d.ts +25 -0
  227. package/dist/components/scenes/iam/AuthShell.svelte +8 -3
  228. package/dist/components/scenes/iam/AuthShell.svelte.d.ts +8 -3
  229. package/dist/components/scenes/iam/ChangePasswordForm.svelte +10 -0
  230. package/dist/components/scenes/iam/ChangePasswordForm.svelte.d.ts +10 -0
  231. package/dist/components/scenes/iam/ForgotPasswordForm.svelte +11 -0
  232. package/dist/components/scenes/iam/ForgotPasswordForm.svelte.d.ts +21 -0
  233. package/dist/components/scenes/iam/LoginForm.svelte +24 -31
  234. package/dist/components/scenes/iam/LoginForm.svelte.d.ts +10 -0
  235. package/dist/components/scenes/iam/PasswordInput.svelte +23 -0
  236. package/dist/components/scenes/iam/PasswordInput.svelte.d.ts +23 -0
  237. package/dist/components/scenes/iam/PermGuard.svelte +21 -11
  238. package/dist/components/scenes/iam/PermGuard.svelte.d.ts +30 -0
  239. package/dist/components/scenes/iam/RegisterForm.svelte +10 -0
  240. package/dist/components/scenes/iam/RegisterForm.svelte.d.ts +10 -0
  241. package/dist/components/scenes/iam/ResetPasswordForm.svelte +10 -0
  242. package/dist/components/scenes/iam/ResetPasswordForm.svelte.d.ts +10 -0
  243. package/dist/components/scenes/iam/UserProfile.svelte +11 -0
  244. package/dist/components/scenes/iam/UserProfile.svelte.d.ts +21 -0
  245. package/dist/components/scenes/iam/auth-error-message.d.ts +10 -0
  246. package/dist/components/scenes/iam/auth-error-message.js +10 -0
  247. package/dist/components/scenes/iam/password-utils.d.ts +39 -1
  248. package/dist/components/scenes/iam/password-utils.js +39 -1
  249. package/dist/components/scenes/iam/permission-context.svelte.d.ts +33 -23
  250. package/dist/components/scenes/iam/permission-context.svelte.js +20 -22
  251. package/dist/components/scenes/storage/AvatarUpload.svelte +11 -0
  252. package/dist/components/scenes/storage/AvatarUpload.svelte.d.ts +20 -0
  253. package/dist/components/scenes/storage/FileList.svelte +13 -2
  254. package/dist/components/scenes/storage/FileList.svelte.d.ts +20 -0
  255. package/dist/components/scenes/storage/FileUpload.svelte +37 -2
  256. package/dist/components/scenes/storage/FileUpload.svelte.d.ts +21 -0
  257. package/dist/components/scenes/storage/ImageUpload.svelte +11 -0
  258. package/dist/components/scenes/storage/ImageUpload.svelte.d.ts +21 -0
  259. package/dist/components/scenes/types.d.ts +352 -11
  260. package/dist/guide-storage.d.ts +13 -1
  261. package/dist/guide-storage.js +13 -1
  262. package/dist/guide-types.d.ts +67 -2
  263. package/dist/guide.svelte.d.ts +22 -1
  264. package/dist/guide.svelte.js +22 -1
  265. package/dist/i18n.svelte.d.ts +64 -3
  266. package/dist/i18n.svelte.js +99 -18
  267. package/dist/index.d.ts +2 -1
  268. package/dist/index.js +1 -2
  269. package/dist/internal/browser-safety.d.ts +51 -2
  270. package/dist/internal/browser-safety.js +45 -7
  271. package/dist/internal/form-context.d.ts +73 -0
  272. package/dist/internal/form-context.js +57 -0
  273. package/dist/internal/form-validation.svelte.d.ts +42 -0
  274. package/dist/internal/form-validation.svelte.js +26 -0
  275. package/dist/internal/icon-safety.d.ts +7 -0
  276. package/dist/internal/icon-safety.js +7 -0
  277. package/dist/internal/locale.d.ts +19 -0
  278. package/dist/internal/locale.js +21 -0
  279. package/dist/message.svelte.d.ts +90 -0
  280. package/dist/message.svelte.js +84 -0
  281. package/dist/messagebox.svelte.d.ts +61 -13
  282. package/dist/messagebox.svelte.js +55 -13
  283. package/dist/messages/en-US.json +80 -2
  284. package/dist/messages/ja-JP.json +462 -0
  285. package/dist/messages/zh-CN.json +80 -2
  286. package/dist/messages.d.ts +24 -3
  287. package/dist/messages.js +18 -3
  288. package/dist/styles/design-tokens.css +4 -2
  289. package/dist/styles/global.css +28 -8
  290. package/dist/styles/theme.css +2 -0
  291. package/dist/theme-config.d.ts +173 -0
  292. package/dist/theme-config.js +143 -0
  293. package/dist/toast.svelte.d.ts +114 -4
  294. package/dist/toast.svelte.js +108 -4
  295. package/dist/types.d.ts +526 -9
  296. package/dist/utils/platform.svelte.d.ts +28 -15
  297. package/dist/utils/platform.svelte.js +19 -14
  298. package/dist/utils.d.ts +102 -0
  299. package/dist/utils.js +93 -0
  300. package/package.json +67 -7
@@ -1,8 +1,23 @@
1
1
  import type { MarkdownSourceKind, MarkdownToolbarDownloadAction } from './document-types.js';
2
2
  /**
3
3
  * 组件内置支持的文档导出格式。
4
+ *
5
+ * @example
6
+ * ```ts
7
+ * import type { AiDocumentDownloadFormat } from '@h-ai/ui'
8
+ * const example: AiDocumentDownloadFormat = 'markdown'
9
+ * ```
4
10
  */
5
11
  export type AiDocumentDownloadFormat = 'word' | 'markdown' | 'pdf';
12
+ /**
13
+ * 归一化后的下载菜单项目。
14
+ *
15
+ * @example
16
+ * ```ts
17
+ * import type { AiDocumentResolvedDownloadAction } from '@h-ai/ui'
18
+ * const example: AiDocumentResolvedDownloadAction = { id: 'markdown', label: 'Markdown', badgeLabel: 'MD' }
19
+ * ```
20
+ */
6
21
  export interface AiDocumentResolvedDownloadAction {
7
22
  /** 菜单项稳定 id;内置格式直接复用格式名,自定义动作沿用上游传入值。 */
8
23
  id: string;
@@ -11,6 +26,15 @@ export interface AiDocumentResolvedDownloadAction {
11
26
  /** 可选短标签;保留给外层定制菜单使用。 */
12
27
  badgeLabel?: string;
13
28
  }
29
+ /**
30
+ * 文档下载输入;自定义动作应由宿主回调处理。
31
+ *
32
+ * @example
33
+ * ```ts
34
+ * import type { AiDocumentDownloadRequest } from '@h-ai/ui'
35
+ * const example: AiDocumentDownloadRequest = { actionId: 'markdown', content: '# 报告\n正文', filename: 'report.md', sourceKind: 'document' }
36
+ * ```
37
+ */
14
38
  export interface AiDocumentDownloadRequest {
15
39
  /** 用户当前选中的下载动作 id。 */
16
40
  actionId: string;
@@ -28,13 +52,41 @@ export interface AiDocumentDownloadRequest {
28
52
  /**
29
53
  * code 类型产物通常只有裸代码正文。
30
54
  * 下载和预览都通过同一份规范化逻辑包装成 fenced markdown,避免两边导出的结构不一致。
55
+ * @param value - 待处理或校验的值。
56
+ * @param kind - 本次操作输入,具体字段见参数类型。
57
+ * @param language - 待识别的语言标记。
58
+ * @returns 保留原文或按代码来源包装后的 Markdown。
59
+ *
60
+ * @example
61
+ * ```ts
62
+ * import { resolveDocumentMarkdownContent } from '@h-ai/ui'
63
+ * const markdown = resolveDocumentMarkdownContent('const count = 42', 'code', 'typescript')
64
+ * // 裸代码会包装成足够长的 Markdown fence,保留源码中的反引号。
65
+ * ```
31
66
  */
32
67
  export declare function resolveDocumentMarkdownContent(value: string, kind?: MarkdownSourceKind, language?: string): string;
33
68
  /**
34
69
  * 把自定义动作和内置动作统一归一成统一的菜单项,保证左右两侧下载菜单展示一致。
70
+ * @param actions - 宿主提供的动作列表。
71
+ * @returns 具备显示标签的标准下载动作列表。
72
+ *
73
+ * @example
74
+ * ```ts
75
+ * import { resolveDocumentDownloadActions } from '@h-ai/ui'
76
+ * const actions = resolveDocumentDownloadActions([{ id: 'markdown', label: 'Markdown', badgeLabel: 'MD' }])
77
+ * ```
35
78
  */
36
79
  export declare function resolveDocumentDownloadActions(actions?: MarkdownToolbarDownloadAction[]): AiDocumentResolvedDownloadAction[];
37
80
  /**
38
81
  * 执行内置下载动作;未知动作直接跳过,方便外层保留自定义回调扩展口。
82
+ * @param request - 包含来源、内容和动作标识的请求。
83
+ * @returns 下载流程的 Promise;SSR 或未知动作无操作。
84
+ * @throws 浏览器渲染、第三方解析或下载失败时抛出异常,由交互边界显示错误。
85
+ *
86
+ * @example
87
+ * ```ts
88
+ * import { downloadAiDocument } from '@h-ai/ui'
89
+ * await downloadAiDocument({ actionId: 'markdown', content: '# 报告\n正文', title: '报告', filename: 'report.md', sourceKind: 'document' })
90
+ * ```
39
91
  */
40
92
  export declare function downloadAiDocument(request: AiDocumentDownloadRequest): Promise<void>;
@@ -1,4 +1,4 @@
1
- import { uiM } from '../../../messages.js';
1
+ import { getUILocale, uiM } from '../../../messages.js';
2
2
  import { renderMarkdownDocument } from './document-parse.js';
3
3
  const DOCUMENT_EXPORT_ROOT_CLASS = 'hai-ai-document-export';
4
4
  const BROWSER_PDF_PAGE_HEIGHT_MM = 297;
@@ -32,6 +32,17 @@ function renderDocumentBlocksForExport(blocks) {
32
32
  /**
33
33
  * code 类型产物通常只有裸代码正文。
34
34
  * 下载和预览都通过同一份规范化逻辑包装成 fenced markdown,避免两边导出的结构不一致。
35
+ * @param value - 待处理或校验的值。
36
+ * @param kind - 本次操作输入,具体字段见参数类型。
37
+ * @param language - 待识别的语言标记。
38
+ * @returns 保留原文或按代码来源包装后的 Markdown。
39
+ *
40
+ * @example
41
+ * ```ts
42
+ * import { resolveDocumentMarkdownContent } from '@h-ai/ui'
43
+ * const markdown = resolveDocumentMarkdownContent('const count = 42', 'code', 'typescript')
44
+ * // 裸代码会包装成足够长的 Markdown fence,保留源码中的反引号。
45
+ * ```
35
46
  */
36
47
  export function resolveDocumentMarkdownContent(value, kind = 'markdown', language) {
37
48
  if (kind !== 'code') {
@@ -45,6 +56,14 @@ export function resolveDocumentMarkdownContent(value, kind = 'markdown', languag
45
56
  }
46
57
  /**
47
58
  * 把自定义动作和内置动作统一归一成统一的菜单项,保证左右两侧下载菜单展示一致。
59
+ * @param actions - 宿主提供的动作列表。
60
+ * @returns 具备显示标签的标准下载动作列表。
61
+ *
62
+ * @example
63
+ * ```ts
64
+ * import { resolveDocumentDownloadActions } from '@h-ai/ui'
65
+ * const actions = resolveDocumentDownloadActions([{ id: 'markdown', label: 'Markdown', badgeLabel: 'MD' }])
66
+ * ```
48
67
  */
49
68
  export function resolveDocumentDownloadActions(actions = []) {
50
69
  if (actions.length === 0) {
@@ -67,6 +86,15 @@ export function resolveDocumentDownloadActions(actions = []) {
67
86
  }
68
87
  /**
69
88
  * 执行内置下载动作;未知动作直接跳过,方便外层保留自定义回调扩展口。
89
+ * @param request - 包含来源、内容和动作标识的请求。
90
+ * @returns 下载流程的 Promise;SSR 或未知动作无操作。
91
+ * @throws 浏览器渲染、第三方解析或下载失败时抛出异常,由交互边界显示错误。
92
+ *
93
+ * @example
94
+ * ```ts
95
+ * import { downloadAiDocument } from '@h-ai/ui'
96
+ * await downloadAiDocument({ actionId: 'markdown', content: '# 报告\n正文', title: '报告', filename: 'report.md', sourceKind: 'document' })
97
+ * ```
70
98
  */
71
99
  export async function downloadAiDocument(request) {
72
100
  if (typeof document === 'undefined') {
@@ -285,7 +313,7 @@ function buildDocumentExportBody(bodyHtml) {
285
313
  }
286
314
  function buildDocumentExportHtml(title, bodyHtml) {
287
315
  return `<!doctype html>
288
- <html lang="zh-CN">
316
+ <html lang="${escapeExportHtml(getUILocale())}">
289
317
  <head>
290
318
  <meta charset="utf-8" />
291
319
  <meta name="viewport" content="width=device-width, initial-scale=1" />
@@ -1,38 +1,76 @@
1
1
  /**
2
- * @h-ai/ui — Markdown document parsing helpers
2
+ * @h-ai/ui — Markdown 文档解析工具
3
3
  *
4
- * Extracts HTML, outline, and code block metadata for document-mode rendering.
4
+ * 为文档模式提取安全 HTML、目录和代码块元信息。
5
5
  */
6
6
  import type { MarkdownCodeBlockItem, MarkdownOutlineItem } from './document-types.js';
7
+ /**
8
+ * 安全 Markdown 文档解析选项;运行按钮不等于允许执行代码。
9
+ *
10
+ * @example
11
+ * ```ts
12
+ * import type { MarkdownDocumentParseOptions } from '@h-ai/ui'
13
+ * const example: MarkdownDocumentParseOptions = { enableHighlight: true, allowHtmlTags: false, showRunButton: false, breaks: true }
14
+ * ```
15
+ */
7
16
  export interface MarkdownDocumentParseOptions {
8
- /** Whether to enable syntax highlighting for code blocks. */
17
+ /** 是否启用代码块语法高亮。 */
9
18
  enableHighlight?: boolean;
10
- /** Whether to render the copy button in code blocks. */
19
+ /** 是否渲染代码块复制按钮。 */
11
20
  showCopyButton?: boolean;
12
- /** Whether to render the run button and preview slot. */
21
+ /** 是否渲染运行按钮和预览槽;实际运行由宿主授权。 */
13
22
  showRunButton?: boolean;
14
- /** Whether to render code/preview tabs in code-block headers. */
23
+ /** 是否渲染代码块头部的代码/预览切换。 */
15
24
  showCodePreviewToggle?: boolean;
16
- /** Label used for the "code" tab when preview toggle is enabled. */
25
+ /** 启用预览切换时的代码页签文案。 */
17
26
  codeViewCodeLabel?: string;
18
- /** Label used for the "preview" tab when preview toggle is enabled. */
27
+ /** 启用预览切换时的预览页签文案。 */
19
28
  codeViewPreviewLabel?: string;
20
- /** Optional helper text displayed beside language in code headers. */
29
+ /** 代码块头部语言标签旁的提示文案。 */
21
30
  codePreviewHint?: string;
22
- /** Whether soft line breaks are converted to <br>. */
31
+ /** 是否将普通换行转换成 br。 */
23
32
  breaks?: boolean;
24
- /** Whether raw HTML tags are parsed through a safe allowlist. */
33
+ /** 是否按安全白名单解析原始 HTML 标签。 */
25
34
  allowHtmlTags?: boolean;
26
35
  }
36
+ /**
37
+ * 一次文档解析生成的安全渲染块、目录和原始代码块信息。
38
+ *
39
+ * @example
40
+ * ```ts
41
+ * import { renderMarkdownDocument } from '@h-ai/ui'
42
+ * import type { MarkdownRenderResult } from '@h-ai/ui'
43
+ * const result: MarkdownRenderResult = renderMarkdownDocument('# 简介\n正文')
44
+ * const headings = result.outline
45
+ * ```
46
+ */
27
47
  export interface MarkdownRenderResult {
28
- /** Extracted outline items for navigation. */
48
+ /** 供目录导航使用的标题条目。 */
29
49
  outline: MarkdownOutlineItem[];
30
- /** Extracted code blocks for run/copy features. */
50
+ /** 供运行/复制功能使用的代码块元信息。 */
31
51
  codeBlocks: MarkdownCodeBlockItem[];
32
52
  /** 阅读态使用的稳定块列表,避免流式更新销毁重型块 DOM。 */
33
53
  blocks: MarkdownDocumentBlock[];
34
54
  }
55
+ /**
56
+ * 文档渲染块的可辨识联合;HTML 块和 Mermaid 源码块分开更新。
57
+ *
58
+ * @example
59
+ * ```ts
60
+ * import type { MarkdownDocumentBlock } from '@h-ai/ui'
61
+ * const example: MarkdownDocumentBlock = { kind: 'html', id: 'paragraph-1', html: '<p>正文</p>' }
62
+ * ```
63
+ */
35
64
  export type MarkdownDocumentBlock = MarkdownDocumentHtmlBlock | MarkdownDocumentMermaidBlock;
65
+ /**
66
+ * 已经过安全策略处理的 Markdown HTML 块;不要填入未消毒输入。
67
+ *
68
+ * @example
69
+ * ```ts
70
+ * import type { MarkdownDocumentHtmlBlock } from '@h-ai/ui'
71
+ * const example: MarkdownDocumentHtmlBlock = { kind: 'html', id: 'paragraph-1', html: '<p>正文</p>' }
72
+ * ```
73
+ */
36
74
  export interface MarkdownDocumentHtmlBlock {
37
75
  /** 普通 Markdown HTML 块。 */
38
76
  kind: 'html';
@@ -41,6 +79,15 @@ export interface MarkdownDocumentHtmlBlock {
41
79
  /** 已按现有安全策略渲染后的 HTML。 */
42
80
  html: string;
43
81
  }
82
+ /**
83
+ * 完整 Mermaid 块的源码与签名,等待异步严格模式渲染。
84
+ *
85
+ * @example
86
+ * ```ts
87
+ * import type { MarkdownDocumentMermaidBlock } from '@h-ai/ui'
88
+ * const example: MarkdownDocumentMermaidBlock = { kind: 'mermaid', id: 'diagram-1', codeBlockId: 'code-1', code: 'graph TD; A-->B', language: 'mermaid', signature: JSON.stringify(['diagram-1', 'graph TD; A-->B']) }
89
+ * ```
90
+ */
44
91
  export interface MarkdownDocumentMermaidBlock {
45
92
  /** 已闭合 Mermaid fence 块。 */
46
93
  kind: 'mermaid';
@@ -56,6 +103,16 @@ export interface MarkdownDocumentMermaidBlock {
56
103
  signature: string;
57
104
  }
58
105
  /**
59
- * Render markdown into HTML and extract outline + code block metadata.
106
+ * 安全渲染 Markdown,同时提取目录和代码块元信息。
107
+ * @param content - Markdown 或文档正文。
108
+ * @param options - 本次操作的行为与显示选项。
109
+ * @returns 已消毒渲染块、目录和代码元信息。
110
+ *
111
+ * @example
112
+ * ```ts
113
+ * import { renderMarkdownDocument } from '@h-ai/ui'
114
+ * const result = renderMarkdownDocument('# 简介\n正文', { allowHtmlTags: false, enableHighlight: true })
115
+ * const firstHeading = result.outline[0]?.text
116
+ * ```
60
117
  */
61
118
  export declare function renderMarkdownDocument(content: string, options?: MarkdownDocumentParseOptions): MarkdownRenderResult;
@@ -1,14 +1,14 @@
1
1
  /**
2
- * @h-ai/ui — Markdown document parsing helpers
2
+ * @h-ai/ui — Markdown 文档解析工具
3
3
  *
4
- * Extracts HTML, outline, and code block metadata for document-mode rendering.
4
+ * 为文档模式提取安全 HTML、目录和代码块元信息。
5
5
  */
6
6
  import { Marked } from 'marked';
7
7
  import { createEditorMarkdownExtensions, extractPlainTextFromTokens, } from './editor-markdown-extensions.js';
8
8
  import { highlightCode, isLanguageSupported } from './highlight.js';
9
9
  import { isMermaidLanguage } from './mermaid-render.js';
10
10
  import { escapeHtml, isExternalLinkHref, sanitizeImageSrc, sanitizeLinkHref, sanitizeMarkdownHtml, } from './safe-html.js';
11
- /** Default parsing options for document mode. */
11
+ /** 文档模式的默认解析选项。 */
12
12
  const DEFAULT_OPTIONS = {
13
13
  enableHighlight: true,
14
14
  showCopyButton: true,
@@ -64,7 +64,7 @@ function isClosedFencedCodeBlock(token) {
64
64
  && [...closingFence].every(char => char === markerChar);
65
65
  }
66
66
  /**
67
- * Create a URL-safe heading slug while keeping letters and digits.
67
+ * 生成保留字母和数字的 URL 安全标题 slug。
68
68
  */
69
69
  function slugifyHeading(text) {
70
70
  // normalized slug used as the base key for headings.
@@ -78,7 +78,7 @@ function slugifyHeading(text) {
78
78
  return normalized || 'section';
79
79
  }
80
80
  /**
81
- * Generate a stable heading id, de-duplicating repeated titles.
81
+ * 为标题生成稳定 ID,并对重复标题去重。
82
82
  */
83
83
  function createHeadingId(state, text) {
84
84
  // base slug before de-duplication.
@@ -89,7 +89,7 @@ function createHeadingId(state, text) {
89
89
  return nextCount === 1 ? base : `${base}-${nextCount}`;
90
90
  }
91
91
  /**
92
- * Add numeric prefixes (1, 1.1, 1.1.1) to outline items.
92
+ * 为目录条目添加 1、1.1 等层级编号。
93
93
  */
94
94
  function createNumberedOutline(outline) {
95
95
  // counters track the current numbering state per heading depth.
@@ -113,7 +113,7 @@ function createNumberedOutline(outline) {
113
113
  });
114
114
  }
115
115
  /**
116
- * Build the marked renderer with outline extraction and code metadata.
116
+ * 构建同时提取目录与代码元信息的 Marked renderer。
117
117
  */
118
118
  function createRendererObject(options, state) {
119
119
  return {
@@ -264,7 +264,7 @@ function createRendererObject(options, state) {
264
264
  };
265
265
  }
266
266
  /**
267
- * Create a marked instance tied to a specific render state.
267
+ * 创建绑定本次临时解析状态的 Marked 实例。
268
268
  */
269
269
  function createMarkedInstance(options, state) {
270
270
  return new Marked({
@@ -368,7 +368,17 @@ function renderMarkdownDocumentBlocks(content, options) {
368
368
  return blocks;
369
369
  }
370
370
  /**
371
- * Render markdown into HTML and extract outline + code block metadata.
371
+ * 安全渲染 Markdown,同时提取目录和代码块元信息。
372
+ * @param content - Markdown 或文档正文。
373
+ * @param options - 本次操作的行为与显示选项。
374
+ * @returns 已消毒渲染块、目录和代码元信息。
375
+ *
376
+ * @example
377
+ * ```ts
378
+ * import { renderMarkdownDocument } from '@h-ai/ui'
379
+ * const result = renderMarkdownDocument('# 简介\n正文', { allowHtmlTags: false, enableHighlight: true })
380
+ * const firstHeading = result.outline[0]?.text
381
+ * ```
372
382
  */
373
383
  export function renderMarkdownDocument(content, options) {
374
384
  if (!content) {