@h-ai/cli 0.1.0-alpha.62 → 0.1.0-alpha.64

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/cli",
   "type": "module",
-  "version": "0.1.0-alpha.62",
+  "version": "0.1.0-alpha.64",
   "description": "Hai Framework CLI for project scaffolding and code generation.",
   "license": "Apache-2.0",
   "keywords": [
@@ -30,7 +30,7 @@
     "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
   },
   "dependencies": {
-    "@h-ai/core": "0.1.0-alpha.62",
+    "@h-ai/core": "0.1.0-alpha.64",
     "cac": "^7.0.1",
     "chalk": "^6.0.1",
     "fast-wrap-ansi": "^0.2.2",
@@ -41,11 +41,11 @@
     "yaml": "^2.9.1"
   },
   "devDependencies": {
-    "@h-ai/cache": "0.1.0-alpha.62",
-    "@h-ai/deploy": "0.1.0-alpha.62",
-    "@h-ai/reach": "0.1.0-alpha.62",
-    "@h-ai/reldb": "0.1.0-alpha.62",
-    "@h-ai/storage": "0.1.0-alpha.62",
+    "@h-ai/cache": "0.1.0-alpha.64",
+    "@h-ai/deploy": "0.1.0-alpha.64",
+    "@h-ai/reach": "0.1.0-alpha.64",
+    "@h-ai/reldb": "0.1.0-alpha.64",
+    "@h-ai/storage": "0.1.0-alpha.64",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^26.6.5",
     "@types/prompts": "^2.4.9",

package/templates/README.md

@@ -157,3 +157,7 @@ import { iam } from '@h-ai/iam'
 选用 IAM 的 admin/h5/website 模板提供 AuthPanel 和标准认证路由；mobile-app 与 fullstack Web/App/Desktop 使用 API 客户端共享动作。修改服务端 config/_iam.yml 即可控制登录方式、注册、重置、协议和品牌，无需改表单。配置 Reach 模板和真实发送 Provider 后启用 OTP/重置。分布式部署使用共享数据库与 Redis。
 
 LDAP/Reach 是可选 peer；IAM 不强制启用 Reach。默认 LDAP 客户端由应用选择安装 ldapts。自定义通知回调、协议弹窗、表单 snippet 用法随 hai-iam/hai-ui skills 完整复制到生成项目，不能要求应用读取本仓库私有路径。
+
+## 表单布局
+
+新增/编辑复用 `@h-ai/ui` 的 Form/FormLayout/FormField：可选一列或双列、标签独立成行或与控件同行，多行文本与多选自动跨列，窄容器自动收为一列。CRUD 使用 `form` 配置，字段可用 `colSpan` 覆盖。错误显示在字段附近并随 UI 语言更新。website 联系页采用 FormLayout + FormField；fullstack 共享用户编辑页采用双列同行标签，个人资料与密码页复用 UI 场景组件。没有数据表单的模板保留现有骨架，新增表单按 hai-ui skill 接入。

package/templates/apps/fullstack/e2e/fullstack.spec.ts.hbs

@@ -61,6 +61,76 @@ test('service rejects plaintext business requests', async ({ request }) => {
 })
 
 {{#if fullstack.e2eFrontend}}
+test('branded authentication, profile layout and blur validation work across screen sizes', async ({ page }, testInfo) => {
+  test.setTimeout(60_000)
+  await page.setViewportSize({ width: 1440, height: 960 })
+  await page.goto('/')
+  await expect(page.getByRole('heading', { name: configuredName, exact: true })).toBeVisible()
+  await capture(page, '{{projectName}}-login-desktop.png', testInfo.outputPath('login-desktop.png'))
+  await page.getByRole('button', { name: /立即注册|Register now/, exact: true }).click()
+  await expect(page.locator('.register-form')).toBeVisible()
+  await capture(page, '{{projectName}}-register-desktop.png', testInfo.outputPath('register-desktop.png'))
+  await page.setViewportSize({ width: 390, height: 844 })
+  await capture(page, '{{projectName}}-register-mobile.png', testInfo.outputPath('register-mobile.png'))
+  expect(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth)).toBe(true)
+  await page.reload()
+  await capture(page, '{{projectName}}-login-mobile.png', testInfo.outputPath('login-mobile.png'))
+  await page.setViewportSize({ width: 1440, height: 960 })
+  await login(page, 'admin', adminPassword)
+  await page.getByTestId('nav-settings').click()
+  const profile = page.getByTestId('profile-form')
+  await expect(profile).toBeVisible()
+  const email = profile.locator('input[name="email"]')
+  await email.fill('invalid-email')
+  await email.press('Tab')
+  await expect(email).toHaveAttribute('aria-invalid', 'true')
+  await capture(page, '{{projectName}}-profile-blur-error.png', testInfo.outputPath('profile-blur-error.png'))
+  await email.fill('')
+  await expect(email).not.toHaveAttribute('aria-invalid')
+  await capture(page, '{{projectName}}-settings-desktop.png', testInfo.outputPath('settings-desktop.png'))
+  for (const width of [768, 390]) {
+    await page.setViewportSize({ width, height: 960 })
+    const fields = await profile.locator('.hai-form-field').evaluateAll(elements => elements.map((field) => {
+      const label = field.querySelector('label')!.getBoundingClientRect()
+      const control = field.querySelector('input')!.getBoundingClientRect()
+      return { labelBottom: label.bottom, controlTop: control.top, controlRight: control.right }
+    }))
+    for (const field of fields) {
+      expect(field.labelBottom).toBeLessThanOrEqual(field.controlTop)
+      expect(field.controlRight).toBeLessThanOrEqual(width)
+    }
+    expect(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth)).toBe(true)
+    await capture(page, `{{projectName}}-settings-${width}.png`, testInfo.outputPath(`settings-${width}.png`))
+  }
+  await page.getByTestId('password-form').scrollIntoViewIfNeeded()
+  await capture(page, '{{projectName}}-password-mobile.png', testInfo.outputPath('password-mobile.png'))
+  await page.setViewportSize({ width: 1440, height: 960 })
+  await page.getByTestId('nav-users').click()
+  await page.getByTestId('create-user').click()
+  const username = page.getByTestId('user-username').locator('input')
+  await username.focus()
+  await username.press('Tab')
+  await expect(username).toHaveAttribute('aria-invalid', 'true')
+  await username.fill('a')
+  await expect(username).toHaveAttribute('aria-invalid', 'true')
+  await page.getByTestId('user-password').locator('input').fill('short')
+  await page.getByTestId('user-password').locator('input').press('Tab')
+  await expect(page.getByTestId('user-password').locator('input')).toHaveAttribute('aria-invalid', 'true')
+  await capture(page, '{{projectName}}-create-blur-error.png', testInfo.outputPath('create-blur-error.png'))
+  await page.getByTestId('user-editor').getByRole('button', { name: /取消|Cancel/, exact: true }).click()
+  await page.getByTestId('create-user').click()
+  await expect(page.getByTestId('user-editor').locator('[aria-invalid="true"]')).toHaveCount(0)
+  await page.getByTestId('user-editor').getByRole('button', { name: /取消|Cancel/, exact: true }).click()
+  await userEditor(page, 'admin')
+  const editEmail = page.getByTestId('user-email').locator('input')
+  await editEmail.fill('invalid-email')
+  await editEmail.press('Tab')
+  await expect(editEmail).toHaveAttribute('aria-invalid', 'true')
+  await capture(page, '{{projectName}}-edit-blur-error.png', testInfo.outputPath('edit-blur-error.png'))
+  await editEmail.fill('admin@example.com')
+  await expect(editEmail).not.toHaveAttribute('aria-invalid')
+})
+
 test('first-use tour, help search and settings navigation work on desktop and mobile', async ({ page }, testInfo) => {
   await page.goto('/')
   await login(page, 'admin', adminPassword, true)

package/templates/apps/fullstack/packages/{{projectName}}-shared/README.md.hbs

@@ -43,8 +43,14 @@ Run root `pnpm typecheck`, `pnpm lint`, `pnpm build`, `pnpm test` and `pnpm test
 
 The service's `config/_iam.yml` controls login methods, registration, password reset, agreements and `ui` branding. Email and SMS use providers/templates in `_reach.yml` or custom callbacks. `AuthPanel` uses the public configuration and framework auth actions to manage tokens, resend countdowns and errors. All service nodes must share the same database and Redis; memory cache is for a single process.
 
+Authentication defaults to a split layout. Set `ui.variant`, `title`, `subtitle`, `brandTitle`, `brandText`, `logoUrl` and `illustrationUrl` to customize login and registration. Without a `brandTitle`, the displayed application name comes from `app.info` and follows `core` configuration.
+
 LDAP and Reach are optional. Install ldapts in the IAM service workspace only when using its default LDAP client, then enable login.ldap and set connection settings. Custom onOtpSendEmail/onOtpSendSms/onPasswordResetRequest callbacks work without Reach and must reject on delivery failure. Agreements open in a Modal. LoginForm/RegisterForm support header/extraFields/footer snippets; AuthPanel forwards loginHeader/loginFields/loginFooter and registerHeader/registerFields/registerFooter. See the generated hai-iam/hai-ui skills for configuration and examples.
 
 协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
 
 See `.agents/skills/hai-iam/reference.md` in the generated application for the complete contract.
+
+## Form layouts
+
+The user editor uses `FormLayout columns={2} labelPosition="left"`. Personal settings use a bounded page width, stacked labels and a single avatar editor. Narrow containers automatically stack fields and labels. UI controls and CRUD forms show client validation on blur, update errors while correcting input and validate untouched fields on submit. Field errors follow the current UI language. The management store syncs locale through the lightweight `@h-ai/ui/i18n` entry, without loading components or tour CSS. Configure `colSpan` on FormField to override automatic spans for textareas, uploads and multiple choices.

package/templates/apps/fullstack/packages/{{projectName}}-shared/src/lib/components/AdminWorkspace.svelte.hbs

@@ -21,6 +21,10 @@
   // 宿主平台在组件生命周期中固定，引导控制器只创建一次。
   const guide = untrack(() => createManagementGuide(store, platform))
   let resetToken = $state('')
+  const authConfig = $derived(store.authConfig && {
+    ...store.authConfig,
+    ui: { ...store.authConfig.ui, brandTitle: store.authConfig.ui.brandTitle || store.info?.name },
+  })
   async function authenticated() {
     await store.authenticated()
     if (resetToken) {
@@ -65,7 +69,7 @@
       {:else}
         <div data-testid='login-form'>
           {#if store.authConfig && store.error}<Alert variant='error' class='mx-auto max-w-lg'>{store.error}</Alert>{/if}
-          <AuthPanel config={store.authConfig} actions={managementAuthActions} {resetToken} initialMode={resetToken ? 'reset' : 'login'} error={store.authConfig ? '' : store.error} onretry={() => void store.initialize(apiOptions, onLocaleChange)} onauthenticated={authenticated} />
+          <AuthPanel config={authConfig} actions={managementAuthActions} {resetToken} initialMode={resetToken ? 'reset' : 'login'} error={store.authConfig ? '' : store.error} onretry={() => void store.initialize(apiOptions, onLocaleChange)} onauthenticated={authenticated} />
         </div>
         <p class='fixed bottom-3 left-0 right-0 text-center text-xs text-base-content/50'><span data-testid='app-name'>{store.info.name}</span> · <span data-testid='app-version'>v{store.info.version}</span> · <span data-testid='app-environment'>{store.info.env}</span></p>
       {/if}

package/templates/apps/fullstack/packages/{{projectName}}-shared/src/lib/components/ProfileSettings.svelte.hbs

@@ -1,7 +1,7 @@
 <script lang='ts'>
   import type { ManagementStore } from '../stores/management-store.svelte.js'
-  import { Card } from '@h-ai/ui/components/compounds/index'
-  import { Avatar, Select } from '@h-ai/ui/components/primitives/index'
+  import { Card, FormField, FormLayout } from '@h-ai/ui/components/compounds/index'
+  import { Badge, Select } from '@h-ai/ui/components/primitives/index'
   import { ChangePasswordForm, UserProfile } from '@h-ai/ui/components/scenes/iam/index'
   import { getThemeInfo } from '@h-ai/ui/theme'
   import * as m from '../paraglide/messages.js'
@@ -14,44 +14,33 @@
   const themeOptions = AVAILABLE_THEMES.map(theme => ({ value: theme, label: getThemeInfo(theme)?.name ?? theme }))
 </script>
 
-<section class='space-y-5' data-testid='settings-page'>
+<section class='mx-auto w-full max-w-4xl space-y-6' data-testid='settings-page'>
   <div>
     <h1 class='text-xl font-semibold tracking-tight'>{m.settings_title()}</h1>
     <p class='mt-1 text-sm text-base-content/50'>{m.settings_description()}</p>
   </div>
   {#if store.user}
-    <div class='grid gap-5 xl:grid-cols-[0.75fr_1.25fr]'>
-      <Card bordered shadow={false} class='h-fit'>
-        <div class='flex items-center gap-4'>
-          <Avatar name={store.user.displayName || store.user.username} src={store.user.avatarUrl} size='lg' />
-          <div class='min-w-0'>
-            <h2 class='truncate text-lg font-semibold'>{store.user.displayName || store.user.username}</h2>
-            <p class='text-sm text-base-content/50'>@{store.user.username}</p>
-            <p class='mt-2 text-xs text-primary'>{store.isAdmin ? m.role_admin() : m.role_user()}</p>
-          </div>
-        </div>
-        <p class='mt-4 text-xs leading-6 text-base-content/50'>{m.avatar_hint()}</p>
-      </Card>
-      <Card title={m.profile_title()} bordered shadow={false} data-guide='admin-profile-form'>
-        <UserProfile user={store.user} editable alwaysEditable fields={['avatar', 'displayName', 'email']} avatarAccept='image/png,image/jpeg,image/webp' avatarHint={m.avatar_hint()} loading={store.saving} onsubmit={data => store.saveProfile(data)} onavatarchange={file => void store.uploadAvatar(file)} data-testid='profile-form' />
-      </Card>
-    </div>
+    <Card title={m.profile_title()} bordered shadow={false} data-guide='admin-profile-form'>
+      <div class='mb-5 flex flex-wrap items-center gap-3 border-b border-base-content/8 pb-4'>
+        <p class='min-w-0 break-all text-sm text-base-content/55'>@{store.user.username}</p>
+        <Badge size='sm' variant='ghost'>{store.isAdmin ? m.role_admin() : m.role_user()}</Badge>
+      </div>
+      <UserProfile columns={2} user={store.user} editable alwaysEditable fields={['avatar', 'displayName', 'email']} avatarAccept='image/png,image/jpeg,image/webp' avatarHint={m.avatar_hint()} loading={store.saving} onsubmit={data => store.saveProfile(data)} onavatarchange={file => void store.uploadAvatar(file)} data-testid='profile-form' />
+    </Card>
     <Card title={m.preferences_title()} bordered shadow={false} data-guide='admin-preferences'>
       <p class='mb-5 text-sm text-base-content/50'>{m.preferences_description()}</p>
-      <div class='grid gap-6 sm:grid-cols-2'>
-        <div class='space-y-2'>
-          <label class='text-sm font-medium' for='profile-language'>{m.settings_language()}</label>
+      <FormLayout columns={2}>
+        <FormField label={m.settings_language()} for='profile-language'>
           <Select id='profile-language' value={store.locale} options={languageOptions} disabled={store.saving} onchange={locale => void store.savePreferences({ locale })} data-testid='profile-language' />
-        </div>
-        <div class='space-y-2'>
-          <label class='text-sm font-medium' for='profile-theme'>{m.settings_theme()}</label>
+        </FormField>
+        <FormField label={m.settings_theme()} for='profile-theme'>
           <Select id='profile-theme' value={themeStore.current} options={themeOptions} disabled={store.saving} onchange={theme => void store.savePreferences({ theme })} data-testid='profile-theme' />
-        </div>
-      </div>
+        </FormField>
+      </FormLayout>
     </Card>
     <Card title={m.password_title()} bordered shadow={false} data-guide='admin-password'>
       <p class='mb-5 text-sm text-base-content/50'>{m.password_rules()}</p>
-      <div class='max-w-xl'><ChangePasswordForm loading={store.saving} passwordPolicy={store.authConfig?.password} minPasswordLength={store.authConfig?.password.minLength ?? 8} onsubmit={data => store.changePassword(data)} data-testid='password-form' /></div>
+      <ChangePasswordForm loading={store.saving} passwordPolicy={store.authConfig?.password} minPasswordLength={store.authConfig?.password.minLength ?? 8} onsubmit={data => store.changePassword(data)} data-testid='password-form' />
     </Card>
   {/if}
 </section>

package/templates/apps/fullstack/packages/{{projectName}}-shared/src/lib/components/UserManagement.svelte.hbs

@@ -1,7 +1,7 @@
 <script lang="ts">
   import type { AdminRoleCode, AdminUser } from '{{fullstack.contractPackageName}}'
   import type { ManagementStore } from '../stores/management-store.svelte.js'
-  import { Card, DataTable, FormField, Modal, Pagination, Skeleton } from '@h-ai/ui/components/compounds/index'
+  import { Card, DataTable, FormField, FormLayout, Modal, Pagination, Skeleton } from '@h-ai/ui/components/compounds/index'
   import { Avatar, Badge, BareInput, Button, Checkbox, Input, Select } from '@h-ai/ui/components/primitives/index'
   import { PasswordInput } from '@h-ai/ui/components/scenes/iam/index'
   import * as m from '../paraglide/messages.js'
@@ -133,23 +133,25 @@
   </div>
 </section>
 
-<Modal bind:open={editorOpen} title={editing ? m.user_edit() : m.user_create()} closeOnBackdrop={!store.saving} closeOnEscape={!store.saving} data-testid="user-editor">
-  <form class="space-y-4" onsubmit={submit}>
-    <FormField label={m.user_username()} required>
-      <Input bind:value={username} name="username" readonly={!!editing} required minlength={3} maxlength={64} pattern="[\w\-]+" autocomplete="off" data-testid="user-username" />
-    </FormField>
-    <FormField label={m.user_display_name()}><Input bind:value={displayName} maxlength={100} data-testid="user-display-name" /></FormField>
-    <FormField label={m.user_email()}><Input type="email" bind:value={email} data-testid="user-email" /></FormField>
-    {#if !editing}
-      <FormField label={m.user_password()} hint={m.initial_password_rules({ min: store.authConfig?.password.minLength ?? 8 })} required><PasswordInput bind:value={password} autocomplete="new-password" minLength={store.authConfig?.password.minLength ?? 8} data-testid="user-password" /></FormField>
-    {/if}
-    <FormField label={m.user_role()}><Select bind:value={role} options={roleOptions} disabled={editing?.id === store.user?.id} data-testid="user-role" /></FormField>
-    <Checkbox bind:checked={enabled} label={m.account_enabled()} disabled={editing?.id === store.user?.id} />
-    {#if store.error}<p class="text-sm text-error" role="alert">{store.error}</p>{/if}
-    <div class="flex justify-end gap-2 border-t border-base-content/8 pt-4">
-      <Button variant="ghost" disabled={store.saving} onclick={() => { editorOpen = false }}>{m.cancel()}</Button>
-      <Button type="submit" variant="primary" loading={store.saving} disabled={!editing && password.length < 8} data-testid="user-save">{m.save()}</Button>
-    </div>
+<Modal bind:open={editorOpen} title={editing ? m.user_edit() : m.user_create()} closeOnBackdrop={!store.saving} closeOnEscape={!store.saving} size="3xl" data-testid="user-editor">
+  <form onsubmit={submit}>
+    <FormLayout columns={2} labelPosition="left" labelWidth="6rem">
+      <FormField label={m.user_username()} required>
+        <Input bind:value={username} name="username" readonly={!!editing} required minlength={3} maxlength={64} pattern="[\w\-]+" autocomplete="off" data-testid="user-username" />
+      </FormField>
+      <FormField label={m.user_display_name()}><Input bind:value={displayName} maxlength={100} data-testid="user-display-name" /></FormField>
+      <FormField label={m.user_email()}><Input type="email" bind:value={email} data-testid="user-email" /></FormField>
+      {#if !editing}
+        <FormField label={m.user_password()} hint={m.initial_password_rules({ min: store.authConfig?.password.minLength ?? 8 })} required><PasswordInput required bind:value={password} autocomplete="new-password" minLength={store.authConfig?.password.minLength ?? 8} data-testid="user-password" /></FormField>
+      {/if}
+      <FormField label={m.user_role()}><Select bind:value={role} options={roleOptions} disabled={editing?.id === store.user?.id} data-testid="user-role" /></FormField>
+      <Checkbox bind:checked={enabled} label={m.account_enabled()} disabled={editing?.id === store.user?.id} />
+      {#if store.error}<p class="text-sm text-error" role="alert">{store.error}</p>{/if}
+      <div class="flex justify-end gap-2 border-t border-base-content/8 pt-4">
+        <Button variant="ghost" disabled={store.saving} onclick={() => { editorOpen = false }}>{m.cancel()}</Button>
+        <Button type="submit" variant="primary" loading={store.saving} disabled={!editing && password.length < 8} data-testid="user-save">{m.save()}</Button>
+      </div>
+    </FormLayout>
   </form>
 </Modal>
 

package/templates/apps/fullstack/packages/{{projectName}}-shared/src/lib/stores/management-store.svelte.ts.hbs

@@ -4,7 +4,7 @@ import type { ChangePasswordFormData, UserProfileSubmitData } from '@h-ai/ui'
 import type { AdminAuditLog, AdminCreateUser, AdminRole, AdminUpdateUser, AdminUser, AvatarUpload, ProfileUpdate } from '{{fullstack.contractPackageName}}'
 import type { AppInfo, ManagementApiOptions } from '../api/api-client.js'
 import { HaiApiClientError } from '@h-ai/api-client'
-import { core } from '@h-ai/core'
+import { setGlobalLocale } from '@h-ai/ui/i18n'
 import { SvelteDate } from 'svelte/reactivity'
 import { initializeManagementApi, managementApi, resolveAvatarUrl } from '../api/api-client.js'
 import * as m from '../paraglide/messages.js'
@@ -305,7 +305,7 @@ export class ManagementStore {
       return
     this.locale = locale
     setLocale(locale, { reload: false })
-    core.i18n.setGlobalLocale(locale)
+    setGlobalLocale(locale)
     if (typeof document !== 'undefined')
       document.documentElement.lang = locale
     this.onLocaleChange?.(locale)

package/templates/apps/website/src/routes/contact/+page.svelte.hbs

@@ -6,7 +6,7 @@
 {{#if hasI18n}}
   import * as m from '$lib/paraglide/messages'
 {{/if}}
-  import { Button, Card, FormField, Input, PageHeader } from '@h-ai/ui'
+  import { Button, Card, FormField, FormLayout, Input, PageHeader, Textarea } from '@h-ai/ui'
 
   let name = $state('')
   let email = $state('')
@@ -33,30 +33,32 @@
 {{/if}}
 
   <Card shadow='sm' class='bg-base-100'>
-    <form class='space-y-4' onsubmit={handleSubmit}>
+    <form onsubmit={handleSubmit}>
+      <FormLayout columns={2} labelPosition='top'>
 {{#if hasI18n}}
-      <FormField label={m.page_contact_name()} required>
-        <Input id='name' type='text' bind:value={name} required />
-      </FormField>
-      <FormField label={m.page_contact_email()} required>
-        <Input id='email' type='email' bind:value={email} required />
-      </FormField>
-      <FormField label={m.page_contact_message()} required>
-        <textarea id='message' class='textarea textarea-bordered w-full' rows='4' bind:value={message}></textarea>
-      </FormField>
-      <Button type='submit' variant='primary' class='w-full'>{m.page_contact_submit()}</Button>
+        <FormField for='name' label={m.page_contact_name()} required>
+          <Input id='name' type='text' bind:value={name} required />
+        </FormField>
+        <FormField for='email' label={m.page_contact_email()} required>
+          <Input id='email' type='email' bind:value={email} required />
+        </FormField>
+        <FormField for='message' label={m.page_contact_message()} required>
+          <Textarea id='message' rows={4} bind:value={message} required />
+        </FormField>
+        <Button type='submit' variant='primary' class='w-full'>{m.page_contact_submit()}</Button>
 {{else}}
-      <FormField label='姓名' required>
-        <Input id='name' type='text' bind:value={name} required />
-      </FormField>
-      <FormField label='邮箱' required>
-        <Input id='email' type='email' bind:value={email} required />
-      </FormField>
-      <FormField label='留言' required>
-        <textarea id='message' class='textarea textarea-bordered w-full' rows='4' bind:value={message}></textarea>
-      </FormField>
-      <Button type='submit' variant='primary' class='w-full'>发送</Button>
+        <FormField for='name' label='姓名' required>
+          <Input id='name' type='text' bind:value={name} required />
+        </FormField>
+        <FormField for='email' label='邮箱' required>
+          <Input id='email' type='email' bind:value={email} required />
+        </FormField>
+        <FormField for='message' label='留言' required>
+          <Textarea id='message' rows={4} bind:value={message} required />
+        </FormField>
+        <Button type='submit' variant='primary' class='w-full'>发送</Button>
 {{/if}}
+      </FormLayout>
     </form>
   </Card>
 </section>

package/templates/base/package.json.hbs

@@ -1,7 +1,7 @@
 {
   "engines": { "node": "^22.22.2 || ^24.15.0 || >=26.0.0" },
   "name": "{{projectName}}",
-  "version": "0.1.0-alpha.62",
+  "version": "0.1.0-alpha.64",
   "private": true,
   "packageManager": "pnpm@12.11.2",
   "description": "{{#if_eq appType 'admin'}}Enterprise management system built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'website'}}Enterprise website built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'h5'}}Mobile H5 app built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'api'}}REST API service built with hai Agent Framework{{/if_eq}}{{#if_eq appType 'mobile-app'}}Mobile app built with hai Agent Framework{{/if_eq}}",

package/templates/skills/hai-kit/SKILL.md

@@ -181,3 +181,7 @@ export const appKitConfig = resolveKitConfig(parse(rawKitConfig) ?? {})
 - 传输加密只通过 `crypto.transport` 间接装配，不在 kit 中新增本地加密工厂或鸭子类型。
 - 服务端业务模块直接调用模块 API，不通过 HTTP 自环。
 - API endpoint 必须用 Zod 校验用户输入，并设置认证/权限边界。
+
+## 声明式 CRUD 表单字段
+
+`kit.crud.define` 的字段支持 `colSpan: 'auto' | 1 | 2`，以及 `validation.message: string | (() => string)`。布局通过 UI 的 `CrudPage.form` 配置；客户端校验用于交互提示，服务端仍使用 Zod 验证和现有权限守卫。UI 公共契约见相邻 [hai-ui skill](../hai-ui/SKILL.md)。

package/templates/skills/hai-ui/SKILL.md

@@ -45,3 +45,17 @@ description: "使用 @h-ai/ui 构建 Svelte 5 表单、表格、弹窗、新手
 - 重要约定
 - 导出路径
 - 相关 Skills
+
+## 表单布局与错误提示
+
+输入控件与 CRUD 新增/编辑默认在首次失焦后显示前端错误，修正输入时即时更新；未操作字段在提交时校验。Select 在焦点离开触发器及选项后校验。应用无需逐项绑定 blur；业务异步校验仍由应用提供。PasswordInput 的 minLength 提供时执行长度校验；登录现有密码时省略该属性。
+
+UserProfile 的 `fieldConstraints` 按字段声明 `required/minlength/maxlength/pattern/validationMessage`；单行控件支持 pattern，业务文案可用翻译函数。不要只在保存回调内放前端校验，服务端仍须执行 schema 校验。
+
+状态层通过轻量入口 `@h-ai/ui/i18n` 导入 `setGlobalLocale` / `createLocaleStore`，不加载组件或引导 CSS。
+
+数据新增/修改统一使用 `Form`（托管提交）或原生 `<form>` + `FormLayout`，不要在应用复制字段 grid。两者支持 `columns={1 | 2}`、`labelPosition='top' | 'left'`、`labelWidth`；默认单列/标签在上，窄容器自动收拢。`FormField.colSpan='auto'` 自动让多行文本、上传和多选占两列，`1` / `2` 可覆盖；自定义宽控件标注 `data-form-wide`。已有控件 ID 或原生控件给 FormField 配 `for`，避免重复或失效的标签。
+
+IAM 表单、AuthPanel、UserProfile、FeedbackModal 直接接收同组参数；CRUD 使用 `form={{ columns: 2, labelPosition: 'left', labelWidth: '6rem' }}`，字段支持 `colSpan` 和延迟翻译的 `validation.message: () => m.required()`。通用字段的 `label/error/hint`、Input/Textarea/Select 的 `validationMessage` 支持翻译函数。内置必填、类型、长度和范围错误由 UI 提供；应用只提供业务文案。通过 UI 的 `setGlobalLocale` / `createLocaleStore` 同步语言，已显示的错误随之更新；自定义提示只用于失败，不能把固定提示直接设成持续的 customValidity。字段错误只在 FormField 或控件其中一处展示。
+
+验证一列/双列与两种标签位置、自动/显式跨列、窄抽屉/手机、无效提交与修正、切换语言后的错误、按钮和回车提交，以及关闭重开后的状态。

package/templates/skills/hai-ui/reference.md

@@ -255,8 +255,8 @@ const p = usePlatform()
 
 | 组件         | Props 要点                                                         | 说明          |
 | ------------ | ------------------------------------------------------------------ | ------------- |
-| `Form`       | `loading`, `disabled`, `onsubmit`                                  | 表单容器      |
-| `FormField`  | `label`, `name`, `error`, `hint`, `required`                       | 表单字段      |
+| `Form`       | `columns`, `labelPosition`, `labelWidth`, `loading`, `disabled`, `onsubmit`                                  | 表单容器      |
+| `FormField`  | `label`, `for`, `colSpan`, `labelPosition`, `error`, `hint`, `required`                       | 表单字段      |
 | `Modal`      | `open`, `title`, `size`, `closeOnBackdrop`                         | 模态框，内置对话框语义、焦点约束和关闭后焦点恢复 |
 | `Drawer`     | `open`, `position`, `size`, `width`, `resizable`, `widthStorageKey` | 可选拖动并记忆宽度的抽屉 |
 | `DataTable`  | `data`, `columns`, `keyField`, `sortKey`, `sortDir`, `onsort`, snippet slots | 数据表格（列定义 `sortable` 可排序） |
@@ -643,6 +643,7 @@ AuthPanel 在 SSR 阶段禁用原生表单控件，客户端挂载并绑定事
 | --------------------------- | -------------------------------------- |
 | `@h-ai/ui`                 | 主入口：所有组件、工具函数、类型       |
 | `@h-ai/ui/theme`           | 轻量主题元数据与工具，不经过组件根入口 |
+| `@h-ai/ui/i18n`            | 轻量语言工具，供状态层使用，不加载组件或引导 CSS |
 | `@h-ai/ui/auto-import`     | Svelte 预处理器：组件自动导入          |
 | `@h-ai/ui/components/*`    | 公开组件目录的 JS 入口，按实际 exports/产物选择 |
 | `@h-ai/ui/components/primitives/index` | 公开原子组件目录入口，如 Button/Input |
@@ -657,3 +658,25 @@ AuthPanel 在 SSR 阶段禁用原生表单控件，客户端挂载并绑定事
 - `hai-iam`：IAM 模块 API（与 LoginForm/RegisterForm 配合）
 - `hai-capacitor`：原生 App 开发（与 SafeArea/AppBar 配合）
 - `hai-api-client`：客户端数据获取
+
+## 表单布局与错误提示
+
+数据新增/修改统一使用 `Form`（托管提交）或原生 `<form>` + `FormLayout`，不要在应用复制字段 grid。两者支持 `columns={1 | 2}`、`labelPosition='top' | 'left'`、`labelWidth`；默认单列/标签在上，窄容器自动收拢。`FormField.colSpan='auto'` 自动让多行文本、上传和多选占两列，`1` / `2` 可覆盖；自定义宽控件标注 `data-form-wide`。已有控件 ID 或原生控件给 FormField 配 `for`，避免重复或失效的标签。
+
+IAM 表单、AuthPanel、UserProfile、FeedbackModal 直接接收同组参数；CRUD 使用 `form={{ columns: 2, labelPosition: 'left', labelWidth: '6rem' }}`，字段支持 `colSpan` 和延迟翻译的 `validation.message: () => m.required()`。通用字段的 `label/error/hint`、Input/Textarea/Select 的 `validationMessage` 支持翻译函数。内置必填、类型、长度和范围错误由 UI 提供；应用只提供业务文案。通过 UI 的 `setGlobalLocale` / `createLocaleStore` 同步语言，已显示的错误随之更新；自定义提示只用于失败，不能把固定提示直接设成持续的 customValidity。字段错误只在 FormField 或控件其中一处展示。
+
+验证一列/双列与两种标签位置、自动/显式跨列、窄抽屉/手机、无效提交与修正、切换语言后的错误、按钮和回车提交，以及关闭重开后的状态。
+
+
+```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>
+```