J3W1 / DESIGN SYSTEM
Form builder
A bounded reference editor for five canonical field kinds, with keyboard ordering, local preview and explicit JSON definition import and export.
draft · LIGHT DOM · 1.1.0
Light DOM retains static content, native semantics, label relationships and host composition without duplicating controls. The bounded form-builder contract remains draft; D-021 has not been promoted.
Live variants
default
No fields yet. Choose a type and add your first field.
Preview
Definition changes clear preview values. Review validates required values and choices.
Try the local workflow
Values stay in this page. Reset clears them. No save request is sent.
Transfer definition
Schema version 1 accepts at most 64 KiB and 20 fields. Invalid imports leave the current definition unchanged. Export excludes entered preview values.
The bounded form editor requires JavaScript. Its definition is plain JSON with stable field IDs, labels, help, required flags and explicit option IDs.
<j3w1-form-builder id="example-form-builder-default"><section class="form-builder form-tool" data-builder="" hidden="" aria-label="Form definition editor">
<div class="form-builder-editor"><label for="example-form-builder-default-builder-kind">Field type<select id="example-form-builder-default-builder-kind" data-kind="" name="builder-kind"><option value="text">Text</option><option value="textarea">Textarea</option><option value="select">Select</option><option value="checkbox">Checkbox</option><option value="radio">Radio</option></select></label><button class="button" type="button" data-add="">Add field</button><label for="example-form-builder-default-builder-density">Preview density<select id="example-form-builder-default-builder-density" data-density-choice="" name="builder-density"><option value="compact">Compact</option><option value="comfortable">Comfortable</option></select></label></div>
<p data-builder-status="" role="status"></p><p data-empty="">No fields yet. Choose a type and add your first field.</p><ol class="form-builder-list" data-field-list=""></ol>
<form class="form-builder-editor" data-editor="" novalidate="" hidden=""><h2>Edit selected field</h2><label for="example-form-builder-default-builder-label">Field label<input id="example-form-builder-default-builder-label" name="label" maxlength="120" required=""></label><label for="example-form-builder-default-builder-help">Field help<textarea id="example-form-builder-default-builder-help" name="help" maxlength="400"></textarea></label><label for="example-form-builder-default-builder-required"><input id="example-form-builder-default-builder-required" name="required" type="checkbox">Required field</label><label for="example-form-builder-default-builder-options" data-options-label="">Options JSON<textarea id="example-form-builder-default-builder-options" name="options" rows="6" maxlength="65537" spellcheck="false"></textarea></label><p>Edit option IDs and labels as JSON. Keep each ID when changing its label. Select and radio fields need 1–20 options.</p><div class="form-tool-actions"><button class="button" type="submit">Save field definition</button><button class="button button-secondary" type="button" data-cancel="">Cancel edit</button></div></form>
<h2>Preview</h2><p>Definition changes clear preview values. Review validates required values and choices.</p><div data-preview=""><section class="admin-form form-tool" data-workflow="builder-preview" hidden=""><h2 class="admin-form-title">Try the local workflow</h2><p>Values stay in this page. Reset clears them. No save request is sent.</p><form novalidate=""><div class="alert alert-danger form-tool-summary" data-errors="" role="alert" tabindex="-1" hidden=""></div><fieldset class="form-tool-fields" data-fields="" aria-label="Enter values"></fieldset><div class="form-tool-actions"><button class="button" type="submit" data-event="submit">Review values</button></div></form><table data-review="" class="table" hidden=""></table><p data-status="" role="status" tabindex="-1" id="example-form-builder-default-builder-preview-field-8-workflow-status"></p><div class="form-tool-actions"><button class="button" type="button" data-event="edit" hidden="">Edit values</button><button class="button" type="button" data-event="confirm" hidden="">Simulate save</button><button class="button" type="button" data-event="complete" hidden="">Complete simulation</button><button class="button" type="button" data-event="reset">Reset values</button></div></section></div>
<h2>Transfer definition</h2><p>Schema version 1 accepts at most 64 KiB and 20 fields. Invalid imports leave the current definition unchanged. Export excludes entered preview values.</p><div class="form-builder-editor"><label for="example-form-builder-default-builder-json">Definition JSON<textarea id="example-form-builder-default-builder-json" data-json="" rows="10" spellcheck="false" maxlength="65537" name="builder-json"></textarea></label></div><div class="form-tool-actions"><button class="button" type="button" data-export="">Show definition JSON</button><button class="button button-secondary" type="button" data-download="">Download definition</button><button class="button button-secondary" type="button" data-import="">Import definition JSON</button><button class="button button-secondary" type="button" data-reset="">Reset builder</button></div></section><p>The bounded form editor requires JavaScript. Its definition is plain JSON with stable field IDs, labels, help, required flags and explicit option IDs.</p></j3w1-form-builder>Install and register
Use the exact version. If npm publication is pending, install the release tarball from the installation guide.
npm install --save-exact @j3w1/ui@1.1.0import '@j3w1/ui/tokens.css';
import '@j3w1/ui/styles/form-builder.css';
import '@j3w1/ui/register/form-builder';Insert the maintained markup above after loading these imports. Its native children provide accessible names and form behavior; the empty custom tag alone does not create a control.
Copy the complete implementation
npx --package=@j3w1/ui@1.1.0 j3w1-ui copy form-builder --out ./vendor/j3w1/form-builderThe CLI verifies every file before writing and refuses overwrites. Serve the output over HTTP and open index.html. Keep its modules, CSS, tokens and licence notices together.
Public API
attributes
| Name | Type / signature | Meaning |
|---|---|---|
disabled | CustomEvent | Disable the native controls owned by this instance. |
loading | CustomEvent | Mark the primary control busy and prevent duplicate activation. |
properties
| Name | Type / signature | Meaning |
|---|---|---|
disabled | boolean | Delegates disabled state to native children. |
name | string | Native control name; application form keys remain explicit. |
definitionJson | string | Validated bounded definition JSON; entered preview values are excluded. |
methods
| Name | Type / signature | Meaning |
|---|---|---|
refresh | (): void | Reconnect behavior after replacing native child structure. |
focus | (options?: FocusOptions): void | Focus the first usable native control. |
exportDefinition | (): string | Export the canonical bounded definition without entered preview values. |
importDefinition | (json: string): boolean | Validate and import a complete definition without partial mutation. |
events
| Name | Type / signature | Meaning |
|---|
Dependencies and verification
Registered components: none. Style dependencies: button, text-field, textarea, select, checkbox, radio-group, alert, table, admin-form, field, switch.
Package presence establishes an available implementation. Actual passes depend on the tested artifact and environment. Read specification execution evidence; read packed-consumer evidence; inspect the complete state matrix.
Full implementation manifest, API and token dependency closure
Canonical specification
Purpose
Build a bounded reference form from text, textarea, select, checkbox and radio fields in the interactive builder. D-021 remains proposed. This draft component does not promote new tokens, roles, profiles or native ports.
Anatomy
Each field has a stable ID, label, help, required flag and, for select/radio, stable option IDs and labels. Add and remove fields, edit definitions and move them with explicit Move up / Move down buttons. Saving an edit validates the complete proposed definition before replacing the current one.
The preview uses the same canonical field renderer and validation model as the validation-recovery composition. Changing a definition clears preview values and errors. Merely moving focus or typing a preview value does not change the definition. Preview state is separate from schema state.
States
The empty state displays an explanation and an add action. An invalid import or definition edit reports a corrective message and leaves the current definition intact. Unavailable movement buttons are disabled at the list boundaries. The default state shows the ordered definition and preview. The static specimen represents the definition; interactive execution evidence is recorded separately.
Keyboard
All operations use native controls. No drag operation is required. Move actions keep focus on the moved field’s controls. Removing a field focuses the next remaining field or the add control. Import and reset return to the add control. Preview submit focuses its error summary; links target stable field control IDs.
Accessibility
Use the canonical label, help and error associations, required markers and radio fieldset/legend semantics. Stable IDs survive JSON round trips and field reordering. Imported strings are text, never markup. No manual screen-reader pass is claimed by test presence.
Portability
Definition schema version 1 pins theme name, version, default profile and constituent component content digest. Accept at most 64 KiB, 20 fields, 20 options per choice field, 120-character labels and 400-character help. Preview text is limited to 2000 characters. Unknown keys, duplicate IDs, unsupported kinds, invalid choices and mismatched theme identity are rejected atomically. An old content identity requires an explicit migration outside this tool.
Everything stays in memory. Only explicit Download definition creates a file, containing the schema and no entered values. Reset clears the definition and preview. There is no autosave, network submission, schema execution, arbitrary HTML/CSS/JavaScript or imported validation expression.
Non-examples
A production backend, conditional logic engine, drag-only editor, arbitrary code generator, persistent account form, or native application port.