RFC: Submission APIs

[edmundhung]

RFC: Submission APIs

Status: Proposed

Releated:

• Add a FORM_ERROR export #211
• Allow hiding things from the the submission #239

Background

There are a few common questions when we parse the FormData on the server:

export async function action({ request }: ActionArgs) {
  const formData = await request.formData();
  const submission = parse(formData, { schema });

  // 1. Why should we check the `submission.intent`? Can we skip it?
  if (!submission.value || submission.intent !== "submit") {
    return json(submission);
  }

  // 2. Can we display additional errors on the form if the job is failed?
  await save(submission.value);

  // 3. How do we reset the form if the submission is successful?
  return json(submission);
}

export default function Example() {
  const lastSubmission = useActionData<typeof action>();
  const [form, fields] = useForm({
    lastSubmission,
  });

  // 4. How do we know if the submission is failed?
}

For sure, we have an answer for all the questions above:

export async function action({ request }: ActionArgs) {
  const formData = await request.formData();
  const submission = parse(formData, { schema });

  /**
   * Checking for `submission.intent` is necessary to avoid the server
   * from further processing data that is not ready. As Conform might call the server
   * for different purposes such as validation or list manipulation in cases like:
   * - No client validation
   * - Progressive enhancement (Before JS is loaded)
   * - Async validation
   */
  if (submission.intent !== "submit") {
    // Include a custom status to indicate that the submission is neither error or success
    return json({ status: "idle", submission } as const);
  }

  if (!submission.value) {
    // Send the `error`` status instead if no value is resolved
    return json({ status: "error", submission } as const, { status: 400 });
  }

  const result = await save(submission.value);

  if (!result.successful) {
    return json({
      status: "error",
      submission: {
        ...submission,
        error: {
          // Manipulate `submission.error` with additional messages
          ...submission.error,
          // The error will be populated on `form.errors`
          "": ["Submission failed"],
          // The error will be populated on `fields.address.errors`
          address: ["Address is invalid"],
        },
      },
    } as const);
  }

  // Conform will reset the form for you if the payload is `null`
  return json({
    status: "success",
    submission: { ...submission, payload: null },
  } as const);
}

export default function Example() {
  const actionData = useActionData<typeof action>();
  const [form, fields] = useForm({
    lastSubmission: actionData?.submission,
  });

  // Now we know the status of the submission with `actionData?.status`
}

However, the DX (Developer Experience) is poor. We can have all these documented, but it is still hard to understand what each of these code snippet does, especially for beginners. It could also be error-prone if you are not familiar with the data structure of the submission object.

We need proper APIs to handle the submission on the server.

Proposal

Introducing an additional method to the submission object: submission.reply().

export async function action({ request }: ActionArgs) {
  const formData = await request.formData();
  const submission = parse(formData, { schema });

  /**
   * The submission status could be either "success", "error" or undefined
   * If the status is undefined, it means that the submission is not ready (i.e. `intent` is not `submit`)
   */
  if (submission.status !== 'success') {
    return json(submission.reply(), {
      // You can also use the status to determine the HTTP status code
      status: submission.status === 'error' ? 400 : 200,
    });
  }

  const result = await save(submission.value);

  if (!result.successful) {
    return json(
      submission.reply({
        // You can also pass additional error to the `reply` method
        formError: ["Submission failed"],
        fieldError: {
          address: ["Address is invalid"],
        },

        // or avoid sending the the field value back to client by specifying the field names
        hideFields: ['password'],
      })
    );
  } 

  // Reply the submission with `resetForm` option
  return json(submission.reply({ resetForm: true }));
}

export default function Example() {
  const lastResult = useActionData<typeof action>();
  const [form, fields] = useForm({
    // `lastSubmission` is renamed to `lastResult` to avoid confusion
    lastResult,
  });

  // We can now find out the status of the submission from the form metadata as well 
  console.log(form.status); // "success", "error" or undefined
}

[cevr]

This looks interesting!

I was thinking for hiding/augmenting submissions, maybe you can have two separate apis:
reject/accept for majority of use cases
rejectWith/acceptWith for augmentation

// form schema is username & password
submission.rejectWith(sub => ({ username: sub.username })) // <-- hide password

[codyarose]

Zod strips out unrecognized keys during parsing by default, so .pick/.omit might be of use for avoiding sending certain field values back to the client.

Maybe .reject/.accept could take an optional schema property that would be used to revalidate the data (strip out omitted keys) before returning. You could use the same schema for parsing the submission and omitting properties you don't want to return to the client.

const schema = z.object({
  username: z.string(),
  password: z.string(),
});

export async function action({ request }: ActionArgs) {
  const formData = await request.formData();
  const submission = parse(formData, { schema });

  if (!submission.value) {
    return json(submission.reject();
  }

  const result = await save(submission.value);
  
  if (!result.successful) {
    return json(
      submission.reject({
        formError: ["Submission failed"],
      })
    );
  }

  return json(submission.accept({ schema: schema.omit({ password: true }) }));
  // or .pick to explicitly define what you _do_ want to return
  // return json(submission.accept({ schema: schema.pick({ username: true }) }));
}

[DavoCg]

Hi @edmundhung

I'm using :

@conform-to/react": "^1.0.0-pre.5
@conform-to/zod": "^1.0.0-pre.5

I have a type error for the fieldErrors in reply : Type 'null' is not assignable to type 'string[]'
I would expect being able to pass directly submission.error to fieldErrors if submission.error is defined.

Is it something that is still subject to change ?

Thank a lot for all the work, v1 is very promising

[edmundhung]

It will always reply with the submission error. The formErrors and fieldErrors options are useful mainly if you have some extra works that might failed and you wanna show additional error on the form. (e.g. failed to save the data in a database / failed to send the email)

[DavoCg]

Oh gotcha, I missed that, I'm indeed using this way for my action logic

if (submission.status === "success") {
    const payload = {
      email: submission.value.email,
      password: submission.value.password,
    };

    try {
      const headers = await signin(payload);
      const redirectUrl = await getRedirectUrl(request);
      return redirect(redirectUrl, { headers });
    } catch (err) {
      return json(
        submission.reply({
          formErrors: ["SIGNIN_ERROR"],
        })
      );
    }
  }

Thanks for the quick answer and happy new year

[dogbane-dev]

Hello, playing around with v1-pre5 and looking great! Had a question about the API

Should the submission API allow for the returning of some arbitrary value? For example the result of a mutation.

The type would have to specified as a generic argument to SubmissionResult but then I think could go something like this:

const result = db.user.update(...)
return submission.reply({
  data: result
})

So that we have access to it on the front end (via lastResult)

Or would this not be generally needed?

[edmundhung]

You are free to return anything on your action. Just making sure you pass the submission result to the useForm hook properly.

export function action() {
  // ...
  const data = db.user.update(...)

  return {
    result: submission.reply(),
    data,
  };
}

export default function Example() {
   const actionData = useActionData();
   const [form, fields] = useForm({
     lastResult: actionData?.result,
   })

   // ...
}

[dogbane-dev]

Oh thank you, this didn't occur to me, I was stuck on needing to return submission.reply()

Appreciate it!

[dogbane-dev]

Also- this is a separate issue so I'll leave a separate comment but I am having some issues with the form.dirty property.

I am playing around with v1-pre5 with Next 14 and its been going largely very well, but am running into some unexpected behavior with the form dirty state.

So I have a form populated with some init values (requested on server at page.tsx level) and form.dirty correctly starts as false

What I want to happen is after a successful submission for form.dirty to go back to false - however it always seems to remains true. Even after a router.refresh, which gets the correct fresh default values, it remains dirty.

Using submission.reply({ resetForm: true }) doesn't seem to help me either for whatever reason because the initial values go back to the pre-submission initial values.

Any ideas? Let me know if youd like me to make a minimal repro

Thanks

[dogbane-dev]

Thanks @edmundhung its starting to work as intended after submission! very cool thanks for the feature 👍

One thing Im not so sure about- if you modify a field and then undo your change (so that is back to the default value) should dirty go back to false? Is this a bug?

conform.demo.mp4

[edmundhung]

It is exact why I added the shouldDirtyConsider option. Maybe you forgot to add it to the todos form?

[dogbane-dev]

Oh oops, you were so right. The example repo is working as expected now. I am still having problems with my personal project repo though for some reason despite having added shouldDirtyConsider for sure. Going to look into it more.

Internally what value is it comparing though ? Because from my console logs in my project it seems like form.value and the passed in defaultValue are deeply equal (aside from the $ACTION properties)

[dogbane-dev]

Ah I think I figured it out btw, I peered at the source code and saw you were using JSON.stringify to compare objects - mine was incorrectly returning dirty because the order of the fields was different . My default values were [{ a: 'test', b: 'test' }] whereas the form values had [{ b: 'test', a: 'test' }] - changing the order of the fields fixed it for me but I think this is a bug

[edmundhung]

This is definitely a bug 😅 I will fix that in the next pre-release.

[adaboese]

My grudge with the current design/proposal is that there is no way to communicate successful state message.

I just want a simple way to communicate form-level (as opposed to input level) success/failure of the submission, e.g.

return json(submission.reply({
  status: {
    type: 'success',
    message: 'Password reset link sent to your email'
  },
});

return json(submission.reply({
  status: {
    type: 'error',
    message: 'Incorrect email or password'
  },
});

At the moment, I have to add new top-level properties and it feels like I am working against the framework, e.g.

return json({
  ...submission.reply(),
  message: {
    message: 'Password reset email sent.',
    type: 'success' as const,
  },
});

[adaboese]

You can with the formError, but then what about the success message?

[edmundhung]

There is nothing wrong from sending extra stuff beyond the submission result. This is also the pattern Kent did in the Epic Stack and how he taught in his workshops, like this:

return json({
  // Always send the result in a named property
  result: submission.reply(),
  // So you can add more stuff later if you need
  message: {
    message: 'Password reset email sent.',
    type: 'success' as const,
  },
});

What would you suggest Conform to do for you if it accepts the success message?

[adaboese]

What would you suggest Conform to do for you if it accepts the success message?

I would extend submission.reply to allow status message.

return json({
  result: submission.reply({
    status: {
      message: 'Password reset email sent.',
      type: 'success' as const,
    }
  }),
});

[edmundhung]

Yeah, you mentioned that already. How will you consume it in the route component? If you pass the message as I mentioned:

export function action() {
  // ...

  return json({
    // Always send the result in a named property
    result: submission.reply(),
    // So you can add more stuff later if you need
    message: {
      message: 'Password reset email sent.',
      type: 'success' as const,
    },
  });
}

export default function Component() {
  const actionData = useActionData();
  const [form, fields] = useForm({
    lastResult: actionData?.result,
  });

  // you can access the message with `actionData?.message`
}

Any difference will it make with your suggestion on the route component side?

[adaboese]

The difference is that the convention is enforced at the library level, which makes it one less thing to think about.

I already pass form.context to FormProvider.

const SignUpForm = () => {
  const fetcher = useFetcher<typeof action>();

  const [form, fields] = useForm({
    lastResult: fetcher.data?.submission,
    onValidate({ formData }) {
      return parseWithZod(formData, { schema: FormDataZodSchema });
    },
  });

  useEffect(() => {
    // We redirect user to this page after sign out, so we need to reset PostHog
    posthog.reset();
  }, []);

  const submitting = fetcher.state === 'submitting';

  return (
    <FormProvider context={form.context}>
      <fetcher.Form
        method="post"
        {...getFormProps(form)}
      >
        <Form.Layout>
          {fetcher.data?.message ? (
            <Form.TopMessage type={fetcher.data.message.type}>
              {fetcher.data.message.message}
            </Form.TopMessage>
          ) : null}

That is, in an ideal world I would not need:

         {fetcher.data?.message ? (
            <Form.TopMessage type={fetcher.data.message.type}>
              {fetcher.data.message.message}
            </Form.TopMessage>
          ) : null}

and could just derive if there is such a message from form.context.

export const TopMessage = () => {
  const context = useFormContext();

  if (!context.statusMessage) {
    return null;
  }

  return <div className={formMessage({ type: context.statusMessage.type })}>{context.statusMessage.message}</div>;
};