fix: restore useField meta object reactivity sync (#5021)

Since v4.12.0, calling useField with the same path in multiple components
(e.g. parent and child) within the same form would create separate PathState
objects instead of sharing one. This broke meta object synchronization —
touching a field in the child would not update the parent's meta.

The regression was introduced when createPathState was changed to only reuse
existing path states for checkbox/radio fields. This restores the v4.11.8
behavior where all field types sharing a path reuse the same PathState,
while also:

- Adding a path identity check to avoid reusing stale path states in field
  array scenarios where paths shift (e.g. after insert)
- Updating removePathState to properly decrement fieldsCount for all shared
  fields (not just checkbox/radio)
- Fixing the unmount logic to handle array IDs for non-multiple shared fields
- Only unsetting path values on unmount when it is the last field or a
  radio/checkbox group

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: logaretm

.changeset/fix-5021-usefield-meta-sync.md

@@ -0,0 +1,5 @@
+---
+"vee-validate": patch
+---
+
+Fix useField meta object syncing regression from v4.11.8 (#5021)

packages/vee-validate/src/useField.ts

@@ -386,10 +386,7 @@ function _useField<TValue = unknown>(
 
     flags.pendingUnmount[field.id] = true;
     const pathState = form.getPathState(path);
-    const matchesId =
-      Array.isArray(pathState?.id) && pathState?.multiple
-        ? pathState?.id.includes(field.id)
-        : pathState?.id === field.id;
+    const matchesId = Array.isArray(pathState?.id) ? pathState?.id.includes(field.id) : pathState?.id === field.id;
     if (!matchesId) {
       return;
     }
@@ -405,7 +402,7 @@ function _useField<TValue = unknown>(
       if (Array.isArray(pathState.id)) {
         pathState.id.splice(pathState.id.indexOf(field.id), 1);
       }
-    } else {
+    } else if (pathState?.multiple || pathState?.fieldsCount <= 1) {
       form.unsetPathValue(toValue(name));
     }
 

packages/vee-validate/src/useForm.ts

@@ -262,10 +262,14 @@ export function useForm<
     config?: Partial<PathStateConfig<TOutput[TPath]>>,
   ): PathState<TValues[TPath], TOutput[TPath]> {
     const initialValue = computed(() => getFromPath(initialValues.value, toValue(path)));
-    const pathStateExists = pathStateLookup.value[toValue(path)];
+    const pathValue = toValue(path);
+    const pathStateExists = pathStateLookup.value[pathValue];
     const isCheckboxOrRadio = config?.type === 'checkbox' || config?.type === 'radio';
-    if (pathStateExists && isCheckboxOrRadio) {
-      pathStateExists.multiple = true;
+    if (pathStateExists && normalizeFormPath(toValue(pathStateExists.path)) === normalizeFormPath(pathValue)) {
+      if (isCheckboxOrRadio) {
+        pathStateExists.multiple = true;
+      }
+
       const id = FIELD_ID_COUNTER++;
       if (Array.isArray(pathStateExists.id)) {
         pathStateExists.id.push(id);
@@ -280,7 +284,6 @@ export function useForm<
     }
 
     const currentValue = computed(() => getFromPath(formValues, toValue(path)));
-    const pathValue = toValue(path);
 
     const unsetBatchIndex = UNSET_BATCH.findIndex(_path => _path === pathValue);
     if (unsetBatchIndex !== -1) {
@@ -576,7 +579,7 @@ export function useForm<
       validateField(path, { mode: 'silent', warn: false });
     });
 
-    if (pathState.multiple && pathState.fieldsCount) {
+    if (pathState.fieldsCount) {
       pathState.fieldsCount--;
     }
 
@@ -589,7 +592,7 @@ export function useForm<
       delete pathState.__flags.pendingUnmount[id];
     }
 
-    if (!pathState.multiple || pathState.fieldsCount <= 0) {
+    if (pathState.fieldsCount <= 0) {
       pathStates.value.splice(idx, 1);
       unsetInitialValue(path);
       rebuildPathLookup();

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

@@ -3181,17 +3181,15 @@ test('removes proper pathState when field is unmounting', async () => {
   renderTemplateField.value = true;
   await flushPromises();
 
+  // Both useField calls share the same path state since they use the same path
   expect(form.meta.value.valid).toBe(false);
-  expect(form.getAllPathStates()).toMatchObject([
-    { id: 0, path: 'foo' },
-    { id: 1, path: 'foo' },
-  ]);
+  expect(form.getAllPathStates()).toMatchObject([{ id: [0, 1], path: 'foo' }]);
 
   renderTemplateField.value = false;
   await flushPromises();
 
   expect(form.meta.value.valid).toBe(true);
-  expect(form.getAllPathStates()).toMatchObject([{ id: 0, path: 'foo' }]);
+  expect(form.getAllPathStates()).toMatchObject([{ id: [0], path: 'foo' }]);
 });
 
 test('handles onSubmit with generic object from zod schema', async () => {

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

@@ -1009,6 +1009,60 @@ describe('useField()', () => {
     expect(field.errors.value).toHaveLength(0);
   });
 
+  // #5021
+  test('meta object syncs between multiple useField calls for the same path within a form', async () => {
+    let parentMeta!: FieldContext['meta'];
+    let childMeta!: FieldContext['meta'];
+    let childHandleBlur!: FieldContext['handleBlur'];
+
+    const ChildComponent = defineComponent({
+      setup() {
+        const { meta, handleBlur } = useField('field');
+        childMeta = meta;
+        childHandleBlur = handleBlur;
+
+        return { meta };
+      },
+      template: `<span id="child-touched">{{ meta.touched }}</span>`,
+    });
+
+    mountWithHoc({
+      components: { ChildComponent },
+      setup() {
+        useForm();
+        const { meta } = useField('field');
+        parentMeta = meta;
+
+        return { meta };
+      },
+      template: `
+        <span id="parent-touched">{{ meta.touched }}</span>
+        <ChildComponent />
+      `,
+    });
+
+    await flushPromises();
+
+    const parentTouched = document.querySelector('#parent-touched');
+    const childTouched = document.querySelector('#child-touched');
+
+    // Both should start as not touched
+    expect(parentTouched?.textContent).toBe('false');
+    expect(childTouched?.textContent).toBe('false');
+    expect(parentMeta.touched).toBe(false);
+    expect(childMeta.touched).toBe(false);
+
+    // Touch from child
+    childHandleBlur();
+    await flushPromises();
+
+    // Both should be touched now (meta is shared)
+    expect(parentMeta.touched).toBe(true);
+    expect(childMeta.touched).toBe(true);
+    expect(parentTouched?.textContent).toBe('true');
+    expect(childTouched?.textContent).toBe('true');
+  });
+
   // #4603
   test('should not remove field value if field with same path was created between scheduling and execution of previous field unset operation', async () => {
     vi.useFakeTimers();