form/formApi.md at b35ecd11070c4e240f25883cbf9811eef2d9c14c

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

Files

Enyel Sequeira b2b9b0aae1 docs: form-api-docs updated and removed some old docs (#433 )

* docs: form-api-docs updated and removed some old docs

* chore: updated docs removed mentioning the types and tried to explain what they do instead

---------

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

2023-10-17 23:19:19 -07:00

9.1 KiB

Raw Blame History

id, title

id	title
formApi	Form API

Creating a new FormApi Instance

Normally, you will not need to create a new FormApi instance directly. Instead, you will use a framework hook/function like useForm or createForm 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 FormApi constructor.

const formApi: FormApi<TData> = new FormApi(formOptions: FormOptions<TData>)

`FormOptions<TData>`

An object representing the options for a form.

```
  defaultValues?: TData
```
- Set initial values for you form.

  defaultState?: Partial<FormState<TData>>

The default state for the form.

```
  asyncDebounceMs?: number
```
- Optional time in milliseconds if you want to introduce a delay before firing off an async action.

    onMount?: (values: TData, formApi: FormApi<TData>) => ValidationError

Optional function that fires as soon as the component mounts.

  onMountAsync?: ( values: TData, formApi: FormApi<TData>) => ValidationError | Promise<ValidationError>

Optional async function that fires when the component mounts

```
  onMountAsyncDebounceMs?: number
```
- The default time in milliseconds that if set to a number larger than 0, will debounce the async validation event by this length of time in milliseconds.

   onChange?: (values: TData, formApi: FormApi<TData>) => ValidationError

Optional function that checks the validity of your data whenever a value changes

```
  onChangeAsync?: (values: TData, formApi: FormApi<TData>) => ValidationError | Promise<ValidationError>
```
- Optional onChange asynchronous counterpart to onChange. Useful for more complex validation logic that might involve server requests.
```
  onChangeAsyncDebounceMs?: number
```
- The default time in milliseconds that if set to a number larger than 0, will debounce the async validation event by this length of time in milliseconds.
```
  onBlur?: (values: TData, formApi: FormApi<TData>) => ValidationError
```
- Optional function that validates the form data when a field loses focus, returns a ValidationError
```
  onBlurAsync?:  (values: TData,formApi: FormApi<TData>) => ValidationError | Promise<ValidationError>
```
- Optional onBlur asynchronous validation method for when a field loses focus return a ValidationError or a promise of Promise<ValidationError>
```
  onBlurAsyncDebounceMs?: number
```
- The default time in milliseconds that if set to a number larger than 0, will debounce the async validation event by this length of time in milliseconds.
```
    onSubmit?: (values: TData, formApi: FormApi<TData>) => any | Promise<any>
```
- A function to be called when the form is submitted, what should happen once the user submits a valid form returns any or a promise Promise<any>
```
  onSubmitInvalid?: (values: TData, formApi: FormApi<TData>) => void
```
- Specify an action for scenarios where the user tries to submit an invalid form.

`FormApi<TFormData>`

A class representing the Form API. It handles the logic and interactions with the form state.

Properties

```
options: FormOptions<TFormData> = {}
```
- The options for the form.
```
store: Store<FormState<TFormData>>
```
- An internal mechanism that keeps track of the form's state.
```
state: FormState<TFormData>
```
- The current state of the form.

fieldInfo: Record<DeepKeys<TFormData>, FieldInfo<TFormData>> ={} as any

A record of field information for each field in the form.

```
  fieldName?: string
```
- An optional string representing the name of the field.
```
validationMeta: ValidationMeta
```
- The validation metadata for the form.

Methods

```
  constructor(opts?: FormOptions<TFormData>)
```
- Constructs a new FormApi instance with the given form options.

  update(options: FormOptions<TFormData>)

Updates the form options and form state.

```
reset()
```
- Resets the form state to the default values.
```
validateAllFields()
```
- Validates all fields in the form.
```
  handleSubmit(e: FormSubmitEvent)
```
- Handles the form submission event, performs validation, and calls the appropriate onSubmit or onInvalidSubmit callbacks.

  getFieldValue<TField extends DeepKeys<TFormData>>(field: TField)

Gets the value of the specified field.

  getFieldMeta<TField extends DeepKeys<TFormData>>(field: TField)

Gets the metadata of the specified field.

  getFieldInfo<TField extends DeepKeys<TFormData>>(field: TField)

Gets the field info of the specified field.

  setFieldMeta<TField extends DeepKeys<TFormData>>(field: TField, updater: Updater<FieldMeta>)

Updates the metadata of the specified field.

  setFieldValue<TField extends DeepKeys<TFormData>>(field: TField, updater: Updater<DeepValue<TFormData, TField>>, opts?: { touch?: boolean })

Sets the value of the specified field and optionally updates the touched state.

  pushFieldValue<TField extends DeepKeys<TFormData>>(field: TField, value: DeepValue<TFormData, TField>, opts?: { touch?: boolean })

Pushes a value into an array field.

  insertFieldValue<TField extends DeepKeys<TFormData>>(field: TField, index: number, value: DeepValue<TFormData, TField>, opts?: { touch?: boolean })

Inserts a value into an array field at the specified index.

  removeFieldValue<TField extends DeepKeys<TFormData>>(field: TField, index: number, opts?: { touch?: boolean })

Removes a value from an array field at the specified index.

  swapFieldValues<TField extends DeepKeys<TFormData>>(field: TField, index1: number, index2: number)

Swaps the values at the specified indices within an array field.

`FormState<TData>`

An object representing the current state of the form.

```
values: TData
```
- The current values of the form fields.
```
isFormValidating: boolean
```
- A boolean indicating if the form is currently validating.
```
formValidationCount: number
```
- A counter for tracking the number of validations performed on the form.
```
isFormValid: boolean
```
- A boolean indicating if the form is valid.
```
  formError?: ValidationError
```
- A possible validation error for the form.
```
fieldMeta: Record<DeepKeys<TData>, FieldMeta>
```
- A record of field metadata for each field in the form.
```
isFieldsValidating: boolean
```
- A boolean indicating if any of the form fields are currently validating.
```
isFieldsValid: boolean
```
- A boolean indicating if all the form fields are valid.
```
isSubmitting: boolean
```
- A boolean indicating if the form is currently submitting.
```
isTouched: boolean
```
- A boolean indicating if any of the form fields have been touched.
```
isSubmitted: boolean
```
- A boolean indicating if the form has been submitted.
```
isValidating: boolean
```
- A boolean indicating if the form or any of its fields are currently validating.
```
isValid: boolean
```
- A boolean indicating if the form and all its fields are valid.
```
canSubmit: boolean
```
- A boolean indicating if the form can be submitted based on its current state.
```
submissionAttempts: number
```
- A counter for tracking the number of submission attempts.

`FieldInfo<TFormData>`

An object representing the field information for a specific field within the form.

```
instances: Record<string, FieldApi<any, TFormData>>
```
- A record of field instances with unique identifiers as keys.
- Check below for ValidationMeta

`ValidationMeta`

An object representing the validation metadata for a field.

```
  validationCount?: number
```
- A counter for tracking the number of validations performed on the field.
```
  validationAsyncCount?: number
```
- A counter for tracking the number of validations performed on the field async.
```
  validationPromise?: Promise<ValidationError>
```
- A promise representing the current validation state of the field.
```
  validationResolve?: (error: ValidationError) => void
```
- A function to resolve the validation promise with a possible validation error.
```
  validationReject?: (error: unknown) => void
```
- A function to reject the validation promise with an error.

`ValidationError`

A type representing a validation error. Possible values are undefined, false, null, or a string with an error message.

`ValidationErrorMapKeys`

A type representing the keys used to map to ValidationError in ValidationErrorMap. It is defined with on${Capitalize<ValidationCause>}

`ValidationErrorMap`

A type that represents a map with the keys as ValidationErrorMapKeys and the values as ValidationError

9.1 KiB Raw Blame History

Creating a new FormApi Instance

FormOptions<TData>

FormApi<TFormData>

Properties

Methods

FormState<TData>

FieldInfo<TFormData>

ValidationMeta

ValidationError

ValidationErrorMapKeys

ValidationErrorMap