fix(form-core): re-run form-level validator on resubmit to clear its own stale field errors

[FrancoKaddour]

Closes #2248

Problem

With only a form-level onSubmit validator (no field-level validators), the form can never re-validate on a second submit while any error is outstanding.

_handleSubmit runs validateAllFields('submit') (field-level only), then bails at if (!this.state.isFieldsValid) return — before this.validate('submit') (the form-level validator) is reached. A form-level validator writes its errors onto fields ({ fields }), but validateAllFields can't clear or recompute them, so isFieldsValid stays false from the previous submit and the form-level validator never re-runs — gating the form off permanently (even with canSubmitWhenInvalid: true).

Fix

Run the form-level validator right after validateAllFields, guarded by whether any field-level validator errored this submit (validateAllFields returns those errors). When none errored, it re-runs and recomputes/clears its own field errors; when field-level validators did error, it's skipped as before (preserving the existing "don't trigger form validators if field validators errored" behavior).

Tests

Added a form-core unit test reproducing #2248 (form-level-only validator, fill fields, resubmit → errors clear and onSubmit runs). Full form-core (504) and react-form (126) suites pass; the existing field-validator-gating test still passes.

Summary by CodeRabbit

• Bug Fixes
  • Form-level submit validation now reruns on each submission when field-level validation passes.
  • Stale field errors are cleared after previously invalid fields are corrected.
  • Valid forms can now submit successfully on a subsequent attempt.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4fb62140-46e5-4d3e-aabc-76e0f15f915c

📥 Commits

Reviewing files that changed from the base of the PR and between 7840e02 and 95847a7.

📒 Files selected for processing (1)

• packages/form-core/tests/FormApi.spec.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/form-core/tests/FormApi.spec.ts

---

📝 Walkthrough

Walkthrough

Form submission now reruns form-level validation when field validation has no errors. A regression test verifies that corrected values clear stale errors and allow onSubmit to run. A patch changeset documents the behavior.

Changes

Form validation resubmission

Layer / File(s)	Summary
Conditional submission validation packages/form-core/src/FormApi.ts	Submission stores field-validation errors, runs form-level validation only when no field errors exist, and removes the unconditional later validation call.
Regression coverage and release note packages/form-core/tests/FormApi.spec.ts, .changeset/form-level-validator-resubmit.md	The regression test verifies that a second submission clears stale errors and invokes onSubmit. The changeset documents the patch release.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related issues

• Form-level validator doesn't re-run after first submit while fields hold errors — bug or by design? #2248 — This change updates the same submission validation flow described in the issue.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the form-level validator resubmission fix and its stale-error behavior.
Description check	✅ Passed	The description clearly explains the problem, fix, tests, and release impact, although it does not use the repository template headings or checklist.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/form-core/tests/FormApi.spec.ts`:
- Around line 1974-1977: Update the regression comment in the FormApi test
around _handleSubmit to replace “Currently” with “Before this fix,” preserving
the description that the prior implementation bailed before validate('submit')
and documenting it as historical behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 451a049e-47dc-4dc9-a1d9-487de253cc4d

📥 Commits

Reviewing files that changed from the base of the PR and between 5d11281 and 7840e02.

📒 Files selected for processing (3)

• .changeset/form-level-validator-resubmit.md
• packages/form-core/src/FormApi.ts
• packages/form-core/tests/FormApi.spec.ts

[MILLERMARRU]

Traced through validateAllFields and validate on main to make sure I understood what each one actually touches before judging the fix. validateAllFields('submit') calls every field's validate with skipFormValidation: true, so fieldErrors here is strictly field-level validator output, it never includes anything the form-level { fields } validator wrote. validate('submit') is the one that actually runs options.validators.onSubmit against the whole form and applies its fields map onto each field's error map. That separation is what makes the fix work.

The actual deadlock in #2248 makes sense once you see that isFieldsValid is a stale aggregate: after the first submit, the form-level validator writes Required into fieldMeta.name.errorMap.onSubmit and fieldMeta.other. On the second submit, there are no field-level validators to touch those entries, so isFieldsValid is still reading last submit's form-level output at the point the old code checked it, before validate('submit') ever got a chance to re-run and overwrite it. Gating the early-return on this.state.isFieldsValid was gating on data the form-level validator itself was supposed to refresh.

Switching the condition to fieldErrors.length === 0 fixes it because that's always this submit's fresh result, not a carried-over flag. And behaviorally nothing changes for the case that matters, when a field-level validator does fail, fieldErrors.length > 0 skips the form-level validator exactly like the old isFieldsValid gate did, since a field-level failure alone was already enough to fail isFieldsValid before. The only path that changes is the one that was actually broken, field-level clean but form-level state stale, and now the form-level validator gets to run and clear its own mess before the gate checks anything.

I also want to flag that the second await this.validate('submit') further down wasn't duplicated, it was moved, so the form-level validator still runs at most once per submit attempt in the passing path. That's an easy thing to get subtly wrong when relocating a call like this, and it's clean here.

Test is solid, it reproduces the exact regression path (submit empty, see fields get flagged by the form-level validator, fill the fields, submit again) and asserts both that the stale errors clear and that onSubmit actually fires, which is the part that would have silently failed forever under the old code without ever throwing.

[FrancoKaddour]

Thanks for the careful trace @MILLERMARRU — you nailed exactly why gating on this submit's fresh fieldErrors instead of the stale isFieldsValid aggregate is what lets the form-level validator clear its own errors. Appreciate the second set of eyes.