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

package/README.md

@@ -1,13 +1,48 @@
 # @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)
 [![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 and default values accept `null | undefined` 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 requires string - NOT optional
+const schema = z.object({
+  username: z.string().min(3),
+  email: z.string().email(),
+});
+
+const form = useZodForm({ schema });
+
+// ✅ Works! defaultValues accepts null/undefined during editing
+form.reset({ username: null, email: undefined });
+
+// ✅ Works! setValue accepts null/undefined during editing
+form.setValue("username", null);
+form.setValue("email", undefined);
+
+// ✅ Validated output type is exactly z.infer<typeof schema>
+const onSubmit = form.handleSubmit((data) => {
+  // Type: { username: string; email: string }
+  // NOT { username: string | null | undefined; email: string | null | undefined }
+  console.log(data.username); // Type: string
+  console.log(data.email); // Type: string
+});
+```
+
 ## Installation
 
 ```bash
@@ -16,19 +51,18 @@ npm install @zod-utils/react-hook-form zod react react-hook-form @hookform/resol
 
 ## 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 +79,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 +95,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,86 +104,23 @@ 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
-
----
-
-### `customErrorResolver(config)`
-
-Custom error message resolver with Japanese translations. Easily customizable for other languages.
-
-```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',
-});
-
-const schema = z.object({
-  username: z.string(),
-  email: z.string().email(),
-});
-
-// Use with Zod
-schema.parse({ username: '', email: 'invalid' }, { errorMap });
-```
-
-**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...
-
----
-
-### `FieldNamespaceMapping`
+**What it does:**
 
-Mapping object for custom field names in error messages.
-
-```typescript
-export const FieldNamespaceMapping = {
-  department: {
-    groupName: '部署・店舗名',
-  },
-  // Add your own namespaces
-};
-
-export type FIELD_NAMESPACE = keyof typeof FieldNamespaceMapping;
-```
-
-**Extend it:**
-```typescript
-import { FieldNamespaceMapping } from '@zod-utils/react-hook-form';
-
-const CustomMapping = {
-  ...FieldNamespaceMapping,
-  userForm: {
-    firstName: '名',
-    lastName: '姓',
-  },
-};
-```
+- **Input transformation**: Form field values can be `null` or `undefined` during editing
+- **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
 
 ---
 
@@ -159,35 +130,53 @@ All utilities from `@zod-utils/core` are re-exported for convenience:
 
 ```typescript
 import {
-  // Schema utilities
+  // Schema utilities (from @zod-utils/core)
   getSchemaDefaults,
   checkIfFieldIsRequired,
   getPrimitiveType,
   removeDefault,
   extractDefault,
-  getUnwrappedType,
+  type Simplify,
 
-  // Type utilities
+  // Type utilities (react-hook-form specific)
   type MakeOptionalAndNullable,
-  type Simplify,
-  type PickArrayObject,
-} from '@zod-utils/react-hook-form';
+} from "@zod-utils/react-hook-form";
+```
+
+See [@zod-utils/core documentation](../core/README.md) for details on schema utilities.
+
+### Type Utilities
+
+#### `MakeOptionalAndNullable<T>`
+
+Make all properties optional and nullable. Useful for React Hook Form input types where fields can be empty during editing.
+
+```typescript
+import type { MakeOptionalAndNullable } from "@zod-utils/react-hook-form";
+
+type User = {
+  name: string;
+  age: number;
+};
+
+type FormInput = MakeOptionalAndNullable<User>;
+// { name?: string | null; age?: number | null; }
 ```
 
-See [@zod-utils/core documentation](../core/README.md) for details.
+This type is used internally by `useZodForm` to allow form fields to be null/undefined during editing while maintaining proper validation types.
 
 ---
 
 ## 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 +184,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 +196,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 +261,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,229 @@
+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';
+
+/**
+ * Transforms all properties in a type to be optional and nullable.
+ *
+ * This type utility is the secret sauce behind `useZodForm`'s type transformation.
+ * It makes form inputs accept `null | undefined` during editing, while validated
+ * output remains exactly as the schema defines.
+ *
+ * **Why this matters:**
+ * - React Hook Form fields often contain `null` or `undefined` during user input
+ * - Zod schemas define strict output types without these nullable/optional wrappers
+ * - This type bridges the gap, eliminating "Type 'null' is not assignable to..." errors
+ *
+ * @template T - The object type to transform
+ *
+ * @example
+ * Basic transformation
+ * ```typescript
+ * type User = {
+ *   name: string;
+ *   age: number;
+ * };
+ *
+ * type FormUser = MakeOptionalAndNullable<User>;
+ * // Result: {
+ * //   name?: string | null;
+ * //   age?: number | null;
+ * // }
+ * ```
+ *
+ * @example
+ * Usage with useZodForm
+ * ```typescript
+ * const schema = z.object({
+ *   title: z.string(),
+ *   count: z.number(),
+ * });
+ *
+ * const form = useZodForm({ schema });
+ *
+ * // ✅ These work without type errors:
+ * form.setValue('title', null); // Accepts null during editing
+ * form.setValue('title', undefined); // Accepts undefined
+ * form.reset({ title: null, count: null }); // Reset with null values
+ *
+ * // But validated output is still:
+ * // { title: string, count: number }
+ * ```
+ *
+ * @example
+ * Comparison with original type
+ * ```typescript
+ * type Schema = {
+ *   email: string;
+ *   isActive: boolean;
+ * };
+ *
+ * // Original: { email: string; isActive: boolean }
+ * // Transformed: { email?: string | null; isActive?: boolean | null }
+ *
+ * const original: Schema = { email: '', isActive: true }; // OK
+ * const original2: Schema = { email: null }; // ❌ Error
+ *
+ * const transformed: MakeOptionalAndNullable<Schema> = {}; // OK
+ * const transformed2: MakeOptionalAndNullable<Schema> = { email: null }; // OK
+ * ```
+ *
+ * @see {@link useZodForm} for how this type is used in practice
+ * @since 0.1.0
+ */
+type MakeOptionalAndNullable<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** (`MakeOptionalAndNullable<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, MakeOptionalAndNullable<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
+ * 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().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
- * ```ts
+ * With default values
+ * ```typescript
  * const schema = z.object({
- *   name: z.string(),
- *   age: z.number()
+ *   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 MakeOptionalAndNullable} 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;
+    schema: z.ZodType<T, MakeOptionalAndNullable<T>>;
     defaultValues?: DefaultValues<MakeOptionalAndNullable<T>>;
     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<MakeOptionalAndNullable<T>, unknown, T>, "resolver" | "defaultValues">) => react_hook_form.UseFormReturn<MakeOptionalAndNullable<T>, unknown, T>;
 
-export { type FIELD_NAMESPACE, FieldNamespaceMapping, createEnglishErrorMap, createJapaneseErrorMap, customErrorResolver, useZodForm };
+export { type MakeOptionalAndNullable, useZodForm };