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 · 4.0.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 button-secondary" 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 button-secondary" 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 button-secondary" type="button" data-event="edit" hidden="">Edit values</button><button class="button button-secondary" type="button" data-event="confirm" hidden="">Simulate save</button><button class="button button-secondary" type="button" data-event="complete" hidden="">Complete simulation</button><button class="button button-tertiary" 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 button-secondary" 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@4.0.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@4.0.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
Form builder form-builder
A bounded reference editor for five canonical field kinds, with keyboard ordering, local preview and explicit JSON definition import and export.
Report an issue with this component
Tokens
Focus a role to inspect its values; follow its link for persistent usage and source details.
| Part | Role | Value | Use |
|---|---|---|---|
root.bg | color.surface.defaultapproveduse | #0d0707 | D-041 surface.default: color.primitive.modern.panel. |
root.text | color.text.defaultapproveduse | #e99499 | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
root.border | color.border.controlapproveduse | #c81a1a | D-041 owner correction: red control and floating-frame borders, distinct from rose text. |
status.text | color.text.mutedapproveduse | #d4868b | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
State matrix
Every declared state and combination, statically rendered; the default cell is live. Sizes: compact, comfortable (switch with the density control above).
| State | Reference definition |
|---|---|
default | Draft reference · 3 fields · default profile
The interactive builder provides native add, edit, move and remove controls, canonical previews, and explicit JSON transfer. This static specimen does not submit data. |
empty | |
invalid | |
disabled |
Purpose
Build a bounded reference form in the interactive builder. D-021 remains proposed; this draft promotes no tokens, roles, profiles or native ports.
Anatomy
Each field has a stable ID, label, help, required flag and, for select and radio, stable option IDs and labels. Saving an edit validates the whole proposed definition before replacing the current one.
The preview uses the canonical field renderer and validation model of the validation-recovery composition. Changing a definition clears preview values and errors; moving focus or typing a preview value never changes the definition.
States
The empty state shows an explanation and an add action. An invalid import or edit reports a corrective message and keeps the current definition. Move buttons are disabled at the list boundaries. Default shows the ordered definition and preview. The static specimen shows the definition; interactive execution evidence is recorded separately.
Keyboard
No drag is required. Moving keeps focus on the moved field’s controls; removing focuses the next remaining field or the add control; import and reset return to the add control. Preview submit focuses its error summary, whose 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 reordering. Imported strings are text, never markup. Test presence claims no manual screen-reader pass.
Portability
Definition schema version 1 pins theme name, version, default profile and constituent component content digest. Limits: 64 KiB, 20 fields, 20 options per choice field, 120-character labels, 400-character help, 2000-character preview text. Unknown keys, duplicate IDs, unsupported kinds, invalid choices and mismatched theme identity are rejected atomically. An old content identity needs an explicit migration outside this tool.
Everything stays in memory; only Download definition creates a file, with the schema and no entered values. Reset clears definition and preview. 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.
Contrast report
4 declared pairs measured on resolved sRGB values with the WCAG 2.x formula; 0 waived (decorative only), 0 failing. A pass is a design target for the named role, not an application-wide conformance claim.
| Pair | State | Kind | Foreground | Background | Ratio | Min | Result |
|---|---|---|---|---|---|---|---|
| form-builder default text | default | text | color.text.default #e99499 | color.surface.default #0d0707 | 8.72 | 4.5 | pass |
| form-builder default border | default | ui | color.border.control #c81a1a | color.surface.default #0d0707 | 3.44 | 3 | pass |
| Editor text | — | text | color.text.default #e99499 | color.surface.default #0d0707 | 8.72 | 4.5 | pass |
| Definition status | — | text | color.text.muted #d4868b | color.surface.default #0d0707 | 7.22 | 4.5 | pass |
Keys
| Key | Action |
|---|---|
| Tab / Shift+Tab | Reach add, field editor, ordering, removal, preview and transfer controls in document order. |
| Enter / Space | Activate the focused native button. Move up and Move down preserve stable identity and focus. |
| Arrow keys | Use native select and radio choices in the preview. |
For agents
Component JSON ·Implementation brief ·Build a task kit ·
Related: admin-form text-field textarea select checkbox radio-group button
Stress fixtures: FX-360 FX-ZOOM-200 FX-DENSITY