feat(form-core): add parseValueWithSchema() stateless method (#1421)

* feat(FormApi): add standard schema validator wrapper

* feat(form-core): add parseValueWithSchema methods

* docs: add parseValueWithSchema documentation

* refactor(form-core): rename FormApi#parseValuesWithSchema

This is to be consistent with other methods
that include the word Values.

* refactor(form-core): adjust unit tests for parseValuesWithSchema

* refactor(FormApi): rename parseFieldValuesWithSchema

Since we don't pass a field to the method, the term
shouldn't be included in the method name.

* docs: generate

Author: LeCarbonator

docs/framework/angular/guides/validation.md

@@ -499,6 +499,41 @@ export class AppComponent {
 }
 ```
 
+If you need even more control over your Standard Schema validation, you can combine a Standard Schema with a callback function like so:
+
+```angular-ts
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [TanStackField],
+  template: `
+    <ng-container
+      [tanstackField]="form"
+      name="age"
+      [validators]="{ onChangeAsync: ageValidator }"
+      #age="field"
+    >
+      <!-- ... -->
+    </ng-container>
+  `,
+})
+export class AppComponent {
+  ageValidator: FieldValidateAsyncFn<any, string, number> = async ({
+    value,
+    fieldApi,
+  }) => {
+    const errors = fieldApi.parseValueWithSchema(
+      z.number().gte(13, 'You must be 13 to make an account'),
+    )
+    if (errors) return errors
+
+    // continue with your validation
+  }
+
+  // ...
+}
+```
+
 ## Preventing invalid forms from being submitted
 
 The `onChange`, `onBlur` etc... callbacks are also run when the form is submitted and the submission is blocked if the form is invalid.

docs/framework/react/guides/validation.md

@@ -503,6 +503,27 @@ Async validations on form and field level are supported as well:
 />
 ```
 
+If you need even more control over your Standard Schema validation, you can combine a Standard Schema with a callback function like so:
+
+```tsx
+<form.Field
+  name="age"
+  asyncDebounceMs={500}
+  validators={{
+    onChangeAsync: async ({ value, fieldApi }) => {
+      const errors = fieldApi.parseValueWithSchema(
+        z.number().gte(13, 'You must be 13 to make an account'),
+      )
+      if (errors) return errors
+      // continue with your validation
+    },
+  }}
+  children={(field) => {
+    return <>{/* ... */}</>
+  }}
+/>
+```
+
 ## Preventing invalid forms from being submitted
 
 The `onChange`, `onBlur` etc... callbacks are also run when the form is submitted and the submission is blocked if the form is invalid.

docs/framework/solid/guides/validation.md

@@ -390,6 +390,28 @@ Async validations on form and field level are supported as well:
 />
 ```
 
+If you need even more control over your Standard Schema validation, you can combine a Standard Schema with a callback function like so:
+
+```tsx
+<form.Field
+  name="age"
+  validators={{
+    onChange: ({ value, fieldApi }) => {
+      const errors = fieldApi.parseValueWithSchema(
+        z.number().gte(13, 'You must be 13 to make an account'),
+      )
+
+      if (errors) return errors
+
+      // continue with your validation
+    },
+  }}
+  children={(field) => {
+    return <>{/* ... */}</>
+  }}
+/>
+```
+
 ## Preventing invalid forms from being submitted
 
 The `onChange`, `onBlur` etc... callbacks are also run when the form is submitted and the submission is blocked if the form is invalid.

docs/framework/vue/guides/validation.md

@@ -442,6 +442,33 @@ Async validations on form and field level are supported as well:
 </template>
 ```
 
+If you need even more control over your Standard Schema validation, you can combine a Standard Schema with a callback function like so:
+
+```vue
+<template>
+  <!-- ... -->
+  <form.Field
+    name="age"
+    :validators="{
+      onChange: ({ value, fieldApi }) => {
+        const errors = fieldApi.parseValueWithSchema(
+          z.number().gte(13, 'You must be 13 to make an account'),
+        )
+
+        if (errors) return errors
+
+        // continue with your validation
+      },
+    }"
+  >
+    <template v-slot="{ field }">
+      <!-- ... -->
+    </template>
+  </form.Field>
+  <!-- ... -->
+</template>
+```
+
 ## Preventing invalid forms from being submitted
 
 The `onChange`, `onBlur` etc... callbacks are also run when the form is submitted and the submission is blocked if the form is invalid.

docs/reference/classes/fieldapi.md

@@ -343,6 +343,63 @@ Moves the value at the first specified index to the second specified index.
 
 ***
 
+### parseValueWithSchema()
+
+```ts
+parseValueWithSchema(schema): 
+  | undefined
+  | StandardSchemaV1Issue[]
+```
+
+Defined in: [packages/form-core/src/FieldApi.ts:1651](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1651)
+
+Parses the field's value with the given schema and returns
+issues (if any). This method does NOT set any internal errors.
+
+#### Parameters
+
+##### schema
+
+[`StandardSchemaV1`](../type-aliases/standardschemav1.md)\<`TData`, `unknown`\>
+
+The standard schema to parse this field's value with.
+
+#### Returns
+
+  \| `undefined`
+  \| [`StandardSchemaV1Issue`](../interfaces/standardschemav1issue.md)[]
+
+***
+
+### parseValueWithSchemaAsync()
+
+```ts
+parseValueWithSchemaAsync(schema): Promise<
+  | undefined
+| StandardSchemaV1Issue[]>
+```
+
+Defined in: [packages/form-core/src/FieldApi.ts:1663](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1663)
+
+Parses the field's value with the given schema and returns
+issues (if any). This method does NOT set any internal errors.
+
+#### Parameters
+
+##### schema
+
+[`StandardSchemaV1`](../type-aliases/standardschemav1.md)\<`TData`, `unknown`\>
+
+The standard schema to parse this field's value with.
+
+#### Returns
+
+`Promise`\<
+  \| `undefined`
+  \| [`StandardSchemaV1Issue`](../interfaces/standardschemav1issue.md)[]\>
+
+***
+
 ### pushValue()
 
 ```ts

docs/reference/classes/formapi.md

@@ -422,6 +422,75 @@ Moves the value at the first specified index to the second specified index withi
 
 ***
 
+### parseValuesWithSchema()
+
+```ts
+parseValuesWithSchema(schema): 
+  | undefined
+  | {
+  fields: Record<string, StandardSchemaV1Issue[]>;
+  form: Record<string, StandardSchemaV1Issue[]>;
+}
+```
+
+Defined in: [packages/form-core/src/FormApi.ts:2075](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L2075)
+
+Parses the form's values with a given standard schema and returns
+issues (if any). This method does NOT set any internal errors.
+
+#### Parameters
+
+##### schema
+
+[`StandardSchemaV1`](../type-aliases/standardschemav1.md)\<`TFormData`, `unknown`\>
+
+The standard schema to parse the form values with.
+
+#### Returns
+
+  \| `undefined`
+  \| \{
+  `fields`: `Record`\<`string`, [`StandardSchemaV1Issue`](../interfaces/standardschemav1issue.md)[]\>;
+  `form`: `Record`\<`string`, [`StandardSchemaV1Issue`](../interfaces/standardschemav1issue.md)[]\>;
+ \}
+
+***
+
+### parseValuesWithSchemaAsync()
+
+```ts
+parseValuesWithSchemaAsync(schema): Promise<
+  | undefined
+  | {
+  fields: Record<string, StandardSchemaV1Issue[]>;
+  form: Record<string, StandardSchemaV1Issue[]>;
+}>
+```
+
+Defined in: [packages/form-core/src/FormApi.ts:2087](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L2087)
+
+Parses the form's values with a given standard schema and returns
+issues (if any). This method does NOT set any internal errors.
+
+#### Parameters
+
+##### schema
+
+[`StandardSchemaV1`](../type-aliases/standardschemav1.md)\<`TFormData`, `unknown`\>
+
+The standard schema to parse the form values with.
+
+#### Returns
+
+`Promise`\<
+  \| `undefined`
+  \| \{
+  `fields`: `Record`\<`string`, [`StandardSchemaV1Issue`](../interfaces/standardschemav1issue.md)[]\>;
+  `form`: `Record`\<`string`, [`StandardSchemaV1Issue`](../interfaces/standardschemav1issue.md)[]\>;
+ \}\>
+
+***
+
 ### pushFieldValue()
 
 ```ts

docs/reference/functions/isstandardschemavalidator.md

@@ -11,7 +11,7 @@ title: isStandardSchemaValidator
 function isStandardSchemaValidator(validator): validator is StandardSchemaV1<unknown, unknown>
 ```
 
-Defined in: [packages/form-core/src/standardSchemaValidator.ts:75](https://github.com/TanStack/form/blob/main/packages/form-core/src/standardSchemaValidator.ts#L75)
+Defined in: [packages/form-core/src/standardSchemaValidator.ts:90](https://github.com/TanStack/form/blob/main/packages/form-core/src/standardSchemaValidator.ts#L90)
 
 ## Parameters
 

docs/reference/index.md

@@ -59,6 +59,7 @@ title: "@tanstack/form-core"
 - [Nullable](type-aliases/nullable.md)
 - [ObjectAccessor](type-aliases/objectaccessor.md)
 - [StandardSchemaV1](type-aliases/standardschemav1.md)
+- [TStandardSchemaValidatorIssue](type-aliases/tstandardschemavalidatorissue.md)
 - [TStandardSchemaValidatorValue](type-aliases/tstandardschemavalidatorvalue.md)
 - [TupleAccessor](type-aliases/tupleaccessor.md)
 - [UnknownAccessor](type-aliases/unknownaccessor.md)

docs/reference/interfaces/standardschemav1issue.md

@@ -7,7 +7,7 @@ title: StandardSchemaV1Issue
 
 # Interface: StandardSchemaV1Issue
 
-Defined in: [packages/form-core/src/standardSchemaValidator.ts:144](https://github.com/TanStack/form/blob/main/packages/form-core/src/standardSchemaValidator.ts#L144)
+Defined in: [packages/form-core/src/standardSchemaValidator.ts:159](https://github.com/TanStack/form/blob/main/packages/form-core/src/standardSchemaValidator.ts#L159)
 
 The issue interface of the failure output.
 
@@ -19,7 +19,7 @@ The issue interface of the failure output.
 readonly message: string;
 ```
 
-Defined in: [packages/form-core/src/standardSchemaValidator.ts:148](https://github.com/TanStack/form/blob/main/packages/form-core/src/standardSchemaValidator.ts#L148)
+Defined in: [packages/form-core/src/standardSchemaValidator.ts:163](https://github.com/TanStack/form/blob/main/packages/form-core/src/standardSchemaValidator.ts#L163)
 
 The error message of the issue.
 
@@ -31,6 +31,6 @@ The error message of the issue.
 readonly optional path: readonly (PropertyKey | StandardSchemaV1PathSegment)[];
 ```
 
-Defined in: [packages/form-core/src/standardSchemaValidator.ts:152](https://github.com/TanStack/form/blob/main/packages/form-core/src/standardSchemaValidator.ts#L152)
+Defined in: [packages/form-core/src/standardSchemaValidator.ts:167](https://github.com/TanStack/form/blob/main/packages/form-core/src/standardSchemaValidator.ts#L167)
 
 The path of the issue, if any.

docs/reference/type-aliases/standardschemav1.md

@@ -11,7 +11,7 @@ title: StandardSchemaV1
 type StandardSchemaV1<Input, Output> = object;
 ```
 
-Defined in: [packages/form-core/src/standardSchemaValidator.ts:83](https://github.com/TanStack/form/blob/main/packages/form-core/src/standardSchemaValidator.ts#L83)
+Defined in: [packages/form-core/src/standardSchemaValidator.ts:98](https://github.com/TanStack/form/blob/main/packages/form-core/src/standardSchemaValidator.ts#L98)
 
 The Standard Schema interface.