From da5026e9e7898228a2b2d1d8680bea343848f9d8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9rgio=20Coimbra?= Date: Sat, 1 Mar 2025 10:36:04 +0000 Subject: [PATCH] feat: add isSubmitSuccessful prop (#919) * feat: add isSubmitSuccessful prop * ci: apply automated fixes and generate docs * chore: fix CI --------- Co-authored-by: Sergio Coimbra Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com> Co-authored-by: Corbin Crutchley --- docs/reference/classes/formapi.md | 62 +++++++++---------- docs/reference/type-aliases/anyformapi.md | 2 +- docs/reference/type-aliases/anyformstate.md | 2 +- docs/reference/type-aliases/baseformstate.md | 8 +++ .../type-aliases/derivedformstate.md | 2 +- docs/reference/type-aliases/formstate.md | 2 +- examples/react/large-form/package.json | 2 +- packages/form-core/src/FormApi.ts | 16 ++++- packages/form-core/tests/FormApi.spec.ts | 26 ++++++++ pnpm-lock.yaml | 2 +- 10 files changed, 86 insertions(+), 38 deletions(-) diff --git a/docs/reference/classes/formapi.md b/docs/reference/classes/formapi.md index d71f41497..d55f89084 100644 --- a/docs/reference/classes/formapi.md +++ b/docs/reference/classes/formapi.md @@ -7,7 +7,7 @@ title: FormApi # Class: FormApi\ -Defined in: [packages/form-core/src/FormApi.ts:654](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L654) +Defined in: [packages/form-core/src/FormApi.ts:659](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L659) A class representing the Form API. It handles the logic and interactions with the form state. @@ -45,7 +45,7 @@ However, if you need to create a new instance manually, you can do so by calling new FormApi(opts?): FormApi ``` -Defined in: [packages/form-core/src/FormApi.ts:741](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L741) +Defined in: [packages/form-core/src/FormApi.ts:746](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L746) Constructs a new `FormApi` instance with the given form options. @@ -67,7 +67,7 @@ Constructs a new `FormApi` instance with the given form options. baseStore: Store>; ``` -Defined in: [packages/form-core/src/FormApi.ts:681](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L681) +Defined in: [packages/form-core/src/FormApi.ts:686](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L686) *** @@ -77,7 +77,7 @@ Defined in: [packages/form-core/src/FormApi.ts:681](https://github.com/TanStack/ fieldInfo: Record ? PrefixTupleAccessor, AllowedIndexes, never>, []> : TFormData extends any[] ? PrefixArrayAccessor, [any]> : TFormData extends Date ? never : TFormData extends object ? PrefixObjectAccessor, []> : TFormData extends string | number | bigint | boolean ? "" : never, FieldInfo>; ``` -Defined in: [packages/form-core/src/FormApi.ts:711](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L711) +Defined in: [packages/form-core/src/FormApi.ts:716](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L716) A record of field information for each field in the form. @@ -89,7 +89,7 @@ A record of field information for each field in the form. fieldMetaDerived: Derived ? PrefixTupleAccessor, AllowedIndexes, never>, []> : TFormData extends any[] ? PrefixArrayAccessor, [any]> : TFormData extends Date ? never : TFormData extends object ? PrefixObjectAccessor, []> : TFormData extends string | number | bigint | boolean ? "" : never, AnyFieldMeta>>; ``` -Defined in: [packages/form-core/src/FormApi.ts:694](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L694) +Defined in: [packages/form-core/src/FormApi.ts:699](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L699) *** @@ -99,7 +99,7 @@ Defined in: [packages/form-core/src/FormApi.ts:694](https://github.com/TanStack/ options: FormOptions = {}; ``` -Defined in: [packages/form-core/src/FormApi.ts:669](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L669) +Defined in: [packages/form-core/src/FormApi.ts:674](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L674) The options for the form. @@ -111,7 +111,7 @@ The options for the form. store: Derived>; ``` -Defined in: [packages/form-core/src/FormApi.ts:695](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L695) +Defined in: [packages/form-core/src/FormApi.ts:700](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L700) ## Accessors @@ -123,7 +123,7 @@ Defined in: [packages/form-core/src/FormApi.ts:695](https://github.com/TanStack/ get state(): FormState ``` -Defined in: [packages/form-core/src/FormApi.ts:713](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L713) +Defined in: [packages/form-core/src/FormApi.ts:718](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L718) ##### Returns @@ -137,7 +137,7 @@ Defined in: [packages/form-core/src/FormApi.ts:713](https://github.com/TanStack/ deleteField(field): void ``` -Defined in: [packages/form-core/src/FormApi.ts:1756](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1756) +Defined in: [packages/form-core/src/FormApi.ts:1770](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1770) #### Type Parameters @@ -161,7 +161,7 @@ Defined in: [packages/form-core/src/FormApi.ts:1756](https://github.com/TanStack getAllErrors(): object ``` -Defined in: [packages/form-core/src/FormApi.ts:1967](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1967) +Defined in: [packages/form-core/src/FormApi.ts:1981](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1981) Returns form and field level errors @@ -212,7 +212,7 @@ errors: ( getFieldInfo(field): FieldInfo ``` -Defined in: [packages/form-core/src/FormApi.ts:1665](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1665) +Defined in: [packages/form-core/src/FormApi.ts:1679](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1679) Gets the field info of the specified field. @@ -238,7 +238,7 @@ Gets the field info of the specified field. getFieldMeta(field): undefined | AnyFieldMeta ``` -Defined in: [packages/form-core/src/FormApi.ts:1656](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1656) +Defined in: [packages/form-core/src/FormApi.ts:1670](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1670) Gets the metadata of the specified field. @@ -264,7 +264,7 @@ Gets the metadata of the specified field. getFieldValue(field): DeepValue ``` -Defined in: [packages/form-core/src/FormApi.ts:1649](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1649) +Defined in: [packages/form-core/src/FormApi.ts:1663](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1663) Gets the value of the specified field. @@ -292,7 +292,7 @@ Gets the value of the specified field. handleSubmit(): Promise ``` -Defined in: [packages/form-core/src/FormApi.ts:1574](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1574) +Defined in: [packages/form-core/src/FormApi.ts:1579](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1579) Handles the form submission, performs validation, and calls the appropriate onSubmit or onInvalidSubmit callbacks. @@ -306,7 +306,7 @@ Handles the form submission, performs validation, and calls the appropriate onSu handleSubmit(submitMeta): Promise ``` -Defined in: [packages/form-core/src/FormApi.ts:1575](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1575) +Defined in: [packages/form-core/src/FormApi.ts:1580](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1580) Handles the form submission, performs validation, and calls the appropriate onSubmit or onInvalidSubmit callbacks. @@ -332,7 +332,7 @@ insertFieldValue( opts?): Promise ``` -Defined in: [packages/form-core/src/FormApi.ts:1785](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1785) +Defined in: [packages/form-core/src/FormApi.ts:1799](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1799) #### Type Parameters @@ -368,7 +368,7 @@ Defined in: [packages/form-core/src/FormApi.ts:1785](https://github.com/TanStack mount(): () => void ``` -Defined in: [packages/form-core/src/FormApi.ts:1042](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1042) +Defined in: [packages/form-core/src/FormApi.ts:1047](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1047) #### Returns @@ -390,7 +390,7 @@ moveFieldValues( opts?): void ``` -Defined in: [packages/form-core/src/FormApi.ts:1914](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1914) +Defined in: [packages/form-core/src/FormApi.ts:1928](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1928) Moves the value at the first specified index to the second specified index within an array field. @@ -431,7 +431,7 @@ pushFieldValue( opts?): void ``` -Defined in: [packages/form-core/src/FormApi.ts:1770](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1770) +Defined in: [packages/form-core/src/FormApi.ts:1784](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1784) Pushes a value into an array field. @@ -468,7 +468,7 @@ removeFieldValue( opts?): Promise ``` -Defined in: [packages/form-core/src/FormApi.ts:1843](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1843) +Defined in: [packages/form-core/src/FormApi.ts:1857](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1857) Removes a value from an array field at the specified index. @@ -506,7 +506,7 @@ replaceFieldValue( opts?): Promise ``` -Defined in: [packages/form-core/src/FormApi.ts:1817](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1817) +Defined in: [packages/form-core/src/FormApi.ts:1831](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1831) Replaces a value into an array field at the specified index. @@ -544,7 +544,7 @@ Replaces a value into an array field at the specified index. reset(values?, opts?): void ``` -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:1132](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1132) 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. @@ -577,7 +577,7 @@ Optional options to control the reset behavior. resetFieldMeta(fieldMeta): Record ``` -Defined in: [packages/form-core/src/FormApi.ts:1702](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1702) +Defined in: [packages/form-core/src/FormApi.ts:1716](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1716) #### Type Parameters @@ -601,7 +601,7 @@ Defined in: [packages/form-core/src/FormApi.ts:1702](https://github.com/TanStack setErrorMap(errorMap): void ``` -Defined in: [packages/form-core/src/FormApi.ts:1941](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1941) +Defined in: [packages/form-core/src/FormApi.ts:1955](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1955) Updates the form's errorMap @@ -623,7 +623,7 @@ Updates the form's errorMap setFieldMeta(field, updater): void ``` -Defined in: [packages/form-core/src/FormApi.ts:1684](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1684) +Defined in: [packages/form-core/src/FormApi.ts:1698](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1698) Updates the metadata of the specified field. @@ -656,7 +656,7 @@ setFieldValue( opts?): void ``` -Defined in: [packages/form-core/src/FormApi.ts:1726](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1726) +Defined in: [packages/form-core/src/FormApi.ts:1740](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1740) Sets the value of the specified field and optionally updates the touched state. @@ -694,7 +694,7 @@ swapFieldValues( opts?): void ``` -Defined in: [packages/form-core/src/FormApi.ts:1885](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1885) +Defined in: [packages/form-core/src/FormApi.ts:1899](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1899) Swaps the values at the specified indices within an array field. @@ -732,7 +732,7 @@ Swaps the values at the specified indices within an array field. update(options?): void ``` -Defined in: [packages/form-core/src/FormApi.ts:1059](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1059) +Defined in: [packages/form-core/src/FormApi.ts:1064](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1064) Updates the form options and form state. @@ -754,7 +754,7 @@ Updates the form options and form state. validateAllFields(cause): Promise ``` -Defined in: [packages/form-core/src/FormApi.ts:1153](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1153) +Defined in: [packages/form-core/src/FormApi.ts:1158](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1158) Validates all fields using the correct handlers for a given validation cause. @@ -779,7 +779,7 @@ validateArrayFieldsStartingFrom( cause): Promise ``` -Defined in: [packages/form-core/src/FormApi.ts:1183](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1183) +Defined in: [packages/form-core/src/FormApi.ts:1188](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1188) 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. @@ -813,7 +813,7 @@ Validates the children of a specified array in the form starting from a given in validateField(field, cause): unknown[] | Promise ``` -Defined in: [packages/form-core/src/FormApi.ts:1222](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1222) +Defined in: [packages/form-core/src/FormApi.ts:1227](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L1227) Validates a specified field in the form using the correct handlers for a given validation type. diff --git a/docs/reference/type-aliases/anyformapi.md b/docs/reference/type-aliases/anyformapi.md index a3c745c33..fd215a60c 100644 --- a/docs/reference/type-aliases/anyformapi.md +++ b/docs/reference/type-aliases/anyformapi.md @@ -11,6 +11,6 @@ title: AnyFormApi type AnyFormApi = FormApi; ``` -Defined in: [packages/form-core/src/FormApi.ts:634](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L634) +Defined in: [packages/form-core/src/FormApi.ts:639](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L639) A type representing the Form API with all generics set to `any` for convenience. diff --git a/docs/reference/type-aliases/anyformstate.md b/docs/reference/type-aliases/anyformstate.md index 4437226a6..50698c96f 100644 --- a/docs/reference/type-aliases/anyformstate.md +++ b/docs/reference/type-aliases/anyformstate.md @@ -11,4 +11,4 @@ title: AnyFormState type AnyFormState = FormState; ``` -Defined in: [packages/form-core/src/FormApi.ts:564](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L564) +Defined in: [packages/form-core/src/FormApi.ts:568](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L568) diff --git a/docs/reference/type-aliases/baseformstate.md b/docs/reference/type-aliases/baseformstate.md index 1d1ee8d2a..be32e3405 100644 --- a/docs/reference/type-aliases/baseformstate.md +++ b/docs/reference/type-aliases/baseformstate.md @@ -61,6 +61,14 @@ fieldMetaBase: Record, AnyFieldMetaBase>; A record of field metadata for each field in the form, not including the derived properties, like `errors` and such +### isSubmitSuccessful + +```ts +isSubmitSuccessful: boolean; +``` + +A boolean indicating if the last submission was successful. + ### isSubmitted ```ts diff --git a/docs/reference/type-aliases/derivedformstate.md b/docs/reference/type-aliases/derivedformstate.md index 94335f016..cf30bf075 100644 --- a/docs/reference/type-aliases/derivedformstate.md +++ b/docs/reference/type-aliases/derivedformstate.md @@ -11,7 +11,7 @@ title: DerivedFormState type DerivedFormState = object; ``` -Defined in: [packages/form-core/src/FormApi.ts:461](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L461) +Defined in: [packages/form-core/src/FormApi.ts:465](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L465) ## Type Parameters diff --git a/docs/reference/type-aliases/formstate.md b/docs/reference/type-aliases/formstate.md index a2c9f98ee..ff23c8776 100644 --- a/docs/reference/type-aliases/formstate.md +++ b/docs/reference/type-aliases/formstate.md @@ -11,7 +11,7 @@ title: FormState type FormState = BaseFormState & DerivedFormState; ``` -Defined in: [packages/form-core/src/FormApi.ts:531](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L531) +Defined in: [packages/form-core/src/FormApi.ts:535](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L535) ## Type Parameters diff --git a/examples/react/large-form/package.json b/examples/react/large-form/package.json index 1490b108e..85a1532fd 100644 --- a/examples/react/large-form/package.json +++ b/examples/react/large-form/package.json @@ -9,7 +9,7 @@ "test:types": "tsc" }, "dependencies": { - "@tanstack/react-form": "^0.47.2", + "@tanstack/react-form": "^0.47.3", "react": "^19.0.0", "react-dom": "^19.0.0" }, diff --git a/packages/form-core/src/FormApi.ts b/packages/form-core/src/FormApi.ts index 12bb05cb6..9f893972e 100644 --- a/packages/form-core/src/FormApi.ts +++ b/packages/form-core/src/FormApi.ts @@ -452,6 +452,10 @@ export type BaseFormState< * A counter for tracking the number of submission attempts. */ submissionAttempts: number + /** + * A boolean indicating if the last submission was successful. + */ + isSubmitSuccessful: boolean /** * @private, used to force a re-evaluation of the form state when options change */ @@ -616,6 +620,7 @@ function getDefaultFormState< isSubmitting: defaultState.isSubmitting ?? false, isValidating: defaultState.isValidating ?? false, submissionAttempts: defaultState.submissionAttempts ?? 0, + isSubmitSuccessful: defaultState.isSubmitSuccessful ?? false, validationMetaMap: defaultState.validationMetaMap ?? { onChange: undefined, onBlur: undefined, @@ -1580,6 +1585,7 @@ export class FormApi< isSubmitted: false, // Count submission attempts submissionAttempts: old.submissionAttempts + 1, + isSubmitSuccessful: false, // Reset isSubmitSuccessful at the start of submission })) // Don't let invalid forms submit @@ -1634,10 +1640,18 @@ export class FormApi< } as any) batch(() => { - this.baseStore.setState((prev) => ({ ...prev, isSubmitted: true })) + this.baseStore.setState((prev) => ({ + ...prev, + isSubmitted: true, + isSubmitSuccessful: true, // Set isSubmitSuccessful to true on successful submission + })) done() }) } catch (err) { + this.baseStore.setState((prev) => ({ + ...prev, + isSubmitSuccessful: false, // Ensure isSubmitSuccessful is false if an error occurs + })) done() throw err } diff --git a/packages/form-core/tests/FormApi.spec.ts b/packages/form-core/tests/FormApi.spec.ts index f81005f16..49543bf8b 100644 --- a/packages/form-core/tests/FormApi.spec.ts +++ b/packages/form-core/tests/FormApi.spec.ts @@ -2838,3 +2838,29 @@ it('should read and update union objects', async () => { field2.mount() expect(field2.getValue()).toStrictEqual(0) }) + +it('should update isSubmitSuccessful correctly during form submission', async () => { + const onSubmit = vi.fn().mockResolvedValue(undefined) + const form = new FormApi({ + defaultValues: { + name: 'test', + }, + onSubmit, + }) + + form.mount() + + expect(form.state.isSubmitSuccessful).toBe(false) + + await form.handleSubmit() + + expect(form.state.isSubmitSuccessful).toBe(true) + expect(onSubmit).toHaveBeenCalledTimes(1) + + // Simulate a failed submission + onSubmit.mockRejectedValueOnce(new Error('Submission failed')) + + await expect(form.handleSubmit()).rejects.toThrow('Submission failed') + + expect(form.state.isSubmitSuccessful).toBe(false) +}) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 90e1a90b1..ae0443227 100755 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -304,7 +304,7 @@ importers: examples/react/large-form: dependencies: '@tanstack/react-form': - specifier: ^0.47.2 + specifier: ^0.47.3 version: link:../../../packages/react-form react: specifier: ^19.0.0