@zod-utils/react-hook-form 0.1.0 → 0.4.0

package/README.md

@@ -1,34 +1,79 @@
 # @zod-utils/react-hook-form
 
-
 [![npm version](https://img.shields.io/npm/v/@zod-utils/react-hook-form.svg)](https://www.npmjs.com/package/@zod-utils/react-hook-form)
 [![npm downloads](https://img.shields.io/npm/dm/@zod-utils/react-hook-form.svg)](https://www.npmjs.com/package/@zod-utils/react-hook-form)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@zod-utils/react-hook-form)](https://bundlephobia.com/package/@zod-utils/react-hook-form)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
 [![CI](https://github.com/thu-san/zod-utils/workflows/CI/badge.svg)](https://github.com/thu-san/zod-utils/actions)
+[![codecov](https://codecov.io/gh/thu-san/zod-utils/branch/main/graph/badge.svg?flag=react-hook-form)](https://codecov.io/gh/thu-san/zod-utils)
+
 React Hook Form integration and utilities for Zod schemas.
 
+## 💡 Why Use This?
+
+**The whole point:** Automatically transforms your Zod schema types so form inputs accept `undefined` (and `null` for objects only) during editing, while the validated output remains exactly as your Zod schema defines.
+
+No more type wrestling with React Hook Form - just pass your schema and it works.
+
+```typescript
+import { useZodForm } from "@zod-utils/react-hook-form";
+import { z } from "zod";
+
+// Your schema with primitives, arrays, and objects - NOT optional
+const schema = z.object({
+  username: z.string().min(3),
+  age: z.number().min(18),
+  tags: z.array(z.string()),
+  profile: z.object({ bio: z.string() }),
+});
+
+const form = useZodForm({ schema });
+
+// ✅ Works! Primitives and arrays accept undefined during editing
+form.setValue("username", undefined);
+form.setValue("age", undefined);
+form.setValue("tags", undefined);
+
+// ✅ Works! Objects accept both null and undefined
+form.setValue("profile", null);
+form.setValue("profile", undefined);
+
+// ✅ Validated output type is exactly z.infer<typeof schema>
+const onSubmit = form.handleSubmit((data) => {
+  // Type: { username: string; age: number; tags: string[]; profile: { bio: string } }
+  // NOT { username: string | null | undefined; ... }
+  console.log(data.username); // Type: string
+  console.log(data.age); // Type: number
+  console.log(data.tags); // Type: string[]
+  console.log(data.profile); // Type: { bio: string }
+});
+```
+
 ## Installation
 
 ```bash
 npm install @zod-utils/react-hook-form zod react react-hook-form @hookform/resolvers
 ```
 
+## Related Packages
+
+- **[@zod-utils/core](https://www.npmjs.com/package/@zod-utils/core)** - Pure TypeScript utilities for Zod schema manipulation (no React dependencies). All utilities are re-exported from this package for convenience.
+
 ## Features
 
-- 🎣 **useZodForm** - Type-safe React Hook Form integration
-- 🌐 **Custom error messages** - Japanese error resolver (customizable)
+- 🎣 **useZodForm** - Automatic type transformation for form inputs (nullable/undefined) while preserving Zod schema validation
 - 📦 **All core utilities** - Re-exports everything from `@zod-utils/core`
 - ⚛️ **React-optimized** - Built specifically for React applications
 
 ## Quick Start
 
 ```typescript
-import { useZodForm, getSchemaDefaults } from '@zod-utils/react-hook-form';
-import { z } from 'zod';
+import { useZodForm, getSchemaDefaults } from "@zod-utils/react-hook-form";
+import { z } from "zod";
 
 const schema = z.object({
-  name: z.string().default('John Doe'),
+  name: z.string().default("John Doe"),
   email: z.string().email(),
   age: z.number().min(18),
 });
@@ -45,9 +90,9 @@ function MyForm() {
 
   return (
     <form onSubmit={onSubmit}>
-      <input {...form.register('name')} />
-      <input {...form.register('email')} type="email" />
-      <input {...form.register('age')} type="number" />
+      <input {...form.register("name")} />
+      <input {...form.register("email")} type="email" />
+      <input {...form.register("age")} type="number" />
       <button type="submit">Submit</button>
     </form>
   );
@@ -61,8 +106,8 @@ function MyForm() {
 Type-safe wrapper around React Hook Form's `useForm` with automatic Zod schema integration.
 
 ```typescript
-import { useZodForm } from '@zod-utils/react-hook-form';
-import { z } from 'zod';
+import { useZodForm } from "@zod-utils/react-hook-form";
+import { z } from "zod";
 
 const schema = z.object({
   username: z.string().min(3),
@@ -70,124 +115,164 @@ const schema = z.object({
 });
 
 const form = useZodForm({
-  schema,                          // Zod schema (required)
-  defaultValues: { /* ... */ },    // Optional default values
-  zodResolverOptions: { /* ... */ }, // Optional zodResolver options
+  schema, // Zod schema (required)
+  defaultValues: {
+    /* ... */
+  }, // Optional default values
+  zodResolverOptions: {
+    /* ... */
+  }, // Optional zodResolver options
   // ... all other useForm options
 });
 ```
 
-**Automatically sets up:**
-- Zod schema validation via `zodResolver`
-- Proper TypeScript typing
-- Form state management
+**What it does:**
 
----
+- **Input transformation** (by default):
+  - **Primitive fields** (string, number, boolean) accept `undefined` only
+  - **Array fields** accept `undefined` only
+  - **Object fields** accept both `null` and `undefined`
+  - You can override this by specifying a custom input type (see examples below)
+- **Output validation**: Validated data matches your Zod schema exactly
+- **Type inference**: No manual type annotations needed - everything is inferred from the schema
+- **Zod integration**: Automatically sets up `zodResolver` for validation
 
-### `customErrorResolver(config)`
+#### Custom Input Types
 
-Custom error message resolver with Japanese translations. Easily customizable for other languages.
+You can override the default input type transformation if needed:
 
 ```typescript
-import { customErrorResolver, FieldNamespaceMapping } from '@zod-utils/react-hook-form';
-import { z } from 'zod';
-
-// Extend the field namespace mapping
-const MyFieldNamespaceMapping = {
-  ...FieldNamespaceMapping,
-  myForm: {
-    username: 'ユーザー名',
-    email: 'メールアドレス',
-  },
-};
-
-const errorMap = customErrorResolver({
-  fieldNamespace: 'myForm',
-});
+import {
+  useZodForm,
+  PartialWithAllNullables,
+} from "@zod-utils/react-hook-form";
+import { z } from "zod";
 
 const schema = z.object({
-  username: z.string(),
+  username: z.string().min(3),
   email: z.string().email(),
+  age: z.number(),
 });
 
-// Use with Zod
-schema.parse({ username: '', email: 'invalid' }, { errorMap });
-```
+// Option 1: Use PartialWithAllNullables to make ALL fields accept null
+const form = useZodForm<
+  z.infer<typeof schema>,
+  PartialWithAllNullables<z.infer<typeof schema>>
+>({
+  schema,
+  defaultValues: { username: null, email: null, age: null },
+});
 
-**Supported error types:**
-- `too_small` / `too_big` - With field-specific messages
-- `invalid_type` - Type mismatch errors
-- `invalid_format` - Email, URL, UUID, etc.
-- `invalid_value` - Enum/literal errors
-- And more...
+// Option 2: Specify exact input types per field
+const form2 = useZodForm<
+  z.infer<typeof schema>,
+  {
+    username?: string | null; // Can be set to null
+    email?: string; // Can only be undefined
+    age?: number | null; // Can be set to null
+  }
+>({
+  schema,
+  defaultValues: { username: null, email: undefined, age: null },
+});
+```
 
 ---
 
-### `FieldNamespaceMapping`
+## Core Utilities (Re-exported)
 
-Mapping object for custom field names in error messages.
+All utilities from `@zod-utils/core` are re-exported for convenience:
 
 ```typescript
-export const FieldNamespaceMapping = {
-  department: {
-    groupName: '部署・店舗名',
-  },
-  // Add your own namespaces
-};
+import {
+  // Schema utilities (from @zod-utils/core)
+  getSchemaDefaults,
+  requiresValidInput,
+  getPrimitiveType,
+  removeDefault,
+  extractDefault,
+  type Simplify,
 
-export type FIELD_NAMESPACE = keyof typeof FieldNamespaceMapping;
+  // Type utilities (react-hook-form specific)
+  type PartialWithNullableObjects,
+  type PartialWithAllNullables,
+} from "@zod-utils/react-hook-form";
 ```
 
-**Extend it:**
+See [@zod-utils/core documentation](../core/README.md) for details on schema utilities.
+
+### Type Utilities
+
+#### `PartialWithNullableObjects<T>`
+
+Transforms properties based on their type. Primitive and array fields become optional-only (not nullable), while object fields become optional and nullable.
+
+**Transformation rules:**
+
+- **Primitives** (string, number, boolean): optional → `type | undefined`
+- **Arrays**: optional → `type[] | undefined`
+- **Objects**: optional and nullable → `type | null | undefined`
+
 ```typescript
-import { FieldNamespaceMapping } from '@zod-utils/react-hook-form';
-
-const CustomMapping = {
-  ...FieldNamespaceMapping,
-  userForm: {
-    firstName: '名',
-    lastName: '姓',
-  },
+import type { PartialWithNullableObjects } from "@zod-utils/react-hook-form";
+
+type User = {
+  name: string;
+  age: number;
+  tags: string[];
+  profile: { bio: string };
 };
+
+type FormInput = PartialWithNullableObjects<User>;
+// {
+//   name?: string;                  // Primitive: optional, not nullable
+//   age?: number;                   // Primitive: optional, not nullable
+//   tags?: string[];                // Array: optional, not nullable
+//   profile?: { bio: string } | null; // Object: optional AND nullable
+// }
 ```
 
----
+This type is used internally by `useZodForm` to allow form fields to accept undefined (and null for objects only) during editing while maintaining proper validation types.
 
-## Core Utilities (Re-exported)
+#### `PartialWithAllNullables<T>`
 
-All utilities from `@zod-utils/core` are re-exported for convenience:
+Makes all fields optional and nullable, regardless of type.
+
+**Transformation rules:**
+
+- **All fields**: optional and nullable → `type | null | undefined`
 
 ```typescript
-import {
-  // Schema utilities
-  getSchemaDefaults,
-  checkIfFieldIsRequired,
-  getPrimitiveType,
-  removeDefault,
-  extractDefault,
-  getUnwrappedType,
+import type { PartialWithAllNullables } from "@zod-utils/react-hook-form";
 
-  // Type utilities
-  type MakeOptionalAndNullable,
-  type Simplify,
-  type PickArrayObject,
-} from '@zod-utils/react-hook-form';
+type User = {
+  name: string;
+  age: number;
+  tags: string[];
+};
+
+type FormInput = PartialWithAllNullables<User>;
+// {
+//   name?: string | null;       // All fields: optional AND nullable
+//   age?: number | null;        // All fields: optional AND nullable
+//   tags?: string[] | null;     // All fields: optional AND nullable
+// }
 ```
 
-See [@zod-utils/core documentation](../core/README.md) for details.
+Use this when all fields need to accept `null`, not just objects/arrays.
 
 ---
 
 ## Complete Example
 
 ```typescript
-import { useZodForm, getSchemaDefaults } from '@zod-utils/react-hook-form';
-import { z } from 'zod';
+import { useZodForm, getSchemaDefaults } from "@zod-utils/react-hook-form";
+import { z } from "zod";
 
 const userSchema = z.object({
   profile: z.object({
-    firstName: z.string().min(1, 'First name is required'),
-    lastName: z.string().min(1, 'Last name is required'),
+    firstName: z.string().min(1, "First name is required"),
+    lastName: z.string().min(1, "Last name is required"),
     age: z.number().min(18).max(120),
   }),
   contact: z.object({
@@ -195,7 +280,7 @@ const userSchema = z.object({
     phone: z.string().optional(),
   }),
   preferences: z.object({
-    theme: z.enum(['light', 'dark']).default('light'),
+    theme: z.enum(["light", "dark"]).default("light"),
     notifications: z.boolean().default(true),
   }),
 });
@@ -207,44 +292,47 @@ function UserForm() {
   });
 
   const onSubmit = form.handleSubmit((data) => {
-    console.log('Valid data:', data);
+    console.log("Valid data:", data);
   });
 
   return (
     <form onSubmit={onSubmit}>
       {/* Profile */}
-      <input {...form.register('profile.firstName')} />
+      <input {...form.register("profile.firstName")} />
       {form.formState.errors.profile?.firstName && (
         <span>{form.formState.errors.profile.firstName.message}</span>
       )}
 
-      <input {...form.register('profile.lastName')} />
+      <input {...form.register("profile.lastName")} />
       {form.formState.errors.profile?.lastName && (
         <span>{form.formState.errors.profile.lastName.message}</span>
       )}
 
-      <input {...form.register('profile.age', { valueAsNumber: true })} type="number" />
+      <input
+        {...form.register("profile.age", { valueAsNumber: true })}
+        type="number"
+      />
       {form.formState.errors.profile?.age && (
         <span>{form.formState.errors.profile.age.message}</span>
       )}
 
       {/* Contact */}
-      <input {...form.register('contact.email')} type="email" />
+      <input {...form.register("contact.email")} type="email" />
       {form.formState.errors.contact?.email && (
         <span>{form.formState.errors.contact.email.message}</span>
       )}
 
-      <input {...form.register('contact.phone')} type="tel" />
+      <input {...form.register("contact.phone")} type="tel" />
 
       {/* Preferences - pre-filled with defaults */}
-      <select {...form.register('preferences.theme')}>
+      <select {...form.register("preferences.theme")}>
         <option value="light">Light</option>
         <option value="dark">Dark</option>
       </select>
 
       <label>
         <input
-          {...form.register('preferences.notifications')}
+          {...form.register("preferences.notifications")}
           type="checkbox"
         />
         Enable notifications
@@ -269,10 +357,10 @@ const form = useZodForm({
 });
 
 // ✅ Fully typed
-form.register('profile.firstName');
+form.register("profile.firstName");
 
 // ❌ TypeScript error
-form.register('nonexistent.field');
+form.register("nonexistent.field");
 ```
 
 ---

package/dist/index.d.mts

@@ -1,66 +1,194 @@
+export * from '@zod-utils/core';
 import * as react_hook_form from 'react-hook-form';
 import { FieldValues, DefaultValues, UseFormProps } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
-import { MakeOptionalAndNullable } from '@zod-utils/core';
-export * from '@zod-utils/core';
-import { ZodTypeAny, ZodErrorMap } from 'zod';
+import { z } from 'zod';
+
+/**
+ * Helper type that adds `null` to object-type fields only (excludes arrays).
+ * @internal
+ */
+type AddNullToObjects<T> = {
+    [K in keyof T]: T[K] extends readonly unknown[] ? T[K] : T[K] extends object ? T[K] | null : T[K];
+};
+/**
+ * Transforms Zod schema types for form inputs.
+ *
+ * - **Primitives** (string, number, boolean): optional → `type | undefined`
+ * - **Arrays**: optional → `type[] | undefined`
+ * - **Objects**: optional and nullable → `type | null | undefined`
+ *
+ * @example
+ * ```typescript
+ * type User = { name: string; tags: string[]; profile: { bio: string } };
+ * type FormInput = PartialWithNullableObjects<User>;
+ * // { name?: string; tags?: string[]; profile?: { bio: string } | null; }
+ * ```
+ */
+type PartialWithNullableObjects<T> = Partial<AddNullToObjects<T>>;
+/**
+ * Makes all fields optional and nullable.
+ *
+ * - **All fields**: optional and nullable → `type | null | undefined`
+ *
+ * @example
+ * ```typescript
+ * type User = { name: string; age: number; tags: string[] };
+ * type FormInput = PartialWithAllNullables<User>;
+ * // { name?: string | null; age?: number | null; tags?: string[] | null; }
+ * ```
+ */
+type PartialWithAllNullables<T> = {
+    [K in keyof T]?: T[K] | null;
+};
 
 /**
- * Type-safe wrapper around useForm with Zod v4 schema integration
- * Automatically sets up zodResolver and provides better type inference
+ * Type-safe React Hook Form wrapper with automatic Zod v4 schema validation and type transformation.
+ *
+ * This hook eliminates the TypeScript friction between React Hook Form's nullable field values
+ * and Zod's strict output types. It uses a two-type schema pattern where:
+ * - **Input type** (`PartialWithNullableObjects<T>`): Form fields accept `null | undefined` during editing
+ * - **Output type** (`T`): Validated data matches exact schema type (no `null | undefined`)
+ *
+ * **Key Benefits:**
+ * - ✅ No more "Type 'null' is not assignable to..." TypeScript errors
+ * - ✅ Use `form.setValue()` and `form.reset()` with `null` values freely
+ * - ✅ Validated output is still type-safe with exact Zod schema types
+ * - ✅ Automatic zodResolver setup - no manual configuration needed
+ *
+ * @template T - The Zod schema output type (extends FieldValues)
+ *
+ * @param options - Configuration object
+ * @param options.schema - Zod schema with two-type signature `z.ZodType<T, PartialWithNullableObjects<T>>`
+ * @param options.defaultValues - Default form values (accepts nullable/undefined values)
+ * @param options.zodResolverOptions - Optional zodResolver configuration
+ * @param options....formOptions - All other react-hook-form useForm options
+ *
+ * @returns React Hook Form instance with type-safe methods
  *
  * @example
- * ```ts
+ * Basic usage with required fields
+ * ```typescript
+ * import { useZodForm } from '@zod-utils/react-hook-form';
+ * import { z } from 'zod';
+ *
  * const schema = z.object({
- *   name: z.string(),
- *   age: z.number()
+ *   name: z.string().min(1), // Required field
+ *   age: z.number().min(0),
+ * }) satisfies z.ZodType<{ name: string; age: number }, any>;
+ *
+ * function MyForm() {
+ *   const form = useZodForm({ schema });
+ *
+ *   // ✅ These work without type errors:
+ *   form.setValue('name', null); // Accepts null during editing
+ *   form.reset({ name: null, age: null }); // Reset with null
+ *
+ *   const onSubmit = (data: { name: string; age: number }) => {
+ *     // ✅ data is exact type - no null | undefined
+ *     console.log(data.name.toUpperCase()); // Safe to use string methods
+ *   };
+ *
+ *   return <form onSubmit={form.handleSubmit(onSubmit)}>...</form>;
+ * }
+ * ```
+ *
+ * @example
+ * With default values
+ * ```typescript
+ * const schema = z.object({
+ *   username: z.string(),
+ *   email: z.string().email(),
+ *   notifications: z.boolean().default(true),
+ * }) satisfies z.ZodType<{
+ *   username: string;
+ *   email: string;
+ *   notifications: boolean;
+ * }, any>;
+ *
+ * const form = useZodForm({
+ *   schema,
+ *   defaultValues: {
+ *     username: '',
+ *     email: '',
+ *     // notifications gets default from schema
+ *   },
  * });
+ * ```
+ *
+ * @example
+ * With optional and nullable fields
+ * ```typescript
+ * const schema = z.object({
+ *   title: z.string(),
+ *   description: z.string().optional(), // Optional in output
+ *   tags: z.array(z.string()).nullable(), // Nullable in output
+ * }) satisfies z.ZodType<{
+ *   title: string;
+ *   description?: string;
+ *   tags: string[] | null;
+ * }, any>;
  *
+ * const form = useZodForm({ schema });
+ *
+ * // All fields accept null/undefined during editing
+ * form.setValue('title', null);
+ * form.setValue('description', undefined);
+ * form.setValue('tags', null);
+ * ```
+ *
+ * @example
+ * With zodResolver options
+ * ```typescript
  * const form = useZodForm({
  *   schema,
- *   defaultValues: { name: '', age: 0 }
+ *   zodResolverOptions: {
+ *     async: true, // Enable async validation
+ *     errorMap: customErrorMap, // Custom error messages
+ *   },
  * });
  * ```
+ *
+ * @example
+ * Complete form example
+ * ```typescript
+ * const userSchema = z.object({
+ *   name: z.string().min(1, 'Name is required'),
+ *   email: z.string().email('Invalid email'),
+ *   age: z.number().min(18, 'Must be 18+'),
+ * }) satisfies z.ZodType<{ name: string; email: string; age: number }, any>;
+ *
+ * function UserForm() {
+ *   const form = useZodForm({
+ *     schema: userSchema,
+ *     defaultValues: { name: '', email: '', age: null },
+ *   });
+ *
+ *   const onSubmit = (data: { name: string; email: string; age: number }) => {
+ *     // Type-safe: data has exact types, no null/undefined
+ *     console.log(`${data.name} is ${data.age} years old`);
+ *   };
+ *
+ *   return (
+ *     <form onSubmit={form.handleSubmit(onSubmit)}>
+ *       <input {...form.register('name')} />
+ *       <input {...form.register('email')} type="email" />
+ *       <input {...form.register('age', { valueAsNumber: true })} type="number" />
+ *       <button type="submit">Submit</button>
+ *     </form>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link PartialWithNullableObjects} for the type transformation utility
+ * @see https://react-hook-form.com/docs/useform for React Hook Form documentation
+ * @see https://zod.dev for Zod schema documentation
+ * @since 0.1.0
  */
-declare const useZodForm: <T extends FieldValues>({ schema, zodResolverOptions, ...formOptions }: {
-    schema: ZodTypeAny;
-    defaultValues?: DefaultValues<MakeOptionalAndNullable<T>>;
+declare const useZodForm: <T extends FieldValues, I extends PartialWithAllNullables<T> = PartialWithNullableObjects<T>>({ schema, zodResolverOptions, ...formOptions }: {
+    schema: z.ZodType<T, I>;
+    defaultValues?: DefaultValues<I>;
     zodResolverOptions?: Parameters<typeof zodResolver>[1];
-} & Omit<UseFormProps<MakeOptionalAndNullable<T>, unknown, T>, "resolver" | "defaultValues">) => react_hook_form.UseFormReturn<any, unknown, any>;
-
-/**
- * Japanese error map for Zod validation errors
- * @param fieldName - Optional custom field name to use in error messages
- * @returns Zod error map function
- */
-declare function createJapaneseErrorMap(fieldName?: string): (issue: Parameters<ZodErrorMap>[0]) => string;
-
-/**
- * English error map for Zod validation errors
- * @param fieldName - Optional custom field name to use in error messages
- * @returns Zod error map function
- */
-declare function createEnglishErrorMap(fieldName?: string): (issue: Parameters<ZodErrorMap>[0]) => string;
-
-/**
- * Field namespace mapping for custom error messages
- * You can extend this mapping to customize field names in error messages
- */
-declare const FieldNamespaceMapping: {
-    department: {
-        groupName: string;
-    };
-};
-type FIELD_NAMESPACE = keyof typeof FieldNamespaceMapping;
-/**
- * Custom error resolver with field namespace support (Japanese locale)
- * @deprecated Use createJapaneseErrorMap or createEnglishErrorMap instead
- * @param options - Configuration options
- * @param options.fieldNamespace - Namespace for field name mappings
- * @returns Error resolver function
- */
-declare const customErrorResolver: ({ fieldNamespace, }: {
-    fieldNamespace: FIELD_NAMESPACE;
-}) => (issue: Parameters<ZodErrorMap>[0]) => string;
+} & Omit<UseFormProps<I, unknown, T>, "resolver" | "defaultValues">) => react_hook_form.UseFormReturn<I, unknown, T>;
 
-export { type FIELD_NAMESPACE, FieldNamespaceMapping, createEnglishErrorMap, createJapaneseErrorMap, customErrorResolver, useZodForm };
+export { type PartialWithAllNullables, type PartialWithNullableObjects, useZodForm };