Skip to content

Commit bc270fb

Browse files
crutchcorncrutchcorn
committed
docs: update reference docs for React
1 parent 6a6c4f5 commit bc270fb

File tree

11 files changed

+129
-150
lines changed

11 files changed

+129
-150
lines changed

‎docs/framework/react/quick-start.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,9 @@ export default function App() {
1515
defaultValues: {
1616
fullName: '',
1717
},
18-
onSubmit: async ({ values }) => {
18+
onSubmit: async ({ value }) => {
1919
// Do something with form data
20-
console.log(values)
20+
console.log(value)
2121
},
2222
})
2323

‎docs/framework/react/reference/Field.md‎

Lines changed: 36 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -3,22 +3,31 @@ id: field
33
title: Field
44
---
55

6-
### `FieldComponent<TParentData>`
6+
### `FieldComponent<TParentData, TFormValidator>`
77

88
A type alias representing a field component for a specific form data type.
99

1010
```tsx
11-
export type FieldComponent = <TField extends DeepKeys<TParentData>>({
11+
export type FieldComponent<
12+
TParentData,
13+
TFormValidator extends
14+
| Validator<TParentData, unknown>
15+
| undefined = undefined,
16+
> = <
17+
TName extends DeepKeys<TParentData>,
18+
TFieldValidator extends
19+
| Validator<DeepValue<TParentData, TName>, unknown>
20+
| undefined = undefined,
21+
TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
22+
>({
1223
children,
1324
...fieldOptions
14-
}: {
15-
children: (
16-
fieldApi: FieldApi<DeepValue<TParentData, TField>, TParentData>,
17-
) => any
18-
name: TField
19-
} & Omit<
20-
FieldOptions<DeepValue<TParentData, TField>, TParentData>,
21-
'name'
25+
}: FieldComponentProps<
26+
TParentData,
27+
TName,
28+
TFieldValidator,
29+
TFormValidator,
30+
TData
2231
>) => any
2332
```
2433
@@ -27,39 +36,35 @@ A function component that takes field options and a render function as children
2736
### `Field`
2837
2938
```tsx
30-
export function Field<TData, TParentData>({
39+
export function Field<
40+
TParentData,
41+
TName extends DeepKeys<TParentData>,
42+
TFieldValidator extends
43+
| Validator<DeepValue<TParentData, TName>, unknown>
44+
| undefined = undefined,
45+
TFormValidator extends
46+
| Validator<TParentData, unknown>
47+
| undefined = undefined,
48+
>({
3149
children,
3250
...fieldOptions
33-
}: { children: (fieldApi: FieldApi<TData, TParentData>) => any } & FieldOptions<
34-
TData,
35-
TParentData
36-
>): any
51+
}: {
52+
children: (
53+
fieldApi: FieldApi<TParentData, TName, TFieldValidator, TFormValidator>,
54+
) => any
55+
} & UseFieldOptions<TParentData, TName, TFieldValidator, TFormValidator>): JSX.Element
3756
```
3857

3958
A functional React component that renders a form field.
4059

4160
- ```tsx
42-
children: (fieldApi: FieldApi<TData, TParentData>) => any
61+
children: (fieldApi: FieldApi<TParentData, TName, TFieldValidator, TFormValidator>) => any
4362
```
4463
- A render function that takes a field API instance and returns a React element.
4564
- ```tsx
46-
fieldOptions: FieldOptions<TData, TParentData>
65+
fieldOptions: UseFieldOptions<TParentData, TName, TFieldValidator, TFormValidator>
4766
```
4867
- The field options.
4968

5069
The `Field` component uses the `useField` hook internally to manage the field instance.
5170

52-
### `createFieldComponent`
53-
54-
```tsx
55-
export function createFieldComponent<TParentData>(
56-
formApi: FormApi<TParentData>,
57-
): FieldComponent<TParentData>
58-
```
59-
60-
A factory function that creates a connected field component for a specific form API instance.
61-
62-
- ```tsx
63-
formApi: FormApi<TParentData>
64-
```
65-
- The form API instance to connect the field component to.

‎docs/framework/react/reference/createFormFactory.md‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -3,34 +3,34 @@ id: createFormFactory
33
title: createFormFactory
44
---
55

6-
### `createFormFactory`
6+
### `createFormFactory<TFormData, TFormValidator>`
77

88
```tsx
9-
export function createFormFactory<TFormData>(
10-
opts?: FormOptions<TFormData>,
11-
): FormFactory<TFormData>
9+
export function createFormFactory<TFormData, TFormValidator>(
10+
opts?: FormOptions<TFormData, TFormValidator>,
11+
): FormFactory<TFormData, TFormValidator>
1212
```
1313

14-
A function that creates a new `FormFactory<TFormData>` instance.
14+
A function that creates a new `FormFactory<TFormData, TFormValidator>` instance.
1515

1616
- `opts`
17-
- Optional form options and a `listen` function to be called with the form state.
17+
- Optional form options.
1818

19-
### `FormFactory<TFormData>`
19+
### `FormFactory<TFormData, TFormValidator>`
2020

2121
A type representing a form factory. Form factories provide a type-safe way to interact with the form API as opposed to using the globally exported form utilities.
2222

2323
```tsx
24-
export type FormFactory<TFormData> = {
25-
useForm: (opts?: FormOptions<TFormData>) => FormApi<TFormData>
24+
export type FormFactory<TFormData, TFormValidator> = {
25+
useForm: (opts?: FormOptions<TFormData, TFormValidator>) => FormApi<TFormData>
2626
useField: UseField<TFormData>
27-
Field: FieldComponent<TFormData>
27+
Field: FieldComponent<TFormData, TFormValidator>
2828
}
2929
```
3030

3131
- `useForm`
32-
- A custom hook that creates and returns a new instance of the `FormApi<TFormData>` class.
32+
- A custom hook that creates and returns a new instance of the `FormApi` class.
3333
- `useField`
34-
- A custom hook that returns an instance of the `FieldApi<TFormData>` class.
34+
- A custom hook that returns an instance of the `FieldApi` class.
3535
- `Field`
3636
- A form field component.

‎docs/framework/react/reference/fieldApi.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,11 @@ id: fieldApi
33
title: Field API
44
---
55

6-
### `FieldApi<TData, TParentData>`
6+
### `FieldApi<TParentData, TName, TFieldValidator, TFormValidator, TData>`
77

8-
When using `@tanstack/react-form`, the [core field API](../../reference/fieldApi) is extended with additional methods for React-specific functionality:
8+
When using `@tanstack/react-form`, the [core field API](../../reference/fieldApi) is extended at type level with additional methods for React-specific functionality:
99

1010
- ```tsx
11-
Field: FieldComponent<TData, TParentData>
11+
Field: FieldComponent<TParentData, TFormValidator>
1212
```
1313
- A pre-bound and type-safe sub-field component using this field as a root.

‎docs/framework/react/reference/formApi.md‎

Lines changed: 18 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -3,23 +3,32 @@ id: formApi
33
title: Form API
44
---
55

6-
### `FormApi<TFormData>`
6+
### `FormApi<TFormData, TFormValidator>`
77

8-
When using `@tanstack/react-form`, the [core form API](../../reference/formApi) is extended with additional methods for React-specific functionality:
8+
When using `@tanstack/react-form`, the [core form API](../../reference/formApi) is extended at type level with additional methods for React-specific functionality:
99

1010
- ```tsx
11-
Field: FieldComponent<TFormData>
11+
Provider: (props: PropsWithChildren) => JSX.Element
1212
```
13-
- A pre-bound and type-safe field component, specific to this forms instance.
13+
- React provider use to wrap your components. Reference React's [ContextProvider]("https://react.dev/reference/react/createContext#provider")
14+
- ```tsx
15+
Field: FieldComponent<TFormData, TFormValidator>
16+
```
17+
- A React component to render form fields. With this, you can render and manage individual form fields.
1418
- ```tsx
1519
useField: UseField<TFormData>
1620
```
17-
- A pre-bound and type-safe custom hook to use fields from this form instance.
21+
- 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.
1822
- ```tsx
19-
useStore<TSelected = NoInfer<FormState<TFormData>>>(selector?: (state: NoInfer<FormState<TFormData>>) => TSelected): TSelected
23+
useStore: <TSelected = NoInfer<FormState<TFormData>>>(
24+
selector?: (state: NoInfer<FormState<TFormData>>) => TSelected,
25+
) => TSelected
2026
```
21-
- A custom hook to use the form store.
27+
- 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
2228
- ```tsx
23-
Subscribe<TSelected = NoInfer<FormState<TFormData>>>(props: {selector?: (state: NoInfer<FormState<TFormData>>) => TSelected; children: ((state: NoInfer<TSelected>) => React.ReactNode) | React.ReactNode}): any
29+
Subscribe: <TSelected = NoInfer<FormState<TFormData>>>(props: {
30+
selector?: (state: NoInfer<FormState<TFormData>>) => TSelected
31+
children: ((state: NoInfer<TSelected>) => ReactNode) | ReactNode
32+
}) => JSX.Element
2433
```
25-
- A subscription component to provide the selected form state to children.
34+
- 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.

‎docs/framework/react/reference/useField.md‎

Lines changed: 35 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -8,44 +8,59 @@ title: useField
88
A type representing a hook for using a field in a form with the given form data type.
99

1010
```tsx
11-
export type UseField = <TField extends DeepKeys<TParentData>>(
12-
opts?: { name: TField } & FieldOptions<
13-
DeepValue<TParentData, TField>,
14-
TParentData
11+
export type UseField<TParentData> = <
12+
TName extends DeepKeys<TParentData>,
13+
TFieldValidator extends
14+
| Validator<DeepValue<TParentData, TName>, unknown>
15+
| undefined = undefined,
16+
TFormValidator extends
17+
| Validator<TParentData, unknown>
18+
| undefined = undefined,
19+
>(
20+
opts?: { name: Narrow<TName> } & UseFieldOptions<
21+
TParentData,
22+
TName,
23+
TFieldValidator,
24+
TFormValidator
1525
>,
16-
) => FieldApi<DeepValue<TParentData, TField>, TParentData>
26+
) => FieldApi<
27+
TParentData,
28+
TName,
29+
TFieldValidator,
30+
TFormValidator,
31+
DeepValue<TParentData, TName>
32+
>
1733
```
1834
1935
- A function that takes an optional object with a `name` property and field options, and returns a `FieldApi` instance for the specified field.
2036
2137
### `useField`
2238
2339
```tsx
24-
export function useField<TData, TParentData>(
25-
opts: FieldOptions<TData, TParentData>,
26-
): FieldApi<TData, TParentData>
40+
export function useField<
41+
TParentData,
42+
TName extends DeepKeys<TParentData>,
43+
TFieldValidator extends
44+
| Validator<DeepValue<TParentData, TName>, unknown>
45+
| undefined = undefined,
46+
TFormValidator extends
47+
| Validator<TParentData, unknown>
48+
| undefined = undefined,
49+
>(
50+
opts: UseFieldOptions<TParentData, TName, TFieldValidator, TFormValidator>,
51+
): FieldApi<TParentData, TName, TFieldValidator, TFormValidator>
2752
```
2853

2954
A hook for managing a field in a form.
3055

3156
- ```tsx
32-
opts: FieldOptions<TData, TParentData>
57+
opts: UseFieldOptions<TParentData, TName, TFieldValidator, TFormValidator>
3358
```
3459
- An object with field options.
3560

3661
#### Returns
3762

3863
- ```tsx
39-
FieldApi<TData, TParentData>
64+
FieldApi<TParentData, TName, TFieldValidator, TFormValidator>
4065
```
4166
- The `FieldApi` instance for the specified field.
42-
43-
### `createUseField`
44-
45-
```tsx
46-
export function createUseField<TParentData>(
47-
formApi: FormApi<TParentData>,
48-
): UseField<TParentData>
49-
```
50-
51-
A function that creates a `UseField` hook bound to the given `formApi`.

‎docs/framework/react/reference/useForm.md‎

Lines changed: 8 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -6,70 +6,13 @@ title: useForm
66
### `useForm`
77

88
```tsx
9-
export function useForm<TData>(opts?: FormOptions<TData>): FormApi<TData>
10-
```
11-
A custom react hook that returns an instance of the `FormApi<TData>` class.
9+
export function useForm<
10+
TFormData,
11+
TFormValidator extends Validator<TFormData, unknown> | undefined = undefined,
12+
>(
13+
opts?: FormOptions<TFormData, TFormValidator>,
14+
): FormApi<TFormData, TFormValidator>
15+
```
16+
A custom React Hook that returns an instance of the `FormApi` class.
1217
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
1318

14-
15-
16-
### `FormProps`
17-
18-
An object type representing the form component props.
19-
20-
- Inherits from `React.HTMLProps<HTMLFormElement>`.
21-
- `children: React.ReactNode`
22-
- The form's child elements.
23-
24-
```tsx
25-
onSubmit: (e: FormSubmitEvent) => void
26-
```
27-
- `onSubmit` function of type `FormSubmitEvent = React.FormEvent<HTMLFormElement>`
28-
29-
```tsx
30-
disabled: boolean
31-
```
32-
- `disabled` boolean to disable form
33-
34-
35-
36-
### Return value of `UseForm` is `FormApi<TFormData>`
37-
38-
- The `FormApi` contains the following properties
39-
40-
```tsx
41-
Provider: (props: { children: any }) => any
42-
```
43-
- React provider use to wrap your components
44-
- Reference React [ContextProvider]("https://react.dev/reference/react/createContext#provider")
45-
46-
47-
48-
```tsx
49-
Field: FieldComponent<TFormData, TFormData>getFormProps: () => FormProps
50-
```
51-
- A React component to render form fields. With this, you can render and manage individual form fields.
52-
53-
```tsx
54-
useField: UseField<TFormData>
55-
```
56-
- 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.
57-
58-
59-
```tsx
60-
useStore: <TSelected = NoInfer<FormState<TFormData>>>(
61-
selector?: (state: NoInfer<FormState<TFormData>>) => TSelected,
62-
) => TSelected
63-
```
64-
- 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
65-
66-
67-
```tsx
68-
Subscribe: <TSelected = NoInfer<FormState<TFormData>>>(props: {
69-
selector?: (state: NoInfer<FormState<TFormData>>) => TSelected
70-
children:
71-
| ((state: NoInfer<TSelected>) => React.ReactNode)
72-
| React.ReactNode
73-
}) => any
74-
```
75-
- 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.

‎docs/framework/solid/quick-start.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,9 @@ function App() {
1313
defaultValues: {
1414
fullName: '',
1515
},
16-
onSubmit: async (values) => {
16+
onSubmit: async ({ value }) => {
1717
// Do something with form data
18-
console.log(values)
18+
console.log(value)
1919
},
2020
}))
2121

0 commit comments

Comments
 (0)