GrSchemaForm

Apart from the grid of columns. The orchestration is given by GrForm, the wrapper and the accessibility by GrFormField, the sections by GrFormSection, and the input by the controls of the core. Hence the main property: a generated form looks and behaves exactly like a hand-written one — the same texts of errors, the same keyboard, the same theme.

The grid is the exception, because the core has no columns: GrFormField answers for one field, and the layout between fields is built by everyone with markup of their own.

What fits into the rules of the core goes into them: required, lengths, bounds, email, url, files. What is expressible from the schema but not from the rules — integer, multipleOf, strict bounds, uniqueness, “has to be ticked” — becomes a local validator. Everything else — refine, cross-field conditions, branches — travels into one check by the schema itself, which remains the source of truth.

The message is taken from the schema only if the author wrote one. Otherwise the text is given by the resolver of the core — with the locale of the core.

compiledRules in defineExpose answers the single question such a package gets asked in production: why is this field not being validated.

A schema describes the data rather than the interface. Everything to do with the look lives in uiSchema and is addressed by a template path (items.*.qty) rather than by the path of a particular row:

const ui: GrUiSchema = {
  layout: {
    columns: 2,
    sections: [
      { id: 'main', title: 'Main', fields: ['email', 'nick'] },
      { id: 'more', title: 'More', fields: ['*'] },
    ],
  },
  order: ['type', '*'],
  fields: {
    'bio': { widget: 'gr:textarea', span: 'full' },
    'items.*.qty': { label: 'Quantity' },
    'company': { when: { path: 'type', eq: 'company' } },
  },
}

A section draws exactly its own fields, and in their order. '*' expands in its place into the remainder — the root fields that no section has named — and follows order. A field that has not landed in any section, when there is no '*' anywhere, is not drawn: sections are both the layout and the selection. Without sections order sets the order of the whole form. Hidden (hidden) and conditional (when) fields behave inside a section the same as without one.

A field hidden by a condition does not take part in the validation: otherwise the submission would be blocked by the requiredness of a field that is not on the screen.

The registry maps a node of the model to a component: a string with format: email is a GrInput[type=email], up to five options a GrRadioGroup, more than that a GrSelect, an array of strings a GrInputTag, an array of objects a repeater.

The default set is deliberately narrow: every entry is a component in dependencies, that is, its CSS in the bundle of every consumer of the form. Sliders, ratings and colour pickers live in extendedRenderers, and the date pickers in ./renderers/chrono; both are connected explicitly, see ../renderers.md.

A 422 answer is parsed from Laravel, JSON:API and RFC 7807, the path is normalised (items[0].name → items.0.name), the error sits on the field and is removed by the very first edit. An error on a field the form does not draw is shown in a summary at the top: “the save did not go through, and why is nowhere” is the worst possible outcome.

The delivery method, the payment type, the kind of document: the set of fields depends on the value of one key. The form draws a switch of the options (up to five a GrRadioGroup, beyond that a GrSelect) and the fields of the chosen branch under it.

The discriminator is not drawn as a separate field in the process: it is governed by the switch, and a second field with the same name would argue with it over the value.

A change of branch rewrites the value: the shared keys are kept, foreign ones are discarded, and the discriminator is set. Keeping foreign ones is not allowed — the schema will complain about them; resetting everything would lose a shared field such as a note that every option has.

It is drawn by GrSchemaUnionField. A branch is a structure rather than a control, and that is why it is not in the registry of renderers: an entry in the registry would give one GrFormField with one label for the whole group.

The tail is drawn by GrSchemaAdditionalFields. An additionalProperties with a schema of the value (or a catchall in zod) gives a list of “key — value” pairs: the name is entered by the user, and the value is drawn by an ordinary control from the schema. As the tail of the object rather than as a field among fields: a pair has neither a place in the schema, nor an entry in uiSchema, nor an order among the declared fields.

An additionalProperties: true without a schema of the value gives no tail: the keys are allowed, but the schema did not say what to draw the value with.

A pair has no visible label — the field of the key plays that role — so the name for the control of the value is given by the key itself, and it moves along with a rename. The details and the way to name the field from the outside (the ariaLabel of GrSchemaField) are in the accessibility document.

• there is no form builder by dragging here and there will not be — that is a product rather than a component of a library;
• the package does not replace server-side validation. A schema on the client saves a request and hints earlier, but the decision is made by the server;
• conditions — if/then/else, not — are not unfolded by the form. Such nodes are marked for a full check by the schema: the error will be shown, but the form will not build a field for every outcome. A branch by a discriminator (oneOf with a shared const, z.discriminatedUnion) it does build — see “A branch” below;
• a union without a discriminator does not branch: there is nothing to choose the option with, and the node goes into the full check with a warning.