GolemUI v2.2.1: button handlers that run on click, and forms that follow a new config
GolemUI v2.2.1 is released. It is a patch release after v2.2.0, with no new features. One fix changes how a button onClick handler runs, so read Upgrading if your forms have buttons with handlers.
Button handlers run only on click
Section titled “Button handlers run only on click”In 2.2.0, the form called every button onClick handler once while it built the form, with undefined, to check if the handler returned an event name. So onClick: (data) => api.save(data) called api.save(undefined) before the user clicked anything. A handler such as (event) => event.data threw there, and the form was not built. On click, the handler got only the form data.
Now a handler that declares a parameter runs only on click. It gets the form data first and the event second, (data, event). The event is the same one that onChange gets, with update, callback and, inside a repeater row, row. So one button handler serves every row of a repeater:
gui.actions.button({ label: 'Make lead', onClick: (data, event) => { if (!event.row) { return; } const name = data.team[event.row.index]?.name || 'This member'; event.callback({ type: 'OVERRIDE_WIDGET_PROP', payload: { uid: 'leadResult', prop: 'text', value: `${name} leads the team.` }, }); },});Click Make lead in a row:
A handler with no parameters, such as onClick: () => 'saved', works as before. The form calls it while it builds the form, and each click sends saved to your formEvent handler. A string that a handler with parameters returns is ignored now, and the form logs a warning. See onClick vs. the other hooks.
A new config gives the same result in every framework
Section titled “A new config gives the same result in every framework”When your app passes a new config object, the form starts again from it. For example, a page that shows one customer at a time passes the config of the next customer. Some frameworks did not follow the new config completely. Now React, Angular, Vue and Lit all do the same:
- React and Vue use the
formNameof the new config, so the form id and the widget ids change with it. Before, they kept the name of the first config. - Vue follows the translator of the new config. Before, it listened to the language changes of the old translator.
- Angular starts the form one time for one new config. Before, it started two times, so a middleware saw two starts and
formHealthsent two values. - Angular and Lit ignore the blur of an input that the new config removed. Before, when the focus was in a field during the change, that blur marked the field of the new form as touched. A required field then showed its error before the user did anything.
- Lit and React give a
setData,setMetaorsetHealthcall made right after the new config to the new form. In Lit, this is a call between the assignment ofconfigand the start. In React, it is a call from auseEffectof the component that renders the form:
const formRef = useRef<FormComponentHandle>(null);const config = useMemo( () => ({ formDef, formName: `customer-${customer.id}`, data: customer }), [customer],);
useEffect(() => { // Fills in the draft of the new customer, not of the previous one. formRef.current?.setData(loadDraft(customer.id));}, [config]);
return <GuiForm ref={formRef} config={config} />;Before, the ref got the handle of the new form one render later, so this call reached the old form. See Runtime Methods for the cases where a call still comes too early.
Repeaters keep the keyboard focus
Section titled “Repeaters keep the keyboard focus”When your app removes rows with setData, for example after it polls the server, the row with the keyboard focus can disappear. Before, the focus then went to the page body, and a keyboard user had to start again from the top of the page.
Now the focus moves to the same element of the new last row. When no row is left, the Add button gets the focus. A focus on a Remove button does not move, so a held Enter key removes only one row. See Keyboard focus after a removal.
The first formHealth value
Section titled “The first formHealth value”The first formHealth value is the health of the started form: ok, or the error of the start, such as an error in the definition. Two cases did not follow this:
- Lit sent
{ status: 'ok' }first and the definition error after it. An app that waits for the first value showed the broken form. - Angular replaced the health of the start with the health of a
setHealthcall made before the start. A definition error was never sent and never logged. Now the health of the start comes first, and the health of the call comes next.
Other fixes
Section titled “Other fixes”$login templates and i18n params.{{ $log($form.total) }}gave error code 40. Now it logs the value and shows it, as$logdoes in awhenrule. An i18n param such as'$log($form.total)'is an expression now, not text. See What expressions can do.- Repeated uids in gui-mcp. The form validator returned valid for two widgets with the same uid. The form then failed with code 21, or, inside a repeater template, showed only one of the two widgets with no message. Now the validator gives an error with the keyword
duplicateUid, on the second widget. Seejson_validate_form_definition. - A moved
gui-formin Lit keeps its selected tab and its open accordion sections. Before, they went back todefaultOpen.gui-tabsalso scrolls its tab strip back to the selected tab after a move. - A failed start in Lit. When a middleware throws while the form starts with a new config, the form now renders the new form. Before, the widgets of the old form stayed.
Upgrading
Section titled “Upgrading”- Upgrade every
@golemui/*package to 2.2.1 at once. - Button handlers that return an event name: a handler with a parameter, such as
onClick: (data) => 'saved', no longer sendssaved. Remove the parameter:onClick: () => 'saved'. - Button handlers with no parameters: the form still calls a handler such as
onClick: () => { api.save(); }while it builds the form. To run it only on click, declare thedataparameter, also when you do not read it:onClick: (_data) => { api.save(); }. - gui-mcp: a definition with a repeated uid is now invalid. Give one of the two widgets another
uid.
The full list of changes is in the changelog.