@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,46 +1,87 @@
1
1
  import type { DataAttributes } from '../../../types.js';
2
2
  /**
3
- * Markdown source type, used to distinguish plain markdown, document panel, or code-only rendering.
3
+ * 内容来源种类,用于区分 Markdown 正文、文档面板和纯代码展示。
4
+ *
5
+ * @example 模块内部上下文
6
+ * ```ts
7
+ * const example: MarkdownSourceKind = 'document'
8
+ * ```
4
9
  */
5
10
  export type MarkdownSourceKind = 'markdown' | 'document' | 'code';
11
+ /**
12
+ * 文档目录节点,绑定稳定锚点、标题级别和编号标题。
13
+ *
14
+ * @example
15
+ * ```ts
16
+ * import type { MarkdownOutlineItem } from '@h-ai/ui'
17
+ * const example: MarkdownOutlineItem = { id: 'intro', text: '简介', level: 1, numberedTitle: '1 简介' }
18
+ * ```
19
+ */
6
20
  export interface MarkdownOutlineItem {
7
- /** Anchor id for outline navigation and heading sync. */
21
+ /** 目录导航与标题同步使用的稳定锚点 ID。 */
8
22
  id: string;
9
- /** Plain heading text without inline markdown formatting. */
23
+ /** 不含行内 Markdown 格式的纯文本标题。 */
10
24
  text: string;
11
- /** Heading level (1-6), mapping to h1-h6. */
25
+ /** 标题级别 1..6,对应 h1..h6。 */
12
26
  level: number;
13
- /** Numbered heading text for outline display. */
27
+ /** 用于目录展示的编号标题。 */
14
28
  numberedTitle: string;
15
29
  }
30
+ /**
31
+ * 代码块的原始源码及语言标记,供复制和预览复用。
32
+ *
33
+ * @example
34
+ * ```ts
35
+ * import type { MarkdownCodeBlockItem } from '@h-ai/ui'
36
+ * const example: MarkdownCodeBlockItem = { id: 'code-1', code: 'const count = 42', language: 'typescript' }
37
+ * ```
38
+ */
16
39
  export interface MarkdownCodeBlockItem {
17
- /** Stable code block id used by preview and DOM bindings. */
40
+ /** 预览与 DOM 关联使用的稳定代码块 ID。 */
18
41
  id: string;
19
- /** Raw code text before highlighting. */
42
+ /** 语法高亮前的原始源码。 */
20
43
  code: string;
21
- /** Detected language label, if any. */
44
+ /** 解析到的语言标记,可省略。 */
22
45
  language?: string;
23
46
  }
47
+ /**
48
+ * 代码块运行请求;由宿主按来源和语言决定是否允许执行。
49
+ *
50
+ * @example
51
+ * ```ts
52
+ * import type { MarkdownCodeRunRequest } from '@h-ai/ui'
53
+ * const example: MarkdownCodeRunRequest = { blockId: 'code-1', code: '1 + 1', language: 'javascript', sourceKind: 'code' }
54
+ * ```
55
+ */
24
56
  export interface MarkdownCodeRunRequest {
25
- /** Code block id for mapping results back to the preview slot. */
57
+ /** 用于将运行结果写回对应预览槽的代码块 ID。 */
26
58
  blockId: string;
27
- /** Raw code text. */
59
+ /** 原始代码文本。 */
28
60
  code: string;
29
- /** Code language for runtime branching. */
61
+ /** 供宿主选择运行方式的代码语言。 */
30
62
  language?: string;
31
- /** Current document title for preview metadata or logging. */
63
+ /** 用于预览元信息的当前文档标题。 */
32
64
  title?: string;
33
- /** Source kind for contextual runtime decisions. */
65
+ /** 供宿主判断运行权限与上下文的内容来源。 */
34
66
  sourceKind: MarkdownSourceKind;
35
67
  }
68
+ /**
69
+ * 宿主返回的预览内容及渲染种类;HTML 脚本必须显式授权。
70
+ *
71
+ * @example
72
+ * ```ts
73
+ * import type { MarkdownCodeRunResult } from '@h-ai/ui'
74
+ * const example: MarkdownCodeRunResult = { kind: 'text', content: '2', title: '计算结果', allowScripts: false }
75
+ * ```
76
+ */
36
77
  export interface MarkdownCodeRunResult {
37
- /** Output kind that drives preview rendering. */
78
+ /** 预览渲染使用的输出种类。 */
38
79
  kind?: 'text' | 'markdown' | 'html' | 'mermaid';
39
- /** Preview output content. */
80
+ /** 预览输出正文。 */
40
81
  content: string;
41
- /** Preview title; default text is used when omitted. */
82
+ /** 预览标题,省略时使用默认文案。 */
42
83
  title?: string;
43
- /** Optional preview description. */
84
+ /** 可选的预览说明。 */
44
85
  description?: string;
45
86
  /**
46
87
  * 预览 iframe 是否允许执行脚本。
@@ -50,49 +91,105 @@ export interface MarkdownCodeRunResult {
50
91
  */
51
92
  allowScripts?: boolean;
52
93
  }
94
+ /**
95
+ * 选区改写菜单的稳定动作标识和已本地化文案。
96
+ *
97
+ * @example
98
+ * ```ts
99
+ * import type { MarkdownRewriteAction } from '@h-ai/ui'
100
+ * const example: MarkdownRewriteAction = { id: 'shorten', label: '精简' }
101
+ * ```
102
+ */
53
103
  export interface MarkdownRewriteAction {
54
- /** Rewrite action id used in callbacks. */
104
+ /** 回调使用的改写动作标识。 */
55
105
  id: string;
56
- /** User-facing label for the rewrite action. */
106
+ /** 已经本地化的改写动作名称。 */
57
107
  label: string;
58
108
  }
109
+ /**
110
+ * 绑定动作、选中文本和当前全文的改写请求。
111
+ *
112
+ * @example
113
+ * ```ts
114
+ * import type { MarkdownRewriteRequest } from '@h-ai/ui'
115
+ * const example: MarkdownRewriteRequest = { actionId: 'shorten', selectedText: '需要精简的段落', content: '# 报告\n需要精简的段落' }
116
+ * ```
117
+ */
59
118
  export interface MarkdownRewriteRequest {
60
- /** Rewrite action id associated with the UI action. */
119
+ /** 当前界面操作关联的改写动作标识。 */
61
120
  actionId: string;
62
- /** The selected source text. */
121
+ /** 当前选中的原文。 */
63
122
  selectedText: string;
64
- /** Full document content at the time of the request. */
123
+ /** 触发请求时的完整文档内容。 */
65
124
  content: string;
66
- /** Current document title. */
125
+ /** 当前文档标题。 */
67
126
  title?: string;
68
127
  }
69
128
  /**
70
- * Legacy block-level format actions preserved for backward compatibility.
129
+ * 块级快捷操作种类:标题或列表。
130
+ *
131
+ * @example
132
+ * ```ts
133
+ * import type { MarkdownBlockFormatKind } from '@h-ai/ui'
134
+ * const example: MarkdownBlockFormatKind = 'heading'
135
+ * ```
71
136
  */
72
137
  export type MarkdownBlockFormatKind = 'heading' | 'bullet';
73
138
  /**
74
- * Rich block-style actions used by the current editor toolbar.
139
+ * 当前工具栏支持的具体段落和标题样式。
140
+ *
141
+ * @example
142
+ * ```ts
143
+ * import type { MarkdownBlockStyleKind } from '@h-ai/ui'
144
+ * const example: MarkdownBlockStyleKind = 'heading2'
145
+ * ```
75
146
  */
76
147
  export type MarkdownBlockStyleKind = 'paragraph' | 'heading1' | 'heading2' | 'heading3' | 'heading4' | 'orderedList' | 'bulletList';
77
148
  /**
78
- * Inline format actions for the editor toolbar.
79
- * `highlight` and `link` stay in the public union so older integrations keep compiling.
149
+ * 选区工具栏提供的行内格式操作。
150
+ * 高亮与链接同样通过选区操作回调交给宿主处理。
151
+ *
152
+ * @example
153
+ * ```ts
154
+ * import type { MarkdownInlineFormatKind } from '@h-ai/ui'
155
+ * const example: MarkdownInlineFormatKind = 'bold'
156
+ * ```
80
157
  */
81
158
  export type MarkdownInlineFormatKind = 'bold' | 'italic' | 'strike' | 'underline' | 'code' | 'highlight' | 'link';
82
159
  /**
83
- * Paragraph alignment actions for the editor toolbar.
160
+ * 选区工具栏提供的段落对齐方式。
161
+ *
162
+ * @example
163
+ * ```ts
164
+ * import type { MarkdownTextAlignKind } from '@h-ai/ui'
165
+ * const example: MarkdownTextAlignKind = 'center'
166
+ * ```
84
167
  */
85
168
  export type MarkdownTextAlignKind = 'left' | 'center' | 'right' | 'justify';
169
+ /**
170
+ * 纯文本选区偏移快照,DOM 变化后用于恢复或回退定位。
171
+ *
172
+ * @example 模块内部上下文
173
+ * ```ts
174
+ * const example: MarkdownSelectionSnapshot = { start: 0, end: 4, text: '示例文本' }
175
+ * ```
176
+ */
86
177
  export interface MarkdownSelectionSnapshot {
87
- /** Selection start offset within the plain-text document. */
178
+ /** 选区在文档纯文本中的起始偏移。 */
88
179
  start: number;
89
- /** Selection end offset within the plain-text document. */
180
+ /** 选区在文档纯文本中的结束偏移。 */
90
181
  end: number;
91
- /** Selected plain text, used as a fallback when structure changes. */
182
+ /** 选中纯文本,用于结构变化后的回退定位。 */
92
183
  text: string;
93
184
  }
94
185
  /**
95
186
  * 颜色面板一次只会修改前景色或背景色中的一个维度。
187
+ *
188
+ * @example
189
+ * ```ts
190
+ * import type { MarkdownColorFormatRequest } from '@h-ai/ui'
191
+ * const example: MarkdownColorFormatRequest = { target: 'text', value: '#2563eb', selectedText: '重点' }
192
+ * ```
96
193
  */
97
194
  export interface MarkdownColorFormatRequest {
98
195
  /** `text` 表示文字颜色,`background` 表示文本底色。 */
@@ -104,6 +201,14 @@ export interface MarkdownColorFormatRequest {
104
201
  /** 当前工具条记住的精确选区偏移,优先用于重复文本场景的恢复。 */
105
202
  selectionSnapshot?: MarkdownSelectionSnapshot;
106
203
  }
204
+ /**
205
+ * 添加、修改或移除选区链接的请求;href=null 表示移除链接。
206
+ *
207
+ * @example 模块内部上下文
208
+ * ```ts
209
+ * const example: MarkdownLinkFormatRequest = { href: 'https://example.com/help', selectedText: '帮助' }
210
+ * ```
211
+ */
107
212
  export interface MarkdownLinkFormatRequest {
108
213
  /** 为空时表示移除当前链接。 */
109
214
  href: string | null;
@@ -112,41 +217,70 @@ export interface MarkdownLinkFormatRequest {
112
217
  /** 当前工具条记住的选中文本,供宿主做文本兜底。 */
113
218
  selectedText?: string;
114
219
  }
220
+ /**
221
+ * 文档下载菜单动作;内置格式直接使用对应格式名,自定义动作交给宿主处理。
222
+ *
223
+ * @example
224
+ * ```ts
225
+ * import type { MarkdownToolbarDownloadAction } from '@h-ai/ui'
226
+ * const example: MarkdownToolbarDownloadAction = { id: 'markdown', label: 'Markdown', badgeLabel: 'MD' }
227
+ * ```
228
+ */
115
229
  export interface MarkdownToolbarDownloadAction {
116
- /** Action id used to identify the download target. */
230
+ /** 下载动作标识。 */
117
231
  id: string;
118
- /** Label shown in the download menu. */
232
+ /** 下载菜单显示的已本地化文案。 */
119
233
  label: string;
120
- /** Optional short badge displayed beside the menu label. */
234
+ /** 菜单文案旁可选的短标签。 */
121
235
  badgeLabel?: string;
122
236
  }
123
237
  /**
124
- * Callback props are exposed to Svelte consumers, so we keep parameter checks bivariant.
125
- * This lets older handlers with narrower unions remain assignable while the component gains new APIs.
238
+ * Svelte 事件属性使用双变型参数检查,保留组件回调的推导方式。
239
+ * 该类型仅约束回调签名,不负责验证宿主执行权限或业务数据。
240
+ * @typeParam Args - 回调参数元组类型。
241
+ * @typeParam Return - 转换结果的数据类型。
242
+ *
243
+ * @example 模块内部上下文
244
+ * ```ts
245
+ * const example: BivariantCallback<[string], void> = value => { document.body.setAttribute('data-format', value) }
246
+ * ```
126
247
  */
127
248
  type BivariantCallback<Args extends unknown[], Return = void> = {
128
249
  bivarianceHack: (...args: Args) => Return;
129
250
  }['bivarianceHack'];
251
+ /**
252
+ * 文档编辑器的数据、预览安全策略和宿主交互回调;不在组件中实现 AI 业务请求。
253
+ *
254
+ * @example
255
+ * ```svelte
256
+ * <script lang="ts">
257
+ * import { AiDocumentEditor } from '@h-ai/ui'
258
+ * import type { AiDocumentEditorProps } from '@h-ai/ui'
259
+ * const props: AiDocumentEditorProps = { content: '# 报告\n正文', title: '报告', sourceKind: 'document', allowHtmlTags: false, allowUnsafeCodePreview: false }
260
+ * </script>
261
+ * <AiDocumentEditor {...props} />
262
+ * ```
263
+ */
130
264
  export interface AiDocumentEditorProps extends DataAttributes {
131
- /** Markdown source content. */
265
+ /** Markdown 原始正文。 */
132
266
  content?: string;
133
- /** Document title displayed in the header. */
267
+ /** 头部展示的文档标题。 */
134
268
  title?: string;
135
- /** Source kind that affects rendering and interactions. */
269
+ /** 影响渲染与交互的内容来源。 */
136
270
  sourceKind?: MarkdownSourceKind;
137
- /** Default language when sourceKind is `code`. */
271
+ /** sourceKind=code 时的默认语言。 */
138
272
  codeLanguage?: string;
139
- /** Content font size. Numbers are interpreted as px. */
273
+ /** 正文字号;数字按 px 解释。 */
140
274
  fontSize?: string | number;
141
- /** Custom class for the outer container. */
275
+ /** 外层容器类名。 */
142
276
  class?: string;
143
- /** Whether to show the copy button on code blocks. */
277
+ /** 是否显示代码块复制按钮。 */
144
278
  showCopyButton?: boolean;
145
- /** Whether to show the run button on code blocks. */
279
+ /** 是否显示代码块运行按钮;是否执行仍由宿主授权。 */
146
280
  showRunButton?: boolean;
147
- /** Whether to show the code/preview toggle on code blocks. */
281
+ /** 是否显示代码/预览切换。 */
148
282
  showCodePreviewToggle?: boolean;
149
- /** Whether to parse raw HTML tags through a safe allowlist. */
283
+ /** 是否按安全白名单解析原始 HTML。 */
150
284
  allowHtmlTags?: boolean;
151
285
  /**
152
286
  * 是否启用内置的高风险代码预览。
@@ -155,93 +289,93 @@ export interface AiDocumentEditorProps extends DataAttributes {
155
289
  * 需要宿主显式开启,或由宿主通过 `oncoderun` 自行提供受控沙箱结果。
156
290
  */
157
291
  allowUnsafeCodePreview?: boolean;
158
- /** Optional helper text displayed beside language when preview toggle is enabled. */
292
+ /** 启用预览切换时语言标签旁的提示。 */
159
293
  codePreviewHint?: string;
160
- /** Whether syntax highlighting is enabled. */
294
+ /** 是否启用语法高亮。 */
161
295
  enableHighlight?: boolean;
162
- /** Whether soft line breaks are rendered as <br>. */
296
+ /** 是否将普通换行渲染为 br。 */
163
297
  breaks?: boolean;
164
- /** Whether to show the left outline panel. */
298
+ /** 是否显示左侧目录。 */
165
299
  showOutline?: boolean;
166
- /** Whether to show numbering prefixes in outline items. */
300
+ /** 是否显示目录编号。 */
167
301
  showOutlineNumbering?: boolean;
168
- /** Whether to show the top toolbar. */
302
+ /** 是否显示顶部工具栏。 */
169
303
  showToolbar?: boolean;
170
- /** Initial outline collapsed state. */
304
+ /** 目录的初始折叠状态。 */
171
305
  initialOutlineCollapsed?: boolean;
172
- /** Status text shown in the header or toolbar. */
306
+ /** 头部或工具栏显示的状态文案。 */
173
307
  statusText?: string;
174
- /** Whether a rewrite flow is in progress. */
308
+ /** 改写流程是否正在执行。 */
175
309
  rewritePending?: boolean;
176
- /** Available rewrite actions; empty hides the menu. */
310
+ /** 可用改写动作,空列表隐藏菜单。 */
177
311
  rewriteActions?: MarkdownRewriteAction[];
178
- /** Callback fired when the close action is clicked. */
312
+ /** 点击关闭时通知宿主。 */
179
313
  onclose?: () => void;
180
- /** Whether the close / back action should render as disabled. */
314
+ /** 是否禁用关闭/返回操作。 */
181
315
  closeDisabled?: boolean;
182
- /** Callback fired when the undo action is clicked. */
316
+ /** 点击撤销时通知宿主。 */
183
317
  onundo?: () => void;
184
- /** Whether the undo button should render as disabled. */
318
+ /** 是否禁用撤销操作。 */
185
319
  undoDisabled?: boolean;
186
- /** Callback fired when the redo action is clicked. */
320
+ /** 点击重做时通知宿主。 */
187
321
  onredo?: () => void;
188
- /** Whether the redo button should render as disabled. */
322
+ /** 是否禁用重做操作。 */
189
323
  redoDisabled?: boolean;
190
- /** Code run handler that returns preview results. */
324
+ /** 由宿主执行并返回预览结果的代码回调。 */
191
325
  oncoderun?: (request: MarkdownCodeRunRequest) => MarkdownCodeRunResult | void | Promise<MarkdownCodeRunResult | void>;
192
- /** Selection rewrite handler for external processing. */
326
+ /** 宿主处理选区改写的回调。 */
193
327
  onrewrite?: (request: MarkdownRewriteRequest) => void | Promise<void>;
194
- /** Exposes the scroll container for external synchronization. */
328
+ /** 向宿主暴露滚动容器以同步滚动。 */
195
329
  editorScrollHost?: HTMLDivElement | null;
196
- /** Exposes the content container for editable reads. */
330
+ /** 向宿主暴露可编辑内容容器。 */
197
331
  previewHost?: HTMLElement | null;
198
- /** Eyebrow label shown above the title. */
332
+ /** 标题上方的辅助标签。 */
199
333
  eyebrow?: string;
200
- /** Primary header text, shown with higher priority. */
334
+ /** 优先显示的头部说明。 */
201
335
  metaText?: string;
202
- /** Pill status text shown near the title. */
336
+ /** 标题附近的状态标签。 */
203
337
  saveState?: string;
204
- /** Whether the document body is contenteditable. */
338
+ /** 正文是否允许 contenteditable 编辑。 */
205
339
  editable?: boolean;
206
- /** Download menu items; defaults are used when empty. */
340
+ /** 下载菜单项,空列表使用内置动作。 */
207
341
  downloadActions?: MarkdownToolbarDownloadAction[];
208
- /** Label for the history action. */
342
+ /** 历史记录操作文案。 */
209
343
  historyActionLabel?: string;
210
- /** Label for the view version action. */
344
+ /** 查看版本操作文案。 */
211
345
  versionActionLabel?: string;
212
- /** Scroll callback for syncing external state. */
346
+ /** 向宿主同步滚动状态的回调。 */
213
347
  ondocumentscroll?: (event: Event) => void;
214
- /** Mouseup callback to sync selection state. */
348
+ /** 鼠标释放时同步选区的回调。 */
215
349
  onpreviewmouseup?: () => void;
216
- /** Input callback for contenteditable changes. */
350
+ /** 可编辑正文发生输入时的回调。 */
217
351
  onpreviewinput?: (event: Event) => void;
218
- /** Blur callback for committing edits. */
352
+ /** 失焦时提交编辑的回调。 */
219
353
  onpreviewblur?: () => void;
220
- /** Callback fired when a download action is chosen. */
354
+ /** 选择下载动作时的回调。 */
221
355
  ondownload?: (actionId: string) => void;
222
- /** Callback fired when the history action is clicked. */
356
+ /** 点击历史记录时的回调。 */
223
357
  onhistory?: () => void;
224
- /** Custom full-document copy handler. */
358
+ /** 宿主自定义的整篇复制操作。 */
225
359
  oncopydocument?: () => void | Promise<void>;
226
- /** Legacy block-format action handler for older heading / bullet integrations. */
360
+ /** 标题/列表快捷格式操作回调。 */
227
361
  onapplyblockformat?: BivariantCallback<[kind: MarkdownBlockFormatKind], void>;
228
- /** Rich block-style handler for paragraph and concrete heading-level changes. */
362
+ /** 切换段落或具体标题级别的回调。 */
229
363
  onapplyblockstyle?: BivariantCallback<[kind: MarkdownBlockStyleKind], void>;
230
- /** Inline-format action handler from the selection toolbar. */
364
+ /** 选区工具栏的行内格式回调。 */
231
365
  onapplyinlineformat?: BivariantCallback<[kind: MarkdownInlineFormatKind], void>;
232
- /** Paragraph alignment handler from the selection toolbar. */
366
+ /** 选区工具栏的段落对齐回调。 */
233
367
  onapplyalignment?: (kind: MarkdownTextAlignKind) => void;
234
- /** Link add / edit / remove handler from the selection toolbar. */
368
+ /** 选区工具栏添加、编辑或移除链接的回调。 */
235
369
  onapplylink?: BivariantCallback<[
236
370
  href: string | null,
237
371
  selectionSnapshot?: MarkdownSelectionSnapshot,
238
372
  selectedText?: string
239
373
  ], void>;
240
- /** Text or background color handler from the selection toolbar. */
374
+ /** 选区工具栏修改文字色或背景色的回调。 */
241
375
  onapplycolor?: (request: MarkdownColorFormatRequest) => void;
242
- /** Selection copy handler for custom behavior. */
376
+ /** 宿主自定义的选区复制操作。 */
243
377
  oncopyselection?: () => void | Promise<void>;
244
- /** Selection annotation handler. */
378
+ /** 宿主处理选区注释的回调。 */
245
379
  onannotation?: () => void | Promise<void>;
246
380
  }
247
381
  export {};
@@ -2,10 +2,26 @@ import type { Token, TokenizerAndRendererExtension } from 'marked';
2
2
  /**
3
3
  * Markdown heading 提取目录时需要一个“纯文本标题”。
4
4
  * 这里显式递归常见 inline token,保证 `<hai-span>`、链接、强调等都能回落成纯文本。
5
+ * @param tokens - Marked token 列表。
6
+ * @returns 递归提取的纯文本,用于标题和目录生成。
7
+ *
8
+ * @example 模块内部上下文
9
+ * ```ts
10
+ * const text = extractPlainTextFromTokens([{ type: 'text', raw: '简介', text: '简介' }])
11
+ * ```
5
12
  */
6
13
  export declare function extractPlainTextFromTokens(tokens: Token[] | undefined): string;
7
14
  /**
8
15
  * ChatWorkspace 编辑器会把“非标准 Markdown”能力写成自定义标签,
9
16
  * 这里把它们注册为 marked 扩展,保证普通 Markdown 和编辑器增强能力共享同一条渲染链路。
17
+ * @returns 受控格式的 Marked tokenizer/renderer 扩展。
18
+ *
19
+ * @example 模块内部上下文
20
+ * ```ts
21
+ * const { Marked } = await import('marked')
22
+ * const extensions = createEditorMarkdownExtensions()
23
+ * const parser = new Marked({ extensions })
24
+ * const html = parser.parse('**重点**')
25
+ * ```
10
26
  */
11
27
  export declare function createEditorMarkdownExtensions(): TokenizerAndRendererExtension[];
@@ -14,6 +14,13 @@ const HAI_HIGHLIGHT_REGEX = /^==((?:\\.|[\s\S])+?)==/;
14
14
  /**
15
15
  * Markdown heading 提取目录时需要一个“纯文本标题”。
16
16
  * 这里显式递归常见 inline token,保证 `<hai-span>`、链接、强调等都能回落成纯文本。
17
+ * @param tokens - Marked token 列表。
18
+ * @returns 递归提取的纯文本,用于标题和目录生成。
19
+ *
20
+ * @example 模块内部上下文
21
+ * ```ts
22
+ * const text = extractPlainTextFromTokens([{ type: 'text', raw: '简介', text: '简介' }])
23
+ * ```
17
24
  */
18
25
  export function extractPlainTextFromTokens(tokens) {
19
26
  if (!tokens || tokens.length === 0) {
@@ -74,6 +81,15 @@ function parseHaiSpanAttributes(rawAttributes) {
74
81
  /**
75
82
  * ChatWorkspace 编辑器会把“非标准 Markdown”能力写成自定义标签,
76
83
  * 这里把它们注册为 marked 扩展,保证普通 Markdown 和编辑器增强能力共享同一条渲染链路。
84
+ * @returns 受控格式的 Marked tokenizer/renderer 扩展。
85
+ *
86
+ * @example 模块内部上下文
87
+ * ```ts
88
+ * const { Marked } = await import('marked')
89
+ * const extensions = createEditorMarkdownExtensions()
90
+ * const parser = new Marked({ extensions })
91
+ * const html = parser.parse('**重点**')
92
+ * ```
77
93
  */
78
94
  export function createEditorMarkdownExtensions() {
79
95
  return [
@@ -11,6 +11,11 @@
11
11
  *
12
12
  * @param lang - 语言标识符(支持别名如 js、ts、py)
13
13
  * @returns 是否支持该语言
14
+ *
15
+ * @example 模块内部上下文
16
+ * ```ts
17
+ * const supported = isLanguageSupported('typescript')
18
+ * ```
14
19
  */
15
20
  export declare function isLanguageSupported(lang: string): boolean;
16
21
  /**
@@ -22,5 +27,11 @@ export declare function isLanguageSupported(lang: string): boolean;
22
27
  * @param text - 代码文本
23
28
  * @param lang - 语言标识符
24
29
  * @returns 高亮后的 HTML 片段
30
+ *
31
+ * @example 模块内部上下文
32
+ * ```ts
33
+ * const html = highlightCode('const count = 42', 'typescript')
34
+ * // 返回已转义/高亮后的代码 HTML,未知语言回退安全纯文本。
35
+ * ```
25
36
  */
26
37
  export declare function highlightCode(text: string, lang: string): string;
@@ -128,6 +128,11 @@ function extractCodeInnerHtml(html) {
128
128
  *
129
129
  * @param lang - 语言标识符(支持别名如 js、ts、py)
130
130
  * @returns 是否支持该语言
131
+ *
132
+ * @example 模块内部上下文
133
+ * ```ts
134
+ * const supported = isLanguageSupported('typescript')
135
+ * ```
131
136
  */
132
137
  export function isLanguageSupported(lang) {
133
138
  return resolveLang(lang) !== null;
@@ -141,6 +146,12 @@ export function isLanguageSupported(lang) {
141
146
  * @param text - 代码文本
142
147
  * @param lang - 语言标识符
143
148
  * @returns 高亮后的 HTML 片段
149
+ *
150
+ * @example 模块内部上下文
151
+ * ```ts
152
+ * const html = highlightCode('const count = 42', 'typescript')
153
+ * // 返回已转义/高亮后的代码 HTML,未知语言回退安全纯文本。
154
+ * ```
144
155
  */
145
156
  export function highlightCode(text, lang) {
146
157
  const resolved = resolveLang(lang);
@@ -7,6 +7,12 @@
7
7
  */
8
8
  /**
9
9
  * Markdown 解析配置
10
+ *
11
+ * @example
12
+ * ```ts
13
+ * import type { MarkdownParseOptions } from '@h-ai/ui'
14
+ * const example: MarkdownParseOptions = { enableHighlight: true, allowHtmlTags: false, showCopyButton: true }
15
+ * ```
10
16
  */
11
17
  export interface MarkdownParseOptions {
12
18
  /** 是否启用代码语法高亮(默认 true) */
@@ -27,8 +33,8 @@ export interface MarkdownParseOptions {
27
33
  *
28
34
  * @example
29
35
  * ```ts
30
- * const html = parseMarkdown('# Hello\n\nWorld')
31
- * // => '<h1>Hello</h1>\n<p>World</p>\n'
36
+ * import { parseMarkdown } from '@h-ai/ui'
37
+ * const html = parseMarkdown('# 简介\n**重点**', { allowHtmlTags: false })
32
38
  * ```
33
39
  */
34
40
  export declare function parseMarkdown(content: string, options?: MarkdownParseOptions): string;
@@ -152,8 +152,8 @@ function getOptionsKey(options) {
152
152
  *
153
153
  * @example
154
154
  * ```ts
155
- * const html = parseMarkdown('# Hello\n\nWorld')
156
- * // => '<h1>Hello</h1>\n<p>World</p>\n'
155
+ * import { parseMarkdown } from '@h-ai/ui'
156
+ * const html = parseMarkdown('# 简介\n**重点**', { allowHtmlTags: false })
157
157
  * ```
158
158
  */
159
159
  export function parseMarkdown(content, options) {