Submit and starting values
Refuse a submit, act after one, and give the form its starting value.
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:
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:
// 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.
Last updated