refactor: streamline button disable logic and enhance field validator typings for clarity

Author: sakobu

README.md

@@ -75,7 +75,7 @@ export function LoginForm() {
         <span>{form.errors.password}</span>
       )}
 
-      <button type="submit" disabled={form.isSubmitting || !form.isValid}>
+      <button type="submit" disabled={form.isSubmitting}>
         {form.isSubmitting ? 'Logging in...' : 'Log In'}
       </button>
     </form>
@@ -174,13 +174,12 @@ export function RegistrationForm() {
     },
     fieldValidators: {
       username: async (value) => {
-        const username = value as string;
-        if (username.length < 3) return undefined;
+        if (value.length < 3) return undefined;
 
         try {
           const { available } = await queryClient.fetchQuery({
-            queryKey: ['check-username', username],
-            queryFn: () => checkUsername(username),
+            queryKey: ['check-username', value],
+            queryFn: () => checkUsername(value),
             staleTime: 30_000,
           });
           return available ? undefined : 'Username is already taken';
@@ -221,7 +220,7 @@ export function RegistrationForm() {
 
       <button
         type="submit"
-        disabled={mutation.isPending || form.isValidating || !form.isValid}
+        disabled={mutation.isPending || form.isValidating}
       >
         {mutation.isPending ? 'Registering...' : 'Create Account'}
       </button>

docs/API.md

@@ -114,10 +114,10 @@ Controls when validation occurs.
 
 #### fieldValidators
 
-Type: `Partial<Record<ExtractFieldPaths<TValues>, (value: unknown, values: TValues) => string | undefined | Promise<string | undefined>>>`
+Type: `{ [K in ExtractFieldPaths<TValues>]?: (value: FieldTypeAtPath<TValues, K>, values: TValues) => string | undefined | Promise<string | undefined> }`
 Optional
 
-Per-field validator functions for field-level async validation. Run independently from the main schema validator, only for the changed field. A field validator only runs when the schema produces **no error** for that field (schema passes first, then the field validator runs).
+Per-field validator functions for field-level async validation. The `value` parameter is typed based on the field path, so no cast is needed. Run independently from the main schema validator, only for the changed field. A field validator only runs when the schema produces **no error** for that field (schema passes first, then the field validator runs).
 
 Return `undefined` for valid, or an error message string for invalid.
 
@@ -126,7 +126,7 @@ const form = useForm(userSchema, {
   initialValues: { username: '', email: '' },
   fieldValidators: {
     username: async (value) => {
-      const available = await checkUsernameAvailable(value as string);
+      const available = await checkUsernameAvailable(value);
       return available ? undefined : 'Username is already taken';
     },
   },

docs/GETTING_STARTED.md

@@ -98,7 +98,7 @@ function LoginForm() {
         )}
       </div>
 
-      <button type="submit" disabled={form.isSubmitting || !form.isValid}>
+      <button type="submit" disabled={form.isSubmitting}>
         {form.isSubmitting ? 'Logging in...' : 'Log In'}
       </button>
     </form>

docs/RECIPES.md

@@ -112,7 +112,7 @@ function CreateUserForm() {
         <div className="form-error">{form.errors[ROOT_ERROR_KEY]}</div>
       )}
 
-      <button type="submit" disabled={form.isSubmitting || !form.isValid}>
+      <button type="submit" disabled={form.isSubmitting}>
         {form.isSubmitting ? 'Saving...' : 'Create User'}
       </button>
 
@@ -1007,7 +1007,7 @@ function RegistrationForm() {
     },
     fieldValidators: {
       username: async (value) => {
-        const available = await checkUsernameAvailable(value as string);
+        const available = await checkUsernameAvailable(value);
         return available ? undefined : 'Username is already taken';
       },
     },
@@ -1029,7 +1029,7 @@ function RegistrationForm() {
 
       <button
         type="submit"
-        disabled={form.isSubmitting || form.isValidating || !form.isValid}
+        disabled={form.isSubmitting || form.isValidating}
       >
         Register
       </button>
@@ -1048,7 +1048,7 @@ function RegistrationForm() {
 | **Race conditions** | Handled per-field (latest wins)    | Handled per-form (latest wins) |
 | **Best for**        | Server lookups (username, email)   | Cross-field async checks       |
 
-Field validators return `undefined` for valid, or an error message string for invalid. They receive the field value and the full form values object: `(value, values) => string | undefined | Promise<string | undefined>`.
+Field validators return `undefined` for valid, or an error message string for invalid. They receive the typed field value and the full form values object: `(value: FieldTypeAtPath<TValues, K>, values: TValues) => string | undefined | Promise<string | undefined>` — no cast needed.
 
 ---
 
@@ -1664,9 +1664,8 @@ export function RegistrationForm() {
     initialValues: { username: '', email: '', password: '', confirmPassword: '' },
     fieldValidators: {
       username: async (value) => {
-        const username = value as string;
-        if (username.length < 3) return undefined;
-        const result = await checkUsername(username);
+        if (value.length < 3) return undefined;
+        const result = await checkUsername(value);
         return match(result, {
           ok: ({ available }) => available ? undefined : 'Username is already taken',
           err: () => 'Unable to check username availability',
@@ -1703,7 +1702,7 @@ export function RegistrationForm() {
         <span>{form.errors[ROOT_ERROR_KEY]}</span>
       )}
 
-      <button type="submit" disabled={form.isSubmitting || form.isValidating || !form.isValid}>
+      <button type="submit" disabled={form.isSubmitting || form.isValidating}>
         {form.isSubmitting ? 'Registering...' : 'Create Account'}
       </button>
     </form>
@@ -1796,13 +1795,12 @@ export function RegistrationForm() {
     initialValues: { username: '', email: '', password: '', confirmPassword: '' },
     fieldValidators: {
       username: async (value) => {
-        const username = value as string;
-        if (username.length < 3) return undefined;
+        if (value.length < 3) return undefined;
 
         try {
           const { available } = await queryClient.fetchQuery({
-            queryKey: ['check-username', username],
-            queryFn: () => checkUsername(username),
+            queryKey: ['check-username', value],
+            queryFn: () => checkUsername(value),
             staleTime: 30_000,
           });
           return available ? undefined : 'Username is already taken';
@@ -1835,7 +1833,7 @@ export function RegistrationForm() {
         <span>{form.errors[ROOT_ERROR_KEY]}</span>
       )}
 
-      <button type="submit" disabled={mutation.isPending || form.isValidating || !form.isValid}>
+      <button type="submit" disabled={mutation.isPending || form.isValidating}>
         {mutation.isPending ? 'Registering...' : 'Create Account'}
       </button>
     </form>

examples/field-validators/FieldValidatorForm.tsx

@@ -29,7 +29,7 @@ export default function FieldValidatorForm() {
     // Per-field async validators — run after schema validation passes for that field
     fieldValidators: {
       username: async (value) => {
-        const available = await checkUsernameAvailable(value as string);
+        const available = await checkUsernameAvailable(value);
         return available ? undefined : 'Username is already taken';
       },
     },

src/types.ts

@@ -197,15 +197,12 @@ export interface FormOptions<TValues extends Record<string, unknown>> {
    * A field validator only runs when the schema produces no error for that field.
    * Return undefined for valid, or an error message string for invalid.
    */
-  fieldValidators?: Partial<
-    Record<
-      ExtractFieldPaths<TValues>,
-      (
-        value: unknown,
-        values: TValues
-      ) => string | undefined | Promise<string | undefined>
-    >
-  >;
+  fieldValidators?: {
+    [K in ExtractFieldPaths<TValues>]?: (
+      value: FieldTypeAtPath<TValues, K>,
+      values: TValues
+    ) => string | undefined | Promise<string | undefined>;
+  };
 }
 
 // =============================================================================
@@ -502,6 +499,28 @@ export type NativeCheckboxGroupOptionProps = {
  * type Form = { payment: Payment };
  * type Paths = ExtractFieldPaths<Form>; // "payment" | "payment.type" | "payment.cardNumber" | "payment.email"
  */
+/**
+ * Resolves the type at a dot-separated field path within a type.
+ * Companion to ExtractFieldPaths — while ExtractFieldPaths extracts all valid paths,
+ * FieldTypeAtPath resolves the value type at a given path.
+ *
+ * @template T - The root type to traverse
+ * @template P - A dot-separated path string
+ *
+ * @example
+ * type User = { name: string; address: { city: string; zip: number } };
+ * type City = FieldTypeAtPath<User, "address.city">; // string
+ * type Zip = FieldTypeAtPath<User, "address.zip">;   // number
+ */
+export type FieldTypeAtPath<T, P extends string> =
+  P extends `${infer K}.${infer Rest}`
+    ? K extends keyof T
+      ? FieldTypeAtPath<NonNullable<T[K]>, Rest>
+      : unknown
+    : P extends keyof T
+      ? T[P]
+      : unknown;
+
 export type ExtractFieldPaths<T> = T extends readonly unknown[]
   ? never
   : T extends object

src/useForm.ts

@@ -361,7 +361,7 @@ export const useForm = <TValues extends Record<string, unknown>>(
       dispatch({ type: 'SET_FIELD_ERROR', field, error: undefined });
 
       const fieldValue = getValueByPath(values, field);
-      const result = validatorFn(fieldValue, values);
+      const result = (validatorFn as (value: unknown, values: TValues) => string | undefined | Promise<string | undefined>)(fieldValue, values);
 
       if (result instanceof Promise) {
         if (!fieldValidationSeqRef.current[field]) {