From 33eacda3e6f3064dcda6608eb540452f718c8c37 Mon Sep 17 00:00:00 2001 From: Corbin Crutchley Date: Thu, 20 Jun 2024 12:54:19 -0700 Subject: [PATCH] docs: typedoc generation * docs: initial work on implementing typedoc * docs: migrate to use formApi reference typedoc comments * chore: document FieldAPI from docs * chore: remove prefix to showcase file types * chore: migrate reference docs to take multiple paths * chore: add external and cleanup * chore: add lit and cleanup rm usage * chore: add manual docs to ts files themselves * chore: add React to reference docs * chore: add solid and vue code samples * chore: fix typedoc generations --- docs/config.json | 121 ++-- docs/framework/angular/reference/index.md | 10 + .../framework/angular/reference/injectform.md | 23 + .../angular/reference/injectstore.md | 27 + .../angular/reference/tanstackfield.md | 260 +++++++ docs/framework/lit/reference/index.md | 5 + .../lit/reference/tanstackformcontroller.md | 139 ++++ docs/framework/react/reference/Field.md | 70 -- .../react/reference/createservervalidate.md | 23 + docs/framework/react/reference/field.md | 33 + docs/framework/react/reference/fieldApi.md | 13 - .../react/reference/fieldcomponent.md | 39 ++ docs/framework/react/reference/formApi.md | 31 - docs/framework/react/reference/index.md | 18 + .../react/reference/initialformstate.md | 29 + docs/framework/react/reference/useField.md | 66 -- docs/framework/react/reference/useForm.md | 18 - docs/framework/react/reference/usefield.md | 35 + docs/framework/react/reference/useform.md | 27 + .../framework/react/reference/usetransform.md | 45 ++ docs/framework/solid/reference/Field.md | 33 +- docs/framework/solid/reference/createField.md | 37 +- docs/framework/solid/reference/createForm.md | 27 +- docs/framework/solid/reference/fieldApi.md | 6 - .../solid/reference/fieldcomponent.md | 37 + docs/framework/solid/reference/formApi.md | 6 - docs/framework/solid/reference/index.md | 12 + docs/framework/vue/reference/Field.md | 33 +- docs/framework/vue/reference/fieldApi.md | 6 - .../framework/vue/reference/fieldcomponent.md | 33 + docs/framework/vue/reference/formApi.md | 6 - docs/framework/vue/reference/index.md | 12 + docs/framework/vue/reference/useField.md | 45 +- docs/framework/vue/reference/useForm.md | 27 +- docs/reference/deepkeys.md | 17 + docs/reference/deepvalue.md | 19 + docs/reference/fieldApi.md | 320 --------- docs/reference/fieldapi.md | 499 +++++++++++++ docs/reference/fieldapioptions.md | 173 +++++ docs/reference/fieldinfo.md | 35 + docs/reference/fieldmeta.md | 69 ++ docs/reference/fieldoptions.md | 129 ++++ docs/reference/fieldstate.md | 33 + docs/reference/fieldvalidators.md | 213 ++++++ docs/reference/formApi.md | 319 --------- docs/reference/formapi.md | 663 ++++++++++++++++++ docs/reference/formoptions.md | 23 + docs/reference/formstate.md | 161 +++++ docs/reference/formvalidators.md | 129 ++++ docs/reference/index.md | 32 + docs/reference/mergeform.md | 25 + docs/reference/types.md | 20 - docs/reference/updater.md | 15 + docs/reference/updaterfn.md | 23 + docs/reference/validationerror.md | 9 + docs/reference/validationmeta.md | 21 + package.json | 3 + packages/angular-form/tsconfig.docs.json | 9 + packages/form-core/src/FieldApi.ts | 226 +++++- packages/form-core/src/FormApi.ts | 240 ++++++- packages/form-core/src/mergeForm.ts | 3 + packages/form-core/src/types.ts | 16 +- packages/form-core/src/util-types.ts | 22 +- packages/form-core/src/utils.ts | 24 + packages/form-core/tsconfig.docs.json | 4 + packages/lit-form/tsconfig.docs.json | 9 + packages/react-form/src/types.ts | 3 + packages/react-form/src/useField.tsx | 28 + packages/react-form/src/useForm.tsx | 20 + packages/react-form/tsconfig.docs.json | 9 + packages/solid-form/tsconfig.docs.json | 9 + packages/vue-form/tsconfig.docs.json | 9 + pnpm-lock.yaml | 67 ++ scripts/reference-docs.js | 124 ++++ scripts/typedoc-remove-prefix.mjs | 24 + 75 files changed, 4151 insertions(+), 997 deletions(-) create mode 100644 docs/framework/angular/reference/index.md create mode 100644 docs/framework/angular/reference/injectform.md create mode 100644 docs/framework/angular/reference/injectstore.md create mode 100644 docs/framework/angular/reference/tanstackfield.md create mode 100644 docs/framework/lit/reference/index.md create mode 100644 docs/framework/lit/reference/tanstackformcontroller.md delete mode 100644 docs/framework/react/reference/Field.md create mode 100644 docs/framework/react/reference/createservervalidate.md create mode 100644 docs/framework/react/reference/field.md delete mode 100644 docs/framework/react/reference/fieldApi.md create mode 100644 docs/framework/react/reference/fieldcomponent.md delete mode 100644 docs/framework/react/reference/formApi.md create mode 100644 docs/framework/react/reference/index.md create mode 100644 docs/framework/react/reference/initialformstate.md delete mode 100644 docs/framework/react/reference/useField.md delete mode 100644 docs/framework/react/reference/useForm.md create mode 100644 docs/framework/react/reference/usefield.md create mode 100644 docs/framework/react/reference/useform.md create mode 100644 docs/framework/react/reference/usetransform.md delete mode 100644 docs/framework/solid/reference/fieldApi.md create mode 100644 docs/framework/solid/reference/fieldcomponent.md delete mode 100644 docs/framework/solid/reference/formApi.md create mode 100644 docs/framework/solid/reference/index.md delete mode 100644 docs/framework/vue/reference/fieldApi.md create mode 100644 docs/framework/vue/reference/fieldcomponent.md delete mode 100644 docs/framework/vue/reference/formApi.md create mode 100644 docs/framework/vue/reference/index.md create mode 100644 docs/reference/deepkeys.md create mode 100644 docs/reference/deepvalue.md delete mode 100644 docs/reference/fieldApi.md create mode 100644 docs/reference/fieldapi.md create mode 100644 docs/reference/fieldapioptions.md create mode 100644 docs/reference/fieldinfo.md create mode 100644 docs/reference/fieldmeta.md create mode 100644 docs/reference/fieldoptions.md create mode 100644 docs/reference/fieldstate.md create mode 100644 docs/reference/fieldvalidators.md delete mode 100644 docs/reference/formApi.md create mode 100644 docs/reference/formapi.md create mode 100644 docs/reference/formoptions.md create mode 100644 docs/reference/formstate.md create mode 100644 docs/reference/formvalidators.md create mode 100644 docs/reference/index.md create mode 100644 docs/reference/mergeform.md delete mode 100644 docs/reference/types.md create mode 100644 docs/reference/updater.md create mode 100644 docs/reference/updaterfn.md create mode 100644 docs/reference/validationerror.md create mode 100644 docs/reference/validationmeta.md create mode 100644 packages/angular-form/tsconfig.docs.json create mode 100644 packages/form-core/tsconfig.docs.json create mode 100644 packages/lit-form/tsconfig.docs.json create mode 100644 packages/react-form/tsconfig.docs.json create mode 100644 packages/solid-form/tsconfig.docs.json create mode 100644 packages/vue-form/tsconfig.docs.json create mode 100644 scripts/reference-docs.js create mode 100644 scripts/typedoc-remove-prefix.mjs diff --git a/docs/config.json b/docs/config.json index 059eb8fae..cb893c5b0 100644 --- a/docs/config.json +++ b/docs/config.json @@ -160,85 +160,78 @@ { "label": "API Reference", "children": [ - { - "label": "FormApi", - "to": "reference/formApi" - }, - { - "label": "FieldApi", - "to": "reference/fieldApi" - }, - { - "label": "Types", - "to": "reference/types" - } + {"label": "JavaScript Reference", "to": "reference/index"}, + {"label": "Classes / FieldApi", "to": "reference/fieldapi"}, + {"label": "Classes / FormApi", "to": "reference/formapi"}, + {"label": "Functions / formOptions", "to": "reference/formoptions"}, + {"label": "Functions / mergeForm", "to": "reference/mergeform"}, + {"label": "Interfaces / FieldApiOptions", "to": "reference/fieldapioptions"}, + {"label": "Interfaces / FieldOptions", "to": "reference/fieldoptions"}, + {"label": "Interfaces / FieldValidators", "to": "reference/fieldvalidators"}, + {"label": "Interfaces / FormOptions", "to": "reference/formoptions"}, + {"label": "Interfaces / FormValidators", "to": "reference/formvalidators"}, + {"label": "Types / DeepKeys", "to": "reference/deepkeys"}, + {"label": "Types / DeepValue", "to": "reference/deepvalue"}, + {"label": "Types / FieldInfo", "to": "reference/fieldinfo"}, + {"label": "Types / FieldMeta", "to": "reference/fieldmeta"}, + {"label": "Types / FieldState", "to": "reference/fieldstate"}, + {"label": "Types / FormState", "to": "reference/formstate"}, + {"label": "Types / Updater", "to": "reference/updater"}, + {"label": "Types / UpdaterFn", "to": "reference/updaterfn"}, + {"label": "Types / ValidationError", "to": "reference/validationerror"}, + {"label": "Types / ValidationMeta", "to": "reference/validationmeta"} ], "frameworks": [ { "label": "react", "children": [ - { - "label": "useForm", - "to": "framework/react/reference/useForm" - }, - { - "label": "useField", - "to": "framework/react/reference/useField" - }, - { - "label": "Field", - "to": "framework/react/reference/Field" - }, - { - "label": "FormApi", - "to": "framework/react/reference/formApi" - }, - { - "label": "FieldApi", - "to": "framework/react/reference/fieldApi" - } + {"label": "React Reference", "to": "framework/react/reference/index"}, + {"label": "Functions / createServerValidate", "to": "framework/react/reference/createservervalidate"}, + {"label": "Functions / Field", "to": "framework/react/reference/field"}, + {"label": "Functions / useField", "to": "framework/react/reference/usefield"}, + {"label": "Functions / useForm", "to": "framework/react/reference/useform"}, + {"label": "Functions / useTransform", "to": "framework/react/reference/usetransform"}, + {"label": "Types / FieldComponent", "to": "framework/react/reference/fieldcomponent"}, + {"label": "Types / UseField", "to": "framework/react/reference/usefield"}, + {"label": "Variables / initialFormState", "to": "framework/react/reference/initialformstate"} ] }, { "label": "vue", "children": [ - { - "label": "useForm", - "to": "framework/vue/reference/useForm" - }, - { - "label": "useField", - "to": "framework/vue/reference/useField" - }, - { - "label": "Field", - "to": "framework/vue/reference/Field" - }, - { - "label": "FormApi", - "to": "framework/vue/reference/formApi" - } + {"label": "Vue Reference", "to": "framework/vue/reference/index"}, + {"label": "Functions / Field", "to": "framework/vue/reference/field"}, + {"label": "Functions / useField", "to": "framework/vue/reference/usefield"}, + {"label": "Functions / useForm", "to": "framework/vue/reference/useform"}, + {"label": "Types / FieldComponent", "to": "framework/vue/reference/fieldcomponent"}, + {"label": "Types / UseField", "to": "framework/vue/reference/usefield"} ] }, { "label": "solid", "children": [ - { - "label": "useForm", - "to": "framework/solid/reference/createForm" - }, - { - "label": "useField", - "to": "framework/solid/reference/createField" - }, - { - "label": "Field", - "to": "framework/solid/reference/Field" - }, - { - "label": "FormApi", - "to": "framework/solid/reference/formApi" - } + {"label": "Solid Reference", "to": "framework/solid/reference/index"}, + {"label": "Functions / createField", "to": "framework/solid/reference/createfield"}, + {"label": "Functions / createForm", "to": "framework/solid/reference/createform"}, + {"label": "Functions / Field", "to": "framework/solid/reference/field"}, + {"label": "Types / CreateField", "to": "framework/solid/reference/createfield"}, + {"label": "Types / FieldComponent", "to": "framework/solid/reference/fieldcomponent"} + ] + }, + { + "label": "lit", + "children": [ + {"label": "Lit Reference", "to": "framework/lit/reference/index"}, + {"label": "Classes / TanStackFormController", "to": "framework/lit/reference/tanstackformcontroller"} + ] + }, + { + "label": "angular", + "children": [ + {"label": "Angular Reference", "to": "framework/angular/reference/index"}, + {"label": "Classes / TanStackField", "to": "framework/angular/reference/tanstackfield"}, + {"label": "Functions / injectForm", "to": "framework/angular/reference/injectform"}, + {"label": "Functions / injectStore", "to": "framework/angular/reference/injectstore"}, ] } ] diff --git a/docs/framework/angular/reference/index.md b/docs/framework/angular/reference/index.md new file mode 100644 index 000000000..32586195f --- /dev/null +++ b/docs/framework/angular/reference/index.md @@ -0,0 +1,10 @@ +# @tanstack/angular-form + +## Classes + +- [TanStackField](tanstackfield.md) + +## Functions + +- [injectForm](injectform.md) +- [injectStore](injectstore.md) diff --git a/docs/framework/angular/reference/injectform.md b/docs/framework/angular/reference/injectform.md new file mode 100644 index 000000000..ba090bd02 --- /dev/null +++ b/docs/framework/angular/reference/injectform.md @@ -0,0 +1,23 @@ +# Function: injectForm() + +```ts +function injectForm(opts?): FormApi +``` + +## Type parameters + +• **TFormData** + +• **TFormValidator** *extends* `undefined` \| `Validator`\<`TFormData`, `unknown`\> = `undefined` + +## Parameters + +• **opts?**: `FormOptions`\<`TFormData`, `TFormValidator`\> + +## Returns + +`FormApi`\<`TFormData`, `TFormValidator`\> + +## Source + +[inject-form.ts:4](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/angular-form/src/inject-form.ts#L4) diff --git a/docs/framework/angular/reference/injectstore.md b/docs/framework/angular/reference/injectstore.md new file mode 100644 index 000000000..551ed2500 --- /dev/null +++ b/docs/framework/angular/reference/injectstore.md @@ -0,0 +1,27 @@ +# Function: injectStore() + +```ts +function injectStore(form, selector?): Signal +``` + +## Type parameters + +• **TFormData** + +• **TFormValidator** *extends* `undefined` \| `Validator`\<`TFormData`, `unknown`\> = `undefined` + +• **TSelected** = `NoInfer`\<`FormState`\<`TFormData`\>\> + +## Parameters + +• **form**: `FormApi`\<`TFormData`, `TFormValidator`\> + +• **selector?** + +## Returns + +`Signal`\<`TSelected`\> + +## Source + +[inject-store.ts:4](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/angular-form/src/inject-store.ts#L4) diff --git a/docs/framework/angular/reference/tanstackfield.md b/docs/framework/angular/reference/tanstackfield.md new file mode 100644 index 000000000..4b7f5e8dc --- /dev/null +++ b/docs/framework/angular/reference/tanstackfield.md @@ -0,0 +1,260 @@ +# Class: TanStackField\ + +## Type parameters + +• **TParentData** + +• **TName** *extends* `DeepKeys`\<`TParentData`\> + +• **TFieldValidator** *extends* `Validator`\<`DeepValue`\<`TParentData`, `TName`\>, `unknown`\> \| `undefined` = `undefined` + +• **TFormValidator** *extends* `Validator`\<`TParentData`, `unknown`\> \| `undefined` = `undefined` + +• **TData** *extends* `DeepValue`\<`TParentData`, `TName`\> = `DeepValue`\<`TParentData`, `TName`\> + +## Implements + +- `OnInit` +- `OnChanges` +- `OnDestroy` +- `FieldOptions`\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\> + +## Constructors + +### new TanStackField() + +```ts +new TanStackField(): TanStackField +``` + +#### Returns + +[`TanStackField`](tanstackfield.md)\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\> + +## Properties + +### api + +```ts +api: FieldApi; +``` + +#### Source + +[tanstack-field.directive.ts:62](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/angular-form/src/tanstack-field.directive.ts#L62) + +*** + +### asyncAlways? + +```ts +optional asyncAlways: boolean; +``` + +#### Implementation of + +`FieldOptions.asyncAlways` + +#### Source + +[tanstack-field.directive.ts:50](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/angular-form/src/tanstack-field.directive.ts#L50) + +*** + +### asyncDebounceMs? + +```ts +optional asyncDebounceMs: number; +``` + +#### Implementation of + +`FieldOptions.asyncDebounceMs` + +#### Source + +[tanstack-field.directive.ts:49](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/angular-form/src/tanstack-field.directive.ts#L49) + +*** + +### defaultMeta? + +```ts +optional defaultMeta: Partial; +``` + +#### Implementation of + +`FieldOptions.defaultMeta` + +#### Source + +[tanstack-field.directive.ts:60](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/angular-form/src/tanstack-field.directive.ts#L60) + +*** + +### defaultValue? + +```ts +optional defaultValue: NoInfer; +``` + +#### Implementation of + +`FieldOptions.defaultValue` + +#### Source + +[tanstack-field.directive.ts:48](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/angular-form/src/tanstack-field.directive.ts#L48) + +*** + +### name + +```ts +name: TName; +``` + +#### Implementation of + +`FieldOptions.name` + +#### Source + +[tanstack-field.directive.ts:44](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/angular-form/src/tanstack-field.directive.ts#L44) + +*** + +### preserveValue? + +```ts +optional preserveValue: boolean; +``` + +#### Implementation of + +`FieldOptions.preserveValue` + +#### Source + +[tanstack-field.directive.ts:51](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/angular-form/src/tanstack-field.directive.ts#L51) + +*** + +### tanstackField + +```ts +tanstackField: FormApi; +``` + +#### Source + +[tanstack-field.directive.ts:53](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/angular-form/src/tanstack-field.directive.ts#L53) + +*** + +### unmount()? + +```ts +optional unmount: () => void; +``` + +#### Returns + +`void` + +#### Source + +[tanstack-field.directive.ts:78](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/angular-form/src/tanstack-field.directive.ts#L78) + +*** + +### validatorAdapter? + +```ts +optional validatorAdapter: TFieldValidator; +``` + +#### Implementation of + +`FieldOptions.validatorAdapter` + +#### Source + +[tanstack-field.directive.ts:52](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/angular-form/src/tanstack-field.directive.ts#L52) + +*** + +### validators? + +```ts +optional validators: NoInfer>; +``` + +#### Implementation of + +`FieldOptions.validators` + +#### Source + +[tanstack-field.directive.ts:57](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/angular-form/src/tanstack-field.directive.ts#L57) + +## Methods + +### ngOnChanges() + +```ts +ngOnChanges(): void +``` + +#### Returns + +`void` + +#### Implementation of + +`OnChanges.ngOnChanges` + +#### Source + +[tanstack-field.directive.ts:90](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/angular-form/src/tanstack-field.directive.ts#L90) + +*** + +### ngOnDestroy() + +```ts +ngOnDestroy(): void +``` + +#### Returns + +`void` + +#### Implementation of + +`OnDestroy.ngOnDestroy` + +#### Source + +[tanstack-field.directive.ts:86](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/angular-form/src/tanstack-field.directive.ts#L86) + +*** + +### ngOnInit() + +```ts +ngOnInit(): void +``` + +#### Returns + +`void` + +#### Implementation of + +`OnInit.ngOnInit` + +#### Source + +[tanstack-field.directive.ts:80](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/angular-form/src/tanstack-field.directive.ts#L80) diff --git a/docs/framework/lit/reference/index.md b/docs/framework/lit/reference/index.md new file mode 100644 index 000000000..fd32972cc --- /dev/null +++ b/docs/framework/lit/reference/index.md @@ -0,0 +1,5 @@ +# @tanstack/lit-form + +## Classes + +- [TanStackFormController](tanstackformcontroller.md) diff --git a/docs/framework/lit/reference/tanstackformcontroller.md b/docs/framework/lit/reference/tanstackformcontroller.md new file mode 100644 index 000000000..ce0b3a0aa --- /dev/null +++ b/docs/framework/lit/reference/tanstackformcontroller.md @@ -0,0 +1,139 @@ +# Class: TanStackFormController\ + +## Type parameters + +• **TParentData** + +• **TFormValidator** *extends* `Validator`\<`TParentData`, `unknown`\> \| `undefined` = `undefined` + +## Implements + +- `ReactiveController` + +## Constructors + +### new TanStackFormController() + +```ts +new TanStackFormController(host, config?): TanStackFormController +``` + +#### Parameters + +• **host**: `ReactiveControllerHost` + +• **config?**: `FormOptions`\<`TParentData`, `TFormValidator`\> + +#### Returns + +[`TanStackFormController`](tanstackformcontroller.md)\<`TParentData`, `TFormValidator`\> + +#### Source + +[tanstack-form-controller.ts:93](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/lit-form/src/tanstack-form-controller.ts#L93) + +## Properties + +### api + +```ts +api: FormApi; +``` + +#### Source + +[tanstack-form-controller.ts:91](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/lit-form/src/tanstack-form-controller.ts#L91) + +## Methods + +### field() + +```ts +field(fieldConfig, render): object +``` + +#### Type parameters + +• **TName** *extends* `string` \| `number` + +• **TFieldValidator** *extends* `undefined` \| `Validator`\<`DeepValue`\<`TParentData`, `TName`, `IsNullable`\<`TParentData`\>\>, `unknown`\> = `undefined` + +• **TData** = `DeepValue`\<`TParentData`, `TName`, `IsNullable`\<`TParentData`\>\> + +#### Parameters + +• **fieldConfig**: `FieldOptions`\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\> + +• **render**: `renderCallback`\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\> + +#### Returns + +`object` + +##### values + +```ts +values: object; +``` + +##### values.form + +```ts +form: FormApi; +``` + +##### values.options + +```ts +options: FieldOptions; +``` + +##### values.render + +```ts +render: renderCallback; +``` + +#### Source + +[tanstack-form-controller.ts:112](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/lit-form/src/tanstack-form-controller.ts#L112) + +*** + +### hostConnected() + +```ts +hostConnected(): void +``` + +#### Returns + +`void` + +#### Implementation of + +`ReactiveController.hostConnected` + +#### Source + +[tanstack-form-controller.ts:102](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/lit-form/src/tanstack-form-controller.ts#L102) + +*** + +### hostDisconnected() + +```ts +hostDisconnected(): void +``` + +#### Returns + +`void` + +#### Implementation of + +`ReactiveController.hostDisconnected` + +#### Source + +[tanstack-form-controller.ts:108](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/lit-form/src/tanstack-form-controller.ts#L108) diff --git a/docs/framework/react/reference/Field.md b/docs/framework/react/reference/Field.md deleted file mode 100644 index 980064b55..000000000 --- a/docs/framework/react/reference/Field.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -id: field -title: Field ---- - -### `FieldComponent` - -A type alias representing a field component for a specific form data type. - -```tsx -export type FieldComponent< - TParentData, - TFormValidator extends - | Validator - | undefined = undefined, -> = < - TName extends DeepKeys, - TFieldValidator extends - | Validator, unknown> - | undefined = undefined, - TData extends DeepValue = DeepValue, ->({ - children, - ...fieldOptions -}: FieldComponentProps< - TParentData, - TName, - TFieldValidator, - TFormValidator, - TData ->) => any -``` - -A function component that takes field options and a render function as children and returns a React component. - -### `Field` - -```tsx -export function Field< - TParentData, - TName extends DeepKeys, - TFieldValidator extends - | Validator, unknown> - | undefined = undefined, - TFormValidator extends - | Validator - | undefined = undefined, ->({ - children, - ...fieldOptions -}: { - children: ( - fieldApi: FieldApi, - ) => any -} & UseFieldOptions): JSX.Element -``` - -A functional React component that renders a form field. - -- ```tsx - children: (fieldApi: FieldApi) => any - ``` - - A render function that takes a field API instance and returns a React element. -- ```tsx - fieldOptions: UseFieldOptions - ``` - - The field options. - -The `Field` component uses the `useField` hook internally to manage the field instance. - diff --git a/docs/framework/react/reference/createservervalidate.md b/docs/framework/react/reference/createservervalidate.md new file mode 100644 index 000000000..282fbf0e8 --- /dev/null +++ b/docs/framework/react/reference/createservervalidate.md @@ -0,0 +1,23 @@ +# Function: createServerValidate() + +```ts +function createServerValidate(defaultOpts?): ValidateFormData +``` + +## Type parameters + +• **TFormData** + +• **TFormValidator** *extends* `undefined` \| `Validator`\<`TFormData`, `unknown`\> = `undefined` + +## Parameters + +• **defaultOpts?**: `FormOptions`\<`TFormData`, `TFormValidator`\> + +## Returns + +`ValidateFormData`\<`TFormData`, `TFormValidator`\> + +## Source + +[createServerValidate.ts:40](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/react-form/src/createServerValidate.ts#L40) diff --git a/docs/framework/react/reference/field.md b/docs/framework/react/reference/field.md new file mode 100644 index 000000000..0404c6efb --- /dev/null +++ b/docs/framework/react/reference/field.md @@ -0,0 +1,33 @@ +# Function: Field() + +```ts +function Field(__namedParameters): ReactNode +``` + +A function component that takes field options and a render function as children and returns a React component. + +The `Field` component uses the `useField` hook internally to manage the field instance. + +## Type parameters + +• **TParentData** + +• **TName** *extends* `string` \| `number` + +• **TFieldValidator** *extends* `undefined` \| `Validator`\<`DeepValue`\<`TParentData`, `TName`\>, `unknown`\> = `undefined` + +• **TFormValidator** *extends* `undefined` \| `Validator`\<`TParentData`, `unknown`\> = `undefined` + +• **TData** = `DeepValue`\<`TParentData`, `TName`\> + +## Parameters + +• **\_\_namedParameters**: `FieldComponentProps`\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\> + +## Returns + +`ReactNode` + +## Source + +[useField.tsx:171](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/react-form/src/useField.tsx#L171) diff --git a/docs/framework/react/reference/fieldApi.md b/docs/framework/react/reference/fieldApi.md deleted file mode 100644 index 85738882b..000000000 --- a/docs/framework/react/reference/fieldApi.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -id: fieldApi -title: Field API ---- - -### `FieldApi` - -When using `@tanstack/react-form`, the [core field API](../../../../reference/fieldApi) is extended at type level with additional methods for React-specific functionality: - -- ```tsx - Field: FieldComponent - ``` - - A pre-bound and type-safe sub-field component using this field as a root. diff --git a/docs/framework/react/reference/fieldcomponent.md b/docs/framework/react/reference/fieldcomponent.md new file mode 100644 index 000000000..957401e7d --- /dev/null +++ b/docs/framework/react/reference/fieldcomponent.md @@ -0,0 +1,39 @@ +# Type alias: FieldComponent()\ + +```ts +type FieldComponent: ({ + children, + ...fieldOptions +}) => NodeType; +``` + +A type alias representing a field component for a specific form data type. + +## Type parameters + +• **TParentData** + +• **TFormValidator** *extends* `Validator`\<`TParentData`, `unknown`\> \| `undefined` = `undefined` + +## Type parameters + +• **TName** *extends* `DeepKeys`\<`TParentData`\> + +• **TFieldValidator** *extends* `Validator`\<`DeepValue`\<`TParentData`, `TName`\>, `unknown`\> \| `undefined` = `undefined` + +• **TData** *extends* `DeepValue`\<`TParentData`, `TName`\> = `DeepValue`\<`TParentData`, `TName`\> + +## Parameters + +• **\{ + children, + ...fieldOptions +\}**: `Omit`\<`FieldComponentProps`\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\>, `"form"`\> + +## Returns + +`NodeType` + +## Source + +[useField.tsx:141](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/react-form/src/useField.tsx#L141) diff --git a/docs/framework/react/reference/formApi.md b/docs/framework/react/reference/formApi.md deleted file mode 100644 index 7850deb3e..000000000 --- a/docs/framework/react/reference/formApi.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -id: formApi -title: Form API ---- - -### `FormApi` - -When using `@tanstack/react-form`, the [core form API](../../../../reference/formApi) is extended at type level with additional methods for React-specific functionality: - -- ```tsx - Field: FieldComponent - ``` - - A React component to render form fields. With this, you can render and manage individual form fields. -- ```tsx - useField: UseField - ``` - - A custom React hook that provides functionalities related to individual form fields. It gives you access to field values, errors, and allows you to set or update field values. -- ```tsx - useStore: >>( - selector?: (state: NoInfer>) => TSelected, - ) => TSelected - ``` - - A `useStore` hook that connects to the internal store of the form. It can be used to access the form's current state or any other related state information. You can optionally pass in a selector function to cherry-pick specific parts of the state -- ```tsx - Subscribe: >>(props: { - selector?: (state: NoInfer>) => TSelected - children: ((state: NoInfer) => ReactNode) | ReactNode - }) => JSX.Element - ``` - - A `Subscribe` function that allows you to listen and react to changes in the form's state. It's especially useful when you need to execute side effects or render specific components in response to state updates. - > Note that TypeScript `5.0.4` and older versions will incorrectly complain if the `selector` method doesn't return the form's full state (`state`). This is caused by a [bug in TypeScript](https://github.com/TanStack/form/pull/606#discussion_r1506715714), and you can safely ignore it with `//@ts-expect-error` directive. diff --git a/docs/framework/react/reference/index.md b/docs/framework/react/reference/index.md new file mode 100644 index 000000000..7a03653b5 --- /dev/null +++ b/docs/framework/react/reference/index.md @@ -0,0 +1,18 @@ +# @tanstack/react-form + +## Type Aliases + +- [FieldComponent](fieldcomponent.md) +- [UseField](usefield.md) + +## Variables + +- [initialFormState](initialformstate.md) + +## Functions + +- [Field](field.md) +- [createServerValidate](createservervalidate.md) +- [useField](usefield.md) +- [useForm](useform.md) +- [useTransform](usetransform.md) diff --git a/docs/framework/react/reference/initialformstate.md b/docs/framework/react/reference/initialformstate.md new file mode 100644 index 000000000..fafc1f01c --- /dev/null +++ b/docs/framework/react/reference/initialformstate.md @@ -0,0 +1,29 @@ +# Variable: initialFormState + +```ts +const initialFormState: object; +``` + +## Type declaration + +### errorMap + +```ts +errorMap: object; +``` + +### errorMap.onServer + +```ts +onServer: undefined = undefined; +``` + +### errors + +```ts +errors: never[] = []; +``` + +## Source + +[createServerValidate.ts:72](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/react-form/src/createServerValidate.ts#L72) diff --git a/docs/framework/react/reference/useField.md b/docs/framework/react/reference/useField.md deleted file mode 100644 index e11ccebe1..000000000 --- a/docs/framework/react/reference/useField.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -id: useField -title: useField ---- - -### `UseField` - -A type representing a hook for using a field in a form with the given form data type. - -```tsx -export type UseField = < - TName extends DeepKeys, - TFieldValidator extends - | Validator, unknown> - | undefined = undefined, - TFormValidator extends - | Validator - | undefined = undefined, ->( - opts?: { name: Narrow } & UseFieldOptions< - TParentData, - TName, - TFieldValidator, - TFormValidator - >, -) => FieldApi< - TParentData, - TName, - TFieldValidator, - TFormValidator, - DeepValue -> -``` - -- A function that takes an optional object with a `name` property and field options, and returns a `FieldApi` instance for the specified field. - -### `useField` - -```tsx -export function useField< - TParentData, - TName extends DeepKeys, - TFieldValidator extends - | Validator, unknown> - | undefined = undefined, - TFormValidator extends - | Validator - | undefined = undefined, ->( - opts: UseFieldOptions, -): FieldApi -``` - -A hook for managing a field in a form. - -- ```tsx - opts: UseFieldOptions - ``` - - An object with field options. - -#### Returns - -- ```tsx - FieldApi - ``` - - The `FieldApi` instance for the specified field. diff --git a/docs/framework/react/reference/useForm.md b/docs/framework/react/reference/useForm.md deleted file mode 100644 index 4edce8709..000000000 --- a/docs/framework/react/reference/useForm.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -id: useForm -title: useForm ---- - -### `useForm` - -```tsx -export function useForm< - TFormData, - TFormValidator extends Validator | undefined = undefined, ->( - opts?: FormOptions, -): FormApi -``` -A custom React Hook that returns an instance of the `FormApi` class. -This API encapsulates all the necessary functionalities related to the form. It allows you to manage form state, handle submissions, and interact with form fields - diff --git a/docs/framework/react/reference/usefield.md b/docs/framework/react/reference/usefield.md new file mode 100644 index 000000000..69731e43b --- /dev/null +++ b/docs/framework/react/reference/usefield.md @@ -0,0 +1,35 @@ +# Function: useField() + +```ts +function useField(opts): FieldApi +``` + +A hook for managing a field in a form. + +## Type parameters + +• **TParentData** + +• **TName** *extends* `string` \| `number` + +• **TFieldValidator** *extends* `undefined` \| `Validator`\<`DeepValue`\<`TParentData`, `TName`\>, `unknown`\> = `undefined` + +• **TFormValidator** *extends* `undefined` \| `Validator`\<`TParentData`, `unknown`\> = `undefined` + +• **TData** = `DeepValue`\<`TParentData`, `TName`\> + +## Parameters + +• **opts**: `UseFieldOptions`\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\> + +An object with field options. + +## Returns + +`FieldApi`\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\> + +The `FieldApi` instance for the specified field. + +## Source + +[useField.tsx:60](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/react-form/src/useField.tsx#L60) diff --git a/docs/framework/react/reference/useform.md b/docs/framework/react/reference/useform.md new file mode 100644 index 000000000..7ca1193fe --- /dev/null +++ b/docs/framework/react/reference/useform.md @@ -0,0 +1,27 @@ +# Function: useForm() + +```ts +function useForm(opts?): FormApi +``` + +A custom React Hook that returns an instance of the `FormApi` class. + +This API encapsulates all the necessary functionalities related to the form. It allows you to manage form state, handle submissions, and interact with form fields + +## Type parameters + +• **TFormData** + +• **TFormValidator** *extends* `undefined` \| `Validator`\<`TFormData`, `unknown`\> = `undefined` + +## Parameters + +• **opts?**: `FormOptions`\<`TFormData`, `TFormValidator`\> + +## Returns + +`FormApi`\<`TFormData`, `TFormValidator`\> + +## Source + +[useForm.tsx:56](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/react-form/src/useForm.tsx#L56) diff --git a/docs/framework/react/reference/usetransform.md b/docs/framework/react/reference/usetransform.md new file mode 100644 index 000000000..c54352ec3 --- /dev/null +++ b/docs/framework/react/reference/usetransform.md @@ -0,0 +1,45 @@ +# Function: useTransform() + +```ts +function useTransform(fn, deps): object +``` + +## Type parameters + +• **TFormData** + +• **TFormValidator** *extends* `undefined` \| `Validator`\<`TFormData`, `unknown`\> = `undefined` + +## Parameters + +• **fn** + +• **deps**: `unknown`[] + +## Returns + +`object` + +### deps + +```ts +deps: unknown[]; +``` + +### fn() + +```ts +fn: (formBase) => FormApi; +``` + +#### Parameters + +• **formBase**: `FormApi`\<`any`, `any`\> + +#### Returns + +`FormApi`\<`TFormData`, `TFormValidator`\> + +## Source + +[useTransform.ts:3](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/react-form/src/useTransform.ts#L3) diff --git a/docs/framework/solid/reference/Field.md b/docs/framework/solid/reference/Field.md index f6993cbcb..71521954f 100644 --- a/docs/framework/solid/reference/Field.md +++ b/docs/framework/solid/reference/Field.md @@ -1,6 +1,29 @@ ---- -id: field -title: Field ---- +# Function: Field() -Please see [/packages/solid-form/src/createField.tsx](https://github.com/TanStack/form/blob/main/packages/solid-form/src/createField.tsx) +```ts +function Field(props): Element +``` + +## Type parameters + +• **TParentData** + +• **TName** *extends* `string` \| `number` + +• **TFieldValidator** *extends* `undefined` \| `Validator`\<`DeepValue`\<`TParentData`, `TName`\>, `unknown`\> = `undefined` + +• **TFormValidator** *extends* `undefined` \| `Validator`\<`TParentData`, `unknown`\> = `undefined` + +• **TData** = `DeepValue`\<`TParentData`, `TName`\> + +## Parameters + +• **props**: `object` & `FieldApiOptions`\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\> & `object` + +## Returns + +`Element` + +## Source + +[createField.tsx:166](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/solid-form/src/createField.tsx#L166) diff --git a/docs/framework/solid/reference/createField.md b/docs/framework/solid/reference/createField.md index 7f7963f04..5fd23c5a0 100644 --- a/docs/framework/solid/reference/createField.md +++ b/docs/framework/solid/reference/createField.md @@ -1,6 +1,33 @@ ---- -id: createField -title: createField ---- +# Function: createField() -Please see [/packages/solid-form/src/createField.tsx](https://github.com/TanStack/form/blob/main/packages/solid-form/src/createField.tsx) +```ts +function createField(opts): () => FieldApi +``` + +## Type parameters + +• **TParentData** + +• **TName** *extends* `string` \| `number` + +• **TFieldValidator** *extends* `undefined` \| `Validator`\<`DeepValue`\<`TParentData`, `TName`\>, `unknown`\> = `undefined` + +• **TFormValidator** *extends* `undefined` \| `Validator`\<`TParentData`, `unknown`\> = `undefined` + +• **TData** = `DeepValue`\<`TParentData`, `TName`\> + +## Parameters + +• **opts** + +## Returns + +`Function` + +### Returns + +`FieldApi`\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\> + +## Source + +[createField.tsx:72](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/solid-form/src/createField.tsx#L72) diff --git a/docs/framework/solid/reference/createForm.md b/docs/framework/solid/reference/createForm.md index 79b9ceb8e..b515950f9 100644 --- a/docs/framework/solid/reference/createForm.md +++ b/docs/framework/solid/reference/createForm.md @@ -1,6 +1,23 @@ ---- -id: createForm -title: createForm ---- +# Function: createForm() -Please see [/packages/solid-form/src/createForm.tsx](https://github.com/TanStack/form/blob/main/packages/solid-form/src/createForm.tsx) +```ts +function createForm(opts?): FormApi +``` + +## Type parameters + +• **TParentData** + +• **TFormValidator** *extends* `undefined` \| `Validator`\<`TParentData`, `unknown`\> = `undefined` + +## Parameters + +• **opts?** + +## Returns + +`FormApi`\<`TParentData`, `TFormValidator`\> + +## Source + +[createForm.tsx:29](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/solid-form/src/createForm.tsx#L29) diff --git a/docs/framework/solid/reference/fieldApi.md b/docs/framework/solid/reference/fieldApi.md deleted file mode 100644 index 1f7e0a647..000000000 --- a/docs/framework/solid/reference/fieldApi.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -id: fieldApi -title: Field API ---- - -Please see [/packages/solid-form/src/createField.tsx](https://github.com/TanStack/form/blob/main/packages/solid-form/src/createField.tsx) diff --git a/docs/framework/solid/reference/fieldcomponent.md b/docs/framework/solid/reference/fieldcomponent.md new file mode 100644 index 000000000..a8d08a209 --- /dev/null +++ b/docs/framework/solid/reference/fieldcomponent.md @@ -0,0 +1,37 @@ +# Type alias: FieldComponent()\ + +```ts +type FieldComponent: ({ + children, + ...fieldOptions +}) => JSXElement; +``` + +## Type parameters + +• **TParentData** + +• **TFormValidator** *extends* `Validator`\<`TParentData`, `unknown`\> \| `undefined` = `undefined` + +## Type parameters + +• **TName** *extends* `DeepKeys`\<`TParentData`\> + +• **TFieldValidator** *extends* `Validator`\<`DeepValue`\<`TParentData`, `TName`\>, `unknown`\> \| `undefined` = `undefined` + +• **TData** *extends* `DeepValue`\<`TParentData`, `TName`\> = `DeepValue`\<`TParentData`, `TName`\> + +## Parameters + +• **\{ + children, + ...fieldOptions +\}**: `Omit`\<`FieldComponentProps`\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\>, `"form"`\> + +## Returns + +`JSXElement` + +## Source + +[createField.tsx:141](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/solid-form/src/createField.tsx#L141) diff --git a/docs/framework/solid/reference/formApi.md b/docs/framework/solid/reference/formApi.md deleted file mode 100644 index caf2085ec..000000000 --- a/docs/framework/solid/reference/formApi.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -id: formApi -title: Form API ---- - -Please see [/packages/solid-form/src/createForm.tsx](https://github.com/TanStack/form/blob/main/packages/solid-form/src/createForm.tsx) diff --git a/docs/framework/solid/reference/index.md b/docs/framework/solid/reference/index.md new file mode 100644 index 000000000..442764376 --- /dev/null +++ b/docs/framework/solid/reference/index.md @@ -0,0 +1,12 @@ +# @tanstack/solid-form + +## Type Aliases + +- [CreateField](createfield.md) +- [FieldComponent](fieldcomponent.md) + +## Functions + +- [Field](field.md) +- [createField](createfield.md) +- [createForm](createform.md) diff --git a/docs/framework/vue/reference/Field.md b/docs/framework/vue/reference/Field.md index 854b3e048..35cb6a738 100644 --- a/docs/framework/vue/reference/Field.md +++ b/docs/framework/vue/reference/Field.md @@ -1,6 +1,29 @@ ---- -id: field -title: Field ---- +# Function: Field() -Please see [/packages/vue-form/src/useField.tsx](https://github.com/TanStack/form/blob/main/packages/vue-form/src/useField.tsx) +```ts +function Field(props): any +``` + +## Type parameters + +• **TParentData** + +• **TName** *extends* `string` \| `number` + +• **TFieldValidator** *extends* `undefined` \| `Validator`\<`DeepValue`\<`TParentData`, `TName`\>, `unknown`\> = `undefined` + +• **TFormValidator** *extends* `undefined` \| `Validator`\<`TParentData`, `unknown`\> = `undefined` + +• **TData** = `DeepValue`\<`TParentData`, `TName`\> + +## Parameters + +• **props**: `FieldApiOptions`\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\> & `object` & `object` \| `object` + +## Returns + +`any` + +## Source + +[packages/vue-form/src/useField.tsx:184](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/vue-form/src/useField.tsx#L184) diff --git a/docs/framework/vue/reference/fieldApi.md b/docs/framework/vue/reference/fieldApi.md deleted file mode 100644 index 4e67651aa..000000000 --- a/docs/framework/vue/reference/fieldApi.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -id: fieldApi -title: Field API ---- - -Please see [/packages/vue-form/src/useField.tsx](https://github.com/TanStack/form/blob/main/packages/vue-form/src/useField.tsx) diff --git a/docs/framework/vue/reference/fieldcomponent.md b/docs/framework/vue/reference/fieldcomponent.md new file mode 100644 index 000000000..2e23dd8aa --- /dev/null +++ b/docs/framework/vue/reference/fieldcomponent.md @@ -0,0 +1,33 @@ +# Type alias: FieldComponent()\ + +```ts +type FieldComponent: (fieldOptions, context) => any; +``` + +## Type parameters + +• **TParentData** + +• **TFormValidator** *extends* `Validator`\<`TParentData`, `unknown`\> \| `undefined` = `undefined` + +## Type parameters + +• **TName** *extends* `DeepKeys`\<`TParentData`\> + +• **TFieldValidator** *extends* `Validator`\<`DeepValue`\<`TParentData`, `TName`\>, `unknown`\> \| `undefined` = `undefined` + +• **TData** *extends* `DeepValue`\<`TParentData`, `TName`\> = `DeepValue`\<`TParentData`, `TName`\> + +## Parameters + +• **fieldOptions**: `Omit`\<`FieldComponentProps`\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\>, `"form"`\> + +• **context**: `SetupContext`\<`object`, `SlotsType`\<`object`\>\> + +## Returns + +`any` + +## Source + +[packages/vue-form/src/useField.tsx:139](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/vue-form/src/useField.tsx#L139) diff --git a/docs/framework/vue/reference/formApi.md b/docs/framework/vue/reference/formApi.md deleted file mode 100644 index e4ccb3cf8..000000000 --- a/docs/framework/vue/reference/formApi.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -id: formApi -title: Form API ---- - -Please see [/packages/vue-form/src/useForm.tsx](https://github.com/TanStack/form/blob/main/packages/vue-form/src/useForm.tsx) diff --git a/docs/framework/vue/reference/index.md b/docs/framework/vue/reference/index.md new file mode 100644 index 000000000..e64f686de --- /dev/null +++ b/docs/framework/vue/reference/index.md @@ -0,0 +1,12 @@ +# @tanstack/vue-form + +## Type Aliases + +- [FieldComponent](fieldcomponent.md) +- [UseField](usefield.md) + +## Functions + +- [Field](field.md) +- [useField](usefield.md) +- [useForm](useform.md) diff --git a/docs/framework/vue/reference/useField.md b/docs/framework/vue/reference/useField.md index c792a98ef..1c43d7c6e 100644 --- a/docs/framework/vue/reference/useField.md +++ b/docs/framework/vue/reference/useField.md @@ -1,6 +1,41 @@ ---- -id: useField -title: useField ---- +# Function: useField() -Please see [/packages/vue-form/src/useField.tsx](https://github.com/TanStack/form/blob/main/packages/vue-form/src/useField.tsx) +```ts +function useField(opts): object +``` + +## Type parameters + +• **TParentData** + +• **TName** *extends* `string` \| `number` + +• **TFieldValidator** *extends* `undefined` \| `Validator`\<`DeepValue`\<`TParentData`, `TName`\>, `unknown`\> = `undefined` + +• **TFormValidator** *extends* `undefined` \| `Validator`\<`TParentData`, `unknown`\> = `undefined` + +• **TData** = `DeepValue`\<`TParentData`, `TName`\> + +## Parameters + +• **opts**: `UseFieldOptions`\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\> + +## Returns + +`object` + +### api + +```ts +api: FieldApi; +``` + +### state + +```ts +state: Readonly["state"]>>; +``` + +## Source + +[packages/vue-form/src/useField.tsx:61](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/vue-form/src/useField.tsx#L61) diff --git a/docs/framework/vue/reference/useForm.md b/docs/framework/vue/reference/useForm.md index ed702816c..4bf6ad66c 100644 --- a/docs/framework/vue/reference/useForm.md +++ b/docs/framework/vue/reference/useForm.md @@ -1,6 +1,23 @@ ---- -id: useForm -title: useForm ---- +# Function: useForm() -Please see [/packages/vue-form/src/useForm.tsx](https://github.com/TanStack/form/blob/main/packages/vue-form/src/useForm.tsx) +```ts +function useForm(opts?): FormApi +``` + +## Type parameters + +• **TFormData** + +• **TFormValidator** *extends* `undefined` \| `Validator`\<`TFormData`, `unknown`\> = `undefined` + +## Parameters + +• **opts?**: `FormOptions`\<`TFormData`, `TFormValidator`\> + +## Returns + +`FormApi`\<`TFormData`, `TFormValidator`\> + +## Source + +[packages/vue-form/src/useForm.tsx:30](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/vue-form/src/useForm.tsx#L30) diff --git a/docs/reference/deepkeys.md b/docs/reference/deepkeys.md new file mode 100644 index 000000000..824b998f2 --- /dev/null +++ b/docs/reference/deepkeys.md @@ -0,0 +1,17 @@ +# Type alias: DeepKeys\ + +```ts +type DeepKeys: TDepth["length"] extends 5 ? never : unknown extends T ? PrefixFromDepth : T extends readonly any[] & IsTuple ? PrefixTupleAccessor, TDepth> : T extends any[] ? PrefixArrayAccessor : T extends Date ? never : T extends object ? PrefixObjectAccessor : T extends string | number | boolean | bigint ? "" : never; +``` + +The keys of an object or array, deeply nested. + +## Type parameters + +• **T** + +• **TDepth** *extends* `any`[] = [] + +## Source + +[packages/form-core/src/util-types.ts:85](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/util-types.ts#L85) diff --git a/docs/reference/deepvalue.md b/docs/reference/deepvalue.md new file mode 100644 index 000000000..4ed88e798 --- /dev/null +++ b/docs/reference/deepvalue.md @@ -0,0 +1,19 @@ +# Type alias: DeepValue\ + +```ts +type DeepValue: unknown extends TValue ? TValue : TValue extends ReadonlyArray ? TAccessor extends `[${infer TBrackets}].${infer TAfter}` ? DeepValue, TAfter> : TAccessor extends `[${infer TBrackets}]` ? DeepValue : TAccessor extends keyof TValue ? TValue[TAccessor] : TValue[TAccessor & number] : TValue extends Record ? TAccessor extends `${infer TBefore}[${infer TEverythingElse}` ? DeepValue, `[${TEverythingElse}`> : TAccessor extends `[${infer TBrackets}]` ? DeepValue : TAccessor extends `${infer TBefore}.${infer TAfter}` ? DeepValue, TAfter> : TAccessor extends string ? TNullable extends true ? Nullable : TValue[TAccessor] : never : never; +``` + +Infer the type of a deeply nested property within an object or an array. + +## Type parameters + +• **TValue** + +• **TAccessor** + +• **TNullable** *extends* `boolean` = `IsNullable`\<`TValue`\> + +## Source + +[packages/form-core/src/util-types.ts:109](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/util-types.ts#L109) diff --git a/docs/reference/fieldApi.md b/docs/reference/fieldApi.md deleted file mode 100644 index 1c39e7509..000000000 --- a/docs/reference/fieldApi.md +++ /dev/null @@ -1,320 +0,0 @@ ---- -id: fieldApi -title: 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. - -```tsx -const fieldApi: FieldApi = new FieldApi(formOptions: FieldOptions) -``` - -### `FieldOptions` - -An object type representing the options for a field in a form. - -- ```tsx - name: TName - ``` - - - The field name. The type will be `DeepKeys` to ensure your name is a deep key of the parent dataset. - -- ```tsx - defaultValue?: TData - ``` - - - An optional default value for the field. - -- ```tsx - defaultMeta?: Partial - ``` - - - An optional object with default metadata for the field. - -- ```tsx - asyncDebounceMs?: number - ``` - - - The default time to debounce async validation if there is not a more specific debounce time passed. - -- ```tsx - asyncAlways?: boolean - ``` - - - If `true`, always run async validation, even if there are errors emitted during synchronous validation. - -- ```typescript - validatorAdapter?: ValidatorType - ``` - - - A validator provided by an extension, like `yupValidator` from `@tanstack/yup-form-adapter` - -- ```tsx - validators?: FieldValidators< - TParentData, - TName, - TFieldValidator, - TFormValidator, - TData - > - ``` - - A list of validators to pass to the field - -### `FieldValidators` - -- ```tsx - onMount?: (formApi: FieldApi) => void - ``` - - - An optional function that takes a param of `formApi` which is a generic type of `TData` and `TParentData` - -- ```tsx - onChange?: ValidateFn - ``` - - - An optional property that takes a `ValidateFn` which is a generic of `TData` and `TParentData`. If `validator` is passed, this may also accept a property from the respective validator (IE: `z.string().min(1)` if `zodAdapter` is passed) - -- ```tsx - onChangeAsync?: ValidateAsyncFn - ``` - - - An optional property similar to `onChange` but async validation. If `validator` is passed, this may also accept a property from the respective validator (IE: `z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' })` if `zodAdapter` is passed) - -- ```tsx - 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 - -- ```tsx - onChangeListenTo?: DeepKeys[] - ``` - - - An optional list of field names that should trigger **this** field's `onChange` and `onChangeAsync` events when **its** value changes - -- ```tsx - onBlur?: ValidateFn - ``` - - - An optional function, when that run when subscribing to blur event of input. If `validator` is passed, this may also accept a property from the respective validator (IE: `z.string().min(1)` if `zodAdapter` is passed) - -- ```tsx - onBlurAsync?: ValidateAsyncFn - ``` - - - An optional function that takes a `ValidateFn` which is a generic of `TData` and `TParentData` happens async. If `validator` is passed, this may also accept a property from the respective validator (IE: `z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' })` if `zodAdapter` is passed) - - ```tsx - 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 - -- ```tsx - onBlurListenTo?: DeepKeys[] - ``` - - - An optional list of field names that should trigger **this** field's `onBlur` and `onBlurAsync` events when **its** field blurs - -- ```tsx - onSubmit?: ValidateFn - ``` - - - An optional function, when that run when subscribing to submit event of input. If `validator` is passed, this may also accept a property from the respective validator (IE: `z.string().min(1)` if `zodAdapter` is passed) - -- ```tsx - onSubmitAsync?: ValidateAsyncFn - ``` - - - An optional function that takes a `ValidateFn` which is a generic of `TData` and `TParentData` happens async. If `validator` is passed, this may also accept a property from the respective validator (IE: `z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' })` if `zodAdapter` is passed) - - ```tsx - onSubmitAsyncDebounceMs?: number - ``` - - - An optional number to represent how long the `onSubmitAsyncDebounceMs` 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 - -### `FieldMeta` - -An object type representing the metadata of a field in a form. - -- ```tsx - isPristine: boolean - ``` - - A flag that is `true` if the field's value have not been modified by the user. Opposite of `isDirty`. -- ```tsx - isDirty: boolean - ``` - - A flag that is `true` if the field's value have been modified by the user. Opposite of `isPristine`. -- ```tsx - isTouched: boolean - ``` - - A flag indicating whether the field has been touched. -- ```tsx - touchedErrors: ValidationError[] - ``` - - An array of errors related to the touched state of the field. -- ```tsx - errors: ValidationError[] - ``` - - An array of errors related related to the field value. -- ```tsx - errorMap: ValidationErrorMap - ``` - - A map of errors related related to the field value. -- ```tsx - isValidating: boolean - ``` - - A flag indicating whether the field is currently being validated. - -### `FieldApiOptions` - -An object type representing the required options for the `FieldApi` class. - -- Inherits from `FieldOptions` with the `form` property set as required. - -### `FieldApi` - -A class representing the API for managing a form field. - -#### Properties - -- ```tsx - form: FormApi - ``` - - A reference to the form API instance. -- ```tsx - name: DeepKeys - ``` - - The field name. -- ```tsx - store: Store> - ``` - - The field state store. -- ```tsx - state: FieldState - ``` - - The current field state. -- ```tsx - options: RequiredByKey, 'validateOn'> - ``` - - The field options with the `validateOn` property set as required. - -#### Methods - -- ```tsx - constructor(opts: FieldApiOptions) - ``` - - - Initializes a new `FieldApi` instance. - -- ```tsx - mount(): () => void - ``` - - - Mounts the field instance to the form. - -- ```tsx - update(opts: FieldApiOptions): void - ``` - - - Updates the field instance with new options. - -- ```tsx - getValue(): TData - ``` - - - Gets the current field value. - -- ```tsx - setValue(updater: Updater, options?: { touch?: boolean; notify?: boolean }): void - ``` - - - Sets the field value and run the `change` validator. - -- ```tsx - getMeta(): FieldMeta - ``` - - - Gets the current field metadata. - -- ```tsx - setMeta(updater: Updater): void - ``` - - - Sets the field metadata. - -- ```tsx - getInfo(): any - ``` - - - Gets the field information object. - -- ```tsx - pushValue(value: TData, opts?: { touch?: boolean }): void - ``` - - - Pushes a new value to the field. - -- ```tsx - insertValue(index: number, value: TData, opts?: { touch?: boolean }): void - ``` - - - Inserts a value at the specified index, shifting the subsequent values to the right. - -- ```tsx - replaceValue(index: number, value: TData): void - ``` - - Replaces a value at the specified index. - -- ```tsx - removeValue(index: number, opts?: { touch?: boolean }): Promise - ``` - - - Removes a value at the specified index. - -- ```tsx - swapValues(aIndex: number, bIndex: number, opts?: { touch?: boolean }): void - ``` - - - Swaps the values at the specified indices. -- ```tsx - moveValue(aIndex: number, bIndex: number, opts?: { touch?: boolean }) - ``` - - - Moves the value at the first specified index to the second specified index. - -- ```tsx - validate(): Promise - ``` - - - Validates the field value. - -- ```tsx - handleBlur(): void; - ``` - - - Handles the blur event. - -- ```tsx - handleChange(value: TData): void - ``` - - Handles the change event. - -### `FieldState` - -An object type representing the state of a field. - -- ```tsx - value: TData - ``` - - The current value of the field. -- ```tsx - meta: FieldMeta - ``` - - The current metadata of the field. diff --git a/docs/reference/fieldapi.md b/docs/reference/fieldapi.md new file mode 100644 index 000000000..b402af058 --- /dev/null +++ b/docs/reference/fieldapi.md @@ -0,0 +1,499 @@ +# Class: FieldApi\ + +A class representing the API for managing a form field. + +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 uses your framework's reactivity model. +However, if you need to create a new instance manually, you can do so by calling +the `new FieldApi` constructor. + +## Type parameters + +• **TParentData** + +• **TName** *extends* [`DeepKeys`](deepkeys.md)\<`TParentData`\> + +• **TFieldValidator** *extends* `Validator`\<[`DeepValue`](deepvalue.md)\<`TParentData`, `TName`\>, `unknown`\> \| `undefined` = `undefined` + +• **TFormValidator** *extends* `Validator`\<`TParentData`, `unknown`\> \| `undefined` = `undefined` + +• **TData** *extends* [`DeepValue`](deepvalue.md)\<`TParentData`, `TName`\> = [`DeepValue`](deepvalue.md)\<`TParentData`, `TName`\> + +## Constructors + +### new FieldApi() + +```ts +new FieldApi(opts): FieldApi +``` + +Initializes a new `FieldApi` instance. + +#### Parameters + +• **opts**: [`FieldApiOptions`](fieldapioptions.md)\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\> + +#### Returns + +[`FieldApi`](fieldapi.md)\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\> + +#### Source + +[packages/form-core/src/FieldApi.ts:436](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L436) + +## Properties + +### form + +```ts +form: FormApi; +``` + +A reference to the form API instance. + +#### Source + +[packages/form-core/src/FieldApi.ts:399](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L399) + +*** + +### name + +```ts +name: unknown extends TParentData ? string : TParentData extends readonly any[] & IsTuple ? PrefixTupleAccessor, AllowedIndexes, never>, []> : TParentData extends any[] ? PrefixArrayAccessor, [any]> : TParentData extends Date ? never : TParentData extends object ? PrefixObjectAccessor, []> : TParentData extends string | number | bigint | boolean ? "" : never; +``` + +The field name. + +#### Source + +[packages/form-core/src/FieldApi.ts:409](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L409) + +*** + +### options + +```ts +options: FieldApiOptions; +``` + +The field options. + +#### Source + +[packages/form-core/src/FieldApi.ts:413](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L413) + +*** + +### state + +```ts +state: FieldState; +``` + +The current field state. + +#### Source + +[packages/form-core/src/FieldApi.ts:427](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L427) + +*** + +### store + +```ts +store: Store, (cb) => FieldState>; +``` + +The field state store. + +#### Source + +[packages/form-core/src/FieldApi.ts:423](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L423) + +## Methods + +### getInfo() + +```ts +getInfo(): FieldInfo +``` + +Gets the field information object. + +#### Returns + +[`FieldInfo`](fieldinfo.md)\<`TParentData`, `TFormValidator`\> + +#### Source + +[packages/form-core/src/FieldApi.ts:652](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L652) + +*** + +### getMeta() + +```ts +getMeta(): FieldMeta +``` + +Gets the current field metadata. + +#### Returns + +[`FieldMeta`](fieldmeta.md) + +#### Source + +[packages/form-core/src/FieldApi.ts:630](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L630) + +*** + +### getValue() + +```ts +getValue(): TData +``` + +Gets the current field value. + +#### Returns + +`TData` + +#### Source + +[packages/form-core/src/FieldApi.ts:607](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L607) + +*** + +### handleBlur() + +```ts +handleBlur(): void +``` + +Handles the blur event. + +#### Returns + +`void` + +#### Source + +[packages/form-core/src/FieldApi.ts:962](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L962) + +*** + +### handleChange() + +```ts +handleChange(updater): void +``` + +Handles the change event. + +#### Parameters + +• **updater**: [`Updater`](updater.md)\<`TData`\> + +#### Returns + +`void` + +#### Source + +[packages/form-core/src/FieldApi.ts:955](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L955) + +*** + +### insertValue() + +```ts +insertValue( + index, + value, +opts?): Promise +``` + +Inserts a value at the specified index, shifting the subsequent values to the right. + +#### Parameters + +• **index**: `number` + +• **value**: `TData` *extends* `any`[] ? `TData`\<`TData`\>\[`number`\] : `never` + +• **opts?** + +• **opts.touch?**: `boolean` + +#### Returns + +`Promise`\<`void`\> + +#### Source + +[packages/form-core/src/FieldApi.ts:665](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L665) + +*** + +### mount() + +```ts +mount(): () => void +``` + +Mounts the field instance to the form. + +#### Returns + +`Function` + +##### Returns + +`void` + +#### Source + +[packages/form-core/src/FieldApi.ts:524](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L524) + +*** + +### moveValue() + +```ts +moveValue( + aIndex, + bIndex, + opts?): void +``` + +Moves the value at the first specified index to the second specified index. + +#### Parameters + +• **aIndex**: `number` + +• **bIndex**: `number` + +• **opts?** + +• **opts.touch?**: `boolean` + +#### Returns + +`void` + +#### Source + +[packages/form-core/src/FieldApi.ts:695](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L695) + +*** + +### pushValue() + +```ts +pushValue(value, opts?): void +``` + +Pushes a new value to the field. + +#### Parameters + +• **value**: `TData` *extends* `any`[] ? `TData`\<`TData`\>\[`number`\] : `never` + +• **opts?** + +• **opts.touch?**: `boolean` + +#### Returns + +`void` + +#### Source + +[packages/form-core/src/FieldApi.ts:657](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L657) + +*** + +### removeValue() + +```ts +removeValue(index, opts?): Promise +``` + +Removes a value at the specified index. + +#### Parameters + +• **index**: `number` + +• **opts?** + +• **opts.touch?**: `boolean` + +#### Returns + +`Promise`\<`void`\> + +#### Source + +[packages/form-core/src/FieldApi.ts:683](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L683) + +*** + +### replaceValue() + +```ts +replaceValue( + index, + value, +opts?): Promise +``` + +Replaces a value at the specified index. + +#### Parameters + +• **index**: `number` + +• **value**: `TData` *extends* `any`[] ? `TData`\<`TData`\>\[`number`\] : `never` + +• **opts?** + +• **opts.touch?**: `boolean` + +#### Returns + +`Promise`\<`void`\> + +#### Source + +[packages/form-core/src/FieldApi.ts:674](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L674) + +*** + +### setMeta() + +```ts +setMeta(updater): void +``` + +Sets the field metadata. + +#### Parameters + +• **updater**: [`Updater`](updater.md)\<[`FieldMeta`](fieldmeta.md)\> + +#### Returns + +`void` + +#### Source + +[packages/form-core/src/FieldApi.ts:646](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L646) + +*** + +### setValue() + +```ts +setValue(updater, options?): void +``` + +Sets the field value and run the `change` validator. + +#### Parameters + +• **updater**: [`Updater`](updater.md)\<`TData`\> + +• **options?** + +• **options.notify?**: `boolean` + +• **options.touch?**: `boolean` + +#### Returns + +`void` + +#### Source + +[packages/form-core/src/FieldApi.ts:614](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L614) + +*** + +### swapValues() + +```ts +swapValues( + aIndex, + bIndex, + opts?): void +``` + +Swaps the values at the specified indices. + +#### Parameters + +• **aIndex**: `number` + +• **bIndex**: `number` + +• **opts?** + +• **opts.touch?**: `boolean` + +#### Returns + +`void` + +#### Source + +[packages/form-core/src/FieldApi.ts:689](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L689) + +*** + +### update() + +```ts +update(opts): void +``` + +Updates the field instance with new options. + +#### Parameters + +• **opts**: [`FieldApiOptions`](fieldapioptions.md)\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\> + +#### Returns + +`void` + +#### Source + +[packages/form-core/src/FieldApi.ts:575](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L575) + +*** + +### validate() + +```ts +validate(cause): ValidationError[] | Promise +``` + +Validates the field value. + +#### Parameters + +• **cause**: `ValidationCause` + +#### Returns + +[`ValidationError`](validationerror.md)[] \| `Promise`\<[`ValidationError`](validationerror.md)[]\> + +#### Source + +[packages/form-core/src/FieldApi.ts:932](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L932) diff --git a/docs/reference/fieldapioptions.md b/docs/reference/fieldapioptions.md new file mode 100644 index 000000000..23efd0f6b --- /dev/null +++ b/docs/reference/fieldapioptions.md @@ -0,0 +1,173 @@ +# Interface: FieldApiOptions\ + +An object type representing the required options for the FieldApi class. + +## Extends + +- [`FieldOptions`](fieldoptions.md)\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\> + +## Type parameters + +• **TParentData** + +• **TName** *extends* [`DeepKeys`](deepkeys.md)\<`TParentData`\> + +• **TFieldValidator** *extends* `Validator`\<[`DeepValue`](deepvalue.md)\<`TParentData`, `TName`\>, `unknown`\> \| `undefined` = `undefined` + +• **TFormValidator** *extends* `Validator`\<`TParentData`, `unknown`\> \| `undefined` = `undefined` + +• **TData** *extends* [`DeepValue`](deepvalue.md)\<`TParentData`, `TName`\> = [`DeepValue`](deepvalue.md)\<`TParentData`, `TName`\> + +## Properties + +### asyncAlways? + +```ts +optional asyncAlways: boolean; +``` + +If `true`, always run async validation, even if there are errors emitted during synchronous validation. + +#### Inherited from + +[`FieldOptions`](fieldoptions.md).[`asyncAlways`](Interface.FieldOptions.md#asyncalways) + +#### Source + +[packages/form-core/src/FieldApi.ts:283](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L283) + +*** + +### asyncDebounceMs? + +```ts +optional asyncDebounceMs: number; +``` + +The default time to debounce async validation if there is not a more specific debounce time passed. + +#### Inherited from + +[`FieldOptions`](fieldoptions.md).[`asyncDebounceMs`](Interface.FieldOptions.md#asyncdebouncems) + +#### Source + +[packages/form-core/src/FieldApi.ts:279](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L279) + +*** + +### defaultMeta? + +```ts +optional defaultMeta: Partial; +``` + +An optional object with default metadata for the field. + +#### Inherited from + +[`FieldOptions`](fieldoptions.md).[`defaultMeta`](Interface.FieldOptions.md#defaultmeta) + +#### Source + +[packages/form-core/src/FieldApi.ts:302](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L302) + +*** + +### defaultValue? + +```ts +optional defaultValue: NoInfer; +``` + +An optional default value for the field. + +#### Inherited from + +[`FieldOptions`](fieldoptions.md).[`defaultValue`](Interface.FieldOptions.md#defaultvalue) + +#### Source + +[packages/form-core/src/FieldApi.ts:275](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L275) + +*** + +### form + +```ts +form: FormApi; +``` + +#### Source + +[packages/form-core/src/FieldApi.ts:325](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L325) + +*** + +### name + +```ts +name: TName; +``` + +The field name. The type will be `DeepKeys` to ensure your name is a deep key of the parent dataset. + +#### Inherited from + +[`FieldOptions`](fieldoptions.md).[`name`](Interface.FieldOptions.md#name) + +#### Source + +[packages/form-core/src/FieldApi.ts:271](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L271) + +*** + +### preserveValue? + +```ts +optional preserveValue: boolean; +``` + +#### Inherited from + +[`FieldOptions`](fieldoptions.md).[`preserveValue`](Interface.FieldOptions.md#preservevalue) + +#### Source + +[packages/form-core/src/FieldApi.ts:284](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L284) + +*** + +### validatorAdapter? + +```ts +optional validatorAdapter: TFieldValidator; +``` + +A validator provided by an extension, like `yupValidator` from `@tanstack/yup-form-adapter` + +#### Inherited from + +[`FieldOptions`](fieldoptions.md).[`validatorAdapter`](Interface.FieldOptions.md#validatoradapter) + +#### Source + +[packages/form-core/src/FieldApi.ts:288](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L288) + +*** + +### validators? + +```ts +optional validators: FieldValidators; +``` + +A list of validators to pass to the field + +#### Inherited from + +[`FieldOptions`](fieldoptions.md).[`validators`](Interface.FieldOptions.md#validators) + +#### Source + +[packages/form-core/src/FieldApi.ts:292](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L292) diff --git a/docs/reference/fieldinfo.md b/docs/reference/fieldinfo.md new file mode 100644 index 000000000..40facef3b --- /dev/null +++ b/docs/reference/fieldinfo.md @@ -0,0 +1,35 @@ +# Type alias: FieldInfo\ + +```ts +type FieldInfo: object; +``` + +An object representing the field information for a specific field within the form. + +## Type parameters + +• **TFormData** + +• **TFormValidator** *extends* `Validator`\<`TFormData`, `unknown`\> \| `undefined` = `undefined` + +## Type declaration + +### instance + +```ts +instance: FieldApi | undefined, TFormValidator> | null; +``` + +An instance of the FieldAPI. + +### validationMetaMap + +```ts +validationMetaMap: Record; +``` + +A record of field validation internal handling. + +## Source + +[packages/form-core/src/FormApi.ts:175](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L175) diff --git a/docs/reference/fieldmeta.md b/docs/reference/fieldmeta.md new file mode 100644 index 000000000..0bc5414cf --- /dev/null +++ b/docs/reference/fieldmeta.md @@ -0,0 +1,69 @@ +# Type alias: FieldMeta + +```ts +type FieldMeta: object; +``` + +An object type representing the metadata of a field in a form. + +## Type declaration + +### errorMap + +```ts +errorMap: ValidationErrorMap; +``` + +A map of errors related to the field value. + +### errors + +```ts +errors: ValidationError[]; +``` + +An array of errors related to the field value. + +### isDirty + +```ts +isDirty: boolean; +``` + +A flag that is `true` if the field's value has been modified by the user. Opposite of `isPristine`. + +### isPristine + +```ts +isPristine: boolean; +``` + +A flag that is `true` if the field's value has not been modified by the user. Opposite of `isDirty`. + +### isTouched + +```ts +isTouched: boolean; +``` + +A flag indicating whether the field has been touched. + +### isValidating + +```ts +isValidating: boolean; +``` + +A flag indicating whether the field is currently being validated. + +### touchedErrors + +```ts +touchedErrors: ValidationError[]; +``` + +An array of errors related to the touched state of the field. + +## Source + +[packages/form-core/src/FieldApi.ts:331](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L331) diff --git a/docs/reference/fieldoptions.md b/docs/reference/fieldoptions.md new file mode 100644 index 000000000..cbb54f05a --- /dev/null +++ b/docs/reference/fieldoptions.md @@ -0,0 +1,129 @@ +# Interface: FieldOptions\ + +An object type representing the options for a field in a form. + +## Extended by + +- [`FieldApiOptions`](fieldapioptions.md) + +## Type parameters + +• **TParentData** + +• **TName** *extends* [`DeepKeys`](deepkeys.md)\<`TParentData`\> + +• **TFieldValidator** *extends* `Validator`\<[`DeepValue`](deepvalue.md)\<`TParentData`, `TName`\>, `unknown`\> \| `undefined` = `undefined` + +• **TFormValidator** *extends* `Validator`\<`TParentData`, `unknown`\> \| `undefined` = `undefined` + +• **TData** *extends* [`DeepValue`](deepvalue.md)\<`TParentData`, `TName`\> = [`DeepValue`](deepvalue.md)\<`TParentData`, `TName`\> + +## Properties + +### asyncAlways? + +```ts +optional asyncAlways: boolean; +``` + +If `true`, always run async validation, even if there are errors emitted during synchronous validation. + +#### Source + +[packages/form-core/src/FieldApi.ts:283](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L283) + +*** + +### asyncDebounceMs? + +```ts +optional asyncDebounceMs: number; +``` + +The default time to debounce async validation if there is not a more specific debounce time passed. + +#### Source + +[packages/form-core/src/FieldApi.ts:279](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L279) + +*** + +### defaultMeta? + +```ts +optional defaultMeta: Partial; +``` + +An optional object with default metadata for the field. + +#### Source + +[packages/form-core/src/FieldApi.ts:302](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L302) + +*** + +### defaultValue? + +```ts +optional defaultValue: NoInfer; +``` + +An optional default value for the field. + +#### Source + +[packages/form-core/src/FieldApi.ts:275](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L275) + +*** + +### name + +```ts +name: TName; +``` + +The field name. The type will be `DeepKeys` to ensure your name is a deep key of the parent dataset. + +#### Source + +[packages/form-core/src/FieldApi.ts:271](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L271) + +*** + +### preserveValue? + +```ts +optional preserveValue: boolean; +``` + +#### Source + +[packages/form-core/src/FieldApi.ts:284](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L284) + +*** + +### validatorAdapter? + +```ts +optional validatorAdapter: TFieldValidator; +``` + +A validator provided by an extension, like `yupValidator` from `@tanstack/yup-form-adapter` + +#### Source + +[packages/form-core/src/FieldApi.ts:288](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L288) + +*** + +### validators? + +```ts +optional validators: FieldValidators; +``` + +A list of validators to pass to the field + +#### Source + +[packages/form-core/src/FieldApi.ts:292](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L292) diff --git a/docs/reference/fieldstate.md b/docs/reference/fieldstate.md new file mode 100644 index 000000000..acf3bc9c9 --- /dev/null +++ b/docs/reference/fieldstate.md @@ -0,0 +1,33 @@ +# Type alias: FieldState\ + +```ts +type FieldState: object; +``` + +An object type representing the state of a field. + +## Type parameters + +• **TData** + +## Type declaration + +### meta + +```ts +meta: FieldMeta; +``` + +The current metadata of the field. + +### value + +```ts +value: TData; +``` + +The current value of the field. + +## Source + +[packages/form-core/src/FieldApi.ts:365](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L365) diff --git a/docs/reference/fieldvalidators.md b/docs/reference/fieldvalidators.md new file mode 100644 index 000000000..45bc671e8 --- /dev/null +++ b/docs/reference/fieldvalidators.md @@ -0,0 +1,213 @@ +# Interface: FieldValidators\ + +## Type parameters + +• **TParentData** + +• **TName** *extends* [`DeepKeys`](deepkeys.md)\<`TParentData`\> + +• **TFieldValidator** *extends* `Validator`\<[`DeepValue`](deepvalue.md)\<`TParentData`, `TName`\>, `unknown`\> \| `undefined` = `undefined` + +• **TFormValidator** *extends* `Validator`\<`TParentData`, `unknown`\> \| `undefined` = `undefined` + +• **TData** *extends* [`DeepValue`](deepvalue.md)\<`TParentData`, `TName`\> = [`DeepValue`](deepvalue.md)\<`TParentData`, `TName`\> + +## Properties + +### onBlur? + +```ts +optional onBlur: FieldValidateOrFn; +``` + +An optional function, that when run when subscribing to blur event of input. +If `validatorAdapter` is passed, this may also accept a property from the respective adapter + +#### Example + +```ts +`z.string().min(1)` if `zodAdapter` is passed +``` + +#### Source + +[packages/form-core/src/FieldApi.ts:195](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L195) + +*** + +### onBlurAsync? + +```ts +optional onBlurAsync: FieldAsyncValidateOrFn; +``` + +An optional property similar to `onBlur` but async validation. If `validatorAdapter` +is passed, this may also accept a property from the respective adapter + +#### Example + +```ts +`z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' })` if `zodAdapter` is passed +``` + +#### Source + +[packages/form-core/src/FieldApi.ts:208](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L208) + +*** + +### onBlurAsyncDebounceMs? + +```ts +optional onBlurAsyncDebounceMs: number; +``` + +An optional number to represent how long the `onBlurAsync` 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 + +#### Source + +[packages/form-core/src/FieldApi.ts:221](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L221) + +*** + +### onBlurListenTo? + +```ts +optional onBlurListenTo: unknown extends TParentData ? string : TParentData extends readonly any[] & IsTuple ? PrefixTupleAccessor, AllowedIndexes, never>, []> : TParentData extends any[] ? PrefixArrayAccessor, [any]> : TParentData extends Date ? never : TParentData extends object ? PrefixObjectAccessor, []> : TParentData extends string | number | bigint | boolean ? "" : never[]; +``` + +An optional list of field names that should trigger this field's `onBlur` and `onBlurAsync` events when its value changes + +#### Source + +[packages/form-core/src/FieldApi.ts:225](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L225) + +*** + +### onChange? + +```ts +optional onChange: FieldValidateOrFn; +``` + +An optional property that takes a `ValidateFn` which is a generic of `TData` and `TParentData`. +If `validatorAdapter` is passed, this may also accept a property from the respective adapter + +#### Example + +```ts +`z.string().min(1)` if `zodAdapter` is passed +``` + +#### Source + +[packages/form-core/src/FieldApi.ts:159](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L159) + +*** + +### onChangeAsync? + +```ts +optional onChangeAsync: FieldAsyncValidateOrFn; +``` + +An optional property similar to `onChange` but async validation. If `validatorAdapter` +is passed, this may also accept a property from the respective adapter + +#### Example + +```ts +`z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' })` if `zodAdapter` is passed +``` + +#### Source + +[packages/form-core/src/FieldApi.ts:172](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L172) + +*** + +### onChangeAsyncDebounceMs? + +```ts +optional 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 + +#### Source + +[packages/form-core/src/FieldApi.ts:184](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L184) + +*** + +### onChangeListenTo? + +```ts +optional onChangeListenTo: unknown extends TParentData ? string : TParentData extends readonly any[] & IsTuple ? PrefixTupleAccessor, AllowedIndexes, never>, []> : TParentData extends any[] ? PrefixArrayAccessor, [any]> : TParentData extends Date ? never : TParentData extends object ? PrefixObjectAccessor, []> : TParentData extends string | number | bigint | boolean ? "" : never[]; +``` + +An optional list of field names that should trigger this field's `onChange` and `onChangeAsync` events when its value changes + +#### Source + +[packages/form-core/src/FieldApi.ts:188](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L188) + +*** + +### onMount? + +```ts +optional onMount: FieldValidateOrFn; +``` + +An optional function that takes a param of `formApi` which is a generic type of `TData` and `TParentData` + +#### Source + +[packages/form-core/src/FieldApi.ts:146](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L146) + +*** + +### onSubmit? + +```ts +optional onSubmit: FieldValidateOrFn; +``` + +An optional function, that when run when subscribing to submit event of input. +If `validatorAdapter` is passed, this may also accept a property from the respective adapter + +#### Example + +```ts +`z.string().min(1)` if `zodAdapter` is passed +``` + +#### Source + +[packages/form-core/src/FieldApi.ts:232](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L232) + +*** + +### onSubmitAsync? + +```ts +optional onSubmitAsync: FieldAsyncValidateOrFn; +``` + +An optional property similar to `onSubmit` but async validation. If `validatorAdapter` +is passed, this may also accept a property from the respective adapter + +#### Example + +```ts +`z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' })` if `zodAdapter` is passed +``` + +#### Source + +[packages/form-core/src/FieldApi.ts:245](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FieldApi.ts#L245) diff --git a/docs/reference/formApi.md b/docs/reference/formApi.md deleted file mode 100644 index fa5e3b18a..000000000 --- a/docs/reference/formApi.md +++ /dev/null @@ -1,319 +0,0 @@ ---- -id: formApi -title: 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. - -```tsx -const formApi: FormApi = new FormApi(formOptions: FormOptions) -``` - -### `FormOptions` - -An object representing the options for a form. - -- ```tsx - asyncDebounceMs?: number - ``` - - Optional time in milliseconds if you want to introduce a delay before firing off an async action. - -- ```tsx - asyncAlways?: boolean - ``` - - If true, always run async validation, even when sync validation has produced an error. Defaults to `undefined`. - -- ```tsx - defaultValues?: TData - ``` - - Set initial values for your form. - -- ```tsx - defaultState?: Partial> - ``` - - The default state for the form. - -- ```tsx - onSubmit?: (values: TData, formApi: FormApi) => any | Promise - ``` - - 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` - -- ```tsx - onSubmitInvalid?: (values: TData, formApi: FormApi) => void - ``` - - Specify an action for scenarios where the user tries to submit an invalid form. - -- ```tsx - validatorAdapter?: TFormValidator - ``` - - A validator adapter to support usage of extra validation types (IE: Zod, Yup, or Valibot usage) - -- ```tsx - validators?: FormValidators - ``` - - A list of validators to pass to the form - -### `FormValidators` - -- ```tsx - onMount?: (values: TData, formApi: FormApi) => ValidationError - ``` - - Optional function that fires as soon as the component mounts. - -- ```tsx - onChange?: (values: TData, formApi: FormApi) => ValidationError - ``` - - Optional function that checks the validity of your data whenever a value changes - -- ```tsx - onChangeAsync?: (values: TData, formApi: FormApi) => ValidationError | Promise - ``` - - Optional onChange asynchronous counterpart to onChange. Useful for more complex validation logic that might involve server requests. - -- ```tsx - 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. - -- ```tsx - onBlur?: (values: TData, formApi: FormApi) => ValidationError - ``` - - Optional function that validates the form data when a field loses focus, returns a `ValidationError` - -- ```tsx - onBlurAsync?: (values: TData,formApi: FormApi) => ValidationError | Promise - ``` - - Optional onBlur asynchronous validation method for when a field loses focus return a `ValidationError` or a promise of `Promise` - -- ```tsx - 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. - -### `FormApi` - -A class representing the Form API. It handles the logic and interactions with the form state. - -#### Properties - -- ```tsx - options: FormOptions = {} - ``` - - The options for the form. - -- ```tsx - store: Store> - ``` - - A [TanStack Store instance](https://tanstack.com/store/latest/docs/reference/Store) that keeps track of the form's state. - -- ```tsx - state: FormState - ``` - - The current state of the form. - -- ```tsx - fieldInfo: Record, FieldInfo> = - {} as any - ``` - - A record of field information for each field in the form. - -#### Methods - -- ```tsx - constructor(opts?: FormOptions) - ``` - - Constructs a new `FormApi` instance with the given form options. -- ```tsx - update(options: FormOptions) - ``` - - Updates the form options and form state. -- ```tsx - reset() - ``` - - Resets the form state to the default values. -- ```tsx - validateAllFields(cause: ValidationCause): Promise - ``` - - Validates all fields in the form using the correct handlers for a given validation type. -- ```tsx - validateArrayFieldsStartingFrom>(field: TField, index: number, cause: ValidationCause): ValidationError[] | Promise - ``` - - 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. -- ```tsx - validateField>(field: TField, cause: ValidationCause): ValidationError[] | Promise - ``` - - Validates a specified field in the form using the correct handlers for a given validation type. - -- ```tsx - handleSubmit() - ``` - - Handles the form submission, performs validation, and calls the appropriate `onSubmit` or `onInvalidSubmit` callbacks. -- ```tsx - getFieldValue>(field: TField) - ``` - - Gets the value of the specified field. -- ```tsx - getFieldMeta>(field: TField) - ``` - - Gets the metadata of the specified field. -- ```tsx - getFieldInfo>(field: TField) - ``` - - Gets the field info of the specified field. -- ```tsx - setFieldMeta>(field: TField, updater: Updater) - ``` - - Updates the metadata of the specified field. -- ```tsx - setFieldValue>(field: TField, updater: Updater>, opts?: { touch?: boolean }) - ``` - - Sets the value of the specified field and optionally updates the touched state. -- ```tsx - pushFieldValue>(field: TField, value: DeepValue, opts?: { touch?: boolean }) - ``` - - Pushes a value into an array field. -- ```tsx - insertFieldValue>(field: TField, index: number, value: DeepValue, opts?: { touch?: boolean }) - ``` - - Inserts a value into an array field at the specified index, shifting the subsequent values to the right. -- ```tsx - replaceFieldValue>(field: TField, index: number, value: DeepValue, opts?: { touch?: boolean }) - ``` - - Replaces a value into an array field at the specified index. -- ```tsx - removeFieldValue>(field: TField, index: number, opts?: { touch?: boolean }) - ``` - - Removes a value from an array field at the specified index. -- ```tsx - swapFieldValues>(field: TField, index1: number, index2: number, opts?: { touch?: boolean }) - ``` - - Swaps the values at the specified indices within an array field. -- ```tsx - moveFieldValues>(field: TField, index1: number, index2: number, opts?: { touch?: boolean }) - ``` - - Moves the value at the first specified index to the second specified index within an array field. - -### `FormState` - -An object representing the current state of the form. - -- ```tsx - values: TData - ``` - - The current values of the form fields. - -- ```tsx - errors: ValidationError[] - ``` - - The error array for the form itself. - -- ```tsx - errorMap: ValidationErrorMap - ``` - - The error map for the form itself. - -- ```tsx - isFormValidating: boolean - ``` - - A boolean indicating if the form is currently validating. - -- ```tsx - isFormValid: boolean - ``` - - A boolean indicating if the form is valid. - -- ```tsx - fieldMeta: Record, FieldMeta> - ``` - - A record of field metadata for each field in the form. - -- ```tsx - isFieldsValidating: boolean - ``` - - A boolean indicating if any of the form fields are currently validating. - -- ```tsx - isFieldsValid: boolean - ``` - - A boolean indicating if all the form fields are valid. - -- ```tsx - isSubmitting: boolean - ``` - - A boolean indicating if the form is currently submitting. - -- ```tsx - isTouched: boolean - ``` - - A boolean indicating if any of the form fields have been touched. - -- ```tsx - isPristine: boolean - ``` - - A boolean indicating if none of the form's fields' values have been modified by the user. `True` if the user have not modified any of the fields. Opposite of `isDirty`. - -- ```tsx - isDirty: boolean - ``` - - A boolean indicating if any of the form's fields' values have been modified by the user. `True` if the user have modified at least one of the fields. Opposite of `isPristine`. - -- ```tsx - isSubmitted: boolean - ``` - - A boolean indicating if the form has been submitted. - -- ```tsx - isValidating: boolean - ``` - - A boolean indicating if the form or any of its fields are currently validating. - -- ```tsx - isValid: boolean - ``` - - A boolean indicating if the form and all its fields are valid. - -- ```tsx - canSubmit: boolean - ``` - - A boolean indicating if the form can be submitted based on its current state. - -- ```tsx - submissionAttempts: number - ``` - - A counter for tracking the number of submission attempts. - -- ```tsx - validationMetaMap: Record - ``` - - An internal mechanism used for keeping track of validation logic in a form. - -### `FieldInfo` - -An object representing the field information for a specific field within the form. - -- ```tsx - instance: FieldApi< - TFormData, - any, - Validator | undefined, - TFormValidator - > | null - ``` - - An instance of the `FieldAPI`. - -- ```tsx - validationMetaMap: Record - ``` - - A record of field validation internal handling. - - Check below for `ValidationMeta` - -### `ValidationMeta` - -An object representing the validation metadata for a field. Not intended for public usage. - -- ```tsx - lastAbortController: AbortController - ``` - - An abort controller stored in memory to cancel previous async validation attempts. diff --git a/docs/reference/formapi.md b/docs/reference/formapi.md new file mode 100644 index 000000000..b343fc86b --- /dev/null +++ b/docs/reference/formapi.md @@ -0,0 +1,663 @@ +# Class: FormApi\ + +A class representing the Form API. It handles the logic and interactions with the form state. + +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 uses your framework's reactivity model. +However, if you need to create a new instance manually, you can do so by calling the `new FormApi` constructor. + +## Type parameters + +• **TFormData** + +• **TFormValidator** *extends* `Validator`\<`TFormData`, `unknown`\> \| `undefined` = `undefined` + +## Constructors + +### new FormApi() + +```ts +new FormApi(opts?): FormApi +``` + +Constructs a new `FormApi` instance with the given form options. + +#### Parameters + +• **opts?**: [`FormOptions`](formoptions.md)\<`TFormData`, `TFormValidator`\> + +#### Returns + +[`FormApi`](formapi.md)\<`TFormData`, `TFormValidator`\> + +#### Source + +[packages/form-core/src/FormApi.ts:344](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L344) + +## Properties + +### fieldInfo + +```ts +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>; +``` + +A record of field information for each field in the form. + +#### Source + +[packages/form-core/src/FormApi.ts:333](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L333) + +*** + +### options + +```ts +options: FormOptions = {}; +``` + +The options for the form. + +#### Source + +[packages/form-core/src/FormApi.ts:317](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L317) + +*** + +### state + +```ts +state: FormState; +``` + +The current state of the form. + +**Note:** +Do not use `state` directly, as it is not reactive. +Please use form.useStore() utility to subscribe to state + +#### Source + +[packages/form-core/src/FormApi.ts:329](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L329) + +*** + +### store + +```ts +store: Store, (cb) => FormState>; +``` + +A [TanStack Store instance](https://tanstack.com/store/latest/docs/reference/Store) that keeps track of the form's state. + +#### Source + +[packages/form-core/src/FormApi.ts:321](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L321) + +## Methods + +### deleteField() + +```ts +deleteField(field): void +``` + +#### Type parameters + +• **TField** *extends* `string` \| `number` + +#### Parameters + +• **field**: `TField` + +#### Returns + +`void` + +#### Source + +[packages/form-core/src/FormApi.ts:925](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L925) + +*** + +### getFieldInfo() + +```ts +getFieldInfo(field): FieldInfo +``` + +Gets the field info of the specified field. + +#### Type parameters + +• **TField** *extends* `string` \| `number` + +#### Parameters + +• **field**: `TField` + +#### Returns + +[`FieldInfo`](fieldinfo.md)\<`TFormData`, `TFormValidator`\> + +#### Source + +[packages/form-core/src/FormApi.ts:842](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L842) + +*** + +### getFieldMeta() + +```ts +getFieldMeta(field): undefined | FieldMeta +``` + +Gets the metadata of the specified field. + +#### Type parameters + +• **TField** *extends* `string` \| `number` + +#### Parameters + +• **field**: `TField` + +#### Returns + +`undefined` \| [`FieldMeta`](fieldmeta.md) + +#### Source + +[packages/form-core/src/FormApi.ts:833](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L833) + +*** + +### getFieldValue() + +```ts +getFieldValue(field): DeepValue> +``` + +Gets the value of the specified field. + +#### Type parameters + +• **TField** *extends* `string` \| `number` + +#### Parameters + +• **field**: `TField` + +#### Returns + +[`DeepValue`](deepvalue.md)\<`TFormData`, `TField`, `IsNullable`\<`TFormData`\>\> + +#### Source + +[packages/form-core/src/FormApi.ts:826](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L826) + +*** + +### handleSubmit() + +```ts +handleSubmit(): Promise +``` + +Handles the form submission, performs validation, and calls the appropriate onSubmit or onInvalidSubmit callbacks. + +#### Returns + +`Promise`\<`void`\> + +#### Source + +[packages/form-core/src/FormApi.ts:766](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L766) + +*** + +### insertFieldValue() + +```ts +insertFieldValue( + field, + index, + value, +opts?): Promise +``` + +Inserts a value into an array field at the specified index, shifting the subsequent values to the right. + +#### Type parameters + +• **TField** *extends* `string` \| `number` + +#### Parameters + +• **field**: `TField` + +• **index**: `number` + +• **value**: [`DeepValue`](deepvalue.md)\<`TFormData`, `TField`, `IsNullable`\<`TFormData`\>\> *extends* `any`[] ? `any`[] & [`DeepValue`](deepvalue.md)\<`TFormData`, `TField`, `IsNullable`\<`TFormData`\>\>\[`number`\] : `never` + +• **opts?** + +• **opts.touch?**: `boolean` + +#### Returns + +`Promise`\<`void`\> + +#### Source + +[packages/form-core/src/FormApi.ts:957](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L957) + +*** + +### mount() + +```ts +mount(): void +``` + +#### Returns + +`void` + +#### Source + +[packages/form-core/src/FormApi.ts:442](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L442) + +*** + +### moveFieldValues() + +```ts +moveFieldValues( + field, + index1, + index2, + opts?): void +``` + +Moves the value at the first specified index to the second specified index within an array field. + +#### Type parameters + +• **TField** *extends* `string` \| `number` + +#### Parameters + +• **field**: `TField` + +• **index1**: `number` + +• **index2**: `number` + +• **opts?** + +• **opts.touch?**: `boolean` + +#### Returns + +`void` + +#### Source + +[packages/form-core/src/FormApi.ts:1075](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L1075) + +*** + +### pushFieldValue() + +```ts +pushFieldValue( + field, + value, + opts?): void +``` + +Pushes a value into an array field. + +#### Type parameters + +• **TField** *extends* `string` \| `number` + +#### Parameters + +• **field**: `TField` + +• **value**: [`DeepValue`](deepvalue.md)\<`TFormData`, `TField`, `IsNullable`\<`TFormData`\>\> *extends* `any`[] ? `any`[] & [`DeepValue`](deepvalue.md)\<`TFormData`, `TField`, `IsNullable`\<`TFormData`\>\>\[`number`\] : `never` + +• **opts?** + +• **opts.touch?**: `boolean` + +#### Returns + +`void` + +#### Source + +[packages/form-core/src/FormApi.ts:939](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L939) + +*** + +### removeFieldValue() + +```ts +removeFieldValue( + field, + index, +opts?): Promise +``` + +Removes a value from an array field at the specified index. + +#### Type parameters + +• **TField** *extends* `string` \| `number` + +#### Parameters + +• **field**: `TField` + +• **index**: `number` + +• **opts?** + +• **opts.touch?**: `boolean` + +#### Returns + +`Promise`\<`void`\> + +#### Source + +[packages/form-core/src/FormApi.ts:1010](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L1010) + +*** + +### replaceFieldValue() + +```ts +replaceFieldValue( + field, + index, + value, +opts?): Promise +``` + +Replaces a value into an array field at the specified index. + +#### Type parameters + +• **TField** *extends* `string` \| `number` + +#### Parameters + +• **field**: `TField` + +• **index**: `number` + +• **value**: [`DeepValue`](deepvalue.md)\<`TFormData`, `TField`, `IsNullable`\<`TFormData`\>\> *extends* `any`[] ? `any`[] & [`DeepValue`](deepvalue.md)\<`TFormData`, `TField`, `IsNullable`\<`TFormData`\>\>\[`number`\] : `never` + +• **opts?** + +• **opts.touch?**: `boolean` + +#### Returns + +`Promise`\<`void`\> + +#### Source + +[packages/form-core/src/FormApi.ts:984](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L984) + +*** + +### reset() + +```ts +reset(): void +``` + +Resets the form state to the default values. + +#### Returns + +`void` + +#### Source + +[packages/form-core/src/FormApi.ts:504](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L504) + +*** + +### resetFieldMeta() + +```ts +resetFieldMeta(fieldMeta): Record +``` + +#### Type parameters + +• **TField** *extends* `string` \| `number` + +#### Parameters + +• **fieldMeta**: `Record`\<`TField`, [`FieldMeta`](fieldmeta.md)\> + +#### Returns + +`Record`\<`TField`, [`FieldMeta`](fieldmeta.md)\> + +#### Source + +[packages/form-core/src/FormApi.ts:876](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L876) + +*** + +### setFieldMeta() + +```ts +setFieldMeta(field, updater): void +``` + +Updates the metadata of the specified field. + +#### Type parameters + +• **TField** *extends* `string` \| `number` + +#### Parameters + +• **field**: `TField` + +• **updater**: [`Updater`](updater.md)\<[`FieldMeta`](fieldmeta.md)\> + +#### Returns + +`void` + +#### Source + +[packages/form-core/src/FormApi.ts:861](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L861) + +*** + +### setFieldValue() + +```ts +setFieldValue( + field, + updater, + opts?): void +``` + +Sets the value of the specified field and optionally updates the touched state. + +#### Type parameters + +• **TField** *extends* `string` \| `number` + +#### Parameters + +• **field**: `TField` + +• **updater**: [`Updater`](updater.md)\<[`DeepValue`](deepvalue.md)\<`TFormData`, `TField`, `IsNullable`\<`TFormData`\>\>\> + +• **opts?** + +• **opts.touch?**: `boolean` + +#### Returns + +`void` + +#### Source + +[packages/form-core/src/FormApi.ts:900](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L900) + +*** + +### swapFieldValues() + +```ts +swapFieldValues( + field, + index1, + index2, + opts?): void +``` + +Swaps the values at the specified indices within an array field. + +#### Type parameters + +• **TField** *extends* `string` \| `number` + +#### Parameters + +• **field**: `TField` + +• **index1**: `number` + +• **index2**: `number` + +• **opts?** + +• **opts.touch?**: `boolean` + +#### Returns + +`void` + +#### Source + +[packages/form-core/src/FormApi.ts:1049](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L1049) + +*** + +### update() + +```ts +update(options?): void +``` + +Updates the form options and form state. + +#### Parameters + +• **options?**: [`FormOptions`](formoptions.md)\<`TFormData`, `TFormValidator`\> + +#### Returns + +`void` + +#### Source + +[packages/form-core/src/FormApi.ts:464](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L464) + +*** + +### validateAllFields() + +```ts +validateAllFields(cause): Promise +``` + +Validates all fields in the form using the correct handlers for a given validation type. + +#### Parameters + +• **cause**: `ValidationCause` + +#### Returns + +`Promise`\<[`ValidationError`](validationerror.md)[]\> + +#### Source + +[packages/form-core/src/FormApi.ts:519](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L519) + +*** + +### validateArrayFieldsStartingFrom() + +```ts +validateArrayFieldsStartingFrom( + field, + index, +cause): Promise +``` + +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. + +#### Type parameters + +• **TField** *extends* `string` \| `number` + +#### Parameters + +• **field**: `TField` + +• **index**: `number` + +• **cause**: `ValidationCause` + +#### Returns + +`Promise`\<[`ValidationError`](validationerror.md)[]\> + +#### Source + +[packages/form-core/src/FormApi.ts:546](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L546) + +*** + +### validateField() + +```ts +validateField(field, cause): ValidationError[] | Promise +``` + +Validates a specified field in the form using the correct handlers for a given validation type. + +#### Type parameters + +• **TField** *extends* `string` \| `number` + +#### Parameters + +• **field**: `TField` + +• **cause**: `ValidationCause` + +#### Returns + +[`ValidationError`](validationerror.md)[] \| `Promise`\<[`ValidationError`](validationerror.md)[]\> + +#### Source + +[packages/form-core/src/FormApi.ts:585](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L585) diff --git a/docs/reference/formoptions.md b/docs/reference/formoptions.md new file mode 100644 index 000000000..5ed5e908f --- /dev/null +++ b/docs/reference/formoptions.md @@ -0,0 +1,23 @@ +# Function: formOptions() + +```ts +function formOptions(defaultOpts?): undefined | FormOptions +``` + +## Type parameters + +• **TFormData** + +• **TFormValidator** *extends* `undefined` \| `Validator`\<`TFormData`, `unknown`\> = `undefined` + +## Parameters + +• **defaultOpts?**: [`FormOptions`](formoptions.md)\<`TFormData`, `TFormValidator`\> + +## Returns + +`undefined` \| [`FormOptions`](formoptions.md)\<`TFormData`, `TFormValidator`\> + +## Source + +[packages/form-core/src/formOptions.ts:4](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/formOptions.ts#L4) diff --git a/docs/reference/formstate.md b/docs/reference/formstate.md new file mode 100644 index 000000000..bb559d53d --- /dev/null +++ b/docs/reference/formstate.md @@ -0,0 +1,161 @@ +# Type alias: FormState\ + +```ts +type FormState: object; +``` + +An object representing the current state of the form. + +## Type parameters + +• **TFormData** + +## Type declaration + +### canSubmit + +```ts +canSubmit: boolean; +``` + +A boolean indicating if the form can be submitted based on its current state. + +### errorMap + +```ts +errorMap: ValidationErrorMap; +``` + +The error map for the form itself. + +### errors + +```ts +errors: ValidationError[]; +``` + +The error array for the form itself. + +### fieldMeta + +```ts +fieldMeta: Record, FieldMeta>; +``` + +A record of field metadata for each field in the form. + +### isDirty + +```ts +isDirty: boolean; +``` + +A boolean indicating if any of the form's fields' values have been modified by the user. `True` if the user have modified at least one of the fields. Opposite of `isPristine`. + +### isFieldsValid + +```ts +isFieldsValid: boolean; +``` + +A boolean indicating if all the form fields are valid. + +### isFieldsValidating + +```ts +isFieldsValidating: boolean; +``` + +A boolean indicating if any of the form fields are currently validating. + +### isFormValid + +```ts +isFormValid: boolean; +``` + +A boolean indicating if the form is valid. + +### isFormValidating + +```ts +isFormValidating: boolean; +``` + +A boolean indicating if the form is currently validating. + +### isPristine + +```ts +isPristine: boolean; +``` + +A boolean indicating if none of the form's fields' values have been modified by the user. `True` if the user have not modified any of the fields. Opposite of `isDirty`. + +### isSubmitted + +```ts +isSubmitted: boolean; +``` + +A boolean indicating if the form has been submitted. + +### isSubmitting + +```ts +isSubmitting: boolean; +``` + +A boolean indicating if the form is currently submitting. + +### isTouched + +```ts +isTouched: boolean; +``` + +A boolean indicating if any of the form fields have been touched. + +### isValid + +```ts +isValid: boolean; +``` + +A boolean indicating if the form and all its fields are valid. + +### isValidating + +```ts +isValidating: boolean; +``` + +A boolean indicating if the form or any of its fields are currently validating. + +### submissionAttempts + +```ts +submissionAttempts: number; +``` + +A counter for tracking the number of submission attempts. + +### validationMetaMap + +```ts +validationMetaMap: Record; +``` + +An internal mechanism used for keeping track of validation logic in a form. + +### values + +```ts +values: TFormData; +``` + +The current values of the form fields. + +## Source + +[packages/form-core/src/FormApi.ts:197](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L197) diff --git a/docs/reference/formvalidators.md b/docs/reference/formvalidators.md new file mode 100644 index 000000000..243509b1c --- /dev/null +++ b/docs/reference/formvalidators.md @@ -0,0 +1,129 @@ +# Interface: FormValidators\ + +## Type parameters + +• **TFormData** + +• **TFormValidator** *extends* `Validator`\<`TFormData`, `unknown`\> \| `undefined` = `undefined` + +## Properties + +### onBlur? + +```ts +optional onBlur: FormValidateOrFn; +``` + +Optional function that validates the form data when a field loses focus, returns a ValidationError + +#### Source + +[packages/form-core/src/FormApi.ts:88](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L88) + +*** + +### onBlurAsync? + +```ts +optional onBlurAsync: FormAsyncValidateOrFn; +``` + +Optional onBlur asynchronous validation method for when a field loses focus return a `ValidationError` or a promise of `Promise` + +#### Source + +[packages/form-core/src/FormApi.ts:92](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L92) + +*** + +### onBlurAsyncDebounceMs? + +```ts +optional 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. + +#### Source + +[packages/form-core/src/FormApi.ts:96](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L96) + +*** + +### onChange? + +```ts +optional onChange: FormValidateOrFn; +``` + +Optional function that checks the validity of your data whenever a value changes + +#### Source + +[packages/form-core/src/FormApi.ts:76](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L76) + +*** + +### onChangeAsync? + +```ts +optional onChangeAsync: FormAsyncValidateOrFn; +``` + +Optional onChange asynchronous counterpart to onChange. Useful for more complex validation logic that might involve server requests. + +#### Source + +[packages/form-core/src/FormApi.ts:80](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L80) + +*** + +### onChangeAsyncDebounceMs? + +```ts +optional 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. + +#### Source + +[packages/form-core/src/FormApi.ts:84](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L84) + +*** + +### onMount? + +```ts +optional onMount: FormValidateOrFn; +``` + +Optional function that fires as soon as the component mounts. + +#### Source + +[packages/form-core/src/FormApi.ts:72](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L72) + +*** + +### onSubmit? + +```ts +optional onSubmit: FormValidateOrFn; +``` + +#### Source + +[packages/form-core/src/FormApi.ts:97](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L97) + +*** + +### onSubmitAsync? + +```ts +optional onSubmitAsync: FormAsyncValidateOrFn; +``` + +#### Source + +[packages/form-core/src/FormApi.ts:98](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L98) diff --git a/docs/reference/index.md b/docs/reference/index.md new file mode 100644 index 000000000..30c3aeb86 --- /dev/null +++ b/docs/reference/index.md @@ -0,0 +1,32 @@ +# @tanstack/form-core + +## Classes + +- [FieldApi](fieldapi.md) +- [FormApi](formapi.md) + +## Interfaces + +- [FieldApiOptions](fieldapioptions.md) +- [FieldOptions](fieldoptions.md) +- [FieldValidators](fieldvalidators.md) +- [FormOptions](formoptions.md) +- [FormValidators](formvalidators.md) + +## Type Aliases + +- [DeepKeys](deepkeys.md) +- [DeepValue](deepvalue.md) +- [FieldInfo](fieldinfo.md) +- [FieldMeta](fieldmeta.md) +- [FieldState](fieldstate.md) +- [FormState](formstate.md) +- [Updater](updater.md) +- [UpdaterFn](updaterfn.md) +- [ValidationError](validationerror.md) +- [ValidationMeta](validationmeta.md) + +## Functions + +- [formOptions](formoptions.md) +- [mergeForm](mergeform.md) diff --git a/docs/reference/mergeform.md b/docs/reference/mergeform.md new file mode 100644 index 000000000..7b55b1d0c --- /dev/null +++ b/docs/reference/mergeform.md @@ -0,0 +1,25 @@ +# Function: mergeForm() + +```ts +function mergeForm(baseForm, state): FormApi, NoInfer> +``` + +## Type parameters + +• **TFormData** + +• **TFormValidator** *extends* `undefined` \| `Validator`\<`TFormData`, `unknown`\> = `undefined` + +## Parameters + +• **baseForm**: [`FormApi`](formapi.md)\<`NoInfer`\<`TFormData`\>, `NoInfer`\<`TFormValidator`\>\> + +• **state**: `Partial`\<[`FormState`](formstate.md)\<`TFormData`\>\> + +## Returns + +[`FormApi`](formapi.md)\<`NoInfer`\<`TFormData`\>, `NoInfer`\<`TFormValidator`\>\> + +## Source + +[packages/form-core/src/mergeForm.ts:37](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/mergeForm.ts#L37) diff --git a/docs/reference/types.md b/docs/reference/types.md deleted file mode 100644 index a32bab7fa..000000000 --- a/docs/reference/types.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -id: types -title: Types - ---- - -### Using TanStack Form Types - -Normally, you will not need use these types directly. However, if you're debugging hard-to-reach issues or are a maintainer of one of our packages, these types can help you distinguish what's going on. - -### `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}` - -### `ValidationErrorMap` - -A type that represents a map with the keys as `ValidationErrorMapKeys` and the values as `ValidationError` \ No newline at end of file diff --git a/docs/reference/updater.md b/docs/reference/updater.md new file mode 100644 index 000000000..8c297407f --- /dev/null +++ b/docs/reference/updater.md @@ -0,0 +1,15 @@ +# Type alias: Updater\ + +```ts +type Updater: TOutput | UpdaterFn; +``` + +## Type parameters + +• **TInput** + +• **TOutput** = `TInput` + +## Source + +[packages/form-core/src/utils.ts:7](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/utils.ts#L7) diff --git a/docs/reference/updaterfn.md b/docs/reference/updaterfn.md new file mode 100644 index 000000000..477a0a0d5 --- /dev/null +++ b/docs/reference/updaterfn.md @@ -0,0 +1,23 @@ +# Type alias: UpdaterFn()\ + +```ts +type UpdaterFn: (input) => TOutput; +``` + +## Type parameters + +• **TInput** + +• **TOutput** = `TInput` + +## Parameters + +• **input**: `TInput` + +## Returns + +`TOutput` + +## Source + +[packages/form-core/src/utils.ts:5](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/utils.ts#L5) diff --git a/docs/reference/validationerror.md b/docs/reference/validationerror.md new file mode 100644 index 000000000..be945d647 --- /dev/null +++ b/docs/reference/validationerror.md @@ -0,0 +1,9 @@ +# Type alias: ValidationError + +```ts +type ValidationError: undefined | false | null | string; +``` + +## Source + +[packages/form-core/src/types.ts:1](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/types.ts#L1) diff --git a/docs/reference/validationmeta.md b/docs/reference/validationmeta.md new file mode 100644 index 000000000..7f57998b3 --- /dev/null +++ b/docs/reference/validationmeta.md @@ -0,0 +1,21 @@ +# Type alias: ValidationMeta + +```ts +type ValidationMeta: object; +``` + +An object representing the validation metadata for a field. Not intended for public usage. + +## Type declaration + +### lastAbortController + +```ts +lastAbortController: AbortController; +``` + +An abort controller stored in memory to cancel previous async validation attempts. + +## Source + +[packages/form-core/src/FormApi.ts:165](https://github.com/TanStack/form/blob/5c94fa159313e0b0411d49fbdc3b117336185e63/packages/form-core/src/FormApi.ts#L165) diff --git a/package.json b/package.json index ad970f098..a968befaa 100644 --- a/package.json +++ b/package.json @@ -27,6 +27,7 @@ "dev": "pnpm run watch", "prettier": "prettier --ignore-unknown .", "prettier:write": "pnpm run prettier --write", + "docs:reference": "node scripts/reference-docs.js", "cipublish": "node scripts/publish.js", "cipublishforce": "CI=true pnpm cipublish" }, @@ -68,6 +69,8 @@ "rimraf": "^5.0.5", "sherif": "^0.8.4", "solid-js": "^1.7.8", + "typedoc": "^0.25.13", + "typedoc-plugin-markdown": "^4.0.3", "typescript": "5.4.2", "typescript49": "npm:typescript@4.9", "typescript50": "npm:typescript@5.0", diff --git a/packages/angular-form/tsconfig.docs.json b/packages/angular-form/tsconfig.docs.json new file mode 100644 index 000000000..978e60f7d --- /dev/null +++ b/packages/angular-form/tsconfig.docs.json @@ -0,0 +1,9 @@ +{ + "extends": "./tsconfig.json", + "exclude": ["src/tests/**/*", ".eslintrc.cjs", "vite.config.ts"], + "compilerOptions": { + "paths": { + "@tanstack/form-core": ["../form-core/src"] + } + } +} diff --git a/packages/form-core/src/FieldApi.ts b/packages/form-core/src/FieldApi.ts index 3e81049a0..aa1caf9de 100644 --- a/packages/form-core/src/FieldApi.ts +++ b/packages/form-core/src/FieldApi.ts @@ -10,6 +10,9 @@ import type { import type { AsyncValidator, SyncValidator, Updater } from './utils' import type { DeepKeys, DeepValue, NoInfer } from './util-types' +/** + * @private + */ export type FieldValidateFn< TParentData, TName extends DeepKeys, @@ -25,6 +28,9 @@ export type FieldValidateFn< fieldApi: FieldApi }) => ValidationError +/** + * @private + */ export type FieldValidateOrFn< TParentData, TName extends DeepKeys, @@ -63,6 +69,9 @@ export type FieldValidateOrFn< TData > +/** + * @private + */ export type FieldValidateAsyncFn< TParentData, TName extends DeepKeys, @@ -79,6 +88,9 @@ export type FieldValidateAsyncFn< signal: AbortSignal }) => ValidationError | Promise +/** + * @private + */ export type FieldAsyncValidateOrFn< TParentData, TName extends DeepKeys, @@ -128,6 +140,9 @@ export interface FieldValidators< | undefined = undefined, TData extends DeepValue = DeepValue, > { + /** + * An optional function that takes a param of `formApi` which is a generic type of `TData` and `TParentData` + */ onMount?: FieldValidateOrFn< TParentData, TName, @@ -135,6 +150,12 @@ export interface FieldValidators< TFormValidator, TData > + /** + * An optional property that takes a `ValidateFn` which is a generic of `TData` and `TParentData`. + * If `validatorAdapter` is passed, this may also accept a property from the respective adapter + * + * @example `z.string().min(1)` if `zodAdapter` is passed + */ onChange?: FieldValidateOrFn< TParentData, TName, @@ -142,6 +163,12 @@ export interface FieldValidators< TFormValidator, TData > + /** + * An optional property similar to `onChange` but async validation. If `validatorAdapter` + * is passed, this may also accept a property from the respective adapter + * + * @example `z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' })` if `zodAdapter` is passed + */ onChangeAsync?: FieldAsyncValidateOrFn< TParentData, TName, @@ -149,8 +176,22 @@ export interface FieldValidators< TFormValidator, TData > + /** + * 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 + */ onChangeAsyncDebounceMs?: number + /** + * An optional list of field names that should trigger this field's `onChange` and `onChangeAsync` events when its value changes + */ onChangeListenTo?: DeepKeys[] + /** + * An optional function, that when run when subscribing to blur event of input. + * If `validatorAdapter` is passed, this may also accept a property from the respective adapter + * + * @example `z.string().min(1)` if `zodAdapter` is passed + */ onBlur?: FieldValidateOrFn< TParentData, TName, @@ -158,6 +199,12 @@ export interface FieldValidators< TFormValidator, TData > + /** + * An optional property similar to `onBlur` but async validation. If `validatorAdapter` + * is passed, this may also accept a property from the respective adapter + * + * @example `z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' })` if `zodAdapter` is passed + */ onBlurAsync?: FieldAsyncValidateOrFn< TParentData, TName, @@ -165,8 +212,23 @@ export interface FieldValidators< TFormValidator, TData > + + /** + * An optional number to represent how long the `onBlurAsync` 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 + */ onBlurAsyncDebounceMs?: number + /** + * An optional list of field names that should trigger this field's `onBlur` and `onBlurAsync` events when its value changes + */ onBlurListenTo?: DeepKeys[] + /** + * An optional function, that when run when subscribing to submit event of input. + * If `validatorAdapter` is passed, this may also accept a property from the respective adapter + * + * @example `z.string().min(1)` if `zodAdapter` is passed + */ onSubmit?: FieldValidateOrFn< TParentData, TName, @@ -174,6 +236,12 @@ export interface FieldValidators< TFormValidator, TData > + /** + * An optional property similar to `onSubmit` but async validation. If `validatorAdapter` + * is passed, this may also accept a property from the respective adapter + * + * @example `z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' })` if `zodAdapter` is passed + */ onSubmitAsync?: FieldAsyncValidateOrFn< TParentData, TName, @@ -183,6 +251,9 @@ export interface FieldValidators< > } +/** + * An object type representing the options for a field in a form. + */ export interface FieldOptions< TParentData, TName extends DeepKeys, @@ -194,12 +265,30 @@ export interface FieldOptions< | undefined = undefined, TData extends DeepValue = DeepValue, > { + /** + * The field name. The type will be `DeepKeys` to ensure your name is a deep key of the parent dataset. + */ name: TName + /** + * An optional default value for the field. + */ defaultValue?: NoInfer + /** + * The default time to debounce async validation if there is not a more specific debounce time passed. + */ asyncDebounceMs?: number + /** + * If `true`, always run async validation, even if there are errors emitted during synchronous validation. + */ asyncAlways?: boolean preserveValue?: boolean + /** + * A validator provided by an extension, like `yupValidator` from `@tanstack/yup-form-adapter` + */ validatorAdapter?: TFieldValidator + /** + * A list of validators to pass to the field + */ validators?: FieldValidators< TParentData, TName, @@ -207,9 +296,15 @@ export interface FieldOptions< TFormValidator, TData > + /** + * An optional object with default metadata for the field. + */ defaultMeta?: Partial } +/** + * An object type representing the required options for the FieldApi class. + */ export interface FieldApiOptions< TParentData, TName extends DeepKeys, @@ -230,25 +325,63 @@ export interface FieldApiOptions< form: FormApi } +/** + * An object type representing the metadata of a field in a form. + */ export type FieldMeta = { + /** + * A flag indicating whether the field has been touched. + */ isTouched: boolean + /** + * A flag that is `true` if the field's value has not been modified by the user. Opposite of `isDirty`. + */ isPristine: boolean + /** + * A flag that is `true` if the field's value has been modified by the user. Opposite of `isPristine`. + */ isDirty: boolean + /** + * An array of errors related to the touched state of the field. + */ touchedErrors: ValidationError[] + /** + * An array of errors related to the field value. + */ errors: ValidationError[] + /** + * A map of errors related to the field value. + */ errorMap: ValidationErrorMap + /** + * A flag indicating whether the field is currently being validated. + */ isValidating: boolean } +/** + * An object type representing the state of a field. + */ export type FieldState = { + /** + * The current value of the field. + */ value: TData + /** + * The current metadata of the field. + */ meta: FieldMeta } -export type ResolveName = unknown extends TParentData - ? string - : DeepKeys - +/** + * A class representing the API for managing a form field. + * + * 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 uses your framework's reactivity model. + * However, if you need to create a new instance manually, you can do so by calling + * the `new FieldApi` constructor. + */ export class FieldApi< TParentData, TName extends DeepKeys, @@ -260,6 +393,9 @@ export class FieldApi< | undefined = undefined, TData extends DeepValue = DeepValue, > { + /** + * A reference to the form API instance. + */ form: FieldApiOptions< TParentData, TName, @@ -267,7 +403,13 @@ export class FieldApi< TFormValidator, TData >['form'] + /** + * The field name. + */ name!: DeepKeys + /** + * The field options. + */ options: FieldApiOptions< TParentData, TName, @@ -275,10 +417,22 @@ export class FieldApi< TFormValidator, TData > = {} as any + /** + * The field state store. + */ store!: Store> + /** + * The current field state. + */ state!: FieldState + /** + * @private + */ prevState!: FieldState + /** + * Initializes a new `FieldApi` instance. + */ constructor( opts: FieldApiOptions< TParentData, @@ -335,6 +489,9 @@ export class FieldApi< this.options = opts as never } + /** + * @private + */ runValidator< TValue extends { value: TData; fieldApi: FieldApi }, TType extends 'validate' | 'validateAsync', @@ -361,6 +518,9 @@ export class FieldApi< return (props.validate as FieldValidateFn)(props.value) as never } + /** + * Mounts the field instance to the form. + */ mount = () => { const info = this.getInfo() info.instance = this as never @@ -409,6 +569,9 @@ export class FieldApi< } } + /** + * Updates the field instance with new options. + */ update = ( opts: FieldApiOptions< TParentData, @@ -438,10 +601,16 @@ export class FieldApi< this.options = opts as never } + /** + * Gets the current field value. + */ getValue = (): TData => { return this.form.getFieldValue(this.name) as TData } + /** + * Sets the field value and run the `change` validator. + */ setValue = ( updater: Updater, options?: { touch?: boolean; notify?: boolean }, @@ -450,7 +619,14 @@ export class FieldApi< this.validate('change') } + /** + * @private + */ _getMeta = () => this.form.getFieldMeta(this.name) + + /** + * Gets the current field metadata. + */ getMeta = () => this._getMeta() ?? ({ @@ -464,37 +640,64 @@ export class FieldApi< ...this.options.defaultMeta, } as FieldMeta) + /** + * Sets the field metadata. + */ setMeta = (updater: Updater) => this.form.setFieldMeta(this.name, updater) + /** + * Gets the field information object. + */ getInfo = () => this.form.getFieldInfo(this.name) + /** + * Pushes a new value to the field. + */ pushValue = ( value: TData extends any[] ? TData[number] : never, opts?: { touch?: boolean }, ) => this.form.pushFieldValue(this.name, value as any, opts) + /** + * Inserts a value at the specified index, shifting the subsequent values to the right. + */ insertValue = ( index: number, value: TData extends any[] ? TData[number] : never, opts?: { touch?: boolean }, ) => this.form.insertFieldValue(this.name, index, value as any, opts) + /** + * Replaces a value at the specified index. + */ replaceValue = ( index: number, value: TData extends any[] ? TData[number] : never, opts?: { touch?: boolean }, ) => this.form.replaceFieldValue(this.name, index, value as any, opts) + /** + * Removes a value at the specified index. + */ removeValue = (index: number, opts?: { touch: boolean }) => this.form.removeFieldValue(this.name, index, opts) + /** + * Swaps the values at the specified indices. + */ swapValues = (aIndex: number, bIndex: number, opts?: { touch?: boolean }) => this.form.swapFieldValues(this.name, aIndex, bIndex, opts) + /** + * Moves the value at the first specified index to the second specified index. + */ moveValue = (aIndex: number, bIndex: number, opts?: { touch?: boolean }) => this.form.moveFieldValues(this.name, aIndex, bIndex, opts) + /** + * @private + */ getLinkedFields = (cause: ValidationCause) => { const fields = Object.values(this.form.fieldInfo) as FieldInfo< any, @@ -520,6 +723,9 @@ export class FieldApi< return linkedFields } + /** + * @private + */ validateSync = (cause: ValidationCause) => { const validates = getSyncValidatorArray(cause, this.options) @@ -597,6 +803,9 @@ export class FieldApi< return { hasErrored } } + /** + * @private + */ validateAsync = async (cause: ValidationCause) => { const validates = getAsyncValidatorArray(cause, this.options) @@ -717,6 +926,9 @@ export class FieldApi< return results.filter(Boolean) } + /** + * Validates the field value. + */ validate = ( cause: ValidationCause, ): ValidationError[] | Promise => { @@ -737,10 +949,16 @@ export class FieldApi< return this.validateAsync(cause) } + /** + * Handles the change event. + */ handleChange = (updater: Updater) => { this.setValue(updater, { touch: true }) } + /** + * Handles the blur event. + */ handleBlur = () => { const prevTouched = this.state.meta.isTouched if (!prevTouched) { diff --git a/packages/form-core/src/FormApi.ts b/packages/form-core/src/FormApi.ts index d4d5e89d4..b9c0fe72a 100644 --- a/packages/form-core/src/FormApi.ts +++ b/packages/form-core/src/FormApi.ts @@ -19,6 +19,9 @@ import type { Validator, } from './types' +/** + * @private + */ export type FormValidateFn< TFormData, TFormValidator extends Validator | undefined = undefined, @@ -27,6 +30,9 @@ export type FormValidateFn< formApi: FormApi }) => ValidationError +/** + * @private + */ export type FormValidateOrFn< TFormData, TFormValidator extends Validator | undefined = undefined, @@ -34,6 +40,9 @@ export type FormValidateOrFn< ? TFN : FormValidateFn +/** + * @private + */ export type FormValidateAsyncFn< TFormData, TFormValidator extends Validator | undefined = undefined, @@ -43,6 +52,9 @@ export type FormValidateAsyncFn< signal: AbortSignal }) => ValidationError | Promise +/** + * @private + */ export type FormAsyncValidateOrFn< TFormData, TFormValidator extends Validator | undefined = undefined, @@ -54,17 +66,41 @@ export interface FormValidators< TFormData, TFormValidator extends Validator | undefined = undefined, > { + /** + * Optional function that fires as soon as the component mounts. + */ onMount?: FormValidateOrFn + /** + * Optional function that checks the validity of your data whenever a value changes + */ onChange?: FormValidateOrFn + /** + * Optional onChange asynchronous counterpart to onChange. Useful for more complex validation logic that might involve server requests. + */ onChangeAsync?: FormAsyncValidateOrFn + /** + * 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. + */ onChangeAsyncDebounceMs?: number + /** + * Optional function that validates the form data when a field loses focus, returns a ValidationError + */ onBlur?: FormValidateOrFn + /** + * Optional onBlur asynchronous validation method for when a field loses focus return a `ValidationError` or a promise of `Promise` + */ onBlurAsync?: FormAsyncValidateOrFn + /** + * 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. + */ onBlurAsyncDebounceMs?: number onSubmit?: FormValidateOrFn onSubmitAsync?: FormAsyncValidateOrFn } +/** + * @private + */ export interface FormTransform< TFormData, TFormValidator extends Validator | undefined = undefined, @@ -75,20 +111,47 @@ export interface FormTransform< deps: unknown[] } +/** + * An object representing the options for a form. + */ export interface FormOptions< TFormData, TFormValidator extends Validator | undefined = undefined, > { + /** + * Set initial values for your form. + */ defaultValues?: TFormData + /** + * The default state for the form. + */ defaultState?: Partial> + /** + * If true, always run async validation, even when sync validation has produced an error. Defaults to undefined. + */ asyncAlways?: boolean + /** + * Optional time in milliseconds if you want to introduce a delay before firing off an async action. + */ asyncDebounceMs?: number + /** + * A validator adapter to support usage of extra validation types (IE: Zod, Yup, or Valibot usage) + */ validatorAdapter?: TFormValidator + /** + * A list of validators to pass to the form + */ validators?: FormValidators + /** + * 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` + */ onSubmit?: (props: { value: TFormData formApi: FormApi }) => any | Promise + /** + * Specify an action for scenarios where the user tries to submit an invalid form. + */ onSubmitInvalid?: (props: { value: TFormData formApi: FormApi @@ -96,44 +159,113 @@ export interface FormOptions< transform?: FormTransform } +/** + * An object representing the validation metadata for a field. Not intended for public usage. + */ export type ValidationMeta = { + /** + * An abort controller stored in memory to cancel previous async validation attempts. + */ lastAbortController: AbortController } +/** + * An object representing the field information for a specific field within the form. + */ export type FieldInfo< TFormData, TFormValidator extends Validator | undefined = undefined, > = { + /** + * An instance of the FieldAPI. + */ instance: FieldApi< TFormData, any, Validator | undefined, TFormValidator > | null + /** + * A record of field validation internal handling. + */ validationMetaMap: Record } +/** + * An object representing the current state of the form. + */ export type FormState = { + /** + * The current values of the form fields. + */ values: TFormData - // Form Validation + /** + * A boolean indicating if the form is currently validating. + */ isFormValidating: boolean + /** + * A boolean indicating if the form is valid. + */ isFormValid: boolean + /** + * The error array for the form itself. + */ errors: ValidationError[] + /** + * The error map for the form itself. + */ errorMap: ValidationErrorMap + /** + * An internal mechanism used for keeping track of validation logic in a form. + */ validationMetaMap: Record - // Fields + /** + * A record of field metadata for each field in the form. + */ fieldMeta: Record, FieldMeta> + /** + * A boolean indicating if any of the form fields are currently validating. + */ isFieldsValidating: boolean + /** + * A boolean indicating if all the form fields are valid. + */ isFieldsValid: boolean + /** + * A boolean indicating if the form is currently submitting. + */ isSubmitting: boolean - // General + /** + * A boolean indicating if any of the form fields have been touched. + */ isTouched: boolean + /** + * A boolean indicating if any of the form's fields' values have been modified by the user. `True` if the user have modified at least one of the fields. Opposite of `isPristine`. + */ isDirty: boolean + /** + * A boolean indicating if none of the form's fields' values have been modified by the user. `True` if the user have not modified any of the fields. Opposite of `isDirty`. + */ isPristine: boolean + /** + * A boolean indicating if the form has been submitted. + */ isSubmitted: boolean + /** + * A boolean indicating if the form or any of its fields are currently validating. + */ isValidating: boolean + /** + * A boolean indicating if the form and all its fields are valid. + */ isValid: boolean + /** + * A boolean indicating if the form can be submitted based on its current state. + */ canSubmit: boolean + /** + * A counter for tracking the number of submission attempts. + */ submissionAttempts: number } @@ -168,21 +300,47 @@ function getDefaultFormState( } } +/** + * A class representing the Form API. It handles the logic and interactions with the form state. + * + * 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 uses your framework's reactivity model. + * However, if you need to create a new instance manually, you can do so by calling the `new FormApi` constructor. + */ export class FormApi< TFormData, TFormValidator extends Validator | undefined = undefined, > { + /** + * The options for the form. + */ options: FormOptions = {} + /** + * A [TanStack Store instance](https://tanstack.com/store/latest/docs/reference/Store) that keeps track of the form's state. + */ store!: Store> - // Do not use __state directly, as it is not reactive. - // Please use form.useStore() utility to subscribe to state + /** + * The current state of the form. + * + * **Note:** + * Do not use `state` directly, as it is not reactive. + * Please use form.useStore() utility to subscribe to state + */ state!: FormState - // // This carries the context for nested fields + /** + * A record of field information for each field in the form. + */ fieldInfo: Record, FieldInfo> = {} as any + /** + * @private + */ prevTransformArray: unknown[] = [] + /** + * Constructs a new `FormApi` instance with the given form options. + */ constructor(opts?: FormOptions) { this.store = new Store>( getDefaultFormState({ @@ -260,6 +418,9 @@ export class FormApi< this.update(opts || {}) } + /** + * @private + */ runValidator< TValue extends { value: TFormData; formApi: FormApi }, TType extends 'validate' | 'validateAsync', @@ -297,6 +458,9 @@ export class FormApi< } } + /** + * Updates the form options and form state. + */ update = (options?: FormOptions) => { if (!options) return @@ -334,6 +498,9 @@ export class FormApi< }) } + /** + * Resets the form state to the default values. + */ reset = () => { const { fieldMeta: currentFieldMeta } = this.state const fieldMeta = this.resetFieldMeta(currentFieldMeta) @@ -346,6 +513,9 @@ export class FormApi< ) } + /** + * Validates all fields in the form using the correct handlers for a given validation type. + */ validateAllFields = async (cause: ValidationCause) => { const fieldValidationPromises: Promise[] = [] as any this.store.batch(() => { @@ -370,6 +540,9 @@ export class FormApi< return fieldErrorMapMap.flat() } + /** + * 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. + */ validateArrayFieldsStartingFrom = async >( field: TField, index: number, @@ -406,6 +579,9 @@ export class FormApi< return fieldErrorMapMap.flat() } + /** + * Validates a specified field in the form using the correct handlers for a given validation type. + */ validateField = >( field: TField, cause: ValidationCause, @@ -423,7 +599,10 @@ export class FormApi< return fieldInstance.validate(cause) } - // TODO: This code is copied from FieldApi, we should refactor to share + /** + * TODO: This code is copied from FieldApi, we should refactor to share + * @private + */ validateSync = (cause: ValidationCause) => { const validates = getSyncValidatorArray(cause, this.options) let hasErrored = false as boolean @@ -480,6 +659,9 @@ export class FormApi< return { hasErrored } } + /** + * @private + */ validateAsync = async ( cause: ValidationCause, ): Promise => { @@ -561,6 +743,9 @@ export class FormApi< return results.filter(Boolean) } + /** + * @private + */ validate = ( cause: ValidationCause, ): ValidationError[] | Promise => { @@ -575,12 +760,10 @@ export class FormApi< return this.validateAsync(cause) } + /** + * Handles the form submission, performs validation, and calls the appropriate onSubmit or onInvalidSubmit callbacks. + */ handleSubmit = async () => { - // Check to see that the form and all fields have been touched - // If they have not, touch them all and run validation - // Run form validation - // Submit the form - this.store.setState((old) => ({ ...old, // Submission attempts mark the form as not submitted @@ -637,16 +820,25 @@ export class FormApi< } } + /** + * Gets the value of the specified field. + */ getFieldValue = >( field: TField, ): DeepValue => getBy(this.state.values, field) + /** + * Gets the metadata of the specified field. + */ getFieldMeta = >( field: TField, ): FieldMeta | undefined => { return this.state.fieldMeta[field] } + /** + * Gets the field info of the specified field. + */ getFieldInfo = >( field: TField, ): FieldInfo => { @@ -663,6 +855,9 @@ export class FormApi< }) } + /** + * Updates the metadata of the specified field. + */ setFieldMeta = >( field: TField, updater: Updater, @@ -699,6 +894,9 @@ export class FormApi< ) } + /** + * Sets the value of the specified field and optionally updates the touched state. + */ setFieldValue = >( field: TField, updater: Updater>, @@ -735,6 +933,9 @@ export class FormApi< delete this.fieldInfo[field] } + /** + * Pushes a value into an array field. + */ pushFieldValue = >( field: TField, value: DeepValue extends any[] @@ -750,6 +951,9 @@ export class FormApi< this.validateField(field, 'change') } + /** + * Inserts a value into an array field at the specified index, shifting the subsequent values to the right. + */ insertFieldValue = async >( field: TField, index: number, @@ -774,6 +978,9 @@ export class FormApi< await this.validateField(field, 'change') } + /** + * Replaces a value into an array field at the specified index. + */ replaceFieldValue = async >( field: TField, index: number, @@ -797,6 +1004,9 @@ export class FormApi< await this.validateArrayFieldsStartingFrom(field, index, 'change') } + /** + * Removes a value from an array field at the specified index. + */ removeFieldValue = async >( field: TField, index: number, @@ -833,6 +1043,9 @@ export class FormApi< await this.validateArrayFieldsStartingFrom(field, index, 'change') } + /** + * Swaps the values at the specified indices within an array field. + */ swapFieldValues = >( field: TField, index1: number, @@ -856,6 +1069,9 @@ export class FormApi< this.validateField(`${field}[${index2}]` as DeepKeys, 'change') } + /** + * Moves the value at the first specified index to the second specified index within an array field. + */ moveFieldValues = >( field: TField, index1: number, diff --git a/packages/form-core/src/mergeForm.ts b/packages/form-core/src/mergeForm.ts index cd08722cb..202e307af 100644 --- a/packages/form-core/src/mergeForm.ts +++ b/packages/form-core/src/mergeForm.ts @@ -2,6 +2,9 @@ import type { FormApi } from './FormApi' import type { Validator } from './types' import type { NoInfer } from './util-types' +/** + * @private + */ export function mutateMergeDeep(target: object, source: object): object { const targetKeys = Object.keys(target) const sourceKeys = Object.keys(source) diff --git a/packages/form-core/src/types.ts b/packages/form-core/src/types.ts index 1e87173fa..13392e588 100644 --- a/packages/form-core/src/types.ts +++ b/packages/form-core/src/types.ts @@ -1,16 +1,28 @@ export type ValidationError = undefined | false | null | string -// If/when TypeScript supports higher-kinded types, this should not be `unknown` anymore +/** + * If/when TypeScript supports higher-kinded types, this should not be `unknown` anymore + * @private + */ export type Validator = () => { validate(options: { value: Type }, fn: Fn): ValidationError validateAsync(options: { value: Type }, fn: Fn): Promise } -// "server" is only intended for SSR/SSG validation and should not execute anything +/** + * "server" is only intended for SSR/SSG validation and should not execute anything + * @private + */ export type ValidationCause = 'change' | 'blur' | 'submit' | 'mount' | 'server' +/** + * @private + */ export type ValidationErrorMapKeys = `on${Capitalize}` +/** + * @private + */ export type ValidationErrorMap = { [K in ValidationErrorMapKeys]?: ValidationError } diff --git a/packages/form-core/src/util-types.ts b/packages/form-core/src/util-types.ts index 25dd9f61b..8a9a107cd 100644 --- a/packages/form-core/src/util-types.ts +++ b/packages/form-core/src/util-types.ts @@ -1,6 +1,9 @@ type Nullable = T | null type IsNullable = [null] extends [T] ? true : false +/** + * @private + */ export type RequiredByKey = Omit & Required> @@ -13,13 +16,22 @@ type NarrowRaw = [K in keyof A]: A[K] extends Function ? A[K] : NarrowRaw } +/** + * @private + */ export type NoInfer = [T][T extends any ? 0 : never] +/** + * @private + */ export type Narrow = Try> type Try = A1 extends A2 ? A1 : Catch -// Hack to get TypeScript to show simplified types in error messages +/** + * Hack to get TypeScript to show simplified types in error messages + * @private + */ export type Pretty = { [K in keyof T]: T[K] } & {} type ComputeRange< @@ -67,6 +79,9 @@ type PrefixObjectAccessor = { : never }[keyof T] +/** + * The keys of an object or array, deeply nested. + */ export type DeepKeys = TDepth['length'] extends 5 ? never : unknown extends T @@ -89,9 +104,8 @@ type PrefixFromDepth< > = TDepth['length'] extends 0 ? T : `.${T}` /** - Infer the type of a deeply nested property within an object or an array. - See the tests in `util-types.test-d.ts` for usage. -*/ + * Infer the type of a deeply nested property within an object or an array. + */ export type DeepValue< // The object or array in which we have the property whose type we're trying to infer TValue, diff --git a/packages/form-core/src/utils.ts b/packages/form-core/src/utils.ts index e6c554b36..535b1d3a0 100644 --- a/packages/form-core/src/utils.ts +++ b/packages/form-core/src/utils.ts @@ -8,6 +8,9 @@ export type Updater = | TOutput | UpdaterFn +/** + * @private + */ export function functionalUpdate( updater: Updater, input: TInput, @@ -19,6 +22,7 @@ export function functionalUpdate( /** * Get a value from an object using a path, including dot notation. + * @private */ export function getBy(obj: any, path: any) { const pathObj = makePathArray(path) @@ -33,6 +37,7 @@ export function getBy(obj: any, path: any) { /** * Set a value on an object using a path, including dot notation. + * @private */ export function setBy(obj: any, _path: any, updater: Updater) { const path = makePathArray(_path) @@ -75,6 +80,7 @@ export function setBy(obj: any, _path: any, updater: Updater) { /** * Delete a field on an object using a path, including dot notation. + * @private */ export function deleteBy(obj: any, _path: any) { const path = makePathArray(_path) @@ -130,6 +136,9 @@ const reFindMultiplePeriods = /\.{2,}/gm const intPrefix = '__int__' const intReplace = `${intPrefix}$1` +/** + * @private + */ export function makePathArray(str: string) { if (typeof str !== 'string') { throw new Error('Path must be a string.') @@ -152,6 +161,9 @@ export function makePathArray(str: string) { }) } +/** + * @private + */ export function isNonEmptyArray(obj: any) { return !(Array.isArray(obj) && obj.length === 0) } @@ -161,12 +173,18 @@ interface AsyncValidatorArrayPartialOptions { asyncDebounceMs?: number } +/** + * @private + */ export interface AsyncValidator { cause: ValidationCause validate: T debounceMs: number } +/** + * @private + */ export function getAsyncValidatorArray( cause: ValidationCause, options: AsyncValidatorArrayPartialOptions, @@ -240,11 +258,17 @@ interface SyncValidatorArrayPartialOptions { validators?: T } +/** + * @private + */ export interface SyncValidator { cause: ValidationCause validate: T } +/** + * @private + */ export function getSyncValidatorArray( cause: ValidationCause, options: SyncValidatorArrayPartialOptions, diff --git a/packages/form-core/tsconfig.docs.json b/packages/form-core/tsconfig.docs.json new file mode 100644 index 000000000..e625eeece --- /dev/null +++ b/packages/form-core/tsconfig.docs.json @@ -0,0 +1,4 @@ +{ + "extends": "./tsconfig.json", + "exclude": ["src/tests/**/*"] +} diff --git a/packages/lit-form/tsconfig.docs.json b/packages/lit-form/tsconfig.docs.json new file mode 100644 index 000000000..c6b51de41 --- /dev/null +++ b/packages/lit-form/tsconfig.docs.json @@ -0,0 +1,9 @@ +{ + "extends": "./tsconfig.json", + "exclude": ["tests", ".eslintrc.cjs", "vite.config.ts"], + "compilerOptions": { + "paths": { + "@tanstack/form-core": ["../form-core/src"] + } + } +} diff --git a/packages/react-form/src/types.ts b/packages/react-form/src/types.ts index 25d013ab0..5ee688e5e 100644 --- a/packages/react-form/src/types.ts +++ b/packages/react-form/src/types.ts @@ -6,6 +6,9 @@ import type { } from '@tanstack/form-core' import type { FunctionComponent } from 'react' +/** + * The field options. + */ export type UseFieldOptions< TParentData, TName extends DeepKeys, diff --git a/packages/react-form/src/useField.tsx b/packages/react-form/src/useField.tsx index 49f29670f..25ed5f058 100644 --- a/packages/react-form/src/useField.tsx +++ b/packages/react-form/src/useField.tsx @@ -6,6 +6,9 @@ import type { NodeType, UseFieldOptions } from './types' import type { DeepKeys, DeepValue, Validator } from '@tanstack/form-core' declare module '@tanstack/form-core' { + /** + * When using `@tanstack/react-form`, the core field API is extended at type level with additional methods for React-specific functionality: + */ // eslint-disable-next-line no-shadow interface FieldApi< TParentData, @@ -18,10 +21,18 @@ declare module '@tanstack/form-core' { | undefined = undefined, TData extends DeepValue = DeepValue, > { + /** + * A pre-bound and type-safe sub-field component using this field as a root. + */ Field: FieldComponent } } +/** + * A type representing a hook for using a field in a form with the given form data type. + * + * A function that takes an optional object with a `name` property and field options, and returns a `FieldApi` instance for the specified field. + */ export type UseField< TParentData, TFormValidator extends @@ -40,6 +51,12 @@ export type UseField< >, ) => FieldApi +/** + * A hook for managing a field in a form. + * @param opts An object with field options. + * + * @returns The `FieldApi` instance for the specified field. + */ export function useField< TParentData, TName extends DeepKeys, @@ -93,6 +110,9 @@ export function useField< return fieldApi as never } +/** + * @param children A render function that takes a field API instance and returns a React element. + */ type FieldComponentProps< TParentData, TName extends DeepKeys, @@ -115,6 +135,9 @@ type FieldComponentProps< ) => NodeType } & UseFieldOptions +/** + * A type alias representing a field component for a specific form data type. + */ export type FieldComponent< TParentData, TFormValidator extends @@ -140,6 +163,11 @@ export type FieldComponent< 'form' >) => NodeType +/** + * A function component that takes field options and a render function as children and returns a React component. + * + * The `Field` component uses the `useField` hook internally to manage the field instance. + */ export const Field = (< TParentData, TName extends DeepKeys, diff --git a/packages/react-form/src/useForm.tsx b/packages/react-form/src/useForm.tsx index 2bc790ab1..36d10b6eb 100644 --- a/packages/react-form/src/useForm.tsx +++ b/packages/react-form/src/useForm.tsx @@ -8,13 +8,28 @@ import type { FormOptions, FormState, Validator } from '@tanstack/form-core' import type { NodeType } from './types' declare module '@tanstack/form-core' { + /** + * When using `@tanstack/react-form`, the core form API is extended at type level with additional methods for React-specific functionality: + */ // eslint-disable-next-line no-shadow interface FormApi { + /** + * A React component to render form fields. With this, you can render and manage individual form fields. + */ Field: FieldComponent + /** + * A custom React hook that provides functionalities related to individual form fields. It gives you access to field values, errors, and allows you to set or update field values. + */ useField: UseField + /** + * A `useStore` hook that connects to the internal store of the form. It can be used to access the form's current state or any other related state information. You can optionally pass in a selector function to cherry-pick specific parts of the state + */ useStore: >>( selector?: (state: NoInfer>) => TSelected, ) => TSelected + /** + * A `Subscribe` function that allows you to listen and react to changes in the form's state. It's especially useful when you need to execute side effects or render specific components in response to state updates. + */ Subscribe: >>(props: { /** TypeScript versions <=5.0.4 have a bug that prevents @@ -33,6 +48,11 @@ declare module '@tanstack/form-core' { } } +/** + * A custom React Hook that returns an instance of the `FormApi` class. + * + * This API encapsulates all the necessary functionalities related to the form. It allows you to manage form state, handle submissions, and interact with form fields + */ export function useForm< TFormData, TFormValidator extends Validator | undefined = undefined, diff --git a/packages/react-form/tsconfig.docs.json b/packages/react-form/tsconfig.docs.json new file mode 100644 index 000000000..918205122 --- /dev/null +++ b/packages/react-form/tsconfig.docs.json @@ -0,0 +1,9 @@ +{ + "extends": "./tsconfig.json", + "exclude": ["src/tests/**/*"], + "compilerOptions": { + "paths": { + "@tanstack/form-core": ["../form-core/src"] + } + } +} diff --git a/packages/solid-form/tsconfig.docs.json b/packages/solid-form/tsconfig.docs.json new file mode 100644 index 000000000..cbb038e33 --- /dev/null +++ b/packages/solid-form/tsconfig.docs.json @@ -0,0 +1,9 @@ +{ + "extends": "./tsconfig.json", + "exclude": ["tests", ".eslintrc.cjs", "test-setup.ts", "vite.config.ts"], + "compilerOptions": { + "paths": { + "@tanstack/form-core": ["../form-core/src"] + } + } +} diff --git a/packages/vue-form/tsconfig.docs.json b/packages/vue-form/tsconfig.docs.json new file mode 100644 index 000000000..918205122 --- /dev/null +++ b/packages/vue-form/tsconfig.docs.json @@ -0,0 +1,9 @@ +{ + "extends": "./tsconfig.json", + "exclude": ["src/tests/**/*"], + "compilerOptions": { + "paths": { + "@tanstack/form-core": ["../form-core/src"] + } + } +} diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index c9082cc8d..8a1a5cdc2 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -95,6 +95,12 @@ importers: solid-js: specifier: ^1.7.8 version: 1.7.12 + typedoc: + specifier: ^0.25.13 + version: 0.25.13(typescript@5.4.2) + typedoc-plugin-markdown: + specifier: ^4.0.3 + version: 4.0.3(typedoc@0.25.13(typescript@5.4.2)) typescript: specifier: 5.4.2 version: 5.4.2 @@ -3914,6 +3920,9 @@ packages: resolution: {integrity: sha512-n5M855fKb2SsfMIiFFoVrABHJC8QtHwVx+mHWP3QcEqBHYienj5dHSgjbxtC0WEZXYt4wcD6zrQElDPhFuZgfA==} engines: {node: '>=12'} + ansi-sequence-parser@1.1.1: + resolution: {integrity: sha512-vJXt3yiaUL4UU546s3rPXlsry/RnM730G1+HkpKE012AN0sx1eOrxSu95oKDIonskeLTijMgqWZ3uDEe3NFvyg==} + ansi-styles@3.2.1: resolution: {integrity: sha512-VT0ZI6kZRdTh8YyJw3SMbYm/u+NqfsAxEpWO0Pf9sq8/e94WxxOpPKx9FR1FlyCtOVDNOQ+8ntlqFxiRc+r5qA==} engines: {node: '>=4'} @@ -6023,6 +6032,9 @@ packages: resolution: {integrity: sha512-jumlc0BIUrS3qJGgIkWZsyfAM7NCWiBcCDhnd+3NNM5KbBmLTgHVfWBcg6W+rLUsIpzpERPsvwUP7CckAQSOoA==} engines: {node: '>=12'} + lunr@2.3.9: + resolution: {integrity: sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==} + lz-string@1.5.0: resolution: {integrity: sha512-h5bgJWpxJNswbU7qCrV0tIKQCaS3blPDrqKWx+QxzuzL1zGUzij9XCWLrSLsJPu5t+eWA/ycetzYAO5IOMcWAQ==} hasBin: true @@ -6065,6 +6077,11 @@ packages: resolution: {integrity: sha512-hdN1wVrZbb29eBGiGjJbeP8JbKjq1urkHJ/LIP/NY48MZ1QVXUsQBV1G1zvYFHn1XE06cwjBsOI2K3Ulnj1YXQ==} engines: {node: '>=8'} + marked@4.3.0: + resolution: {integrity: sha512-PRsaiG84bK+AMvxziE/lCFss8juXjNaWzVbN5tXAm4XjeaS9NAHhop+PjQxz2A9h8Q4M/xGmzP8vqNwy6JeK0A==} + engines: {node: '>= 12'} + hasBin: true + media-typer@0.3.0: resolution: {integrity: sha512-dq+qelQ9akHpcOl/gUVRTxVIOkAJ1wR3QAvb4RsVjS8oVoFjDGTc679wJYmUmknUF5HwMLOgb5O+a3KxfWapPQ==} engines: {node: '>= 0.6'} @@ -7336,6 +7353,9 @@ packages: resolution: {integrity: sha512-L2tNE60i5gRNe5eFNSjUAqt2rCIbKj9jp/50zCfsw8bSBX6noHamR7FDhaecyrNBk6ZgGEEAjxGe4C6iqelwZw==} hasBin: true + shiki@0.14.7: + resolution: {integrity: sha512-dNPAPrxSc87ua2sKJ3H5dQ/6ZaY8RNnaAqK+t0eG7p0Soi2ydiqbGOTaZCqaYvA/uZYfS1LJnemt3Q+mSfcPCg==} + side-channel@1.0.4: resolution: {integrity: sha512-q5XPytqFEIKHkGdiMIrY10mvLRvnQh42/+GoBlFW3b2LXLE2xxJpZFdm94we0BaoV3RwJyGqg5wS7epxTv0Zvw==} @@ -7862,6 +7882,18 @@ packages: typed-assert@1.0.9: resolution: {integrity: sha512-KNNZtayBCtmnNmbo5mG47p1XsCyrx6iVqomjcZnec/1Y5GGARaxPs6r49RnSPeUP3YjNYiU9sQHAtY4BBvnZwg==} + typedoc-plugin-markdown@4.0.3: + resolution: {integrity: sha512-0tZbeVGGCd4+lpoIX+yHWgUfyaLZCQCgJOpuVdTtOtD3+jKaedJ4sl/tkNaYBPeWVKiyDkSHfGuHkq53jlzIFg==} + peerDependencies: + typedoc: 0.25.x + + typedoc@0.25.13: + resolution: {integrity: sha512-pQqiwiJ+Z4pigfOnnysObszLiU3mVLWAExSPf+Mu06G/qsc3wzbuM56SZQvONhHLncLUhYzOVkjFFpFfL5AzhQ==} + engines: {node: '>= 16'} + hasBin: true + peerDependencies: + typescript: 4.6.x || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x || 5.2.x || 5.3.x || 5.4.x + types-react-dom@19.0.0-rc.1: resolution: {integrity: sha512-VSLZJl8VXCD0fAWp7DUTFUDCcZ8DVXOQmjhJMD03odgeFmu14ZQJHCXeETm3BEAhJqfgJaFkLnGkQv88sRx0fQ==} @@ -8184,6 +8216,12 @@ packages: vlq@0.2.3: resolution: {integrity: sha512-DRibZL6DsNhIgYQ+wNdWDL2SL3bKPlVrRiBqV5yuMm++op8W4kGFtaQfCs4KEJn0wBZcHVHJ3eoywX8983k1ow==} + vscode-oniguruma@1.7.0: + resolution: {integrity: sha512-L9WMGRfrjOhgHSdOYgCt/yRMsXzLDJSL7BPrOZt73gU0iWO4mpqzqQzOz5srxqTvMBaR0XZTSrVWo4j55Rc6cA==} + + vscode-textmate@8.0.0: + resolution: {integrity: sha512-AFbieoL7a5LMqcnOF04ji+rpXadgOXnZsxQr//r83kLPr7biP7am3g9zbaZIaBGwBRWeSvoMD4mgPdX3e4NWBg==} + vue-component-type-helpers@1.8.4: resolution: {integrity: sha512-6bnLkn8O0JJyiFSIF0EfCogzeqNXpnjJ0vW/SZzNHfe6sPx30lTtTXlE5TFs2qhJlAtDFybStVNpL73cPe3OMQ==} @@ -11593,6 +11631,8 @@ snapshots: ansi-regex@6.0.1: {} + ansi-sequence-parser@1.1.1: {} + ansi-styles@3.2.1: dependencies: color-convert: 1.9.3 @@ -14070,6 +14110,8 @@ snapshots: lru-cache@7.18.3: {} + lunr@2.3.9: {} + lz-string@1.5.0: {} magic-string@0.16.0: @@ -14122,6 +14164,8 @@ snapshots: map-obj@4.3.0: {} + marked@4.3.0: {} + media-typer@0.3.0: {} memfs@3.5.3: @@ -15551,6 +15595,13 @@ snapshots: sherif-windows-arm64: 0.8.4 sherif-windows-x64: 0.8.4 + shiki@0.14.7: + dependencies: + ansi-sequence-parser: 1.1.1 + jsonc-parser: 3.2.1 + vscode-oniguruma: 1.7.0 + vscode-textmate: 8.0.0 + side-channel@1.0.4: dependencies: call-bind: 1.0.7 @@ -16099,6 +16150,18 @@ snapshots: typed-assert@1.0.9: {} + typedoc-plugin-markdown@4.0.3(typedoc@0.25.13(typescript@5.4.2)): + dependencies: + typedoc: 0.25.13(typescript@5.4.2) + + typedoc@0.25.13(typescript@5.4.2): + dependencies: + lunr: 2.3.9 + marked: 4.3.0 + minimatch: 9.0.3 + shiki: 0.14.7 + typescript: 5.4.2 + types-react-dom@19.0.0-rc.1: dependencies: '@types/react': 18.3.3 @@ -16429,6 +16492,10 @@ snapshots: vlq@0.2.3: {} + vscode-oniguruma@1.7.0: {} + + vscode-textmate@8.0.0: {} + vue-component-type-helpers@1.8.4: {} vue-demi@0.14.6(vue@3.3.4): diff --git a/scripts/reference-docs.js b/scripts/reference-docs.js new file mode 100644 index 000000000..fad58707e --- /dev/null +++ b/scripts/reference-docs.js @@ -0,0 +1,124 @@ +import * as path from 'node:path' +import { fileURLToPath } from 'node:url' +import { promises } from 'node:fs' +import * as TypeDoc from 'typedoc' + +// Prevent Knip from removing the import +import { load } from './typedoc-remove-prefix.mjs' +;(() => load)() + +const { rm, mkdir } = promises +const __dirname = path.dirname(fileURLToPath(import.meta.url)) + +/** + * @type {Partial} + */ +const options = { + plugin: [ + 'typedoc-plugin-markdown', + path.resolve(__dirname, './typedoc-remove-prefix.mjs'), + ], + hideGenerator: true, + readme: 'none', + flattenOutputFiles: true, + entryFileName: 'index', + hideBreadcrumbs: true, + hidePageHeader: true, + useCodeBlocks: true, + excludePrivate: true, +} + +const packages = [ + { + name: 'form-core', + entryPoint: path.resolve(__dirname, '../packages/form-core/src/index.ts'), + tsconfig: path.resolve( + __dirname, + '../packages/form-core/tsconfig.docs.json', + ), + outputDir: path.resolve(__dirname, '../docs/reference'), + }, + { + name: 'angular-form', + entryPoint: path.resolve( + __dirname, + '../packages/angular-form/src/index.ts', + ), + tsconfig: path.resolve( + __dirname, + '../packages/angular-form/tsconfig.docs.json', + ), + outputDir: path.resolve(__dirname, '../docs/framework/angular/reference'), + exclude: ['packages/form-core/**/*'], + }, + { + name: 'lit-form', + entryPoint: path.resolve(__dirname, '../packages/lit-form/src/index.ts'), + tsconfig: path.resolve( + __dirname, + '../packages/lit-form/tsconfig.docs.json', + ), + outputDir: path.resolve(__dirname, '../docs/framework/lit/reference'), + exclude: ['packages/form-core/**/*'], + }, + { + name: 'react-form', + entryPoint: path.resolve(__dirname, '../packages/react-form/src/index.ts'), + tsconfig: path.resolve( + __dirname, + '../packages/react-form/tsconfig.docs.json', + ), + outputDir: path.resolve(__dirname, '../docs/framework/react/reference'), + exclude: ['packages/form-core/**/*'], + }, + { + name: 'solid-form', + entryPoint: path.resolve(__dirname, '../packages/solid-form/src/index.ts'), + tsconfig: path.resolve( + __dirname, + '../packages/solid-form/tsconfig.docs.json', + ), + outputDir: path.resolve(__dirname, '../docs/framework/solid/reference'), + exclude: ['packages/form-core/**/*'], + }, + { + name: 'vue-form', + entryPoint: path.resolve(__dirname, '../packages/vue-form/src/index.ts'), + tsconfig: path.resolve( + __dirname, + '../packages/vue-form/tsconfig.docs.json', + ), + outputDir: path.resolve(__dirname, '../docs/framework/vue/reference'), + exclude: ['packages/form-core/**/*'], + }, +] + +async function main() { + for (const pkg of packages) { + // Clean and recreate the output directories + try { + await rm(pkg.outputDir, { recursive: true }) + } catch (error) { + // @ts-ignore + if (error.code !== 'ENOENT') { + throw error + } + } + await mkdir(pkg.outputDir, { recursive: true }) + + const app = await TypeDoc.Application.bootstrapWithPlugins({ + ...options, + entryPoints: [pkg.entryPoint], + tsconfig: pkg.tsconfig, + exclude: pkg.exclude, + }) + + const project = await app.convert() + + if (project) { + await app.generateDocs(project, pkg.outputDir) + } + } +} + +main().catch(console.error) diff --git a/scripts/typedoc-remove-prefix.mjs b/scripts/typedoc-remove-prefix.mjs new file mode 100644 index 000000000..f9cfc8d76 --- /dev/null +++ b/scripts/typedoc-remove-prefix.mjs @@ -0,0 +1,24 @@ +import { MarkdownRendererEvent } from 'typedoc-plugin-markdown' + +/** + * @param {import("typedoc-plugin-markdown").MarkdownApplication} app + */ +export function load(app) { + app.renderer.on( + MarkdownRendererEvent.BEGIN, + /** + * @param {import("typedoc-plugin-markdown").MarkdownRendererEvent} renderer + */ (renderer) => { + renderer.urls = renderer.urls?.map((urlMapping) => { + const name = urlMapping.url.split('.') + if (name[0] !== 'index') { + name.splice(0, 1) + } + const newBasename = name.join('.').toLowerCase() + urlMapping.url = newBasename + urlMapping.model.url = newBasename + return urlMapping + }) + }, + ) +}