GrForm

A field is required if it has a required rule or if the GrFormField itself carries the required prop. Both sources take part both in the * marker and in the validation: the second one used to draw the asterisk while the submit went through with an empty field.

A field with no rules is in that case given an implicit { required: true } — with the same message from the locale as an explicit rule.

resetFields() returns the model to the snapshot. The snapshot is taken on mounting, so an edit form needs to retake it after the data has loaded:

const form = ref<GrFormInstance>()

const data = await api.load()
Object.assign(model, data)
form.value?.setSnapshot()

Without that the “reset” would return the empty object the model was before the server answered. resetFields(names?) can also do a pointed reset; a key that is not in the snapshot is deleted rather than turned into undefined. The exception is methods: they do not enter the snapshot by construction, and deleting them would mean breaking the model (see “The model may be someone else’s”).

isDirty compares the model with the snapshot, and isValid means “there are no known errors” — until the first validate() that is not yet “the form is valid” but “nobody has checked”. Both are available through the ref of the form and in the slot props.

The disabled of the form travels into the context of the field and further into the controls: “switch everything off for the duration of the submission” no longer requires walking the controls one by one. The prop of a control and the prop of a field add to it by “or” — the way it is already done with readonly.

The submit button usually stands below the fields rather than in a GrFormField, so GrButton type="submit" reads the disabled of the form itself and is switched off together with it — a “switched-off” form cannot be submitted a second time. The other buttons (type="button", type="reset") are left alone: “Cancel” and “Reset” stay working. A switched-off form also ignores the submit event itself — Enter in a field and a button that is not a GrButton.

reserveMessage on the form holds space for the message line under all of its fields: errors on submit do not shift the form, a dialog or a fixed-height panel. A field with a reserveMessage of its own decides for itself. The reserve is one line; several errors on a field grow below it. The details are in GrFormField.md.

<template>
  <GrForm :model="model" :rules="rules" reserve-message>
    <GrFormField label="Recipient" name="name">
      <GrInput v-model="model.name" />
    </GrFormField>
  </GrForm>
</template>

The constraints on a file are described where the rest of the rules are — with the file rule:

const rules: GrFormRules = {
  contract: [{
    required: true,
    file: { accept: '.pdf,application/pdf', maxSizeMb: 1 },
  }],
}

The rule has no checks of its own at all: it assembles the same validators from ../file-validation.md that GrFormFile and v-dropzone run on a choice and on a drop. The text of the error is therefore one as well — it comes from the validator and is localised with its gr.fileValidation.* key rather than turning into a separate “invalid file”. rule.message overrides it, as with any other rule.

File and File[] values are checked; everything else the rule lets through — it must not invent a verdict for a string. Emptiness is dealt with by required.

If there are several problematic files, the field shows the first one — a form field has one error line, and files are no exception here. A detailed breakdown per file remains the job of GrFormFile.

GrFormFile itself does not change in the process. The constraints on the field (accept, limit, validators) are quick feedback: a bad file does not reach the model at all. The rule of the form is a guarantee at submit: it is visible to validate(), enters the invalid event and takes part in the scroll to the first error. No duplication appears on the screen: what the field did not let into the model is not shown to the rule of the form. The typical division is the constraints in rules and accept on the field as a filter for the choice dialog.

While a rule is travelling to the server, the field is marked aria-busy and shows a string from the locale (gr.form.validating) instead of the old error: the error belonged to the previous value, and keeping it on the screen means lying about the current one.

The list of fields being checked is available as validatingFields — in the expose and in the slot props.

Overlapping runs of one field are settled by a generation counter: the result of the last run applies, and a run that was displaced gives the caller the verdict of the one that displaced it, having waited for it. validate() and submit therefore cannot slip through on a value nobody has checked yet.

clearValidate() and resetFields() cancel the checks in flight: their answer belongs to the state before the reset, it will not reach the cleared form, and the field stops being counted as under validation at once, without waiting for the server.

model is typed with a generic rather than as a dictionary: a model is sometimes an object of someone else’s library — Inertia’s useForm, a store — where methods of its own lie beside the fields. It goes in as it is, with no as unknown as, and submit gives it away with the same type.

const form = useForm({ email: '', password: '' })

<GrForm :model="form" :rules="rules" @submit="form.post('/login')">

The form addresses only the names declared by fields (GrFormField name), so everything else in the object does not concern it. Two consequences are worth knowing in advance:

• resetFields() returns the values of the fields and does not touch the methods. The snapshot is built as a clone, and a clone drops functions — without a separate guard “not in the snapshot” would mean “delete”, and the reset would sweep post, reset and errors off the object. The external form’s own reset (form.reset()) remains yours in the process: it knows about its service fields, and GrForm does not;
• isDirty is computed over the whole object. An external form has reactive fields of its own beside the data ones (processing, errors), and the form will see their changes too. If a “the user edited the data” flag is needed, take it from the external form itself.

Rules are sometimes promises, so validate() always returns a Promise, and submit is emitted after it resolves. In tests a single nextTick() is not enough:

await wrapper.find('form').trigger('submit')
await flushPromises() // not nextTick: the rules may have gone to the server
expect(onSubmit).toHaveBeenCalled()

• submit(model) — only when the form is valid;
• invalid(errors) — a map of messages when the submit did not go through. Without it “the form is invalid” and “nothing happened” look the same;
• validate(name, valid, message) — the result for a single field.

Imperatively: validate(), validateField(name, trigger?), clearValidate(), resetFields(), setSnapshot(), scrollToField(name), plus isDirty, isValid, validatingFields.

The type for a ref is GrFormInstance rather than InstanceType<typeof GrForm>: the form is generic, and such a component compiles into a function, which has no constructor.

const form = ref<GrFormInstance>()
form.value?.resetFields()

The rules and their messages — ../file-validation.md for files and GrForm/validation.ts for the rest; the engine is public (runFieldRules, createGrFormMessageResolver), and GrPromptDialog uses the same one.