feat: enhance getFieldError to support group paths and descendant touches

Author: sakobu

docs/API.md

@@ -528,7 +528,15 @@ resetForm(): void
 
 ### getFieldError
 
-Returns the error message for a field only if it has been touched, otherwise `undefined`.
+Returns the error message for a field path, gated on user interaction.
+
+- **Leaf paths**: returns the error iff the field itself has been touched.
+- **Group / parent paths**: returns the error iff *any* descendant field has been
+  touched. Cross-field validation errors that schemas attach to a non-leaf path
+  (e.g. `S.refineAt("confirm", v => v.password === v.confirm, …)` or
+  `S.refineAt("r2", …)` over a tuple) surface naturally on the group container,
+  without callers having to read `form.errors` and `form.touched` directly.
+
 Eliminates the common `touched[field] ? errors[field] : undefined` boilerplate.
 
 ```typescript
@@ -539,11 +547,11 @@ getFieldError<TField extends ExtractFieldPaths<TValues>>(
 
 **Parameters:**
 
-- `field` - Field path with autocomplete
+- `field` - Field path with autocomplete (leaf or parent)
 
-**Returns:** The error message string if the field is touched and has an error, otherwise `undefined`.
+**Returns:** The error message string if visible per the rules above, otherwise `undefined`.
 
-**Example:**
+**Example — leaf:**
 
 ```typescript
 // Instead of:
@@ -553,6 +561,27 @@ getFieldError<TField extends ExtractFieldPaths<TValues>>(
 {form.getFieldError("email") && <span>{form.getFieldError("email")}</span>}
 ```
 
+**Example — group / parent path:**
+
+```typescript
+const schema = S.chain(
+  S.object({
+    password: S.required(S.string()),
+    confirm: S.required(S.string()),
+  }),
+  S.refineAt('confirm', (v) => v.password === v.confirm, 'Passwords must match'),
+);
+
+// In a fieldset that owns both inputs — error becomes visible once any
+// descendant of `confirm` is touched (or `confirm` itself, for a leaf).
+{form.getFieldError('confirm') && <p className="err">{form.getFieldError('confirm')}</p>}
+```
+
+The descendant scan uses a path-prefix check that guards against sibling
+collisions — `r2` does not match a touch on `r20`. `getFieldError` never
+aggregates *across* paths: it only returns an error attached at the queried
+path, gated on touch of the path or any of its descendants.
+
 ### getFieldId
 
 Returns a stable HTML element ID for a field without creating onChange/onBlur handlers.

src/useForm.ts

@@ -874,24 +874,45 @@ export const useForm = <TValues extends Record<string, unknown>>(
   // ===========================================================================
 
   /**
-   * Returns the error message for a field only if it has been touched, otherwise `undefined`.
-   * Eliminates the common `touched[field] ? errors[field] : undefined` boilerplate.
+   * Returns the error message for a field path, gated on user interaction.
+   *
+   * - Leaf paths: returns the error iff the field itself has been touched.
+   * - Group / parent paths: returns the error iff *any* descendant field has
+   *   been touched. This makes cross-field validation errors that schemas
+   *   attach to a non-leaf path (e.g. `S.refineAt("confirm", v => v.password
+   *   === v.confirm, …)` or `S.refineAt("r2", …)` over a tuple) surface
+   *   naturally on the group container, without callers having to read
+   *   `form.errors` and `form.touched` directly.
+   *
+   * Eliminates the common `touched[field] ? errors[field] : undefined`
+   * boilerplate and removes the leaf-only constraint that previously hid
+   * group-level errors.
    *
    * @template TField - The field path type (auto-inferred with autocomplete)
    * @param field - The field path (with type-safe autocomplete)
-   * @returns The error message string if the field is touched and has an error, otherwise `undefined`
+   * @returns The error message string if visible per the rules above, otherwise `undefined`
    *
    * @example
-   * // Instead of:
-   * {form.touched.email && form.errors.email && <span>{form.errors.email}</span>}
-   *
-   * // Use:
+   * // Leaf:
    * {form.getFieldError("email") && <span>{form.getFieldError("email")}</span>}
+   *
+   * @example
+   * // Group — schema has `refineAt("r2", v => !equal(v.r1, v.r2), "must differ")`:
+   * {form.getFieldError("r2") && <Banner msg={form.getFieldError("r2")} />}
    */
   const getFieldError = useCallback(
     <TField extends ExtractFieldPaths<TValues>>(field: TField): string | undefined => {
       const key = normalizePath(field);
-      return formState.touched[key] ? errors[key] : undefined;
+      const err = errors[key];
+      if (!err) return undefined;
+      // Visible iff the queried path itself or any descendant has been touched.
+      // `isPathAffected(touchedKey, key)` already encodes "same path or
+      // descendant," reusing the same semantics used for cascading error
+      // clears (see utils.ts).
+      for (const touchedKey in formState.touched) {
+        if (formState.touched[touchedKey] && isPathAffected(touchedKey, key)) return err;
+      }
+      return undefined;
     },
     [formState.touched, errors],
   );

tests/hooks/useForm.test.tsx

@@ -794,6 +794,127 @@ describe('useForm', () => {
 
       expect(result.current.getFieldError('address.city')).toBe('City is required');
     });
+
+    test('group path: returns undefined when no descendant is touched', () => {
+      const { result } = renderHook(() =>
+        useForm(alwaysValidValidator, {
+          initialValues: { r1: [0, 0, 0], r2: [0, 0, 0] },
+        }),
+      );
+
+      act(() => {
+        result.current.setServerErrors({ r2: 'Vectors must differ' });
+      });
+
+      // Error exists but no descendant touched — invisible.
+      expect(result.current.getFieldError('r2')).toBeUndefined();
+    });
+
+    test('group path: bubbles error once a descendant is touched', () => {
+      const { result } = renderHook(() =>
+        useForm(alwaysValidValidator, {
+          initialValues: { r1: [0, 0, 0], r2: [0, 0, 0] },
+        }),
+      );
+
+      act(() => {
+        result.current.setServerErrors({ r2: 'Vectors must differ' });
+        result.current.setFieldTouched('r2.0', true);
+      });
+
+      expect(result.current.getFieldError('r2')).toBe('Vectors must differ');
+    });
+
+    test('group path: ignores sibling-prefix touches (r20.0 must not satisfy "r2." scan)', () => {
+      const { result } = renderHook(() =>
+        useForm(alwaysValidValidator, {
+          initialValues: {
+            r2: [0, 0, 0],
+            r20: [0, 0, 0],
+          },
+        }),
+      );
+
+      act(() => {
+        result.current.setServerErrors({ r2: 'Vectors must differ' });
+        result.current.setFieldTouched('r20.0', true);
+      });
+
+      // r20.0 starts with "r20." not "r2." — the trailing-dot guard.
+      expect(result.current.getFieldError('r2')).toBeUndefined();
+    });
+
+    test('group path: nested descendant satisfies the scan', () => {
+      const { result } = renderHook(() =>
+        useForm(alwaysValidValidator, {
+          initialValues: {
+            secondary: { position: [0, 0, 0], velocity: [0, 0, 0] },
+          },
+        }),
+      );
+
+      act(() => {
+        result.current.setServerErrors({
+          secondary: 'Primary and secondary must differ',
+        });
+        result.current.setFieldTouched('secondary.position.0', true);
+      });
+
+      expect(result.current.getFieldError('secondary')).toBe('Primary and secondary must differ');
+    });
+
+    test('group path: descendant touched but no error at path → undefined', () => {
+      const { result } = renderHook(() =>
+        useForm(alwaysValidValidator, {
+          initialValues: { r1: [0, 0, 0], r2: [0, 0, 0] },
+        }),
+      );
+
+      act(() => {
+        result.current.setFieldTouched('r2.0', true);
+      });
+
+      // Short-circuit: no error at "r2", scan never runs.
+      expect(result.current.getFieldError('r2')).toBeUndefined();
+    });
+
+    test('leaf path: behavior unchanged when descendants are touched', () => {
+      // Ensures the new branch doesn't accidentally affect leaf semantics.
+      const { result } = renderHook(() =>
+        useForm(alwaysValidValidator, {
+          initialValues: { name: '' },
+        }),
+      );
+
+      act(() => {
+        result.current.setServerErrors({ name: 'Name is required' });
+        result.current.setFieldTouched('name', true);
+      });
+
+      expect(result.current.getFieldError('name')).toBe('Name is required');
+    });
+
+    test("group path: error at one parent does not bubble through a sibling parent's descendant touch", () => {
+      const { result } = renderHook(() =>
+        useForm(alwaysValidValidator, {
+          initialValues: {
+            primary: { position: [0, 0, 0] },
+            secondary: { position: [0, 0, 0] },
+          },
+        }),
+      );
+
+      act(() => {
+        result.current.setServerErrors({
+          primary: 'primary error',
+          secondary: 'secondary error',
+        });
+        result.current.setFieldTouched('primary.position.0', true);
+      });
+
+      expect(result.current.getFieldError('primary')).toBe('primary error');
+      expect(result.current.getFieldError('secondary')).toBeUndefined();
+    });
   });
 
   describe('getFieldId', () => {