Merge branch 'main' into reset-field

Author: harry-whorlow

CONTRIBUTING.md

@@ -17,21 +17,47 @@ If you are here to suggest a feature, first create an issue if it does not alrea
 If you have been assigned to fix an issue or develop a new feature, please follow these steps to get started:
 
 - Fork this repository.
-- Install dependencies by running `$ pnpm install`.
-  - We use [pnpm](https://pnpm.io/) v7 for package management.
-  - We use [nvm](https://github.com/nvm-sh/nvm) to manage node versions - please make sure to use the version mentioned in `.nvmrc`.
-- Run development server using `pnpm run watch`.
+- Install dependencies
+
+  ```bash
+  pnpm install
+  ```
+
+  - We use [pnpm](https://pnpm.io/) v9 for package management (run in case of pnpm-related issues).
+
+    ```bash
+    corepack enable && corepack prepare
+    ```
+
+  - We use [nvm](https://github.com/nvm-sh/nvm) to manage node versions - please make sure to use the version mentioned in `.nvmrc`
+
+    ```bash
+    nvm use
+    ```
+
+- Build all packages.
+
+  ```bash
+  pnpm build:all
+  ```
+
+- Run development server.
+
+  ```bash
+  pnpm run watch
+  ```
+
 - Implement your changes and tests to files in the `src/` directory and corresponding test files.
 - Document your changes in the appropriate doc page.
 - Git stage your required changes and commit (see below commit guidelines).
 - Submit PR for review.
 
 ### Editing the docs locally and previewing the changes
 
-The documentations for all the TanStack projects are hosted on [tanstack.com](https://tanstack.com), which is a Remix application (https://github.com/TanStack/tanstack.com). You need to run this app locally to preview your changes in the `TanStack/form` docs.
+The documentations for all the TanStack projects are hosted on [tanstack.com](https://tanstack.com), which is a TanStack Start application (https://github.com/TanStack/tanstack.com). You need to run this app locally to preview your changes in the `TanStack/form` docs.
 
 > [!NOTE]
-> The Remix app fetches the doc pages from GitHub in production, and searches for them at `../form/docs` in development. Your local clone of `TanStack/form` needs to be in the same directory as the local clone of `TansStack/tanstack.com`.
+> The website fetches the doc pages from GitHub in production, and searches for them at `../form/docs` in development. Your local clone of `TanStack/form` needs to be in the same directory as the local clone of `TansStack/tanstack.com`.
 
 You can follow these steps to set up the docs for local development:
 
@@ -85,13 +111,23 @@ https://github.com/fulopkovacs/form/assets/43729152/9d35a3c3-8153-4e74-9cb2-af27
 
 ### Running examples
 
-- Make sure you've installed the dependencies by running `$ pnpm install` in the repo's root directory.
-- If you want to run the example against your local changes, run `pnpm run watch` in the repo's root directory. Otherwise, it will be run against the latest TanStack Form release.
-- Run `pnpm run dev` in the selected examples' directory.
+- Make sure you've installed the dependencies in the repo's root directory.
+
+  ```bash
+  pnpm install
+  ```
+
+- If you want to run the example against your local changes, run below in the repo's root directory. Otherwise, it will be run against the latest TanStack Form release.
+
+  ```bash
+  pnpm run watch
+  ```
 
-#### Note on `examples/react-native`
+- Run below in the selected examples' directory.
 
-React Native example requires Expo to work. Please follow the instructions from example's README.md file to learn more.
+  ```bash
+  pnpm run dev
+  ```
 
 #### Note on standalone execution
 
@@ -103,8 +139,17 @@ You can use Gitpod (An Online Open Source VS Code like IDE which is free for Ope
 
 - clone the `TanStack/form` repo.
 - install all the dependencies in `/` and `/docs`.
-- run `npm start` in the root(`/`) to Auto-build files.
-- run `npm run dev` in `/docs`.
+- run below in the root(`/`) to Auto-build files.
+
+  ```bash
+  npm start
+  ```
+
+- run below in `/docs`.
+
+  ```bash
+  npm run dev
+  ```
 
 [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/TanStack/form)
 
@@ -119,7 +164,7 @@ We have very precise rules over how our git commit messages can be formatted. Th
 Each commit message consists of a **header**, a **body** and a **footer**. The header has a special
 format that includes a **type**, a **scope** and a **subject**:
 
-```
+```text
 <type>(<scope>): <subject>
 <BLANK LINE>
 <body>
@@ -138,17 +183,15 @@ Must be one of the following:
 - **feat**: A new feature
 - **fix**: A bug fix
 - **docs**: Documentation only changes
-- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing
-  semi-colons, etc)
+- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semicolons, etc.)
 - **refactor**: A code change that neither fixes a bug nor adds a feature
 - **perf**: A code change that improves performance
 - **test**: Adding missing or correcting existing tests
-- **chore**: Changes to the build process or auxiliary tools and libraries such as documentation
-  generation
+- **chore**: Changes to the build process or auxiliary tools and libraries such as documentation generation
 
 ### Scope
 
-The scope could be anything specifying place of the commit change. For example `useForm`, `useMutation` etc...
+The scope could be anything specifying place of the commit change. For example `form-core`, `react-form` etc...
 
 You can use `*` when the change affects more than a single scope.
 
@@ -174,11 +217,11 @@ The footer should contain any information about **Breaking Changes** and is also
 
 Here is an example of the release type that will be done based on a commit messages:
 
-| Commit message                                                                                                                                                                                   | Release type               |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- |
-| `fix(pencil): stop graphite breaking when too much pressure applied`                                                                                                                             | Patch Release              |
-| `feat(pencil): add 'graphiteWidth' option`                                                                                                                                                       | ~~Minor~~ Feature Release  |
-| `perf(pencil): remove graphiteWidth option`<br><br>`BREAKING CHANGE: The graphiteWidth option has been removed.`<br>`The default graphite width of 10mm is always used for performance reasons.` | ~~Major~~ Breaking Release |
+| Commit message                                                                                                                                                                                    | Release type               |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| fix(pencil): stop graphite breaking when too much pressure applied                                                                                                                                | Patch Release              |
+| feat(pencil): add `graphiteWidth` option                                                                                                                                                          | ~~Minor~~ Feature Release  |
+| perf(pencil): remove `graphiteWidth` option<br/><br/>BREAKING CHANGE: The `graphiteWidth` option has been removed.<br/>The default graphite width of 10mm is always used for performance reasons. | ~~Major~~ Breaking Release |
 
 ### Revert
 

docs/framework/react/guides/form-composition.md

@@ -3,7 +3,7 @@ id: form-composition
 title: Form Composition
 ---
 
-A common criticism of TanStack Form is its verbosity out-of-the-box. While this _can_ be useful for educational purposes - helping enforce understanding our APIs - it's not ideal in production usecases.
+A common criticism of TanStack Form is its verbosity out-of-the-box. While this _can_ be useful for educational purposes - helping enforce understanding our APIs - it's not ideal in production use cases.
 
 As a result, while `form.Field` enables the most powerful and flexible usage of TanStack Form, we provide APIs that wrap it and make your application code less verbose.
 
@@ -18,7 +18,9 @@ At it's most basic, `createFormHook` is a function that takes a `fieldContext` a
 ```tsx
 import { createFormHookContexts, createFormHook } from '@tanstack/react-form'
 
-const { fieldContext, formContext } = createFormHookContexts()
+// export useFieldContext for use in your custom components
+export const { fieldContext, formContext, useFieldContext } =
+  createFormHookContexts()
 
 const { useAppForm } = createFormHook({
   fieldContext,
@@ -45,9 +47,12 @@ function App() {
 
 Once this scaffolding is in place, you can start adding custom field and form components to your form hook.
 
+> Note: the `useFieldContext` must be the same one exported from your custom form context
+
 ```tsx
-function TextField({ label }: { label: string }) {
-  // Use the context returned from `createFormHookContexts`
+import { useFieldContext } from './form-context.tsx'
+
+export function TextField({ label }: { label: string }) {
   // The `Field` infers that it should have a `value` type of `string`
   const field = useFieldContext<string>()
   return (
@@ -65,6 +70,8 @@ function TextField({ label }: { label: string }) {
 You're then able to register this component with your form hook.
 
 ```tsx
+import { TextField } from './text-field.tsx'
+
 const { useAppForm } = createFormHook({
   fieldContext,
   formContext,

docs/framework/react/guides/reactivity.md

@@ -31,12 +31,20 @@ While it IS possible to omit the selector, resist the urge as omitting it would
 The `form.Subscribe` component is best suited when you need to react to something within the UI of your component. For example, showing or hiding ui based on the value of a form field.
 
 ```tsx
-<form.Subscribe>
-  selector={(state) => state.firstName}
+<form.Subscribe
+  selector={(state) => state.values.firstName}
   children={(firstName) => (
-    <form.Field>{(field) => <input name="lastName" value={field.state.lastName} onChange={field.handleChange}/></form.Field>
+    <form.Field>
+      {(field) => (
+        <input
+          name="lastName"
+          value={field.state.lastName}
+          onChange={field.handleChange}
+        />
+      )}
+    </form.Field>
   )}
-</form.Subscribe>
+/>
 ```
 
 > The `form.Subscribe` component doesn't trigger component-level re-renders. Anytime the value subscribed to changes, only the `form.Subscribe` component re-renders.

docs/framework/react/reference/functions/createformhook.md

@@ -11,7 +11,7 @@ title: createFormHook
 function createFormHook<TComponents, TFormComponents>(__namedParameters): object
 ```
 
-Defined in: [packages/react-form/src/createFormHook.tsx:186](https://github.com/TanStack/form/blob/main/packages/react-form/src/createFormHook.tsx#L186)
+Defined in: [packages/react-form/src/createFormHook.tsx:223](https://github.com/TanStack/form/blob/main/packages/react-form/src/createFormHook.tsx#L223)
 
 ## Type Parameters
 
@@ -101,7 +101,7 @@ withForm: <TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync
 
 ##### \_\_namedParameters
 
-`WithFormProps`\<`TFormData`, `TOnMount`, `TOnChange`, `TOnChangeAsync`, `TOnBlur`, `TOnBlurAsync`, `TOnSubmit`, `TOnSubmitAsync`, `TOnServer`, `TSubmitMeta`, `TComponents`, `TFormComponents`, `TRenderProps`\>
+[`WithFormProps`](../interfaces/withformprops.md)\<`TFormData`, `TOnMount`, `TOnChange`, `TOnChangeAsync`, `TOnBlur`, `TOnBlurAsync`, `TOnSubmit`, `TOnSubmitAsync`, `TOnServer`, `TSubmitMeta`, `TComponents`, `TFormComponents`, `TRenderProps`\>
 
 #### Returns
 
@@ -111,7 +111,7 @@ withForm: <TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync
 
 ###### props
 
-`PropsWithChildren`\<`NoInfer`\<`TRenderProps`\> & `object`\>
+`PropsWithChildren`\<`NoInfer`\<`UnwrapOrAny`\<`TRenderProps`\>\> & `object`\>
 
 ##### Returns
 

docs/framework/react/reference/functions/createformhookcontexts.md

@@ -11,7 +11,7 @@ title: createFormHookContexts
 function createFormHookContexts(): object
 ```
 
-Defined in: [packages/react-form/src/createFormHook.tsx:16](https://github.com/TanStack/form/blob/main/packages/react-form/src/createFormHook.tsx#L16)
+Defined in: [packages/react-form/src/createFormHook.tsx:53](https://github.com/TanStack/form/blob/main/packages/react-form/src/createFormHook.tsx#L53)
 
 ## Returns
 

docs/framework/react/reference/functions/usetransform.md

@@ -8,43 +8,21 @@ title: useTransform
 # Function: useTransform()
 
 ```ts
-function useTransform<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnServer, TSubmitMeta>(fn, deps): FormTransform<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnServer, TSubmitMeta>
+function useTransform(fn, deps): FormTransform<any, any, any, any, any, any, any, any, any, any>
 ```
 
-Defined in: [packages/react-form/src/useTransform.ts:8](https://github.com/TanStack/form/blob/main/packages/react-form/src/useTransform.ts#L8)
-
-## Type Parameters
-
-• **TFormData**
-
-• **TOnMount** *extends* `undefined` \| `FormValidateOrFn`\<`TFormData`\>
-
-• **TOnChange** *extends* `undefined` \| `FormValidateOrFn`\<`TFormData`\>
-
-• **TOnChangeAsync** *extends* `undefined` \| `FormAsyncValidateOrFn`\<`TFormData`\>
-
-• **TOnBlur** *extends* `undefined` \| `FormValidateOrFn`\<`TFormData`\>
-
-• **TOnBlurAsync** *extends* `undefined` \| `FormAsyncValidateOrFn`\<`TFormData`\>
-
-• **TOnSubmit** *extends* `undefined` \| `FormValidateOrFn`\<`TFormData`\>
-
-• **TOnSubmitAsync** *extends* `undefined` \| `FormAsyncValidateOrFn`\<`TFormData`\>
-
-• **TOnServer** *extends* `undefined` \| `FormAsyncValidateOrFn`\<`TFormData`\>
-
-• **TSubmitMeta**
+Defined in: [packages/react-form/src/useTransform.ts:9](https://github.com/TanStack/form/blob/main/packages/react-form/src/useTransform.ts#L9)
 
 ## Parameters
 
 ### fn
 
-(`formBase`) => `FormApi`\<`TFormData`, `TOnMount`, `TOnChange`, `TOnChangeAsync`, `TOnBlur`, `TOnBlurAsync`, `TOnSubmit`, `TOnSubmitAsync`, `TOnServer`, `TSubmitMeta`\>
+(`formBase`) => `AnyFormApi`
 
 ### deps
 
 `unknown`[]
 
 ## Returns
 
-`FormTransform`\<`TFormData`, `TOnMount`, `TOnChange`, `TOnChangeAsync`, `TOnBlur`, `TOnBlurAsync`, `TOnSubmit`, `TOnSubmitAsync`, `TOnServer`, `TSubmitMeta`\>
+`FormTransform`\<`any`, `any`, `any`, `any`, `any`, `any`, `any`, `any`, `any`, `any`\>

docs/framework/react/reference/index.md

@@ -10,6 +10,7 @@ title: "@tanstack/react-form"
 ## Interfaces
 
 - [ReactFormApi](interfaces/reactformapi.md)
+- [WithFormProps](interfaces/withformprops.md)
 
 ## Type Aliases
 

docs/framework/react/reference/interfaces/withformprops.md

@@ -0,0 +1,72 @@
+---
+id: WithFormProps
+title: WithFormProps
+---
+
+<!-- DO NOT EDIT: this page is autogenerated from the type comments -->
+
+# Interface: WithFormProps\<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnServer, TSubmitMeta, TFieldComponents, TFormComponents, TRenderProps\>
+
+Defined in: [packages/react-form/src/createFormHook.tsx:173](https://github.com/TanStack/form/blob/main/packages/react-form/src/createFormHook.tsx#L173)
+
+## Extends
+
+- `FormOptions`\<`TFormData`, `TOnMount`, `TOnChange`, `TOnChangeAsync`, `TOnBlur`, `TOnBlurAsync`, `TOnSubmit`, `TOnSubmitAsync`, `TOnServer`, `TSubmitMeta`\>
+
+## Type Parameters
+
+• **TFormData**
+
+• **TOnMount** *extends* `undefined` \| `FormValidateOrFn`\<`TFormData`\>
+
+• **TOnChange** *extends* `undefined` \| `FormValidateOrFn`\<`TFormData`\>
+
+• **TOnChangeAsync** *extends* `undefined` \| `FormAsyncValidateOrFn`\<`TFormData`\>
+
+• **TOnBlur** *extends* `undefined` \| `FormValidateOrFn`\<`TFormData`\>
+
+• **TOnBlurAsync** *extends* `undefined` \| `FormAsyncValidateOrFn`\<`TFormData`\>
+
+• **TOnSubmit** *extends* `undefined` \| `FormValidateOrFn`\<`TFormData`\>
+
+• **TOnSubmitAsync** *extends* `undefined` \| `FormAsyncValidateOrFn`\<`TFormData`\>
+
+• **TOnServer** *extends* `undefined` \| `FormAsyncValidateOrFn`\<`TFormData`\>
+
+• **TSubmitMeta**
+
+• **TFieldComponents** *extends* `Record`\<`string`, `ComponentType`\<`any`\>\>
+
+• **TFormComponents** *extends* `Record`\<`string`, `ComponentType`\<`any`\>\>
+
+• **TRenderProps** *extends* `Record`\<`string`, `unknown`\> = `Record`\<`string`, `never`\>
+
+## Properties
+
+### props?
+
+```ts
+optional props: TRenderProps;
+```
+
+Defined in: [packages/react-form/src/createFormHook.tsx:200](https://github.com/TanStack/form/blob/main/packages/react-form/src/createFormHook.tsx#L200)
+
+***
+
+### render()
+
+```ts
+render: (props) => Element;
+```
+
+Defined in: [packages/react-form/src/createFormHook.tsx:201](https://github.com/TanStack/form/blob/main/packages/react-form/src/createFormHook.tsx#L201)
+
+#### Parameters
+
+##### props
+
+`PropsWithChildren`\<`NoInfer`\<`TRenderProps`\> & `object`\>
+
+#### Returns
+
+`Element`

docs/framework/solid/reference/functions/createfield.md

@@ -11,7 +11,7 @@ title: createField
 function createField<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnServer, TParentSubmitMeta>(opts): () => FieldApi<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnServer, TParentSubmitMeta> & SolidFieldApi<TParentData, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnServer, TParentSubmitMeta>
 ```
 
-Defined in: [packages/solid-form/src/createField.tsx:237](https://github.com/TanStack/form/blob/main/packages/solid-form/src/createField.tsx#L237)
+Defined in: [packages/solid-form/src/createField.tsx:236](https://github.com/TanStack/form/blob/main/packages/solid-form/src/createField.tsx#L236)
 
 ## Type Parameters