form/fieldApi.md at c2f995704648d918997d61ab9c2db04208ad1df4

mirror of https://github.com/LukeHagar/form.git synced 2025-12-09 12:27:44 +00:00

Files

Ray Liu c2f9957046 feat(form-core): Change from touched error message and error message to error map and array of errors (#442 )

* feature(FieldAPI): Change from touched error message and  error message to error map and array of errors

BREAKING CHANGE: The touched Error and error field has been removed will be replaced with touched errors array and errors map.

* feat: update documentation for updated fields

* chore: update Vue adapter as well

* fix: update getErrorMapKey to return onChange when change is the validation cause

* chore: remove console.log

---------

Co-authored-by: Corbin Crutchley <git@crutchcorn.dev>

2023-09-08 11:14:54 -07:00

7.0 KiB

Raw Blame History

id, title

id	title
fieldApi	Field API

Creating a new FieldApi Instance

Normally, you will not need to create a new FieldApi instance directly. Instead, you will use a framework hook/function like useField or createField to create a new instance for you that utilizes your frameworks reactivity model. However, if you need to create a new instance manually, you can do so by calling the new FieldApi constructor.

const fieldApi: FieldApi<TData> = new FieldApi(formOptions: Field Options<TData>)

`FieldOptions<TData, TFormData>`

An object type representing the options for a field in a form.

```
name
```
- The field name. If TFormData is unknown, the type will be string. Otherwise, it will be DeepKeys<TFormData>.
```
defaultValue?: TData
```
- An optional default value for the field.
```
defaultMeta?: Partial<FieldMeta>
```
- An optional object with default metadata for the field.
```
onMount?: (formApi: FieldApi<TData, TFormData>) => void
```
- An optional function that takes a param of formApi which is a generic type of TData and TFormData
```
 onChange?: ValidateFn<TData, TFormData>
```
- An optional property that takes a ValidateFn which is a generic of TData and TFormData
```
  onChangeAsync?: ValidateAsyncFn<TData, TFormData>
```
- An optional property similar to onChange but async validation
```
   onChangeAsyncDebounceMs?: number
```
- An optional number to represent how long the onChangeAsync should wait before running
- If set to a number larger than 0, will debounce the async validation event by this length of time in milliseconds
```
  onBlur?: ValidateFn<TData, TFormData>
```
- An optional function, when that run when subscribing to blur event of input
```
 onBlurAsync?: ValidateAsyncFn<TData, TFormData>
```
- An optional function that takes a ValidateFn which is a generic of TData and TFormData happens async
```
onBlurAsyncDebounceMs?: number
```
- An optional number to represent how long the onBlurAsyncDebounceMs should wait before running
- If set to a number larger than 0, will debounce the async validation event by this length of time in milliseconds
```
onSubmitAsync?: number
```
- If set to a number larger than 0, will debounce the async validation event by this length of time in milliseconds

`ValidationCause`

A type representing the cause of a validation event.

'change' | 'blur' | 'submit' | 'mount'

`FieldMeta`

An object type representing the metadata of a field in a form.

```
isTouched: boolean
```
- A flag indicating whether the field has been touched.
```
touchedErrors: ValidationError[]
```
- An array of errors related to the touched state of the field.
```
errors: ValidationError[]
```
- An array of errors related related to the field value.
```
errorMap: ValidationErrorMap
```
- A map of errors related related to the field value.
```
isValidating: boolean
```
- A flag indicating whether the field is currently being validated.

`FieldApiOptions<TData, TFormData>`

An object type representing the required options for the FieldApi class.

Inherits from FieldOptions<TData, TFormData> with the form property set as required.

`FieldApi<TData, TFormData>`

A class representing the API for managing a form field.

Properties

```
uid: number
```
- A unique identifier for the field instance.
```
form: FormApi<TFormData>
```
- A reference to the form API instance.
```
name: DeepKeys<TFormData>
```
- The field name.
```
store: Store<FieldState<TData>>
```
- The field state store.
```
state: FieldState<TData>
```
- The current field state.

options: RequiredByKey<FieldOptions<TData, TFormData>, 'validateOn'>

The field options with the validateOn property set as required.

Methods

constructor(opts: FieldApiOptions<TData, TFormData>)

Initializes a new FieldApi instance.

```
mount(): () => void
```
- Mounts the field instance to the form.
```
updateStore(): void
```
- Updates the field store with the latest form state.

update(opts: FieldApiOptions<TData, TFormData>): void

Updates the field instance with new options.

```
getValue(): TData
```
- Gets the current field value.

setValue(updater: Updater<TData>, options?: { touch?: boolean; notify?: boolean }): void

Sets the field value.

```
getMeta(): FieldMeta
```
- Gets the current field metadata.

setMeta(updater: Updater<FieldMeta>): void

Sets the field metadata.

```
getInfo(): any
```
- Gets the field information object.
```
pushValue(value: TData): void
```
- Pushes a new value to the field.

insertValue(index: number, value: TData): void

Inserts a value at the specified index.

```
removeValue(index: number): void
```
- Removes a value at the specified index.

swapValues(aIndex: number, bIndex: number): void

Swaps the values at the specified indices.

getSubField<TName extends DeepKeys<TData>>(name: TName): FieldApi<DeepValue<TData, TName>, TFormData>

Gets a subfield instance.

```
validate(): Promise<any>
```
- Validates the field value.
```
handleBlur(): void;
```
- Handles the blur event.
```
handleChange(value: TData): void
```
- Handles the change event.

`FieldState<TData>`

An object type representing the state of a field.

```
value: TData
```
- The current value of the field.
```
meta: FieldMeta
```
- The current metadata of the field.

`UserChangeProps<TData>`

An object type representing the change and blur event handlers for a field.

```
onChange?: (value: TData) => void
```
- An optional function to further handle the change event.
```
onBlur?: (event: any) => void
```
- An optional function to further handle the blur event.

`UserInputProps`

An object type representing the input event handlers for a field.

```
onChange?: (event: any) => void
```
- An optional function to further handle the change event.
```
onBlur?: (event: any) => void
```
- An optional function to further handle the blur event.

`ChangeProps<TData>`

An object type representing the change and blur event handlers for a field.

```
value: TData
```
- The current value of the field.
```
onChange: (value: TData) => void
```
- A function to handle the change event.
```
onBlur: (event: any) => void
```
- A function to handle the blur event.

`InputProps`

An object type representing the input event handlers for a field.

```
value: string
```
- The current value of the field, coerced to a string.
```
onChange: (event: any) => void
```
- A function to handle the change event.
```
onBlur: (event: any) => void
```
- A function to handle the blur event.

7.0 KiB Raw Blame History

Creating a new FieldApi Instance

FieldOptions<TData, TFormData>

ValidationCause

FieldMeta

FieldApiOptions<TData, TFormData>

FieldApi<TData, TFormData>