Handle global/server errors in forms

[bluebill1049]

• Start Date: 01-01-2023

💁‍♂️ Summary

This proposal is made so we can discuss and find a proper and better to handle generic errors which not associated with specific form fields.

👋🏻 Motivation

There are errors which potentially not associated with the form field or coming from the server, we would like a better way to handle it to provide a better developer experience.

👀 Related feature request: #7661

The most user would have used setError to set server error:

const onSubmit = () => {
  try {
    fetch(...)
  } catch() {
    setError('server', { type: 'serverError', message: e.message })
  }
}

This works relatively well, however, it will require a developer to manually remove that server error before the next submission could pass, because the server error does not associate with any input, so the validation error will be persister unless the user invoked clearErrors('server'). eg:

onSubmit: (e) => {
  methods.clearErrors();
  methods.handleSubmit(submit)(e);
},

📖 Design/Proposal

Include a global root error, which is:

• type-safe
• no submission blocking, no longer need clearErrors
• not field associated
• flexible enough for custom errors not related to form field
• using root for consistency as we used for field array root errors as well

const onSubmit = () => {
  try {
    fetch(...)
    if (response.statusCode > 300) {
        setError('root.serverError', { 
          type: response.statusCode,
          message: e.message,
          // meta: {}, // something to be consider to included in the phase 2 with meta object
        })
    }
  } catch(e) {
    setError('root.serverCatch', { 
      type: 'server',
      message: e.message
    })
  }
}

const onClick = () => {
  setError('root.random', { 
    type: 'random', 
    message: 'random' 
  })
}

return (
  <>
    {errors.root.serverError.type === 400 && <p>server response message</p>}
    <p>{errors.root.serverError.message}</p>
    
    {errors.root.serverCatch.type === 'server' && <p>server error message</p>}
    <p>{errors.root.serverCatch.message}</p>
    
    <p>{errors.root.random.message}</p>
  </>
)

😢 Drawbacks

Potentially naming clashes with an existing error that users are already using.

🙋‍♂️ Unresolved questions

Do we have any better approach?

cc @Moshyfawn @leapful

[enyelsequeira]

This would be extremely helpful, specially with the new next 13. Few questions to think about

1. does that mean you could do logic outside of the component?
2. Would this addition to the API allow usage of the library with Remix run. I know there are other libs thats use this under the hood like remixseasonsed forms. However there are some caveats.
3. How would you handle multiple steps in the form? I think bottom line would how would you share data between server and client component maybe 🤔

[bluebill1049]

does that mean you could do logic outside of the component?

At the moment, it's still hook-based, so it will have to be within the component.

Would this addition to the API allow usage of the library with Remix run. I know there are other libs thats use this under the hood like remixseasonsed forms. However there are some caveats.

Would love to do so, do you have any insight or documentation where we can look into it?

How would you handle multiple steps in the form? I think bottom line would how would you share data between server and client component maybe

I would still suggest breaking multiple steps forms into forms instead of a giant useForm hoisting everything in there. Even with this app that I am buidling which split each step into its own form state.

Each step would be able to send a request to save the form data, and if there is a server error, I am logging that to the user and info them about the failure and they can continue to fill up the rest of the steps.

[enyelsequeira]

Yeah for sure this is the one that I’ve personally used in the past, but then again like I’ve said the moment you start making abstraction the way you normally would using RHF is start falling apart and becomes harder to use https://remix-forms.seasoned.cc/

[joaopaulomoraes]

[Brainstorm]: What if errors were split or merged based on the value of an isServer (the name can change) option? Default can be false, no custom properties or parameters are required.

setError('registerInput', { ..., message: 'custom message' });

{errors.registerInput.message}

setError('registerInput', { ..., message: 'server message' }, { isServer?: boolean = false, meta?: object }); // statusCode, etc

{errors.server.message}

{errors.server?.meta?.statusCode} // for additional data or UI validation

So only when isServer is on everything related to the field can be ignored and the error abstracted.

[joaopaulomoraes]

Noice!

[bluebill1049]

I have thought about this last night, i think this approach maybe troublesome, because users may potenitally have a deeply nested error object which is hard to detect and unblock for the submission.

setError('data.test.long.deep', { type: 'server', mesage: 'errr' })

[joaopaulomoraes]

But is there a way to get away from it? If the user nests more, I understand that he really wants or needs it for some reason. In this case: "what you post is what you get" wypiwyg.

[bluebill1049]

If we use the original RFC proposal then nested is fine.

setErro('root.deep.userError', { type: 'userError' })

because it's single node of object which we need to take care of.

[joaopaulomoraes]

No problem to me :p

[bennettdams]

What I haven't understood yet: Where is the naming (and therefore the typesafe usage) of the error fields (e.g. "random" from errors.root.random) coming from?

For such cases, I right now create variables to save strings that define an error field name.

This is especially important when using RHF with Zod, so you can easily check additional form state to show more specific error messages.

One way to integrate this check is by using Zod's refine method directly on the schema and then refining the inputs.
As an example, when a user wants to update a post, either the "post title" or the "post subtitle" needs to be changed:

const schemaUpdatePost = z
  .object({
    postId: z.string().cuid(),
    title: z.string().min(1).optional(),
    subtitle: z.string().optional(),
  })
  .refine((data) => !!data.title || !!data.subtitle, {
    message: 'Either title or subtitle should be changed.',
    // 🟠 this is the field name to show an error for
    path: ["foo"],
  })

For this error to be integrated with RHF, you would usually set your custom error yourself, something like the example below. Saving the error field name in a variable prevents RHF and Zod to be out of sync:

const generalFormErrorKey = 'general-form-error-key'

const schemaUpdatePost = z
  .object(...)
  .refine((data) => !!data.title || !!data.subtitle, {
    ...
    // 🟠 use variable
    path: [generalFormErrorKey],
  })


// usage with RHF
const {
  register,
  formState: {
    errors: {
      // @ts-expect-error This error was added via Zod, but RHF's type is not aware of it.
      [generalFormErrorKey]: generalErrorRaw,
    },
  },
} = useForm<UserUpdate>({ ... })

As you can see, this is not typesafe right now (-> @ts-expect-error), which mainly comes from the point that RHF is not aware of the field names of the "general" errors.

[bluebill1049]

What I haven't understood yet: Where is the naming (and therefore the typesafe usage) of the error fields (e.g. "random" from errors.root.random) coming from?

The root errors object will be a Record type, which allows the user to insert general errors, such as server errors or errors that the developer wishes not to be blocked during submissions.

useForm<FormValues>()

// declare root error type is optional
useForm<FormValues & { root: { random: FieldError } }>()

One way to integrate this check is by using Zod's refine method directly on the schema and then refining the inputs.
As an example, when a user wants to update a post, either the "post title" or the "post subtitle" needs to be changed:

We maybe able to looking a integration with the resolver, but for now we have to consider all use case include build-in and other resolvers.

[yordis]

@bennettdams how did you end up dealing with Zod at the root? I am trying to contribute to wasmCloud Washboard and I am not sure what the best solution is:

const formSchema = z
  .object({
    authenticators: z.array(authenticatorSchema),
    latticeUrl: z.string().url({message: 'Please enter a valid URL'}),
  })
  .refine(
    (data) => {
      return canConnect({servers: data.latticeUrl});
    },
    {message: 'Could not connect to Lattice', path: ['root']}, // this is not working
  );
  
  
  console.log(form.formState.errors);

Ideally it would be under root key:

{
    "": {
        "message": "Could not connect to Lattice",
        "type": "custom"
    },
    "latticeUrl": {
        "message": "Please enter a valid URL",
        "type": "invalid_string",
        "ref": {}
    }
}

[enesozturk]

I'm not pretty sure @enyelsequeira's questions was the same meaning with this;

• Could this feature solve the issue validating unmounted forms? Imagine I have a dynamic form rendered with tab view. (with Radix Tabs) It's unmounting the inactive tabs. Each tab have different inputs but they have belong to same Hook Form instance. So if I only fill the second tab's inputs and submit form, it doesn't validate the first and third tab's inputs.

Or do you have any solution to this or do you think global errors can implement this use case? @bluebill1049

[amitayt]

Any update on this @bluebill1049 ? as for now

setError('root.serverError', { 
 type: '400',
});

developer needs to manually remove that server error before the next submission could pass,