Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(core) onSubmit meta #1131

Open
wants to merge 26 commits into
base: main
Choose a base branch
from
Open

feat(core) onSubmit meta #1131

Show file tree
Hide file tree
Changes from 9 commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
0c5f04e
feat(core) onSubmit meta
Jan 27, 2025
bd845ce
working prototype
Jan 28, 2025
394eddb
ci: apply automated fixes and generate docs
autofix-ci[bot] Jan 28, 2025
541aa17
commented Ts inference test
Jan 28, 2025
0ac0f3b
re-ordered generics
Jan 28, 2025
dc3c646
conditional generics issue
Jan 28, 2025
6a3d932
clean up of types and tests
Jan 28, 2025
ebe6936
hacky workaround for now
Jan 29, 2025
bc0785b
ci: apply automated fixes and generate docs
autofix-ci[bot] Jan 29, 2025
9bb39fc
fix react-form build 2
Jan 30, 2025
50404a6
chore: some more missing generics
Feb 4, 2025
8cbb040
ci: apply automated fixes and generate docs
autofix-ci[bot] Feb 4, 2025
0fb2ced
chore: remove generic constraint and fix react adaptor
Feb 4, 2025
92530cf
ci: apply automated fixes and generate docs
autofix-ci[bot] Feb 4, 2025
64ad6fc
fix: distributed conitional fix
Feb 4, 2025
c54fde2
ci: apply automated fixes and generate docs
autofix-ci[bot] Feb 4, 2025
9e86a74
fix: broken test now types are infered correctly
Feb 4, 2025
dbbb2cf
ci: apply automated fixes and generate docs
autofix-ci[bot] Feb 4, 2025
fb5c9ee
chore: angular adapter generics
Feb 4, 2025
5fc23ba
ci: apply automated fixes and generate docs
autofix-ci[bot] Feb 4, 2025
d43120a
chore: lit adapter generics
Feb 4, 2025
059b82b
ci: apply automated fixes and generate docs
autofix-ci[bot] Feb 4, 2025
3238984
chore: solid adapter generics
Feb 4, 2025
a6c8690
chore: vue adapter generics
Feb 4, 2025
3aa73f2
ci: apply automated fixes and generate docs
autofix-ci[bot] Feb 4, 2025
27cffc8
chore: MR comments
Feb 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 60 additions & 36 deletions docs/reference/classes/formapi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,9 @@ id: FormApi
title: FormApi
---

# Class: FormApi\<TFormData, TFormValidator\>
# Class: FormApi\<TFormData, TFormValidator, TFormSubmitMeta\>

Defined in: [packages/form-core/src/FormApi.ts:361](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L361)
Defined in: [packages/form-core/src/FormApi.ts:374](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L374)

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

Expand All @@ -19,27 +19,29 @@ However, if you need to create a new instance manually, you can do so by calling

• **TFormValidator** *extends* `Validator`\<`TFormData`, `unknown`\> \| `undefined` = `undefined`

• **TFormSubmitMeta** *extends* `object` = `never`

## Constructors

### new FormApi()

```ts
new FormApi<TFormData, TFormValidator>(opts?): FormApi<TFormData, TFormValidator>
new FormApi<TFormData, TFormValidator, TFormSubmitMeta>(opts?): FormApi<TFormData, TFormValidator, TFormSubmitMeta>
```

Defined in: [packages/form-core/src/FormApi.ts:390](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L390)
Defined in: [packages/form-core/src/FormApi.ts:404](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L404)

Constructs a new `FormApi` instance with the given form options.

#### Parameters

##### opts?

[`FormOptions`](../interfaces/formoptions.md)\<`TFormData`, `TFormValidator`\>
[`FormOptions`](../interfaces/formoptions.md)\<`TFormData`, `TFormValidator`, `TFormSubmitMeta`\>

#### Returns

[`FormApi`](formapi.md)\<`TFormData`, `TFormValidator`\>
[`FormApi`](formapi.md)\<`TFormData`, `TFormValidator`, `TFormSubmitMeta`\>

## Properties

Expand All @@ -49,7 +51,7 @@ Constructs a new `FormApi` instance with the given form options.
baseStore: Store<BaseFormState<TFormData>, (cb) => BaseFormState<TFormData>>;
```

Defined in: [packages/form-core/src/FormApi.ts:369](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L369)
Defined in: [packages/form-core/src/FormApi.ts:383](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L383)

***

Expand All @@ -59,7 +61,7 @@ Defined in: [packages/form-core/src/FormApi.ts:369](https://github.com/TanStack/
fieldInfo: Record<unknown extends TFormData ? string : TFormData extends readonly any[] & IsTuple<TFormData> ? PrefixTupleAccessor<TFormData<TFormData>, AllowedIndexes<TFormData<TFormData>, never>, []> : TFormData extends any[] ? PrefixArrayAccessor<TFormData<TFormData>, [any]> : TFormData extends Date ? never : TFormData extends object ? PrefixObjectAccessor<TFormData<TFormData>, []> : TFormData extends string | number | bigint | boolean ? "" : never, FieldInfo<TFormData, TFormValidator>>;
```

Defined in: [packages/form-core/src/FormApi.ts:375](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L375)
Defined in: [packages/form-core/src/FormApi.ts:389](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L389)

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

Expand All @@ -71,17 +73,17 @@ A record of field information for each field in the form.
fieldMetaDerived: Derived<Record<unknown extends TFormData ? string : TFormData extends readonly any[] & IsTuple<TFormData> ? PrefixTupleAccessor<TFormData<TFormData>, AllowedIndexes<TFormData<TFormData>, never>, []> : TFormData extends any[] ? PrefixArrayAccessor<TFormData<TFormData>, [any]> : TFormData extends Date ? never : TFormData extends object ? PrefixObjectAccessor<TFormData<TFormData>, []> : TFormData extends string | number | bigint | boolean ? "" : never, FieldMeta>>;
```

Defined in: [packages/form-core/src/FormApi.ts:370](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L370)
Defined in: [packages/form-core/src/FormApi.ts:384](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L384)

***

### options

```ts
options: FormOptions<TFormData, TFormValidator> = {};
options: FormOptions<TFormData, TFormValidator, TFormSubmitMeta> = {};
```

Defined in: [packages/form-core/src/FormApi.ts:368](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L368)
Defined in: [packages/form-core/src/FormApi.ts:382](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L382)

The options for the form.

Expand All @@ -93,7 +95,7 @@ The options for the form.
store: Derived<FormState<TFormData>>;
```

Defined in: [packages/form-core/src/FormApi.ts:371](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L371)
Defined in: [packages/form-core/src/FormApi.ts:385](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L385)

## Accessors

Expand All @@ -105,7 +107,7 @@ Defined in: [packages/form-core/src/FormApi.ts:371](https://github.com/TanStack/
get state(): FormState<TFormData>
```

Defined in: [packages/form-core/src/FormApi.ts:378](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L378)
Defined in: [packages/form-core/src/FormApi.ts:392](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L392)

##### Returns

Expand All @@ -119,7 +121,7 @@ Defined in: [packages/form-core/src/FormApi.ts:378](https://github.com/TanStack/
deleteField<TField>(field): void
```

Defined in: [packages/form-core/src/FormApi.ts:1227](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1227)
Defined in: [packages/form-core/src/FormApi.ts:1252](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1252)

#### Type Parameters

Expand All @@ -143,7 +145,7 @@ Defined in: [packages/form-core/src/FormApi.ts:1227](https://github.com/TanStack
getFieldInfo<TField>(field): FieldInfo<TFormData, TFormValidator>
```

Defined in: [packages/form-core/src/FormApi.ts:1136](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1136)
Defined in: [packages/form-core/src/FormApi.ts:1161](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1161)

Gets the field info of the specified field.

Expand All @@ -169,7 +171,7 @@ Gets the field info of the specified field.
getFieldMeta<TField>(field): undefined | FieldMeta
```

Defined in: [packages/form-core/src/FormApi.ts:1127](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1127)
Defined in: [packages/form-core/src/FormApi.ts:1152](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1152)

Gets the metadata of the specified field.

Expand All @@ -195,7 +197,7 @@ Gets the metadata of the specified field.
getFieldValue<TField>(field): DeepValue<TFormData, TField, IsNullable<TFormData>>
```

Defined in: [packages/form-core/src/FormApi.ts:1120](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1120)
Defined in: [packages/form-core/src/FormApi.ts:1145](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1145)

Gets the value of the specified field.

Expand All @@ -217,15 +219,37 @@ Gets the value of the specified field.

### handleSubmit()

#### Call Signature

```ts
handleSubmit(): Promise<void>
```

Defined in: [packages/form-core/src/FormApi.ts:1061](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1061)
Defined in: [packages/form-core/src/FormApi.ts:1079](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1079)

Handles the form submission, performs validation, and calls the appropriate onSubmit or onInvalidSubmit callbacks.

#### Returns
##### Returns

`Promise`\<`void`\>

#### Call Signature

```ts
handleSubmit(submitMeta): Promise<void>
```

Defined in: [packages/form-core/src/FormApi.ts:1080](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1080)

Handles the form submission, performs validation, and calls the appropriate onSubmit or onInvalidSubmit callbacks.

##### Parameters

###### submitMeta

`TFormSubmitMeta`

##### Returns

`Promise`\<`void`\>

Expand All @@ -241,7 +265,7 @@ insertFieldValue<TField>(
opts?): Promise<void>
```

Defined in: [packages/form-core/src/FormApi.ts:1259](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1259)
Defined in: [packages/form-core/src/FormApi.ts:1284](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1284)

Inserts a value into an array field at the specified index, shifting the subsequent values to the right.

Expand Down Expand Up @@ -279,7 +303,7 @@ Inserts a value into an array field at the specified index, shifting the subsequ
mount(): () => void
```

Defined in: [packages/form-core/src/FormApi.ts:638](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L638)
Defined in: [packages/form-core/src/FormApi.ts:654](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L654)

#### Returns

Expand All @@ -301,7 +325,7 @@ moveFieldValues<TField>(
opts?): void
```

Defined in: [packages/form-core/src/FormApi.ts:1377](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1377)
Defined in: [packages/form-core/src/FormApi.ts:1402](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1402)

Moves the value at the first specified index to the second specified index within an array field.

Expand Down Expand Up @@ -342,7 +366,7 @@ pushFieldValue<TField>(
opts?): void
```

Defined in: [packages/form-core/src/FormApi.ts:1241](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1241)
Defined in: [packages/form-core/src/FormApi.ts:1266](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1266)

Pushes a value into an array field.

Expand Down Expand Up @@ -379,7 +403,7 @@ removeFieldValue<TField>(
opts?): Promise<void>
```

Defined in: [packages/form-core/src/FormApi.ts:1312](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1312)
Defined in: [packages/form-core/src/FormApi.ts:1337](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1337)

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

Expand Down Expand Up @@ -417,7 +441,7 @@ replaceFieldValue<TField>(
opts?): Promise<void>
```

Defined in: [packages/form-core/src/FormApi.ts:1286](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1286)
Defined in: [packages/form-core/src/FormApi.ts:1311](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1311)

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

Expand Down Expand Up @@ -455,7 +479,7 @@ Replaces a value into an array field at the specified index.
reset(values?, opts?): void
```

Defined in: [packages/form-core/src/FormApi.ts:701](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L701)
Defined in: [packages/form-core/src/FormApi.ts:719](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L719)

Resets the form state to the default values.
If values are provided, the form will be reset to those values instead and the default values will be updated.
Expand Down Expand Up @@ -488,7 +512,7 @@ Optional options to control the reset behavior.
resetFieldMeta<TField>(fieldMeta): Record<TField, FieldMeta>
```

Defined in: [packages/form-core/src/FormApi.ts:1173](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1173)
Defined in: [packages/form-core/src/FormApi.ts:1198](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1198)

#### Type Parameters

Expand All @@ -512,7 +536,7 @@ Defined in: [packages/form-core/src/FormApi.ts:1173](https://github.com/TanStack
setErrorMap(errorMap): void
```

Defined in: [packages/form-core/src/FormApi.ts:1401](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1401)
Defined in: [packages/form-core/src/FormApi.ts:1426](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1426)

Updates the form's errorMap

Expand All @@ -534,7 +558,7 @@ Updates the form's errorMap
setFieldMeta<TField>(field, updater): void
```

Defined in: [packages/form-core/src/FormApi.ts:1155](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1155)
Defined in: [packages/form-core/src/FormApi.ts:1180](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1180)

Updates the metadata of the specified field.

Expand Down Expand Up @@ -567,7 +591,7 @@ setFieldValue<TField>(
opts?): void
```

Defined in: [packages/form-core/src/FormApi.ts:1197](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1197)
Defined in: [packages/form-core/src/FormApi.ts:1222](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1222)

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

Expand Down Expand Up @@ -605,7 +629,7 @@ swapFieldValues<TField>(
opts?): void
```

Defined in: [packages/form-core/src/FormApi.ts:1351](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1351)
Defined in: [packages/form-core/src/FormApi.ts:1376](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1376)

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

Expand Down Expand Up @@ -643,15 +667,15 @@ Swaps the values at the specified indices within an array field.
update(options?): void
```

Defined in: [packages/form-core/src/FormApi.ts:655](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L655)
Defined in: [packages/form-core/src/FormApi.ts:671](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L671)

Updates the form options and form state.

#### Parameters

##### options?

[`FormOptions`](../interfaces/formoptions.md)\<`TFormData`, `TFormValidator`\>
[`FormOptions`](../interfaces/formoptions.md)\<`TFormData`, `TFormValidator`, `TFormSubmitMeta`\>

#### Returns

Expand All @@ -665,7 +689,7 @@ Updates the form options and form state.
validateAllFields(cause): Promise<ValidationError[]>
```

Defined in: [packages/form-core/src/FormApi.ts:727](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L727)
Defined in: [packages/form-core/src/FormApi.ts:745](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L745)

Validates form and all fields in using the correct handlers for a given validation cause.

Expand All @@ -690,7 +714,7 @@ validateArrayFieldsStartingFrom<TField>(
cause): Promise<ValidationError[]>
```

Defined in: [packages/form-core/src/FormApi.ts:755](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L755)
Defined in: [packages/form-core/src/FormApi.ts:773](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L773)

Validates the children of a specified array in the form starting from a given index until the end using the correct handlers for a given validation type.

Expand Down Expand Up @@ -726,7 +750,7 @@ validateField<TField>(field, cause):
| Promise<ValidationError[]>
```

Defined in: [packages/form-core/src/FormApi.ts:794](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L794)
Defined in: [packages/form-core/src/FormApi.ts:812](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L812)

Validates a specified field in the form using the correct handlers for a given validation type.

Expand Down
Loading
Loading