feat: set field errors from the form validators

[fulopkovacs]

This PR adds the ability to set field errors from the form validators.

The API would look like this (this is a value returned by a validator):

{
  form: "General form error", // optional,
  fields: {
    username: "Username taken",
    password: "Password is too short"
  }
}

We'll add support for Zod, Yup, and Valibot in a separate PR.

TODO

• Initial implementation of the feature
• Add tests for
  • basic fields
  • array fields
  • nested fields in array fields
  • linked fields
• Clean up the code
  • form-core
  • tests
• Docs
• Rebase to main

[nx-cloud]

☁️ Nx Cloud Report

CI is running/has finished running commands for commit a8dbbdc. As they complete they will appear below. Click to see the status, the terminal output, and the build insights.

📂 See all runs for this CI Pipeline Execution

---

✅ Successfully ran 1 target

• nx affected --targets=test:format,test:sherif,test:knip,test:eslint,test:lib,test:types,test:build,build --parallel=3

---

Sent with 💌 from NxCloud.

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 98.92473% with 1 lines in your changes are missing coverage. Please review.

Project coverage is 91.39%. Comparing base (9ecc5e2) to head (f681ae4).
Report is 6 commits behind head on main.

Files	Patch %	Lines
packages/form-core/src/FormApi.ts	98.27%	1 Missing ⚠️

❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff            @@
##           main     #656       +/-   ##
=========================================
+ Coverage      0   91.39%   +91.39%     
=========================================
  Files         0       32       +32     
  Lines         0      964      +964     
  Branches      0      215      +215     
=========================================
+ Hits          0      881      +881     
- Misses        0       77       +77     
- Partials      0        6        +6     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[denisorehovsky]

Hi. When are you planning to release it? Thanks.

[fulopkovacs]

Hi. When are you planning to release it? Thanks.

I'm planning to pick this up during the weekend. 😅 Unfortunately there are some urgent things that I have to take care of in the tanstack/query repo (a lot of broken links in the docs), but I'll jump on this PR after that.

[denisorehovsky]

@fulopkovacs Perfect. Thank you. This is indeed necessary. I migrated from react-hook-form, which had a setError function that allowed setting errors when the backend responded with errors. It was surprising that this library doesn't yet support something similar. I think it's a very common use case to have backend validation and then set field-level validation errors.

[fulopkovacs]

Sad status update: I ran into some issues as I started adding more complex tests. This is a bummer because I wanted to get this one ready during the weekend. 😢

[denisorehovsky]

@fulopkovacs It's ok :)
Will be waiting for the update

[denisorehovsky]

@fulopkovacs Hey :) You're probably busy, so I'm sorry to bother you, but do you know when you will be able to get back to this PR? Without this solution, I will likely need to find a workaround for properly handling backend errors, or switch back to react-hook-form

[crutchcorn]

Hey @denisorehovsky, just as a heads up - we don't follow any kind of release schedule or cadence. As we're all volunteer based, we're only able to take on tasks as we have time. Maybe you could consider sponsoring the project financially or making a PR if you're needing priority support? 😄

Moreover, though, I'm not sure I understand how this is a blocker for anything. This PR is a nicety, not a required feature to merge form and field errors. You can always do that manually by using a helper component.

[fulopkovacs]

@fulopkovacs Hey :) You're probably busy, so I'm sorry to bother you, but do you know when you will be able to get back to this PR? Without this solution, I will likely need to find a workaround for properly handling backend errors, or switch back to react-hook-form

Hey ☺️,

I'm actively working on this PR! The process is slow, because there are many scenarios to handle. All the form-core tests are passing for the sync validators, and locally I am getting closer to solving the problem of the async validators too, but unexpected things keep popping up (right now I'm solving some issues for the linked fields).

After all the form-core tests pass, I'm planning to add some library tests (React), to make sure that everything is OK.

Then, the PR will go to review, but unfortunately, I don't expect that to be very quick (it's gonna be a beefy PR), and there's always the chance that the approach I chose doesn't fit the project well enough. 😬

In short, I'm sorry, but this will likely take some time. (Honestly, it's more complex than I expected it to be, I thought I'd be ready by the end of last week.)

Finding a workaround is a more realistic solution than waiting for this feature to be merged. For example, you can handle the form's validation on the server with the form's onSubmitAsync validator, and save the field-related errors to your component's local state before you return an error (that you don't have to display btw) for the form. There are also other ways to solve this, I hope you find one that fits your use case.

In situations like this, I'm really sad that it's not my full-time job, it'd be awesome to respond to the users' needs more quickly! 😢 Thanks for your understanding though.