fix(core): clear stale wizard step errors

Author: RtlZeroMemory

CHANGELOG.md

@@ -6,6 +6,14 @@ The format is based on Keep a Changelog and the project follows Semantic Version
 
 ## [Unreleased]
 
+### Bug Fixes
+
+- `useForm` wizard transitions now clear stale step errors when async revalidation succeeds after a field value changes, preventing false navigation blocks.
+
+### Tests
+
+- Added wizard regressions for `nextStep()` and `goToStep()` when async step errors become stale after field edits.
+
 ## [0.1.0-alpha.60] - 2026-03-14
 
 ### Bug Fixes

packages/core/src/forms/__tests__/form.wizard.test.ts

@@ -388,6 +388,82 @@ describe("useForm wizard", () => {
     assert.equal(form.errors.email, "Email already taken");
   });
 
+  test("nextStep clears stale async-style step errors after the field value changes", async () => {
+    const h = createTestContext();
+
+    const options = createWizardOptions({
+      initialValues: {
+        name: "Ada",
+        email: "taken@example.com",
+        age: 30,
+      },
+      validateOnChange: false,
+      validateAsync: async (values) =>
+        values.email === "taken@example.com" ? { email: "Email already taken" } : {},
+      wizard: {
+        initialStep: 1,
+        steps: [
+          { id: "step-account", fields: ["name"] },
+          { id: "step-contact", fields: ["email"] },
+          { id: "step-confirm", fields: ["age"] },
+        ],
+      },
+    });
+
+    let form = h.render(options);
+    form.setFieldError("email", "Email already taken");
+    form = h.render(options);
+    form.setFieldValue("email", "fresh@example.com");
+    form = h.render(options);
+
+    const moved = form.nextStep();
+    form = h.render(options);
+
+    assert.equal(moved, false);
+    assert.equal(form.currentStep, 1);
+    assert.equal(form.errors.email, "Email already taken");
+
+    await flushMicrotasks();
+    form = h.render(options);
+
+    assert.equal(form.currentStep, 2);
+    assert.equal(form.errors.email, undefined);
+  });
+
+  test("goToStep clears stale async-style intermediate errors after the field value changes", async () => {
+    const h = createTestContext();
+
+    const options = createWizardOptions({
+      initialValues: {
+        name: "Ada",
+        email: "taken@example.com",
+        age: 30,
+      },
+      validateOnChange: false,
+      validateAsync: async (values) =>
+        values.email === "taken@example.com" ? { email: "Email already taken" } : {},
+    });
+
+    let form = h.render(options);
+    form.setFieldError("email", "Email already taken");
+    form = h.render(options);
+    form.setFieldValue("email", "fresh@example.com");
+    form = h.render(options);
+
+    const moved = form.goToStep(2);
+    form = h.render(options);
+
+    assert.equal(moved, false);
+    assert.equal(form.currentStep, 0);
+    assert.equal(form.errors.email, "Email already taken");
+
+    await flushMicrotasks();
+    form = h.render(options);
+
+    assert.equal(form.currentStep, 2);
+    assert.equal(form.errors.email, undefined);
+  });
+
   test("goToStep allows forward navigation when intermediate steps are valid", () => {
     const h = createTestContext();
 

packages/core/src/forms/internal/wizard.ts

@@ -197,6 +197,7 @@ export function resolveWizardTransition<T extends Record<string, unknown>>(optio
   transitionSteps: ReadonlyArray<WizardTransitionStep<T>>;
   source: WizardTransitionSource<T>;
   asyncErrors?: ValidationResult<T>;
+  includeSourceErrors?: boolean;
   runWizardStepValidation: (
     values: T,
     stepIndex: number,
@@ -209,12 +210,18 @@ export function resolveWizardTransition<T extends Record<string, unknown>>(optio
 }> | null {
   let mergedErrors = options.source.errors as ValidationResult<T>;
   for (const transitionStep of options.transitionSteps) {
+    const stepSourceErrors =
+      options.includeSourceErrors === false
+        ? clearValidationFields(mergedErrors, transitionStep.fields)
+        : options.asyncErrors === undefined
+          ? mergedErrors
+          : clearValidationFields(mergedErrors, transitionStep.fields);
     const baseStepErrors = options.runWizardStepValidation(
       options.values,
       transitionStep.stepIndex,
       {
         ...options.source,
-        errors: mergedErrors,
+        errors: stepSourceErrors,
       },
     );
     const stepErrors =
@@ -278,6 +285,7 @@ export function createWizardActions<T extends Record<string, unknown>>(options:
       values: snapshot.values,
       transitionSteps,
       source: snapshot,
+      includeSourceErrors: !options.validateAsync,
       runWizardStepValidation: options.runWizardStepValidation,
     });
     if (blocked) {
@@ -330,6 +338,7 @@ export function createWizardActions<T extends Record<string, unknown>>(options:
         transitionSteps,
         source: options.stateRef.current,
         asyncErrors,
+        includeSourceErrors: false,
         runWizardStepValidation: options.runWizardStepValidation,
       });
       if (asyncBlocked) {
@@ -393,6 +402,7 @@ export function createWizardActions<T extends Record<string, unknown>>(options:
       values: snapshot.values,
       transitionSteps,
       source: snapshot,
+      includeSourceErrors: !options.validateAsync,
       runWizardStepValidation: options.runWizardStepValidation,
     });
     if (blocked) {
@@ -445,6 +455,7 @@ export function createWizardActions<T extends Record<string, unknown>>(options:
         transitionSteps,
         source: options.stateRef.current,
         asyncErrors,
+        includeSourceErrors: false,
         runWizardStepValidation: options.runWizardStepValidation,
       });
       if (asyncBlocked) {