GolemUI v2.1.2: one set of ids per form, and a lighter form validator
GolemUI v2.1.2 is released. It is a patch release after v2.1.1 with two changes: forms on the same page stop sharing DOM ids, and the form validator in @golemui/gui-mcp gets much smaller and faster. Most apps need no change. If your CSS or your tests select GolemUI fields by id, read Upgrading first.
Two forms, two sets of ids
Section titled “Two forms, two sets of ids”In 2.1.1, a widget built its DOM ids from its uid alone. A login form and a newsletter form on the same page, each with an email field, both rendered an input with id="email-textinput". The browser resolves an id to the first element that has it, so the label, hint and error of the second form pointed at the input of the first one. A click on the second label focused the wrong field, and a screen reader read the wrong hint.
Now every DOM id inside a form starts with the form’s formName: the control, its label, hint and errors, the popups, the list options, the tab and accordion parts, and the widget’s host element. The two forms below both have an email field. Click the Email label of the second one, and the cursor goes to the newsletter field:
Give each form a name to know its ids:
<GuiForm config={{ formDef: login, formName: 'login' }} /><GuiForm config={{ formDef: newsletter, formName: 'newsletter' }} />The inputs get the ids login-email-textinput and newsletter-email-textinput. A form without a formName generates one, so its ids are scoped too, but you can’t predict them. Set a name when the server renders the form, and when your CSS or tests select GolemUI elements by id. See formName.
Only DOM ids take the prefix. The widget uid stays as it is, and so do the store, the form events, the after references and the data-cy attributes. Tests that select by data-cy keep working.
In GolemUI Components
Section titled “In GolemUI Components”Every element of GolemUI Components has a new id-prefix attribute (the idPrefix property). GolemUI Forms sets it to the form’s formName. An element used on its own takes no prefix, so its ids don’t change. Use it when two elements on one page share a uid:
<gui-textinput uid="email" id-prefix="billing" label="Email"></gui-textinput><gui-textinput uid="email" id-prefix="shipping" label="Email"></gui-textinput>The label, hint, errors and every ARIA reference of each element follow its own prefix.
In custom widgets
Section titled “In custom widgets”The hooks, composables and adapters now give your custom widgets two more values: domId, the widget uid behind the form’s name, and formName. Use domId for the ids your widget renders, and pass formName as idPrefix to the GolemUI Components elements inside it:
const { domId, value, onValueChanged } = useInputWidget<number, RatingProps>( widget,);
return ( <div className="rating" id={domId}> {/* … */} </div>);In Angular and Lit, read adapter.domId and adapter.formName. See DOM ids.
A lighter form validator in gui-mcp
Section titled “A lighter form validator in gui-mcp”@golemui/gui-mcp checks form definitions: the json_validate_form_definition tool, the validate-json command and validateFormDefinition in your own code. In 2.1.1 its validator was one module of 4.73 MB minified. Now each widget type has its own module.
| What | Minified | Gzipped |
|---|---|---|
| 2.1.1: the validator module | 4.73 MB | 362 KB |
2.1.2: validateFormDefinition | 2.38 MB | 171 KB |
| 2.1.2: lazy entry, everything a typical form loads | 305 KB | 48.5 KB |
- A lazy entry for browsers.
@golemui/gui-mcp/json/lazyhasvalidateFormDefinitionAsync, which loads only the validators of the widget types the form uses and returns the same result asvalidateFormDefinition. The typical form in the table has six widgets.preload()starts loading the common validators before the first form arrives. - Much faster. The old validator took time exponential in the depth of the layouts. A 4KB issue tracker form took 1.1s to validate. The test suite’s 5,099 forms now validate in 108ms instead of 39s.
- Clearer errors. A layout with an empty
childrenarray gets aminItemserror instead of a generic one. A repeatertemplatethat is not a built-in layout, such as a chunk reference, a custom widget or an input, gets apositionerror that says so.
import { preload, validateFormDefinitionAsync,} from '@golemui/gui-mcp/json/lazy';
preload(['textinput', 'select']);
const result = await validateFormDefinitionAsync({ formDefinition: myForm });if (!result.valid) console.error(result.errors);@golemui/gui-mcp/json stays synchronous and bundles anywhere, Cloudflare Workers included. Neither entry compiles code at runtime, so both work under a strict Content Security Policy. See the gui-mcp README.
Upgrading
Section titled “Upgrading”- Upgrade every
@golemui/*package to 2.1.2 at once. - Selectors by id: CSS, tests or scripts that select a Forms widget by id, such as
#email-textinput, no longer match. Set aformNameand add it to the selector (#signup-email-textinput), or select bydata-cyor by class. - Your own ARIA references: an
aria-describedby,aria-controlsor<label for>outside the form that points at a GolemUI id needs the prefix too. - Custom widgets: a widget that renders
id={uid}still works, but two forms that use it share that id. Switch todomId. - gui-mcp: nothing to change. To validate forms in a browser, switch to
@golemui/gui-mcp/json/lazy.
The full list of changes is in the changelog.