@h-ai/ui 1.0.0-beta.19 → 1.0.0-beta.20
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.
- package/README.en.md +167 -44
- package/README.ja.md +166 -43
- package/README.md +169 -47
- package/auto-import.js +124 -18
- package/package.json +2 -2
package/README.en.md
CHANGED
|
@@ -4,23 +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
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
|
-
|
|
14
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.
|
|
15
|
-
## Core features
|
|
16
12
|
|
|
17
|
-
|
|
18
|
-
- Authentication, CRUD, AI content, onboarding and a help center.
|
|
19
|
-
- Svelte 5, themes, responsive layouts and Chinese/English/Japanese component messages.
|
|
20
|
-
|
|
21
|
-
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.
|
|
22
|
-
|
|
23
|
-
## Getting started
|
|
13
|
+
## Quick Start
|
|
24
14
|
|
|
25
15
|
### Installation
|
|
26
16
|
|
|
@@ -30,15 +20,13 @@ npm install @h-ai/ui @h-ai/core
|
|
|
30
20
|
|
|
31
21
|
For a Node server, declare both UI and core as production dependencies so the adapter preserves native logging and runtime dependencies.
|
|
32
22
|
|
|
33
|
-
###
|
|
34
|
-
|
|
35
|
-
#### 1. Configure application imports in package.json
|
|
23
|
+
### 1. Configure application imports in package.json
|
|
36
24
|
|
|
37
25
|
```json
|
|
38
26
|
{ "imports": { "#lib/*": "./src/lib/*" } }
|
|
39
27
|
```
|
|
40
28
|
|
|
41
|
-
|
|
29
|
+
### 2. Configure vite.config.ts
|
|
42
30
|
|
|
43
31
|
SvelteKit 3 configures preprocessing, the compiler and the adapter in the Vite plugin; only a plain Svelte/Vite project keeps svelte.config.js.
|
|
44
32
|
|
|
@@ -68,7 +56,7 @@ export default defineConfig({
|
|
|
68
56
|
})
|
|
69
57
|
```
|
|
70
58
|
|
|
71
|
-
|
|
59
|
+
### 3. Configure src/app.css
|
|
72
60
|
|
|
73
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.
|
|
74
62
|
|
|
@@ -91,7 +79,7 @@ When using Crypto or Kit/IAM, include `sm-crypto@0.5.8` in application productio
|
|
|
91
79
|
|
|
92
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.
|
|
93
81
|
|
|
94
|
-
|
|
82
|
+
### 4. Use components
|
|
95
83
|
|
|
96
84
|
```svelte
|
|
97
85
|
<script>
|
|
@@ -115,7 +103,7 @@ With auto-import enabled, use components directly in templates without individua
|
|
|
115
103
|
|
|
116
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.
|
|
117
105
|
|
|
118
|
-
The preprocessor
|
|
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.
|
|
119
107
|
|
|
120
108
|
```ts
|
|
121
109
|
import { Card } from '@h-ai/ui/components/compounds/index'
|
|
@@ -123,7 +111,99 @@ import { Button } from '@h-ai/ui/components/primitives/index'
|
|
|
123
111
|
import { getThemeInfo, THEMES } from '@h-ai/ui/theme'
|
|
124
112
|
```
|
|
125
113
|
|
|
126
|
-
|
|
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
|
|
127
207
|
|
|
128
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.
|
|
129
209
|
|
|
@@ -135,6 +215,32 @@ Public Svelte components forward caller-supplied `data-*` attributes to their ro
|
|
|
135
215
|
|
|
136
216
|
No extra button, input, or overlay wrappers are needed just for `data-testid`.
|
|
137
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
|
+
|
|
138
244
|
### Component architecture
|
|
139
245
|
|
|
140
246
|
Three layers (primitives → compounds → scenes):
|
|
@@ -154,7 +260,7 @@ components/
|
|
|
154
260
|
|
|
155
261
|
### Component catalog
|
|
156
262
|
|
|
157
|
-
#### Primitives
|
|
263
|
+
#### Primitives
|
|
158
264
|
|
|
159
265
|
| Component | Description | Key props |
|
|
160
266
|
| ---------------- | ------------------- | ------------------------------------------------------------------------------ |
|
|
@@ -183,7 +289,7 @@ components/
|
|
|
183
289
|
|
|
184
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`.
|
|
185
291
|
|
|
186
|
-
#### Compounds
|
|
292
|
+
#### Compounds
|
|
187
293
|
|
|
188
294
|
##### Forms
|
|
189
295
|
|
|
@@ -308,16 +414,16 @@ Inside a Modal or Drawer, portal controls participate in the owning dialog's Tab
|
|
|
308
414
|
| ------------ | ----------- | ----------------------------------------------- |
|
|
309
415
|
| `PageHeader` | Page header | `title`, `description`; supports `actions` slot |
|
|
310
416
|
|
|
311
|
-
#### Scenes
|
|
417
|
+
#### Scenes
|
|
312
418
|
|
|
313
|
-
##### Guide
|
|
419
|
+
##### Guide
|
|
314
420
|
|
|
315
421
|
| Component | Description | Key props |
|
|
316
422
|
| --- | --- | --- |
|
|
317
423
|
| `GuideHost` | First-use invitations, tours and help dialog host | `guide`, `locale`, `scope`, `autoStart` |
|
|
318
424
|
| `HelpCenter` | Standalone searchable help center | `articles`, `tours`, `locale`, `selectedId`, `onstart` |
|
|
319
425
|
|
|
320
|
-
##### App
|
|
426
|
+
##### App
|
|
321
427
|
|
|
322
428
|
| Component | Description | Key props |
|
|
323
429
|
| ------------------ | ---------------------------------------------- | -------------------------------------------------------- |
|
|
@@ -337,7 +443,7 @@ Pass the type: webhook task from report jobs into FeedbackDetail.webhook to show
|
|
|
337
443
|
|
|
338
444
|
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.
|
|
339
445
|
|
|
340
|
-
##### IAM authentication
|
|
446
|
+
##### IAM authentication
|
|
341
447
|
|
|
342
448
|
| Component | Description | Key props |
|
|
343
449
|
| -------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
|
|
@@ -355,7 +461,7 @@ Descriptions are optional. Call `prepare()` from `@h-ai/feedback/client` before
|
|
|
355
461
|
| `SessionRecoveryDialog` | In-place session recovery | `recovery`, `actions` |
|
|
356
462
|
| `SensitiveOperationsForm` | Permission operation editor | `operations`, `onsubmit`, `ondone` |
|
|
357
463
|
|
|
358
|
-
##### Storage
|
|
464
|
+
##### Storage
|
|
359
465
|
|
|
360
466
|
| Component | Description | Key props |
|
|
361
467
|
| -------------- | ------------- | ------------------------------------------------------------ |
|
|
@@ -366,7 +472,7 @@ Descriptions are optional. Call `prepare()` from `@h-ai/feedback/client` before
|
|
|
366
472
|
|
|
367
473
|
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.
|
|
368
474
|
|
|
369
|
-
##### Crypto display
|
|
475
|
+
##### Crypto display
|
|
370
476
|
|
|
371
477
|
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.
|
|
372
478
|
|
|
@@ -380,7 +486,7 @@ Callers must connect `EncryptedInput` to a real encryption service through `onen
|
|
|
380
486
|
|
|
381
487
|
Defaults match `@h-ai/crypto`: `SM4` for encrypted inputs, `SM3` for hashes, and `SM2` for signatures.
|
|
382
488
|
|
|
383
|
-
##### AI documents and spreadsheets
|
|
489
|
+
##### AI documents and spreadsheets
|
|
384
490
|
|
|
385
491
|
| Component | Description | Key props / capabilities |
|
|
386
492
|
| ------------------------ | ---------------------- | ---------------------------------------------------------------------------------------------------------- |
|
|
@@ -436,7 +542,6 @@ Renderers load dynamically by type. SSR reserves height and shows a loading plac
|
|
|
436
542
|
</ReportCard>
|
|
437
543
|
```
|
|
438
544
|
|
|
439
|
-
|
|
440
545
|
`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'`:
|
|
441
546
|
|
|
442
547
|
```svelte
|
|
@@ -454,7 +559,7 @@ Renderers load dynamically by type. SSR reserves height and shows a loading plac
|
|
|
454
559
|
/>
|
|
455
560
|
```
|
|
456
561
|
|
|
457
|
-
##### CRUD scenes
|
|
562
|
+
##### CRUD scenes
|
|
458
563
|
|
|
459
564
|
| Component | Description | Key props / capabilities |
|
|
460
565
|
| ------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
@@ -471,7 +576,7 @@ Renderers load dynamically by type. SSR reserves height and shows a loading plac
|
|
|
471
576
|
>
|
|
472
577
|
> 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.
|
|
473
578
|
|
|
474
|
-
##### Error pages
|
|
579
|
+
##### Error pages
|
|
475
580
|
|
|
476
581
|
| Component | Description | Key props / capabilities |
|
|
477
582
|
| ----------- | --------------------------------------------------- | ----------------------------------------------------------------------- |
|
|
@@ -876,8 +981,6 @@ agreements:
|
|
|
876
981
|
# privacyPolicyUrl: https://example.com/privacy
|
|
877
982
|
```
|
|
878
983
|
|
|
879
|
-
|
|
880
|
-
|
|
881
984
|
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.
|
|
882
985
|
|
|
883
986
|
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.
|
|
@@ -1000,7 +1103,6 @@ Agreements open in a Modal and preserve form input. Pages must allow iframe embe
|
|
|
1000
1103
|
</AuthPanel>
|
|
1001
1104
|
```
|
|
1002
1105
|
|
|
1003
|
-
|
|
1004
1106
|
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.
|
|
1005
1107
|
|
|
1006
1108
|
### Request locale isolation
|
|
@@ -1009,11 +1111,11 @@ Wrap Node requests and SSR in `core.i18n.runWithLocale(locale, () => handleReque
|
|
|
1009
1111
|
|
|
1010
1112
|
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.
|
|
1011
1113
|
|
|
1012
|
-
|
|
1114
|
+
### Input limits and HTTP capabilities
|
|
1013
1115
|
|
|
1014
1116
|
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#存储输入约束与跨端能力).
|
|
1015
1117
|
|
|
1016
|
-
|
|
1118
|
+
### Compact workspaces and collapsible filters
|
|
1017
1119
|
|
|
1018
1120
|
`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.
|
|
1019
1121
|
|
|
@@ -1041,25 +1143,46 @@ In this example, m, statusOptions, clearFilters and loadRows belong to the host
|
|
|
1041
1143
|
</div>
|
|
1042
1144
|
```
|
|
1043
1145
|
|
|
1044
|
-
|
|
1146
|
+
### Design and interaction acceptance
|
|
1045
1147
|
|
|
1046
1148
|
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).
|
|
1047
1149
|
|
|
1048
1150
|
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.
|
|
1049
1151
|
|
|
1050
|
-
|
|
1152
|
+
### Optional interactive challenges
|
|
1051
1153
|
|
|
1052
|
-
|
|
1154
|
+
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.
|
|
1053
1155
|
|
|
1054
|
-
|
|
1156
|
+
See policy, defaults and recovery boundaries in [IAM](../iam/README.en.md).
|
|
1055
1157
|
|
|
1056
|
-
##
|
|
1158
|
+
## Configuration
|
|
1057
1159
|
|
|
1058
|
-
|
|
1160
|
+
### Choose configuration by task
|
|
1059
1161
|
|
|
1060
|
-
|
|
1162
|
+
| Configuration entry | Scenario | Input | Effect | Example |
|
|
1163
|
+
| --- | --- | --- | --- | --- |
|
|
1164
|
+
| `Component Props` | Rendering and interaction | typed props, bound values, callbacks, children snippets | DOM, bindings and callback events | `<Input bind:value={draft} />` |
|
|
1165
|
+
| `Theme` | Themes and colors | supported theme ID, color values, preference key | DOM theme/CSS variables; nonsensitive browser preference | `applyTheme("light")` |
|
|
1166
|
+
| `Locale` | Interface language | supportedLocales, defaultLocale, persistKey, detectBrowser | component-tree locale; isolated SSR state | `createLocaleStore({ defaultLocale: "ja-JP", detectBrowser: false })` |
|
|
1167
|
+
| `Guide` | Help and onboarding | tours, articles, nonsecret scope/version, nav adapter | guide/help state and nonsensitive progress | `createGuide({ tours: [], persistence: "memory" })` |
|
|
1168
|
+
| `CRUD` | Resource fields and API | CrudResource fields/API callbacks and controller options | resource view model; API must implement authorization | `createCrudController(crud, { autoLoad: false })` |
|
|
1169
|
+
| `Authentication` | Public auth policy | IAM-whitelisted config and standard actions | AuthPanel submits to host actions; no secret persistence | `<AuthPanel {config} {actions} />` |
|
|
1170
|
+
|
|
1171
|
+
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.
|
|
1172
|
+
|
|
1173
|
+
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.
|
|
1174
|
+
|
|
1175
|
+
## Error Handling
|
|
1176
|
+
|
|
1177
|
+
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.
|
|
1178
|
+
|
|
1179
|
+
### Error messages and correlated logs
|
|
1180
|
+
|
|
1181
|
+
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.
|
|
1182
|
+
|
|
1183
|
+
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.
|
|
1061
1184
|
|
|
1062
|
-
## Development
|
|
1185
|
+
## Development
|
|
1063
1186
|
|
|
1064
1187
|
```sh
|
|
1065
1188
|
pnpm --filter @h-ai/ui typecheck
|