Facet Fields / developer preview
Fields that carry
their own weight.
Facet Fields are original, form-associated Web Components for the input details that make an application feel dependable: labels, messages, constraints, validation, and safe state changes.
@linewisp/wisp-fields; it is not published to npm yet.Getting started
Register the element, place it inside a form, and configure it in JavaScript. Values, labels, options, help text, and errors are set through safe DOM APIs rather than generated HTML.
import { defineWispField } from '@linewisp/wisp-fields';
defineWispField();
document.querySelector('wisp-field').configure({
name: 'project-name',
label: 'Project name',
type: 'text',
required: true,
minLength: 3,
helpText: 'Use a name your team will recognise.',
});The essentials
Field types
Use ordinary platform semantics first. Each type retains its native browser input behavior and can take the shared theme and density settings.
text, email, number, password, tel, url, and textarea.select with safe text-only option labels, and checkbox with form-aware checked state.placeholder, helpText, autoComplete, inputMode, read-only, disabled, and required behavior.Configuration API
| Option | Type | Purpose |
|---|---|---|
name, label, type | required | Defines the form name, visible label, and supported native-field type. |
value, checked | string, boolean | Sets the initial state. Checkbox values are included only while checked. |
options | array | Required for select; labels are always rendered as text. |
required, min, max, minLength, maxLength, pattern | constraints | Uses clear built-in error messages before custom validation runs. |
validate | function | Returns an error string or null for synchronous application rules. |
validateAsync | async function | Receives a cancellation signal. Stale results are ignored. |
theme, density | shared values | Aligns the field with the rest of the Facet interface. |
Validation lifecycle
Built-in constraints run on change and blur. Call validate() on form submission, or use validateAsync() for a host-provided check. Starting a new validation or changing a value cancels any older async request, so late responses cannot overwrite the latest result.
Use setValue(value) and setChecked(checked) for programmatic changes. Both preserve form-associated state. Read valid when you need the current constraint result without displaying a new error.
Methods and events
Methods and state
value,checked, andvalidsetValue(value, validate?)setChecked(checked, validate?)validate()andvalidateAsync()reset()andfocus()
Events
wisp-field-inputon a value editwisp-field-changeafter a committed change- Both include
name,value,valid, anderror.
Framework use
Facet Fields is browser-native, with typed adapters for React, Vue, and Angular. Each adapter owns component registration, applies configuration changes, forwards the native events, and gives advanced users access to the underlying WispFieldElement. Open Fields Studio ↗ to change a configuration and copy a framework starter.
JavaScript
import { defineWispField } from '@linewisp/wisp-fields';
defineWispField();
document.querySelector('wisp-field').configure({
name: 'email', label: 'Email address', type: 'email', required: true,
});React
import { WispField } from '@linewisp/wisp-fields-react';
<WispField configuration={{ name: 'email', label: 'Email address', type: 'email' }}
onFieldChange={({ value, valid }) => save(value, valid)} />Vue
import { WispField } from '@linewisp/wisp-fields-vue';
<WispField :configuration="emailField" @field-change="save" />Angular
import { WispFieldComponent } from '@linewisp/wisp-fields-angular';
<linewisp-field [configuration]="emailField"
(fieldChange)="save($event)" />Accessibility and safety
Every field connects its label, help, and error text with native relationships. Errors announce through an alert, async checks announce their pending state, focus styles are visible, and checkbox state follows native input semantics. The component validates untyped JavaScript configuration and renders option labels as text rather than HTML.