Class: FormState<VS, SD, ES, WS>

A class that implements the core form state machine behavior.

Type parameters#

Name	Type	Description
`VS`	`VS`	Type of form value state.
`SD`	`unknown`	Type of submit handler result.
`ES`	`undefined`	Type of form error state.
`WS`	`undefined`	Type of form warning state.

Hierarchy#

StateManager<FormData<VS, SD, ES, WS>>
↳ FormState

Constructors#

constructor#

• new FormState<VS, SD, ES, WS>(initialValues, options)

Create a new FormState instance with initial values and config options.

const form = new FormState(   // Initial form values   {     name: '',     email: '',   },
   // Form options   {     // Submit handler     async onSubmit(values) {       return {ok: true};     },
     // Error validation callback     validate(values) {       const errors = {};
       if (!values.name) {         errors.name = 'required;       }
       if (!values.email) {         errors.email = 'required;       }
       return errors;     },
     // Warning validation callback     warn(values) {       const warnings = {};
       if (!/.+\@.+\..+/.test(values.email)) {         warnings.email = 'invalid email';       }
       return warnings;     },   },);

Type parameters#

Name	Type
`VS`	`VS`
`SD`	`unknown`
`ES`	`undefined`
`WS`	`undefined`

Parameters#

Name	Type	Description
`initialValues`	`VS`	Initial form values.
`options`	`FormOptions`<`VS`, `SD`, `ES`, `WS`>	Form options object.

Overrides#

StateManager<FormData<VS, SD, ES, WS\>\>.constructor

Methods#

acceptPendingFieldValue#

▸ acceptPendingFieldValue(path, resolve?): void

Set the pending value as the current value for a field.

(See also: rejectPendingFieldValue)

const form = new FormState({foo: 'bar'}, {onSubmit() {...}});
formState.setValues({foo, 'updated'});
formState.getFieldValue('foo'); // 'bar'
formState.acceptPendingFieldValue('foo');
formState.getFieldValue('foo'); // 'updated'

Parameters#

Name	Type	Description
`path`	`FieldPath`	The path to a field within the form state.
`resolve`	(`value`: `any`, `pendingValue`: `any`) => `any`

Returns#

void

blurField#

▸ blurField(path): void

Process a blur event for a given path. This clears the current focused path state and sets the touched flag for that path. In the case that the current focused path is not the provided path, this action applies the effects of an implicit focus event before applying the blur effects. This serves as backup in case a field has failed to fire a focus event, keeping the derived state consistent.

(See also: focusField)

const form = new FormState({foo: 'bar'}, ...);
formState.blurField('foo');

Parameters#

Name	Type	Description
`path`	`FieldPath`	The path to a field within the form state.

Returns#

void

focusField#

▸ focusField(path): void

Process a focus event for a given path. This sets the current focus path to the provided path and sets the visited flag for that path. In the case that the current focused path is not undefined, this action applies the effects of an implicit blur event before applying the focus effects. This serves as backup in case a field has failed to fire a blur event, keeping the derived state consistent.

(See also: blurField)

const form = new FormState({foo: 'bar'}, ...);
formState.focusField('foo');

Parameters#

Name	Type	Description
`path`	`FieldPath`	The path to a field within the form state.

Returns#

void

getErrors#

▸ getErrors(): undefined | ES

Get the current error validation state. This method returns the most recent value returned from FormOptions.validate.

Returns#

undefined | ES

getFieldError#

▸ getFieldError(path): any

Parameters#

Name	Type
`path`	`FieldPath`

Returns#

any

getFieldValue#

▸ getFieldValue(path): any

Parameters#

Name	Type
`path`	`FieldPath`

Returns#

any

getFieldWarning#

▸ getFieldWarning(path): any

Parameters#

Name	Type
`path`	`FieldPath`

Returns#

any

getInitialFieldValue#

▸ getInitialFieldValue(path): any

Parameters#

Name	Type
`path`	`FieldPath`

Returns#

any

getPendingFieldValue#

▸ getPendingFieldValue(path): any

Parameters#

Name	Type
`path`	`FieldPath`

Returns#

any

getResult#

▸ getResult(): undefined | SD

Returns#

undefined | SD

getState#

▸ getState(): FormData<VS, SD, ES, WS>

Returns#

FormData<VS, SD, ES, WS>

Inherited from#

StateManager.getState

getSubmitErrors#

▸ getSubmitErrors(): undefined | ES

Returns#

undefined | ES

getSubmitStatus#

▸ getSubmitStatus(): FormSubmitStatus

Returns#

FormSubmitStatus

getWarnings#

▸ getWarnings(): undefined | WS

Get the current warning validation state. This method returns the most recent value returned from FormOptions.warn.

Returns#

undefined | WS

hasErrors#

▸ hasErrors(): boolean

Returns#

boolean

hasSubmitErrors#

▸ hasSubmitErrors(): boolean

Returns#

boolean

hasWarnings#

▸ hasWarnings(): boolean

Returns#

boolean

isFieldDetached#

▸ isFieldDetached(path): boolean

Parameters#

Name	Type
`path`	`FieldPath`

Returns#

boolean

isFieldDirty#

▸ isFieldDirty(path): boolean

Parameters#

Name	Type
`path`	`FieldPath`

Returns#

boolean

isFieldFocused#

▸ isFieldFocused(path): boolean

Parameters#

Name	Type
`path`	`FieldPath`

Returns#

boolean

isFieldTouched#

▸ isFieldTouched(path): boolean

Parameters#

Name	Type
`path`	`FieldPath`

Returns#

boolean

isFieldVisited#

▸ isFieldVisited(path): boolean

Parameters#

Name	Type
`path`	`FieldPath`

Returns#

boolean

rejectPendingFieldValue#

▸ rejectPendingFieldValue(path): void

Set the current value as the pending value for a field.

(See also: acceptPendingFieldValue)

const form = new FormState({foo: 'bar'}, {onSubmit() {}});
formState.setValues({foo, 'updated'});
formState.getPendingFieldValue('foo'); // 'updated'
formState.rejectPendingFieldValue('foo');
formState.getPendingFieldValue('foo'); // 'foo'

Parameters#

Name	Type	Description
`path`	`FieldPath`	The path to a field within the form state.

Returns#

void

runValidate#

▸ runValidate(): void

Update the error state with the result of the provided validate callback.

Returns#

void

runWarn#

▸ runWarn(): void

Update the warning state with the result of the provided warn callback.

Returns#

void

setFieldValue#

▸ setFieldValue(path, setValueAction): void

Set the current value at a given path and run the provided validate and warn callbacks to update the error and warning state if the value change is not idempotent.

Parameters#

Name	Type	Description
`path`	`FieldPath`	The path to a field within the form state.
`setValueAction`	`any`

Returns#

void

setValues#

▸ setValues(values): void

Process an incoming values prop. This action update the cached initial values and pending values in the state - which will in turn update the derived detached and dirty flags returned from useField.

Parameters#

Name	Type
`values`	`VS`

Returns#

void

submit#

▸ submit(): Promise<void>

Submit the current form values by calling the configured submit callback.

Returns#

Promise<void>

A promise that resolves when the submit sequence is complete.

subscribe#

▸ subscribe(subscriber): Object

Parameters#

Name	Type
`subscriber`	() => `void`

Returns#

Object

Name	Type
`unsubscribe`	() => `void`

Inherited from#

StateManager.subscribe