feat: added useFieldModel to useForm API

Author: logaretm

packages/vee-validate/src/types.ts

@@ -15,6 +15,8 @@ export type Locator = { __locatorRef: string } & ((values: GenericFormValues) =>
 
 export type MaybeRef<T> = Ref<T> | T;
 
+export type MaybeArray<T> = T | T[];
+
 export interface FieldMeta<TValue> {
   touched: boolean;
   dirty: boolean;
@@ -159,6 +161,14 @@ export type FieldPathLookup<TValues extends Record<string, any> = Record<string,
   Record<keyof TValues, PrivateFieldContext | PrivateFieldContext[]>
 >;
 
+export type MapValues<T, TValues extends Record<string, any>> = {
+  [K in keyof T]: T[K] extends MaybeRef<infer TKey>
+    ? TKey extends keyof TValues
+      ? Ref<TValues[TKey]>
+      : Ref<unknown>
+    : Ref<unknown>;
+};
+
 export interface PrivateFormContext<TValues extends Record<string, any> = Record<string, any>>
   extends FormActions<TValues> {
   formId: number;
@@ -184,6 +194,8 @@ export interface PrivateFormContext<TValues extends Record<string, any> = Record
     onSubmitValidationErrorCb?: InvalidSubmissionHandler<TValues>
   ): (e?: Event) => Promise<TReturn | undefined>;
   setFieldInitialValue(path: string, value: unknown): void;
+  useFieldModel<TPath extends keyof TValues>(path: MaybeRef<TPath>): Ref<TValues[TPath]>;
+  useFieldModel<TPath extends keyof TValues>(paths: [...MaybeRef<TPath>[]]): MapValues<typeof paths, TValues>;
 }
 
 export interface FormContext<TValues extends Record<string, any> = Record<string, any>>

packages/vee-validate/src/useFieldState.ts

@@ -4,11 +4,11 @@ import { FormContextKey } from './symbols';
 import { FieldMeta, FieldState, MaybeRef } from './types';
 import { getFromPath, injectWithSelf } from './utils';
 
-interface StateSetterInit<TValue = unknown> extends FieldState<TValue> {
+export interface StateSetterInit<TValue = unknown> extends FieldState<TValue> {
   initialValue: TValue;
 }
 
-interface FieldStateComposable<TValue = unknown> {
+export interface FieldStateComposable<TValue = unknown> {
   id: number;
   path: MaybeRef<string>;
   meta: FieldMeta<TValue>;
@@ -19,7 +19,7 @@ interface FieldStateComposable<TValue = unknown> {
   setState(state: Partial<StateSetterInit<TValue>>): void;
 }
 
-interface StateInit<TValue = unknown> {
+export interface StateInit<TValue = unknown> {
   modelValue: MaybeRef<TValue>;
   standalone: boolean;
 }
@@ -74,12 +74,12 @@ interface FieldValueComposable<TValue = unknown> {
 /**
  * Creates the field value and resolves the initial value
  */
-function _useFieldValue<TValue = unknown>(
+export function _useFieldValue<TValue = unknown>(
   path: MaybeRef<string>,
-  modelValue: MaybeRef<TValue> | undefined,
-  shouldInjectForm: boolean
+  modelValue?: MaybeRef<TValue>,
+  shouldInjectForm = true
 ): FieldValueComposable<TValue> {
-  const form = shouldInjectForm ? injectWithSelf(FormContextKey, undefined) : undefined;
+  const form = shouldInjectForm === true ? injectWithSelf(FormContextKey, undefined) : undefined;
   const modelRef = ref(unref(modelValue)) as Ref<TValue>;
 
   function resolveInitialValue() {

packages/vee-validate/src/useForm.ts

@@ -35,6 +35,8 @@ import {
   FieldPathLookup,
   PrivateFieldArrayContext,
   InvalidSubmissionHandler,
+  MaybeArray,
+  MapValues,
 } from './types';
 import {
   getFromPath,
@@ -49,6 +51,7 @@ import {
 import { FormContextKey } from './symbols';
 import { validateYupSchema, validateObjectSchema } from './validate';
 import { refreshInspector, registerFormWithDevTools } from './devtools';
+import { _useFieldValue } from './useFieldState';
 
 interface FormOptions<TValues extends Record<string, any>> {
   validationSchema?: MaybeRef<
@@ -179,6 +182,7 @@ export function useForm<TValues extends Record<string, any> = Record<string, any
     stageInitialValue,
     unsetInitialValue,
     setFieldInitialValue,
+    useFieldModel,
   };
 
   function isFieldGroup(
@@ -282,6 +286,23 @@ export function useForm<TValues extends Record<string, any> = Record<string, any
     Object.values(fieldArraysLookup).forEach(f => f && f.reset());
   }
 
+  function createModel<TPath extends keyof TValues>(path: MaybeRef<TPath>) {
+    const { value } = _useFieldValue<TValues[TPath]>(path as string);
+    watch(value, () => validate({ mode: 'validated-only' }));
+
+    return value;
+  }
+
+  function useFieldModel<TPath extends keyof TValues>(path: MaybeRef<TPath>): Ref<TValues[TPath]>;
+  function useFieldModel<TPath extends keyof TValues>(paths: [...TPath[]]): MapValues<typeof paths, TValues>;
+  function useFieldModel<TPath extends keyof TValues>(path: MaybeRef<TPath> | [...MaybeRef<TPath>[]]) {
+    if (!Array.isArray(path)) {
+      return createModel<TPath>(path);
+    }
+
+    return path.map(createModel) as MapValues<typeof path, TValues>;
+  }
+
   /**
    * Sets the touched meta state on a field
    */
@@ -722,6 +743,7 @@ export function useForm<TValues extends Record<string, any> = Record<string, any
     setValues,
     setFieldTouched,
     setTouched,
+    useFieldModel,
   };
 }
 

packages/vee-validate/tests/helpers/index.ts

@@ -97,3 +97,14 @@ export async function dispatchFileEvent(input: HTMLInputElement, name: string |
   input.dispatchEvent(event);
   await flushPromises();
 }
+
+export async function runInSetup(cb: () => any) {
+  mountWithHoc({
+    setup() {
+      cb();
+    },
+    template: `
+        <div></div>
+    `,
+  });
+}

packages/vee-validate/tests/useForm.spec.ts

@@ -1,5 +1,5 @@
 import { FormContext, useField, useForm } from '@/vee-validate';
-import { mountWithHoc, setValue, flushPromises } from './helpers';
+import { mountWithHoc, setValue, flushPromises, runInSetup } from './helpers';
 import * as yup from 'yup';
 import { Ref } from 'vue';
 
@@ -411,4 +411,62 @@ describe('useForm()', () => {
     expect(meta[1]?.textContent).toBe('false');
     expect(meta[2]?.textContent).toBe('false');
   });
+
+  test('Creates a writeable model for a field path', async () => {
+    await runInSetup(() => {
+      const { values, useFieldModel } = useForm({
+        initialValues: {
+          greet: 'hey',
+          age: 1,
+        },
+      });
+      const greet = useFieldModel('greet');
+      const age = useFieldModel('age');
+
+      expect(values.greet).toBe('hey');
+      expect(values.age).toBe(1);
+      greet.value = 'hello';
+      age.value = 2;
+      expect(values.greet).toBe('hello');
+      expect(values.age).toBe(2);
+    });
+  });
+
+  test('Creates multiple writeable models for given field paths', async () => {
+    await runInSetup(() => {
+      const { values, useFieldModel } = useForm({
+        initialValues: {
+          greet: 'hey',
+          age: 1,
+        },
+      });
+
+      const [age, greet] = useFieldModel(['age', 'greet']);
+
+      expect(values.greet).toBe('hey');
+      expect(values.age).toBe(1);
+      greet.value = 'hello';
+      age.value = 2;
+      expect(values.greet).toBe('hello');
+      expect(values.age).toBe(2);
+    });
+  });
+
+  test('Validates the field model immediately and when it changes', async () => {
+    await runInSetup(async () => {
+      const { errors, useFieldModel } = useForm();
+      const model = useFieldModel('test');
+
+      await flushPromises();
+      expect(errors.value.test).toBe(REQUIRED_MESSAGE);
+
+      model.value = 'hello';
+      await flushPromises();
+      expect(errors.value.test).toBe('');
+
+      model.value = '';
+      await flushPromises();
+      expect(errors.value.test).toBe(REQUIRED_MESSAGE);
+    });
+  });
 });