@h-ai/ui 1.0.0-beta.2 → 1.0.0-beta.21

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 (167) hide show
  1. package/README.en.md +252 -70
  2. package/README.ja.md +251 -69
  3. package/README.md +253 -72
  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 +40 -12
  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/editor-markdown-extensions.js +9 -3
  46. package/dist/components/scenes/ai/highlight.js +18 -1
  47. package/dist/components/scenes/ai/markdown-parse.js +81 -28
  48. package/dist/components/scenes/ai/mermaid-render.js +13 -1
  49. package/dist/components/scenes/ai/safe-html.js +9 -3
  50. package/dist/components/scenes/ai/table/AiTableEditor.svelte +27 -9
  51. package/dist/components/scenes/app/FeedbackDetail.svelte +102 -24
  52. package/dist/components/scenes/app/FeedbackForm.svelte +70 -16
  53. package/dist/components/scenes/app/FeedbackList.svelte +138 -21
  54. package/dist/components/scenes/app/FeedbackRecorder.svelte +18 -5
  55. package/dist/components/scenes/app/FeedbackReplay.svelte +15 -3
  56. package/dist/components/scenes/app/FeedbackScreenshot.svelte +64 -13
  57. package/dist/components/scenes/app/LanguageSwitch.svelte +6 -2
  58. package/dist/components/scenes/app/SettingsLayout.svelte +3 -1
  59. package/dist/components/scenes/app/ThemeSelector.svelte +29 -5
  60. package/dist/components/scenes/app/ThemeToggle.svelte +6 -2
  61. package/dist/components/scenes/app/WorkspaceLayout.svelte +1 -1
  62. package/dist/components/scenes/app/feedback-functions.js +6 -2
  63. package/dist/components/scenes/charts/Chart.svelte +55 -21
  64. package/dist/components/scenes/charts/Chart.svelte.d.ts +0 -1
  65. package/dist/components/scenes/charts/ChartLoadError.svelte +13 -0
  66. package/dist/components/scenes/charts/ChartLoadError.svelte.d.ts +6 -0
  67. package/dist/components/scenes/charts/DashboardGrid.svelte +34 -0
  68. package/dist/components/scenes/charts/DashboardGrid.svelte.d.ts +15 -0
  69. package/dist/components/scenes/charts/MetricCard.svelte +69 -0
  70. package/dist/components/scenes/charts/MetricCard.svelte.d.ts +15 -0
  71. package/dist/components/scenes/charts/ReportCard.svelte +48 -0
  72. package/dist/components/scenes/charts/ReportCard.svelte.d.ts +15 -0
  73. package/dist/components/scenes/charts/chart-presets.d.ts +15 -0
  74. package/dist/components/scenes/charts/chart-presets.js +56 -0
  75. package/dist/components/scenes/charts/chart-types.d.ts +13 -2
  76. package/dist/components/scenes/charts/dashboard-types.d.ts +79 -0
  77. package/dist/components/scenes/charts/dashboard-types.js +1 -0
  78. package/dist/components/scenes/charts/index.d.ts +6 -2
  79. package/dist/components/scenes/charts/index.js +4 -1
  80. package/dist/components/scenes/charts/renderers/AreaChart.svelte +1 -0
  81. package/dist/components/scenes/charts/renderers/AreaChart.svelte.d.ts +1 -0
  82. package/dist/components/scenes/charts/renderers/BarChart.svelte +1 -0
  83. package/dist/components/scenes/charts/renderers/BarChart.svelte.d.ts +1 -0
  84. package/dist/components/scenes/charts/renderers/LineChart.svelte +39 -12
  85. package/dist/components/scenes/charts/renderers/LineChart.svelte.d.ts +1 -0
  86. package/dist/components/scenes/charts/renderers/PieChart.svelte +1 -0
  87. package/dist/components/scenes/charts/renderers/PieChart.svelte.d.ts +1 -0
  88. package/dist/components/scenes/charts/renderers/ScatterChart.svelte +1 -0
  89. package/dist/components/scenes/charts/renderers/ScatterChart.svelte.d.ts +1 -0
  90. package/dist/components/scenes/code/CodeWorkspace.svelte +946 -0
  91. package/dist/components/scenes/code/CodeWorkspace.svelte.d.ts +21 -0
  92. package/dist/components/scenes/code/CodeWorkspaceEditor.svelte +737 -0
  93. package/dist/components/scenes/code/CodeWorkspaceEditor.svelte.d.ts +37 -0
  94. package/dist/components/scenes/code/CodeWorkspaceGutter.svelte +246 -0
  95. package/dist/components/scenes/code/CodeWorkspaceGutter.svelte.d.ts +23 -0
  96. package/dist/components/scenes/code/CodeWorkspaceSearch.svelte +234 -0
  97. package/dist/components/scenes/code/CodeWorkspaceSearch.svelte.d.ts +23 -0
  98. package/dist/components/scenes/code/CodeWorkspaceTree.svelte +519 -0
  99. package/dist/components/scenes/code/CodeWorkspaceTree.svelte.d.ts +26 -0
  100. package/dist/components/scenes/code/code-editor.d.ts +12 -0
  101. package/dist/components/scenes/code/code-editor.js +93 -0
  102. package/dist/components/scenes/code/code-types.d.ts +346 -0
  103. package/dist/components/scenes/code/code-types.js +1 -0
  104. package/dist/components/scenes/code/index.d.ts +2 -0
  105. package/dist/components/scenes/code/index.js +1 -0
  106. package/dist/components/scenes/code/workers/css.worker.d.ts +1 -0
  107. package/dist/components/scenes/code/workers/css.worker.js +1 -0
  108. package/dist/components/scenes/code/workers/editor.worker.d.ts +1 -0
  109. package/dist/components/scenes/code/workers/editor.worker.js +1 -0
  110. package/dist/components/scenes/code/workers/html.worker.d.ts +1 -0
  111. package/dist/components/scenes/code/workers/html.worker.js +1 -0
  112. package/dist/components/scenes/code/workers/json.worker.d.ts +1 -0
  113. package/dist/components/scenes/code/workers/json.worker.js +1 -0
  114. package/dist/components/scenes/code/workers/ts.worker.d.ts +1 -0
  115. package/dist/components/scenes/code/workers/ts.worker.js +1 -0
  116. package/dist/components/scenes/crud/CrudDetailDrawer.svelte +6 -2
  117. package/dist/components/scenes/crud/CrudDetailPanel.svelte +6 -2
  118. package/dist/components/scenes/crud/CrudEditPanel.svelte +41 -12
  119. package/dist/components/scenes/crud/CrudPage.svelte +34 -9
  120. package/dist/components/scenes/crud/crud-controller.svelte.js +23 -8
  121. package/dist/components/scenes/crud/crud-form-validation.js +27 -9
  122. package/dist/components/scenes/crypto/EncryptedInput.svelte +9 -3
  123. package/dist/components/scenes/error/error-presets.js +30 -5
  124. package/dist/components/scenes/guide/GuideHostContent.svelte +7 -1
  125. package/dist/components/scenes/guide/HelpCenter.svelte +23 -4
  126. package/dist/components/scenes/iam/AgreementNotice.svelte +9 -3
  127. package/dist/components/scenes/iam/AuthPanel.svelte +74 -16
  128. package/dist/components/scenes/iam/ChangePasswordForm.svelte +6 -2
  129. package/dist/components/scenes/iam/ForgotPasswordForm.svelte +9 -3
  130. package/dist/components/scenes/iam/LoginForm.svelte +32 -8
  131. package/dist/components/scenes/iam/PasswordInput.svelte +50 -12
  132. package/dist/components/scenes/iam/RegisterForm.svelte +11 -3
  133. package/dist/components/scenes/iam/ResetPasswordForm.svelte +6 -2
  134. package/dist/components/scenes/iam/SensitiveOperationsForm.svelte +3 -1
  135. package/dist/components/scenes/iam/SessionRecoveryDialog.svelte +4 -1
  136. package/dist/components/scenes/iam/UserProfile.svelte +41 -14
  137. package/dist/components/scenes/iam/auth-captcha.js +9 -2
  138. package/dist/components/scenes/iam/auth-error-message.d.ts +2 -2
  139. package/dist/components/scenes/iam/auth-error-message.js +16 -3
  140. package/dist/components/scenes/iam/password-utils.js +9 -2
  141. package/dist/components/scenes/iam/sensitive-actions.svelte.js +4 -1
  142. package/dist/components/scenes/index.d.ts +1 -0
  143. package/dist/components/scenes/index.js +2 -0
  144. package/dist/components/scenes/storage/FileList.svelte +3 -1
  145. package/dist/components/scenes/storage/FileUpload.svelte +7 -2
  146. package/dist/components/scenes/types.d.ts +2 -2
  147. package/dist/guide-storage.js +12 -4
  148. package/dist/guide.svelte.js +59 -16
  149. package/dist/i18n.svelte.js +9 -3
  150. package/dist/internal/dialog-focus.d.ts +19 -0
  151. package/dist/internal/dialog-focus.js +104 -4
  152. package/dist/internal/form-validation.svelte.js +46 -15
  153. package/dist/internal/icon-safety.js +6 -2
  154. package/dist/message.svelte.js +6 -2
  155. package/dist/messagebox.svelte.js +6 -2
  156. package/dist/messages/en-US.json +60 -1
  157. package/dist/messages/ja-JP.json +60 -1
  158. package/dist/messages/zh-CN.json +60 -1
  159. package/dist/styles/eye-care.css +55 -0
  160. package/dist/styles/global.css +16 -0
  161. package/dist/styles/theme.css +1 -0
  162. package/dist/theme-config.d.ts +1 -1
  163. package/dist/theme-config.js +136 -21
  164. package/dist/toast.svelte.js +14 -3
  165. package/dist/types.d.ts +3 -3
  166. package/dist/utils.js +6 -2
  167. package/package.json +25 -19
package/README.en.md CHANGED
@@ -4,21 +4,13 @@
4
4
 
5
5
  [Framework home](../../README.en.md) · Related modules: [@h-ai/core](../core/README.en.md)
6
6
 
7
- ## Introduction
8
-
9
7
  Built-in messages support `zh-CN`, `en-US` and `ja-JP`; the language selector offers all three by default.
10
8
 
11
- A cross-platform Svelte 5 Runes component library with DaisyUI v5 + Tailwind CSS v4 styling and Bits UI v2 headless interactions. Includes built-in i18n (zh-CN / en-US / ja-JP) and 15 curated DaisyUI themes plus high contrast and square business themes.
9
+ A cross-platform Svelte 5 Runes component library with DaisyUI v5 + Tailwind CSS v4 styling and Bits UI v2 headless interactions. Includes built-in i18n (zh-CN / en-US / ja-JP) and 15 curated DaisyUI themes plus high contrast, square business and eye-care themes.
12
10
 
13
- ## Core features
11
+ HTTP/UI boundaries expose business messages only for explicit valid 4xx statuses. Missing or invalid `httpStatus` is treated as 500 with a safe message. Custom business errors must carry a complete error definition or an explicit status.
14
12
 
15
- - Forms, tables, dialogs, navigation, charts and application components.
16
- - Authentication, CRUD, AI content, onboarding and a help center.
17
- - Svelte 5, themes, responsive layouts and Chinese/English/Japanese component messages.
18
-
19
- Markdown underline and highlight markers support escaping; unclosed markers remain text. Toasts and document downloads handle unusually long text without repeated scanning, while trace identifiers remain hidden by default.
20
-
21
- ## Getting started
13
+ ## Quick Start
22
14
 
23
15
  ### Installation
24
16
 
@@ -28,50 +20,45 @@ npm install @h-ai/ui @h-ai/core
28
20
 
29
21
  For a Node server, declare both UI and core as production dependencies so the adapter preserves native logging and runtime dependencies.
30
22
 
31
- ### Quick start
23
+ ### 1. Configure application imports in package.json
32
24
 
33
- #### 1. Configure svelte.config.js
34
-
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. Configure vite.config.ts
46
30
 
47
- export default config
48
- ```
31
+ SvelteKit 3 configures preprocessing, the compiler and the adapter in the Vite plugin; only a plain Svelte/Vite project keeps svelte.config.js.
49
32
 
50
- #### 2. Configure vite.config.ts
33
+ Run `vitePreprocess()` or other style/template language transforms before `autoImportHaiUi()`. Auto-import reads the complete Svelte AST and does not accept unprocessed SCSS, Pug or other nonstandard syntax. Its direct markup API remains synchronous.
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
- When using Crypto or Kit/IAM, include `sm-crypto@0.5.7` in application production dependencies. CLI projects already do this; for manual setup, run `pnpm add sm-crypto@0.5.7`. The external option alone is insufficient: adapter-node also uses direct production dependencies to preserve native package loading.
59
+ ### 3. Configure src/app.css
73
60
 
74
- #### 3. Configure src/app.css
61
+ When using Crypto or Kit/IAM, include `sm-crypto@0.5.8` in application production dependencies. CLI projects already do this; for manual setup, run `pnpm add sm-crypto@0.5.8`. The external option alone is insufficient: adapter-node also uses direct production dependencies to preserve native package loading.
75
62
 
76
63
  ```css
77
64
  @import 'tailwindcss';
@@ -92,7 +79,7 @@ When using Crypto or Kit/IAM, include `sm-crypto@0.5.7` in application productio
92
79
 
93
80
  > `@source` makes TailwindCSS scan classes in `@h-ai/ui`; without it, component styles are missing. In nested monorepo apps, dependencies may be hoisted to root `node_modules`, so retain both paths.
94
81
 
95
- #### 4. Use components
82
+ ### 4. Use components
96
83
 
97
84
  ```svelte
98
85
  <script>
@@ -116,7 +103,7 @@ With auto-import enabled, use components directly in templates without individua
116
103
 
117
104
  Pages using a subset of components, such as administration screens, can import public component-directory entry points directly. Import theme utilities from the lightweight `@h-ai/ui/theme` entry so theme consumers do not load the root entry's AI and chart components. Use `@h-ai/ui/i18n` for locale utilities in stores without loading components or tour CSS. Check the installed package's exports; do not import its internal `src/` or `dist/` paths.
118
105
 
119
- The preprocessor recognizes semicolon-free, multiline and aliased imports without injecting components already bound locally. Type-only imports do not replace runtime components.
106
+ The preprocessor imports only components actually used in the template AST; examples in comments, textarea content and script strings do not trigger imports. Script declarations and local each, await and snippet bindings take precedence. Real semicolon-free, multiline and aliased imports are recognized through the syntax tree, without duplicating existing runtime bindings. Type-only component bindings from the root `@h-ai/ui` entry are promoted to values when needed. A conflicting type-only import from another module causes a build error naming the file and component; alias the type, or explicitly import the component under another local name.
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-\* attribute forwarding
114
+ ## Features
115
+
116
+ ### Purpose, inputs and outputs
117
+
118
+ UI has no init/close. Use these fragments in the application component or browser interaction context. Named variables stand for application-provided requests, schemas, resource definitions or options. Follow the corresponding examples for setup and failure handling. Check HaiResult.success and await asynchronous calls.
119
+
120
+ | Entry | Use case | Input | Output | Call fragment |
121
+ | --- | --- | --- | --- | --- |
122
+ | `autoImportHaiUi` | Auto-import | `preprocessed Svelte source and filename through markup` | `PreprocessorGroup; synchronous { code }` | `autoImportHaiUi()` |
123
+ | `parseMarkdown` | Safe Markdown | `Markdown source, MarkdownParseOptions?` | `HTML string; raw HTML escaped or allowlisted` | `parseMarkdown("# Hello", { allowHtmlTags: false })` |
124
+ | `renderMarkdownDocument` | Editor document model | `Markdown source, MarkdownDocumentParseOptions?` | `MarkdownRenderResult with outline/codeBlocks/blocks` | `renderMarkdownDocument("# Report", { allowHtmlTags: false })` |
125
+ | `isLanguageSupported` | Check highlight language | `language name` | `boolean` | `isLanguageSupported("typescript")` |
126
+ | `highlightCode` | Highlight code | `code text, supported language` | `escaped/highlighted HTML string` | `highlightCode("const total = 1", "typescript")` |
127
+ | `resolveDocumentMarkdownContent` | Fence code content | `text, sourceKind?, language?` | `Markdown string with a safe fence length` | `resolveDocumentMarkdownContent("const x = 1", "code", "ts")` |
128
+ | `resolveDocumentDownloadActions` | Download menu | `MarkdownToolbarDownloadAction[]?` | `AiDocumentResolvedDownloadAction[]` | `resolveDocumentDownloadActions([{ id: "markdown", label: "Markdown" }])` |
129
+ | `downloadAiDocument` | Download selected format | `AiDocumentDownloadRequest` | `Promise<void>; browser failure rejects, SSR does nothing` | `downloadAiDocument({ actionId: "markdown", content: "# Report", filename: "report.md" })` |
130
+ | `createLocaleStore` | Component locale state | `{ defaultLocale?, supportedLocales?, detectBrowser?, persistKey? }` | `locale store with current/set/isSupported` | `createLocaleStore({ defaultLocale: "zh-CN", detectBrowser: false })` |
131
+ | `getGlobalLocale` | Read current locale | `none` | `locale string from current context` | `getGlobalLocale()` |
132
+ | `setGlobalLocale` | Set browser/startup locale | `locale` | `void; use request context for SSR` | `setGlobalLocale("en-US")` |
133
+ | `detectBrowserLocale` | Detect browser locale | `supportedLocales?` | `supported locale or null` | `detectBrowserLocale()` |
134
+ | `isLocaleSupported` | Check supported locale | `locale, supportedLocales?` | `boolean` | `isLocaleSupported("ja-JP")` |
135
+ | `resolveLocale` | Normalize locale | `locale, supportedLocales?, fallback?` | `supported locale` | `resolveLocale("en")` |
136
+ | `interpolate` | Interpolate message | `template string, InterpolationParams` | `string` | `interpolate("Hello {name}", { name: "Ada" })` |
137
+ | `getThemeInfo` | Theme metadata | `theme ID` | `ThemeInfo or undefined` | `getThemeInfo("light")` |
138
+ | `isDarkTheme` | Dark theme check | `theme ID` | `boolean` | `isDarkTheme("dark")` |
139
+ | `normalizeThemeId` | Normalize theme | `candidate theme ID, fallback?` | `supported theme ID` | `normalizeThemeId("unknown", "light")` |
140
+ | `normalizeHexColor` | Normalize color | `string or null/undefined` | `six-digit lowercase hex string or null` | `normalizeHexColor("#5765F0")` |
141
+ | `resolveThemeTone` | Theme tone | `theme ID` | `light or dark` | `resolveThemeTone("light")` |
142
+ | `createThemeBootstrapScript` | Bootstrap theme | `ThemeBootstrapScriptOptions from trusted host config` | `script string for the application HTML shell` | `createThemeBootstrapScript({ storageKey: "theme", defaultThemeId: "light" })` |
143
+ | `getThemeInitScript` | Default theme bootstrap | `none` | `script string` | `getThemeInitScript()` |
144
+ | `applyTheme` | Apply theme | `theme ID, persist? (default true)` | `void; updates DOM/browser preference` | `applyTheme("dark")` |
145
+ | `getCurrentTheme` | Current theme | `none` | `theme ID string` | `getCurrentTheme()` |
146
+ | `getSavedTheme` | Saved theme | `fallback theme ID?` | `theme ID string` | `getSavedTheme("light")` |
147
+ | `createGuide` | Guide controller | `GuideOptions: tours, articles?, nav?, persistence?, persistKey?` | `GuideController; no init/close` | `createGuide({ tours: [], persistence: "memory" })` |
148
+ | `resolveGuideText` | Resolve guide text | `string or translation callback?` | `string` | `resolveGuideText(() => m.help())` |
149
+ | `matchPermission` | Permission visibility | `required permission, userPermissions[]` | `boolean; not server authorization` | `matchPermission("orders:read", ["orders:*"])` |
150
+ | `setPermissionContext` | Provide permission context | `() => current permissions; component initialization only` | `void` | `setPermissionContext(() => user.permissions)` |
151
+ | `usePermission` | Consume permissions | `none; component initialization only` | `PermissionContext with hasPerm/hasAnyPerm/hasAllPerms` | `usePermission()` |
152
+ | `createSensitiveActions` | Sensitive confirmation | `standard auth actions providing reauthenticate/publicConfig?` | `SensitiveActions: configure/authorize/submit/cancel` | `createSensitiveActions(actions)` |
153
+ | `createSessionRecovery` | In-place session recovery | `none; configure public config and current user afterward` | `SessionRecovery controller` | `createSessionRecovery()` |
154
+ | `defineCrud` | Define CRUD | `CrudResource with fields/API callbacks` | `CrudDef for CrudPage` | `defineCrud(resourceDefinition)` |
155
+ | `createCrudController` | Manage list state | `CrudDef, { autoLoad? }?` | `controller data/nav/loading/loaded/error/load/reload` | `createCrudController(crud, { autoLoad: false })` |
156
+ | `mapPaginated` | Map paginated items | `PaginatedResult<T>, (item,index) => R` | `PaginatedResult<R> retaining total/page/pageSize` | `mapPaginated(page, item => ({ ...item, selected: false }))` |
157
+ | `createBrowserNavAdapter` | Browser navigation | `none` | `NavAdapter` | `createBrowserNavAdapter()` |
158
+ | `registerClipboardHostWriter` | Register host clipboard | `async text => boolean or null to unregister` | `void` | `registerClipboardHostWriter(null)` |
159
+ | `writeTextToClipboard` | Copy and check result | `text: string` | `Promise<boolean>; true only when write succeeds` | `writeTextToClipboard("trace-001")` |
160
+ | `cn` | Combine classes | `...string\|boolean\|null\|undefined values` | `string` | `cn("flex", active && "text-primary")` |
161
+ | `getDataAttributes` | Forward data attributes | `props record` | `ForwardedDataAttributes` | `getDataAttributes({ "data-testid": "save" })` |
162
+ | `generateId` | UI identifier | `prefix?; not a security token generator` | `string` | `generateId("field")` |
163
+ | `portal` | Portal a node | `HTMLElement, target HTMLElement or selector?` | `Svelte action result with cleanup` | `portal(node, document.body)` |
164
+ | `detectPlatform` | Detect platform | `none` | `Platform` | `detectPlatform()` |
165
+ | `isMobile` | Check mobile | `none` | `boolean` | `isMobile()` |
166
+ | `isNativeApp` | Check native shell | `none` | `boolean` | `isNativeApp()` |
167
+ | `usePlatform` | Reactive platform view | `none; component initialization` | `{ current, isMobile, isApp }` | `usePlatform()` |
168
+ | `getVariantClass` | Map theme classes | `Variant, prefix?` | `string class name` | `getVariantClass("primary", "btn")` |
169
+ | `getSizeClass` | Map theme classes | `Size, prefix?` | `string class name` | `getSizeClass("sm", "btn")` |
170
+ | `getInputSizeClass` | Map theme classes | `Size` | `string class name` | `getInputSizeClass("sm")` |
171
+ | `getBadgeVariantClass` | Map theme classes | `Variant` | `string class name` | `getBadgeVariantClass("info")` |
172
+ | `getBadgeSizeClass` | Map theme classes | `Size` | `string class name` | `getBadgeSizeClass("sm")` |
173
+ | `getAlertVariantClass` | Map theme classes | `Variant` | `string class name` | `getAlertVariantClass("info")` |
174
+ | `getProgressVariantClass` | Map theme classes | `Variant` | `string class name` | `getProgressVariantClass("primary")` |
175
+ | `useToastFeedback` | Operation feedback | `() => safely localized message, variant?` | `void; source-owned toast lifecycle` | `useToastFeedback(() => errorMessage(error))` |
176
+ | `notifySuccess` | Operation feedback | `localized message, duration?` | `toast ID string` | `notifySuccess(m.saved())` |
177
+ | `notifyInfo` | Operation feedback | `localized message, duration?` | `toast ID string` | `notifyInfo(m.loading())` |
178
+ | `notifyWarning` | Operation feedback | `localized message, duration?` | `toast ID string` | `notifyWarning(m.warning())` |
179
+ | `notifyError` | Operation feedback | `unknown error, safe fallback?, duration?` | `toast ID string; internal exception text hidden` | `notifyError(error, m.retry())` |
180
+ | `errorMessage` | Operation feedback | `unknown error, safe fallback?` | `safe localized string` | `errorMessage(error, m.retry())` |
181
+ | `toast.add` | Shared feedback queue | `localized options/message` | `string item ID` | `toast.add({ message: m.saved(), variant: "success" })` |
182
+ | `toast.success` | Shared feedback queue | `localized safe message, duration?` | `string item ID` | `toast.success(m.result())` |
183
+ | `toast.info` | Shared feedback queue | `localized safe message, duration?` | `string item ID` | `toast.info(m.result())` |
184
+ | `toast.warning` | Shared feedback queue | `localized safe message, duration?` | `string item ID` | `toast.warning(m.result())` |
185
+ | `toast.error` | Shared feedback queue | `localized safe message, duration?` | `string item ID` | `toast.error(m.result())` |
186
+ | `toast.remove` | Shared feedback queue | `item ID` | `void` | `toast.remove(id)` |
187
+ | `toast.clear` | Shared feedback queue | `none` | `void` | `toast.clear()` |
188
+ | `message.add` | Shared feedback queue | `localized options/message` | `string item ID` | `message.add({ message: m.saved(), type: "success" })` |
189
+ | `message.success` | Shared feedback queue | `localized safe message, duration?` | `string item ID` | `message.success(m.result())` |
190
+ | `message.info` | Shared feedback queue | `localized safe message, duration?` | `string item ID` | `message.info(m.result())` |
191
+ | `message.warning` | Shared feedback queue | `localized safe message, duration?` | `string item ID` | `message.warning(m.result())` |
192
+ | `message.error` | Shared feedback queue | `localized safe message, duration?` | `string item ID` | `message.error(m.result())` |
193
+ | `message.remove` | Shared feedback queue | `item ID` | `void` | `message.remove(id)` |
194
+ | `message.clear` | Shared feedback queue | `none` | `void` | `message.clear()` |
195
+ | `toast.pause` | Toast timing | `toast ID` | `void` | `toast.pause(id)` |
196
+ | `toast.resume` | Toast timing | `toast ID` | `void` | `toast.resume(id)` |
197
+ | `messageBox.confirm` | Async confirmation | `localized string or MessageBoxOptions` | `Promise<boolean>; host handles confirmation/cancellation` | `messageBox.confirm({ message: m.confirm() })` |
198
+ | `messageBox.alert` | Async confirmation | `localized string or MessageBoxOptions` | `Promise<boolean>; host handles confirmation/cancellation` | `messageBox.alert({ message: m.confirm() })` |
199
+
200
+ - Forms, tables, dialogs, navigation, charts and application components.
201
+ - Authentication, CRUD, AI content, onboarding and a help center.
202
+ - Svelte 5, themes, responsive layouts and Chinese/English/Japanese component messages.
203
+
204
+ Markdown underline and highlight markers support escaping; unclosed markers remain text. Toasts and document downloads handle unusually long text without repeated scanning, while trace identifiers remain hidden by default.
205
+
206
+ ### data-\* attribute forwarding
128
207
 
129
208
  Public Svelte components forward caller-supplied `data-*` attributes to their root or primary interactive element for tests, analytics, and automation. Other unknown attributes are not forwarded.
130
209
 
@@ -136,6 +215,32 @@ Public Svelte components forward caller-supplied `data-*` attributes to their ro
136
215
 
137
216
  No extra button, input, or overlay wrappers are needed just for `data-testid`.
138
217
 
218
+ ### Component-family inputs, events and outputs
219
+
220
+ These families cover the interaction categories in the component catalog. Supply application-owned m, rows, user, controllers and callbacks. Display components render DOM; interactive components report through bindings/callbacks and do not grant server authorization. See Examples, catalog notes and the UI skill for complete compositions. Exported Props types constrain further options.
221
+
222
+ | Component family | Input | Output/events | Example fragment |
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
  ### Component architecture
140
245
 
141
246
  Three layers (primitives → compounds → scenes):
@@ -155,7 +260,7 @@ components/
155
260
 
156
261
  ### Component catalog
157
262
 
158
- #### Primitives (20)
263
+ #### Primitives
159
264
 
160
265
  | Component | Description | Key props |
161
266
  | ---------------- | ------------------- | ------------------------------------------------------------------------------ |
@@ -180,9 +285,11 @@ components/
180
285
  | `Spinner` | Loading animation | `size`, `variant` |
181
286
  | `Progress` | Progress bar | `value`, `max`, `variant`, `striped`, `animated` |
182
287
 
288
+ `Checkbox`, `Switch` and `Radio` default to the theme primary color, and their checked states follow the current DaisyUI theme; `Checkbox` colors can be overridden with a `checkbox-*` class.
289
+
183
290
  For `BareInput` with `type="file"`, read `event.currentTarget.files` in `onchange` and leave the file path `value` unbound. Other input types support `bind:value`.
184
291
 
185
- #### Compounds (37)
292
+ #### Compounds
186
293
 
187
294
  ##### Forms
188
295
 
@@ -209,6 +316,8 @@ Text controls validate on blur after input and update errors as input is correct
209
316
 
210
317
  `UserProfile.fieldConstraints` accepts per-field `required`, `minlength`, `maxlength`, `pattern` and `validationMessage` (`pattern` applies to single-line inputs), so application rules such as username formats share blur validation. `validationMessage` also accepts a deferred translation function.
211
318
 
319
+ `UserProfile.onsubmit` must return `true` to confirm a successful save, or `false` to keep the editor and draft. Thrown errors also keep editing open and use the shared Toast feedback. Cancel restores the saved values from `user`.
320
+
212
321
  `CrudEditPanel.onsubmit` receives only writable fields declared by the form. Fields marked `readonly` are omitted when editing and remain available when creating. Primary keys, related display values and audit timestamps are not copied from the entire row. Null values, `false` and `0` are preserved. Keep strict schema validation on the server.
213
322
 
214
323
  `LoginForm`, `RegisterForm`, `ChangePasswordForm`, `ForgotPasswordForm`, `ResetPasswordForm`, `AuthPanel`, `UserProfile` and `FeedbackModal` accept the same layout options. Pass them through `CrudPage.form` or directly to `CrudEditPanel`. CRUD fields support `colSpan` and deferred `validation.message`. Buttons and Enter both validate before submission; corrections clear errors. Server validation remains required.
@@ -242,6 +351,10 @@ Text controls validate on blur after input and update errors as input is correct
242
351
  | `Confirm` | Confirmation dialog | `open`, `title`, `message`, `variant`, `onconfirm` |
243
352
  | `Popover` | Popover | `open`, `position`, `trigger`, `offset`, `portal` |
244
353
 
354
+ `Popover` renders in `body` by default. In `click` mode, Enter or Space opens the panel and moves focus into it. Escape closes the panel and returns focus to the trigger. Use `portal={false}` to render inline.
355
+
356
+ Inside a Modal or Drawer, portal controls participate in the owning dialog's Tab and Shift+Tab order. Closing the Popover removes that registration and restores focus to its trigger.
357
+
245
358
  ##### Data display
246
359
 
247
360
  | Component | Description | Key props |
@@ -283,7 +396,9 @@ Text controls validate on blur after input and update errors as input is correct
283
396
  | `Breadcrumb` | Breadcrumbs | `items`, `separator` |
284
397
  | `Steps` | Steps | `items`, `current`, `direction`, `clickable` |
285
398
  | `Dropdown` | Dropdown menu | `items`, `trigger`, `triggerClass`, `position` |
286
- | `Tooltip` | Tooltip | `content`, `position`, `delay` |
399
+ | `Tooltip` | Tooltip | `content`, `position`, `delay`, `portal` (use inside overflow-clipped containers) |
400
+
401
+ `Dropdown` renders the menu in `body` in `click` and `hover` modes. In `manual` mode, toggle `dropdown-open` through `class` to control the inline menu.
287
402
 
288
403
  ##### State placeholders
289
404
 
@@ -299,16 +414,40 @@ Text controls validate on blur after input and update errors as input is correct
299
414
  | ------------ | ----------- | ----------------------------------------------- |
300
415
  | `PageHeader` | Page header | `title`, `description`; supports `actions` slot |
301
416
 
302
- #### Scenes (43)
417
+ #### Scenes
418
+
419
+ ##### Code workspace
420
+
421
+ Use `CodeWorkspace` to browse read-only source files. A directory listing and a file reader are enough to get started. The directory callback receives `null` for the root. Opening a file creates or reuses a tab keyed by file ID and version. Switching tabs restores the cursor and scroll position for recently viewed files.
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
+ Supply `source.search` for filename and workspace content search, and return `nextCursor` when another page is available. File and folder `markers` can show risk and Git state. Return `annotations` from `readFile` to mark lines or ranges. Use the `inspector` and `selectionActions` snippets to render the side panel and actions for the selected code. See the [code workspace guide](../../docs/usage/development/ui.md#代码工作区).
303
438
 
304
- ##### Guide (2)
439
+ Vite loads Monaco and its same-origin workers on demand in the browser. The editor follows the Hai theme by default and supports presets and custom palettes. Monaco editors on the same page share a theme. Mobile devices and editor load failures use a plain-text view.
440
+
441
+ Use the `annotationIcon` snippet to render a gutter icon. On hover, `hoverText` displays plain text, or `annotationHover` renders a custom component when `hoverText` is omitted. Press Enter to enter the popup and Escape to close it.
442
+
443
+ ##### Guide
305
444
 
306
445
  | Component | Description | Key props |
307
446
  | --- | --- | --- |
308
447
  | `GuideHost` | First-use invitations, tours and help dialog host | `guide`, `locale`, `scope`, `autoStart` |
309
448
  | `HelpCenter` | Standalone searchable help center | `articles`, `tours`, `locale`, `selectedId`, `onstart` |
310
449
 
311
- ##### App (11)
450
+ ##### App
312
451
 
313
452
  | Component | Description | Key props |
314
453
  | ------------------ | ---------------------------------------------- | -------------------------------------------------------- |
@@ -328,7 +467,7 @@ Pass the type: webhook task from report jobs into FeedbackDetail.webhook to show
328
467
 
329
468
  Descriptions are optional. Call `prepare()` from `@h-ai/feedback/client` before opening the modal. Connect `onfileschange` to attachment preparation and `onannotate` to image editing that burns annotations into the pixels. Failed submissions retain input and support local export. The list shows the description or server summary and requests pages through `onquerychange`; UI permissions do not replace server authorization. See the [feedback module](../feedback/README.en.md) for integration and offline tools.
330
469
 
331
- ##### IAM authentication (11)
470
+ ##### IAM authentication
332
471
 
333
472
  | Component | Description | Key props |
334
473
  | -------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
@@ -346,7 +485,7 @@ Descriptions are optional. Call `prepare()` from `@h-ai/feedback/client` before
346
485
  | `SessionRecoveryDialog` | In-place session recovery | `recovery`, `actions` |
347
486
  | `SensitiveOperationsForm` | Permission operation editor | `operations`, `onsubmit`, `ondone` |
348
487
 
349
- ##### Storage (4)
488
+ ##### Storage
350
489
 
351
490
  | Component | Description | Key props |
352
491
  | -------------- | ------------- | ------------------------------------------------------------ |
@@ -357,7 +496,7 @@ Descriptions are optional. Call `prepare()` from `@h-ai/feedback/client` before
357
496
 
358
497
  Upload components do not embed presigning, headers, or PUT/POST protocols. Applications call their service through `uploadHandler(file, { signal, onProgress })` and return `{ url?, response? }`. Image/avatar uploads require a displayable `url`. Without a handler, `FileUpload` only selects files, and image/avatar components generate local previews only.
359
498
 
360
- ##### Crypto display (3)
499
+ ##### Crypto display
361
500
 
362
501
  Input changes immediately clear `encryptedValue`; only successful results for current input are restored. Clearing, callback replacement, and unmounting invalidate old requests. Failures show built-in errors and leave ciphertext empty. Submit encrypted inputs only when current ciphertext is nonempty.
363
502
 
@@ -371,7 +510,7 @@ Callers must connect `EncryptedInput` to a real encryption service through `onen
371
510
 
372
511
  Defaults match `@h-ai/crypto`: `SM4` for encrypted inputs, `SM3` for hashes, and `SM2` for signatures.
373
512
 
374
- ##### AI documents and spreadsheets (4)
513
+ ##### AI documents and spreadsheets
375
514
 
376
515
  | Component | Description | Key props / capabilities |
377
516
  | ------------------------ | ---------------------- | ---------------------------------------------------------------------------------------------------------- |
@@ -389,6 +528,7 @@ Defaults match `@h-ai/crypto`: `SM4` for encrypted inputs, `SM3` for hashes, and
389
528
  > - `fontSize` accepts a `number` in px or any CSS length such as `1.125rem`.
390
529
  > - `allowHtmlTags` is off by default; when enabled, tags such as `<b>` / `<i>` / `<u>` / `<mark>` use a safe allowlist, with dangerous tags/attributes still sanitized.
391
530
  > - Text entities in safe HTML retain one level of meaning, so quotes, comparison operators and `&` in configuration snippets remain readable. Encoded tags remain text and are never reparsed as markup.
531
+ > - HTML code blocks such as `<pre><code class="language-yaml">` also receive safely rebuilt highlighting and copy buttons. Input styles and events are discarded. Supported languages include YAML, TypeScript, Shell, PowerShell, dotenv, Nginx, Dockerfile and Svelte.
392
532
  > - Raw `<img>` tags retain `width` / `height` as positive integer pixel values from 1 to 99999. These reserve space before lazy images load and keep document layout and anchor positions stable. Percentages, negatives, decimals, events, and arbitrary `style` are removed.
393
533
 
394
534
  ```svelte
@@ -406,6 +546,26 @@ Defaults match `@h-ai/crypto`: `SM4` for encrypted inputs, `SM3` for hashes, and
406
546
 
407
547
  ##### Charts
408
548
 
549
+ Lightweight dashboards use `MetricCard` (value, unit and percentage change), `ReportCard` (heading, actions, content, loading/empty states), and `DashboardGrid` (one, two or more columns based on container width). MetricCard alone does not load a chart engine. `trend={12.8}` means +12.8%; `trendTone` expresses business meaning independently, so a decrease can be success. Missing and non-finite values show “—”; zero remains visible.
550
+
551
+ `Chart` supports `preset`: `grouped-bar`, `stacked-bar`, `stacked-area`, `donut`, and `sparkline`. Presets supply defaults; explicit `type` and native props take precedence, such as `innerRadius={0.8}` overriding the donut radius. Other LayerChart props and snippets continue to pass through.
552
+
553
+ Renderers load dynamically by type. SSR reserves height and shows a loading placeholder; drawing starts after browser mount. Loading and empty charts do not load renderers. Prefer the public charts entry for dashboard-only consumers. For advanced charts, place native LayerChart components in ReportCard children, beyond Chart's five types. Declare a compatible `layerchart` dependency and use its actual public entries such as `layerchart/svg` or `layerchart/hierarchy`. Load advanced components dynamically when needed; see the admin native ArcChart example.
554
+
555
+ ```svelte
556
+ <script lang="ts">
557
+ import { Chart, DashboardGrid, MetricCard, ReportCard } from '@h-ai/ui/components/scenes/charts/index'
558
+ const data = [{ month: 'Jan', revenue: 42, cost: 24 }, { month: 'Feb', revenue: 58, cost: 31 }]
559
+ </script>
560
+
561
+ <DashboardGrid label="Key metrics" columns={4}>
562
+ <MetricCard title="Revenue" value="128,430" unit="CNY" trend={12.8} trendTone="success" trendLabel="vs previous month" />
563
+ </DashboardGrid>
564
+ <ReportCard title="Revenue and cost">
565
+ <Chart preset="grouped-bar" {data} x="month" y={['revenue', 'cost']} />
566
+ </ReportCard>
567
+ ```
568
+
409
569
  `Chart type='line'` uses LayerChart's native line chart by default. For monitoring dashboards with segmented lines, points, nearest-point hover, and vertical reference lines, use `lineVariant='segmented-point'`:
410
570
 
411
571
  ```svelte
@@ -423,7 +583,7 @@ Defaults match `@h-ai/crypto`: `SM4` for encrypted inputs, `SM3` for hashes, and
423
583
  />
424
584
  ```
425
585
 
426
- ##### CRUD scenes (5)
586
+ ##### CRUD scenes
427
587
 
428
588
  | Component | Description | Key props / capabilities |
429
589
  | ------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -440,7 +600,7 @@ Defaults match `@h-ai/crypto`: `SM4` for encrypted inputs, `SM3` for hashes, and
440
600
  >
441
601
  > Columns first shrink to 7rem and truncate long text; horizontal scrolling appears only if total width still exceeds the container. The action column stays fixed on the right.
442
602
 
443
- ##### Error pages (1)
603
+ ##### Error pages
444
604
 
445
605
  | Component | Description | Key props / capabilities |
446
606
  | ----------- | --------------------------------------------------- | ----------------------------------------------------------------------- |
@@ -700,6 +860,8 @@ On mobile pages, match `BottomNav` width to the page shell to avoid spanning the
700
860
  </div>
701
861
  ```
702
862
 
863
+ `BottomNav` and `ThemeSelector` keep their trigger buttons disabled until the client has mounted and the event handlers are ready.
864
+
703
865
  #### Icons
704
866
 
705
867
  Components use Iconify (Tabler Icons):
@@ -717,10 +879,12 @@ npm install -D @iconify/tailwind4 @iconify-json/tabler
717
879
 
718
880
  #### Theme switching
719
881
 
720
- Manage 15 curated DaisyUI themes plus high contrast and square business themes through built-in utilities:
882
+ Manage 15 curated DaisyUI themes plus high contrast, square business and eye-care themes through built-in utilities:
721
883
 
722
884
  `high-contrast` ships in shared theme.css with bright text on dark surfaces, clear borders/focus, and stronger muted text/placeholders. ThemeSelector has localized labels; examples and default generated projects offer it. Explicit fullstack themes lists remain host controlled. Palette checks target 7:1 for normal text; arbitrary application content still needs accessibility review.
723
885
 
886
+ `eye-care` ships in shared theme.css with warm green surfaces, dark text, readable placeholders and clear focus outlines. Select “Eye care” in examples and default templates; the preference survives reloads. Existing default themes and explicit fullstack themes lists are preserved.
887
+
724
888
  `formal` provides square corners for business buttons, fields, cards and dialogs, with localized labels in examples and default templates. Button submitHint displays the native Enter action only for type=submit; it adds no global shortcut. LoginForm focuses its identifier on desktop when ready and no element has focus; autoFocus=false opts out. Search Enter submits immediately while respecting IME composition. Theme choices support arrows/Home/End, Enter/Space and Escape focus restoration. Confirmation dialogs initially focus Cancel and synchronize Escape cancellation.
725
889
 
726
890
  ```ts
@@ -734,7 +898,7 @@ import {
734
898
  normalizeHexColor, // 归一化 #RGB / #RRGGBB 主题色
735
899
  normalizeThemeId, // 校验主题 ID 并自动回退
736
900
  THEME_GROUPS, // 按亮色/暗色分组
737
- THEMES, // ThemeInfo[] — 17 个主题元数据
901
+ THEMES, // ThemeInfo[] — 18 个主题元数据
738
902
  } from '@h-ai/ui/theme'
739
903
  ```
740
904
 
@@ -779,7 +943,7 @@ Client locale state management, automatically synchronized with the `@h-ai/core`
779
943
  ```svelte
780
944
  <script>
781
945
  import { createLocaleStore, setGlobalLocale } from '@h-ai/ui/i18n'
782
- import { setLocale } from '$lib/paraglide/runtime'
946
+ import { setLocale } from '#lib/paraglide/runtime.js'
783
947
 
784
948
  const localeStore = createLocaleStore()
785
949
 
@@ -841,11 +1005,9 @@ agreements:
841
1005
  # privacyPolicyUrl: https://example.com/privacy
842
1006
  ```
843
1007
 
844
-
845
-
846
1008
  AuthPanel accepts public IAM config and actions for password/LDAP/email/SMS login, registration and recovery. config.ui supplies layout, branding and images. LoginForm supports methods, onsendotp, otpLength and resendInterval; password forms accept passwordPolicy. Network and token storage remain in actions.
847
1009
 
848
- Use `authErrorMessage(error)` from `@h-ai/ui/components/scenes/iam/index` for authentication failures. It maps public codes to the current UI language, combines username/password failures, hides raw unknown/server errors and preserves a valid `traceId`. AuthPanel, OTP sending, sensitive confirmation and fullstack password changes share this mapping. Initial/expired passwords, reuse of the current password (`hai:iam:034`) and session limits have actionable messages. Authentication errors and successful operations use the unified Toast. Password confirmation compares exact strings without Unicode normalization or trimming and reports mismatches through Toast while retaining field associations.
1010
+ Use `authErrorMessage(error)` from `@h-ai/ui/components/scenes/iam/index` for authentication failures. It maps public codes to the current UI language, combines username/password failures, hides raw unknown/server errors and preserves a valid `traceId`. AuthPanel, OTP sending, sensitive confirmation and fullstack password changes share this mapping. Initial/expired passwords, reuse of the current password (`hai:iam:034`) and session limits have actionable messages. Authentication errors and successful operations use the unified Toast. Password confirmation compares exact strings without Unicode normalization or trimming and reports mismatches through Toast while retaining field associations. AuthPanel displays the server’s UTC time and synchronization guidance for time errors verified by Kit or API Client.
849
1011
 
850
1012
  AuthPanel disables native form controls during SSR and enables input after client mount binds events, preventing early input from being lost during hydration. Applications need no extra readiness code. E2E tests wait for editable controls and cover delayed client scripts.
851
1013
 
@@ -965,7 +1127,6 @@ Agreements open in a Modal and preserve form input. Pages must allow iframe embe
965
1127
  </AuthPanel>
966
1128
  ```
967
1129
 
968
-
969
1130
  Component subpaths expose only explicit barrels in package.exports, such as `@h-ai/ui/components/primitives/index`. Component internals and storage helpers stay private; host clipboard registration remains public.
970
1131
 
971
1132
  ### Request locale isolation
@@ -974,11 +1135,11 @@ Wrap Node requests and SSR in `core.i18n.runWithLocale(locale, () => handleReque
974
1135
 
975
1136
  Browsers keep application-level `setGlobalLocale` / `createLocaleStore`. During SSR, UI store initialization and setters only update the store; messages read the request scope. `runWithLocale` requires the Node entry; browser translations use explicit locale options or application state.
976
1137
 
977
- ## Input limits and HTTP capabilities
1138
+ ### Input limits and HTTP capabilities
978
1139
 
979
1140
  Object keys are limited to 1024 UTF-8 bytes and reject absolute paths, backslashes, control characters and dot segments. Each public HTTP batch delete accepts 1–1000 entries. `@h-ai/storage/schemas` exposes the shared browser-safe rules. Presign expiry is an integer from 1 to 604800 seconds (Node default 3600, HTTP default 900). Upload signing accepts only key/contentType/expiresIn; contentLength/maxSize/metadata/checksum are unsupported. Invalid input returns HTTP 400 and the typed client maps it to VALIDATION_FAILED. FileUpload limits guide file selection; applications must validate actual objects on the server. Node streaming/checksum/conditional-write options have no default HTTP endpoints. See the [capability and authorization matrix (Chinese)](../storage/README.md#存储输入约束与跨端能力).
980
1141
 
981
- ## Compact workspaces and collapsible filters
1142
+ ### Compact workspaces and collapsible filters
982
1143
 
983
1144
  `WorkspaceLayout` shares a compact navigation header, a content area with 12/16px padding and an optional footer. An omitted footer reserves no space. title is the page title in navigation; leading/actions/footer are snippets. data-* attributes reach the content main. The host must pass down available height and min-height: 0.
984
1145
 
@@ -1006,25 +1167,46 @@ In this example, m, statusOptions, clearFilters and loadRows belong to the host
1006
1167
  </div>
1007
1168
  ```
1008
1169
 
1009
- ## Design and interaction acceptance
1170
+ ### Design and interaction acceptance
1010
1171
 
1011
1172
  Use [hai-ui-design](../cli/templates/skills/hai-ui-design/SKILL.md) for page decisions, [hai-ui](../cli/templates/skills/hai-ui/SKILL.md) for implementation, and [hai-ui-review](../cli/templates/skills/hai-ui-review/SKILL.md) for rendered UI review. See the [shared design guidance](../../.agents/instructions/ui-design.md).
1012
1173
 
1013
1174
  Tabs support arrow/Home/End navigation, disabled items and one Tab stop. Tables expose sort/loading state and keyboard row activation. Pagination labels follow locale and external page changes update the jump input. Expanded filters follow document focus order and view buttons expose selection. Empty/Alert wrap long content. theme.css imports shared tokens; focus follows the current theme and global.css respects reduced motion. Applications still implement filtering, sorting, paging and recovery.
1014
1175
 
1015
- ## Error messages and correlated logs
1176
+ ### Optional interactive challenges
1016
1177
 
1017
- HTTP errors carry safe localized messages and a reference ID. ToastContainer shows only the readable message by default; its diagnostic icon reveals the ID and copy action. The same ID remains in `error.traceId` and `X-Trace-Id`. The framework reuses the request ID to correlate browser and server logs. Sanitized exceptions, stacks and operation context remain in logs; internal cause/ext are not exposed. Field validation returns localized field names and messages only.
1178
+ AuthPanel uses actions.createCaptcha to automatically create and asynchronously solve self-hosted ALTCHA when config.captcha.enabled, submitting one-use proofs for login/register/sendOtp/passwordReset/renewPassword. The solver is not loaded when disabled. createAuthActions supplies the action; custom actions must preserve captcha and missing actions fail closed. Proofs stay in request memory and are always verified/consumed on the server.
1018
1179
 
1019
- Use `core.error.toPublic(error, traceId?)` at HTTP/UI boundaries and `core.error.formatMessage(error)` after translating messages; formatting is idempotent. Pass complete Error objects to logs instead of discarding their context. Database failures log driver codes, sanitized messages/stacks and table/column context; SQL text, bound values and connection credentials are excluded.
1180
+ See policy, defaults and recovery boundaries in [IAM](../iam/README.en.md).
1020
1181
 
1021
- ## Optional interactive challenges
1182
+ ## Configuration
1022
1183
 
1023
- AuthPanel uses actions.createCaptcha to automatically create and asynchronously solve self-hosted ALTCHA when config.captcha.enabled, submitting one-use proofs for login/register/sendOtp/passwordReset/renewPassword. The solver is not loaded when disabled. createAuthActions supplies the action; custom actions must preserve captcha and missing actions fail closed. Proofs stay in request memory and are always verified/consumed on the server.
1184
+ ### Choose configuration by task
1024
1185
 
1025
- See policy, defaults and recovery boundaries in [IAM](../iam/README.en.md).
1186
+ | Configuration entry | Scenario | Input | Effect | Example |
1187
+ | --- | --- | --- | --- | --- |
1188
+ | `Component Props` | Rendering and interaction | typed props, bound values, callbacks, children snippets | DOM, bindings and callback events | `<Input bind:value={draft} />` |
1189
+ | `Theme` | Themes and colors | supported theme ID, color values, preference key | DOM theme/CSS variables; nonsensitive browser preference | `applyTheme("light")` |
1190
+ | `Locale` | Interface language | supportedLocales, defaultLocale, persistKey, detectBrowser | component-tree locale; isolated SSR state | `createLocaleStore({ defaultLocale: "ja-JP", detectBrowser: false })` |
1191
+ | `Guide` | Help and onboarding | tours, articles, nonsecret scope/version, nav adapter | guide/help state and nonsensitive progress | `createGuide({ tours: [], persistence: "memory" })` |
1192
+ | `CRUD` | Resource fields and API | CrudResource fields/API callbacks and controller options | resource view model; API must implement authorization | `createCrudController(crud, { autoLoad: false })` |
1193
+ | `Authentication` | Public auth policy | IAM-whitelisted config and standard actions | AuthPanel submits to host actions; no secret persistence | `<AuthPanel {config} {actions} />` |
1194
+
1195
+ When building Svelte applications with pnpm, register the `deepmerge@4.3.1` patch in the project's `patchedDependencies` and keep the patch file. Retain the DaisyUI style patch when that package is used. CLI-generated projects include applicable entries. Installing a framework npm package does not propagate this repository's pnpm patch configuration; manual integrations must copy the relevant [patch files](../../patches/) and registrations before reinstalling dependencies.
1196
+
1197
+ This package contains Svelte components and utilities and has no init/close lifecycle. Inputs are component props, callbacks and theme options; outputs are rendered UI, bound values and events. Configure Tailwind/DaisyUI and preprocessing as shown above. There is no shared _ui.yml or module environment variable for component props.
1198
+
1199
+ ## Error Handling
1200
+
1201
+ The host provides loading/error and completion state. Check business HaiResult.success in the application adapter, then pass safe localized messages. UI helpers use the direct return types above rather than a universal HaiResult wrapper. notifyError/errorMessage hide unknown internal exception text. Catch rejected browser helpers such as downloadAiDocument at the interaction boundary and release loading. UserProfile.onsubmit ends editing only when it returns true.
1202
+
1203
+ ### Error messages and correlated logs
1204
+
1205
+ HTTP errors carry safe localized messages and a reference ID. ToastContainer shows only the readable message by default; its diagnostic icon reveals the ID and copy action. The same ID remains in `error.traceId` and `X-Trace-Id`. The framework reuses the request ID to correlate browser and server logs. Sanitized exceptions, stacks and operation context remain in logs; internal cause/ext are not exposed. Field validation returns localized field names and messages only.
1206
+
1207
+ Use `core.error.toPublic(error, traceId?)` at HTTP/UI boundaries and `core.error.formatMessage(error)` after translating messages; formatting is idempotent. Pass complete Error objects to logs instead of discarding their context. Database failures log driver codes, sanitized messages/stacks and table/column context; SQL text, bound values and connection credentials are excluded.
1026
1208
 
1027
- ## Development and testing
1209
+ ## Development
1028
1210
 
1029
1211
  ```sh
1030
1212
  pnpm --filter @h-ai/ui typecheck