@h-ai/ui 0.1.0-alpha.62 → 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                                         |
@@ -531,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']}
@@ -698,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()
@@ -729,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

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>
+```
+
 #### フィードバック
 
 | コンポーネント   | 説明           | 主なプロパティ                           |
@@ -531,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']}
@@ -698,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()
@@ -729,7 +755,7 @@ import {
   isLocaleSupported, // 检查 locale 是否支持
   resolveLocale, // 解析 locale（支持回退）
   setGlobalLocale, // 设置全局 locale（同步 @h-ai/core）
-} from '@h-ai/ui'
+} from '@h-ai/ui/i18n'
 ```
 
 ## 設定による認証画面

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>
+```
+
 #### 反馈
 
 | 组件             | 描述     | 主要属性                          |
@@ -530,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']}
@@ -728,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()
@@ -759,7 +785,7 @@ import {
   isLocaleSupported, // 检查 locale 是否支持
   resolveLocale, // 解析 locale（支持回退）
   setGlobalLocale, // 设置全局 locale（同步 @h-ai/core）
-} from '@h-ai/ui'
+} from '@h-ai/ui/i18n'
 ```
 
 

package/auto-import.d.ts

@@ -58,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',

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;
     /** 自定义类名 */

package/dist/components/compounds/DatePicker.svelte

@@ -23,8 +23,10 @@
 -->
 <script lang='ts'>
   import type { DateValue } from '@internationalized/date'
-  import type { DataAttributes, Size } from '../../types.js'
+  import type { DataAttributes, FormText, Size } from '../../types.js'
   import { DatePicker as BitsDatePicker } from 'bits-ui'
+  import { getFormFieldContext } from '../../internal/form-context.js'
+  import { resolveFormText } from '../../internal/form-validation.svelte.js'
   import { cn, getDataAttributes } from '../../utils.js'
   import { getFormControlSizeClasses } from '../control-size.js'
 
@@ -44,7 +46,7 @@
     /** 尺寸 */
     size?: Size
     /** 错误消息 */
-    error?: string
+    error?: FormText
     /** 自定义类名 */
     class?: string
     /** 日期变更回调 */
@@ -66,6 +68,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))
 </script>
 
@@ -80,10 +87,12 @@
     onValueChange={v => onchange?.(v)}
   >
     <BitsDatePicker.Input
+      aria-labelledby={field?.labelId}
+      aria-describedby={[field?.messageId, localError && !field?.error ? messageId : ''].filter(Boolean).join(' ') || undefined}
       class={cn(
         'flex w-full items-center gap-0.5 rounded-lg border bg-base-100 pr-2 transition-[border-color,box-shadow] duration-150',
         sizeClasses.control,
-        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',
         disabled && 'cursor-not-allowed opacity-50',
@@ -149,7 +158,7 @@
     </BitsDatePicker.Content>
   </BitsDatePicker.Root>
 
-  {#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/DatePicker.svelte.d.ts

@@ -1,5 +1,5 @@
 import type { DateValue } from '@internationalized/date';
-import type { DataAttributes, Size } from '../../types.js';
+import type { DataAttributes, FormText, Size } from '../../types.js';
 interface Props {
     /** 选中日期（双向绑定） */
     value?: DateValue;
@@ -16,7 +16,7 @@ interface Props {
     /** 尺寸 */
     size?: Size;
     /** 错误消息 */
-    error?: string;
+    error?: FormText;
     /** 自定义类名 */
     class?: string;
     /** 日期变更回调 */

package/dist/components/compounds/Form.svelte

@@ -10,12 +10,16 @@
 <script lang='ts'>
   import type { DataAttributes, FormProps } from '../../types.js'
   import { cn, getDataAttributes } from '../../utils.js'
+  import FormLayout from './FormLayout.svelte'
 
   const {
     id = '',
     class: className = '',
     loading = false,
     disabled = false,
+    columns = 1,
+    labelPosition = 'top',
+    labelWidth = '8rem',
     onsubmit,
     onreset,
     onerror,
@@ -65,9 +69,7 @@
     }
   }
 
-  function handleReset(e: Event) {
-    e.preventDefault()
-    formElement?.reset()
+  function handleReset() {
     onreset?.()
   }
 
@@ -94,7 +96,9 @@
       onsubmit={handleSubmit}
       onreset={handleReset}
 >
-  {#if children}
-    {@render children()}
-  {/if}
+  <FormLayout {columns} {labelPosition} {labelWidth}>
+    {#if children}
+      {@render children()}
+    {/if}
+  </FormLayout>
 </form>

package/dist/components/compounds/FormField.svelte

@@ -9,6 +9,9 @@
 -->
 <script lang='ts'>
   import type { DataAttributes, FormFieldProps } from '../../types.js'
+  import { setContext } from 'svelte'
+  import { FORM_FIELD_CONTEXT, getFormLayoutContext } from '../../internal/form-context.js'
+  import { resolveFormText } from '../../internal/form-validation.svelte.js'
   import { cn, getDataAttributes } from '../../utils.js'
 
   const {
@@ -16,43 +19,105 @@
     error = '',
     hint = '',
     required = false,
+    for: providedControlId,
+    labelPosition,
+    labelWidth,
+    colSpan = 'auto',
     class: className = '',
     children,
     ...restProps
   }: FormFieldProps & DataAttributes = $props()
 
   const dataAttributes = $derived(getDataAttributes(restProps))
+  const layout = getFormLayoutContext()
+  const uniqueId = $props.id()
+  const controlId = $derived(providedControlId ?? `${uniqueId}-control`)
+  const messageId = `${uniqueId}-message`
+  const labelId = `${uniqueId}-label`
+  const resolvedLabel = $derived(resolveFormText(label))
+  const resolvedError = $derived(resolveFormText(error))
+  const resolvedHint = $derived(resolveFormText(hint))
+  const position = $derived(labelPosition ?? layout?.labelPosition ?? 'top')
+  const width = $derived(labelWidth ?? layout?.labelWidth ?? '8rem')
+  setContext(FORM_FIELD_CONTEXT, {
+    get controlId() { return controlId },
+    get labelId() { return labelId },
+    get messageId() { return resolvedError || resolvedHint ? messageId : undefined },
+    get error() { return resolvedError },
+  })
   const fieldClass = $derived(
     cn(
-      'fieldset w-full',
+      'hai-form-field w-full min-w-0',
       className,
     ),
   )
 </script>
 
-<div {...dataAttributes} class={fieldClass}>
-  {#if label}
-    <legend class='fieldset-legend'>
-      {label}
+<div {...dataAttributes} class={fieldClass} data-col-span={colSpan} data-label-position={position} style:--hai-form-label-width={width}>
+  {#if resolvedLabel}
+    <label id={labelId} for={controlId} class='field-label text-sm font-medium text-base-content/70'>
+      {resolvedLabel}
       {#if required}
         <span class='text-error'>*</span>
       {/if}
-    </legend>
+    </label>
   {/if}
 
-  <div class='field-content'>
+  <div class='field-content min-w-0'>
     {#if children}
       {@render children()}
     {/if}
   </div>
 
-  {#if error || hint}
-    <div>
-      {#if error}
-        <span class='fieldset-label text-error'>{error}</span>
-      {:else if hint}
-        <span class='fieldset-label text-base-content/60'>{hint}</span>
+  {#if resolvedError || resolvedHint}
+    <div id={messageId} class='field-message text-xs leading-relaxed break-words' aria-live='polite'>
+      {#if resolvedError}
+        <span class='text-error'>{resolvedError}</span>
+      {:else if resolvedHint}
+        <span class='text-base-content/60'>{resolvedHint}</span>
       {/if}
     </div>
   {/if}
 </div>
+
+<style>
+  .hai-form-field {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr);
+    gap: 0.375rem 1rem;
+  }
+
+  .field-label {
+    overflow-wrap: anywhere;
+  }
+
+  .field-content > :global(.fieldset) {
+    padding-block: 0;
+  }
+
+  .hai-form-field[data-label-position='left']:has(.field-label) {
+    grid-template-columns: minmax(0, var(--hai-form-label-width)) minmax(0, 1fr);
+  }
+
+  .hai-form-field[data-label-position='left'] .field-label {
+    padding-top: 0.5rem;
+  }
+
+  .hai-form-field[data-label-position='left']:has(.field-label) .field-message {
+    grid-column: 2;
+  }
+
+  @container hai-form (max-width: 27.99rem) {
+    .hai-form-field[data-label-position='left']:has(.field-label) {
+      grid-template-columns: minmax(0, 1fr);
+    }
+
+    .hai-form-field[data-label-position='left'] .field-label {
+      padding-top: 0;
+    }
+
+    .hai-form-field[data-label-position='left']:has(.field-label) .field-message {
+      grid-column: 1;
+    }
+  }
+</style>