# Submit and starting values

> Refuse a submit, act after one, and give the form its starting value.

Source: https://forms.lunarhue.dev/solid/writing-plugins/submit

## Refusing a submit

A throw or a rejected promise in `onSubmit` is a bug. It goes to
`onPluginError` and the submit carries on. To stop a submit on purpose, return
`refuse`, directly or from the promise. The definition's `onSubmit` isn't
called, the submission ends `"invalid"` as it does when validation fails, and
`onSubmitted` gets it. Set a form error first so the user sees why:

```ts
import { definePlugin, refuse } from "@lunarhue/forms-core/plugins";

const captcha = definePlugin({
  name: "captcha",
  setup: (ctx) => ({
    async onSubmit() {
      try {
        const token = await fetchToken();
        ctx.write(() => ctx.store.root.at("token").setValue(token, { edited: false }));
        return undefined;
      } catch {
        ctx.store.root.setErrors({ message: "We couldn't check the form. Try again." });
        return refuse;
      }
    },
  }),
});
```

`refuse` returned directly stops the plugins after this one from running their
`onSubmit`. Returned from a promise it can't, since every `onSubmit` started
when the submit did. A plugin doesn't know the form's error type, so the error
it sets must fit the form's `mapError`, if it has one.

## After a submit

`onSubmitted(submission, input)` runs once a submit ends. `input` is the form
value the definition's `onSubmit` got as `ctx.input`, read when validation
finished, so it holds edits the user made while validation ran. It is
undefined when the submit ended `"invalid"`. A submit that a reset stops never
reaches `onSubmitted`.

To make a value the baseline, call `ctx.baseline.move(path, value, keep)`.
Each array in `value` pairs its items with the current items by index. `keep`
changes that for one array, by its stable path: return `true` to keep the old
baseline's pairing, or a list of item keys to pair with. `baselineOnSubmit`
passes the keys each array had when the value was sent.

## Starting values

A plugin can give the form its starting value with `initial`. It runs before
the store is made, gets the value the store would start from, and returns the
value to start from instead, or undefined to keep it:

```ts
// Starts the form from a value the server and the client both have.
const startFrom = (value: Profile) => definePlugin({ name: "start", initial: () => value, setup: () => ({}) });
```

The store, its baseline and its server snapshot all start from that value.
Nothing is written, so the form isn't dirty and no plugin sees a record. When
several plugins have `initial`, each gets the value the one before returned,
so the last one in the list wins.

The value replaces the store's starting value whole. It isn't merged with a
schema plugin's defaults the way `defaultValues` is, though `initial` gets
those merged defaults and can merge into them itself. A value that differs
between server and client, such as one read from browser storage, makes
hydration fail. Read those in `onActive` and write them with `ctx.write`, as
`persist` does.

`attach` can return an `initial` hook too. It gets the value at the part's
path when the part attaches and returns the value to keep there, which is how
`mask` cleans a field's starting value. The store keeps it with no write
record, and the baseline moves with it while the field isn't dirty, so the
form doesn't start dirty.
