feat: introduce defineField and deprecate bind API (#4497)

.changeset/eight-adults-kiss.md

@@ -0,0 +1,5 @@
+---
+'vee-validate': patch
+---
+
+feat: add label support to defineField closes #4530

docs/src/components/examples/CompositionBasic.vue

@@ -7,12 +7,12 @@ const schema = yup.object({
   password: yup.string().min(6).required(),
 });
 
-const { defineInputBinds, errors, handleSubmit } = useForm({
+const { defineField, errors, handleSubmit } = useForm({
   validationSchema: schema,
 });
 
-const email = defineInputBinds('email');
-const password = defineInputBinds('password');
+const [email, emailAttrs] = defineField('email');
+const [password, passwordAttrs] = defineField('password');
 
 const onSubmit = handleSubmit(values => {
   alert(JSON.stringify(values, null, 2));
@@ -21,10 +21,10 @@ const onSubmit = handleSubmit(values => {
 
 <template>
   <form @submit="onSubmit">
-    <input v-bind="email" name="email" type="email" />
+    <input v-model="email" v-bind="emailAttrs" name="email" type="email" />
     <span>{{ errors.email }}</span>
 
-    <input v-bind="password" name="password" type="password" />
+    <input v-model="password" v-bind="passwordAttrs" name="password" type="password" />
     <span>{{ errors.password }}</span>
 
     <button>Submit</button>

docs/src/components/examples/CompositionComponentBindsBasic01.vue

@@ -2,13 +2,13 @@
 import { useForm } from 'vee-validate';
 import CustomInput from './CustomInput.vue';
 
-const { values, defineComponentBinds } = useForm();
+const { values, defineField } = useForm();
 
-const email = defineComponentBinds('email');
+const [email, emailProps] = defineField('email');
 </script>
 
 <template>
-  <CustomInput v-bind="email" />
+  <CustomInput v-model="email" v-bind="emailProps" />
 
   <pre>values: {{ values }}</pre>
 </template>

docs/src/components/examples/CompositionComponentBindsBasic02.vue

@@ -3,17 +3,17 @@ import { useForm } from 'vee-validate';
 import * as yup from 'yup';
 import CustomInput from './CustomInput.vue';
 
-const { values, errors, defineComponentBinds } = useForm({
+const { values, errors, defineField } = useForm({
   validationSchema: yup.object({
     email: yup.string().email().required(),
   }),
 });
 
-const email = defineComponentBinds('email');
+const [email, emailProps] = defineField('email');
 </script>
 
 <template>
-  <CustomInput v-bind="email" />
+  <CustomInput v-model="email" v-bind="emailProps" />
 
   <pre>errors: {{ errors }}</pre>
   <pre>values: {{ values }}</pre>

docs/src/components/examples/CompositionComponentBindsBasic03.vue

@@ -3,19 +3,19 @@ import { useForm } from 'vee-validate';
 import * as yup from 'yup';
 import CustomInput from './CustomInput.vue';
 
-const { values, errors, defineComponentBinds } = useForm({
+const { values, errors, defineField } = useForm({
   validationSchema: yup.object({
     email: yup.string().email().required(),
   }),
 });
 
-const email = defineComponentBinds('email', {
+const [email, emailProps] = defineField('email', {
   validateOnValueUpdate: false,
 });
 </script>
 
 <template>
-  <CustomInput v-bind="email" />
+  <CustomInput v-model="email" v-bind="emailProps" />
   <div>{{ errors.email }}</div>
 
   <pre>values: {{ values }}</pre>

docs/src/components/examples/CompositionComponentBindsBasic04.vue

@@ -3,21 +3,21 @@ import { useForm } from 'vee-validate';
 import * as yup from 'yup';
 import CustomInput from './CustomInput.vue';
 
-const { values, errors, defineComponentBinds } = useForm({
+const { values, errors, defineField } = useForm({
   validationSchema: yup.object({
     email: yup.string().email().required(),
   }),
 });
 
-const email = defineComponentBinds('email', {
-  mapProps: state => ({
+const [email, emailProps] = defineField('email', {
+  props: state => ({
     error: state.errors[0],
   }),
 });
 </script>
 
 <template>
-  <CustomInput v-bind="email" />
+  <CustomInput v-model="email" v-bind="emailProps" />
 
   <pre>values: {{ values }}</pre>
   <pre>errors: {{ errors }}</pre>

docs/src/components/examples/CompositionComponentBindsBasic05.vue

@@ -1,39 +1,24 @@
 <script setup>
 import { useForm } from 'vee-validate';
 import * as yup from 'yup';
-import CustomInput from './CustomInput.vue';
 
-const { values, errors, defineInputBinds, defineComponentBinds } = useForm({
+const { values, errors, defineField } = useForm({
   validationSchema: yup.object({
     email: yup.string().email().required(),
-    emailComponent: yup.string().email().required(),
   }),
 });
 
-const email = defineInputBinds('email', state => {
-  return {
-    // validate aggressively as long as there are errors on the input
-    validateOnInput: state.errors.length > 0,
-  };
-});
-
-const emailComponent = defineComponentBinds('emailComponent', state => {
+const [email, emailAttrs] = defineField('email', state => {
   return {
     // validate aggressively as long as there are errors on the input
     validateOnModelUpdate: state.errors.length > 0,
-    validateOnBlur: true,
-    props: {
-      error: state.errors[0],
-    },
   };
 });
 </script>
 
 <template>
-  <input v-bind="email" />
+  <input v-model="email" v-bind="emailAttrs" />
   <div>{{ errors.email }}</div>
 
-  <CustomInput v-bind="emailComponent" />
-
   <pre>values: {{ values }}</pre>
 </template>

docs/src/components/examples/CompositionDynamicSchemaComputed.vue

@@ -6,22 +6,22 @@ import * as yup from 'yup';
 
 const limit = ref(5);
 
-const { errors, defineInputBinds } = useForm({
+const { errors, defineField } = useForm({
   validationSchema: computed(() =>
     toTypedSchema(
       yup.object({
         content: yup.string().max(limit.value),
-      })
-    )
+      }),
+    ),
   ),
 });
 
-const content = defineInputBinds('content');
+const [content, contentAttrs] = defineField('content');
 </script>
 
 <template>
   <input v-model.number="limit" />
 
-  <input v-bind="content" />
+  <input v-model="content" v-bind="contentAttrs" />
   <div>{{ errors.content }}</div>
 </template>

docs/src/components/examples/CompositionDynamicSchemaYupLazy.vue

@@ -6,22 +6,22 @@ import * as yup from 'yup';
 
 const limit = ref(5);
 
-const { errors, defineInputBinds } = useForm({
+const { errors, defineField } = useForm({
   validationSchema: toTypedSchema(
     yup.lazy(() =>
       yup.object({
         content: yup.string().max(limit.value),
-      })
-    )
+      }),
+    ),
   ),
 });
 
-const content = defineInputBinds('content');
+const [content, contentAttrs] = defineField('content');
 </script>
 
 <template>
   <input v-model.number="limit" />
 
-  <input v-bind="content" />
+  <input v-model="content" v-bind="contentAttrs" />
   <div>{{ errors.content }}</div>
 </template>

docs/src/components/examples/CompositionHandlingForms01.vue

@@ -1,13 +1,13 @@
-<template>
-  <input v-bind="name" />
-
-  <button :disabled="!meta.touched">Submit</button>
-</template>
-
 <script setup>
 import { useForm } from 'vee-validate';
 
-const { meta, defineInputBinds } = useForm();
+const { meta, defineField } = useForm();
 
-const name = defineInputBinds('name');
+const [name, nameAttrs] = defineField('name');
 </script>
+
+<template>
+  <input v-model="name" v-bind="nameAttrs" />
+
+  <button :disabled="!meta.touched">Submit</button>
+</template>

docs/src/components/examples/CompositionHandlingForms02.vue

@@ -1,20 +1,8 @@
-<template>
-  <form @submit="onSubmit">
-    <input type="email" v-bind="email" />
-    <div>{{ errors.email }}</div>
-
-    <input type="password" v-bind="password" />
-    <div>{{ errors.password }}</div>
-
-    <button>Submit</button>
-  </form>
-</template>
-
 <script setup>
 import { useForm } from 'vee-validate';
 import * as yup from 'yup';
 
-const { errors, handleSubmit, defineInputBinds } = useForm({
+const { errors, handleSubmit, defineField } = useForm({
   validationSchema: yup.object({
     email: yup.string().email().required(),
     password: yup.string().min(6).required(),
@@ -27,6 +15,18 @@ const onSubmit = handleSubmit(values => {
   alert(JSON.stringify(values, null, 2));
 });
 
-const email = defineInputBinds('email');
-const password = defineInputBinds('password');
+const [email, emailAttrs] = defineField('email');
+const [password, passwordAttrs] = defineField('password');
 </script>
+
+<template>
+  <form @submit="onSubmit">
+    <input type="email" v-model="email" v-bind="emailAttrs" />
+    <div>{{ errors.email }}</div>
+
+    <input type="password" v-model="password" v-bind="passwordAttrs" />
+    <div>{{ errors.password }}</div>
+
+    <button>Submit</button>
+  </form>
+</template>

docs/src/components/examples/CompositionHandlingForms03.vue

@@ -1,20 +1,8 @@
-<template>
-  <form @submit="onSubmit">
-    <input v-bind="email" name="email" type="email" />
-    <span>{{ errors.email }}</span>
-
-    <input v-bind="password" name="password" type="password" />
-    <span>{{ errors.password }}</span>
-
-    <button>Submit</button>
-  </form>
-</template>
-
 <script setup>
 import { useForm } from 'vee-validate';
 import * as yup from 'yup';
 
-const { errors, handleSubmit, defineInputBinds } = useForm({
+const { errors, handleSubmit, defineField } = useForm({
   validationSchema: yup.object({
     email: yup.string().email().required(),
     password: yup.string().min(6).required(),
@@ -32,13 +20,25 @@ const onSubmit = handleSubmit(
       behavior: 'smooth',
     });
     el.focus();
-  }
+  },
 );
 
-const email = defineInputBinds('email');
-const password = defineInputBinds('password');
+const [email, emailAttrs] = defineField('email');
+const [password, passwordAttrs] = defineField('password');
 </script>
 
+<template>
+  <form @submit="onSubmit">
+    <input v-model="email" v-bind="emailAttrs" name="email" type="email" />
+    <span>{{ errors.email }}</span>
+
+    <input v-model="password" v-bind="passwordAttrs" name="password" type="password" />
+    <span>{{ errors.password }}</span>
+
+    <button>Submit</button>
+  </form>
+</template>
+
 <style>
 input,
 button {