@h-ai/ui 1.0.0-beta.3 → 1.0.0-beta.30

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 (169) hide show
  1. package/README.en.md +251 -71
  2. package/README.ja.md +250 -70
  3. package/README.md +252 -73
  4. package/auto-import.d.ts +5 -0
  5. package/auto-import.js +242 -65
  6. package/dist/components/compounds/Accordion.svelte +6 -2
  7. package/dist/components/compounds/BottomNav.svelte +14 -2
  8. package/dist/components/compounds/Card.svelte +3 -1
  9. package/dist/components/compounds/Combobox.svelte +41 -5
  10. package/dist/components/compounds/DataTable.svelte +28 -8
  11. package/dist/components/compounds/DatePicker.svelte +6 -1
  12. package/dist/components/compounds/Drawer.svelte +12 -4
  13. package/dist/components/compounds/Dropdown.svelte +135 -59
  14. package/dist/components/compounds/Empty.svelte +10 -2
  15. package/dist/components/compounds/FormField.svelte +10 -2
  16. package/dist/components/compounds/JsonViewer.svelte +18 -6
  17. package/dist/components/compounds/Modal.svelte +8 -2
  18. package/dist/components/compounds/Pagination.svelte +22 -7
  19. package/dist/components/compounds/Popover.svelte +93 -12
  20. package/dist/components/compounds/Steps.svelte +24 -8
  21. package/dist/components/compounds/SwipeCell.svelte +3 -1
  22. package/dist/components/compounds/TableToolbar.svelte +32 -9
  23. package/dist/components/compounds/Tabs.svelte +25 -5
  24. package/dist/components/compounds/TagInput.svelte +2 -0
  25. package/dist/components/compounds/Timeline.svelte +6 -2
  26. package/dist/components/compounds/ToastContainer.svelte +41 -10
  27. package/dist/components/compounds/Tooltip.svelte +1 -1
  28. package/dist/components/compounds/Tooltip.svelte.d.ts +1 -1
  29. package/dist/components/control-size.js +48 -8
  30. package/dist/components/primitives/Avatar.svelte +9 -3
  31. package/dist/components/primitives/BareInput.svelte +3 -1
  32. package/dist/components/primitives/Button.svelte +6 -2
  33. package/dist/components/primitives/Checkbox.svelte +5 -0
  34. package/dist/components/primitives/IconButton.svelte +3 -1
  35. package/dist/components/primitives/Input.svelte +19 -3
  36. package/dist/components/primitives/Radio.svelte +4 -1
  37. package/dist/components/primitives/Range.svelte +3 -1
  38. package/dist/components/primitives/Rating.svelte +9 -3
  39. package/dist/components/primitives/Select.svelte +21 -5
  40. package/dist/components/primitives/Tag.svelte +6 -10
  41. package/dist/components/primitives/Textarea.svelte +14 -2
  42. package/dist/components/scenes/ai/AiDocumentEditor.svelte +45 -69
  43. package/dist/components/scenes/ai/document-download.js +6 -2
  44. package/dist/components/scenes/ai/document-parse.js +24 -8
  45. package/dist/components/scenes/ai/document-types.d.ts +0 -12
  46. package/dist/components/scenes/ai/editor-markdown-extensions.js +9 -3
  47. package/dist/components/scenes/ai/highlight.js +3 -1
  48. package/dist/components/scenes/ai/index.d.ts +1 -1
  49. package/dist/components/scenes/ai/markdown-parse.js +36 -10
  50. package/dist/components/scenes/ai/mermaid-render.js +13 -1
  51. package/dist/components/scenes/ai/safe-html.js +9 -3
  52. package/dist/components/scenes/ai/table/AiTableEditor.svelte +28 -16
  53. package/dist/components/scenes/app/FeedbackDetail.svelte +102 -24
  54. package/dist/components/scenes/app/FeedbackForm.svelte +70 -16
  55. package/dist/components/scenes/app/FeedbackList.svelte +138 -21
  56. package/dist/components/scenes/app/FeedbackRecorder.svelte +18 -5
  57. package/dist/components/scenes/app/FeedbackReplay.svelte +15 -3
  58. package/dist/components/scenes/app/FeedbackScreenshot.svelte +64 -13
  59. package/dist/components/scenes/app/LanguageSwitch.svelte +6 -2
  60. package/dist/components/scenes/app/SettingsLayout.svelte +3 -1
  61. package/dist/components/scenes/app/ThemeSelector.svelte +29 -5
  62. package/dist/components/scenes/app/ThemeToggle.svelte +6 -2
  63. package/dist/components/scenes/app/WorkspaceLayout.svelte +1 -1
  64. package/dist/components/scenes/app/feedback-functions.js +6 -2
  65. package/dist/components/scenes/charts/Chart.svelte +55 -21
  66. package/dist/components/scenes/charts/Chart.svelte.d.ts +0 -1
  67. package/dist/components/scenes/charts/ChartLoadError.svelte +13 -0
  68. package/dist/components/scenes/charts/ChartLoadError.svelte.d.ts +6 -0
  69. package/dist/components/scenes/charts/DashboardGrid.svelte +34 -0
  70. package/dist/components/scenes/charts/DashboardGrid.svelte.d.ts +15 -0
  71. package/dist/components/scenes/charts/MetricCard.svelte +69 -0
  72. package/dist/components/scenes/charts/MetricCard.svelte.d.ts +15 -0
  73. package/dist/components/scenes/charts/ReportCard.svelte +48 -0
  74. package/dist/components/scenes/charts/ReportCard.svelte.d.ts +15 -0
  75. package/dist/components/scenes/charts/chart-presets.d.ts +15 -0
  76. package/dist/components/scenes/charts/chart-presets.js +56 -0
  77. package/dist/components/scenes/charts/chart-types.d.ts +13 -2
  78. package/dist/components/scenes/charts/dashboard-types.d.ts +79 -0
  79. package/dist/components/scenes/charts/dashboard-types.js +1 -0
  80. package/dist/components/scenes/charts/index.d.ts +6 -2
  81. package/dist/components/scenes/charts/index.js +4 -1
  82. package/dist/components/scenes/charts/renderers/AreaChart.svelte +1 -0
  83. package/dist/components/scenes/charts/renderers/AreaChart.svelte.d.ts +1 -0
  84. package/dist/components/scenes/charts/renderers/BarChart.svelte +1 -0
  85. package/dist/components/scenes/charts/renderers/BarChart.svelte.d.ts +1 -0
  86. package/dist/components/scenes/charts/renderers/LineChart.svelte +39 -12
  87. package/dist/components/scenes/charts/renderers/LineChart.svelte.d.ts +1 -0
  88. package/dist/components/scenes/charts/renderers/PieChart.svelte +1 -0
  89. package/dist/components/scenes/charts/renderers/PieChart.svelte.d.ts +1 -0
  90. package/dist/components/scenes/charts/renderers/ScatterChart.svelte +1 -0
  91. package/dist/components/scenes/charts/renderers/ScatterChart.svelte.d.ts +1 -0
  92. package/dist/components/scenes/code/CodeWorkspace.svelte +946 -0
  93. package/dist/components/scenes/code/CodeWorkspace.svelte.d.ts +21 -0
  94. package/dist/components/scenes/code/CodeWorkspaceEditor.svelte +737 -0
  95. package/dist/components/scenes/code/CodeWorkspaceEditor.svelte.d.ts +37 -0
  96. package/dist/components/scenes/code/CodeWorkspaceGutter.svelte +246 -0
  97. package/dist/components/scenes/code/CodeWorkspaceGutter.svelte.d.ts +23 -0
  98. package/dist/components/scenes/code/CodeWorkspaceSearch.svelte +234 -0
  99. package/dist/components/scenes/code/CodeWorkspaceSearch.svelte.d.ts +23 -0
  100. package/dist/components/scenes/code/CodeWorkspaceTree.svelte +519 -0
  101. package/dist/components/scenes/code/CodeWorkspaceTree.svelte.d.ts +26 -0
  102. package/dist/components/scenes/code/code-editor.d.ts +12 -0
  103. package/dist/components/scenes/code/code-editor.js +93 -0
  104. package/dist/components/scenes/code/code-types.d.ts +346 -0
  105. package/dist/components/scenes/code/code-types.js +1 -0
  106. package/dist/components/scenes/code/index.d.ts +2 -0
  107. package/dist/components/scenes/code/index.js +1 -0
  108. package/dist/components/scenes/code/workers/css.worker.d.ts +1 -0
  109. package/dist/components/scenes/code/workers/css.worker.js +1 -0
  110. package/dist/components/scenes/code/workers/editor.worker.d.ts +1 -0
  111. package/dist/components/scenes/code/workers/editor.worker.js +1 -0
  112. package/dist/components/scenes/code/workers/html.worker.d.ts +1 -0
  113. package/dist/components/scenes/code/workers/html.worker.js +1 -0
  114. package/dist/components/scenes/code/workers/json.worker.d.ts +1 -0
  115. package/dist/components/scenes/code/workers/json.worker.js +1 -0
  116. package/dist/components/scenes/code/workers/ts.worker.d.ts +1 -0
  117. package/dist/components/scenes/code/workers/ts.worker.js +1 -0
  118. package/dist/components/scenes/crud/CrudDetailDrawer.svelte +6 -2
  119. package/dist/components/scenes/crud/CrudDetailPanel.svelte +6 -2
  120. package/dist/components/scenes/crud/CrudEditPanel.svelte +41 -12
  121. package/dist/components/scenes/crud/CrudPage.svelte +34 -9
  122. package/dist/components/scenes/crud/crud-controller.svelte.js +23 -8
  123. package/dist/components/scenes/crud/crud-form-validation.js +27 -9
  124. package/dist/components/scenes/crypto/EncryptedInput.svelte +9 -3
  125. package/dist/components/scenes/error/error-presets.js +30 -5
  126. package/dist/components/scenes/guide/GuideHostContent.svelte +7 -1
  127. package/dist/components/scenes/guide/HelpCenter.svelte +23 -4
  128. package/dist/components/scenes/iam/AgreementNotice.svelte +9 -3
  129. package/dist/components/scenes/iam/AuthPanel.svelte +74 -16
  130. package/dist/components/scenes/iam/ChangePasswordForm.svelte +6 -2
  131. package/dist/components/scenes/iam/ForgotPasswordForm.svelte +9 -3
  132. package/dist/components/scenes/iam/LoginForm.svelte +32 -8
  133. package/dist/components/scenes/iam/PasswordInput.svelte +50 -12
  134. package/dist/components/scenes/iam/RegisterForm.svelte +11 -3
  135. package/dist/components/scenes/iam/ResetPasswordForm.svelte +6 -2
  136. package/dist/components/scenes/iam/SensitiveOperationsForm.svelte +3 -1
  137. package/dist/components/scenes/iam/SessionRecoveryDialog.svelte +4 -1
  138. package/dist/components/scenes/iam/UserProfile.svelte +41 -14
  139. package/dist/components/scenes/iam/auth-captcha.js +9 -2
  140. package/dist/components/scenes/iam/auth-error-message.d.ts +2 -2
  141. package/dist/components/scenes/iam/auth-error-message.js +16 -3
  142. package/dist/components/scenes/iam/password-utils.js +9 -2
  143. package/dist/components/scenes/iam/sensitive-actions.svelte.js +4 -1
  144. package/dist/components/scenes/index.d.ts +1 -0
  145. package/dist/components/scenes/index.js +2 -0
  146. package/dist/components/scenes/storage/FileList.svelte +3 -1
  147. package/dist/components/scenes/storage/FileUpload.svelte +7 -2
  148. package/dist/components/scenes/types.d.ts +2 -2
  149. package/dist/guide-storage.js +12 -4
  150. package/dist/guide.svelte.js +59 -16
  151. package/dist/i18n.svelte.js +9 -3
  152. package/dist/internal/dialog-focus.d.ts +19 -0
  153. package/dist/internal/dialog-focus.js +104 -4
  154. package/dist/internal/form-validation.svelte.js +46 -15
  155. package/dist/internal/icon-safety.js +6 -2
  156. package/dist/message.svelte.js +6 -2
  157. package/dist/messagebox.svelte.js +6 -2
  158. package/dist/messages/en-US.json +60 -2
  159. package/dist/messages/ja-JP.json +60 -2
  160. package/dist/messages/zh-CN.json +60 -2
  161. package/dist/styles/eye-care.css +55 -0
  162. package/dist/styles/global.css +16 -0
  163. package/dist/styles/theme.css +1 -0
  164. package/dist/theme-config.d.ts +1 -3
  165. package/dist/theme-config.js +137 -22
  166. package/dist/toast.svelte.js +27 -7
  167. package/dist/types.d.ts +3 -3
  168. package/dist/utils.js +6 -2
  169. package/package.json +25 -19
package/README.md CHANGED
@@ -4,21 +4,13 @@
4
4
 
5
5
  [框架首页](../../README.md) · 相关模块:[@h-ai/core](../core/README.md)
6
6
 
7
- ## 简介
8
-
9
7
  内置中英日文消息(`zh-CN` / `en-US` / `ja-JP`),语言选择器默认提供三种语言。
10
8
 
11
- 基于 Svelte 5 Runes 的多端 UI 组件库,采用 DaisyUI v5 + Tailwind CSS v4 样式 + Bits UI v2 headless 交互,内置 i18n(zh-CN / en-US / ja-JP),内置 15 个精选 DaisyUI 主题、高对比及直角商务主题。
12
-
13
- ## 核心功能清单
14
-
15
- - 表单、表格、弹窗、导航、图表与业务场景组件。
16
- - 认证、CRUD、AI 内容展示、新手引导和帮助中心。
17
- - Svelte 5、主题切换、响应式布局及中英日文组件文案。
9
+ 基于 Svelte 5 Runes 的多端 UI 组件库,采用 DaisyUI v5 + Tailwind CSS v4 样式 + Bits UI v2 headless 交互,内置 i18n(zh-CN / en-US / ja-JP),内置 15 个精选 DaisyUI 主题、高对比、直角商务及护眼主题。
18
10
 
19
- Markdown 下划线与高亮支持转义,未闭合标记按文本处理;Toast 和文档下载在异常长文本输入下保持可用,追踪编号仍默认收起。
11
+ HTTP/UI 边界只对明确的有效 4xx 状态公开业务提示;错误缺少 `httpStatus` 或状态非法时按 500 返回安全提示。手写业务错误须提供完整错误定义或显式状态,不能依赖缺省状态展示原文。
20
12
 
21
- ## 使用入门
13
+ ## 快速开始
22
14
 
23
15
  ### 安装
24
16
 
@@ -28,50 +20,45 @@ npm install @h-ai/ui @h-ai/core
28
20
 
29
21
  Node 服务端工程将 UI 与 core 都列为生产依赖,确保适配器保留 core 的日志和原生依赖加载。
30
22
 
31
- ### 快速开始
32
-
33
- #### 1. 配置 svelte.config.js
23
+ ### 1. 配置 package.json 的应用导入
34
24
 
35
- ```js
36
- import { autoImportHaiUi } from '@h-ai/ui/auto-import'
37
- import adapter from '@sveltejs/adapter-node'
38
- import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'
25
+ ```json
26
+ { "imports": { "#lib/*": "./src/lib/*" } }
27
+ ```
39
28
 
40
- /** @type {import('@sveltejs/kit').Config} */
41
- const config = {
42
- preprocess: [autoImportHaiUi(), vitePreprocess()],
43
- compilerOptions: { runes: true },
44
- kit: { adapter: adapter() },
45
- }
29
+ ### 2. 配置 vite.config.ts
46
30
 
47
- export default config
48
- ```
31
+ SvelteKit 3 的预处理、编译器与适配器都在 Vite 插件中配置;纯 Svelte/Vite 工程才保留 svelte.config.js。
49
32
 
50
- #### 2. 配置 vite.config.ts
33
+ 预处理顺序为 `vitePreprocess()` 或其他样式/模板语言转换在前、`autoImportHaiUi()` 在后。自动导入读取整份 Svelte AST,不直接接受尚未转换的 SCSS、Pug 等非标准语法;保留同步调用方式。
51
34
 
52
35
  ```ts
36
+ import { autoImportHaiUi } from '@h-ai/ui/auto-import'
53
37
  import { haiOptimizeExclude, haiPrebundledDeps } from '@h-ai/ui/vite'
38
+ import adapter from '@sveltejs/adapter-node'
54
39
  import { sveltekit } from '@sveltejs/kit/vite'
40
+ import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'
55
41
  import tailwindcss from '@tailwindcss/vite'
56
42
  import { defineConfig } from 'vite'
57
43
 
58
44
  export default defineConfig({
59
- plugins: [sveltekit(), tailwindcss()],
60
- optimizeDeps: {
61
- // bits-ui 含 .svelte 源码须 exclude;@internationalized/date 须与 bits-ui 同为原始副本,
62
- // 否则日期组件会因双实例 instanceof 失败抛 "Unknown date type"
63
- exclude: [...haiOptimizeExclude],
64
- // 预打包 @h-ai/ui 的重型纯 JS 依赖(语法高亮 / Mermaid / PDF 等),
65
- // 避免首次进入业务路由时触发依赖再优化与整页刷新
66
- include: [...haiPrebundledDeps],
67
- },
45
+ plugins: [
46
+ sveltekit({
47
+ preprocess: [vitePreprocess(), autoImportHaiUi()],
48
+ compilerOptions: { runes: true },
49
+ adapter: adapter(),
50
+ paths: { relative: false },
51
+ }),
52
+ tailwindcss(),
53
+ ],
54
+ optimizeDeps: { exclude: [...haiOptimizeExclude], include: [...haiPrebundledDeps] },
68
55
  ssr: { noExternal: ['@h-ai/ui', '@h-ai/kit'], external: ['@h-ai/core', 'sm-crypto'] },
69
56
  })
70
57
  ```
71
58
 
72
- 使用 Crypto 或依赖它的 Kit/IAM 时,应用生产依赖需包含 `sm-crypto@0.5.7`。CLI 已配好这一项;手工接入时运行 `pnpm add sm-crypto@0.5.7`。仅设置 external 不够,adapter-node 还需要这项直接依赖声明才能保留原包加载。
59
+ ### 3. 配置 src/app.css
73
60
 
74
- #### 3. 配置 src/app.css
61
+ 使用 Crypto 或依赖它的 Kit/IAM 时,应用生产依赖需包含 `sm-crypto@0.5.8`。CLI 已配好这一项;手工接入时运行 `pnpm add sm-crypto@0.5.8`。仅设置 external 不够,adapter-node 还需要直接生产依赖声明才能保留原包加载。
75
62
 
76
63
  ```css
77
64
  @import 'tailwindcss';
@@ -92,7 +79,7 @@ export default defineConfig({
92
79
 
93
80
  > `@source` 让 TailwindCSS 扫描 `@h-ai/ui` 组件中使用的 class 名,否则组件样式会丢失。嵌套应用位于 monorepo 中时,依赖包可能被提升到工作区根 `node_modules`,所以建议同时保留两条路径。
94
81
 
95
- #### 4. 使用组件
82
+ ### 4. 使用组件
96
83
 
97
84
  ```svelte
98
85
  <script>
@@ -116,7 +103,7 @@ export default defineConfig({
116
103
 
117
104
  管理后台等只使用部分组件的页面,可直接使用公开组件目录入口;主题工具通过轻量 `@h-ai/ui/theme` 导入,避免主题消费加载根入口中的 AI、图表等组件。状态层的语言工具使用 `@h-ai/ui/i18n`,不加载组件与引导 CSS。组件路径以已安装版本的 exports 为准,不导入包内 `src/` 或 `dist/`。
118
105
 
119
- 自动导入器识别无分号、跨行及带别名的显式导入,已绑定的组件名称不会重复注入;仅类型导入不会替代运行时组件。
106
+ 自动导入器只为模板 AST 中实际使用的组件注入导入,注释、textarea 和脚本字符串中的示例不触发导入;脚本声明以及 each、await、snippet 等模板局部绑定优先。无分号、跨行及带别名的真实导入按语法树识别,已绑定的运行时组件名称不会重复注入。根入口 `@h-ai/ui` 的仅类型组件绑定按需提升为值;外部模块的同名类型无法安全合并时,构建错误会列出文件和组件名,请为类型设置别名,或用其他本地名显式导入组件。
120
107
 
121
108
  ```ts
122
109
  import { Card } from '@h-ai/ui/components/compounds/index'
@@ -124,7 +111,99 @@ import { Button } from '@h-ai/ui/components/primitives/index'
124
111
  import { getThemeInfo, THEMES } from '@h-ai/ui/theme'
125
112
  ```
126
113
 
127
- #### data-* 属性透传
114
+ ## 功能
115
+
116
+ ### 用途、输入与输出
117
+
118
+ UI 无 init/close;以下片段在应用组件或浏览器交互上下文中使用,命名变量代表应用已提供的请求、Schema、资源定义或配置。完整步骤和失败处理见对应功能示例。`HaiResult` 先判断 `success`,异步项按签名 `await`。
119
+
120
+ | 入口 | 场景 | 输入 | 输出 | 调用片段 |
121
+ | --- | --- | --- | --- | --- |
122
+ | `autoImportHaiUi` | 自动导入 | `preprocessed Svelte source and filename through markup` | `PreprocessorGroup; synchronous { code }` | `autoImportHaiUi()` |
123
+ | `parseMarkdown` | 安全 Markdown | `Markdown source, MarkdownParseOptions?` | `HTML string; raw HTML escaped or allowlisted` | `parseMarkdown("# Hello", { allowHtmlTags: false })` |
124
+ | `renderMarkdownDocument` | 编辑器文档模型 | `Markdown source, MarkdownDocumentParseOptions?` | `MarkdownRenderResult with outline/codeBlocks/blocks` | `renderMarkdownDocument("# Report", { allowHtmlTags: false })` |
125
+ | `isLanguageSupported` | 检查高亮语言 | `language name` | `boolean` | `isLanguageSupported("typescript")` |
126
+ | `highlightCode` | 同步代码高亮 | `code text, supported language` | `escaped/highlighted HTML string` | `highlightCode("const total = 1", "typescript")` |
127
+ | `resolveDocumentMarkdownContent` | 代码内容加围栏 | `text, sourceKind?, language?` | `Markdown string with a safe fence length` | `resolveDocumentMarkdownContent("const x = 1", "code", "ts")` |
128
+ | `resolveDocumentDownloadActions` | 下载动作菜单 | `MarkdownToolbarDownloadAction[]?` | `AiDocumentResolvedDownloadAction[]` | `resolveDocumentDownloadActions([{ id: "markdown", label: "Markdown" }])` |
129
+ | `downloadAiDocument` | 下载已选格式 | `AiDocumentDownloadRequest` | `Promise<void>; browser failure rejects, SSR does nothing` | `downloadAiDocument({ actionId: "markdown", content: "# Report", filename: "report.md" })` |
130
+ | `createLocaleStore` | 组件树语言状态 | `{ defaultLocale?, supportedLocales?, detectBrowser?, persistKey? }` | `locale store with current/set/isSupported` | `createLocaleStore({ defaultLocale: "zh-CN", detectBrowser: false })` |
131
+ | `getGlobalLocale` | 读取当前语言 | `none` | `locale string from current context` | `getGlobalLocale()` |
132
+ | `setGlobalLocale` | 设置浏览器或启动语言 | `locale` | `void; use request context for SSR` | `setGlobalLocale("en-US")` |
133
+ | `detectBrowserLocale` | 识别浏览器语言 | `supportedLocales?` | `supported locale or null` | `detectBrowserLocale()` |
134
+ | `isLocaleSupported` | 校验支持语言 | `locale, supportedLocales?` | `boolean` | `isLocaleSupported("ja-JP")` |
135
+ | `resolveLocale` | 归一化语言 | `locale, supportedLocales?, fallback?` | `supported locale` | `resolveLocale("en")` |
136
+ | `interpolate` | 替换文案参数 | `template string, InterpolationParams` | `string` | `interpolate("Hello {name}", { name: "Ada" })` |
137
+ | `getThemeInfo` | 主题元数据 | `theme ID` | `ThemeInfo or undefined` | `getThemeInfo("light")` |
138
+ | `isDarkTheme` | 识别暗色主题 | `theme ID` | `boolean` | `isDarkTheme("dark")` |
139
+ | `normalizeThemeId` | 归一化主题 | `candidate theme ID, fallback?` | `supported theme ID` | `normalizeThemeId("unknown", "light")` |
140
+ | `normalizeHexColor` | 归一化颜色 | `string or null/undefined` | `six-digit lowercase hex string or null` | `normalizeHexColor("#5765F0")` |
141
+ | `resolveThemeTone` | 主题亮暗语义 | `theme ID` | `light or dark` | `resolveThemeTone("light")` |
142
+ | `createThemeBootstrapScript` | 防首屏主题闪烁 | `ThemeBootstrapScriptOptions from trusted host config` | `script string for the application HTML shell` | `createThemeBootstrapScript({ storageKey: "theme", defaultThemeId: "light" })` |
143
+ | `getThemeInitScript` | 默认主题启动脚本 | `none` | `script string` | `getThemeInitScript()` |
144
+ | `applyTheme` | 切换页面主题 | `theme ID, persist? (default true)` | `void; updates DOM/browser preference` | `applyTheme("dark")` |
145
+ | `getCurrentTheme` | 读取页面主题 | `none` | `theme ID string` | `getCurrentTheme()` |
146
+ | `getSavedTheme` | 读取主题偏好 | `fallback theme ID?` | `theme ID string` | `getSavedTheme("light")` |
147
+ | `createGuide` | 引导控制器 | `GuideOptions: tours, articles?, nav?, persistence?, persistKey?` | `GuideController; no init/close` | `createGuide({ tours: [], persistence: "memory" })` |
148
+ | `resolveGuideText` | 延迟翻译引导文案 | `string or translation callback?` | `string` | `resolveGuideText(() => m.help())` |
149
+ | `matchPermission` | 前端权限显示 | `required permission, userPermissions[]` | `boolean; not server authorization` | `matchPermission("orders:read", ["orders:*"])` |
150
+ | `setPermissionContext` | 提供组件权限上下文 | `() => current permissions; component initialization only` | `void` | `setPermissionContext(() => user.permissions)` |
151
+ | `usePermission` | 消费组件权限 | `none; component initialization only` | `PermissionContext with hasPerm/hasAnyPerm/hasAllPerms` | `usePermission()` |
152
+ | `createSensitiveActions` | 敏感操作确认 | `standard auth actions providing reauthenticate/publicConfig?` | `SensitiveActions: configure/authorize/submit/cancel` | `createSensitiveActions(actions)` |
153
+ | `createSessionRecovery` | 原地恢复会话 | `none; configure public config and current user afterward` | `SessionRecovery controller` | `createSessionRecovery()` |
154
+ | `defineCrud` | 声明列表表单 | `CrudResource with fields/API callbacks` | `CrudDef for CrudPage` | `defineCrud(resourceDefinition)` |
155
+ | `createCrudController` | 托管列表状态 | `CrudDef, { autoLoad? }?` | `controller data/nav/loading/loaded/error/load/reload` | `createCrudController(crud, { autoLoad: false })` |
156
+ | `mapPaginated` | 映射分页条目 | `PaginatedResult<T>, (item,index) => R` | `PaginatedResult<R> retaining total/page/pageSize` | `mapPaginated(page, item => ({ ...item, selected: false }))` |
157
+ | `createBrowserNavAdapter` | 接入普通浏览器导航 | `none` | `NavAdapter` | `createBrowserNavAdapter()` |
158
+ | `registerClipboardHostWriter` | 注册 WebView 剪贴板 | `async text => boolean or null to unregister` | `void` | `registerClipboardHostWriter(null)` |
159
+ | `writeTextToClipboard` | 复制并核对结果 | `text: string` | `Promise<boolean>; true only when write succeeds` | `writeTextToClipboard("trace-001")` |
160
+ | `cn` | 合并类名 | `...string\|boolean\|null\|undefined values` | `string` | `cn("flex", active && "text-primary")` |
161
+ | `getDataAttributes` | 只透传 data 属性 | `props record` | `ForwardedDataAttributes` | `getDataAttributes({ "data-testid": "save" })` |
162
+ | `generateId` | 生成 UI 标识 | `prefix?; not a security token generator` | `string` | `generateId("field")` |
163
+ | `portal` | 将节点挂到宿主 | `HTMLElement, target HTMLElement or selector?` | `Svelte action result with cleanup` | `portal(node, document.body)` |
164
+ | `detectPlatform` | 检测终端类型 | `none` | `Platform` | `detectPlatform()` |
165
+ | `isMobile` | 检查移动端 | `none` | `boolean` | `isMobile()` |
166
+ | `isNativeApp` | 检查原生壳 | `none` | `boolean` | `isNativeApp()` |
167
+ | `usePlatform` | 响应式终端视图 | `none; component initialization` | `{ current, isMobile, isApp }` | `usePlatform()` |
168
+ | `getVariantClass` | 映射主题样式 | `Variant, prefix?` | `string class name` | `getVariantClass("primary", "btn")` |
169
+ | `getSizeClass` | 映射主题样式 | `Size, prefix?` | `string class name` | `getSizeClass("sm", "btn")` |
170
+ | `getInputSizeClass` | 映射主题样式 | `Size` | `string class name` | `getInputSizeClass("sm")` |
171
+ | `getBadgeVariantClass` | 映射主题样式 | `Variant` | `string class name` | `getBadgeVariantClass("info")` |
172
+ | `getBadgeSizeClass` | 映射主题样式 | `Size` | `string class name` | `getBadgeSizeClass("sm")` |
173
+ | `getAlertVariantClass` | 映射主题样式 | `Variant` | `string class name` | `getAlertVariantClass("info")` |
174
+ | `getProgressVariantClass` | 映射主题样式 | `Variant` | `string class name` | `getProgressVariantClass("primary")` |
175
+ | `useToastFeedback` | 操作结果提示 | `() => safely localized message, variant?` | `void; source-owned toast lifecycle` | `useToastFeedback(() => errorMessage(error))` |
176
+ | `notifySuccess` | 操作结果提示 | `localized message, duration?` | `toast ID string` | `notifySuccess(m.saved())` |
177
+ | `notifyInfo` | 操作结果提示 | `localized message, duration?` | `toast ID string` | `notifyInfo(m.loading())` |
178
+ | `notifyWarning` | 操作结果提示 | `localized message, duration?` | `toast ID string` | `notifyWarning(m.warning())` |
179
+ | `notifyError` | 操作结果提示 | `unknown error, safe fallback?, duration?` | `toast ID string; internal exception text hidden` | `notifyError(error, m.retry())` |
180
+ | `errorMessage` | 操作结果提示 | `unknown error, safe fallback?` | `safe localized string` | `errorMessage(error, m.retry())` |
181
+ | `toast.add` | 共享提示队列 | `localized options/message` | `string item ID` | `toast.add({ message: m.saved(), variant: "success" })` |
182
+ | `toast.success` | 共享提示队列 | `localized safe message, duration?` | `string item ID` | `toast.success(m.result())` |
183
+ | `toast.info` | 共享提示队列 | `localized safe message, duration?` | `string item ID` | `toast.info(m.result())` |
184
+ | `toast.warning` | 共享提示队列 | `localized safe message, duration?` | `string item ID` | `toast.warning(m.result())` |
185
+ | `toast.error` | 共享提示队列 | `localized safe message, duration?` | `string item ID` | `toast.error(m.result())` |
186
+ | `toast.remove` | 共享提示队列 | `item ID` | `void` | `toast.remove(id)` |
187
+ | `toast.clear` | 共享提示队列 | `none` | `void` | `toast.clear()` |
188
+ | `message.add` | 共享提示队列 | `localized options/message` | `string item ID` | `message.add({ message: m.saved(), type: "success" })` |
189
+ | `message.success` | 共享提示队列 | `localized safe message, duration?` | `string item ID` | `message.success(m.result())` |
190
+ | `message.info` | 共享提示队列 | `localized safe message, duration?` | `string item ID` | `message.info(m.result())` |
191
+ | `message.warning` | 共享提示队列 | `localized safe message, duration?` | `string item ID` | `message.warning(m.result())` |
192
+ | `message.error` | 共享提示队列 | `localized safe message, duration?` | `string item ID` | `message.error(m.result())` |
193
+ | `message.remove` | 共享提示队列 | `item ID` | `void` | `message.remove(id)` |
194
+ | `message.clear` | 共享提示队列 | `none` | `void` | `message.clear()` |
195
+ | `toast.pause` | 提示计时 | `toast ID` | `void` | `toast.pause(id)` |
196
+ | `toast.resume` | 提示计时 | `toast ID` | `void` | `toast.resume(id)` |
197
+ | `messageBox.confirm` | 异步确认弹窗 | `localized string or MessageBoxOptions` | `Promise<boolean>; host handles confirmation/cancellation` | `messageBox.confirm({ message: m.confirm() })` |
198
+ | `messageBox.alert` | 异步确认弹窗 | `localized string or MessageBoxOptions` | `Promise<boolean>; host handles confirmation/cancellation` | `messageBox.alert({ message: m.confirm() })` |
199
+
200
+ - 表单、表格、弹窗、导航、图表与业务场景组件。
201
+ - 认证、CRUD、AI 内容展示、新手引导和帮助中心。
202
+ - Svelte 5、主题切换、响应式布局及中英日文组件文案。
203
+
204
+ Markdown 下划线与高亮支持转义,未闭合标记按文本处理;Toast 和文档下载在异常长文本输入下保持可用,追踪编号仍默认收起。
205
+
206
+ ### data-* 属性透传
128
207
 
129
208
  公开 Svelte 组件支持把调用方传入的 `data-*` 属性透传到组件根节点或主交互节点,便于测试选择器、埋点和自动化标记。普通未知属性不会被透传。
130
209
 
@@ -136,6 +215,32 @@ import { getThemeInfo, THEMES } from '@h-ai/ui/theme'
136
215
 
137
216
  无需再为了 `data-testid` 单独封装按钮、输入框或弹层组件。
138
217
 
218
+ ### 组件族的输入、事件与输出
219
+
220
+ 下表覆盖组件清单中的交互类别;变量 m、rows、user、controllers 和回调由业务应用提供。静态展示组件输出 DOM,交互组件通过绑定和回调向应用报告变化,均不自动取得业务授权。更完整的组合步骤见本页“使用示例”、对应组件清单说明及 UI skill;其余 Props 由实际导出的 Props 类型约束。
221
+
222
+ | 组件族 | 输入 | 输出/事件 | 使用片段 |
223
+ | --- | --- | --- | --- |
224
+ | Button / IconButton / BareButton | variant, size, loading, disabled; icon/snippet; onclick | click event; loading/disabled block repeated action | `<Button loading={saving} onclick={save}>{m.save()}</Button>` |
225
+ | Input / BareInput / Textarea / PasswordInput | type, value, label/validation props | bind:value; input/change/focus events; file input exposes FileList | `<Input bind:value={draft} required />` |
226
+ | Select / Radio / Range / Rating / Combobox | options or min/max/step, current value | bound selected value and selection callbacks | `<Select options={options} bind:value={selected} />` |
227
+ | Checkbox / Switch / ToggleCheckbox / ToggleInput / ToggleRadio | checked/name/label, disabled | bind:checked and change events | `<Checkbox bind:checked={enabled} label={m.enabled()} />` |
228
+ | Form / FormLayout / FormField / TagInput | columns, labels, error/hint, tags, submit callback | validated submit event, tag changes, accessible field association | `<Form onsubmit={save}><FormField label={m.name()}><Input bind:value={name} /></FormField></Form>` |
229
+ | Modal / Drawer / Popover / Dropdown / Tooltip / Calendar | open, trigger/content snippets, dimensions, selected value | bound open/selection; focus handling and close actions | `<Modal bind:open={open} title={m.details()}>{m.content()}</Modal>` |
230
+ | DataTable / TableToolbar / Pagination / FilterBar | rows, columns, total/page, draft search/filter, loading | row/sort/page/query callbacks; host performs the request | `<DataTable {columns} data={rows} sortKey={sortKey} sortDir={sortDir} onsort={sortRows} />` |
231
+ | Tabs / Breadcrumb / Steps / BottomNav / AppBar | items/current key, links, titles and action snippets | selected key/navigation callbacks; host owns routing | `<Tabs {items} bind:active={activeTab} />` |
232
+ | Alert / Badge / Avatar / Tag / Spinner / Progress / Skeleton / Empty / Result | status/variant/value/text/image and state props | presentational DOM; tag/alert close callbacks when enabled | `<Progress value={completed} max={total} />` |
233
+ | WorkspaceLayout / PageHeader / SettingsLayout / SettingsModal | title, sections, active key, leading/actions/footer/children | layout DOM; selection/open callbacks; no business writes | `<WorkspaceLayout title={m.title()}>{m.content()}</WorkspaceLayout>` |
234
+ | FileUpload / ImageUpload / AvatarUpload / FileList | accept/size limits, File values, uploadHandler, files | selected files/progress/result URL and delete/download callbacks | `<ImageUpload bind:value={imageUrl} uploadHandler={uploadImage} />` |
235
+ | AuthPanel / AuthShell / LoginForm / RegisterForm / password forms / PermGuard | public IAM config, standard actions, errors, permission context | authenticated/submit/reset callbacks; server still authorizes | `<AuthPanel {config} {actions} />` |
236
+ | UserProfile / SensitiveOperationsForm / ReauthenticationDialog / SessionRecoveryDialog | profile or operations, async submit, current controller/state | UserProfile closes only on true; other confirmations report explicit completion | `<UserProfile {user} editable onsubmit={saveProfile} />` |
237
+ | CrudPage / CrudFilterBar / CrudEditPanel / CrudDetailPanel / CrudDeleteConfirm | CrudDef, data/nav, loading/error/permissions, API callbacks | resource-bound query/edit/delete callbacks; server enforces resource access | `<CrudPage {crud} data={controller.data} nav={controller.nav} />` |
238
+ | MarkdownRenderer / AiDocumentEditor / AiTableEditor / AiDocumentDownloadMenu | content or columns/rows, action callbacks, safe HTML options | Markdown HTML, content/cell changes and explicit download/run requests | `<MarkdownRenderer content={markdown} allowHtmlTags={false} />` |
239
+ | EncryptedInput / HashDisplay / SignatureDisplay | plaintext/hash/signature, algorithm label, real onencrypt callback | display DOM; bound encryptedValue only after current request succeeds | `<EncryptedInput bind:value={plain} bind:encryptedValue={cipher} onencrypt={encrypt} />` |
240
+ | FeedbackModal / FeedbackForm / FeedbackList / FeedbackDetail / FeedbackScreenshot | prepared evidence, attachments, rows/report, permissions and actions | submission/query/status/export/retry/annotation callbacks | `<FeedbackForm attachments={attachments} onsubmit={submitFeedback} />` |
241
+ | Chart / DashboardGrid / MetricCard / ReportCard | chart data/preset and raw chart props; metrics and loading state | rendered chart/dashboard; native chart callbacks pass through | `<MetricCard title={m.revenue()} value={revenue} trend={growth} />` |
242
+ | GuideHost / HelpCenter | GuideController, locale/scope, articles/tours | onboarding/help UI; start/close callbacks and nonsensitive preferences | `<GuideHost {guide} scope={user.id} locale={locale} />` |
243
+
139
244
  ### 组件架构
140
245
 
141
246
  组件按三层划分(primitives → compounds → scenes):
@@ -155,7 +260,7 @@ components/
155
260
 
156
261
  ### 组件清单
157
262
 
158
- #### 原子组件 Primitives(20 个)
263
+ #### 原子组件 Primitives
159
264
 
160
265
  | 组件 | 描述 | 主要属性 |
161
266
  | ---------------- | ------------ | ------------------------------------------------------------------ |
@@ -180,9 +285,11 @@ components/
180
285
  | `Spinner` | 加载动画 | `size`, `variant` |
181
286
  | `Progress` | 进度条 | `value`, `max`, `variant`, `striped`, `animated` |
182
287
 
288
+ `Checkbox`、`Switch` 和 `Radio` 默认使用主题主色,选中态跟随当前 DaisyUI 主题;`Checkbox` 可用 `checkbox-*` 类名覆盖颜色。
289
+
183
290
  `BareInput` 的 `file` 类型通过 `onchange` 读取 `event.currentTarget.files`,不绑定文件路径 `value`;其他输入类型可使用 `bind:value`。
184
291
 
185
- #### 组合组件 Compounds(37 个)
292
+ #### 组合组件 Compounds
186
293
 
187
294
  ##### 表单
188
295
 
@@ -209,6 +316,8 @@ components/
209
316
 
210
317
  `UserProfile.fieldConstraints` 按字段接收 `required`、`minlength`、`maxlength`、`pattern` 和 `validationMessage`(`pattern` 用于单行输入),让应用的用户名等业务规则复用失焦校验;`validationMessage` 支持延迟翻译函数。
211
318
 
319
+ `UserProfile.onsubmit` 必须返回 `true` 确认保存成功,返回 `false` 时保留编辑器和草稿;抛错也保留草稿并通过统一 Toast 提示。取消编辑恢复 `user` 中已保存的值。
320
+
212
321
  `CrudEditPanel.onsubmit` 只接收表单声明的可写字段,编辑时排除 `readonly` 字段;新建时仍可填写该字段。主键、关联展示值和审计时间不从整行记录自动回传,空值、`false` 和 `0` 保持原值。服务端继续使用严格 schema 校验。
213
322
 
214
323
  `LoginForm`、`RegisterForm`、`ChangePasswordForm`、`ForgotPasswordForm`、`ResetPasswordForm`、`AuthPanel`、`UserProfile` 和 `FeedbackModal` 接受同一组布局参数。`CrudPage` 通过 `form` 传入;`CrudEditPanel` 直接接收。CRUD 字段支持 `colSpan`,`validation.message` 支持翻译函数;按钮与回车均先校验,修正后错误消失,客户端校验不能替代服务端校验。
@@ -242,6 +351,10 @@ components/
242
351
  | `Confirm` | 确认框 | `open`, `title`, `message`, `variant`, `onconfirm` |
243
352
  | `Popover` | 弹出层 | `open`, `position`, `trigger`, `offset`, `portal` |
244
353
 
354
+ `Popover` 默认挂载到 `body`。在 `click` 模式下按 Enter 或空格打开后,焦点进入面板,按 Escape 关闭并返回触发控件。需要内联挂载时使用 `portal={false}`。
355
+
356
+ 在 Modal/Drawer 内,Popover 的 portal 内容参与所属弹窗的 Tab 与 Shift+Tab 顺序,保持在模态边界内;关闭后撤销登记并恢复触发位置。
357
+
245
358
  ##### 数据展示
246
359
 
247
360
  | 组件 | 描述 | 主要属性 |
@@ -283,7 +396,9 @@ components/
283
396
  | `Breadcrumb` | 面包屑 | `items`, `separator` |
284
397
  | `Steps` | 步骤条 | `items`, `current`, `direction`, `clickable` |
285
398
  | `Dropdown` | 下拉菜单 | `items`, `trigger`, `triggerClass`, `position` |
286
- | `Tooltip` | 提示 | `content`, `position`, `delay` |
399
+ | `Tooltip` | 提示 | `content`, `position`, `delay`, `portal`(裁剪容器内使用) |
400
+
401
+ `Dropdown` 的 `click` 和 `hover` 模式将菜单挂载到 `body`。在 `manual` 模式下,调用方通过 `class` 切换 `dropdown-open` 来控制内联菜单。
287
402
 
288
403
  ##### 状态占位
289
404
 
@@ -299,16 +414,40 @@ components/
299
414
  | ------------ | -------- | ------------------------------------------- |
300
415
  | `PageHeader` | 页面头部 | `title`, `description`,支持 `actions` 插槽 |
301
416
 
302
- #### 场景组件 Scenes(43 个)
417
+ #### 场景组件 Scenes
418
+
419
+ ##### 代码工作区
303
420
 
304
- ##### Guide 引导与帮助(2 个)
421
+ 用 `CodeWorkspace` 浏览只读源码。最小接入只需提供目录列表和文件内容。目录回调收到 `null` 时返回根节点。打开文件即创建标签,标签按文件 ID 和版本复用,切换时恢复近期查看过的文件的光标与滚动位置。
422
+
423
+ ```svelte
424
+ <script lang="ts">
425
+ import type { CodeWorkspaceSource } from '@h-ai/ui/components/scenes/code/index'
426
+ import { CodeWorkspace } from '@h-ai/ui/components/scenes/code/index'
427
+
428
+ const source: CodeWorkspaceSource = {
429
+ listChildren: () => [{ kind: 'file', id: 'readme', name: 'README.md' }],
430
+ readFile: () => ({ text: '# Hello', language: 'markdown' }),
431
+ }
432
+ </script>
433
+
434
+ <CodeWorkspace {source} />
435
+ ```
436
+
437
+ 传入 `source.search` 启用文件名和工作区内容搜索,返回 `nextCursor` 时可继续加载。文件或目录上的 `markers` 展示风险和 Git 状态,`readFile` 返回的 `annotations` 可标记行或范围。传入 `inspector` 和 `selectionActions` snippet 连接右侧检查区及选区浮动操作。更多用法见[代码工作区接入](../../docs/usage/development/ui.md#代码工作区)。
438
+
439
+ Monaco 和同源 worker 由 Vite 在浏览器按需加载。主题默认跟随 Hai,可选预设或传自定义配色。同页 Monaco 编辑器共享主题。移动端和编辑器加载失败时提供纯文本浏览。
440
+
441
+ 行前图标由 `annotationIcon` Snippet 自定义。悬停时优先显示标注的 `hoverText`,否则使用 `annotationHover` Snippet,支持交互组件。按 Enter 可进入浮层,按 Escape 关闭。
442
+
443
+ ##### Guide 引导与帮助
305
444
 
306
445
  | 组件 | 描述 | 主要属性 |
307
446
  | --- | --- | --- |
308
447
  | `GuideHost` | 首次邀请、页面导览与帮助弹窗宿主 | `guide`, `locale`, `scope`, `autoStart` |
309
448
  | `HelpCenter` | 可独立使用的帮助中心 | `articles`, `tours`, `locale`, `selectedId`, `onstart` |
310
449
 
311
- ##### App 应用级(13 个)
450
+ ##### App 应用级
312
451
 
313
452
  | 组件 | 描述 | 主要属性 |
314
453
  | ---------------- | ---------------- | ------------------ |
@@ -328,7 +467,7 @@ components/
328
467
 
329
468
  反馈说明可为空;宿主先用 `@h-ai/feedback/client` 的 `prepare()` 固定现场,再打开弹窗。表单通过 `onfileschange` 准备主动附件、通过 `onannotate` 将标注烧录到图片;受理失败保留输入并可本地导出。列表展示说明或服务端事实摘要,以 `onquerychange` 取得分页数据;界面权限不代替服务端授权。完整接入与离线工具见 [feedback 模块](../feedback/README.md)。
330
469
 
331
- ##### IAM 身份认证(13 个)
470
+ ##### IAM 身份认证
332
471
 
333
472
  | 组件 | 描述 | 主要属性 |
334
473
  | -------------------- | ---------- | ----------------------------------------------------- |
@@ -346,7 +485,7 @@ components/
346
485
  | `SessionRecoveryDialog` | 原地会话恢复 | `recovery`, `actions` |
347
486
  | `SensitiveOperationsForm` | 权限敏感操作编辑 | `operations`, `onsubmit`, `ondone` |
348
487
 
349
- ##### Storage 存储(4 个)
488
+ ##### Storage 存储
350
489
 
351
490
  | 组件 | 描述 | 主要属性 |
352
491
  | -------------- | -------- | -------------------------------------------------------- |
@@ -357,7 +496,7 @@ components/
357
496
 
358
497
  上传组件不内置 presign、请求头或 PUT/POST 协议。应用层通过 `uploadHandler(file, { signal, onProgress })` 调用自己的 service,并返回 `{ url?, response? }`;图片和头像上传需要返回可展示的 `url`。未提供 handler 时,`FileUpload` 只选择文件,图片/头像组件只生成本地预览。
359
498
 
360
- ##### Crypto 加密展示(3 个)
499
+ ##### Crypto 加密展示
361
500
 
362
501
  输入变化立即清空 `encryptedValue`,只有当前输入的成功结果会回填;清空、回调替换和卸载均使旧请求失效。失败显示内置错误提示且密文保持为空;表单应仅在当前密文非空时提交需要加密的输入。
363
502
 
@@ -371,7 +510,7 @@ components/
371
510
 
372
511
  默认算法与 `@h-ai/crypto` 对齐:加密输入使用 `SM4`,哈希展示使用 `SM3`,签名展示使用 `SM2`。
373
512
 
374
- ##### AI 文档与表格(4 个)
513
+ ##### AI 文档与表格
375
514
 
376
515
  | 组件 | 描述 | 主要属性 / 能力 |
377
516
  | ------------------------ | ---------------- | ---------------- |
@@ -406,6 +545,26 @@ components/
406
545
 
407
546
  ##### Charts 图表
408
547
 
548
+ 轻量看板由 `MetricCard`(数值、单位、百分比变化)、`ReportCard`(标题、操作、内容、加载/空态)和 `DashboardGrid`(按容器宽度收拢为一/二/多列)组成。指标卡自身不加载图形引擎;`trend={12.8}` 表示 +12.8%,`trendTone` 独立表达业务好坏,下降也可以是 success。缺失或非有限数显示“—”,零值正常显示。
549
+
550
+ `Chart.preset` 支持:`grouped-bar`、`stacked-bar`、`stacked-area`、`donut`、`sparkline`。预设补默认图形类型和配置,显式 `type` 及原生属性优先;例如 `innerRadius={0.8}` 覆盖环形默认半径。其他 LayerChart 属性与 snippet 继续透传。
551
+
552
+ 按类型动态加载渲染器;SSR 保留高度并显示加载占位,浏览器挂载后绘制。加载态和空数据不加载渲染器。只需要看板组件时优先使用公开 charts 入口。高级图形通过 `ReportCard` 的 children 使用原生 LayerChart,不受 Chart 的五种类型限制;应用需显式依赖兼容的 `layerchart`,按需使用 `layerchart/svg`、`layerchart/hierarchy` 等实际公开入口。用动态组件加载控制高级图形的加载时机,见 admin 的原生 ArcChart 示例。
553
+
554
+ ```svelte
555
+ <script lang="ts">
556
+ import { Chart, DashboardGrid, MetricCard, ReportCard } from '@h-ai/ui/components/scenes/charts/index'
557
+ const data = [{ month: 'Jan', revenue: 42, cost: 24 }, { month: 'Feb', revenue: 58, cost: 31 }]
558
+ </script>
559
+
560
+ <DashboardGrid label="Key metrics" columns={4}>
561
+ <MetricCard title="Revenue" value="128,430" unit="CNY" trend={12.8} trendTone="success" trendLabel="vs previous month" />
562
+ </DashboardGrid>
563
+ <ReportCard title="Revenue and cost">
564
+ <Chart preset="grouped-bar" {data} x="month" y={['revenue', 'cost']} />
565
+ </ReportCard>
566
+ ```
567
+
409
568
  `Chart type='line'` 默认透传 LayerChart 原生折线图;需要监控看板常见的“分段线 + 圆点 + 最近点 hover + 竖向参考线”时,使用 `lineVariant='segmented-point'`:
410
569
 
411
570
  ```svelte
@@ -423,7 +582,7 @@ components/
423
582
  />
424
583
  ```
425
584
 
426
- ##### CRUD 场景(5 个)
585
+ ##### CRUD 场景
427
586
 
428
587
  | 组件 | 描述 | 主要属性 / 能力 |
429
588
  | -------------------- | ------------ | ---------------- |
@@ -440,7 +599,7 @@ components/
440
599
  >
441
600
  > 表格列会优先压缩到 7rem 并截断超长文本;列总宽度仍超过容器时才显示横向滚动条。操作列固定在右侧,横向滚动时保持可见。
442
601
 
443
- ##### 错误页场景(1 个)
602
+ ##### 错误页场景
444
603
 
445
604
  | 组件 | 描述 | 主要属性 / 能力 |
446
605
  | ----------- | ------------ | ---------------- |
@@ -503,7 +662,7 @@ components/
503
662
 
504
663
  状态层可从轻量入口 `@h-ai/ui/toast` 导入 `toast`、`useToastFeedback`、`notifySuccess` / `notifyError` / `notifyInfo` / `notifyWarning` 和 `errorMessage`,不会连带加载组件及引导 CSS;`ToastContainer` 仍从组件入口导入并在根布局挂载。
505
664
 
506
- 默认不显示 traceId。可以传 `toast.add({ message: m.retry(), variant: 'warning', traceId })`;已有安全文案中的 `(traceId: …)` 也会自动分离。小图标展开“问题追踪编号”、复制按钮及联系客户支持或开发人员时提供编号的说明。复制失败时可手动选择编号。悬停、聚焦或展开时暂停计时,结束后继续剩余时间;也可调用 `toast.pause(id)` / `toast.resume(id)`。旧 `Alert` 的 warning/error 用法需迁移到 Toast;字段的可见错误文案也由 Toast 统一展示,保留 aria-invalid、读屏描述和原位恢复操作。
665
+ 默认不显示 traceId。可以传 `toast.add({ message: m.retry(), variant: 'warning', traceId })`;已有安全文案中的 `(traceId: …)` 也会自动分离。小图标展开“问题追踪编号”、复制按钮及联系客户支持或开发人员时提供编号的说明。复制失败时可手动选择编号。悬停、聚焦或展开时暂停计时,结束后继续剩余时间;也可调用 `toast.pause(id)` / `toast.resume(id)`。warning/error 使用 Toast;字段的可见错误文案也由 Toast 统一展示,保留 aria-invalid、读屏描述和原位恢复操作。
507
666
 
508
667
  #### 指定提示方位
509
668
 
@@ -700,6 +859,8 @@ toast.add({ message: m.saved(), position: 'bottom-center' })
700
859
  </div>
701
860
  ```
702
861
 
862
+ `BottomNav` 的导航按钮与 `ThemeSelector` 的主题按钮在客户端挂载后启用,确保点击时事件已绑定。
863
+
703
864
  #### 图标
704
865
 
705
866
  组件使用 Iconify (Tabler Icons):
@@ -717,10 +878,12 @@ npm install -D @iconify/tailwind4 @iconify-json/tabler
717
878
 
718
879
  #### 主题切换
719
880
 
720
- 使用内置的主题工具函数管理 15 个精选 DaisyUI 主题、高对比及直角商务主题:
881
+ 使用内置的主题工具函数管理 15 个精选 DaisyUI 主题、高对比、直角商务及护眼主题:
721
882
 
722
883
  `high-contrast` 随共享 theme.css 提供:黑底亮字、清晰边框/焦点、增强次要文字及占位符对比度。ThemeSelector 提供三语名称;示例与默认生成工程可选择,fullstack 的显式 themes 列表仍由宿主决定。配色按普通文字 7:1 的目标验收,不代表任意业务内容已通过整站无障碍认证。
723
884
 
885
+ `eye-care` 随共享 theme.css 提供暖绿色背景、深色正文、可读占位符与清晰焦点。主题选择器显示“护眼”,示例及默认模板可直接选择,刷新后保留偏好;现有默认主题及 fullstack 显式 themes 白名单不变。
886
+
724
887
  `formal` 提供直角的商务外观,按钮、输入框、卡片与弹窗不使用装饰性圆角;主题选择器提供三语名称,示例和默认模板可选择。Button 的 submitHint 仅在 type=submit 时显示原生 Enter 提示,不绑定全局快捷键;LoginForm 默认在桌面首次就绪且页面无焦点时聚焦标识,autoFocus=false 可关闭。筛选 Enter 即时查询且忽略输入法确认;主题菜单支持方向键/Home/End、Enter/Space 及 Esc 恢复焦点;确认框默认聚焦取消,Esc 同步取消状态。
725
888
 
726
889
  ```ts
@@ -734,7 +897,7 @@ import {
734
897
  normalizeHexColor, // 归一化 #RGB / #RRGGBB 主题色
735
898
  normalizeThemeId, // 校验主题 ID 并自动回退
736
899
  THEME_GROUPS, // 按亮色/暗色分组
737
- THEMES, // ThemeInfo[] — 17 个主题元数据
900
+ THEMES, // ThemeInfo[] — 18 个主题元数据
738
901
  } from '@h-ai/ui/theme'
739
902
  ```
740
903
 
@@ -755,7 +918,6 @@ import { createThemeBootstrapScript, DEFAULT_THEME_COLOR_CSS_VAR } from '@h-ai/u
755
918
 
756
919
  const themeBootstrapScript = createThemeBootstrapScript({
757
920
  storageKey: 'hai-demo-preferences',
758
- legacyThemeStorageKey: 'hai-demo-theme',
759
921
  defaultThemeColor: '#5765f0',
760
922
  colorCssVar: DEFAULT_THEME_COLOR_CSS_VAR,
761
923
  })
@@ -779,7 +941,7 @@ transformPageChunk: ({ html }) => html.replace('%theme_bootstrap%', themeBootstr
779
941
  ```svelte
780
942
  <script>
781
943
  import { createLocaleStore, setGlobalLocale } from '@h-ai/ui/i18n'
782
- import { setLocale } from '$lib/paraglide/runtime'
944
+ import { setLocale } from '#lib/paraglide/runtime.js'
783
945
 
784
946
  const localeStore = createLocaleStore()
785
947
 
@@ -814,7 +976,6 @@ import {
814
976
  } from '@h-ai/ui/i18n'
815
977
  ```
816
978
 
817
-
818
979
  协议在 Modal 内显示并保留表单输入;使用 URL 时,协议页面须允许 iframe 嵌入,组件禁用其脚本,另提供新窗口查看入口。登录/注册表单使用 `header/extraFields/footer` snippet,AuthPanel 透传 `loginHeader/loginFields/loginFooter` 和 `registerHeader/registerFields/registerFooter`,底部保留内置导航。自定义字段由应用绑定状态和提交,不会隐式写入 IAM 用户模型。
819
980
 
820
981
  ```svelte
@@ -858,11 +1019,9 @@ agreements:
858
1019
  # privacyPolicyUrl: https://example.com/privacy
859
1020
  ```
860
1021
 
861
-
862
-
863
1022
  AuthPanel 直接接收 IAM 白名单配置和 actions,内置登录(密码/LDAP/邮件/短信)、注册、找回、重置及协议展示。使用 `config.ui` 配置卡片/分栏、标题、品牌、Logo 和配图。`LoginForm` 提供 methods、onsendotp、otpLength、resendInterval;密码表单接受 passwordPolicy。组件只渲染与交互,网络和 Token 存储通过 actions 注入。
864
1023
 
865
- 认证错误统一使用 `authErrorMessage(error)`(从 `@h-ai/ui/components/scenes/iam/index` 导入):按公开错误码显示当前 UI 语言,凭据错误统一为“用户名或密码不正确”,未知错误及服务异常不显示原文,保留有效 `traceId`。AuthPanel、验证码发送、敏感操作确认与 fullstack 改密共用此映射。首次改密、密码过期、当前密码复用(`hai:iam:034`)和会话上限各有操作指引;操作成功和错误均使用统一 Toast。确认密码与服务端一样逐字符比较,不归一化 Unicode 或裁剪空白,输入不一致时由 Toast 提示,并保留字段关联。
1024
+ 认证错误统一使用 `authErrorMessage(error)`(从 `@h-ai/ui/components/scenes/iam/index` 导入):按公开错误码显示当前 UI 语言,凭据错误统一为“用户名或密码不正确”,未知错误及服务异常不显示原文,保留有效 `traceId`。AuthPanel、验证码发送、敏感操作确认与 fullstack 改密共用此映射。首次改密、密码过期、当前密码复用(`hai:iam:034`)和会话上限各有操作指引;操作成功和错误均使用统一 Toast。确认密码与服务端一样逐字符比较,不归一化 Unicode 或裁剪空白,输入不一致时由 Toast 提示,并保留字段关联。Kit 和 API Client 确认的时间窗口错误会在认证提示中显示服务器 UTC 时间及校时建议。
866
1025
 
867
1026
  AuthPanel 在 SSR 阶段禁用原生表单控件,客户端挂载并绑定事件后自动开放输入,避免接管时丢失早到的输入。应用无需额外的就绪适配;E2E 等待控件可编辑,并覆盖客户端脚本延迟加载的场景。
868
1027
 
@@ -969,7 +1128,6 @@ import { cn, generateId, getSizeClass, getVariantClass } from '@h-ai/ui'
969
1128
  import { toast } from '@h-ai/ui'
970
1129
  ```
971
1130
 
972
-
973
1131
  组件子路径只开放 package.exports 明确列出的 barrel,例如 `@h-ai/ui/components/primitives/index`;不开放任意组件实现或内部存储辅助函数。宿主剪贴板注册仍是公开能力。
974
1132
 
975
1133
  ### 请求语言隔离
@@ -978,17 +1136,17 @@ Node 请求与 SSR 使用 `core.i18n.runWithLocale(locale, () => handleRequest()
978
1136
 
979
1137
  浏览器继续使用应用级 `setGlobalLocale` / `createLocaleStore`。SSR 的 UI store 初始化和 setter 只修改自身状态,不写全局语言;UI 消息从请求上下文读取。`runWithLocale` 仅支持 Node 入口,浏览器通过显式 locale 或应用状态翻译。
980
1138
 
981
- ## 输入约束与 HTTP 能力
1139
+ ### 输入约束与 HTTP 能力
982
1140
 
983
1141
  存储 key 按 UTF-8 最多 1024 字节,并拒绝绝对路径、反斜线、控制字符及点路径段;公开 HTTP 批量删除每次 1–1000 项。`@h-ai/storage/schemas` 提供浏览器安全的共同规则。预签名有效期为整数 1–604800 秒(Node 默认 3600,HTTP 默认 900);HTTP 上传仅接受 key/contentType/expiresIn,不支持 contentLength/maxSize/metadata/checksum。无效输入返回 HTTP 400,typed client 映射 VALIDATION_FAILED。FileUpload 的大小/类型限制仅为前端体验,实际对象须由应用服务端复核。Node 流式读写/checksum/条件写等没有默认 HTTP 端点。完整映射与授权边界见 [存储 API 能力](../storage/README.md#存储输入约束与跨端能力)。
984
1142
 
985
- ## 紧凑工作区与可收起筛选
1143
+ ### 紧凑工作区与可收起筛选
986
1144
 
987
1145
  `WorkspaceLayout` 统一导航、内容区和可选页脚:顶栏采用紧凑高度,主内容使用 12/16px 内边距;没有页脚时不预留高度。通过 `title` 提供导航中的页面标题,`leading/actions/footer` 为 snippet,`data-*` 透传内容 main。父布局需传递剩余高度及 min-height: 0。
988
1146
 
989
1147
  同名 `PageHeader` 自动省略重复标题,保留说明和操作;`SettingsLayout` 复用该行为。工作区中的 `CrudPage` 默认不重复显示页面标题,操作并入工具栏;独立使用仍显示标题,可用 `showHeader` 显式覆盖。
990
1148
 
991
- `FilterBar` 的 leading 和 actions 保持可见,children 默认收起,`bind:expanded` 控制展开,`activeCount` 提示已启用条件,`onreset` 提供内置三语重置按钮。收起保留控件和值;重置和请求逻辑由宿主回调处理。`TableToolbar` 复用该布局并提供原生查询表单,`CrudFilterBar` 复用相同实现;`onsearch` 在提交时读取当前绑定的搜索和筛选草稿,`onfilterchange` 只通知草稿变化。`onreset`(TableToolbar 使用 `onclearfilters`)必须同步清空宿主已提交条件并重新查询。旧 `toolbarStyle`、排序弹层及 TableToolbar 的排序属性已移除;请使用 DataTable 的 `sortKey`、`sortDir`、`onsort`。 扩展筛选按容器宽度自适应为 1/2/4/6 列,字段横向间距 20px、纵向间距 16px,标签和控件分别对齐;日期范围占两列,窄屏占整行。
1149
+ `FilterBar` 的 leading 和 actions 保持可见,children 默认收起,`bind:expanded` 控制展开,`activeCount` 提示已启用条件,`onreset` 提供内置三语重置按钮。收起保留控件和值;重置和请求逻辑由宿主回调处理。`TableToolbar` 复用该布局并提供原生查询表单,`CrudFilterBar` 复用相同实现;`onsearch` 在提交时读取当前绑定的搜索和筛选草稿,`onfilterchange` 只通知草稿变化。`onreset`(TableToolbar 使用 `onclearfilters`)必须同步清空宿主已提交条件并重新查询。列表排序使用 DataTable 的 `sortKey`、`sortDir`、`onsort`。 扩展筛选按容器宽度自适应为 1/2/4/6 列,字段横向间距 20px、纵向间距 16px,标签和控件分别对齐;日期范围占两列,窄屏占整行。
992
1150
 
993
1151
  下例的 m、statusOptions、clearFilters 和 loadRows 由业务应用提供;清空回调须重置搜索及全部条件。
994
1152
 
@@ -1010,23 +1168,44 @@ Node 请求与 SSR 使用 `core.i18n.runWithLocale(locale, () => handleRequest()
1010
1168
  </div>
1011
1169
  ```
1012
1170
 
1013
- ## 设计与交互验收
1171
+ ### 设计与交互验收
1014
1172
 
1015
1173
  页面设计使用 [hai-ui-design](../cli/templates/skills/hai-ui-design/SKILL.md),组件实现使用 [hai-ui](../cli/templates/skills/hai-ui/SKILL.md),真实界面走查使用 [hai-ui-review](../cli/templates/skills/hai-ui-review/SKILL.md)。[设计约定](../../.agents/instructions/ui-design.md) 说明布局、状态和示例。
1016
1174
 
1017
1175
  Tabs 支持方向键/Home/End、禁用项跳过和单一 Tab 入口;表格提供排序与加载状态和行键盘操作;分页导航/输入名称跟随语言,外部页码同步跳页输入;筛选展开遵循文档焦点顺序,视图按钮提供选中状态。Empty/Alert 支持长内容换行。theme.css 引入共享 tokens,焦点跟随当前主题,global.css 响应减少动态效果。应用仍需接入实际筛选、排序、分页与失败恢复。
1018
1176
 
1019
- ## 错误提示与关联日志
1177
+ ### 可选交互挑战
1020
1178
 
1021
- HTTP 错误返回安全本地化文案及追踪编号;ToastContainer 默认只显示可读说明,编号由排查图标展开和复制。响应同时包含 `error.traceId` 和 `X-Trace-Id`。框架复用本次 requestId 作为 traceId,前后端日志自动关联。底层异常、堆栈和操作上下文经凭据脱敏后写入日志,不通过 cause/ext 向用户公开。字段校验只返回本地化的字段名和错误。
1179
+ AuthPanel 在 config.captcha.enabled 时通过 actions.createCaptcha 自动生成并异步求解自托管 ALTCHA,按 login/register/sendOtp/passwordReset/renewPassword 用途提交单用证明;关闭时不加载求解器。createAuthActions 已提供动作,自定义动作须保留 captcha,缺少动作时不放行。证明仅存在当前请求内存,服务端始终校验与消费。
1022
1180
 
1023
- `core.error.toPublic(error, traceId?)` 用于接口/UI 边界;`core.error.formatMessage(error)` 用于重新翻译后的提示,重复调用不会重复追加标识。日志传入完整 Error 对象,不能只记录通用标题或提前 String(error) 丢失上下文。数据库失败记录驱动错误码、消息、堆栈及表/列;SQL 原文、绑定值和连接凭据不进入日志。
1181
+ 策略、默认值和恢复边界见 [IAM](../iam/README.md)。
1024
1182
 
1025
- ## 可选交互挑战
1183
+ ## 配置
1026
1184
 
1027
- AuthPanel 在 config.captcha.enabled 时通过 actions.createCaptcha 自动生成并异步求解自托管 ALTCHA,按 login/register/sendOtp/passwordReset/renewPassword 用途提交单用证明;关闭时不加载求解器。createAuthActions 已提供动作,自定义动作须保留 captcha,缺少动作时不放行。证明仅存在当前请求内存,服务端始终校验与消费。
1185
+ ### 按场景选择配置入口
1028
1186
 
1029
- 策略、默认值和恢复边界见 [IAM](../iam/README.md)。
1187
+ | 配置入口 | 场景 | 输入 | 生效结果 | 示例 |
1188
+ | --- | --- | --- | --- | --- |
1189
+ | `Component Props` | 控制渲染与交互 | typed props, bound values, callbacks, children snippets | DOM, bindings and callback events | `<Input bind:value={draft} />` |
1190
+ | `Theme` | 主题与颜色 | supported theme ID, color values, preference key | DOM theme/CSS variables; nonsensitive browser preference | `applyTheme("light")` |
1191
+ | `Locale` | 界面语言 | supportedLocales, defaultLocale, persistKey, detectBrowser | component-tree locale; isolated SSR state | `createLocaleStore({ defaultLocale: "ja-JP", detectBrowser: false })` |
1192
+ | `Guide` | 帮助与首次引导 | tours, articles, nonsecret scope/version, nav adapter | guide/help state and nonsensitive progress | `createGuide({ tours: [], persistence: "memory" })` |
1193
+ | `CRUD` | 资源字段与 API | CrudResource fields/API callbacks and controller options | resource view model; API must implement authorization | `createCrudController(crud, { autoLoad: false })` |
1194
+ | `Authentication` | 公开认证配置 | IAM-whitelisted config and standard actions | AuthPanel submits to host actions; no secret persistence | `<AuthPanel {config} {actions} />` |
1195
+
1196
+ 使用 pnpm 构建 Svelte 应用时,工程需要在 `patchedDependencies` 注册 `deepmerge@4.3.1` 对应的补丁,并保留实际 patch 文件;采用 DaisyUI 时同样保留其样式补丁。CLI 生成工程已携带适用项。安装框架 npm 包不会把框架仓库的 pnpm 补丁配置自动传递到你的工程,手工接入应同步[补丁目录](../../patches/)及相应注册后重新安装依赖。
1197
+
1198
+ 本包是 Svelte 组件与工具库,无 init/close。输入由组件 Props、事件回调与主题参数传入;组件输出为界面、绑定值和回调事件。先按快速开始装配 Tailwind/DaisyUI 与预处理器,再选择下文组件。没有统一的 `_ui.yml`,不要把组件属性误写为模块环境变量。
1199
+
1200
+ ## 错误处理
1201
+
1202
+ 组件的 loading/error 与业务完成状态由宿主提供。业务接口返回 HaiResult 时,在应用适配层先检查 success,再传入安全本地化文案;UI 工具本身遵循表中的直接返回值,不统一包装 HaiResult。未知异常交给 notifyError/errorMessage 隐藏内部原文。downloadAiDocument 等异步浏览器工具会拒绝 Promise,必须由交互边界捕获并释放 loading。UserProfile.onsubmit 只有返回 true 才结束编辑。
1203
+
1204
+ ### 错误提示与关联日志
1205
+
1206
+ HTTP 错误返回安全本地化文案及追踪编号;ToastContainer 默认只显示可读说明,编号由排查图标展开和复制。响应同时包含 `error.traceId` 和 `X-Trace-Id`。框架复用本次 requestId 作为 traceId,前后端日志自动关联。底层异常、堆栈和操作上下文经凭据脱敏后写入日志,不通过 cause/ext 向用户公开。字段校验只返回本地化的字段名和错误。
1207
+
1208
+ `core.error.toPublic(error, traceId?)` 用于接口/UI 边界;`core.error.formatMessage(error)` 用于重新翻译后的提示,重复调用不会重复追加标识。日志传入完整 Error 对象,不能只记录通用标题或提前 String(error) 丢失上下文。数据库失败记录驱动错误码、消息、堆栈及表/列;SQL 原文、绑定值和连接凭据不进入日志。
1030
1209
 
1031
1210
  ## 开发测试
1032
1211
 
package/auto-import.d.ts CHANGED
@@ -16,6 +16,10 @@ type AutoImportHaiUiPreprocessor = {
16
16
  export function autoImportHaiUi(): AutoImportHaiUiPreprocessor
17
17
 
18
18
  declare global {
19
+ const Chart: typeof import('@h-ai/ui')['Chart']
20
+ const DashboardGrid: typeof import('@h-ai/ui')['DashboardGrid']
21
+ const MetricCard: typeof import('@h-ai/ui')['MetricCard']
22
+ const ReportCard: typeof import('@h-ai/ui')['ReportCard']
19
23
  const GuideHost: typeof import('@h-ai/ui')['GuideHost']
20
24
  const HelpCenter: typeof import('@h-ai/ui')['HelpCenter']
21
25
  // primitives
@@ -68,6 +72,7 @@ declare global {
68
72
  const PageHeader: typeof import('@h-ai/ui')['PageHeader']
69
73
  const FilterBar: typeof import('@h-ai/ui')['FilterBar']
70
74
  const WorkspaceLayout: typeof import('@h-ai/ui')['WorkspaceLayout']
75
+ const CodeWorkspace: typeof import('@h-ai/ui')['CodeWorkspace']
71
76
  const Pagination: typeof import('@h-ai/ui')['Pagination']
72
77
  const Popover: typeof import('@h-ai/ui')['Popover']
73
78
  const PullRefresh: typeof import('@h-ai/ui')['PullRefresh']