refactor(@vben-core/form-ui): migrate to Zod 4 and TanStack Form (#8176)

* build(@vben-core/form-ui): update form validation dependencies

* refactor(@vben-core/form-ui): replace vee-validate with TanStack Form

* test(@vben-core/form-ui): cover TanStack Form migration

* docs(@vben/docs): document Zod 4 form migration

* refactor(project): update form adapters

* refactor(project): migrate application form consumers

* refactor(@vben/playground): migrate form examples

* docs(@vben/docs): fix validate return type and required rule empty check in form docs

* fix(@vben-core/form-ui): resolve oxlint and eslint errors

- rewrite nested ternary expressions as if/else in form-field-array.vue and form-runtime.ts
- sort @tanstack/vue-form before @vben-core/composables in package.json

* chore: fix merge artifacts and formatting

- move dependencies before devDependencies in root package.json
- update preferences snapshot for widget positioning fields
- format form-array demo README

* refactor(@vben-core/form-ui): optimize form runtime and value flow

- add fine-grained field selectors and atomic dependency resolution
- expose raw and formatted value snapshots with focused regression coverage

* fix(@vben/layouts): dispose sortable instance on unmount

* docs(@vben/docs): document form runtime API changes

- list added, changed, removed, and deprecated form APIs
- document atomic dependencies and raw versus formatted values

docs/src/_env/adapter/form.ts

@@ -1,6 +1,7 @@
 import type {
+  VbenFormProps as FormProps,
   VbenFormSchema as FormSchema,
-  VbenFormProps,
+  FormValues,
 } from '@vben/common-ui';
 
 import type { ComponentType } from './component';
@@ -24,7 +25,7 @@ setupVbenForm<ComponentType>({
       Upload: 'fileList',
     },
   },
-  defineRules: {
+  rules: {
     required: (value, _params, ctx) => {
       if (value === undefined || value === null || value.length === 0) {
         return $t('ui.formRules.required', [ctx.label]);
@@ -40,9 +41,18 @@ setupVbenForm<ComponentType>({
   },
 });
 
-const useVbenForm = useForm<ComponentType>;
+function useVbenForm<TValues extends FormValues = FormValues>(
+  options: FormProps<ComponentType, Record<never, never>, TValues>,
+) {
+  return useForm<TValues, ComponentType, Record<never, never>>(options);
+}
 
 export { useVbenForm, z };
 
-export type VbenFormSchema = FormSchema<ComponentType>;
-export type { VbenFormProps };
+export type VbenFormSchema<TValues extends FormValues = FormValues> =
+  FormSchema<ComponentType, Record<never, never>, TValues>;
+export type VbenFormProps<TValues extends FormValues = FormValues> = FormProps<
+  ComponentType,
+  Record<never, never>,
+  TValues
+>;

docs/src/components/common-ui/vben-form.md

@@ -16,7 +16,9 @@ outline: deep
 
 ## 适配器
 
-表单底层使用 [vee-validate](https://vee-validate.logaretm.com/v4/) 进行表单验证，所以你可以使用 `vee-validate` 的所有功能。对于不同的 UI 框架，我们提供了适配器，以便更好的适配不同的 UI 框架。
+表单内部使用 [TanStack Form](https://tanstack.com/form/latest/docs/framework/vue/overview) 管理状态与校验生命周期，并使用 [Zod 4](https://zod.dev/v4) 描述 schema。业务侧仍通过 `useVbenForm`、`FormApi` 和组件适配器使用表单，不应直接依赖底层 TanStack 实例。
+
+从 Zod 3 或旧表单引擎升级时，请先阅读 [Zod 4 与 TanStack Form 迁移指南](/guide/in-depth/zod-v4-form-migration)。
 
 ### 适配器说明
 
@@ -26,8 +28,9 @@ outline: deep
 
 ```ts
 import type {
+  FormValues,
+  VbenFormProps as FormProps,
   VbenFormSchema as FormSchema,
-  VbenFormProps,
 } from '@vben/common-ui';
 
 import type { ComponentType } from './component';
@@ -42,6 +45,8 @@ setupVbenForm<ComponentType>({
   config: {
     // ant design vue组件库默认都是 v-model:value
     baseModelPropName: 'value',
+    // 仅当组件不发送 update:*、只发送 change 时启用
+    changeEventFallback: false,
     // 一些组件库空值为 null，重置表单时需要和实际组件行为保持一致
     emptyStateValue: null,
     // 一些组件是 v-model:checked 或者 v-model:fileList
@@ -52,7 +57,7 @@ setupVbenForm<ComponentType>({
       Upload: 'fileList',
     },
   },
-  defineRules: {
+  rules: {
     // 输入项目必填国际化适配
     required: (value, _params, ctx) => {
       if (value === undefined || value === null || value.length === 0) {
@@ -70,11 +75,20 @@ setupVbenForm<ComponentType>({
   },
 });
 
-const useVbenForm = useForm<ComponentType>;
+function useVbenForm<TValues extends FormValues = FormValues>(
+  options: FormProps<ComponentType, Record<never, never>, TValues>,
+) {
+  return useForm<TValues, ComponentType, Record<never, never>>(options);
+}
 
 export { useVbenForm, z };
-export type VbenFormSchema = FormSchema<ComponentType>;
-export type { VbenFormProps };
+export type VbenFormSchema<TValues extends FormValues = FormValues> =
+  FormSchema<ComponentType, Record<never, never>, TValues>;
+export type VbenFormProps<TValues extends FormValues = FormValues> = FormProps<
+  ComponentType,
+  Record<never, never>,
+  TValues
+>;
 ```
 
 :::
@@ -252,6 +266,8 @@ export { initComponentAdapter };
 
 _注意_ 需要指定 `dependencies` 的 `triggerFields` 属性，设置由谁的改动来触发，以便表单组件能够正确的联动。
 
+新代码推荐使用 `dependencies.resolve(context)` 一次返回完整动态状态。它只在 `triggerFields` 变化时执行，并原子更新 `if`、`show`、`disabled`、`required`、`rules`、`componentProps`、`help` 和 `renderComponentContent`，避免多个异步回调产生中间状态。原有多回调结构继续兼容。
+
 <DemoPreview dir="demos/vben-form/dynamic" />
 
 ## 自定义组件
@@ -287,29 +303,105 @@ const [Form, formApi] = useVbenForm({
 </template>
 ```
 
+### 类型传递与插槽
+
+通过 `useVbenForm<TValues>` 定义一次表单值类型后，`getValues`、`setValues`、`setFieldValue`、`handleSubmit`、`handleValuesChange`、`formApi.form.values` 和 selector 都会沿用该类型，可直接作为 API 请求参数：
+
+```vue
+<script setup lang="ts">
+import { useVbenForm } from '#/adapter/form';
+
+interface AccountFormValues {
+  email: string;
+  nickname: string;
+}
+
+const [Form, formApi] = useVbenForm<AccountFormValues>({
+  handleSubmit(values, rawValues) {
+    // values: AccountFormValues
+    // rawValues: Readonly<AccountFormValues>
+    return addAccount(values);
+  },
+  schema: [
+    { component: 'Input', fieldName: 'email', label: 'Email' },
+    { component: 'Input', fieldName: 'nickname', label: 'Nickname' },
+  ],
+});
+
+async function fillForm() {
+  await formApi.setValues({ email: 'user@example.com' });
+  const values = await formApi.getValues(); // AccountFormValues
+  return values;
+}
+</script>
+
+<template>
+  <Form>
+    <template #email="{ componentField, field, formApi, values }">
+      <!-- field.state.value、componentField.modelValue 均为 string -->
+      <input v-bind="componentField" :data-email="values.email" />
+      <button type="button" @click="formApi.clearValidation('email')">
+        Clear
+      </button>
+    </template>
+    <template #default="{ formApi, shapes, values }">
+      <!-- values: AccountFormValues -->
+      <button type="button" @click="formApi.submit()">
+        Submit {{ shapes.length }} fields for {{ values.email }}
+      </button>
+    </template>
+  </Form>
+</template>
+```
+
+字段命名插槽提供 `field`、`componentField`、`modelValue`、`name`、`disabled`、`isInValid`、`values` 和 `formApi`。默认插槽提供 `shapes`、`values` 和 `formApi`；`reset-before`、`submit-before`、`expand-before`、`expand-after` 提供 `values` 和 `formApi`。未声明 `TValues` 时仍兼容任意字段名，但 slot props 会回退为宽泛类型。
+
 ### FormApi
 
 useVbenForm 返回的第二个参数，是一个对象，包含了一些表单的方法。
 
 | 方法名 | 描述 | 类型 | 版本号 |
 | --- | --- | --- | --- |
-| submitForm | 提交表单 | `(e:Event)=>Promise<Record<string,any>>` | - |
-| validateAndSubmitForm | 提交并校验表单 | `(e:Event)=>Promise<Record<string,any>>` | - |
-| resetForm | 重置表单 | `()=>Promise<void>` | - |
-| setValues | 设置表单值, 默认会过滤不在schema中定义的field, 可通过filterFields形参关闭过滤 | `(fields: Record<string, any>, filterFields?: boolean, shouldValidate?: boolean) => Promise<void>` | - |
-| getValues | 获取表单值 | `(fields:Record<string, any>,shouldValidate: boolean = false)=>Promise<void>` | - |
-| validate | 表单校验 | `()=>Promise<void>` | - |
-| validateField | 校验指定字段 | `(fieldName: string)=>Promise<ValidationResult<unknown>>` | - |
+| submit | 提交表单 | `(e?: Event) => Promise<TValues>` | - |
+| validateAndSubmit | 校验通过后提交表单 | `() => Promise<TValues \| undefined>` | - |
+| reset | 重置表单 | `(state?: FormResetState<TValues>, options?: FormResetOptions) => Promise<void>` | - |
+| clearValidation | 清空指定字段或全部校验，并取消进行中的异步校验 | `(fieldNames?: FormFieldName<TValues> \| FormFieldName<TValues>[]) => Promise<void>` | - |
+| setValues | 设置表单值，默认会过滤不在 schema 中定义的字段 | `(fields: Partial<TValues>, filterFields?: boolean, shouldValidate?: boolean) => Promise<void>` | - |
+| getValues | 获取经过字段映射和 valueFormat 的值 | `() => Promise<TValues>` | - |
+| getRawValues | 获取未格式化的独立值快照 | `() => Promise<TValues>` | - |
+| getValueSnapshot | 一次获取原始值和格式化值 | `() => Promise<FormValueSnapshot<TValues>>` | - |
+| formatValues | 格式化指定的原始值快照 | `(rawValues: Readonly<TValues>) => TValues` | - |
+| validate | 表单校验 | `() => Promise<FormValidationResult>` | - |
+| validateField | 校验指定字段 | `(fieldName: string) => Promise<FormValidationResult>` | - |
 | isFieldValid | 检查某个字段是否已通过校验 | `(fieldName: string)=>Promise<boolean>` | - |
-| resetValidate | 重置表单校验 | `()=>Promise<void>` | - |
 | updateSchema | 更新formSchema | `(schema:FormSchema[])=>void` | - |
 | setFieldValue | 设置字段值 | `(field: string, value: any, shouldValidate?: boolean)=>Promise<void>` | - |
 | setState | 设置组件状态（props） | `(stateOrFn:\| ((prev: VbenFormProps) => Partial<VbenFormProps>)\| Partial<VbenFormProps>)=>Promise<void>` | - |
 | getState | 获取组件状态（props） | `()=>Promise<VbenFormProps>` | - |
-| form | 表单对象实例，可以操作表单，见 [useForm](https://vee-validate.logaretm.com/v4/api/use-form/) | - | - |
+| form | 稳定的 `FormContextApi`，提供 values、errors、set/reset/validate/submit 与数组字段操作，不暴露底层 TanStack 泛型 | `FormContextApi` | - |
 | getFieldComponentRef | 获取指定字段的组件实例 | `<T=unknown>(fieldName: string)=>T` | >5.5.3 |
 | getFocusedField | 获取当前已获得焦点的字段 | `()=>string\|undefined` | >5.5.3 |
 
+旧命名 `submitForm`、`validateAndSubmitForm`、`resetForm`、`resetValidate` 分别对应 `submit`、`validateAndSubmit`、`reset`、`clearValidation`。它们仍可调用，但已标记 `@deprecated`，开发环境每个旧名称只警告一次，生产环境静默。
+
+### FormContextApi 响应式读取
+
+`formApi.form` 提供细粒度 selector。字段组件应优先使用字段级方法，避免订阅整份 values 或 errors：
+
+| 方法 | 返回值 | 用途 |
+| --- | --- | --- |
+| `useFieldValue(fieldName)` | `Readonly<Ref<FormFieldValue>>` | 订阅一个字段值。 |
+| `useFieldValues(fieldNames)` | `Readonly<Ref<FormFieldValue[]>>` | 订阅一组声明字段值。 |
+| `useFieldError(fieldName)` | `Readonly<Ref<string \| undefined>>` | 订阅一个字段错误。 |
+| `useValues()` | `Readonly<Ref<TValues>>` | 订阅整份表单值。 |
+| `useSelector(selector)` | `Readonly<Ref<TResult>>` | 兼容入口，可从 `{ values, errors, meta }` 组合选择状态。 |
+
+```ts
+const email = formApi.form.useFieldValue('email');
+const emailError = formApi.form.useFieldError('email');
+const submitting = formApi.form.useSelector((state) => state.meta.submitting);
+```
+
 ## Props
 
 所有属性都可以传入 `useVbenForm` 的第一个参数中。
@@ -323,8 +415,8 @@ useVbenForm 返回的第二个参数，是一个对象，包含了一些表单
 | actionLayout | 表单操作按钮位置 | `'newLine' \| 'rowEnd' \| 'inline'` | `rowEnd` |
 | actionPosition | 表单操作按钮对齐方式 | `'left' \| 'center' \| 'right'` | `right` |
 | handleReset | 表单重置回调 | `(values: Record<string, any>,) => Promise<void> \| void` | - |
-| handleSubmit | 表单提交回调 | `(values: Record<string, any>,) => Promise<void> \| void` | - |
-| handleValuesChange | 表单值变化回调 | `(values: Record<string, any>, fieldsChanged: string[]) => void` | - |
+| handleSubmit | 表单提交回调 | `(values: TValues, rawValues: Readonly<TValues>) => Promise<void> \| void` | - |
+| handleValuesChange | 表单值变化回调 | `(rawValues: Readonly<TValues>, fieldsChanged: string[], getFormattedValues: () => TValues) => void` | - |
 | handleCollapsedChange | 表单收起展开状态变化回调 | `(collapsed: boolean) => void` | - |
 | actionButtonsReverse | 调换操作按钮位置 | `boolean` | `false` |
 | resetButtonOptions | 重置按钮组件参数 | `ActionButtonOptions` | - |
@@ -343,7 +435,9 @@ useVbenForm 返回的第二个参数，是一个对象，包含了一些表单
 
 ::: tip handleValuesChange
 
-`handleValuesChange` 回调函数的第一个参数`values`装载了表单改变后的当前值对象，第二个参数`fieldsChanged`是一个数组，包含了所有被改变的字段名。注意：第二个参数仅在v5.5.4(不含)以上版本可用，并且传递的是已在schema中定义的字段名。如果你使用了字段映射并且需要检查是哪些字段发生了变化的话，请注意该参数并不会包含映射后的字段名。
+`handleValuesChange` 的第一个参数是未经过 `valueFormat`、`fieldMappingTime` 或 array-to-string 转换的只读当前值，第二个参数是本次发生变化的 schema 字段名。第三个参数 `getFormattedValues` 是惰性函数：不调用就不会执行深拷贝和格式化，适合只在少数变化场景读取提交结构。字段映射生成的目标字段不会出现在 `fieldsChanged` 中。
+
+`getRawValues()` 和 `getValues()` 分别只生成一份目标快照；确实需要同时比较两种结构时再调用 `getValueSnapshot()`。`handleSubmit(values, rawValues)` 会在提交边界同时提供格式化结果和对应的原始快照。
 
 :::
 
@@ -410,6 +504,11 @@ export interface ActionButtonOptions {
 
 ```ts
 export interface FormCommonConfig {
+  /**
+   * 仅当组件不发送 update:*、只发送 change 时启用兼容回退
+   * @default false
+   */
+  changeEventFallback?: boolean;
   /**
    * 所有表单项的props
    */
@@ -431,7 +530,7 @@ export interface FormCommonConfig {
    * 所有表单项的控件样式
    * @default {}
    */
-  formFieldProps?: Partial<typeof Field>;
+  formFieldProps?: FormFieldOptions;
   /**
    * 所有表单项的栅格布局
    * @default ""
@@ -475,11 +574,14 @@ export interface FormCommonConfig {
 ```ts
 export interface FormSchema<
   T extends BaseFormComponentType = BaseFormComponentType,
+  TValues extends FormValues = FormValues,
 > extends FormCommonConfig {
   /** 组件 */
   component: Component | T;
   /** 组件参数 */
-  componentProps?: ComponentProps;
+  componentProps?:
+    | MaybeComponentProps
+    | ((ctx: FormSchemaContext<TValues>) => MaybeComponentProps);
   /** 默认值 */
   defaultValue?: any;
   /** 依赖 */
@@ -489,13 +591,15 @@ export interface FormSchema<
   /** 字段名，也作为自定义插槽的名称 */
   fieldName: string;
   /** 帮助信息 */
-  help?: CustomRenderType;
+  help?: string | ((ctx: FormSchemaContext<TValues>) => Component | string);
   /** 是否隐藏表单项 */
   hide?: boolean;
   /** 表单的标签（如果是一个string，会用于默认必选规则的消息提示） */
   label?: CustomRenderType;
   /** 自定义组件内部渲染  */
-  renderComponentContent?: RenderComponentContentType;
+  renderComponentContent?: (
+    ctx: FormSchemaContext<TValues>,
+  ) => Record<string, any>;
   /** 字段规则 */
   rules?: FormSchemaRuleType;
   /** 后缀 */
@@ -505,6 +609,8 @@ export interface FormSchema<
 }
 ```
 
+顶层 `componentProps`、`help` 和 `renderComponentContent` 函数只接收轻量 `FormSchemaContext`，适合数组行索引、字段路径等 schema 信息。需要读取表单值时，使用 `dependencies.resolve({ values, ... })`，避免每个字段订阅整份 values。
+
 :::
 
 ::: details FormValueFormat
@@ -529,29 +635,37 @@ type FormValueFormat = (
 
 ```ts
 dependencies: {
-  // 触发字段。只有这些字段值变动时，联动才会触发
-  triggerFields: ['name'],
-  // 动态判断当前字段是否需要显示，不显示则直接销毁
-  if(values,formApi){},
-  // 动态判断当前字段是否需要显示，不显示用css隐藏
-  show(values,formApi){},
-  // 动态判断当前字段是否需要禁用
-  disabled(values,formApi){},
-  // 字段变更时，都会触发该函数
-  trigger(values,formApi){},
-  // 动态rules
-  rules(values,formApi){},
-  // 动态必填
-  required(values,formApi){},
-  // 动态组件参数
-  componentProps(values,formApi){},
+  triggerFields: ['type', 'role'],
+  resolve({ values, actions, controller, schema }) {
+    const editable = values.type === 'editable';
+    return {
+      componentProps: { placeholder: schema.fieldName },
+      disabled: !editable,
+      required: values.role === 'owner',
+      rules: editable ? 'required' : null,
+      show: values.type !== 'hidden',
+    };
+  },
 }
 ```
 
+`resolve` 返回的字段会一次性提交；支持 `if`、`show`、`disabled`、`required`、`rules`、`componentProps`、`help` 和 `renderComponentContent`。未返回 `rules` 时继续使用静态规则，显式返回 `rules: null` 时关闭静态规则。`actions` 是稳定的 `FormContextApi`，`controller` 是高层 FormApi，`schema` 包含字段名和数组行上下文。
+
+旧的 `if/show/disabled/required/rules/componentProps/trigger` 回调语法仍完整兼容并保持原求值顺序，但已标记为 `@deprecated`，开发环境首次使用时会提示迁移。新旧语法在同一个 dependencies 对象中互斥；绕过类型同时传入时以 `resolve` 为准。
+
 ### 表单校验
 
 表单校验需要通过 schema 内的 `rules` 属性进行配置。
 
+字段默认在 blur、change 和 submit 时校验。使用 `formFieldProps.validateOn` 限制交互触发时机，submit 始终校验；异步校验可通过 `asyncDebounceMs` 防抖：
+
+```ts
+formFieldProps: {
+  asyncDebounceMs: 300,
+  validateOn: ['blur'],
+}
+```
+
 rules的值可以是字符串（预定义的校验规则名称），也可以是一个zod的schema。
 
 #### 预定义的校验规则

docs/src/demos/vben-form/dynamic/index.vue

@@ -124,26 +124,28 @@ const [Form] = useVbenForm({
         showSearch: true,
       },
       dependencies: {
-        componentProps(values) {
+        resolve({ values }) {
           if (values.field2 === '123') {
             return {
-              options: [
-                {
-                  label: '选项1',
-                  value: '1',
-                },
-                {
-                  label: '选项2',
-                  value: '2',
-                },
-                {
-                  label: '选项3',
-                  value: '3',
-                },
-              ],
+              componentProps: {
+                options: [
+                  {
+                    label: '选项1',
+                    value: '1',
+                  },
+                  {
+                    label: '选项2',
+                    value: '2',
+                  },
+                  {
+                    label: '选项3',
+                    value: '3',
+                  },
+                ],
+              },
             };
           }
-          return {};
+          return { componentProps: {} };
         },
         triggerFields: ['field2'],
       },

docs/src/demos/vben-form/rules/index.vue

@@ -69,7 +69,7 @@ const [Form] = useVbenForm({
       fieldName: 'field4',
       // 界面显示的label
       label: '邮箱',
-      rules: z.string().email('请输入正确的邮箱'),
+      rules: z.email('请输入正确的邮箱'),
     },
     {
       component: 'InputNumber',

docs/src/en/components/common-ui/vben-form.md

@@ -6,6 +6,10 @@ outline: deep
 
 `Vben Form` is the shared form abstraction used across different UI-library variants such as `Ant Design Vue`, `Element Plus`, `Naive UI`, and other adapters added inside this repository.
 
+It uses [TanStack Form](https://tanstack.com/form/latest/docs/framework/vue/overview) internally for state and validation lifecycles, with [Zod 4](https://zod.dev/v4) schemas. Application code should continue using `useVbenForm`, `FormApi`, and the adapter layer instead of depending on the raw TanStack instance.
+
+Read the [Zod 4 and TanStack Form migration guide](/en/guide/in-depth/zod-v4-form-migration) before upgrading an existing project.
+
 > If some details are not obvious from the docs, check the live demos as well.
 
 ## Adapter Setup
@@ -23,8 +27,9 @@ The current adapter pattern is:
 
 ```ts
 import type {
+  FormValues,
+  VbenFormProps as FormProps,
   VbenFormSchema as FormSchema,
-  VbenFormProps,
 } from '@vben/common-ui';
 
 import type { ComponentType } from './component';
@@ -46,7 +51,7 @@ setupVbenForm<ComponentType>({
       Upload: 'fileList',
     },
   },
-  defineRules: {
+  rules: {
     required: (value, _params, ctx) => {
       if (value === undefined || value === null || value.length === 0) {
         return $t('ui.formRules.required', [ctx.label]);
@@ -62,11 +67,20 @@ setupVbenForm<ComponentType>({
   },
 });
 
-const useVbenForm = useForm<ComponentType>;
+function useVbenForm<TValues extends FormValues = FormValues>(
+  options: FormProps<ComponentType, Record<never, never>, TValues>,
+) {
+  return useForm<TValues, ComponentType, Record<never, never>>(options);
+}
 
 export { useVbenForm, z };
-export type VbenFormSchema = FormSchema<ComponentType>;
-export type { VbenFormProps };
+export type VbenFormSchema<TValues extends FormValues = FormValues> =
+  FormSchema<ComponentType, Record<never, never>, TValues>;
+export type VbenFormProps<TValues extends FormValues = FormValues> = FormProps<
+  ComponentType,
+  Record<never, never>,
+  TValues
+>;
 ```
 
 ### Component Adapter Example
@@ -191,6 +205,55 @@ Create the form through `useVbenForm`:
 
 <DemoPreview dir="demos/vben-form/basic" />
 
+## Typed Values and Slots
+
+Declare the value shape once with `useVbenForm<TValues>`. The same type flows through value APIs, callbacks, selectors, and field/default/action slots:
+
+```vue
+<script setup lang="ts">
+import { useVbenForm } from '#/adapter/form';
+
+interface AccountFormValues {
+  email: string;
+  nickname: string;
+}
+
+const [Form, formApi] = useVbenForm<AccountFormValues>({
+  handleSubmit(values) {
+    return addAccount(values); // AccountFormValues
+  },
+  schema: [
+    { component: 'Input', fieldName: 'email', label: 'Email' },
+    { component: 'Input', fieldName: 'nickname', label: 'Nickname' },
+  ],
+});
+
+async function fillForm() {
+  await formApi.setValues({ email: 'user@example.com' });
+  return formApi.getValues(); // Promise<AccountFormValues>
+}
+</script>
+
+<template>
+  <Form>
+    <template #email="{ componentField, field, formApi, values }">
+      <!-- field.state.value and componentField.modelValue are strings -->
+      <input v-bind="componentField" :data-email="values.email" />
+      <button type="button" @click="formApi.clearValidation('email')">
+        Clear
+      </button>
+    </template>
+    <template #default="{ formApi, shapes, values }">
+      <button type="button" @click="formApi.submit()">
+        Submit {{ shapes.length }} fields for {{ values.email }}
+      </button>
+    </template>
+  </Form>
+</template>
+```
+
+Named field slots expose `field`, `componentField`, `modelValue`, `name`, `disabled`, `isInValid`, `values`, and `formApi`. The default slot exposes `shapes`, `values`, and `formApi`; action slots expose `values` and `formApi`. Forms without an explicit `TValues` remain compatible with arbitrary slot names and broad props.
+
 ## Value Formatting
 
 Use `schema.valueFormat` when the component value is convenient for the UI but the final payload returned by `getValues()` should use a different shape.
@@ -204,10 +267,25 @@ Use `schema.valueFormat` when the component value is convenient for the UI but t
 ## Key API Notes
 
 - `useVbenForm` returns `[Form, formApi]`
+- `useVbenForm<TValues>` propagates values through APIs, callbacks, schema callbacks, and slots
+- prefer `reset`, `submit`, `validateAndSubmit`, and `clearValidation`
+- `resetForm`, `submitForm`, `validateAndSubmitForm`, and `resetValidate` remain deprecated aliases that warn once in development
+- `clearValidation` invalidates in-flight async results before clearing errors
 - `formApi.getFieldComponentRef()` and `formApi.getFocusedField()` are available in current versions
-- `handleValuesChange(values, fieldsChanged)` includes the second parameter in newer versions
+- `handleValuesChange(values, fieldsChanged)` receives readonly raw form state before `valueFormat`, `fieldMappingTime`, or array-to-string conversion
+- its third `getFormattedValues` argument formats lazily, so raw-only change handlers avoid clone and transform work
+- `getRawValues()` returns only an independent raw snapshot, `getValues()` returns only the formatted payload, and `getValueSnapshot()` returns both
+- `handleSubmit(values, rawValues)` receives the formatted payload and its corresponding raw snapshot
 - `fieldMappingTime` and `scrollToFirstError` are part of the current form props
 - `schema.valueFormat` lets `getValues()` transform UI values into backend-friendly payloads
+- `formApi.form` is the stable `FormContextApi`; raw TanStack generics are intentionally not exposed
+- prefer `formApi.form.useFieldValue`, `useFieldValues`, and `useFieldError` for fine-grained subscriptions; use `useValues` only when the whole form is required
+- `useSelector` remains the compatibility selector for combined `{ values, errors, meta }` state
+- legacy `setupVbenForm({ defineRules })` still works, warns once in development, and is silent in production; use `rules` for new code
+- prefer `dependencies: { triggerFields, resolve(context) }` for one atomic dynamic-state patch; legacy dependency callbacks remain supported but are deprecated and warn once in development
+- top-level `componentProps`, `help`, and `renderComponentContent` functions receive `FormSchemaContext`; value-dependent rendering belongs in `dependencies.resolve`
+- use `formFieldProps.validateOn` with `blur` and/or `change`; submit always validates, and `asyncDebounceMs` debounces async validators
+- use `changeEventFallback: true` only for components that emit `change` without an `update:*` event
 
 ## Reference
 

docs/src/en/guide/in-depth/zod-v4-form-migration.md

@@ -0,0 +1,242 @@
+---
+outline: deep
+---
+
+# Zod 4 and TanStack Form Migration
+
+This migration upgrades form schemas from Zod 3 to Zod 4 and replaces vee-validate with TanStack Form internally. The Vben business API remains stable while implementation-specific form APIs are removed from the public boundary.
+
+## Dependency Changes
+
+| Area | Before | After |
+| --- | --- | --- |
+| Schema | `zod@^3.25.76` | `zod@^4.4.3` |
+| Defaults | `zod-defaults@0.1.3` | `zod-defaults@^0.2.3` |
+| Form engine | `vee-validate@^4.15.1` | `@tanstack/vue-form@^1.33.2` |
+| Zod adapter | `@vee-validate/zod@^4.15.1` | Removed; TanStack Form supports Standard Schema |
+
+Source files, package manifests, and the lockfile must no longer depend on `vee-validate` or `@vee-validate/zod`.
+
+## Compatibility Boundary
+
+The following Vben APIs remain supported:
+
+- `useVbenForm(options)` returning `[Form, formApi]`
+- existing `FormApi` methods for values, reset, validation, submission, schema updates, and component refs
+- existing `FormSchema` fields, dependencies, `valueFormat`, and array schema structure
+- application adapters and the re-exported `z` namespace
+- the existing `componentField` slot and binding shape
+
+`formApi.form` is now the library-independent `FormContextApi`. It exposes values, errors, meta, set/reset/validate/submit methods, and array operations without leaking vee or raw TanStack generics.
+
+New code uses `reset`, `submit`, `validateAndSubmit`, and `clearValidation`. The former `resetForm`, `submitForm`, `validateAndSubmitForm`, and `resetValidate` names remain deprecated forwarding aliases. They emit one warning per name in development and stay silent in production.
+
+## Form UI API Changes in This Refactor
+
+### Added APIs
+
+| API | Type/Location | Description |
+| --- | --- | --- |
+| `dependencies.resolve(context)` | `FormItemDependenciesResolve` | Evaluates one complete dynamic patch from declared `triggerFields` and commits it atomically. Context contains readonly `values`, `actions`, `controller`, and row-aware `schema`. |
+| `useValues()` | `FormContextApi` | Subscribes to all form values. Use only when full-form reactivity is required. |
+| `useFieldValue(fieldName)` | `FormContextApi` | Subscribes to one field value without reacting to unrelated fields. |
+| `useFieldValues(fieldNames)` | `FormContextApi` | Subscribes to a declared group of field values. |
+| `useFieldError(fieldName)` | `FormContextApi` | Subscribes to one field error without consuming the full error object. |
+| `getRawValues()` | `FormApi` | Returns an independent raw snapshot before field mapping and `valueFormat`. |
+| `formatValues(rawValues)` | `FormApi` | Runs the unified formatting pipeline on a supplied raw snapshot. |
+| `getValueSnapshot()` | `FormApi` | Returns `{ rawValues, values }`, where `values` is the formatted payload. |
+| `asyncDebounceMs` | `FormFieldOptions` | Configures TanStack Field async validation debounce. |
+| `changeEventFallback` | `FormCommonConfig` / adapter config | Enables fallback for legacy components that emit `change` without `update:*`; defaults to `false`. |
+
+`dependencies.resolve` may return `if`, `show`, `disabled`, `required`, `rules`, `componentProps`, `help`, and `renderComponentContent`. Omitting `rules` keeps the static rule; returning `rules: null` disables it.
+
+### Changed APIs
+
+| API | Before | After |
+| --- | --- | --- |
+| Submit callback | `handleSubmit(values)` | `handleSubmit(values, rawValues)`; the first argument is formatted and the second is the matching readonly raw snapshot. Existing single-argument functions remain valid. |
+| Values change callback | `handleValuesChange(values, fieldsChanged)` | `handleValuesChange(rawValues, fieldsChanged, getFormattedValues)`; formatting is lazy and incurs no clone/transform cost unless requested. |
+| Field validation triggers | Four `validateOn*` booleans | `validateOn?: readonly ('blur' \| 'change')[]`; submit always validates. |
+| Change-event compatibility | `disabledOnChangeListener: false` enabled fallback | `changeEventFallback: true` enables fallback with positive semantics. |
+| Top-level render callbacks | `componentProps(values, actions, ctx)`, `help(values, actions, ctx)`, `renderComponentContent(values, actions, ctx)` | Receive only lightweight `FormSchemaContext`; value-dependent behavior moves to `dependencies.resolve`. |
+| `validateAndSubmit()` | Repeated low-level validation/scroll handling and could validate again during submit | Delegates to canonical `validate()` and shared submission logic; invalid forms do not submit. |
+| `getValues()` | Implicitly returned transformed values | Still returns the formatted payload; use `getRawValues()` for raw state. |
+
+### Removed APIs
+
+| Removed API | Replacement |
+| --- | --- |
+| `FormValidationOptions` | `validate()` and `validateField(fieldName)` no longer accept options. |
+| `force` / `silent` / `validated-only` validation modes | Removed because these vee modes have no TanStack runtime semantics. |
+| `validateOnBlur` / `validateOnChange` / `validateOnInput` / `validateOnModelUpdate` | Use `formFieldProps.validateOn`; input and model updates are represented by `change`. |
+| `disabledOnChangeListener` | Use positive `changeEventFallback`. |
+| `disabledOnInputListener` | Input listeners are no longer bound automatically; provide `componentProps.onInput` explicitly when required. |
+| `values/actions` parameters from top-level schema render functions | Use `FormSchemaContext`; move value-dependent behavior to `dependencies.resolve`. |
+
+### Deprecated but Supported
+
+- `dependencies.if/show/disabled/required/rules/componentProps/trigger` remain compatible for this release, but every callback is marked `@deprecated` and emits one development warning. If both syntaxes bypass the type union, `resolve` wins.
+- `resetForm`, `submitForm`, `resetValidate`, and `validateAndSubmitForm` continue forwarding to canonical methods.
+- `FormActions` remains as a deprecated alias of `FormContextApi`.
+- `setupVbenForm({ defineRules })` remains supported; `rules` wins for duplicate names.
+- The re-exported `z`, `componentField` slots, and `emptyStateValue` remain unchanged.
+
+### Internal Behavior Changes
+
+- Field components use fine-grained value/error selectors; full error aggregation is no longer on the normal input path.
+- Async validators discard stale Promises through a Vben generation without reading private TanStack AbortController or meta fields.
+- New and legacy dependencies share one atomic executor, so stale async results cannot overwrite newer state.
+- Formatting runs in a fixed array-to-string, range mapping, schema `valueFormat` order and performs one deep clone per formatted snapshot.
+
+## Typed Values and Slots
+
+Application adapters keep the UI component mapping fixed and expose the business value shape as the only generic:
+
+```ts
+interface AccountFormValues {
+  email: string;
+  nickname: string;
+}
+
+const [Form, formApi] = useVbenForm<AccountFormValues>({
+  handleSubmit(values) {
+    return addAccount(values);
+  },
+  schema: [
+    { component: 'Input', fieldName: 'email' },
+    { component: 'Input', fieldName: 'nickname' },
+  ],
+});
+```
+
+`TValues` flows through `VbenFormProps`, `FormSchema`, `FormApi`, `FormContextApi`, value APIs, submit/change callbacks, selectors, and dynamic schema callbacks. The returned `Form` component also exposes typed slots: known field slots use the matching value type for `field.state.value` and `componentField.modelValue`, while all field/default/action slots receive the complete `values` and matching `formApi`. Legacy forms without `TValues` retain arbitrary slot names and broad props.
+
+## New and Legacy Rule Registration
+
+Use `rules` in new code:
+
+```ts
+setupVbenForm({
+  rules: {
+    required(value, _params, context) {
+      const isEmpty =
+        value === undefined ||
+        value === null ||
+        value === '' ||
+        (Array.isArray(value) && value.length === 0);
+      return isEmpty ? `${context.label} is required` : true;
+    },
+  },
+});
+```
+
+The legacy `defineRules` option forwards to the same registry:
+
+```ts
+setupVbenForm({
+  defineRules: {
+    required: legacyRequiredRule,
+  },
+});
+```
+
+Legacy runtime usage emits one warning per deprecation key in development and no warnings in production. If both options define the same rule, `rules` wins. The `FormActions` type remains as a deprecated alias of `FormContextApi`; editors report the type deprecation because type-only usage cannot emit runtime warnings.
+
+## Running the Codemod
+
+Run the pinned tool against each affected tsconfig from a clean Git worktree:
+
+```bash
+npx --yes zod-v3-to-v4@1.21.3 path/to/tsconfig.json
+```
+
+The tool edits `.ts`, `.tsx`, and `.vue` files in place and has no dry-run mode. Always review `git diff` afterward.
+
+The codemod primarily recognizes direct `zod` imports. Schemas that obtain `z` through `@vben/common-ui` or an application adapter need manual review, especially constructor errors, string formats, and dynamic refinement messages.
+
+## Zod 4 Changes
+
+### Unified Error Parameters
+
+Replace `required_error` and `invalid_type_error` with `error`:
+
+```ts
+const count = z.number({
+  error: (issue) =>
+    issue.input === undefined ? 'Count is required' : 'Count must be a number',
+});
+```
+
+Use an `error(issue)` callback for dynamic refinement messages instead of passing a function that returns params as the second argument to `.refine()`.
+
+### String Formats and Errors
+
+Prefer top-level format schemas:
+
+```ts
+z.email('Invalid email');
+z.url('Invalid URL');
+z.uuid('Invalid UUID');
+```
+
+Read validation details from `ZodError.issues`; the old `.errors` property is removed.
+
+### Defaults and Optionality
+
+Zod 4 defaults may return immediately when the input is `undefined`. Review `.default().optional()` using actual parse behavior instead of internal type names.
+
+Vben initial values use this precedence:
+
+1. explicit schema `defaultValue`
+2. Zod `.default()`
+3. Zod 4-compatible `zod-defaults`
+4. component empty-state conventions
+
+Required markers are derived from whether the schema accepts `undefined`.
+
+### Wrappers, Refine, Transform, and Coerce
+
+Do not read `_def`, `_zod.def`, or `typeName`. Use public `.unwrap()` APIs and public pipe inputs. Delegate intersection defaults to the Zod 4-compatible `zod-defaults` package.
+
+Standard Schema validation does not write transform/coerce output back into TanStack Form state. Keep using `valueFormat` for submission payload conversion, or explicitly call `parseAsync` at the submission boundary when transformed schema output is required.
+
+Also review these changes:
+
+- `z.record()` should specify key and value schemas
+- `z.enum()` replaces former `nativeEnum` use cases
+- number integer, Infinity, and finite behavior
+- object strictness, merge, and unknown keys
+- intersection merge conflicts
+- coerce input types defaulting to `unknown`
+- removal of Zod 3 types such as `ZodEffects`, `ZodTypeAny`, and `AnyZodObject`
+
+## Form Engine Behavior
+
+`formFieldProps.validateOn` accepts `blur` and `change`, with both enabled by default; submit always validates fields. `asyncDebounceMs` configures TanStack Field async debounce. The four vee-style `validateOn*` booleans and `force/silent/validated-only` modes have been removed.
+
+The shadcn form primitives now use a Vben-owned field context. Labels, controls, descriptions, and messages continue to provide ids, `aria-invalid`, `aria-describedby`, touched, dirty, valid, and error states.
+
+`clearValidation(fieldNames?)` advances Vben's validator generation and clears public error state without relying on a private TanStack AbortController. A Promise that finishes later is discarded as stale. Omitting `fieldNames` covers every registered field and every field with an existing error.
+
+`dependencies.resolve(context)` is the recommended API: it evaluates once and atomically commits one dynamic-state patch, while stale async results are discarded as a unit. Legacy `if/show/disabled/required/rules/componentProps/trigger` callbacks remain supported through the same normalized executor, but are marked `@deprecated` and emit one development warning. Both APIs react only to declared `triggerFields`.
+
+`handleValuesChange(rawValues, fieldsChanged, getFormattedValues)` receives readonly raw values and formats only when its third argument is called. `getRawValues()` and `getValues()` each create only the requested snapshot; use `getValueSnapshot()` when both are required. `handleSubmit(values, rawValues)` receives both forms at submission. The formatter performs one deep clone, then applies array-to-string, range mapping, and schema `valueFormat` in order. Array fields keep using TanStack push/remove operations and stable row identity.
+
+## Test and Acceptance Matrix
+
+Required coverage includes:
+
+- Zod defaults, optional, nullable, intersection, pipe, transform, coerce, and errors
+- runtime values, selectors, reset, manual errors, validation, and async validation
+- field binding, blur/change triggers, error messages, ARIA, dependencies, and arrays
+- new/legacy API equivalence, warning deduplication, production silence, and type aliases
+- complete `useVbenForm` lifecycle, submission, `handleValuesChange`, submit-on-change, and async race handling
+
+Acceptance requires zero TypeScript errors, zero build errors, all tests passing, no unhandled browser errors, modified-file formatting and lint passing, and no source dependency on vee or Zod private structures.
+
+## References
+
+- [Zod 4 release notes](https://zod.dev/v4)
+- [Zod migration guide](https://zod.dev/v4/changelog)
+- [TanStack Form Vue overview](https://tanstack.com/form/latest/docs/framework/vue/overview)
+- [TanStack Form validation](https://tanstack.com/form/latest/docs/framework/vue/guides/validation)

docs/src/guide/in-depth/zod-v4-form-migration.md

@@ -0,0 +1,274 @@
+---
+outline: deep
+---
+
+# Zod 4 与 TanStack Form 迁移指南
+
+本次迁移将表单校验 schema 从 Zod 3 升级到 Zod 4，并将内部表单引擎从 vee-validate 替换为 TanStack Form。迁移目标是保持 Vben 业务 API 稳定，同时移除业务代码对具体表单引擎的耦合。
+
+## 依赖变化
+
+| 类型 | 迁移前 | 迁移后 |
+| --- | --- | --- |
+| Schema | `zod@^3.25.76` | `zod@^4.4.3` |
+| 默认值 | `zod-defaults@0.1.3` | `zod-defaults@^0.2.3` |
+| 表单引擎 | `vee-validate@^4.15.1` | `@tanstack/vue-form@^1.33.2` |
+| Zod 适配器 | `@vee-validate/zod@^4.15.1` | 不再需要，TanStack Form 支持 Standard Schema |
+
+迁移后，源码、package manifest 和锁文件中都不应再依赖 `vee-validate` 或 `@vee-validate/zod`。
+
+## 上层兼容范围
+
+以下 Vben API 保持兼容：
+
+- `useVbenForm(options)` 仍返回 `[Form, formApi]`
+- `FormApi` 的值、校验、提交、重置、schema 更新和组件引用能力
+- `FormSchema` 的 `fieldName`、`component`、`componentProps`、`rules`、`dependencies`、`defaultValue`、`valueFormat` 和数组字段结构
+- `dependencies.triggerFields` 与回调参数
+- 组件适配器和 `z` 重导出路径
+- 自定义 slot 中原有的 `componentField` 绑定对象
+
+`formApi.form` 现在是库无关的 `FormContextApi`。它提供 values、errors、meta、字段读写、验证、提交、重置和数组操作，但不再暴露 vee `FormContext` 或原始 TanStack 实例。
+
+新代码使用 `reset`、`submit`、`validateAndSubmit` 和 `clearValidation`。旧的 `resetForm`、`submitForm`、`validateAndSubmitForm` 和 `resetValidate` 仍会委托给新实现，并通过 `@deprecated` 与开发环境一次性 warning 提示迁移；生产环境不输出 warning。
+
+## 本轮 Form UI API 变更
+
+### 新增 API
+
+| API | 类型/位置 | 说明 |
+| --- | --- | --- |
+| `dependencies.resolve(context)` | `FormItemDependenciesResolve` | 根据声明的 `triggerFields` 一次计算完整动态 patch，并原子更新字段状态。context 包含只读 `values`、`actions`、`controller` 和数组行感知的 `schema`。 |
+| `useValues()` | `FormContextApi` | 订阅完整表单值。仅在确实需要整表响应式值时使用。 |
+| `useFieldValue(fieldName)` | `FormContextApi` | 订阅单字段值，避免无关字段变化触发组件更新。 |
+| `useFieldValues(fieldNames)` | `FormContextApi` | 订阅一组字段值，主要用于声明式依赖计算。 |
+| `useFieldError(fieldName)` | `FormContextApi` | 订阅单字段错误，不再依赖全量错误对象。 |
+| `getRawValues()` | `FormApi` | 返回未执行字段映射与 `valueFormat` 的独立原始值快照。 |
+| `formatValues(rawValues)` | `FormApi` | 对指定原始值执行统一格式化流水线。 |
+| `getValueSnapshot()` | `FormApi` | 同时返回 `{ rawValues, values }`，其中 `values` 为格式化结果。 |
+| `asyncDebounceMs` | `FormFieldOptions` | 设置 TanStack Field 异步校验防抖时间。 |
+| `changeEventFallback` | `FormCommonConfig` / adapter config | 为只发送 `change`、不发送 `update:*` 的旧组件启用事件回退，默认 `false`。 |
+
+`dependencies.resolve` 可以返回 `if`、`show`、`disabled`、`required`、`rules`、`componentProps`、`help` 和 `renderComponentContent`。未返回 `rules` 时继续使用静态规则；显式返回 `rules: null` 时关闭静态规则。
+
+### 变更的 API
+
+| API | 迁移前 | 迁移后 |
+| --- | --- | --- |
+| 提交回调 | `handleSubmit(values)` | `handleSubmit(values, rawValues)`；首参为格式化值，次参为同一次提交对应的只读原始快照。旧单参数函数仍可直接使用。 |
+| 值变化回调 | `handleValuesChange(values, fieldsChanged)` | `handleValuesChange(rawValues, fieldsChanged, getFormattedValues)`；第三个参数为惰性格式化函数，不调用时不产生深拷贝和转换开销。 |
+| 字段校验触发 | 四个 `validateOn*` 布尔项 | `validateOn?: readonly ('blur' \| 'change')[]`；submit 始终校验。 |
+| change 事件兼容 | `disabledOnChangeListener: false` 表示启用 | `changeEventFallback: true` 表示启用，改为正向语义。 |
+| 顶层动态渲染回调 | `componentProps(values, actions, ctx)`、`help(values, actions, ctx)`、`renderComponentContent(values, actions, ctx)` | 仅接收轻量 `FormSchemaContext`。依赖表单值的动态逻辑迁移到 `dependencies.resolve`。 |
+| `validateAndSubmit()` | 自行调用底层校验并重复实现错误滚动，提交阶段可能再次校验 | 委托统一 `validate()` 与共享提交逻辑，无效时不提交，错误滚动只有一个实现。 |
+| `getValues()` | 隐式完成所有字段转换 | 语义保持为“返回格式化值”；需要原始值时显式使用 `getRawValues()`。 |
+
+### 删除的 API
+
+| 已删除 API | 替代方式 |
+| --- | --- |
+| `FormValidationOptions` | `validate()` 与 `validateField(fieldName)` 不再接收 options。 |
+| `force` / `silent` / `validated-only` validation mode | 这些 vee mode 在 TanStack runtime 中没有对应语义，直接删除。 |
+| `validateOnBlur` / `validateOnChange` / `validateOnInput` / `validateOnModelUpdate` | 使用 `formFieldProps.validateOn`；input 与 model update 统一归入 `change`。 |
+| `disabledOnChangeListener` | 使用正向语义的 `changeEventFallback`。 |
+| `disabledOnInputListener` | 不再自动绑定 input listener；确需自定义 input 处理时在 `componentProps.onInput` 中显式提供。 |
+| 顶层 schema 渲染函数中的 `values/actions` 参数 | 使用 `FormSchemaContext`；值相关联动使用 `dependencies.resolve`。 |
+
+### 已弃用但保留兼容
+
+- `dependencies.if/show/disabled/required/rules/componentProps/trigger` 本轮仍完整兼容，但均已标记 `@deprecated`。开发环境首次使用时警告一次；新旧语法绕过类型同时存在时以 `resolve` 为准。
+- `resetForm`、`submitForm`、`resetValidate` 和 `validateAndSubmitForm` 继续转发到新方法。
+- `FormActions` 继续作为 `FormContextApi` 的弃用类型别名。
+- `setupVbenForm({ defineRules })` 继续兼容；与 `rules` 同名时新 API 优先。
+- `z` 重导出、`componentField` slot 和 `emptyStateValue` 保持不变。
+
+### 非 API 行为调整
+
+- 字段组件改用细粒度 value/error selector；全量错误聚合退出普通输入热路径。
+- async validator 通过 Vben generation 丢弃过期 Promise，不读取 TanStack 私有 AbortController 或 meta 字段。
+- dependencies 新旧语法共用一个原子执行器，异步旧结果不会覆盖新状态。
+- 值格式化按 array-to-string、时间范围映射、schema `valueFormat` 的固定顺序执行，并且每次格式化只深拷贝一次。
+
+## 值类型与插槽类型
+
+应用 adapter 保留 UI 组件类型，只把业务值类型作为泛型暴露：
+
+```ts
+interface AccountFormValues {
+  email: string;
+  nickname: string;
+}
+
+const [Form, formApi] = useVbenForm<AccountFormValues>({
+  handleSubmit(values) {
+    return addAccount(values);
+  },
+  schema: [
+    { component: 'Input', fieldName: 'email' },
+    { component: 'Input', fieldName: 'nickname' },
+  ],
+});
+```
+
+`TValues` 会传递给 `VbenFormProps`、`FormSchema`、`FormApi`、`FormContextApi`、值读写 API、提交/变化回调、selector 和 schema 动态回调。返回的 `Form` 组件同时提供 typed slots：已知字段插槽的 `field.state.value` 与 `componentField.modelValue` 使用对应字段类型，并额外提供完整 `values` 与同型 `formApi`；默认和操作插槽也提供 `values/formApi`。未声明 `TValues` 的旧表单仍允许任意字段插槽并回退为宽泛类型。
+
+## 新旧规则注册 API
+
+新代码使用 `rules`：
+
+```ts
+setupVbenForm({
+  rules: {
+    required(value, _params, context) {
+      const isEmpty =
+        value === undefined ||
+        value === null ||
+        value === '' ||
+        (Array.isArray(value) && value.length === 0);
+      return isEmpty ? `${context.label} is required` : true;
+    },
+  },
+});
+```
+
+旧的 `defineRules` 仍会转发到同一个规则注册表：
+
+```ts
+setupVbenForm({
+  defineRules: {
+    required: legacyRequiredRule,
+  },
+});
+```
+
+使用旧入口时，开发环境针对该弃用项只输出一次警告；生产环境不输出。若同时提供 `rules` 与 `defineRules` 的同名规则，`rules` 优先。`FormActions` 类型保留为 `FormContextApi` 的弃用别名，类型别名本身无法触发运行时警告，编辑器会通过 `@deprecated` 提示迁移。
+
+## 使用迁移工具
+
+建议在干净的 Git 工作树中按项目 tsconfig 执行固定版本工具：
+
+```bash
+npx --yes zod-v3-to-v4@1.21.3 path/to/tsconfig.json
+```
+
+工具会原地修改 `.ts`、`.tsx` 和 `.vue` 文件，没有 dry-run 模式。执行后必须检查 `git diff`。
+
+工具只能可靠识别直接从 `zod` 导入的调用。通过 `@vben/common-ui` 或应用 adapter 间接取得 `z` 的 schema 需要人工审计，尤其是构造器错误参数、字符串格式和动态 refine 参数。
+
+## Zod 4 代码变更
+
+### 错误参数
+
+构造器中的 `required_error` 和 `invalid_type_error` 合并为 `error`：
+
+```ts
+const count = z.number({
+  error: (issue) =>
+    issue.input === undefined ? 'Count is required' : 'Count must be a number',
+});
+```
+
+refinement 继续支持字符串或对象参数。需要根据输入动态生成消息时，使用 `error(issue)`，不再传入返回 params 的第二个函数。
+
+### 字符串格式
+
+优先使用顶层格式 API：
+
+```ts
+z.email('Invalid email');
+z.url('Invalid URL');
+z.uuid('Invalid UUID');
+```
+
+旧的 `z.string().email()` 等形式不应继续新增。
+
+### 错误列表
+
+ZodError 使用 `issues`：
+
+```ts
+const result = schema.safeParse(value);
+if (!result.success) {
+  console.log(result.error.issues);
+}
+```
+
+不要读取已移除的 `.errors`。
+
+### 默认值与 optional
+
+Zod 4 的 default 在输入为 `undefined` 时可以直接返回默认值。`.default().optional()` 的结果必须按实际 parse 语义复核，而不是通过类型名称猜测。
+
+Vben 表单按以下优先级生成初值：
+
+1. schema 中显式 `defaultValue`
+2. Zod schema 中的 `.default()`
+3. `zod-defaults` 生成的对象、intersection 和基础空值
+4. Vben 组件约定的空字符串、空数组或空状态值
+
+必填标记以 schema 是否接受 `undefined` 为准。
+
+### 包装器、refine 与 transform
+
+不要读取 `_def`、`_zod.def` 或 `typeName`。公共包装器使用 `.unwrap()`；Zod 4 的 transform/pipe 使用公开的输入 schema。intersection 的默认值交给支持 Zod 4 的 `zod-defaults` 处理。
+
+TanStack Form 使用 Standard Schema 校验时不会自动把 transform/coerce 的输出写回当前表单 state。提交 payload 需要转换时，继续使用 `valueFormat`；如果必须提交 schema transform 后的结果，应在提交边界显式调用 `parseAsync`。
+
+### 其他需要复核的 API
+
+- `z.record()` 需要明确 key schema 与 value schema
+- `z.enum()` 已覆盖原 `nativeEnum` 用法
+- number 的 `int`、Infinity 和 finite 约束需按 Zod 4 语义复核
+- object 的 strict、merge、unknown keys 行为需要通过测试确认
+- intersection 合并冲突现在可能直接抛出错误
+- coerce schema 的 input 类型默认为 `unknown`
+- `ZodEffects`、`ZodTypeAny`、`AnyZodObject` 等 Zod 3 类型不应继续使用
+
+## 表单引擎行为
+
+### 验证触发
+
+`formFieldProps.validateOn` 接收 `blur`、`change` 数组，默认两者都启用；所有字段仍会在 submit 时验证。`asyncDebounceMs` 映射到 TanStack Field 的异步防抖配置。原 vee 风格的四个 `validateOn*` 布尔项和 `force/silent/validated-only` mode 已删除。
+
+### 错误与可访问性
+
+shadcn form primitive 使用 Vben 自有字段上下文，不再注入 vee 的 `FieldContextKey`。`FormLabel`、`FormControl`、`FormDescription` 和 `FormMessage` 继续维护：
+
+- `for` 与 control id
+- `aria-invalid`
+- `aria-describedby`
+- touched、dirty、valid 和错误消息
+
+`clearValidation(fieldNames?)` 会递增 Vben validator generation 并清空公开错误状态，不依赖 TanStack 私有 AbortController。异步 Promise 即使随后完成也会因代次过期而被丢弃；省略字段参数时会处理全部已注册或已有错误的字段。
+
+### 依赖与数组
+
+`dependencies.resolve(context)` 是推荐语法：一次求值并原子提交完整动态 patch，过期异步结果整体丢弃。旧的 `if/show/disabled/required/rules/componentProps/trigger` 语法仍兼容，但已标记为 `@deprecated` 并在开发环境首次使用时提示迁移；内部仍归一到同一个执行器。两种语法都只根据 `triggerFields` 重算，无关字段变化不会执行回调。
+
+`handleValuesChange(rawValues, fieldsChanged, getFormattedValues)` 接收未格式化的只读当前值，第三个参数仅在调用时执行格式化。`getRawValues()` 和 `getValues()` 分别只生成原始或格式化快照；需要同时比较时使用 `getValueSnapshot()`。提交回调通过 `handleSubmit(values, rawValues)` 同时取得两种结构。格式化流水线只深拷贝一次，并按 array-to-string、时间范围映射、schema `valueFormat` 的顺序执行。数组字段继续使用 TanStack push/remove 操作和稳定行身份。
+
+## 测试与验收
+
+迁移至少需要覆盖以下层级：
+
+- Zod 4 helper：default、optional、nullable、intersection、pipe、transform、coerce 与错误参数
+- runtime：值读写、selector、reset、字段错误、validate 和异步校验
+- 组件：输入绑定、blur/change 触发、错误消息、ARIA、dependencies 和数组增删
+- 兼容：`rules`/`defineRules` 结果一致、开发 warning 去重、生产静默、类型别名
+- 集成：`useVbenForm` 生命周期、提交、`handleValuesChange`、submit-on-change 和 async race
+
+验收标准：
+
+1. 受影响 package、应用、playground 和 docs 无 TypeScript 错误
+2. form-ui 与所有应用构建成功
+3. 单元、组件和集成测试全部通过
+4. 浏览器 smoke 流程无 `pageerror`、`console.error` 或未处理 Promise
+5. 修改文件通过 oxfmt 与 ESLint
+6. 静态搜索中不再出现 vee 依赖、Zod 私有结构或 Zod 3 错误参数
+
+## 参考资料
+
+- [Zod 4 release notes](https://zod.dev/v4)
+- [Zod migration guide](https://zod.dev/v4/changelog)
+- [TanStack Form Vue overview](https://tanstack.com/form/latest/docs/framework/vue/overview)
+- [TanStack Form validation](https://tanstack.com/form/latest/docs/framework/vue/guides/validation)