Forms, switch product
announcements

GolemUI v2.3.0: convert a gui.* form to a JSON form definition

GolemUI v2.3.0 is released. It adds one function, toJsonFormDefinition, which converts a form written with the TS API (gui.*) into a JSON form definition. The release also fixes an onBlur handler in the states of a widget.

GolemUI reads a form in two formats. The gui.* API is code: it has selectors, automatic labels, typed validators and functions. A JSON form definition is data: you can store it in a database, send it from a server, and check it with the published JSON Schemas or with the MCP tools. Before 2.3.0, the library had no function to get the second format from the first.

toJsonFormDefinition takes the formDef, the formSelectors and the formConfig that you pass to the form component. Only formDef is required:

import { gui, toJsonFormDefinition } from '@golemui/gui-shared';
const formDef = [
gui.inputs.textInput('email', {
label: 'Email',
validator: { required: true, format: 'email' },
}),
gui.inputs.dropdown('country', {
onChange: () => 'countryChanged',
items: ['US', 'CA', 'MX'],
}),
gui.actions.button({
uid: 'save',
label: 'Sign up',
onClick: (data) => save(data),
}),
];
const { formDefinition, diagnostics } = toJsonFormDefinition({ formDef });

The function runs the same builder as the form component. So the JSON form holds what the builder adds to your widgets: the automatic label Country, the automatic placeholders, and the type of each validator:

{
"$schema": "https://golemui.com/schemas/form.schema.json",
"form": [
{
"kind": "input",
"type": "textinput",
"uid": "email",
"path": "email",
"label": "Email",
"validator": { "type": "string", "required": true, "format": "email" },
"props": { "placeholder": "email" }
},
{
"kind": "input",
"type": "dropdown",
"uid": "country",
"path": "country",
"label": "Country",
"on": { "change": "countryChanged" },
"props": { "items": ["US", "CA", "MX"], "placeholder": "country" }
},
{
"kind": "action",
"type": "button",
"uid": "save",
"label": "Sign up",
"on": { "click": "save_click" }
}
]
}

The values that selectors set, and the states of formConfig, are in the JSON form too. @golemui/gui-shared has the function, and it needs no other package.

JSON cannot hold a function. A handler that only returns an event name, such as onChange: () => 'countryChanged', keeps that name. Any other handler gets a new event name, made from the widget and the event: the onClick function of the button save becomes save_click. Your formEvent handler gets the event, and for a click event.data is the form data, the same value that the function took:

function handleFormEvent(event: FormEvent) {
if (event.name === 'save_click') {
save(event.data);
}
}

The name comes from the uid of the widget, or from its path, label or type when it has no uid. It does not come from the position of the widget, so it stays the same when you add a widget before it. See Event names.

A form that JSON cannot hold completely does not make the conversion throw. diagnostics has one entry for each difference, with a severity, a code, a message and a JSON pointer into the form definition. For the form above, it has one entry:

[
{
"severity": "warning",
"code": "event-handler",
"message": "The onClick handler of the button \"save\" is a function, and JSON cannot hold a function. The JSON form holds the event name \"save_click\". Handle this event in the formEvent handler of the form component.",
"pointer": "/form/2/on/click"
}
]

error means that a widget is not in the JSON form, for example a display widget that is a render function. warning means that the widget is in the JSON form, and a part of it needs work by hand, for example a widget that is a callback. info is a note. So a test can keep a converted form complete:

import { toJsonFormDefinition } from '@golemui/gui-shared';
import { expect, it } from 'vitest';
import { signUpFormDef } from './sign-up.form';
it('converts the sign-up form with no error', () => {
const { diagnostics } = toJsonFormDefinition({ formDef: signUpFormDef });
expect(diagnostics.filter((entry) => entry.severity === 'error')).toEqual([]);
});

Five values of formConfig are not part of a JSON form: functions, dependencies, validateOn, itemRenderers and widgetLoaders. Each one gives a host-config entry, and you pass it in the config of the form component, next to formDef.

The conversion builds the form in the same way as the form component. So it calls each widget callback one time, and each event handler that has no parameters one time. The function does not check the result with the JSON Schema of a form: open the file in an editor that reads JSON Schemas, or call json_validate_form_definition.

See Convert a gui.* form to JSON for the table of what the JSON form holds, every diagnostic code, and the form config.

An onBlur handler in the states of a widget was never called. The builder took it as a prop with the name onBlur.register, and a blur sent no event. Now it is a handler, as onChange, onClick, onLoad and onFilter in a state already were:

gui.inputs.textInput('email', {
label: 'Email',
states: {
register: { onBlur: () => 'checkEmailIsFree' },
},
});

When the state register is active, a blur of the email input sends checkEmailIsFree to your formEvent handler. In a JSON form, the handler is the key "blur.register" of on.

  • Upgrade every @golemui/* package to 2.3.0 at once.
  • onBlur handlers in widget states run now. If a widget has one, check that you want it to run. A handler that has no parameters also runs one time while the form is built, to give the event name.

The full list of changes is in the changelog.

Previous GolemUI v2.2.1: button handlers that run on click, and forms that follow a new config
Next You are at the latest post