chore: pnpmize docs folder

Author: logaretm

docs/src/pages/guide/composition-api/typed-schema.mdx

@@ -0,0 +1,271 @@
+---
+layout: ../../../layouts/PageLayout.astro
+title: Typed Schemas
+description: Type-safe input and output types
+order: 5
+next: guide/composition-api/api-review
+menuTitle: Caveats
+new: true
+---
+
+import DocTip from '@/components/DocTip.vue';
+import DocBadge from '@/components/DocBadge.vue';
+
+# Typed Schemas <DocBadge title="v4.8" />
+
+<DocTip type="warn">
+
+This guide is aimed towards TypeScript usage with vee-validate's composition API. If you are using the components API or JavaScript then there isn't much to learn here.
+
+</DocTip>
+
+## Input and Output types
+
+Consider the following form:
+
+```ts
+import { useForm } from 'vee-validate';
+import { object, string } from 'yup';
+
+const { values, handleSubmit } = useForm({
+  validationSchema: object({
+    email: string().required(),
+    password: string().required(),
+    name: string(),
+  }),
+});
+```
+
+When attempting to interact with the `values` you will notice that it is untyped. Meaning you don't get any type hints or checks which makes it less safe to use.
+
+```ts
+// 💥 Blows up because `email` is undefined
+values.email.endsWith('@gmail.com');
+```
+
+Providing an `initialValues` or an interface to `useForm` could help:
+
+```ts
+interface MyForm {
+  email?: string | null;
+  password?: string | null;
+}
+
+const { values, handleSubmit } = useForm<MyForm>({
+  validationSchema: object({
+    email: string().required(),
+    password: string().required(),
+    name: string(),
+  }),
+});
+
+// ❌ Type error, which means `values` is type-safe
+values.email.endsWith('@gmail.com');
+```
+
+But then you will find another problem when using `handleSubmit`:
+
+```ts
+handleSubmit(values => {
+  // Must be checked, this means submmited values are innacurate
+  if (values.email) {
+    values.email.endsWith('@gmail.com');
+  }
+});
+```
+
+Even though you marked your field as `required`, it still uses the same type you provider earlier which will keep the `email` field as nullable. This is what we mean by the "dual nature" of form values.
+
+Form values can exist in two types/versions:
+
+- The **"input"** type which is the one the user is filling/interacting with, it is the one that captures the user input.
+- The **"output"** type which is the one the user ends up submitting.
+
+You can tell vee-validate about this information by using the typed schema resolvers available in compainion packages.
+
+## Yup
+
+You can use yup as a typed schema with the `@vee-validate/yup` package:
+
+```sh
+# npm
+npm install @vee-validate/yup
+# yarn
+yarn add @vee-validate/yup
+# pnpm
+pnpm add @vee-validate/yup
+```
+
+The `@vee-valdiate/yup` package exposes a `toTypedSchema` function that accepts any yup schema. Which then you can pass along to `validationSchema` option on `useForm`.
+
+This makes the form values and submitted values typed automatically and caters for both input and output types of that schema.
+
+```ts
+import { useForm } from 'vee-validate';
+import { object, string } from 'yup';
+import { toTypedSchema } from '@vee-validate/yup';
+
+const { values, handleSubmit } = useForm({
+  validationSchema: toTypedSchema(
+    object({
+      email: string().required(),
+      password: string().required(),
+      name: string(),
+    })
+  ),
+});
+
+// ❌ Type error, which means `values` is type-safe
+values.email.endsWith('@gmail.com');
+
+handleSubmit(submitted => {
+  // No errors, because email is required!
+  submitted.email.endsWith('@gmail.com');
+
+  // ❌ Type error, because `name` is not required so it could be undefined
+  // Means that your fields are now type safe!
+  submitted.name.length;
+});
+```
+
+### Yup default values
+
+You can also define default values on your schema directly and it will be picked up by the form:
+
+```ts
+import { useForm } from 'vee-validate';
+import { object, string } from 'yup';
+import { toTypedSchema } from '@vee-validate/yup';
+
+const { values, handleSubmit } = useForm({
+  validationSchema: toTypedSchema(
+    object({
+      email: string().required().default('[email protected]'),
+      password: string().required().default(''),
+      name: string().default(''),
+    })
+  ),
+});
+```
+
+Your initial values will be using the schema defaults, and also the defaults will be used if the values submitted is missing these fields.
+
+### Yup transforms
+
+You can also define transforms to cast your fields before submission:
+
+```ts
+import { useForm } from 'vee-validate';
+import { object, number } from 'yup';
+import { toTypedSchema } from '@vee-validate/yup';
+
+const { values, handleSubmit } = useForm({
+  validationSchema: toTypedSchema(
+    object({
+      age: number()
+        .transform(val => Number(val))
+        .required(),
+    })
+  ),
+});
+```
+
+But note that this does not change the input or output types of the casted fields. The cast will only occur when setting the initial value and when the values are submitted.
+
+## Zod
+
+Zod is an excellent library for value validation which mirrors static typing APIs.
+
+In their own words it is a:
+
+> TypeScript-first schema validation with static type inference
+
+You can use zod as a typed schema with the `@vee-validate/zod` package:
+
+```sh
+# npm
+npm install @vee-validate/zod
+# yarn
+yarn add @vee-validate/zod
+# pnpm
+pnpm add @vee-validate/zod
+```
+
+The `@vee-valdiate/zod` package exposes a `toTypedSchema` function that accepts any zod schema. Which then you can pass along to `validationSchema` option on `useForm`.
+
+This makes the form values and submitted values typed automatically and caters for both input and output types of that schema.
+
+```ts
+import { useForm } from 'vee-validate';
+import { object, string } from 'yup';
+import { toTypedSchema } from '@vee-validate/yup';
+
+const { values, handleSubmit } = useForm({
+  validationSchema: toTypedSchema(
+    object({
+      email: string().min(1, 'required'),
+      password: string().min(1, 'required'),
+      name: string().optional(),
+    })
+  ),
+});
+
+// ❌ Type error, which means `values` is type-safe
+values.email.endsWith('@gmail.com');
+
+handleSubmit(submitted => {
+  // No errors, because email is required!
+  submitted.email.endsWith('@gmail.com');
+
+  // ❌ Type error, because `name` is not required so it could be undefined
+  // Means that your fields are now type safe!
+  submitted.name.length;
+});
+```
+
+### Zod default values
+
+You can also define default values on your zod schema directly and it will be picked up by the form:
+
+```ts
+import { useForm } from 'vee-validate';
+import { object, string } from 'yup';
+import { toTypedSchema } from '@vee-validate/yup';
+
+const { values, handleSubmit } = useForm({
+  validationSchema: toTypedSchema(
+    object({
+      email: string().default('[email protected]'),
+      password: string().default(''),
+    })
+  ),
+});
+```
+
+Your initial values will be using the schema defaults, and also the defaults will be used if the values submitted is missing these fields.
+
+### Zod preprocess
+
+You can also define preprocessors to cast your fields before submission:
+
+```ts
+import { useForm } from 'vee-validate';
+import { object, number, preprocess } from 'yup';
+import { toTypedSchema } from '@vee-validate/yup';
+
+const { values, handleSubmit } = useForm({
+  validationSchema: toTypedSchema(
+    object({
+      age: preprocess(val => Number(val), number()),
+    })
+  ),
+});
+
+// typed as `unknown` since the source value can be anything
+values.age;
+
+handleSubmit(submitted => {
+  // will be typed as number because zod made sure it is!
+  values.age;
+});
+```