@h-ai/ui 0.1.0-alpha.61 → 0.1.0-alpha.63

package/README.en.md

@@ -98,7 +98,7 @@ With auto-import enabled, use components directly in templates without individua
 
 > `@h-ai/ui/auto-import` injects all public Svelte components except `toast`, type imports, and `Range` (which conflicts with the DOM `Range` constructor).
 
-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. Check the installed package's exports; do not import its internal `src/` or `dist/` paths.
+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.
 
 The preprocessor recognizes semicolon-free, multiline and aliased imports without injecting components already bound locally. Type-only imports do not replace runtime components.
 
@@ -166,16 +166,42 @@ components/
 
 For `BareInput` with `type="file"`, read `event.currentTarget.files` in `onchange` and leave the file path `value` unbound. Other input types support `bind:value`.
 
-### Compounds (36)
+### Compounds (37)
 
 #### Forms
 
 | Component   | Description    | Key props                                    |
 | ----------- | -------------- | -------------------------------------------- |
-| `Form`      | Form container | `loading`, `disabled`, `onsubmit`            |
-| `FormField` | Form field     | `label`, `error`, `hint`, `required`         |
+| `Form`      | Form container | `columns`, `labelPosition`, `labelWidth`, `loading`, `disabled`, `onsubmit`            |
+| `FormField` | Form field     | `label`, `for`, `colSpan`, `labelPosition`, `error`, `hint`, `required`         |
+| `FormLayout` | Form layout | `columns`, `labelPosition`, `labelWidth` |
 | `TagInput`  | Tag input      | `tags`, `maxTags`, `allowDuplicates`, `size` |
 
+#### Form layouts and validation
+
+`Form` and `FormLayout` (for native `<form>` elements) share `columns={1 | 2}`, `labelPosition="top" | "left"` and `labelWidth` (default `8rem`). Defaults are one column and stacked labels. Two columns collapse below a container width of `36rem`; inline labels stack below `28rem`.
+
+`FormField.colSpan` defaults to `'auto'`: textareas, file/image uploads, TagInput and multiple Combobox controls span both columns. Use `1` or `2` to override, or mark a custom wide control with `data-form-wide`. Non-field content, including headings, error summaries and actions, spans the full row. Fields may override `labelPosition` / `labelWidth`.
+
+Labels connect to nested UI controls automatically; use `<FormField for="control-id">` for explicit IDs or native controls. Errors and hints use `aria-describedby`, invalid controls use `aria-invalid`, and field errors appear once. `label` / `error` / `hint` accept strings or deferred translation functions.
+
+`Input`, `Textarea`, `Select` and `PasswordInput` provide Chinese/English native validation messages. `validationMessage` overrides failures without keeping valid input invalid. Sync locale with the UI `setGlobalLocale` / `createLocaleStore` to update visible validation errors immediately. `Textarea` supports `minlength` / `maxlength`; `Select` supports `name`, required validation and FormData serialization.
+
+`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.
+
+```svelte
+<!-- m、save、name、notes 为应用自己的翻译、提交回调和状态 -->
+<Form columns={2} labelPosition="left" labelWidth="6rem" onsubmit={save}>
+  <FormField label={() => m.name()} required>
+    <Input name="name" bind:value={name} required />
+  </FormField>
+  <FormField label={() => m.notes()}>
+    <Textarea name="notes" bind:value={notes} />
+  </FormField>
+  <Button type="submit">{m.save()}</Button>
+</Form>
+```
+
 #### Feedback
 
 | Component        | Description     | Key props                                         |
@@ -248,7 +274,14 @@ For `BareInput` with `type="file"`, read `event.currentTarget.files` in `onchang
 | ------------ | ----------- | ----------------------------------------------- |
 | `PageHeader` | Page header | `title`, `description`; supports `actions` slot |
 
-### Scenes (34)
+### Scenes (36)
+
+#### Guide (2)
+
+| Component | Description | Key props |
+| --- | --- | --- |
+| `GuideHost` | First-use invitations, tours and help dialog host | `guide`, `locale`, `scope`, `autoStart` |
+| `HelpCenter` | Standalone searchable help center | `articles`, `tours`, `locale`, `selectedId`, `onstart` |
 
 #### App (7)
 
@@ -524,7 +557,7 @@ Defaults match `@h-ai/crypto`: `SM4` for encrypted inputs, `SM3` for hashes, and
   crud={roleCrud}
   {data}
   permissions={{ create: true, update: true, delete: true }}
-  form={{ variant: 'modal', modalSize: 'lg' }}
+  form={{ variant: 'modal', modalSize: '3xl', columns: 2, labelPosition: 'top' }}
   pagination={{ showSizeChanger: true, showJumper: true, pageSizeOptions: [10, 20, 50] }}
   density='compact'
   detailColumns={['name']}
@@ -691,7 +724,7 @@ Client locale state management, automatically synchronized with the `@h-ai/core`
 
 ```svelte
 <script>
-  import { createLocaleStore, setGlobalLocale } from '@h-ai/ui'
+  import { createLocaleStore, setGlobalLocale } from '@h-ai/ui/i18n'
   import { setLocale } from '$lib/paraglide/runtime'
 
   const localeStore = createLocaleStore()
@@ -722,7 +755,7 @@ import {
   isLocaleSupported, // 检查 locale 是否支持
   resolveLocale, // 解析 locale（支持回退）
   setGlobalLocale, // 设置全局 locale（同步 @h-ai/core）
-} from '@h-ai/ui'
+} from '@h-ai/ui/i18n'
 ```
 
 ## Configuration driven authentication
@@ -756,6 +789,58 @@ AuthPanel disables native form controls during SSR and enables input after clien
 
 [完整 IAM 配置 / IAM configuration](../iam/README.en.md)
 
+## Onboarding and help center
+
+Import `createGuide`, `GuideHost` and `HelpCenter` from `@h-ai/ui/guide`. No init/close is required. The tour engine loads when a tour starts; controls follow the current theme and include Chinese/English translations. Business text uses application i18n callbacks.
+
+The same entry exports `resolveGuideText(text?)` to evaluate strings or i18n callbacks; host components resolve text automatically.
+
+Create the controller inside a layout component, register tours with id/title/steps and optional route/version, then mount `<GuideHost {guide} {locale} scope={user.id} autoStart='overview' />`. Add `data-guide` to existing target components. Supply the application's NavAdapter for SPA navigation.
+
+```svelte
+<script lang='ts'>
+  import { createGuide, GuideHost } from '@h-ai/ui/guide'
+
+  const guide = createGuide({
+    nav,
+    persistKey: 'my-app-guide',
+    tours: [{
+      id: 'users',
+      version: 1,
+      route: '/users',
+      title: () => m.guide_users_title(),
+      description: () => m.guide_users_description(),
+      steps: [{
+        target: 'users-create',
+        title: () => m.guide_create_title(),
+        description: () => m.guide_create_description(),
+      }],
+    }],
+    articles: [{
+      id: 'users-help',
+      title: () => m.guide_users_title(),
+      content: () => m.guide_users_markdown(),
+      tourId: 'users',
+    }],
+  })
+</script>
+
+<GuideHost {guide} {locale} scope={user.id} autoStart='users' />
+<Button onclick={() => guide.openHelp()}>{m.help()}</Button>
+<!-- 在目标页面为现有按钮添加锚点，无需额外包装。 -->
+<Button data-guide='users-create' onclick={createUser}>{m.create_user()}</Button>
+```
+
+`start(id)` returns Promise<boolean> and always allows replay; failure returns false and sets error. `startIfNeeded(id)` returns boolean and offers a first-use invitation. `openHelp(articleId?)` opens searchable Markdown help; `stop()` cancels without marking completion; `reset(id)` clears the current user's preference.
+
+The close button, Escape, and overlay clicks cancel pending highlighting and clear `busy` even before the first positioning frame completes. A pending `start()` resolves to false without recording completion.
+
+Persistence supports cookie (default), localStorage and memory, with an in-instance fallback when storage is restricted. Preferences are isolated by user and version. Later delays reminders for one day; Cookie preferences expire after one year. The default full-page navigation uses a short-lived sessionStorage record to start on the destination page.
+
+Use `() => m.key()` for localized content and pass the current locale. Steps render as plain text; help uses the existing safe Markdown renderer with raw HTML disabled. Targets wait up to 3000ms by default; before(signal) prepares tabs or drawers, optional skips nonessential missing targets, and missing required targets stop the tour. Unmounting cancels pending work. Never share controllers across SSR users.
+
+HelpCenter can also render a standalone page using articles, optional tours, locale, selectedId and onstart. The admin-console example and CLI fullstack Web/App/Desktop include first-use invitations, help and profile tours by default. See the [complete integration guide](../cli/templates/skills/hai-ui/guide.md).
+
 ## Other exports
 
 ```ts

package/README.ja.md

@@ -98,7 +98,7 @@ export default defineConfig({
 
 > `toast`・型 import・DOM の `Range` と衝突する `Range` を除き、公開 Svelte コンポーネントは `@h-ai/ui/auto-import` で自動注入できます。
 
-管理画面など一部のコンポーネントを使うページは、公開コンポーネントディレクトリーの入口から直接 import できます。テーマツールは軽量な `@h-ai/ui/theme` から読み込み、テーマの利用だけでルート入口の AI・グラフコンポーネントを読み込まないようにします。インストール済みパッケージの exports を確認し、内部 `src/`・`dist/` は import しないでください。
+管理画面など一部のコンポーネントを使うページは、公開コンポーネントディレクトリーの入口から直接 import できます。テーマツールは軽量な `@h-ai/ui/theme` から読み込み、テーマの利用だけでルート入口の AI・グラフコンポーネントを読み込まないようにします。ストアの言語ツールは `@h-ai/ui/i18n` から読み込み、コンポーネントやガイド CSS を読み込みません。インストール済みパッケージの exports を確認し、内部 `src/`・`dist/` は import しないでください。
 
 自動 import はセミコロンなし、複数行、別名の import を認識し、既存のローカル名を重複注入しません。型のみの import は実行時コンポーネントの代わりにはなりません。
 
@@ -166,16 +166,42 @@ components/
 
 `BareInput` の `type="file"` では `onchange` の `event.currentTarget.files` を読み取り、ファイルパスの `value` はバインドしません。他の入力型では `bind:value` を使用できます。
 
-### Compounds：複合コンポーネント（36）
+### Compounds：複合コンポーネント（37）
 
 #### フォーム
 
 | コンポーネント | 説明               | 主なプロパティ                               |
 | -------------- | ------------------ | -------------------------------------------- |
-| `Form`         | フォームコンテナー | `loading`, `disabled`, `onsubmit`            |
-| `FormField`    | フォーム項目       | `label`, `error`, `hint`, `required`         |
+| `Form`         | フォームコンテナー | `columns`, `labelPosition`, `labelWidth`, `loading`, `disabled`, `onsubmit`            |
+| `FormField`    | フォーム項目       | `label`, `for`, `colSpan`, `labelPosition`, `error`, `hint`, `required`         |
+| `FormLayout` | フォーム配置 | `columns`, `labelPosition`, `labelWidth` |
 | `TagInput`     | タグ入力           | `tags`, `maxTags`, `allowDuplicates`, `size` |
 
+#### フォームのレイアウトと検証
+
+`Form` とネイティブ `<form>` 内で使う `FormLayout` は、`columns={1 | 2}`、`labelPosition="top" | "left"`、`labelWidth`（既定 `8rem`）を共有します。既定は1列・ラベルを上に配置します。コンテナー幅が `36rem` 未満では1列、`28rem` 未満では横並びラベルも縦並びになります。
+
+`FormField.colSpan` の既定は `'auto'`。Textarea、ファイル・画像アップロード、TagInput、複数選択 Combobox は2列を占めます。`1` / `2` で指定でき、独自の幅広コントロールには `data-form-wide` を付けます。見出し、エラー概要、操作ボタンなどの非 FormField 要素は行全体を使用します。項目ごとに `labelPosition` / `labelWidth` を上書きできます。
+
+ラベルは内部 UI コントロールに自動で関連付けられます。明示 ID やネイティブ要素は `<FormField for="control-id">` を使います。エラーとヒントは `aria-describedby`、無効な要素は `aria-invalid` で通知し、エラーは重複表示しません。`label` / `error` / `hint` は文字列または翻訳関数を受け取ります。
+
+`Input`、`Textarea`、`Select`、`PasswordInput` のネイティブ検証は中国語・英語に対応します。`validationMessage` は失敗時だけ適用され、有効な入力を無効にし続けません。UI の `setGlobalLocale` / `createLocaleStore` で言語を同期すると表示中のエラーも更新されます。`Textarea` は `minlength` / `maxlength`、`Select` は `name`・必須検証・FormData に対応します。
+
+`LoginForm`、`RegisterForm`、`ChangePasswordForm`、`ForgotPasswordForm`、`ResetPasswordForm`、`AuthPanel`、`UserProfile`、`FeedbackModal` は同じレイアウト設定に対応します。`CrudPage.form` または `CrudEditPanel` に渡します。CRUD 項目は `colSpan` と翻訳関数の `validation.message` に対応し、ボタンと Enter のどちらも送信前に検証します。入力修正でエラーが消えます。サーバー側の検証も必要です。
+
+```svelte
+<!-- m、save、name、notes 为应用自己的翻译、提交回调和状态 -->
+<Form columns={2} labelPosition="left" labelWidth="6rem" onsubmit={save}>
+  <FormField label={() => m.name()} required>
+    <Input name="name" bind:value={name} required />
+  </FormField>
+  <FormField label={() => m.notes()}>
+    <Textarea name="notes" bind:value={notes} />
+  </FormField>
+  <Button type="submit">{m.save()}</Button>
+</Form>
+```
+
 #### フィードバック
 
 | コンポーネント   | 説明           | 主なプロパティ                           |
@@ -248,7 +274,14 @@ components/
 | -------------- | -------------- | ---------------------------------------------- |
 | `PageHeader`   | ページヘッダー | `title`, `description`、`actions` スロット対応 |
 
-### Scenes：用途別コンポーネント（34）
+### Scenes：用途別コンポーネント（36）
+
+#### Guide：案内・ヘルプ（2）
+
+| コンポーネント | 説明 | 主なプロパティ |
+| --- | --- | --- |
+| `GuideHost` | 初回案内・ガイド・ヘルプダイアログ | `guide`, `locale`, `scope`, `autoStart` |
+| `HelpCenter` | 独立して使える検索付きヘルプ | `articles`, `tours`, `locale`, `selectedId`, `onstart` |
 
 #### App：アプリ全体（7）
 
@@ -524,7 +557,7 @@ components/
   crud={roleCrud}
   {data}
   permissions={{ create: true, update: true, delete: true }}
-  form={{ variant: 'modal', modalSize: 'lg' }}
+  form={{ variant: 'modal', modalSize: '3xl', columns: 2, labelPosition: 'top' }}
   pagination={{ showSizeChanger: true, showJumper: true, pageSizeOptions: [10, 20, 50] }}
   density='compact'
   detailColumns={['name']}
@@ -691,7 +724,7 @@ transformPageChunk: ({ html }) => html.replace('%theme_bootstrap%', themeBootstr
 
 ```svelte
 <script>
-  import { createLocaleStore, setGlobalLocale } from '@h-ai/ui'
+  import { createLocaleStore, setGlobalLocale } from '@h-ai/ui/i18n'
   import { setLocale } from '$lib/paraglide/runtime'
 
   const localeStore = createLocaleStore()
@@ -722,7 +755,7 @@ import {
   isLocaleSupported, // 检查 locale 是否支持
   resolveLocale, // 解析 locale（支持回退）
   setGlobalLocale, // 设置全局 locale（同步 @h-ai/core）
-} from '@h-ai/ui'
+} from '@h-ai/ui/i18n'
 ```
 
 ## 設定による認証画面
@@ -756,6 +789,58 @@ AuthPanel は SSR 中のフォーム操作を無効にし、クライアント
 
 [完整 IAM 配置 / IAM configuration](../iam/README.ja.md)
 
+## 初回ガイドとヘルプセンター
+
+`@h-ai/ui/guide` から `createGuide`、`GuideHost`、`HelpCenter` をインポートします。init/close は不要です。ガイド開始時にエンジンを読み込み、既存テーマと中国語・英語の共通文言を使用します。業務内容はアプリの翻訳関数を使います。
+
+同じ入口の `resolveGuideText(text?)` は文字列や i18n コールバックを評価します。ホストコンポーネントは文言を自動で解析します。
+
+レイアウト内でコントローラーを作成し、id/title/steps と任意の route/version を登録します。`<GuideHost {guide} {locale} scope={user.id} autoStart='overview' />` を配置し、対象コンポーネントに data-guide を付けます。SPA は既存の NavAdapter を提供してください。
+
+```svelte
+<script lang='ts'>
+  import { createGuide, GuideHost } from '@h-ai/ui/guide'
+
+  const guide = createGuide({
+    nav,
+    persistKey: 'my-app-guide',
+    tours: [{
+      id: 'users',
+      version: 1,
+      route: '/users',
+      title: () => m.guide_users_title(),
+      description: () => m.guide_users_description(),
+      steps: [{
+        target: 'users-create',
+        title: () => m.guide_create_title(),
+        description: () => m.guide_create_description(),
+      }],
+    }],
+    articles: [{
+      id: 'users-help',
+      title: () => m.guide_users_title(),
+      content: () => m.guide_users_markdown(),
+      tourId: 'users',
+    }],
+  })
+</script>
+
+<GuideHost {guide} {locale} scope={user.id} autoStart='users' />
+<Button onclick={() => guide.openHelp()}>{m.help()}</Button>
+<!-- 在目标页面为现有按钮添加锚点，无需额外包装。 -->
+<Button data-guide='users-create' onclick={createUser}>{m.create_user()}</Button>
+```
+
+start(id) は Promise<boolean> を返し、手動で再表示できます。失敗時は false と error を設定します。startIfNeeded(id) は初回案内の有無を boolean で返します。openHelp(articleId?) は検索付き Markdown ヘルプを開き、stop() は完了として記録せず終了し、reset(id) は現在のユーザーの状態を削除します。
+
+閉じるボタン、Escape、オーバーレイのクリックは、最初の位置決めフレームが完了する前でも待機と `busy` 状態を解除します。開始中の `start()` は false を返し、完了として記録しません。
+
+保存先は cookie（既定）、localStorage、memory です。保存が制限された環境ではインスタンス内のメモリーに戻ります。ユーザーとバージョンごとに状態を分け、後で表示は一日延期、Cookie は一年保存します。既定のページ遷移は短期 sessionStorage 記録で移動先から開始します。
+
+文言は `() => m.key()` で遅延評価し、現在の locale を渡します。説明はプレーンテキスト、ヘルプは安全な MarkdownRenderer を使用し、生 HTML を無効にします。要素の待機は既定で 3000ms。before(signal) でタブ等を準備し、optional の要素のみ省略できます。必要な要素がなければ終了し、アンマウント時に処理を解除します。SSR ユーザー間でコントローラーを共有しないでください。
+
+HelpCenter は articles、任意の tours、locale、selectedId、onstart で独立ページにも配置できます。admin-console と CLI fullstack Web/App/Desktop は初回案内、ヘルプ、プロフィールガイドを標準搭載します。[詳細ガイド](../cli/templates/skills/hai-ui/guide.md)を参照してください。
+
 ## その他のエクスポート
 
 ```ts

package/README.md

@@ -98,7 +98,7 @@ export default defineConfig({
 
 > 除 `toast`、类型导入与 `Range`（会和 DOM `Range` 构造器冲突）外，其余公开 Svelte 组件都可通过 `@h-ai/ui/auto-import` 自动注入。
 
-管理后台等只使用部分组件的页面，可直接使用公开组件目录入口；主题工具通过轻量 `@h-ai/ui/theme` 导入，避免主题消费加载根入口中的 AI、图表等组件。组件路径以已安装版本的 exports 为准，不导入包内 `src/` 或 `dist/`。
+管理后台等只使用部分组件的页面，可直接使用公开组件目录入口；主题工具通过轻量 `@h-ai/ui/theme` 导入，避免主题消费加载根入口中的 AI、图表等组件。状态层的语言工具使用 `@h-ai/ui/i18n`，不加载组件与引导 CSS。组件路径以已安装版本的 exports 为准，不导入包内 `src/` 或 `dist/`。
 
 自动导入器识别无分号、跨行及带别名的显式导入，已绑定的组件名称不会重复注入；仅类型导入不会替代运行时组件。
 
@@ -166,16 +166,42 @@ components/
 
 `BareInput` 的 `file` 类型通过 `onchange` 读取 `event.currentTarget.files`，不绑定文件路径 `value`；其他输入类型可使用 `bind:value`。
 
-### 组合组件 Compounds（36 个）
+### 组合组件 Compounds（37 个）
 
 #### 表单
 
 | 组件        | 描述     | 主要属性                                     |
 | ----------- | -------- | -------------------------------------------- |
-| `Form`      | 表单容器 | `loading`, `disabled`, `onsubmit`            |
-| `FormField` | 表单字段 | `label`, `error`, `hint`, `required`         |
+| `Form`      | 表单容器 | `columns`, `labelPosition`, `labelWidth`, `loading`, `disabled`, `onsubmit`            |
+| `FormField` | 表单字段 | `label`, `for`, `colSpan`, `labelPosition`, `error`, `hint`, `required`         |
+| `FormLayout` | 表单布局 | `columns`, `labelPosition`, `labelWidth` |
 | `TagInput`  | 标签输入 | `tags`, `maxTags`, `allowDuplicates`, `size` |
 
+#### 表单布局与校验
+
+`Form` 和可嵌入原生 `<form>` 的 `FormLayout` 共用 `columns={1 | 2}`、`labelPosition="top" | "left"`、`labelWidth`（默认 `8rem`）。默认单列、标签独立成行；双列在容器不足 `36rem` 时收为单列，同行标签在容器不足 `28rem` 时改为上下排列。
+
+`FormField.colSpan` 默认 `'auto'`：多行文本、文件/图片上传、TagInput 和多选 Combobox 自动占两列；`1` / `2` 显式覆盖。自定义宽控件标注 `data-form-wide`。标题、错误摘要、按钮及其他非 FormField 内容自动独占一行。字段可单独覆盖 `labelPosition` / `labelWidth`。
+
+标签自动关联内部 UI 控件；已有控件 ID 或原生控件使用 `<FormField for="control-id">`。错误/提示通过 `aria-describedby` 关联，错误控件带 `aria-invalid`，只显示一份字段提示。`label` / `error` / `hint` 支持字符串或延迟翻译函数。
+
+`Input`、`Textarea`、`Select` 和 `PasswordInput` 的原生校验使用内置中英文提示；`validationMessage` 只覆盖失败提示，不让有效输入一直无效。应用通过 UI 的 `setGlobalLocale` / `createLocaleStore` 同步语言，已显示的校验错误即时更新。`Textarea` 支持 `minlength` / `maxlength`，`Select` 支持 `name`、必填校验和 FormData 序列化。
+
+`LoginForm`、`RegisterForm`、`ChangePasswordForm`、`ForgotPasswordForm`、`ResetPasswordForm`、`AuthPanel`、`UserProfile` 和 `FeedbackModal` 接受同一组布局参数。`CrudPage` 通过 `form` 传入；`CrudEditPanel` 直接接收。CRUD 字段支持 `colSpan`，`validation.message` 支持翻译函数；按钮与回车均先校验，修正后错误消失，客户端校验不能替代服务端校验。
+
+```svelte
+<!-- m、save、name、notes 为应用自己的翻译、提交回调和状态 -->
+<Form columns={2} labelPosition="left" labelWidth="6rem" onsubmit={save}>
+  <FormField label={() => m.name()} required>
+    <Input name="name" bind:value={name} required />
+  </FormField>
+  <FormField label={() => m.notes()}>
+    <Textarea name="notes" bind:value={notes} />
+  </FormField>
+  <Button type="submit">{m.save()}</Button>
+</Form>
+```
+
 #### 反馈
 
 | 组件             | 描述     | 主要属性                          |
@@ -248,7 +274,14 @@ components/
 | ------------ | -------- | ------------------------------------------- |
 | `PageHeader` | 页面头部 | `title`, `description`，支持 `actions` 插槽 |
 
-### 场景组件 Scenes（34 个）
+### 场景组件 Scenes（36 个）
+
+#### Guide 引导与帮助（2 个）
+
+| 组件 | 描述 | 主要属性 |
+| --- | --- | --- |
+| `GuideHost` | 首次邀请、页面导览与帮助弹窗宿主 | `guide`, `locale`, `scope`, `autoStart` |
+| `HelpCenter` | 可独立使用的帮助中心 | `articles`, `tours`, `locale`, `selectedId`, `onstart` |
 
 #### App 应用级（7 个）
 
@@ -523,7 +556,7 @@ components/
   crud={roleCrud}
   {data}
   permissions={{ create: true, update: true, delete: true }}
-  form={{ variant: 'modal', modalSize: 'lg' }}
+  form={{ variant: 'modal', modalSize: '3xl', columns: 2, labelPosition: 'top' }}
   pagination={{ showSizeChanger: true, showJumper: true, pageSizeOptions: [10, 20, 50] }}
   density='compact'
   detailColumns={['name']}
@@ -721,7 +754,7 @@ AuthPanel 在 SSR 阶段禁用原生表单控件，客户端挂载并绑定事
 
 ```svelte
 <script>
-  import { createLocaleStore, setGlobalLocale } from '@h-ai/ui'
+  import { createLocaleStore, setGlobalLocale } from '@h-ai/ui/i18n'
   import { setLocale } from '$lib/paraglide/runtime'
 
   const localeStore = createLocaleStore()
@@ -752,7 +785,7 @@ import {
   isLocaleSupported, // 检查 locale 是否支持
   resolveLocale, // 解析 locale（支持回退）
   setGlobalLocale, // 设置全局 locale（同步 @h-ai/core）
-} from '@h-ai/ui'
+} from '@h-ai/ui/i18n'
 ```
 
 
@@ -773,6 +806,59 @@ import {
 上例的 subscribe 为应用自身的 $state，应用包装 register 动作校验/提交扩展业务数据；如需单独组合表单，使用 `<RegisterForm> {#snippet extraFields()}...{/snippet} </RegisterForm>`。扩展里的按钮须为 `type="button"`，避免误提交。
 
 
+## 新手引导与帮助中心
+
+`@h-ai/ui/guide` 提供 `createGuide`、`GuideHost`、`HelpCenter` 和相关类型。无需 init/close；引擎在开始导览时按需加载，浮层复用当前主题。组件内置中英文按钮、进度和错误提示，业务内容使用应用 i18n。
+
+同一入口的 `resolveGuideText(text?)` 可解析字符串或 i18n 回调；宿主组件已自动解析文案。
+
+下例放在应用布局中；`nav` 是应用现有 NavAdapter，`locale`、`user` 与翻译函数 `m` 来自应用，翻译 key 需在应用消息中定义。目标按钮放在 `/users` 页面。
+
+```svelte
+<script lang='ts'>
+  import { createGuide, GuideHost } from '@h-ai/ui/guide'
+
+  const guide = createGuide({
+    nav,
+    persistKey: 'my-app-guide',
+    tours: [{
+      id: 'users',
+      version: 1,
+      route: '/users',
+      title: () => m.guide_users_title(),
+      description: () => m.guide_users_description(),
+      steps: [{
+        target: 'users-create',
+        title: () => m.guide_create_title(),
+        description: () => m.guide_create_description(),
+      }],
+    }],
+    articles: [{
+      id: 'users-help',
+      title: () => m.guide_users_title(),
+      content: () => m.guide_users_markdown(),
+      tourId: 'users',
+    }],
+  })
+</script>
+
+<GuideHost {guide} {locale} scope={user.id} autoStart='users' />
+<Button onclick={() => guide.openHelp()}>{m.help()}</Button>
+<!-- 在目标页面为现有按钮添加锚点，无需额外包装。 -->
+<Button data-guide='users-create' onclick={createUser}>{m.create_user()}</Button>
+```
+
+- `start(id)` 返回 `Promise<boolean>`，允许手动重看；失败返回 false 并设置 `error`。`startIfNeeded(id)` 返回 boolean 并显示首次邀请，通常由 autoStart 处理。
+- `openHelp(articleId?)` 打开帮助，`stop()` 取消导览，`reset(id)` 删除当前用户的偏好。完成、稍后和不再提醒分别记录；稍后暂缓一天，Cookie 默认保存一年。
+- 关闭按钮、Escape 和遮罩点击在首帧定位期间也会取消等待、清除 `busy`；启动中的 `start()` 返回 false，不记录完成。
+- `persistence` 支持 cookie（默认）、localStorage、memory；受限存储回退到实例内存。scope 使用非敏感用户标识，version 变化会重新提示。
+- 通过已有 NavAdapter 接入 SvelteKit、SPA 或原生 WebView；默认完整导航使用 sessionStorage 保存短期启动记录。宿主只在浏览器挂载后读取记录，SSR 实例不得跨用户共享。
+- 目标等待默认 3000ms，可用 waitTimeout 调整。before(signal) 可展开页签/抽屉；必要元素缺失停止，可选步骤使用 optional 跳过。引导不会自动提交业务表单。
+- 业务文案用函数延迟求值，并传入当前 locale。步骤内容按纯文本显示；帮助正文复用安全 MarkdownRenderer，原始 HTML 关闭。
+- HelpCenter 可独立放入帮助页面，props 为 articles、tours（可选）、locale、selectedId 和 onstart；支持类别标签、标题/正文搜索和关联导览。
+
+admin-console 示例和 CLI fullstack Web/App/Desktop 默认包含帮助入口、首次邀请及个人资料导览。完整配置和验证场景见 [引导指南](../cli/templates/skills/hai-ui/guide.md)。
+
 ## 其他导出
 
 ```ts

package/auto-import.d.ts

@@ -16,6 +16,8 @@ type AutoImportHaiUiPreprocessor = {
 export function autoImportHaiUi(): AutoImportHaiUiPreprocessor
 
 declare global {
+  const GuideHost: typeof import('@h-ai/ui')['GuideHost']
+  const HelpCenter: typeof import('@h-ai/ui')['HelpCenter']
   // primitives
   const Avatar: typeof import('@h-ai/ui')['Avatar']
   const Badge: typeof import('@h-ai/ui')['Badge']
@@ -56,6 +58,7 @@ declare global {
   const Empty: typeof import('@h-ai/ui')['Empty']
   const Form: typeof import('@h-ai/ui')['Form']
   const FormField: typeof import('@h-ai/ui')['FormField']
+  const FormLayout: typeof import('@h-ai/ui')['FormLayout']
   const InfiniteScroll: typeof import('@h-ai/ui')['InfiniteScroll']
   const MessageContainer: typeof import('@h-ai/ui')['MessageContainer']
   const MessageBoxContainer: typeof import('@h-ai/ui')['MessageBoxContainer']

package/auto-import.js

@@ -49,6 +49,7 @@ const UI_COMPONENTS = new Set([
   'Empty',
   'Form',
   'FormField',
+  'FormLayout',
   'InfiniteScroll',
   'MessageContainer',
   'MessageBoxContainer',
@@ -77,6 +78,8 @@ const UI_COMPONENTS = new Set([
   'ThemeColorPicker',
   'ThemeSelector',
   'ThemeToggle',
+  'GuideHost',
+  'HelpCenter',
   // scenes - iam
   'AuthShell',
   'AuthPanel',

package/dist/components/compounds/Combobox.svelte

@@ -34,8 +34,10 @@
   />
 -->
 <script lang='ts'>
-  import type { DataAttributes, Size } from '../../types.js'
+  import type { DataAttributes, FormText, Size } from '../../types.js'
   import { Combobox } from 'bits-ui'
+  import { getFormFieldContext } from '../../internal/form-context.js'
+  import { resolveFormText } from '../../internal/form-validation.svelte.js'
   import { uiM } from '../../messages.js'
   import { cn, getDataAttributes } from '../../utils.js'
   import { getFormControlSizeClasses } from '../control-size.js'
@@ -67,7 +69,7 @@
     /** 是否禁用 */
     disabled?: boolean
     /** 错误消息 */
-    error?: string
+    error?: FormText
     /** 表单标签 */
     label?: string
     /** 自定义类名 */
@@ -91,6 +93,11 @@
   }: Props & DataAttributes = $props()
 
   const dataAttributes = $derived(getDataAttributes(restProps))
+  const field = getFormFieldContext()
+  const uniqueId = $props.id()
+  const messageId = `${uniqueId}-message`
+  const localError = $derived(resolveFormText(error))
+  const effectiveError = $derived(field?.error || localError)
   const sizeClasses = $derived(getFormControlSizeClasses(size))
   // 为未提供 value 时设置初始默认值（仅在初始化时执行一次）
   // 统一以空字符串初始化，避免在初始化阶段捕获 multiple 的初始值。
@@ -101,7 +108,7 @@
 
   // ─── 统一视觉样式（与 Select 对齐：rounded-lg / 柔和边框 / focus ring） ───
   const controlStateClass = $derived(
-    error
+    effectiveError
       ? 'border-error/60 focus-within:ring-2 focus-within:ring-error/15'
       : 'border-base-content/15 hover:border-base-content/25 focus-within:border-primary/50 focus-within:ring-2 focus-within:ring-primary/10',
   )
@@ -200,7 +207,7 @@
   }
 </script>
 
-<div {...dataAttributes} class='fieldset w-full {className}'>
+<div {...dataAttributes} class='fieldset w-full {className}' data-form-wide={multiple ? '' : undefined}>
   {#if fieldLabel}
     <legend class='fieldset-legend font-medium'>{fieldLabel}</legend>
   {/if}
@@ -243,6 +250,9 @@
           {/each}
 
           <Combobox.Input
+            id={field?.controlId}
+            aria-invalid={effectiveError ? true : undefined}
+            aria-describedby={[field?.messageId, localError && !field?.error ? messageId : ''].filter(Boolean).join(' ') || undefined}
             bind:ref={inputRef}
             class={cn('flex-1 min-w-20 bg-transparent py-0.5 outline-none placeholder:text-base-content/40', sizeClasses.spacing)}
             placeholder={selectedOptions.length === 0 ? placeholder : ''}
@@ -312,6 +322,9 @@
     >
       <div class='relative'>
         <Combobox.Input
+          id={field?.controlId}
+          aria-invalid={effectiveError ? true : undefined}
+          aria-describedby={[field?.messageId, localError && !field?.error ? messageId : ''].filter(Boolean).join(' ') || undefined}
           bind:ref={inputRef}
           class={cn(
             'w-full rounded-lg border bg-base-100 pr-9 outline-none transition-[border-color,box-shadow] duration-150 placeholder:text-base-content/40',
@@ -372,7 +385,7 @@
     </Combobox.Root>
   {/if}
 
-  {#if error}
-    <span class='fieldset-label text-error'>{error}</span>
+  {#if localError && !field?.error}
+    <p id={messageId} class='mt-1.5 text-xs text-error leading-relaxed break-words' aria-live='polite'>{localError}</p>
   {/if}
 </div>

package/dist/components/compounds/Combobox.svelte.d.ts

@@ -1,4 +1,4 @@
-import type { DataAttributes, Size } from '../../types.js';
+import type { DataAttributes, FormText, Size } from '../../types.js';
 import { Combobox } from 'bits-ui';
 /** 选项定义 */
 interface Option {
@@ -25,7 +25,7 @@ interface Props {
     /** 是否禁用 */
     disabled?: boolean;
     /** 错误消息 */
-    error?: string;
+    error?: FormText;
     /** 表单标签 */
     label?: string;
     /** 自定义类名 */