@zod-utils/react-hook-form 6.2.0 → 7.0.0

package/README.md

@@ -241,7 +241,7 @@ You can override the default input type transformation if needed:
 ```typescript
 import {
   useZodForm,
-  DeepPartialWithAllNullables,
+  PartialWithAllNullables,
 } from "@zod-utils/react-hook-form";
 import { z } from "zod";
 
@@ -251,10 +251,10 @@ const schema = z.object({
   age: z.number(),
 });
 
-// Option 1: Use DeepPartialWithAllNullables to make ALL fields accept null
+// Option 1: Use PartialWithAllNullables to make ALL fields accept null
 const form = useZodForm<
   z.infer<typeof schema>,
-  DeepPartialWithAllNullables<z.infer<typeof schema>>
+  PartialWithAllNullables<z.infer<typeof schema>>
 >({
   schema,
   defaultValues: { username: null, email: null, age: null },
@@ -453,11 +453,10 @@ import {
   flattenFieldSelector,
 
   // Type utilities
-  type DeepPartialWithNullableObjects,
-  type DeepPartialWithAllNullables,
-  // Deprecated aliases (kept for backward compatibility)
-  type PartialWithNullableObjects, // Use DeepPartialWithNullableObjects
-  type PartialWithAllNullables, // Use DeepPartialWithAllNullables
+  type PartialWithNullableObjects,
+  type PartialWithAllNullables,
+  type PartialFields,
+  partialFields,
   type DiscriminatorProps,
   type DiscriminatorKey,
   type DiscriminatorValue,
@@ -473,19 +472,20 @@ See [@zod-utils/core documentation](../core/README.md) for details on schema uti
 
 ### Type Utilities
 
-#### `DeepPartialWithNullableObjects<T>`
+#### `PartialWithNullableObjects<T>`
 
-Recursively transforms properties based on their type. Primitive and array fields become optional-only (not nullable), while object fields become optional, nullable, and **recursively transformed**.
+Transforms properties based on their type. By default, **non-recursive** - nested object fields stay strict.
 
 **Transformation rules:**
 
 - **Primitives** (string, number, boolean): optional → `type | undefined`
 - **Arrays**: optional → `type[] | undefined`
 - **Built-in objects** (Date, RegExp, etc.): optional and nullable → `type | null | undefined`
-- **Plain objects**: optional, nullable, and **recursively transformed** → `DeepType | null | undefined`
+- **Plain objects**: optional and nullable, but **nested fields stay strict** → `{ strictField: type } | null | undefined`
+- **Objects marked with `partialFields()`**: optional, nullable, and **recursively transformed** on direct fields
 
 ```typescript
-import type { DeepPartialWithNullableObjects } from "@zod-utils/react-hook-form";
+import type { PartialWithNullableObjects } from "@zod-utils/react-hook-form";
 
 type User = {
   name: string;
@@ -494,39 +494,33 @@ type User = {
   profile: { bio: string; settings: { theme: string } };
 };
 
-type FormInput = DeepPartialWithNullableObjects<User>;
+type FormInput = PartialWithNullableObjects<User>;
 // {
 //   name?: string;                        // Primitive: optional, not nullable
 //   age?: number;                         // Primitive: optional, not nullable
 //   tags?: string[];                      // Array: optional, not nullable
-//   profile?: {                           // Object: optional, nullable, AND recursive
-//     bio?: string;                       // Nested primitive: also optional
-//     settings?: { theme?: string } | null; // Nested object: also recursive
+//   profile?: {                           // Object: optional, nullable
+//     bio: string;                        // Nested field: STRICT (not optional)
+//     settings: { theme: string };        // Nested object: STRICT
 //   } | null;
 // }
 ```
 
-This ensures `useWatch` returns correct types (`T | undefined`) at any nesting depth, since form fields are `undefined` until values are set:
+This is ideal for forms where nested objects come from selectors/dropdowns (should be complete when provided).
 
-```typescript
-const form = useZodForm({ schema });
-const bio = form.watch("profile.bio"); // Correctly typed as `string | undefined`
-```
-
-> **Note:** `PartialWithNullableObjects<T>` is a deprecated alias for `DeepPartialWithNullableObjects<T>`, kept for backward compatibility.
-
-#### `DeepPartialWithAllNullables<T>`
+#### `PartialWithAllNullables<T>`
 
-Recursively makes all fields optional and nullable, regardless of type.
+Makes all fields optional and nullable, but by default **non-recursive** - nested object fields stay strict.
 
 **Transformation rules:**
 
 - **Primitives**: optional and nullable → `type | null | undefined`
 - **Arrays**: optional and nullable → `type[] | null | undefined`
-- **Plain objects**: optional, nullable, and **recursively transformed** → `DeepType | null | undefined`
+- **Plain objects**: optional and nullable, but **nested fields stay strict**
+- **Objects marked with `partialFields()`**: optional, nullable, and **recursively transformed** on direct fields
 
 ```typescript
-import type { DeepPartialWithAllNullables } from "@zod-utils/react-hook-form";
+import type { PartialWithAllNullables } from "@zod-utils/react-hook-form";
 
 type User = {
   name: string;
@@ -534,17 +528,53 @@ type User = {
   profile: { bio: string };
 };
 
-type FormInput = DeepPartialWithAllNullables<User>;
+type FormInput = PartialWithAllNullables<User>;
 // {
-//   name?: string | null;                    // All fields: optional AND nullable
-//   age?: number | null;                     // All fields: optional AND nullable
-//   profile?: { bio?: string | null } | null; // Nested fields also nullable
+//   name?: string | null;                 // Primitive: optional AND nullable
+//   age?: number | null;                  // Primitive: optional AND nullable
+//   profile?: { bio: string } | null;     // Object: nullable, but bio is STRICT
 // }
 ```
 
-Use this when all fields need to accept `null`, not just objects/arrays.
+#### `partialFields(schema)` - Opt-in Recursive Transformation
+
+Use `partialFields()` to mark specific nested objects that should have their **direct fields** made partial. This is useful for objects where users fill in fields manually (vs. objects selected from dropdowns).
+
+```typescript
+import { partialFields } from "@zod-utils/react-hook-form";
+import { z } from "zod";
+
+const schema = z.object({
+  price: z.number(),
+  // User fills in these fields - opt-in to partial
+  detail: partialFields(
+    z.object({
+      hotel: z.string(),
+      nights: z.number(),
+    })
+  ),
+  // Selected from dropdown - stays strict
+  agent: z.object({
+    name: z.string(),
+    fee: z.number(),
+  }),
+});
+
+type FormInput = PartialWithNullableObjects<z.infer<typeof schema>>;
+// {
+//   price?: number;
+//   detail?: {
+//     hotel?: string;      // Partial - user input
+//     nights?: number;     // Partial - user input
+//   } | null;
+//   agent?: {
+//     name: string;        // STRICT - from selector
+//     fee: number;         // STRICT - from selector
+//   } | null;
+// }
+```
 
-> **Note:** `PartialWithAllNullables<T>` is a deprecated alias for `DeepPartialWithAllNullables<T>`, kept for backward compatibility.
+**Note:** `partialFields()` only affects the direct fields of the marked object. Nested objects within it will still stay strict unless they are also wrapped with `partialFields()`.
 
 ---
 

package/dist/index.d.mts

@@ -229,77 +229,131 @@ declare function useFieldChecks<TSchema extends z.ZodType, TDiscriminatorKey ext
  */
 type BuiltInObject = Date | RegExp | Map<unknown, unknown> | Set<unknown> | WeakMap<object, unknown> | WeakSet<object> | Promise<unknown> | Error;
 /**
- * Recursively transforms object types for form inputs.
- *
- * - **Primitives** (string, number, boolean): optional → `type | undefined`
- * - **Arrays**: optional → `type[] | undefined`
- * - **Built-in objects** (Date, RegExp, etc.): optional and nullable → `type | null | undefined`
- * - **Plain objects**: optional, nullable, and recursively transformed → `DeepType | null | undefined`
- *
- * This ensures `useWatch` returns correct types at any nesting depth,
- * since form fields are `undefined` until values are set.
+ * Brand symbol for marking objects that should receive recursive partial transformation.
+ * @internal
+ */
+declare const FormInputBrand: unique symbol;
+/**
+ * Branded type to mark objects that should have their direct fields made partial.
+ * Use with {@link partialFields} helper to mark specific schema objects.
  *
  * @example
  * ```typescript
- * type User = { name: string; tags: string[]; profile: { bio: string } };
- * type FormInput = DeepPartialWithNullableObjects<User>;
- * // Evaluates to: { name?: string; tags?: string[]; profile?: { bio?: string } | null; }
+ * // Objects marked with PartialFields will have their direct fields made optional
+ * type MarkedObject = PartialFields<{ name: string; age: number }>;
  * ```
+ */
+type PartialFields<T> = T & {
+    readonly [FormInputBrand]: true;
+};
+/**
+ * Helper function to mark a Zod schema so its direct fields become partial.
+ *
+ * By default, nested objects in form inputs keep their fields strict (only the object
+ * itself becomes nullable). Use this helper to opt-in specific objects to have their
+ * direct fields also become optional.
+ *
+ * **Note:** This only affects the direct fields of the marked object. Nested objects
+ * within it will still stay strict unless they are also wrapped with `partialFields()`.
+ *
+ * **Use cases:**
+ * - Form input fields that users fill in manually (should be partial)
+ * - Objects from selectors/dropdowns should NOT use this (keep strict)
  *
  * @example
- * Type inference with useZodForm
  * ```typescript
- * const schema = z.object({ name: z.string(), age: z.number() });
- * const form = useZodForm({ schema }); // ✅ Works without defaultValues
- * const name = form.watch('name'); // ✅ Correctly typed as string | undefined
+ * import { partialFields } from '@zod-utils/react-hook-form';
+ *
+ * const schema = z.object({
+ *   price: z.number(),
+ *   // User fills in these fields - opt-in to partial
+ *   detail: partialFields(z.object({
+ *     hotel: z.string(),
+ *     nights: z.number(),
+ *   })),
+ *   // Selected from dropdown - stays strict
+ *   agent: z.object({
+ *     name: z.string(),
+ *     fee: z.number(),
+ *   }),
+ * });
+ *
+ * // Result with PartialWithNullableObjects:
+ * // detail.hotel  → string | undefined (partial - user input)
+ * // detail.nights → number | undefined (partial - user input)
+ * // agent.name    → string (strict! - from selector)
+ * // agent.fee     → number (strict! - from selector)
  * ```
+ */
+declare function partialFields<T extends z.ZodType>(schema: T): z.ZodType<PartialFields<z.infer<T>>, PartialFields<z.input<T>>>;
+/**
+ * Transforms object types for form inputs with selective recursion.
+ *
+ * **Default behavior (non-recursive):**
+ * - **Primitives** (string, number, boolean): optional → `type | undefined`
+ * - **Arrays**: optional → `type[] | undefined`
+ * - **Built-in objects** (Date, RegExp, etc.): optional and nullable → `type | null | undefined`
+ * - **Plain objects**: optional and nullable, but nested fields stay **strict** → `{ strictField: type } | null | undefined`
+ *
+ * **Opt-in recursive behavior:**
+ * - Objects marked with {@link partialFields} will have their nested fields recursively transformed
+ *
+ * This ensures objects from selectors/dropdowns keep strict types for their fields,
+ * while form input fields can be partially filled.
  *
  * @example
- * Nested fields are also correctly typed
  * ```typescript
- * const schema = z.object({ profile: z.object({ bio: z.string() }) });
- * const form = useZodForm({ schema });
- * const bio = form.watch('profile.bio'); // ✅ Correctly typed as string | undefined
+ * import { partialFields } from '@zod-utils/react-hook-form';
+ * import { z } from 'zod';
+ *
+ * const schema = z.object({
+ *   price: z.number(),
+ *   detail: partialFields(z.object({ hotel: z.string(), nights: z.number() })),
+ *   agent: z.object({ name: z.string(), fee: z.number() }),
+ * });
+ *
+ * type FormInput = PartialWithNullableObjects<z.infer<typeof schema>>;
+ * // {
+ * //   price?: number;
+ * //   detail?: { hotel?: string; nights?: number } | null;  // Recursive!
+ * //   agent?: { name: string; fee: number } | null;          // Strict nested!
+ * // }
  * ```
  */
-type DeepPartialWithNullableObjects<T> = {
-    [K in keyof T]?: T[K] extends readonly unknown[] ? T[K] : T[K] extends BuiltInObject ? T[K] | null : T[K] extends object ? Simplify<DeepPartialWithNullableObjects<T[K]>> | null : T[K];
+type PartialWithNullableObjects<T> = {
+    [K in keyof T]?: T[K] extends readonly unknown[] ? T[K] : T[K] extends BuiltInObject ? T[K] | null : T[K] extends PartialFields<infer U> ? Simplify<PartialWithNullableObjects<U>> | null : T[K] extends object ? T[K] | null : T[K];
 };
 /**
- * @deprecated Use {@link DeepPartialWithNullableObjects} instead.
- * This alias is kept for backward compatibility.
- */
-type PartialWithNullableObjects<T> = DeepPartialWithNullableObjects<T>;
-/**
- * Recursively makes all fields optional and nullable.
+ * Transforms all fields to be optional and nullable, with selective recursion.
+ *
+ * Similar to {@link PartialWithNullableObjects} but also adds `| null` to primitives and arrays.
  *
+ * **Default behavior (non-recursive):**
  * - **Primitives**: optional and nullable → `type | null | undefined`
  * - **Arrays**: optional and nullable → `type[] | null | undefined`
- * - **Built-in objects** (Date, RegExp, etc.): optional and nullable → `type | null | undefined`
- * - **Plain objects**: optional, nullable, and recursively transformed → `DeepType | null | undefined`
+ * - **Plain objects**: optional and nullable, but nested fields stay **strict**
+ *
+ * **Opt-in recursive behavior:**
+ * - Objects marked with {@link partialFields} will have their nested fields recursively transformed
  *
  * @example
  * ```typescript
  * type User = { name: string; age: number; profile: { bio: string } };
- * type FormInput = DeepPartialWithAllNullables<User>;
- * // { name?: string | null; age?: number | null; profile?: { bio?: string | null } | null; }
+ * type FormInput = PartialWithAllNullables<User>;
+ * // { name?: string | null; age?: number | null; profile?: { bio: string } | null; }
+ * // Note: profile.bio stays strict (string, not string | null | undefined)
  * ```
  */
-type DeepPartialWithAllNullables<T> = {
-    [K in keyof T]?: T[K] extends readonly unknown[] ? T[K] | null : T[K] extends BuiltInObject ? T[K] | null : T[K] extends object ? Simplify<DeepPartialWithAllNullables<T[K]>> | null : T[K] | null;
+type PartialWithAllNullables<T> = {
+    [K in keyof T]?: T[K] extends readonly unknown[] ? T[K] | null : T[K] extends BuiltInObject ? T[K] | null : T[K] extends PartialFields<infer U> ? Simplify<PartialWithAllNullables<U>> | null : T[K] extends object ? T[K] | null : T[K] | null;
 };
-/**
- * @deprecated Use {@link DeepPartialWithAllNullables} instead.
- * This alias is kept for backward compatibility.
- */
-type PartialWithAllNullables<T> = DeepPartialWithAllNullables<T>;
 
 /**
  * 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** (`DeepPartialWithNullableObjects<TOutput>`): Form fields accept `null | undefined` during editing
+ * - **Input type** (`PartialWithNullableObjects<TOutput>`): Form fields accept `null | undefined` during editing
  * - **Output type** (`TOutput`): Validated data matches exact schema type (no `null | undefined`)
  *
  * **Key Benefits:**
@@ -310,7 +364,7 @@ type PartialWithAllNullables<T> = DeepPartialWithAllNullables<T>;
  *
  * @template TInput - The Zod schema input type (accepts nullable/undefined values during form editing)
  * @template TOutput - The Zod schema output type (extends FieldValues)
- * @template TFormInput - The form input type (defaults to DeepPartialWithNullableObjects<TInput>)
+ * @template TFormInput - The form input type (defaults to PartialWithNullableObjects<TInput>)
  * @template TDefaultValues - The type of default values (inferred from usage for better type safety)
  *
  * @param options - Configuration object
@@ -455,12 +509,12 @@ type PartialWithAllNullables<T> = DeepPartialWithAllNullables<T>;
  * }
  * ```
  *
- * @see {@link DeepPartialWithNullableObjects} for the type transformation utility
+ * @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: <TInput extends FieldValues, TOutput extends FieldValues, TFormInput extends DeepPartialWithAllNullables<TInput> = DeepPartialWithNullableObjects<TInput>, TDefaultValues extends Partial<TFormInput> | undefined = undefined>({ schema, zodResolverOptions, ...formOptions }: {
+declare const useZodForm: <TInput extends FieldValues, TOutput extends FieldValues, TFormInput extends PartialWithAllNullables<TInput> = PartialWithNullableObjects<TInput>, TDefaultValues extends Partial<TFormInput> | undefined = undefined>({ schema, zodResolverOptions, ...formOptions }: {
     schema: z.ZodType<TOutput, TInput>;
     defaultValues?: TDefaultValues;
     zodResolverOptions?: Parameters<typeof zodResolver>[1];
@@ -491,4 +545,4 @@ declare function flattenFieldSelector(params?: {
     };
 }): unknown[];
 
-export { type DeepPartialWithAllNullables, type DeepPartialWithNullableObjects, FormSchemaContext, type FormSchemaContextType, type FormSchemaContextValue, FormSchemaProvider, type PartialWithAllNullables, type PartialWithNullableObjects, flattenFieldSelector, isRequiredField, useExtractFieldFromSchema, useFieldChecks, useFormSchema, useIsRequiredField, useZodForm };
+export { FormSchemaContext, type FormSchemaContextType, type FormSchemaContextValue, FormSchemaProvider, type PartialFields, type PartialWithAllNullables, type PartialWithNullableObjects, flattenFieldSelector, isRequiredField, partialFields, useExtractFieldFromSchema, useFieldChecks, useFormSchema, useIsRequiredField, useZodForm };

package/dist/index.d.ts

@@ -229,77 +229,131 @@ declare function useFieldChecks<TSchema extends z.ZodType, TDiscriminatorKey ext
  */
 type BuiltInObject = Date | RegExp | Map<unknown, unknown> | Set<unknown> | WeakMap<object, unknown> | WeakSet<object> | Promise<unknown> | Error;
 /**
- * Recursively transforms object types for form inputs.
- *
- * - **Primitives** (string, number, boolean): optional → `type | undefined`
- * - **Arrays**: optional → `type[] | undefined`
- * - **Built-in objects** (Date, RegExp, etc.): optional and nullable → `type | null | undefined`
- * - **Plain objects**: optional, nullable, and recursively transformed → `DeepType | null | undefined`
- *
- * This ensures `useWatch` returns correct types at any nesting depth,
- * since form fields are `undefined` until values are set.
+ * Brand symbol for marking objects that should receive recursive partial transformation.
+ * @internal
+ */
+declare const FormInputBrand: unique symbol;
+/**
+ * Branded type to mark objects that should have their direct fields made partial.
+ * Use with {@link partialFields} helper to mark specific schema objects.
  *
  * @example
  * ```typescript
- * type User = { name: string; tags: string[]; profile: { bio: string } };
- * type FormInput = DeepPartialWithNullableObjects<User>;
- * // Evaluates to: { name?: string; tags?: string[]; profile?: { bio?: string } | null; }
+ * // Objects marked with PartialFields will have their direct fields made optional
+ * type MarkedObject = PartialFields<{ name: string; age: number }>;
  * ```
+ */
+type PartialFields<T> = T & {
+    readonly [FormInputBrand]: true;
+};
+/**
+ * Helper function to mark a Zod schema so its direct fields become partial.
+ *
+ * By default, nested objects in form inputs keep their fields strict (only the object
+ * itself becomes nullable). Use this helper to opt-in specific objects to have their
+ * direct fields also become optional.
+ *
+ * **Note:** This only affects the direct fields of the marked object. Nested objects
+ * within it will still stay strict unless they are also wrapped with `partialFields()`.
+ *
+ * **Use cases:**
+ * - Form input fields that users fill in manually (should be partial)
+ * - Objects from selectors/dropdowns should NOT use this (keep strict)
  *
  * @example
- * Type inference with useZodForm
  * ```typescript
- * const schema = z.object({ name: z.string(), age: z.number() });
- * const form = useZodForm({ schema }); // ✅ Works without defaultValues
- * const name = form.watch('name'); // ✅ Correctly typed as string | undefined
+ * import { partialFields } from '@zod-utils/react-hook-form';
+ *
+ * const schema = z.object({
+ *   price: z.number(),
+ *   // User fills in these fields - opt-in to partial
+ *   detail: partialFields(z.object({
+ *     hotel: z.string(),
+ *     nights: z.number(),
+ *   })),
+ *   // Selected from dropdown - stays strict
+ *   agent: z.object({
+ *     name: z.string(),
+ *     fee: z.number(),
+ *   }),
+ * });
+ *
+ * // Result with PartialWithNullableObjects:
+ * // detail.hotel  → string | undefined (partial - user input)
+ * // detail.nights → number | undefined (partial - user input)
+ * // agent.name    → string (strict! - from selector)
+ * // agent.fee     → number (strict! - from selector)
  * ```
+ */
+declare function partialFields<T extends z.ZodType>(schema: T): z.ZodType<PartialFields<z.infer<T>>, PartialFields<z.input<T>>>;
+/**
+ * Transforms object types for form inputs with selective recursion.
+ *
+ * **Default behavior (non-recursive):**
+ * - **Primitives** (string, number, boolean): optional → `type | undefined`
+ * - **Arrays**: optional → `type[] | undefined`
+ * - **Built-in objects** (Date, RegExp, etc.): optional and nullable → `type | null | undefined`
+ * - **Plain objects**: optional and nullable, but nested fields stay **strict** → `{ strictField: type } | null | undefined`
+ *
+ * **Opt-in recursive behavior:**
+ * - Objects marked with {@link partialFields} will have their nested fields recursively transformed
+ *
+ * This ensures objects from selectors/dropdowns keep strict types for their fields,
+ * while form input fields can be partially filled.
  *
  * @example
- * Nested fields are also correctly typed
  * ```typescript
- * const schema = z.object({ profile: z.object({ bio: z.string() }) });
- * const form = useZodForm({ schema });
- * const bio = form.watch('profile.bio'); // ✅ Correctly typed as string | undefined
+ * import { partialFields } from '@zod-utils/react-hook-form';
+ * import { z } from 'zod';
+ *
+ * const schema = z.object({
+ *   price: z.number(),
+ *   detail: partialFields(z.object({ hotel: z.string(), nights: z.number() })),
+ *   agent: z.object({ name: z.string(), fee: z.number() }),
+ * });
+ *
+ * type FormInput = PartialWithNullableObjects<z.infer<typeof schema>>;
+ * // {
+ * //   price?: number;
+ * //   detail?: { hotel?: string; nights?: number } | null;  // Recursive!
+ * //   agent?: { name: string; fee: number } | null;          // Strict nested!
+ * // }
  * ```
  */
-type DeepPartialWithNullableObjects<T> = {
-    [K in keyof T]?: T[K] extends readonly unknown[] ? T[K] : T[K] extends BuiltInObject ? T[K] | null : T[K] extends object ? Simplify<DeepPartialWithNullableObjects<T[K]>> | null : T[K];
+type PartialWithNullableObjects<T> = {
+    [K in keyof T]?: T[K] extends readonly unknown[] ? T[K] : T[K] extends BuiltInObject ? T[K] | null : T[K] extends PartialFields<infer U> ? Simplify<PartialWithNullableObjects<U>> | null : T[K] extends object ? T[K] | null : T[K];
 };
 /**
- * @deprecated Use {@link DeepPartialWithNullableObjects} instead.
- * This alias is kept for backward compatibility.
- */
-type PartialWithNullableObjects<T> = DeepPartialWithNullableObjects<T>;
-/**
- * Recursively makes all fields optional and nullable.
+ * Transforms all fields to be optional and nullable, with selective recursion.
+ *
+ * Similar to {@link PartialWithNullableObjects} but also adds `| null` to primitives and arrays.
  *
+ * **Default behavior (non-recursive):**
  * - **Primitives**: optional and nullable → `type | null | undefined`
  * - **Arrays**: optional and nullable → `type[] | null | undefined`
- * - **Built-in objects** (Date, RegExp, etc.): optional and nullable → `type | null | undefined`
- * - **Plain objects**: optional, nullable, and recursively transformed → `DeepType | null | undefined`
+ * - **Plain objects**: optional and nullable, but nested fields stay **strict**
+ *
+ * **Opt-in recursive behavior:**
+ * - Objects marked with {@link partialFields} will have their nested fields recursively transformed
  *
  * @example
  * ```typescript
  * type User = { name: string; age: number; profile: { bio: string } };
- * type FormInput = DeepPartialWithAllNullables<User>;
- * // { name?: string | null; age?: number | null; profile?: { bio?: string | null } | null; }
+ * type FormInput = PartialWithAllNullables<User>;
+ * // { name?: string | null; age?: number | null; profile?: { bio: string } | null; }
+ * // Note: profile.bio stays strict (string, not string | null | undefined)
  * ```
  */
-type DeepPartialWithAllNullables<T> = {
-    [K in keyof T]?: T[K] extends readonly unknown[] ? T[K] | null : T[K] extends BuiltInObject ? T[K] | null : T[K] extends object ? Simplify<DeepPartialWithAllNullables<T[K]>> | null : T[K] | null;
+type PartialWithAllNullables<T> = {
+    [K in keyof T]?: T[K] extends readonly unknown[] ? T[K] | null : T[K] extends BuiltInObject ? T[K] | null : T[K] extends PartialFields<infer U> ? Simplify<PartialWithAllNullables<U>> | null : T[K] extends object ? T[K] | null : T[K] | null;
 };
-/**
- * @deprecated Use {@link DeepPartialWithAllNullables} instead.
- * This alias is kept for backward compatibility.
- */
-type PartialWithAllNullables<T> = DeepPartialWithAllNullables<T>;
 
 /**
  * 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** (`DeepPartialWithNullableObjects<TOutput>`): Form fields accept `null | undefined` during editing
+ * - **Input type** (`PartialWithNullableObjects<TOutput>`): Form fields accept `null | undefined` during editing
  * - **Output type** (`TOutput`): Validated data matches exact schema type (no `null | undefined`)
  *
  * **Key Benefits:**
@@ -310,7 +364,7 @@ type PartialWithAllNullables<T> = DeepPartialWithAllNullables<T>;
  *
  * @template TInput - The Zod schema input type (accepts nullable/undefined values during form editing)
  * @template TOutput - The Zod schema output type (extends FieldValues)
- * @template TFormInput - The form input type (defaults to DeepPartialWithNullableObjects<TInput>)
+ * @template TFormInput - The form input type (defaults to PartialWithNullableObjects<TInput>)
  * @template TDefaultValues - The type of default values (inferred from usage for better type safety)
  *
  * @param options - Configuration object
@@ -455,12 +509,12 @@ type PartialWithAllNullables<T> = DeepPartialWithAllNullables<T>;
  * }
  * ```
  *
- * @see {@link DeepPartialWithNullableObjects} for the type transformation utility
+ * @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: <TInput extends FieldValues, TOutput extends FieldValues, TFormInput extends DeepPartialWithAllNullables<TInput> = DeepPartialWithNullableObjects<TInput>, TDefaultValues extends Partial<TFormInput> | undefined = undefined>({ schema, zodResolverOptions, ...formOptions }: {
+declare const useZodForm: <TInput extends FieldValues, TOutput extends FieldValues, TFormInput extends PartialWithAllNullables<TInput> = PartialWithNullableObjects<TInput>, TDefaultValues extends Partial<TFormInput> | undefined = undefined>({ schema, zodResolverOptions, ...formOptions }: {
     schema: z.ZodType<TOutput, TInput>;
     defaultValues?: TDefaultValues;
     zodResolverOptions?: Parameters<typeof zodResolver>[1];
@@ -491,4 +545,4 @@ declare function flattenFieldSelector(params?: {
     };
 }): unknown[];
 
-export { type DeepPartialWithAllNullables, type DeepPartialWithNullableObjects, FormSchemaContext, type FormSchemaContextType, type FormSchemaContextValue, FormSchemaProvider, type PartialWithAllNullables, type PartialWithNullableObjects, flattenFieldSelector, isRequiredField, useExtractFieldFromSchema, useFieldChecks, useFormSchema, useIsRequiredField, useZodForm };
+export { FormSchemaContext, type FormSchemaContextType, type FormSchemaContextValue, FormSchemaProvider, type PartialFields, type PartialWithAllNullables, type PartialWithNullableObjects, flattenFieldSelector, isRequiredField, partialFields, useExtractFieldFromSchema, useFieldChecks, useFormSchema, useIsRequiredField, useZodForm };

package/dist/index.js

@@ -89,6 +89,11 @@ function useFieldChecks(params) {
     return core.getFieldChecks(field);
   }, [...flattenFieldSelector(params)]);
 }
+
+// src/types.ts
+function partialFields(schema) {
+  return schema;
+}
 var useZodForm = (_a) => {
   var _b = _a, {
     schema,
@@ -107,6 +112,7 @@ exports.FormSchemaContext = FormSchemaContext;
 exports.FormSchemaProvider = FormSchemaProvider;
 exports.flattenFieldSelector = flattenFieldSelector;
 exports.isRequiredField = isRequiredField;
+exports.partialFields = partialFields;
 exports.useExtractFieldFromSchema = useExtractFieldFromSchema;
 exports.useFieldChecks = useFieldChecks;
 exports.useFormSchema = useFormSchema;

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/utils.ts","../src/context.tsx","../src/use-zod-form.ts"],"names":["createContext","useContext","jsx","useMemo","extractFieldFromSchema","requiresValidInput","getFieldChecks","zodResolver","useForm"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkBO,SAAS,qBAAqB,MAAA,EAIlC;AAtBH,EAAA,IAAA,EAAA,EAAA,EAAA;AAuBE,EAAA,OAAO;AAAA,IACL,MAAA,IAAA,IAAA,GAAA,MAAA,GAAA,MAAA,CAAQ,MAAA;AAAA,IACR,MAAA,IAAA,IAAA,GAAA,MAAA,GAAA,MAAA,CAAQ,IAAA;AAAA,IAAA,CACR,EAAA,GAAA,MAAA,IAAA,IAAA,GAAA,MAAA,GAAA,MAAA,CAAQ,kBAAR,IAAA,GAAA,MAAA,GAAA,EAAA,CAAuB,GAAA;AAAA,IAAA,CACvB,EAAA,GAAA,MAAA,IAAA,IAAA,GAAA,MAAA,GAAA,MAAA,CAAQ,kBAAR,IAAA,GAAA,MAAA,GAAA,EAAA,CAAuB;AAAA,GACzB;AACF;AC0BO,IAAM,iBAAA,GAAoBA,oBAMvB,IAAI;AA6BP,SAAS,cAUd,OAAA,EAKyE;AAKzE,EAAA,OAAOC,iBAAW,iBAAiB,CAAA;AAKrC;AAqCO,SAAS,kBAAA,CAId;AAAA,EACA,MAAA;AAAA,EACA,aAAA;AAAA,EACA;AACF,CAAA,EAI6B;AAC3B,EAAA,uBACEC,cAAA,CAAC,kBAAkB,QAAA,EAAlB,EAA2B,OAAO,EAAE,MAAA,EAAQ,aAAA,EAAc,EACxD,QAAA,EACH,CAAA;AAEJ;AAwBO,SAAS,mBAUd,MAAA,EASS;AAET,EAAA,OAAOC,cAAQ,MAAM;AACnB,IAAA,IAAI,CAAC,MAAA,EAAQ;AACX,MAAA,OAAO,KAAA;AAAA,IACT;AACA,IAAA,OAAO,gBAAgB,MAAM,CAAA;AAAA,EAC/B,GAAG,CAAC,GAAG,oBAAA,CAAqB,MAAM,CAAC,CAAC,CAAA;AACtC;AA2CO,SAAS,gBAUd,MAAA,EAOS;AACT,EAAA,MAAM,KAAA,GAAQC,4BAAuB,MAAM,CAAA;AAE3C,EAAA,IAAI,CAAC,KAAA,EAAO;AACV,IAAA,OAAO,KAAA;AAAA,EACT;AAEA,EAAA,OAAOC,wBAAmB,KAAK,CAAA;AACjC;AAuCO,SAAS,0BAUd,MAAA,EASuB;AAEvB,EAAA,OAAOF,cAAQ,MAAM;AACnB,IAAA,IAAI,CAAC,MAAA,EAAQ;AACX,MAAA,OAAO,MAAA;AAAA,IACT;AACA,IAAA,OAAOC,4BAAuB,MAAM,CAAA;AAAA,EACtC,GAAG,CAAC,GAAG,oBAAA,CAAqB,MAAM,CAAC,CAAC,CAAA;AACtC;AAwBO,SAAS,eAUd,MAAA,EASiB;AAEjB,EAAA,OAAOD,cAAQ,MAAM;AACnB,IAAA,IAAI,CAAC,MAAA,EAAQ;AACX,MAAA,OAAO,EAAC;AAAA,IACV;AAEA,IAAA,MAAM,KAAA,GAAQC,4BAAuB,MAAM,CAAA;AAC3C,IAAA,IAAI,CAAC,KAAA,EAAO,OAAO,EAAC;AACpB,IAAA,OAAOE,oBAAe,KAAK,CAAA;AAAA,EAC7B,GAAG,CAAC,GAAG,oBAAA,CAAqB,MAAM,CAAC,CAAC,CAAA;AACtC;AC3OO,IAAM,UAAA,GAAa,CAMxB,EAAA,KAWI;AAXJ,EAAA,IAAA,EAAA,GAAA,EAAA,EACA;AAAA,IAAA,MAAA;AAAA,IACA;AAAA,GAtLF,GAoLE,EAAA,EAGG,WAAA,GAAA,SAAA,CAHH,EAAA,EAGG;AAAA,IAFH,QAAA;AAAA,IACA;AAAA,GAAA,CAAA;AAUA,EAAA,MAAM,QAAA,GAAWC,eAAA,CAAY,MAAA,EAAQ,kBAAkB,CAAA;AAGvD,EAAA,OAAOC,qBAAA,CAAQ,cAAA,CAAA;AAAA,IACb;AAAA,GAAA,EACG,WAAA,CACqD,CAAA;AAC5D","file":"index.js","sourcesContent":["import type { z } from 'zod';\n\n/**\n * Flattens a FieldSelector into an array of primitive values for use in React dependency arrays.\n *\n * This is useful for `useMemo` and `useCallback` dependencies where you want to avoid\n * re-running when object references change but values stay the same.\n *\n * @param params - The FieldSelector containing schema, name, and optional discriminator\n * @returns An array of primitive values suitable for React dependency arrays\n *\n * @example\n * ```tsx\n * const memoizedValue = useMemo(() => {\n *   return extractFieldFromSchema(params);\n * }, flattenFieldSelector(params));\n * ```\n */\nexport function flattenFieldSelector(params?: {\n  schema?: z.ZodType;\n  name?: string;\n  discriminator?: { key: unknown; value: unknown };\n}) {\n  return [\n    params?.schema,\n    params?.name,\n    params?.discriminator?.key,\n    params?.discriminator?.value,\n  ];\n}\n","'use client';\n\nimport {\n  type DiscriminatorKey,\n  type DiscriminatorValue,\n  extractFieldFromSchema,\n  type FieldSelectorProps,\n  getFieldChecks,\n  requiresValidInput,\n  type SchemaAndDiscriminatorProps,\n  type ZodUnionCheck,\n} from '@zod-utils/core';\nimport {\n  type Context,\n  createContext,\n  type ReactNode,\n  useContext,\n  useMemo,\n} from 'react';\nimport type { z } from 'zod';\nimport { flattenFieldSelector } from './utils';\n\n/**\n * Type for the FormSchemaContext with full generic support.\n * @internal\n */\nexport type FormSchemaContextType<\n  TSchema extends z.ZodType,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema>,\n  TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>,\n> = Context<SchemaAndDiscriminatorProps<\n  TSchema,\n  TDiscriminatorKey,\n  TDiscriminatorValue\n> | null>;\n\n/**\n * Context value type for FormSchemaContext.\n */\nexport type FormSchemaContextValue<\n  TSchema extends z.ZodType,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema>,\n  TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>,\n> = SchemaAndDiscriminatorProps<\n  TSchema,\n  TDiscriminatorKey,\n  TDiscriminatorValue\n> | null;\n\n/**\n * React Context for providing Zod schema to form components.\n *\n * Use with {@link FormSchemaProvider} to provide schema context, and\n * {@link useFormSchema} to consume it in child components.\n */\nexport const FormSchemaContext = createContext<{\n  schema: z.ZodType;\n  discriminator?: {\n    key: unknown;\n    value: unknown;\n  };\n} | null>(null);\n\n/**\n * Hook to access the form schema from context.\n *\n * The optional `_params` argument is used for TypeScript type inference only.\n * Pass your schema to get proper type narrowing of the context value.\n *\n * @param _params - Optional params for type inference (not used at runtime)\n * @returns The schema context value or null if not within a provider\n *\n * @example\n * ```tsx\n * // Without type params (returns generic context)\n * function MyFormField() {\n *   const context = useFormSchema();\n *   if (!context) return null;\n *\n *   const { schema, discriminator } = context;\n *   // Use schema for validation or field extraction\n * }\n *\n * // With type params (for type-safe schema access)\n * function TypedFormField() {\n *   const context = useFormSchema({ schema: mySchema });\n *   // context.schema is now typed as typeof mySchema\n * }\n * ```\n */\nexport function useFormSchema<\n  TSchema extends z.ZodType = z.ZodType,\n  TDiscriminatorKey extends\n    DiscriminatorKey<TSchema> = DiscriminatorKey<TSchema>,\n  TDiscriminatorValue extends DiscriminatorValue<\n    TSchema,\n    TDiscriminatorKey\n  > = DiscriminatorValue<TSchema, TDiscriminatorKey>,\n>(\n  // Parameter used for type inference only, not at runtime\n  _params?: SchemaAndDiscriminatorProps<\n    TSchema,\n    TDiscriminatorKey,\n    TDiscriminatorValue\n  >,\n): FormSchemaContextValue<TSchema, TDiscriminatorKey, TDiscriminatorValue> {\n  // Type assertion is necessary because React context is created with a generic type,\n  // but we want to return a narrower type based on the generic parameters.\n  // The caller is responsible for ensuring type safety via the _params argument.\n  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n  return useContext(FormSchemaContext) as FormSchemaContextValue<\n    TSchema,\n    TDiscriminatorKey,\n    TDiscriminatorValue\n  >;\n}\n\n/**\n * Provider component that makes Zod schema available to all child components.\n *\n * Use this to wrap your form and provide schema context to nested components\n * like field labels and validation indicators.\n *\n * @example\n * Basic usage with ZodObject\n * ```tsx\n * const schema = z.object({\n *   name: z.string(),\n *   email: z.string().email().optional()\n * });\n *\n * <FormSchemaProvider schema={schema}>\n *   <YourFormComponents />\n * </FormSchemaProvider>\n * ```\n *\n * @example\n * Usage with discriminated union\n * ```tsx\n * const schema = z.discriminatedUnion('mode', [\n *   z.object({ mode: z.literal('create'), name: z.string() }),\n *   z.object({ mode: z.literal('edit'), id: z.number() })\n * ]);\n *\n * <FormSchemaProvider\n *   schema={schema}\n *   discriminator={{ key: 'mode', value: 'create' }}\n * >\n *   <YourFormComponents />\n * </FormSchemaProvider>\n * ```\n */\nexport function FormSchemaProvider<\n  TSchema extends z.ZodType,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema>,\n  TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>,\n>({\n  schema,\n  discriminator,\n  children,\n}: SchemaAndDiscriminatorProps<\n  TSchema,\n  TDiscriminatorKey,\n  TDiscriminatorValue\n> & { children: ReactNode }) {\n  return (\n    <FormSchemaContext.Provider value={{ schema, discriminator }}>\n      {children}\n    </FormSchemaContext.Provider>\n  );\n}\n\n/**\n * Hook to check if a field requires valid input based on the Zod schema.\n *\n * Memoized - only recalculates when schema, name, or discriminator changes.\n *\n * @param params - Schema, name, and optional discriminator\n * @returns true if the field requires valid input, false otherwise\n *\n * @example\n * ```tsx\n * function MyFieldLabel({ name, schema }: { name: string; schema: z.ZodType }) {\n *   const isRequired = useIsRequiredField({ schema, name });\n *\n *   return (\n *     <label>\n *       {name}\n *       {isRequired && <span className=\"text-red-500\">*</span>}\n *     </label>\n *   );\n * }\n * ```\n */\nexport function useIsRequiredField<\n  TSchema extends z.ZodType,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema> = never,\n  TDiscriminatorValue extends DiscriminatorValue<\n    TSchema,\n    TDiscriminatorKey\n  > = never,\n  TFilterType = unknown,\n  TStrict extends boolean = true,\n>(\n  params:\n    | FieldSelectorProps<\n        TSchema,\n        TDiscriminatorKey,\n        TDiscriminatorValue,\n        TFilterType,\n        TStrict\n      >\n    | undefined,\n): boolean {\n  // biome-ignore lint/correctness/useExhaustiveDependencies: using flattenFieldSelector for stable deps\n  return useMemo(() => {\n    if (!params) {\n      return false;\n    }\n    return isRequiredField(params);\n  }, [...flattenFieldSelector(params)]);\n}\n\n/**\n * Determines if a field requires valid input (will show validation errors on empty/invalid input).\n *\n * Uses `requiresValidInput` from `@zod-utils/core` which checks the underlying field after\n * removing defaults. This tells you if the field will error when user submits empty input.\n *\n * Returns false if the underlying field accepts:\n * - `undefined` (via `.optional()`)\n * - `null` (via `.nullable()`)\n * - Empty strings (plain `z.string()` without `.min(1)`)\n * - Empty arrays (plain `z.array()` without `.min(1)`)\n *\n * @param options - Schema, field name, and optional discriminator\n * @returns true if the field requires valid input, false otherwise\n *\n * @example\n * ```typescript\n * const schema = z.object({\n *   name: z.string().min(1),\n *   bio: z.string().optional(),\n * });\n *\n * isRequiredField({ schema, name: 'name' }); // true\n * isRequiredField({ schema, name: 'bio' });  // false\n * ```\n *\n * @example\n * With discriminated union\n * ```typescript\n * const schema = z.discriminatedUnion('mode', [\n *   z.object({ mode: z.literal('create'), name: z.string().min(1) }),\n *   z.object({ mode: z.literal('edit'), id: z.number() }),\n * ]);\n *\n * isRequiredField({\n *   schema,\n *   name: 'name',\n *   discriminator: { key: 'mode', value: 'create' },\n * }); // true\n * ```\n */\nexport function isRequiredField<\n  TSchema extends z.ZodType,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema> = never,\n  TDiscriminatorValue extends DiscriminatorValue<\n    TSchema,\n    TDiscriminatorKey\n  > = never,\n  TFilterType = unknown,\n  TStrict extends boolean = true,\n>(\n  params: FieldSelectorProps<\n    TSchema,\n    TDiscriminatorKey,\n    TDiscriminatorValue,\n    TFilterType,\n    TStrict\n  >,\n): boolean {\n  const field = extractFieldFromSchema(params);\n\n  if (!field) {\n    return false;\n  }\n\n  return requiresValidInput(field);\n}\n\n/**\n * React hook to extract a field's Zod schema from a parent schema.\n *\n * Memoized - only recalculates when schema, name, or discriminator changes.\n * Supports nested paths and discriminated unions.\n *\n * @param params - Schema, name, and optional discriminator\n * @returns The Zod schema for the field, or undefined if not found\n *\n * @example\n * ```tsx\n * function MyFieldInfo({ name, schema }: { name: string; schema: z.ZodType }) {\n *   const fieldSchema = useExtractFieldFromSchema({ schema, name });\n *\n *   if (!fieldSchema) return null;\n *\n *   // Use fieldSchema for custom validation or field info\n *   return <span>{fieldSchema._zod.typeName}</span>;\n * }\n * ```\n *\n * @example\n * With discriminated union\n * ```tsx\n * const schema = z.discriminatedUnion('mode', [\n *   z.object({ mode: z.literal('create'), name: z.string() }),\n *   z.object({ mode: z.literal('edit'), id: z.number() }),\n * ]);\n *\n * const fieldSchema = useExtractFieldFromSchema({\n *   schema,\n *   name: 'name',\n *   discriminator: { key: 'mode', value: 'create' },\n * });\n * // Returns z.string() schema\n * ```\n */\nexport function useExtractFieldFromSchema<\n  TSchema extends z.ZodType,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema> = never,\n  TDiscriminatorValue extends DiscriminatorValue<\n    TSchema,\n    TDiscriminatorKey\n  > = never,\n  TFilterType = unknown,\n  TStrict extends boolean = true,\n>(\n  params:\n    | FieldSelectorProps<\n        TSchema,\n        TDiscriminatorKey,\n        TDiscriminatorValue,\n        TFilterType,\n        TStrict\n      >\n    | undefined,\n): z.ZodType | undefined {\n  // biome-ignore lint/correctness/useExhaustiveDependencies: using flattenFieldSelector for stable deps\n  return useMemo(() => {\n    if (!params) {\n      return undefined;\n    }\n    return extractFieldFromSchema(params);\n  }, [...flattenFieldSelector(params)]);\n}\n\n/**\n * Hook to get validation checks from a field's Zod schema.\n *\n * Memoized - only recalculates when schema, name, or discriminator changes.\n * Combines field extraction and check retrieval in one cached operation.\n *\n * @param params - Schema, name, and optional discriminator\n * @returns Array of validation checks (min, max, pattern, etc.) or empty array\n *\n * @example\n * ```tsx\n * function MyFieldHint({ schema, name }: { schema: z.ZodType; name: string }) {\n *   const checks = useFieldChecks({ schema, name });\n *\n *   const maxLength = checks.find(c => c.check === 'max_length');\n *   if (maxLength) {\n *     return <span>Max {maxLength.maximum} characters</span>;\n *   }\n *   return null;\n * }\n * ```\n */\nexport function useFieldChecks<\n  TSchema extends z.ZodType,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema> = never,\n  TDiscriminatorValue extends DiscriminatorValue<\n    TSchema,\n    TDiscriminatorKey\n  > = never,\n  TFilterType = unknown,\n  TStrict extends boolean = true,\n>(\n  params:\n    | FieldSelectorProps<\n        TSchema,\n        TDiscriminatorKey,\n        TDiscriminatorValue,\n        TFilterType,\n        TStrict\n      >\n    | undefined,\n): ZodUnionCheck[] {\n  // biome-ignore lint/correctness/useExhaustiveDependencies: using flattenFieldSelector for stable deps\n  return useMemo(() => {\n    if (!params) {\n      return [];\n    }\n\n    const field = extractFieldFromSchema(params);\n    if (!field) return [];\n    return getFieldChecks(field);\n  }, [...flattenFieldSelector(params)]);\n}\n","import { zodResolver } from '@hookform/resolvers/zod';\nimport { type FieldValues, type UseFormProps, useForm } from 'react-hook-form';\nimport type { z } from 'zod';\nimport type {\n  DeepPartialWithAllNullables,\n  DeepPartialWithNullableObjects,\n} from './types';\n\n/**\n * Type-safe React Hook Form wrapper with automatic Zod v4 schema validation and type transformation.\n *\n * This hook eliminates the TypeScript friction between React Hook Form's nullable field values\n * and Zod's strict output types. It uses a two-type schema pattern where:\n * - **Input type** (`DeepPartialWithNullableObjects<TOutput>`): Form fields accept `null | undefined` during editing\n * - **Output type** (`TOutput`): Validated data matches exact schema type (no `null | undefined`)\n *\n * **Key Benefits:**\n * - ✅ No more \"Type 'null' is not assignable to...\" TypeScript errors\n * - ✅ Use `form.setValue()` and `form.reset()` with `null` values freely\n * - ✅ Validated output is still type-safe with exact Zod schema types\n * - ✅ Automatic zodResolver setup - no manual configuration needed\n *\n * @template TInput - The Zod schema input type (accepts nullable/undefined values during form editing)\n * @template TOutput - The Zod schema output type (extends FieldValues)\n * @template TFormInput - The form input type (defaults to DeepPartialWithNullableObjects<TInput>)\n * @template TDefaultValues - The type of default values (inferred from usage for better type safety)\n *\n * @param options - Configuration object\n * @param options.schema - Zod schema with two-type signature `z.ZodType<TOutput, TInput>`\n * @param options.defaultValues - Default form values (shallow partial - nested objects must be complete if provided)\n * @param options.zodResolverOptions - Optional zodResolver configuration\n * @param options....formOptions - All other react-hook-form useForm options\n *\n * @returns React Hook Form instance with type-safe methods\n *\n * @example\n * Basic usage with required fields\n * ```typescript\n * import { useZodForm } from '@zod-utils/react-hook-form';\n * import { z } from 'zod';\n *\n * const schema = z.object({\n *   name: z.string().min(1), // Required field\n *   age: z.number().min(0),\n * }) satisfies z.ZodType<{ name: string; age: number }, any>;\n *\n * function MyForm() {\n *   const form = useZodForm({ schema });\n *\n *   // ✅ These work without type errors:\n *   form.setValue('name', null); // Accepts null during editing\n *   form.reset({ name: null, age: null }); // Reset with null\n *\n *   const onSubmit = (data: { name: string; age: number }) => {\n *     // ✅ data is exact type - no null | undefined\n *     console.log(data.name.toUpperCase()); // Safe to use string methods\n *   };\n *\n *   return <form onSubmit={form.handleSubmit(onSubmit)}>...</form>;\n * }\n * ```\n *\n * @example\n * With default values\n * ```typescript\n * const schema = z.object({\n *   username: z.string(),\n *   email: z.string().email(),\n *   notifications: z.boolean().default(true),\n * }) satisfies z.ZodType<{\n *   username: string;\n *   email: string;\n *   notifications: boolean;\n * }, any>;\n *\n * const form = useZodForm({\n *   schema,\n *   defaultValues: {\n *     username: '',\n *     email: '',\n *     // notifications gets default from schema\n *   },\n * });\n * ```\n *\n * @example\n * Without default values (all fields are optional during editing)\n * ```typescript\n * const schema = z.object({\n *   name: z.string().min(1),\n *   email: z.string().email(),\n *   age: z.number(),\n * }) satisfies z.ZodType<{ name: string; email: string; age: number }, any>;\n *\n * // ✅ No defaultValues needed - fields are optional during editing\n * const form = useZodForm({ schema });\n *\n * // Form fields can be set individually as user types\n * form.setValue('name', 'John');\n * form.setValue('email', 'john@example.com');\n * form.setValue('age', 25);\n *\n * // All fields must be valid on submit (per schema validation)\n * ```\n *\n * @example\n * With optional and nullable fields\n * ```typescript\n * const schema = z.object({\n *   title: z.string(),\n *   description: z.string().optional(), // Optional in output\n *   tags: z.array(z.string()).nullable(), // Nullable in output\n * }) satisfies z.ZodType<{\n *   title: string;\n *   description?: string;\n *   tags: string[] | null;\n * }, any>;\n *\n * const form = useZodForm({ schema });\n *\n * // All fields accept null/undefined during editing\n * form.setValue('title', null);\n * form.setValue('description', undefined);\n * form.setValue('tags', null);\n * ```\n *\n * @example\n * With zodResolver options\n * ```typescript\n * const form = useZodForm({\n *   schema,\n *   zodResolverOptions: {\n *     async: true, // Enable async validation\n *     errorMap: customErrorMap, // Custom error messages\n *   },\n * });\n * ```\n *\n * @example\n * Complete form example\n * ```typescript\n * const userSchema = z.object({\n *   name: z.string().min(1, 'Name is required'),\n *   email: z.string().email('Invalid email'),\n *   age: z.number().min(18, 'Must be 18+'),\n * }) satisfies z.ZodType<{ name: string; email: string; age: number }, any>;\n *\n * function UserForm() {\n *   const form = useZodForm({\n *     schema: userSchema,\n *     defaultValues: { name: '', email: '', age: null },\n *   });\n *\n *   const onSubmit = (data: { name: string; email: string; age: number }) => {\n *     // Type-safe: data has exact types, no null/undefined\n *     console.log(`${data.name} is ${data.age} years old`);\n *   };\n *\n *   return (\n *     <form onSubmit={form.handleSubmit(onSubmit)}>\n *       <input {...form.register('name')} />\n *       <input {...form.register('email')} type=\"email\" />\n *       <input {...form.register('age', { valueAsNumber: true })} type=\"number\" />\n *       <button type=\"submit\">Submit</button>\n *     </form>\n *   );\n * }\n * ```\n *\n * @see {@link DeepPartialWithNullableObjects} for the type transformation utility\n * @see https://react-hook-form.com/docs/useform for React Hook Form documentation\n * @see https://zod.dev for Zod schema documentation\n * @since 0.1.0\n */\nexport const useZodForm = <\n  TInput extends FieldValues,\n  TOutput extends FieldValues,\n  TFormInput extends\n    DeepPartialWithAllNullables<TInput> = DeepPartialWithNullableObjects<TInput>,\n  TDefaultValues extends Partial<TFormInput> | undefined = undefined,\n>({\n  schema,\n  zodResolverOptions,\n  ...formOptions\n}: {\n  schema: z.ZodType<TOutput, TInput>;\n  defaultValues?: TDefaultValues;\n  zodResolverOptions?: Parameters<typeof zodResolver>[1];\n} & Omit<\n  UseFormProps<TFormInput, unknown, TOutput>,\n  'resolver' | 'defaultValues'\n>) => {\n  const resolver = zodResolver(schema, zodResolverOptions);\n\n  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n  return useForm({\n    resolver,\n    ...formOptions,\n  } as unknown as UseFormProps<TFormInput, unknown, TOutput>);\n};\n"]}
+{"version":3,"sources":["../src/utils.ts","../src/context.tsx","../src/types.ts","../src/use-zod-form.ts"],"names":["createContext","useContext","jsx","useMemo","extractFieldFromSchema","requiresValidInput","getFieldChecks","zodResolver","useForm"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkBO,SAAS,qBAAqB,MAAA,EAIlC;AAtBH,EAAA,IAAA,EAAA,EAAA,EAAA;AAuBE,EAAA,OAAO;AAAA,IACL,MAAA,IAAA,IAAA,GAAA,MAAA,GAAA,MAAA,CAAQ,MAAA;AAAA,IACR,MAAA,IAAA,IAAA,GAAA,MAAA,GAAA,MAAA,CAAQ,IAAA;AAAA,IAAA,CACR,EAAA,GAAA,MAAA,IAAA,IAAA,GAAA,MAAA,GAAA,MAAA,CAAQ,kBAAR,IAAA,GAAA,MAAA,GAAA,EAAA,CAAuB,GAAA;AAAA,IAAA,CACvB,EAAA,GAAA,MAAA,IAAA,IAAA,GAAA,MAAA,GAAA,MAAA,CAAQ,kBAAR,IAAA,GAAA,MAAA,GAAA,EAAA,CAAuB;AAAA,GACzB;AACF;AC0BO,IAAM,iBAAA,GAAoBA,oBAMvB,IAAI;AA6BP,SAAS,cAUd,OAAA,EAKyE;AAKzE,EAAA,OAAOC,iBAAW,iBAAiB,CAAA;AAKrC;AAqCO,SAAS,kBAAA,CAId;AAAA,EACA,MAAA;AAAA,EACA,aAAA;AAAA,EACA;AACF,CAAA,EAI6B;AAC3B,EAAA,uBACEC,cAAA,CAAC,kBAAkB,QAAA,EAAlB,EAA2B,OAAO,EAAE,MAAA,EAAQ,aAAA,EAAc,EACxD,QAAA,EACH,CAAA;AAEJ;AAwBO,SAAS,mBAUd,MAAA,EASS;AAET,EAAA,OAAOC,cAAQ,MAAM;AACnB,IAAA,IAAI,CAAC,MAAA,EAAQ;AACX,MAAA,OAAO,KAAA;AAAA,IACT;AACA,IAAA,OAAO,gBAAgB,MAAM,CAAA;AAAA,EAC/B,GAAG,CAAC,GAAG,oBAAA,CAAqB,MAAM,CAAC,CAAC,CAAA;AACtC;AA2CO,SAAS,gBAUd,MAAA,EAOS;AACT,EAAA,MAAM,KAAA,GAAQC,4BAAuB,MAAM,CAAA;AAE3C,EAAA,IAAI,CAAC,KAAA,EAAO;AACV,IAAA,OAAO,KAAA;AAAA,EACT;AAEA,EAAA,OAAOC,wBAAmB,KAAK,CAAA;AACjC;AAuCO,SAAS,0BAUd,MAAA,EASuB;AAEvB,EAAA,OAAOF,cAAQ,MAAM;AACnB,IAAA,IAAI,CAAC,MAAA,EAAQ;AACX,MAAA,OAAO,MAAA;AAAA,IACT;AACA,IAAA,OAAOC,4BAAuB,MAAM,CAAA;AAAA,EACtC,GAAG,CAAC,GAAG,oBAAA,CAAqB,MAAM,CAAC,CAAC,CAAA;AACtC;AAwBO,SAAS,eAUd,MAAA,EASiB;AAEjB,EAAA,OAAOD,cAAQ,MAAM;AACnB,IAAA,IAAI,CAAC,MAAA,EAAQ;AACX,MAAA,OAAO,EAAC;AAAA,IACV;AAEA,IAAA,MAAM,KAAA,GAAQC,4BAAuB,MAAM,CAAA;AAC3C,IAAA,IAAI,CAAC,KAAA,EAAO,OAAO,EAAC;AACpB,IAAA,OAAOE,oBAAe,KAAK,CAAA;AAAA,EAC7B,GAAG,CAAC,GAAG,oBAAA,CAAqB,MAAM,CAAC,CAAC,CAAA;AACtC;;;AC9UO,SAAS,cACd,MAAA,EACiE;AAEjE,EAAA,OAAO,MAAA;AAIT;AC2FO,IAAM,UAAA,GAAa,CAMxB,EAAA,KAWI;AAXJ,EAAA,IAAA,EAAA,GAAA,EAAA,EACA;AAAA,IAAA,MAAA;AAAA,IACA;AAAA,GAtLF,GAoLE,EAAA,EAGG,WAAA,GAAA,SAAA,CAHH,EAAA,EAGG;AAAA,IAFH,QAAA;AAAA,IACA;AAAA,GAAA,CAAA;AAUA,EAAA,MAAM,QAAA,GAAWC,eAAA,CAAY,MAAA,EAAQ,kBAAkB,CAAA;AAGvD,EAAA,OAAOC,qBAAA,CAAQ,cAAA,CAAA;AAAA,IACb;AAAA,GAAA,EACG,WAAA,CACqD,CAAA;AAC5D","file":"index.js","sourcesContent":["import type { z } from 'zod';\n\n/**\n * Flattens a FieldSelector into an array of primitive values for use in React dependency arrays.\n *\n * This is useful for `useMemo` and `useCallback` dependencies where you want to avoid\n * re-running when object references change but values stay the same.\n *\n * @param params - The FieldSelector containing schema, name, and optional discriminator\n * @returns An array of primitive values suitable for React dependency arrays\n *\n * @example\n * ```tsx\n * const memoizedValue = useMemo(() => {\n *   return extractFieldFromSchema(params);\n * }, flattenFieldSelector(params));\n * ```\n */\nexport function flattenFieldSelector(params?: {\n  schema?: z.ZodType;\n  name?: string;\n  discriminator?: { key: unknown; value: unknown };\n}) {\n  return [\n    params?.schema,\n    params?.name,\n    params?.discriminator?.key,\n    params?.discriminator?.value,\n  ];\n}\n","'use client';\n\nimport {\n  type DiscriminatorKey,\n  type DiscriminatorValue,\n  extractFieldFromSchema,\n  type FieldSelectorProps,\n  getFieldChecks,\n  requiresValidInput,\n  type SchemaAndDiscriminatorProps,\n  type ZodUnionCheck,\n} from '@zod-utils/core';\nimport {\n  type Context,\n  createContext,\n  type ReactNode,\n  useContext,\n  useMemo,\n} from 'react';\nimport type { z } from 'zod';\nimport { flattenFieldSelector } from './utils';\n\n/**\n * Type for the FormSchemaContext with full generic support.\n * @internal\n */\nexport type FormSchemaContextType<\n  TSchema extends z.ZodType,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema>,\n  TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>,\n> = Context<SchemaAndDiscriminatorProps<\n  TSchema,\n  TDiscriminatorKey,\n  TDiscriminatorValue\n> | null>;\n\n/**\n * Context value type for FormSchemaContext.\n */\nexport type FormSchemaContextValue<\n  TSchema extends z.ZodType,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema>,\n  TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>,\n> = SchemaAndDiscriminatorProps<\n  TSchema,\n  TDiscriminatorKey,\n  TDiscriminatorValue\n> | null;\n\n/**\n * React Context for providing Zod schema to form components.\n *\n * Use with {@link FormSchemaProvider} to provide schema context, and\n * {@link useFormSchema} to consume it in child components.\n */\nexport const FormSchemaContext = createContext<{\n  schema: z.ZodType;\n  discriminator?: {\n    key: unknown;\n    value: unknown;\n  };\n} | null>(null);\n\n/**\n * Hook to access the form schema from context.\n *\n * The optional `_params` argument is used for TypeScript type inference only.\n * Pass your schema to get proper type narrowing of the context value.\n *\n * @param _params - Optional params for type inference (not used at runtime)\n * @returns The schema context value or null if not within a provider\n *\n * @example\n * ```tsx\n * // Without type params (returns generic context)\n * function MyFormField() {\n *   const context = useFormSchema();\n *   if (!context) return null;\n *\n *   const { schema, discriminator } = context;\n *   // Use schema for validation or field extraction\n * }\n *\n * // With type params (for type-safe schema access)\n * function TypedFormField() {\n *   const context = useFormSchema({ schema: mySchema });\n *   // context.schema is now typed as typeof mySchema\n * }\n * ```\n */\nexport function useFormSchema<\n  TSchema extends z.ZodType = z.ZodType,\n  TDiscriminatorKey extends\n    DiscriminatorKey<TSchema> = DiscriminatorKey<TSchema>,\n  TDiscriminatorValue extends DiscriminatorValue<\n    TSchema,\n    TDiscriminatorKey\n  > = DiscriminatorValue<TSchema, TDiscriminatorKey>,\n>(\n  // Parameter used for type inference only, not at runtime\n  _params?: SchemaAndDiscriminatorProps<\n    TSchema,\n    TDiscriminatorKey,\n    TDiscriminatorValue\n  >,\n): FormSchemaContextValue<TSchema, TDiscriminatorKey, TDiscriminatorValue> {\n  // Type assertion is necessary because React context is created with a generic type,\n  // but we want to return a narrower type based on the generic parameters.\n  // The caller is responsible for ensuring type safety via the _params argument.\n  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n  return useContext(FormSchemaContext) as FormSchemaContextValue<\n    TSchema,\n    TDiscriminatorKey,\n    TDiscriminatorValue\n  >;\n}\n\n/**\n * Provider component that makes Zod schema available to all child components.\n *\n * Use this to wrap your form and provide schema context to nested components\n * like field labels and validation indicators.\n *\n * @example\n * Basic usage with ZodObject\n * ```tsx\n * const schema = z.object({\n *   name: z.string(),\n *   email: z.string().email().optional()\n * });\n *\n * <FormSchemaProvider schema={schema}>\n *   <YourFormComponents />\n * </FormSchemaProvider>\n * ```\n *\n * @example\n * Usage with discriminated union\n * ```tsx\n * const schema = z.discriminatedUnion('mode', [\n *   z.object({ mode: z.literal('create'), name: z.string() }),\n *   z.object({ mode: z.literal('edit'), id: z.number() })\n * ]);\n *\n * <FormSchemaProvider\n *   schema={schema}\n *   discriminator={{ key: 'mode', value: 'create' }}\n * >\n *   <YourFormComponents />\n * </FormSchemaProvider>\n * ```\n */\nexport function FormSchemaProvider<\n  TSchema extends z.ZodType,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema>,\n  TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>,\n>({\n  schema,\n  discriminator,\n  children,\n}: SchemaAndDiscriminatorProps<\n  TSchema,\n  TDiscriminatorKey,\n  TDiscriminatorValue\n> & { children: ReactNode }) {\n  return (\n    <FormSchemaContext.Provider value={{ schema, discriminator }}>\n      {children}\n    </FormSchemaContext.Provider>\n  );\n}\n\n/**\n * Hook to check if a field requires valid input based on the Zod schema.\n *\n * Memoized - only recalculates when schema, name, or discriminator changes.\n *\n * @param params - Schema, name, and optional discriminator\n * @returns true if the field requires valid input, false otherwise\n *\n * @example\n * ```tsx\n * function MyFieldLabel({ name, schema }: { name: string; schema: z.ZodType }) {\n *   const isRequired = useIsRequiredField({ schema, name });\n *\n *   return (\n *     <label>\n *       {name}\n *       {isRequired && <span className=\"text-red-500\">*</span>}\n *     </label>\n *   );\n * }\n * ```\n */\nexport function useIsRequiredField<\n  TSchema extends z.ZodType,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema> = never,\n  TDiscriminatorValue extends DiscriminatorValue<\n    TSchema,\n    TDiscriminatorKey\n  > = never,\n  TFilterType = unknown,\n  TStrict extends boolean = true,\n>(\n  params:\n    | FieldSelectorProps<\n        TSchema,\n        TDiscriminatorKey,\n        TDiscriminatorValue,\n        TFilterType,\n        TStrict\n      >\n    | undefined,\n): boolean {\n  // biome-ignore lint/correctness/useExhaustiveDependencies: using flattenFieldSelector for stable deps\n  return useMemo(() => {\n    if (!params) {\n      return false;\n    }\n    return isRequiredField(params);\n  }, [...flattenFieldSelector(params)]);\n}\n\n/**\n * Determines if a field requires valid input (will show validation errors on empty/invalid input).\n *\n * Uses `requiresValidInput` from `@zod-utils/core` which checks the underlying field after\n * removing defaults. This tells you if the field will error when user submits empty input.\n *\n * Returns false if the underlying field accepts:\n * - `undefined` (via `.optional()`)\n * - `null` (via `.nullable()`)\n * - Empty strings (plain `z.string()` without `.min(1)`)\n * - Empty arrays (plain `z.array()` without `.min(1)`)\n *\n * @param options - Schema, field name, and optional discriminator\n * @returns true if the field requires valid input, false otherwise\n *\n * @example\n * ```typescript\n * const schema = z.object({\n *   name: z.string().min(1),\n *   bio: z.string().optional(),\n * });\n *\n * isRequiredField({ schema, name: 'name' }); // true\n * isRequiredField({ schema, name: 'bio' });  // false\n * ```\n *\n * @example\n * With discriminated union\n * ```typescript\n * const schema = z.discriminatedUnion('mode', [\n *   z.object({ mode: z.literal('create'), name: z.string().min(1) }),\n *   z.object({ mode: z.literal('edit'), id: z.number() }),\n * ]);\n *\n * isRequiredField({\n *   schema,\n *   name: 'name',\n *   discriminator: { key: 'mode', value: 'create' },\n * }); // true\n * ```\n */\nexport function isRequiredField<\n  TSchema extends z.ZodType,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema> = never,\n  TDiscriminatorValue extends DiscriminatorValue<\n    TSchema,\n    TDiscriminatorKey\n  > = never,\n  TFilterType = unknown,\n  TStrict extends boolean = true,\n>(\n  params: FieldSelectorProps<\n    TSchema,\n    TDiscriminatorKey,\n    TDiscriminatorValue,\n    TFilterType,\n    TStrict\n  >,\n): boolean {\n  const field = extractFieldFromSchema(params);\n\n  if (!field) {\n    return false;\n  }\n\n  return requiresValidInput(field);\n}\n\n/**\n * React hook to extract a field's Zod schema from a parent schema.\n *\n * Memoized - only recalculates when schema, name, or discriminator changes.\n * Supports nested paths and discriminated unions.\n *\n * @param params - Schema, name, and optional discriminator\n * @returns The Zod schema for the field, or undefined if not found\n *\n * @example\n * ```tsx\n * function MyFieldInfo({ name, schema }: { name: string; schema: z.ZodType }) {\n *   const fieldSchema = useExtractFieldFromSchema({ schema, name });\n *\n *   if (!fieldSchema) return null;\n *\n *   // Use fieldSchema for custom validation or field info\n *   return <span>{fieldSchema._zod.typeName}</span>;\n * }\n * ```\n *\n * @example\n * With discriminated union\n * ```tsx\n * const schema = z.discriminatedUnion('mode', [\n *   z.object({ mode: z.literal('create'), name: z.string() }),\n *   z.object({ mode: z.literal('edit'), id: z.number() }),\n * ]);\n *\n * const fieldSchema = useExtractFieldFromSchema({\n *   schema,\n *   name: 'name',\n *   discriminator: { key: 'mode', value: 'create' },\n * });\n * // Returns z.string() schema\n * ```\n */\nexport function useExtractFieldFromSchema<\n  TSchema extends z.ZodType,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema> = never,\n  TDiscriminatorValue extends DiscriminatorValue<\n    TSchema,\n    TDiscriminatorKey\n  > = never,\n  TFilterType = unknown,\n  TStrict extends boolean = true,\n>(\n  params:\n    | FieldSelectorProps<\n        TSchema,\n        TDiscriminatorKey,\n        TDiscriminatorValue,\n        TFilterType,\n        TStrict\n      >\n    | undefined,\n): z.ZodType | undefined {\n  // biome-ignore lint/correctness/useExhaustiveDependencies: using flattenFieldSelector for stable deps\n  return useMemo(() => {\n    if (!params) {\n      return undefined;\n    }\n    return extractFieldFromSchema(params);\n  }, [...flattenFieldSelector(params)]);\n}\n\n/**\n * Hook to get validation checks from a field's Zod schema.\n *\n * Memoized - only recalculates when schema, name, or discriminator changes.\n * Combines field extraction and check retrieval in one cached operation.\n *\n * @param params - Schema, name, and optional discriminator\n * @returns Array of validation checks (min, max, pattern, etc.) or empty array\n *\n * @example\n * ```tsx\n * function MyFieldHint({ schema, name }: { schema: z.ZodType; name: string }) {\n *   const checks = useFieldChecks({ schema, name });\n *\n *   const maxLength = checks.find(c => c.check === 'max_length');\n *   if (maxLength) {\n *     return <span>Max {maxLength.maximum} characters</span>;\n *   }\n *   return null;\n * }\n * ```\n */\nexport function useFieldChecks<\n  TSchema extends z.ZodType,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema> = never,\n  TDiscriminatorValue extends DiscriminatorValue<\n    TSchema,\n    TDiscriminatorKey\n  > = never,\n  TFilterType = unknown,\n  TStrict extends boolean = true,\n>(\n  params:\n    | FieldSelectorProps<\n        TSchema,\n        TDiscriminatorKey,\n        TDiscriminatorValue,\n        TFilterType,\n        TStrict\n      >\n    | undefined,\n): ZodUnionCheck[] {\n  // biome-ignore lint/correctness/useExhaustiveDependencies: using flattenFieldSelector for stable deps\n  return useMemo(() => {\n    if (!params) {\n      return [];\n    }\n\n    const field = extractFieldFromSchema(params);\n    if (!field) return [];\n    return getFieldChecks(field);\n  }, [...flattenFieldSelector(params)]);\n}\n","import type { Simplify } from '@zod-utils/core';\nimport type { z } from 'zod';\n\n/**\n * Built-in types that should not be recursively transformed.\n * These are treated as leaf values (like primitives) and only get `| null` added.\n * @internal\n */\ntype BuiltInObject =\n  | Date\n  | RegExp\n  | Map<unknown, unknown>\n  | Set<unknown>\n  | WeakMap<object, unknown>\n  | WeakSet<object>\n  | Promise<unknown>\n  | Error;\n\n/**\n * Brand symbol for marking objects that should receive recursive partial transformation.\n * @internal\n */\ndeclare const FormInputBrand: unique symbol;\n\n/**\n * Branded type to mark objects that should have their direct fields made partial.\n * Use with {@link partialFields} helper to mark specific schema objects.\n *\n * @example\n * ```typescript\n * // Objects marked with PartialFields will have their direct fields made optional\n * type MarkedObject = PartialFields<{ name: string; age: number }>;\n * ```\n */\nexport type PartialFields<T> = T & { readonly [FormInputBrand]: true };\n\n/**\n * Helper function to mark a Zod schema so its direct fields become partial.\n *\n * By default, nested objects in form inputs keep their fields strict (only the object\n * itself becomes nullable). Use this helper to opt-in specific objects to have their\n * direct fields also become optional.\n *\n * **Note:** This only affects the direct fields of the marked object. Nested objects\n * within it will still stay strict unless they are also wrapped with `partialFields()`.\n *\n * **Use cases:**\n * - Form input fields that users fill in manually (should be partial)\n * - Objects from selectors/dropdowns should NOT use this (keep strict)\n *\n * @example\n * ```typescript\n * import { partialFields } from '@zod-utils/react-hook-form';\n *\n * const schema = z.object({\n *   price: z.number(),\n *   // User fills in these fields - opt-in to partial\n *   detail: partialFields(z.object({\n *     hotel: z.string(),\n *     nights: z.number(),\n *   })),\n *   // Selected from dropdown - stays strict\n *   agent: z.object({\n *     name: z.string(),\n *     fee: z.number(),\n *   }),\n * });\n *\n * // Result with PartialWithNullableObjects:\n * // detail.hotel  → string | undefined (partial - user input)\n * // detail.nights → number | undefined (partial - user input)\n * // agent.name    → string (strict! - from selector)\n * // agent.fee     → number (strict! - from selector)\n * ```\n */\nexport function partialFields<T extends z.ZodType>(\n  schema: T,\n): z.ZodType<PartialFields<z.infer<T>>, PartialFields<z.input<T>>> {\n  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n  return schema as z.ZodType<\n    PartialFields<z.infer<T>>,\n    PartialFields<z.input<T>>\n  >;\n}\n\n/**\n * Transforms object types for form inputs with selective recursion.\n *\n * **Default behavior (non-recursive):**\n * - **Primitives** (string, number, boolean): optional → `type | undefined`\n * - **Arrays**: optional → `type[] | undefined`\n * - **Built-in objects** (Date, RegExp, etc.): optional and nullable → `type | null | undefined`\n * - **Plain objects**: optional and nullable, but nested fields stay **strict** → `{ strictField: type } | null | undefined`\n *\n * **Opt-in recursive behavior:**\n * - Objects marked with {@link partialFields} will have their nested fields recursively transformed\n *\n * This ensures objects from selectors/dropdowns keep strict types for their fields,\n * while form input fields can be partially filled.\n *\n * @example\n * ```typescript\n * import { partialFields } from '@zod-utils/react-hook-form';\n * import { z } from 'zod';\n *\n * const schema = z.object({\n *   price: z.number(),\n *   detail: partialFields(z.object({ hotel: z.string(), nights: z.number() })),\n *   agent: z.object({ name: z.string(), fee: z.number() }),\n * });\n *\n * type FormInput = PartialWithNullableObjects<z.infer<typeof schema>>;\n * // {\n * //   price?: number;\n * //   detail?: { hotel?: string; nights?: number } | null;  // Recursive!\n * //   agent?: { name: string; fee: number } | null;          // Strict nested!\n * // }\n * ```\n */\nexport type PartialWithNullableObjects<T> = {\n  [K in keyof T]?: T[K] extends readonly unknown[]\n    ? T[K] // Arrays: just optional (via ?), no null, no recursion\n    : T[K] extends BuiltInObject\n      ? T[K] | null // Built-in objects: optional + nullable, no recursion\n      : T[K] extends PartialFields<infer U>\n        ? Simplify<PartialWithNullableObjects<U>> | null // FormInput marked: recurse + null + optional\n        : T[K] extends object\n          ? T[K] | null // Plain objects: optional + nullable, NO recursion (strict nested)\n          : T[K]; // Primitives: just optional (via ?)\n};\n\n/**\n * Transforms all fields to be optional and nullable, with selective recursion.\n *\n * Similar to {@link PartialWithNullableObjects} but also adds `| null` to primitives and arrays.\n *\n * **Default behavior (non-recursive):**\n * - **Primitives**: optional and nullable → `type | null | undefined`\n * - **Arrays**: optional and nullable → `type[] | null | undefined`\n * - **Plain objects**: optional and nullable, but nested fields stay **strict**\n *\n * **Opt-in recursive behavior:**\n * - Objects marked with {@link partialFields} will have their nested fields recursively transformed\n *\n * @example\n * ```typescript\n * type User = { name: string; age: number; profile: { bio: string } };\n * type FormInput = PartialWithAllNullables<User>;\n * // { name?: string | null; age?: number | null; profile?: { bio: string } | null; }\n * // Note: profile.bio stays strict (string, not string | null | undefined)\n * ```\n */\nexport type PartialWithAllNullables<T> = {\n  [K in keyof T]?: T[K] extends readonly unknown[]\n    ? T[K] | null // Arrays: optional + nullable, no recursion\n    : T[K] extends BuiltInObject\n      ? T[K] | null // Built-in objects: optional + nullable, no recursion\n      : T[K] extends PartialFields<infer U>\n        ? Simplify<PartialWithAllNullables<U>> | null // FormInput marked: recurse + null + optional\n        : T[K] extends object\n          ? T[K] | null // Plain objects: optional + nullable, NO recursion (strict nested)\n          : T[K] | null; // Primitives: optional + nullable\n};\n","import { zodResolver } from '@hookform/resolvers/zod';\nimport { type FieldValues, type UseFormProps, useForm } from 'react-hook-form';\nimport type { z } from 'zod';\nimport type {\n  PartialWithAllNullables,\n  PartialWithNullableObjects,\n} from './types';\n\n/**\n * Type-safe React Hook Form wrapper with automatic Zod v4 schema validation and type transformation.\n *\n * This hook eliminates the TypeScript friction between React Hook Form's nullable field values\n * and Zod's strict output types. It uses a two-type schema pattern where:\n * - **Input type** (`PartialWithNullableObjects<TOutput>`): Form fields accept `null | undefined` during editing\n * - **Output type** (`TOutput`): Validated data matches exact schema type (no `null | undefined`)\n *\n * **Key Benefits:**\n * - ✅ No more \"Type 'null' is not assignable to...\" TypeScript errors\n * - ✅ Use `form.setValue()` and `form.reset()` with `null` values freely\n * - ✅ Validated output is still type-safe with exact Zod schema types\n * - ✅ Automatic zodResolver setup - no manual configuration needed\n *\n * @template TInput - The Zod schema input type (accepts nullable/undefined values during form editing)\n * @template TOutput - The Zod schema output type (extends FieldValues)\n * @template TFormInput - The form input type (defaults to PartialWithNullableObjects<TInput>)\n * @template TDefaultValues - The type of default values (inferred from usage for better type safety)\n *\n * @param options - Configuration object\n * @param options.schema - Zod schema with two-type signature `z.ZodType<TOutput, TInput>`\n * @param options.defaultValues - Default form values (shallow partial - nested objects must be complete if provided)\n * @param options.zodResolverOptions - Optional zodResolver configuration\n * @param options....formOptions - All other react-hook-form useForm options\n *\n * @returns React Hook Form instance with type-safe methods\n *\n * @example\n * Basic usage with required fields\n * ```typescript\n * import { useZodForm } from '@zod-utils/react-hook-form';\n * import { z } from 'zod';\n *\n * const schema = z.object({\n *   name: z.string().min(1), // Required field\n *   age: z.number().min(0),\n * }) satisfies z.ZodType<{ name: string; age: number }, any>;\n *\n * function MyForm() {\n *   const form = useZodForm({ schema });\n *\n *   // ✅ These work without type errors:\n *   form.setValue('name', null); // Accepts null during editing\n *   form.reset({ name: null, age: null }); // Reset with null\n *\n *   const onSubmit = (data: { name: string; age: number }) => {\n *     // ✅ data is exact type - no null | undefined\n *     console.log(data.name.toUpperCase()); // Safe to use string methods\n *   };\n *\n *   return <form onSubmit={form.handleSubmit(onSubmit)}>...</form>;\n * }\n * ```\n *\n * @example\n * With default values\n * ```typescript\n * const schema = z.object({\n *   username: z.string(),\n *   email: z.string().email(),\n *   notifications: z.boolean().default(true),\n * }) satisfies z.ZodType<{\n *   username: string;\n *   email: string;\n *   notifications: boolean;\n * }, any>;\n *\n * const form = useZodForm({\n *   schema,\n *   defaultValues: {\n *     username: '',\n *     email: '',\n *     // notifications gets default from schema\n *   },\n * });\n * ```\n *\n * @example\n * Without default values (all fields are optional during editing)\n * ```typescript\n * const schema = z.object({\n *   name: z.string().min(1),\n *   email: z.string().email(),\n *   age: z.number(),\n * }) satisfies z.ZodType<{ name: string; email: string; age: number }, any>;\n *\n * // ✅ No defaultValues needed - fields are optional during editing\n * const form = useZodForm({ schema });\n *\n * // Form fields can be set individually as user types\n * form.setValue('name', 'John');\n * form.setValue('email', 'john@example.com');\n * form.setValue('age', 25);\n *\n * // All fields must be valid on submit (per schema validation)\n * ```\n *\n * @example\n * With optional and nullable fields\n * ```typescript\n * const schema = z.object({\n *   title: z.string(),\n *   description: z.string().optional(), // Optional in output\n *   tags: z.array(z.string()).nullable(), // Nullable in output\n * }) satisfies z.ZodType<{\n *   title: string;\n *   description?: string;\n *   tags: string[] | null;\n * }, any>;\n *\n * const form = useZodForm({ schema });\n *\n * // All fields accept null/undefined during editing\n * form.setValue('title', null);\n * form.setValue('description', undefined);\n * form.setValue('tags', null);\n * ```\n *\n * @example\n * With zodResolver options\n * ```typescript\n * const form = useZodForm({\n *   schema,\n *   zodResolverOptions: {\n *     async: true, // Enable async validation\n *     errorMap: customErrorMap, // Custom error messages\n *   },\n * });\n * ```\n *\n * @example\n * Complete form example\n * ```typescript\n * const userSchema = z.object({\n *   name: z.string().min(1, 'Name is required'),\n *   email: z.string().email('Invalid email'),\n *   age: z.number().min(18, 'Must be 18+'),\n * }) satisfies z.ZodType<{ name: string; email: string; age: number }, any>;\n *\n * function UserForm() {\n *   const form = useZodForm({\n *     schema: userSchema,\n *     defaultValues: { name: '', email: '', age: null },\n *   });\n *\n *   const onSubmit = (data: { name: string; email: string; age: number }) => {\n *     // Type-safe: data has exact types, no null/undefined\n *     console.log(`${data.name} is ${data.age} years old`);\n *   };\n *\n *   return (\n *     <form onSubmit={form.handleSubmit(onSubmit)}>\n *       <input {...form.register('name')} />\n *       <input {...form.register('email')} type=\"email\" />\n *       <input {...form.register('age', { valueAsNumber: true })} type=\"number\" />\n *       <button type=\"submit\">Submit</button>\n *     </form>\n *   );\n * }\n * ```\n *\n * @see {@link PartialWithNullableObjects} for the type transformation utility\n * @see https://react-hook-form.com/docs/useform for React Hook Form documentation\n * @see https://zod.dev for Zod schema documentation\n * @since 0.1.0\n */\nexport const useZodForm = <\n  TInput extends FieldValues,\n  TOutput extends FieldValues,\n  TFormInput extends\n    PartialWithAllNullables<TInput> = PartialWithNullableObjects<TInput>,\n  TDefaultValues extends Partial<TFormInput> | undefined = undefined,\n>({\n  schema,\n  zodResolverOptions,\n  ...formOptions\n}: {\n  schema: z.ZodType<TOutput, TInput>;\n  defaultValues?: TDefaultValues;\n  zodResolverOptions?: Parameters<typeof zodResolver>[1];\n} & Omit<\n  UseFormProps<TFormInput, unknown, TOutput>,\n  'resolver' | 'defaultValues'\n>) => {\n  const resolver = zodResolver(schema, zodResolverOptions);\n\n  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n  return useForm({\n    resolver,\n    ...formOptions,\n  } as unknown as UseFormProps<TFormInput, unknown, TOutput>);\n};\n"]}

package/dist/index.mjs

@@ -88,6 +88,11 @@ function useFieldChecks(params) {
     return getFieldChecks(field);
   }, [...flattenFieldSelector(params)]);
 }
+
+// src/types.ts
+function partialFields(schema) {
+  return schema;
+}
 var useZodForm = (_a) => {
   var _b = _a, {
     schema,
@@ -102,6 +107,6 @@ var useZodForm = (_a) => {
   }, formOptions));
 };
 
-export { FormSchemaContext, FormSchemaProvider, flattenFieldSelector, isRequiredField, useExtractFieldFromSchema, useFieldChecks, useFormSchema, useIsRequiredField, useZodForm };
+export { FormSchemaContext, FormSchemaProvider, flattenFieldSelector, isRequiredField, partialFields, useExtractFieldFromSchema, useFieldChecks, useFormSchema, useIsRequiredField, useZodForm };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/utils.ts","../src/context.tsx","../src/use-zod-form.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkBO,SAAS,qBAAqB,MAAA,EAIlC;AAtBH,EAAA,IAAA,EAAA,EAAA,EAAA;AAuBE,EAAA,OAAO;AAAA,IACL,MAAA,IAAA,IAAA,GAAA,MAAA,GAAA,MAAA,CAAQ,MAAA;AAAA,IACR,MAAA,IAAA,IAAA,GAAA,MAAA,GAAA,MAAA,CAAQ,IAAA;AAAA,IAAA,CACR,EAAA,GAAA,MAAA,IAAA,IAAA,GAAA,MAAA,GAAA,MAAA,CAAQ,kBAAR,IAAA,GAAA,MAAA,GAAA,EAAA,CAAuB,GAAA;AAAA,IAAA,CACvB,EAAA,GAAA,MAAA,IAAA,IAAA,GAAA,MAAA,GAAA,MAAA,CAAQ,kBAAR,IAAA,GAAA,MAAA,GAAA,EAAA,CAAuB;AAAA,GACzB;AACF;AC0BO,IAAM,iBAAA,GAAoB,cAMvB,IAAI;AA6BP,SAAS,cAUd,OAAA,EAKyE;AAKzE,EAAA,OAAO,WAAW,iBAAiB,CAAA;AAKrC;AAqCO,SAAS,kBAAA,CAId;AAAA,EACA,MAAA;AAAA,EACA,aAAA;AAAA,EACA;AACF,CAAA,EAI6B;AAC3B,EAAA,uBACE,GAAA,CAAC,kBAAkB,QAAA,EAAlB,EAA2B,OAAO,EAAE,MAAA,EAAQ,aAAA,EAAc,EACxD,QAAA,EACH,CAAA;AAEJ;AAwBO,SAAS,mBAUd,MAAA,EASS;AAET,EAAA,OAAO,QAAQ,MAAM;AACnB,IAAA,IAAI,CAAC,MAAA,EAAQ;AACX,MAAA,OAAO,KAAA;AAAA,IACT;AACA,IAAA,OAAO,gBAAgB,MAAM,CAAA;AAAA,EAC/B,GAAG,CAAC,GAAG,oBAAA,CAAqB,MAAM,CAAC,CAAC,CAAA;AACtC;AA2CO,SAAS,gBAUd,MAAA,EAOS;AACT,EAAA,MAAM,KAAA,GAAQ,uBAAuB,MAAM,CAAA;AAE3C,EAAA,IAAI,CAAC,KAAA,EAAO;AACV,IAAA,OAAO,KAAA;AAAA,EACT;AAEA,EAAA,OAAO,mBAAmB,KAAK,CAAA;AACjC;AAuCO,SAAS,0BAUd,MAAA,EASuB;AAEvB,EAAA,OAAO,QAAQ,MAAM;AACnB,IAAA,IAAI,CAAC,MAAA,EAAQ;AACX,MAAA,OAAO,MAAA;AAAA,IACT;AACA,IAAA,OAAO,uBAAuB,MAAM,CAAA;AAAA,EACtC,GAAG,CAAC,GAAG,oBAAA,CAAqB,MAAM,CAAC,CAAC,CAAA;AACtC;AAwBO,SAAS,eAUd,MAAA,EASiB;AAEjB,EAAA,OAAO,QAAQ,MAAM;AACnB,IAAA,IAAI,CAAC,MAAA,EAAQ;AACX,MAAA,OAAO,EAAC;AAAA,IACV;AAEA,IAAA,MAAM,KAAA,GAAQ,uBAAuB,MAAM,CAAA;AAC3C,IAAA,IAAI,CAAC,KAAA,EAAO,OAAO,EAAC;AACpB,IAAA,OAAO,eAAe,KAAK,CAAA;AAAA,EAC7B,GAAG,CAAC,GAAG,oBAAA,CAAqB,MAAM,CAAC,CAAC,CAAA;AACtC;AC3OO,IAAM,UAAA,GAAa,CAMxB,EAAA,KAWI;AAXJ,EAAA,IAAA,EAAA,GAAA,EAAA,EACA;AAAA,IAAA,MAAA;AAAA,IACA;AAAA,GAtLF,GAoLE,EAAA,EAGG,WAAA,GAAA,SAAA,CAHH,EAAA,EAGG;AAAA,IAFH,QAAA;AAAA,IACA;AAAA,GAAA,CAAA;AAUA,EAAA,MAAM,QAAA,GAAW,WAAA,CAAY,MAAA,EAAQ,kBAAkB,CAAA;AAGvD,EAAA,OAAO,OAAA,CAAQ,cAAA,CAAA;AAAA,IACb;AAAA,GAAA,EACG,WAAA,CACqD,CAAA;AAC5D","file":"index.mjs","sourcesContent":["import type { z } from 'zod';\n\n/**\n * Flattens a FieldSelector into an array of primitive values for use in React dependency arrays.\n *\n * This is useful for `useMemo` and `useCallback` dependencies where you want to avoid\n * re-running when object references change but values stay the same.\n *\n * @param params - The FieldSelector containing schema, name, and optional discriminator\n * @returns An array of primitive values suitable for React dependency arrays\n *\n * @example\n * ```tsx\n * const memoizedValue = useMemo(() => {\n *   return extractFieldFromSchema(params);\n * }, flattenFieldSelector(params));\n * ```\n */\nexport function flattenFieldSelector(params?: {\n  schema?: z.ZodType;\n  name?: string;\n  discriminator?: { key: unknown; value: unknown };\n}) {\n  return [\n    params?.schema,\n    params?.name,\n    params?.discriminator?.key,\n    params?.discriminator?.value,\n  ];\n}\n","'use client';\n\nimport {\n  type DiscriminatorKey,\n  type DiscriminatorValue,\n  extractFieldFromSchema,\n  type FieldSelectorProps,\n  getFieldChecks,\n  requiresValidInput,\n  type SchemaAndDiscriminatorProps,\n  type ZodUnionCheck,\n} from '@zod-utils/core';\nimport {\n  type Context,\n  createContext,\n  type ReactNode,\n  useContext,\n  useMemo,\n} from 'react';\nimport type { z } from 'zod';\nimport { flattenFieldSelector } from './utils';\n\n/**\n * Type for the FormSchemaContext with full generic support.\n * @internal\n */\nexport type FormSchemaContextType<\n  TSchema extends z.ZodType,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema>,\n  TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>,\n> = Context<SchemaAndDiscriminatorProps<\n  TSchema,\n  TDiscriminatorKey,\n  TDiscriminatorValue\n> | null>;\n\n/**\n * Context value type for FormSchemaContext.\n */\nexport type FormSchemaContextValue<\n  TSchema extends z.ZodType,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema>,\n  TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>,\n> = SchemaAndDiscriminatorProps<\n  TSchema,\n  TDiscriminatorKey,\n  TDiscriminatorValue\n> | null;\n\n/**\n * React Context for providing Zod schema to form components.\n *\n * Use with {@link FormSchemaProvider} to provide schema context, and\n * {@link useFormSchema} to consume it in child components.\n */\nexport const FormSchemaContext = createContext<{\n  schema: z.ZodType;\n  discriminator?: {\n    key: unknown;\n    value: unknown;\n  };\n} | null>(null);\n\n/**\n * Hook to access the form schema from context.\n *\n * The optional `_params` argument is used for TypeScript type inference only.\n * Pass your schema to get proper type narrowing of the context value.\n *\n * @param _params - Optional params for type inference (not used at runtime)\n * @returns The schema context value or null if not within a provider\n *\n * @example\n * ```tsx\n * // Without type params (returns generic context)\n * function MyFormField() {\n *   const context = useFormSchema();\n *   if (!context) return null;\n *\n *   const { schema, discriminator } = context;\n *   // Use schema for validation or field extraction\n * }\n *\n * // With type params (for type-safe schema access)\n * function TypedFormField() {\n *   const context = useFormSchema({ schema: mySchema });\n *   // context.schema is now typed as typeof mySchema\n * }\n * ```\n */\nexport function useFormSchema<\n  TSchema extends z.ZodType = z.ZodType,\n  TDiscriminatorKey extends\n    DiscriminatorKey<TSchema> = DiscriminatorKey<TSchema>,\n  TDiscriminatorValue extends DiscriminatorValue<\n    TSchema,\n    TDiscriminatorKey\n  > = DiscriminatorValue<TSchema, TDiscriminatorKey>,\n>(\n  // Parameter used for type inference only, not at runtime\n  _params?: SchemaAndDiscriminatorProps<\n    TSchema,\n    TDiscriminatorKey,\n    TDiscriminatorValue\n  >,\n): FormSchemaContextValue<TSchema, TDiscriminatorKey, TDiscriminatorValue> {\n  // Type assertion is necessary because React context is created with a generic type,\n  // but we want to return a narrower type based on the generic parameters.\n  // The caller is responsible for ensuring type safety via the _params argument.\n  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n  return useContext(FormSchemaContext) as FormSchemaContextValue<\n    TSchema,\n    TDiscriminatorKey,\n    TDiscriminatorValue\n  >;\n}\n\n/**\n * Provider component that makes Zod schema available to all child components.\n *\n * Use this to wrap your form and provide schema context to nested components\n * like field labels and validation indicators.\n *\n * @example\n * Basic usage with ZodObject\n * ```tsx\n * const schema = z.object({\n *   name: z.string(),\n *   email: z.string().email().optional()\n * });\n *\n * <FormSchemaProvider schema={schema}>\n *   <YourFormComponents />\n * </FormSchemaProvider>\n * ```\n *\n * @example\n * Usage with discriminated union\n * ```tsx\n * const schema = z.discriminatedUnion('mode', [\n *   z.object({ mode: z.literal('create'), name: z.string() }),\n *   z.object({ mode: z.literal('edit'), id: z.number() })\n * ]);\n *\n * <FormSchemaProvider\n *   schema={schema}\n *   discriminator={{ key: 'mode', value: 'create' }}\n * >\n *   <YourFormComponents />\n * </FormSchemaProvider>\n * ```\n */\nexport function FormSchemaProvider<\n  TSchema extends z.ZodType,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema>,\n  TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>,\n>({\n  schema,\n  discriminator,\n  children,\n}: SchemaAndDiscriminatorProps<\n  TSchema,\n  TDiscriminatorKey,\n  TDiscriminatorValue\n> & { children: ReactNode }) {\n  return (\n    <FormSchemaContext.Provider value={{ schema, discriminator }}>\n      {children}\n    </FormSchemaContext.Provider>\n  );\n}\n\n/**\n * Hook to check if a field requires valid input based on the Zod schema.\n *\n * Memoized - only recalculates when schema, name, or discriminator changes.\n *\n * @param params - Schema, name, and optional discriminator\n * @returns true if the field requires valid input, false otherwise\n *\n * @example\n * ```tsx\n * function MyFieldLabel({ name, schema }: { name: string; schema: z.ZodType }) {\n *   const isRequired = useIsRequiredField({ schema, name });\n *\n *   return (\n *     <label>\n *       {name}\n *       {isRequired && <span className=\"text-red-500\">*</span>}\n *     </label>\n *   );\n * }\n * ```\n */\nexport function useIsRequiredField<\n  TSchema extends z.ZodType,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema> = never,\n  TDiscriminatorValue extends DiscriminatorValue<\n    TSchema,\n    TDiscriminatorKey\n  > = never,\n  TFilterType = unknown,\n  TStrict extends boolean = true,\n>(\n  params:\n    | FieldSelectorProps<\n        TSchema,\n        TDiscriminatorKey,\n        TDiscriminatorValue,\n        TFilterType,\n        TStrict\n      >\n    | undefined,\n): boolean {\n  // biome-ignore lint/correctness/useExhaustiveDependencies: using flattenFieldSelector for stable deps\n  return useMemo(() => {\n    if (!params) {\n      return false;\n    }\n    return isRequiredField(params);\n  }, [...flattenFieldSelector(params)]);\n}\n\n/**\n * Determines if a field requires valid input (will show validation errors on empty/invalid input).\n *\n * Uses `requiresValidInput` from `@zod-utils/core` which checks the underlying field after\n * removing defaults. This tells you if the field will error when user submits empty input.\n *\n * Returns false if the underlying field accepts:\n * - `undefined` (via `.optional()`)\n * - `null` (via `.nullable()`)\n * - Empty strings (plain `z.string()` without `.min(1)`)\n * - Empty arrays (plain `z.array()` without `.min(1)`)\n *\n * @param options - Schema, field name, and optional discriminator\n * @returns true if the field requires valid input, false otherwise\n *\n * @example\n * ```typescript\n * const schema = z.object({\n *   name: z.string().min(1),\n *   bio: z.string().optional(),\n * });\n *\n * isRequiredField({ schema, name: 'name' }); // true\n * isRequiredField({ schema, name: 'bio' });  // false\n * ```\n *\n * @example\n * With discriminated union\n * ```typescript\n * const schema = z.discriminatedUnion('mode', [\n *   z.object({ mode: z.literal('create'), name: z.string().min(1) }),\n *   z.object({ mode: z.literal('edit'), id: z.number() }),\n * ]);\n *\n * isRequiredField({\n *   schema,\n *   name: 'name',\n *   discriminator: { key: 'mode', value: 'create' },\n * }); // true\n * ```\n */\nexport function isRequiredField<\n  TSchema extends z.ZodType,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema> = never,\n  TDiscriminatorValue extends DiscriminatorValue<\n    TSchema,\n    TDiscriminatorKey\n  > = never,\n  TFilterType = unknown,\n  TStrict extends boolean = true,\n>(\n  params: FieldSelectorProps<\n    TSchema,\n    TDiscriminatorKey,\n    TDiscriminatorValue,\n    TFilterType,\n    TStrict\n  >,\n): boolean {\n  const field = extractFieldFromSchema(params);\n\n  if (!field) {\n    return false;\n  }\n\n  return requiresValidInput(field);\n}\n\n/**\n * React hook to extract a field's Zod schema from a parent schema.\n *\n * Memoized - only recalculates when schema, name, or discriminator changes.\n * Supports nested paths and discriminated unions.\n *\n * @param params - Schema, name, and optional discriminator\n * @returns The Zod schema for the field, or undefined if not found\n *\n * @example\n * ```tsx\n * function MyFieldInfo({ name, schema }: { name: string; schema: z.ZodType }) {\n *   const fieldSchema = useExtractFieldFromSchema({ schema, name });\n *\n *   if (!fieldSchema) return null;\n *\n *   // Use fieldSchema for custom validation or field info\n *   return <span>{fieldSchema._zod.typeName}</span>;\n * }\n * ```\n *\n * @example\n * With discriminated union\n * ```tsx\n * const schema = z.discriminatedUnion('mode', [\n *   z.object({ mode: z.literal('create'), name: z.string() }),\n *   z.object({ mode: z.literal('edit'), id: z.number() }),\n * ]);\n *\n * const fieldSchema = useExtractFieldFromSchema({\n *   schema,\n *   name: 'name',\n *   discriminator: { key: 'mode', value: 'create' },\n * });\n * // Returns z.string() schema\n * ```\n */\nexport function useExtractFieldFromSchema<\n  TSchema extends z.ZodType,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema> = never,\n  TDiscriminatorValue extends DiscriminatorValue<\n    TSchema,\n    TDiscriminatorKey\n  > = never,\n  TFilterType = unknown,\n  TStrict extends boolean = true,\n>(\n  params:\n    | FieldSelectorProps<\n        TSchema,\n        TDiscriminatorKey,\n        TDiscriminatorValue,\n        TFilterType,\n        TStrict\n      >\n    | undefined,\n): z.ZodType | undefined {\n  // biome-ignore lint/correctness/useExhaustiveDependencies: using flattenFieldSelector for stable deps\n  return useMemo(() => {\n    if (!params) {\n      return undefined;\n    }\n    return extractFieldFromSchema(params);\n  }, [...flattenFieldSelector(params)]);\n}\n\n/**\n * Hook to get validation checks from a field's Zod schema.\n *\n * Memoized - only recalculates when schema, name, or discriminator changes.\n * Combines field extraction and check retrieval in one cached operation.\n *\n * @param params - Schema, name, and optional discriminator\n * @returns Array of validation checks (min, max, pattern, etc.) or empty array\n *\n * @example\n * ```tsx\n * function MyFieldHint({ schema, name }: { schema: z.ZodType; name: string }) {\n *   const checks = useFieldChecks({ schema, name });\n *\n *   const maxLength = checks.find(c => c.check === 'max_length');\n *   if (maxLength) {\n *     return <span>Max {maxLength.maximum} characters</span>;\n *   }\n *   return null;\n * }\n * ```\n */\nexport function useFieldChecks<\n  TSchema extends z.ZodType,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema> = never,\n  TDiscriminatorValue extends DiscriminatorValue<\n    TSchema,\n    TDiscriminatorKey\n  > = never,\n  TFilterType = unknown,\n  TStrict extends boolean = true,\n>(\n  params:\n    | FieldSelectorProps<\n        TSchema,\n        TDiscriminatorKey,\n        TDiscriminatorValue,\n        TFilterType,\n        TStrict\n      >\n    | undefined,\n): ZodUnionCheck[] {\n  // biome-ignore lint/correctness/useExhaustiveDependencies: using flattenFieldSelector for stable deps\n  return useMemo(() => {\n    if (!params) {\n      return [];\n    }\n\n    const field = extractFieldFromSchema(params);\n    if (!field) return [];\n    return getFieldChecks(field);\n  }, [...flattenFieldSelector(params)]);\n}\n","import { zodResolver } from '@hookform/resolvers/zod';\nimport { type FieldValues, type UseFormProps, useForm } from 'react-hook-form';\nimport type { z } from 'zod';\nimport type {\n  DeepPartialWithAllNullables,\n  DeepPartialWithNullableObjects,\n} from './types';\n\n/**\n * Type-safe React Hook Form wrapper with automatic Zod v4 schema validation and type transformation.\n *\n * This hook eliminates the TypeScript friction between React Hook Form's nullable field values\n * and Zod's strict output types. It uses a two-type schema pattern where:\n * - **Input type** (`DeepPartialWithNullableObjects<TOutput>`): Form fields accept `null | undefined` during editing\n * - **Output type** (`TOutput`): Validated data matches exact schema type (no `null | undefined`)\n *\n * **Key Benefits:**\n * - ✅ No more \"Type 'null' is not assignable to...\" TypeScript errors\n * - ✅ Use `form.setValue()` and `form.reset()` with `null` values freely\n * - ✅ Validated output is still type-safe with exact Zod schema types\n * - ✅ Automatic zodResolver setup - no manual configuration needed\n *\n * @template TInput - The Zod schema input type (accepts nullable/undefined values during form editing)\n * @template TOutput - The Zod schema output type (extends FieldValues)\n * @template TFormInput - The form input type (defaults to DeepPartialWithNullableObjects<TInput>)\n * @template TDefaultValues - The type of default values (inferred from usage for better type safety)\n *\n * @param options - Configuration object\n * @param options.schema - Zod schema with two-type signature `z.ZodType<TOutput, TInput>`\n * @param options.defaultValues - Default form values (shallow partial - nested objects must be complete if provided)\n * @param options.zodResolverOptions - Optional zodResolver configuration\n * @param options....formOptions - All other react-hook-form useForm options\n *\n * @returns React Hook Form instance with type-safe methods\n *\n * @example\n * Basic usage with required fields\n * ```typescript\n * import { useZodForm } from '@zod-utils/react-hook-form';\n * import { z } from 'zod';\n *\n * const schema = z.object({\n *   name: z.string().min(1), // Required field\n *   age: z.number().min(0),\n * }) satisfies z.ZodType<{ name: string; age: number }, any>;\n *\n * function MyForm() {\n *   const form = useZodForm({ schema });\n *\n *   // ✅ These work without type errors:\n *   form.setValue('name', null); // Accepts null during editing\n *   form.reset({ name: null, age: null }); // Reset with null\n *\n *   const onSubmit = (data: { name: string; age: number }) => {\n *     // ✅ data is exact type - no null | undefined\n *     console.log(data.name.toUpperCase()); // Safe to use string methods\n *   };\n *\n *   return <form onSubmit={form.handleSubmit(onSubmit)}>...</form>;\n * }\n * ```\n *\n * @example\n * With default values\n * ```typescript\n * const schema = z.object({\n *   username: z.string(),\n *   email: z.string().email(),\n *   notifications: z.boolean().default(true),\n * }) satisfies z.ZodType<{\n *   username: string;\n *   email: string;\n *   notifications: boolean;\n * }, any>;\n *\n * const form = useZodForm({\n *   schema,\n *   defaultValues: {\n *     username: '',\n *     email: '',\n *     // notifications gets default from schema\n *   },\n * });\n * ```\n *\n * @example\n * Without default values (all fields are optional during editing)\n * ```typescript\n * const schema = z.object({\n *   name: z.string().min(1),\n *   email: z.string().email(),\n *   age: z.number(),\n * }) satisfies z.ZodType<{ name: string; email: string; age: number }, any>;\n *\n * // ✅ No defaultValues needed - fields are optional during editing\n * const form = useZodForm({ schema });\n *\n * // Form fields can be set individually as user types\n * form.setValue('name', 'John');\n * form.setValue('email', 'john@example.com');\n * form.setValue('age', 25);\n *\n * // All fields must be valid on submit (per schema validation)\n * ```\n *\n * @example\n * With optional and nullable fields\n * ```typescript\n * const schema = z.object({\n *   title: z.string(),\n *   description: z.string().optional(), // Optional in output\n *   tags: z.array(z.string()).nullable(), // Nullable in output\n * }) satisfies z.ZodType<{\n *   title: string;\n *   description?: string;\n *   tags: string[] | null;\n * }, any>;\n *\n * const form = useZodForm({ schema });\n *\n * // All fields accept null/undefined during editing\n * form.setValue('title', null);\n * form.setValue('description', undefined);\n * form.setValue('tags', null);\n * ```\n *\n * @example\n * With zodResolver options\n * ```typescript\n * const form = useZodForm({\n *   schema,\n *   zodResolverOptions: {\n *     async: true, // Enable async validation\n *     errorMap: customErrorMap, // Custom error messages\n *   },\n * });\n * ```\n *\n * @example\n * Complete form example\n * ```typescript\n * const userSchema = z.object({\n *   name: z.string().min(1, 'Name is required'),\n *   email: z.string().email('Invalid email'),\n *   age: z.number().min(18, 'Must be 18+'),\n * }) satisfies z.ZodType<{ name: string; email: string; age: number }, any>;\n *\n * function UserForm() {\n *   const form = useZodForm({\n *     schema: userSchema,\n *     defaultValues: { name: '', email: '', age: null },\n *   });\n *\n *   const onSubmit = (data: { name: string; email: string; age: number }) => {\n *     // Type-safe: data has exact types, no null/undefined\n *     console.log(`${data.name} is ${data.age} years old`);\n *   };\n *\n *   return (\n *     <form onSubmit={form.handleSubmit(onSubmit)}>\n *       <input {...form.register('name')} />\n *       <input {...form.register('email')} type=\"email\" />\n *       <input {...form.register('age', { valueAsNumber: true })} type=\"number\" />\n *       <button type=\"submit\">Submit</button>\n *     </form>\n *   );\n * }\n * ```\n *\n * @see {@link DeepPartialWithNullableObjects} for the type transformation utility\n * @see https://react-hook-form.com/docs/useform for React Hook Form documentation\n * @see https://zod.dev for Zod schema documentation\n * @since 0.1.0\n */\nexport const useZodForm = <\n  TInput extends FieldValues,\n  TOutput extends FieldValues,\n  TFormInput extends\n    DeepPartialWithAllNullables<TInput> = DeepPartialWithNullableObjects<TInput>,\n  TDefaultValues extends Partial<TFormInput> | undefined = undefined,\n>({\n  schema,\n  zodResolverOptions,\n  ...formOptions\n}: {\n  schema: z.ZodType<TOutput, TInput>;\n  defaultValues?: TDefaultValues;\n  zodResolverOptions?: Parameters<typeof zodResolver>[1];\n} & Omit<\n  UseFormProps<TFormInput, unknown, TOutput>,\n  'resolver' | 'defaultValues'\n>) => {\n  const resolver = zodResolver(schema, zodResolverOptions);\n\n  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n  return useForm({\n    resolver,\n    ...formOptions,\n  } as unknown as UseFormProps<TFormInput, unknown, TOutput>);\n};\n"]}
+{"version":3,"sources":["../src/utils.ts","../src/context.tsx","../src/types.ts","../src/use-zod-form.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkBO,SAAS,qBAAqB,MAAA,EAIlC;AAtBH,EAAA,IAAA,EAAA,EAAA,EAAA;AAuBE,EAAA,OAAO;AAAA,IACL,MAAA,IAAA,IAAA,GAAA,MAAA,GAAA,MAAA,CAAQ,MAAA;AAAA,IACR,MAAA,IAAA,IAAA,GAAA,MAAA,GAAA,MAAA,CAAQ,IAAA;AAAA,IAAA,CACR,EAAA,GAAA,MAAA,IAAA,IAAA,GAAA,MAAA,GAAA,MAAA,CAAQ,kBAAR,IAAA,GAAA,MAAA,GAAA,EAAA,CAAuB,GAAA;AAAA,IAAA,CACvB,EAAA,GAAA,MAAA,IAAA,IAAA,GAAA,MAAA,GAAA,MAAA,CAAQ,kBAAR,IAAA,GAAA,MAAA,GAAA,EAAA,CAAuB;AAAA,GACzB;AACF;AC0BO,IAAM,iBAAA,GAAoB,cAMvB,IAAI;AA6BP,SAAS,cAUd,OAAA,EAKyE;AAKzE,EAAA,OAAO,WAAW,iBAAiB,CAAA;AAKrC;AAqCO,SAAS,kBAAA,CAId;AAAA,EACA,MAAA;AAAA,EACA,aAAA;AAAA,EACA;AACF,CAAA,EAI6B;AAC3B,EAAA,uBACE,GAAA,CAAC,kBAAkB,QAAA,EAAlB,EAA2B,OAAO,EAAE,MAAA,EAAQ,aAAA,EAAc,EACxD,QAAA,EACH,CAAA;AAEJ;AAwBO,SAAS,mBAUd,MAAA,EASS;AAET,EAAA,OAAO,QAAQ,MAAM;AACnB,IAAA,IAAI,CAAC,MAAA,EAAQ;AACX,MAAA,OAAO,KAAA;AAAA,IACT;AACA,IAAA,OAAO,gBAAgB,MAAM,CAAA;AAAA,EAC/B,GAAG,CAAC,GAAG,oBAAA,CAAqB,MAAM,CAAC,CAAC,CAAA;AACtC;AA2CO,SAAS,gBAUd,MAAA,EAOS;AACT,EAAA,MAAM,KAAA,GAAQ,uBAAuB,MAAM,CAAA;AAE3C,EAAA,IAAI,CAAC,KAAA,EAAO;AACV,IAAA,OAAO,KAAA;AAAA,EACT;AAEA,EAAA,OAAO,mBAAmB,KAAK,CAAA;AACjC;AAuCO,SAAS,0BAUd,MAAA,EASuB;AAEvB,EAAA,OAAO,QAAQ,MAAM;AACnB,IAAA,IAAI,CAAC,MAAA,EAAQ;AACX,MAAA,OAAO,MAAA;AAAA,IACT;AACA,IAAA,OAAO,uBAAuB,MAAM,CAAA;AAAA,EACtC,GAAG,CAAC,GAAG,oBAAA,CAAqB,MAAM,CAAC,CAAC,CAAA;AACtC;AAwBO,SAAS,eAUd,MAAA,EASiB;AAEjB,EAAA,OAAO,QAAQ,MAAM;AACnB,IAAA,IAAI,CAAC,MAAA,EAAQ;AACX,MAAA,OAAO,EAAC;AAAA,IACV;AAEA,IAAA,MAAM,KAAA,GAAQ,uBAAuB,MAAM,CAAA;AAC3C,IAAA,IAAI,CAAC,KAAA,EAAO,OAAO,EAAC;AACpB,IAAA,OAAO,eAAe,KAAK,CAAA;AAAA,EAC7B,GAAG,CAAC,GAAG,oBAAA,CAAqB,MAAM,CAAC,CAAC,CAAA;AACtC;;;AC9UO,SAAS,cACd,MAAA,EACiE;AAEjE,EAAA,OAAO,MAAA;AAIT;AC2FO,IAAM,UAAA,GAAa,CAMxB,EAAA,KAWI;AAXJ,EAAA,IAAA,EAAA,GAAA,EAAA,EACA;AAAA,IAAA,MAAA;AAAA,IACA;AAAA,GAtLF,GAoLE,EAAA,EAGG,WAAA,GAAA,SAAA,CAHH,EAAA,EAGG;AAAA,IAFH,QAAA;AAAA,IACA;AAAA,GAAA,CAAA;AAUA,EAAA,MAAM,QAAA,GAAW,WAAA,CAAY,MAAA,EAAQ,kBAAkB,CAAA;AAGvD,EAAA,OAAO,OAAA,CAAQ,cAAA,CAAA;AAAA,IACb;AAAA,GAAA,EACG,WAAA,CACqD,CAAA;AAC5D","file":"index.mjs","sourcesContent":["import type { z } from 'zod';\n\n/**\n * Flattens a FieldSelector into an array of primitive values for use in React dependency arrays.\n *\n * This is useful for `useMemo` and `useCallback` dependencies where you want to avoid\n * re-running when object references change but values stay the same.\n *\n * @param params - The FieldSelector containing schema, name, and optional discriminator\n * @returns An array of primitive values suitable for React dependency arrays\n *\n * @example\n * ```tsx\n * const memoizedValue = useMemo(() => {\n *   return extractFieldFromSchema(params);\n * }, flattenFieldSelector(params));\n * ```\n */\nexport function flattenFieldSelector(params?: {\n  schema?: z.ZodType;\n  name?: string;\n  discriminator?: { key: unknown; value: unknown };\n}) {\n  return [\n    params?.schema,\n    params?.name,\n    params?.discriminator?.key,\n    params?.discriminator?.value,\n  ];\n}\n","'use client';\n\nimport {\n  type DiscriminatorKey,\n  type DiscriminatorValue,\n  extractFieldFromSchema,\n  type FieldSelectorProps,\n  getFieldChecks,\n  requiresValidInput,\n  type SchemaAndDiscriminatorProps,\n  type ZodUnionCheck,\n} from '@zod-utils/core';\nimport {\n  type Context,\n  createContext,\n  type ReactNode,\n  useContext,\n  useMemo,\n} from 'react';\nimport type { z } from 'zod';\nimport { flattenFieldSelector } from './utils';\n\n/**\n * Type for the FormSchemaContext with full generic support.\n * @internal\n */\nexport type FormSchemaContextType<\n  TSchema extends z.ZodType,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema>,\n  TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>,\n> = Context<SchemaAndDiscriminatorProps<\n  TSchema,\n  TDiscriminatorKey,\n  TDiscriminatorValue\n> | null>;\n\n/**\n * Context value type for FormSchemaContext.\n */\nexport type FormSchemaContextValue<\n  TSchema extends z.ZodType,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema>,\n  TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>,\n> = SchemaAndDiscriminatorProps<\n  TSchema,\n  TDiscriminatorKey,\n  TDiscriminatorValue\n> | null;\n\n/**\n * React Context for providing Zod schema to form components.\n *\n * Use with {@link FormSchemaProvider} to provide schema context, and\n * {@link useFormSchema} to consume it in child components.\n */\nexport const FormSchemaContext = createContext<{\n  schema: z.ZodType;\n  discriminator?: {\n    key: unknown;\n    value: unknown;\n  };\n} | null>(null);\n\n/**\n * Hook to access the form schema from context.\n *\n * The optional `_params` argument is used for TypeScript type inference only.\n * Pass your schema to get proper type narrowing of the context value.\n *\n * @param _params - Optional params for type inference (not used at runtime)\n * @returns The schema context value or null if not within a provider\n *\n * @example\n * ```tsx\n * // Without type params (returns generic context)\n * function MyFormField() {\n *   const context = useFormSchema();\n *   if (!context) return null;\n *\n *   const { schema, discriminator } = context;\n *   // Use schema for validation or field extraction\n * }\n *\n * // With type params (for type-safe schema access)\n * function TypedFormField() {\n *   const context = useFormSchema({ schema: mySchema });\n *   // context.schema is now typed as typeof mySchema\n * }\n * ```\n */\nexport function useFormSchema<\n  TSchema extends z.ZodType = z.ZodType,\n  TDiscriminatorKey extends\n    DiscriminatorKey<TSchema> = DiscriminatorKey<TSchema>,\n  TDiscriminatorValue extends DiscriminatorValue<\n    TSchema,\n    TDiscriminatorKey\n  > = DiscriminatorValue<TSchema, TDiscriminatorKey>,\n>(\n  // Parameter used for type inference only, not at runtime\n  _params?: SchemaAndDiscriminatorProps<\n    TSchema,\n    TDiscriminatorKey,\n    TDiscriminatorValue\n  >,\n): FormSchemaContextValue<TSchema, TDiscriminatorKey, TDiscriminatorValue> {\n  // Type assertion is necessary because React context is created with a generic type,\n  // but we want to return a narrower type based on the generic parameters.\n  // The caller is responsible for ensuring type safety via the _params argument.\n  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n  return useContext(FormSchemaContext) as FormSchemaContextValue<\n    TSchema,\n    TDiscriminatorKey,\n    TDiscriminatorValue\n  >;\n}\n\n/**\n * Provider component that makes Zod schema available to all child components.\n *\n * Use this to wrap your form and provide schema context to nested components\n * like field labels and validation indicators.\n *\n * @example\n * Basic usage with ZodObject\n * ```tsx\n * const schema = z.object({\n *   name: z.string(),\n *   email: z.string().email().optional()\n * });\n *\n * <FormSchemaProvider schema={schema}>\n *   <YourFormComponents />\n * </FormSchemaProvider>\n * ```\n *\n * @example\n * Usage with discriminated union\n * ```tsx\n * const schema = z.discriminatedUnion('mode', [\n *   z.object({ mode: z.literal('create'), name: z.string() }),\n *   z.object({ mode: z.literal('edit'), id: z.number() })\n * ]);\n *\n * <FormSchemaProvider\n *   schema={schema}\n *   discriminator={{ key: 'mode', value: 'create' }}\n * >\n *   <YourFormComponents />\n * </FormSchemaProvider>\n * ```\n */\nexport function FormSchemaProvider<\n  TSchema extends z.ZodType,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema>,\n  TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>,\n>({\n  schema,\n  discriminator,\n  children,\n}: SchemaAndDiscriminatorProps<\n  TSchema,\n  TDiscriminatorKey,\n  TDiscriminatorValue\n> & { children: ReactNode }) {\n  return (\n    <FormSchemaContext.Provider value={{ schema, discriminator }}>\n      {children}\n    </FormSchemaContext.Provider>\n  );\n}\n\n/**\n * Hook to check if a field requires valid input based on the Zod schema.\n *\n * Memoized - only recalculates when schema, name, or discriminator changes.\n *\n * @param params - Schema, name, and optional discriminator\n * @returns true if the field requires valid input, false otherwise\n *\n * @example\n * ```tsx\n * function MyFieldLabel({ name, schema }: { name: string; schema: z.ZodType }) {\n *   const isRequired = useIsRequiredField({ schema, name });\n *\n *   return (\n *     <label>\n *       {name}\n *       {isRequired && <span className=\"text-red-500\">*</span>}\n *     </label>\n *   );\n * }\n * ```\n */\nexport function useIsRequiredField<\n  TSchema extends z.ZodType,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema> = never,\n  TDiscriminatorValue extends DiscriminatorValue<\n    TSchema,\n    TDiscriminatorKey\n  > = never,\n  TFilterType = unknown,\n  TStrict extends boolean = true,\n>(\n  params:\n    | FieldSelectorProps<\n        TSchema,\n        TDiscriminatorKey,\n        TDiscriminatorValue,\n        TFilterType,\n        TStrict\n      >\n    | undefined,\n): boolean {\n  // biome-ignore lint/correctness/useExhaustiveDependencies: using flattenFieldSelector for stable deps\n  return useMemo(() => {\n    if (!params) {\n      return false;\n    }\n    return isRequiredField(params);\n  }, [...flattenFieldSelector(params)]);\n}\n\n/**\n * Determines if a field requires valid input (will show validation errors on empty/invalid input).\n *\n * Uses `requiresValidInput` from `@zod-utils/core` which checks the underlying field after\n * removing defaults. This tells you if the field will error when user submits empty input.\n *\n * Returns false if the underlying field accepts:\n * - `undefined` (via `.optional()`)\n * - `null` (via `.nullable()`)\n * - Empty strings (plain `z.string()` without `.min(1)`)\n * - Empty arrays (plain `z.array()` without `.min(1)`)\n *\n * @param options - Schema, field name, and optional discriminator\n * @returns true if the field requires valid input, false otherwise\n *\n * @example\n * ```typescript\n * const schema = z.object({\n *   name: z.string().min(1),\n *   bio: z.string().optional(),\n * });\n *\n * isRequiredField({ schema, name: 'name' }); // true\n * isRequiredField({ schema, name: 'bio' });  // false\n * ```\n *\n * @example\n * With discriminated union\n * ```typescript\n * const schema = z.discriminatedUnion('mode', [\n *   z.object({ mode: z.literal('create'), name: z.string().min(1) }),\n *   z.object({ mode: z.literal('edit'), id: z.number() }),\n * ]);\n *\n * isRequiredField({\n *   schema,\n *   name: 'name',\n *   discriminator: { key: 'mode', value: 'create' },\n * }); // true\n * ```\n */\nexport function isRequiredField<\n  TSchema extends z.ZodType,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema> = never,\n  TDiscriminatorValue extends DiscriminatorValue<\n    TSchema,\n    TDiscriminatorKey\n  > = never,\n  TFilterType = unknown,\n  TStrict extends boolean = true,\n>(\n  params: FieldSelectorProps<\n    TSchema,\n    TDiscriminatorKey,\n    TDiscriminatorValue,\n    TFilterType,\n    TStrict\n  >,\n): boolean {\n  const field = extractFieldFromSchema(params);\n\n  if (!field) {\n    return false;\n  }\n\n  return requiresValidInput(field);\n}\n\n/**\n * React hook to extract a field's Zod schema from a parent schema.\n *\n * Memoized - only recalculates when schema, name, or discriminator changes.\n * Supports nested paths and discriminated unions.\n *\n * @param params - Schema, name, and optional discriminator\n * @returns The Zod schema for the field, or undefined if not found\n *\n * @example\n * ```tsx\n * function MyFieldInfo({ name, schema }: { name: string; schema: z.ZodType }) {\n *   const fieldSchema = useExtractFieldFromSchema({ schema, name });\n *\n *   if (!fieldSchema) return null;\n *\n *   // Use fieldSchema for custom validation or field info\n *   return <span>{fieldSchema._zod.typeName}</span>;\n * }\n * ```\n *\n * @example\n * With discriminated union\n * ```tsx\n * const schema = z.discriminatedUnion('mode', [\n *   z.object({ mode: z.literal('create'), name: z.string() }),\n *   z.object({ mode: z.literal('edit'), id: z.number() }),\n * ]);\n *\n * const fieldSchema = useExtractFieldFromSchema({\n *   schema,\n *   name: 'name',\n *   discriminator: { key: 'mode', value: 'create' },\n * });\n * // Returns z.string() schema\n * ```\n */\nexport function useExtractFieldFromSchema<\n  TSchema extends z.ZodType,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema> = never,\n  TDiscriminatorValue extends DiscriminatorValue<\n    TSchema,\n    TDiscriminatorKey\n  > = never,\n  TFilterType = unknown,\n  TStrict extends boolean = true,\n>(\n  params:\n    | FieldSelectorProps<\n        TSchema,\n        TDiscriminatorKey,\n        TDiscriminatorValue,\n        TFilterType,\n        TStrict\n      >\n    | undefined,\n): z.ZodType | undefined {\n  // biome-ignore lint/correctness/useExhaustiveDependencies: using flattenFieldSelector for stable deps\n  return useMemo(() => {\n    if (!params) {\n      return undefined;\n    }\n    return extractFieldFromSchema(params);\n  }, [...flattenFieldSelector(params)]);\n}\n\n/**\n * Hook to get validation checks from a field's Zod schema.\n *\n * Memoized - only recalculates when schema, name, or discriminator changes.\n * Combines field extraction and check retrieval in one cached operation.\n *\n * @param params - Schema, name, and optional discriminator\n * @returns Array of validation checks (min, max, pattern, etc.) or empty array\n *\n * @example\n * ```tsx\n * function MyFieldHint({ schema, name }: { schema: z.ZodType; name: string }) {\n *   const checks = useFieldChecks({ schema, name });\n *\n *   const maxLength = checks.find(c => c.check === 'max_length');\n *   if (maxLength) {\n *     return <span>Max {maxLength.maximum} characters</span>;\n *   }\n *   return null;\n * }\n * ```\n */\nexport function useFieldChecks<\n  TSchema extends z.ZodType,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema> = never,\n  TDiscriminatorValue extends DiscriminatorValue<\n    TSchema,\n    TDiscriminatorKey\n  > = never,\n  TFilterType = unknown,\n  TStrict extends boolean = true,\n>(\n  params:\n    | FieldSelectorProps<\n        TSchema,\n        TDiscriminatorKey,\n        TDiscriminatorValue,\n        TFilterType,\n        TStrict\n      >\n    | undefined,\n): ZodUnionCheck[] {\n  // biome-ignore lint/correctness/useExhaustiveDependencies: using flattenFieldSelector for stable deps\n  return useMemo(() => {\n    if (!params) {\n      return [];\n    }\n\n    const field = extractFieldFromSchema(params);\n    if (!field) return [];\n    return getFieldChecks(field);\n  }, [...flattenFieldSelector(params)]);\n}\n","import type { Simplify } from '@zod-utils/core';\nimport type { z } from 'zod';\n\n/**\n * Built-in types that should not be recursively transformed.\n * These are treated as leaf values (like primitives) and only get `| null` added.\n * @internal\n */\ntype BuiltInObject =\n  | Date\n  | RegExp\n  | Map<unknown, unknown>\n  | Set<unknown>\n  | WeakMap<object, unknown>\n  | WeakSet<object>\n  | Promise<unknown>\n  | Error;\n\n/**\n * Brand symbol for marking objects that should receive recursive partial transformation.\n * @internal\n */\ndeclare const FormInputBrand: unique symbol;\n\n/**\n * Branded type to mark objects that should have their direct fields made partial.\n * Use with {@link partialFields} helper to mark specific schema objects.\n *\n * @example\n * ```typescript\n * // Objects marked with PartialFields will have their direct fields made optional\n * type MarkedObject = PartialFields<{ name: string; age: number }>;\n * ```\n */\nexport type PartialFields<T> = T & { readonly [FormInputBrand]: true };\n\n/**\n * Helper function to mark a Zod schema so its direct fields become partial.\n *\n * By default, nested objects in form inputs keep their fields strict (only the object\n * itself becomes nullable). Use this helper to opt-in specific objects to have their\n * direct fields also become optional.\n *\n * **Note:** This only affects the direct fields of the marked object. Nested objects\n * within it will still stay strict unless they are also wrapped with `partialFields()`.\n *\n * **Use cases:**\n * - Form input fields that users fill in manually (should be partial)\n * - Objects from selectors/dropdowns should NOT use this (keep strict)\n *\n * @example\n * ```typescript\n * import { partialFields } from '@zod-utils/react-hook-form';\n *\n * const schema = z.object({\n *   price: z.number(),\n *   // User fills in these fields - opt-in to partial\n *   detail: partialFields(z.object({\n *     hotel: z.string(),\n *     nights: z.number(),\n *   })),\n *   // Selected from dropdown - stays strict\n *   agent: z.object({\n *     name: z.string(),\n *     fee: z.number(),\n *   }),\n * });\n *\n * // Result with PartialWithNullableObjects:\n * // detail.hotel  → string | undefined (partial - user input)\n * // detail.nights → number | undefined (partial - user input)\n * // agent.name    → string (strict! - from selector)\n * // agent.fee     → number (strict! - from selector)\n * ```\n */\nexport function partialFields<T extends z.ZodType>(\n  schema: T,\n): z.ZodType<PartialFields<z.infer<T>>, PartialFields<z.input<T>>> {\n  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n  return schema as z.ZodType<\n    PartialFields<z.infer<T>>,\n    PartialFields<z.input<T>>\n  >;\n}\n\n/**\n * Transforms object types for form inputs with selective recursion.\n *\n * **Default behavior (non-recursive):**\n * - **Primitives** (string, number, boolean): optional → `type | undefined`\n * - **Arrays**: optional → `type[] | undefined`\n * - **Built-in objects** (Date, RegExp, etc.): optional and nullable → `type | null | undefined`\n * - **Plain objects**: optional and nullable, but nested fields stay **strict** → `{ strictField: type } | null | undefined`\n *\n * **Opt-in recursive behavior:**\n * - Objects marked with {@link partialFields} will have their nested fields recursively transformed\n *\n * This ensures objects from selectors/dropdowns keep strict types for their fields,\n * while form input fields can be partially filled.\n *\n * @example\n * ```typescript\n * import { partialFields } from '@zod-utils/react-hook-form';\n * import { z } from 'zod';\n *\n * const schema = z.object({\n *   price: z.number(),\n *   detail: partialFields(z.object({ hotel: z.string(), nights: z.number() })),\n *   agent: z.object({ name: z.string(), fee: z.number() }),\n * });\n *\n * type FormInput = PartialWithNullableObjects<z.infer<typeof schema>>;\n * // {\n * //   price?: number;\n * //   detail?: { hotel?: string; nights?: number } | null;  // Recursive!\n * //   agent?: { name: string; fee: number } | null;          // Strict nested!\n * // }\n * ```\n */\nexport type PartialWithNullableObjects<T> = {\n  [K in keyof T]?: T[K] extends readonly unknown[]\n    ? T[K] // Arrays: just optional (via ?), no null, no recursion\n    : T[K] extends BuiltInObject\n      ? T[K] | null // Built-in objects: optional + nullable, no recursion\n      : T[K] extends PartialFields<infer U>\n        ? Simplify<PartialWithNullableObjects<U>> | null // FormInput marked: recurse + null + optional\n        : T[K] extends object\n          ? T[K] | null // Plain objects: optional + nullable, NO recursion (strict nested)\n          : T[K]; // Primitives: just optional (via ?)\n};\n\n/**\n * Transforms all fields to be optional and nullable, with selective recursion.\n *\n * Similar to {@link PartialWithNullableObjects} but also adds `| null` to primitives and arrays.\n *\n * **Default behavior (non-recursive):**\n * - **Primitives**: optional and nullable → `type | null | undefined`\n * - **Arrays**: optional and nullable → `type[] | null | undefined`\n * - **Plain objects**: optional and nullable, but nested fields stay **strict**\n *\n * **Opt-in recursive behavior:**\n * - Objects marked with {@link partialFields} will have their nested fields recursively transformed\n *\n * @example\n * ```typescript\n * type User = { name: string; age: number; profile: { bio: string } };\n * type FormInput = PartialWithAllNullables<User>;\n * // { name?: string | null; age?: number | null; profile?: { bio: string } | null; }\n * // Note: profile.bio stays strict (string, not string | null | undefined)\n * ```\n */\nexport type PartialWithAllNullables<T> = {\n  [K in keyof T]?: T[K] extends readonly unknown[]\n    ? T[K] | null // Arrays: optional + nullable, no recursion\n    : T[K] extends BuiltInObject\n      ? T[K] | null // Built-in objects: optional + nullable, no recursion\n      : T[K] extends PartialFields<infer U>\n        ? Simplify<PartialWithAllNullables<U>> | null // FormInput marked: recurse + null + optional\n        : T[K] extends object\n          ? T[K] | null // Plain objects: optional + nullable, NO recursion (strict nested)\n          : T[K] | null; // Primitives: optional + nullable\n};\n","import { zodResolver } from '@hookform/resolvers/zod';\nimport { type FieldValues, type UseFormProps, useForm } from 'react-hook-form';\nimport type { z } from 'zod';\nimport type {\n  PartialWithAllNullables,\n  PartialWithNullableObjects,\n} from './types';\n\n/**\n * Type-safe React Hook Form wrapper with automatic Zod v4 schema validation and type transformation.\n *\n * This hook eliminates the TypeScript friction between React Hook Form's nullable field values\n * and Zod's strict output types. It uses a two-type schema pattern where:\n * - **Input type** (`PartialWithNullableObjects<TOutput>`): Form fields accept `null | undefined` during editing\n * - **Output type** (`TOutput`): Validated data matches exact schema type (no `null | undefined`)\n *\n * **Key Benefits:**\n * - ✅ No more \"Type 'null' is not assignable to...\" TypeScript errors\n * - ✅ Use `form.setValue()` and `form.reset()` with `null` values freely\n * - ✅ Validated output is still type-safe with exact Zod schema types\n * - ✅ Automatic zodResolver setup - no manual configuration needed\n *\n * @template TInput - The Zod schema input type (accepts nullable/undefined values during form editing)\n * @template TOutput - The Zod schema output type (extends FieldValues)\n * @template TFormInput - The form input type (defaults to PartialWithNullableObjects<TInput>)\n * @template TDefaultValues - The type of default values (inferred from usage for better type safety)\n *\n * @param options - Configuration object\n * @param options.schema - Zod schema with two-type signature `z.ZodType<TOutput, TInput>`\n * @param options.defaultValues - Default form values (shallow partial - nested objects must be complete if provided)\n * @param options.zodResolverOptions - Optional zodResolver configuration\n * @param options....formOptions - All other react-hook-form useForm options\n *\n * @returns React Hook Form instance with type-safe methods\n *\n * @example\n * Basic usage with required fields\n * ```typescript\n * import { useZodForm } from '@zod-utils/react-hook-form';\n * import { z } from 'zod';\n *\n * const schema = z.object({\n *   name: z.string().min(1), // Required field\n *   age: z.number().min(0),\n * }) satisfies z.ZodType<{ name: string; age: number }, any>;\n *\n * function MyForm() {\n *   const form = useZodForm({ schema });\n *\n *   // ✅ These work without type errors:\n *   form.setValue('name', null); // Accepts null during editing\n *   form.reset({ name: null, age: null }); // Reset with null\n *\n *   const onSubmit = (data: { name: string; age: number }) => {\n *     // ✅ data is exact type - no null | undefined\n *     console.log(data.name.toUpperCase()); // Safe to use string methods\n *   };\n *\n *   return <form onSubmit={form.handleSubmit(onSubmit)}>...</form>;\n * }\n * ```\n *\n * @example\n * With default values\n * ```typescript\n * const schema = z.object({\n *   username: z.string(),\n *   email: z.string().email(),\n *   notifications: z.boolean().default(true),\n * }) satisfies z.ZodType<{\n *   username: string;\n *   email: string;\n *   notifications: boolean;\n * }, any>;\n *\n * const form = useZodForm({\n *   schema,\n *   defaultValues: {\n *     username: '',\n *     email: '',\n *     // notifications gets default from schema\n *   },\n * });\n * ```\n *\n * @example\n * Without default values (all fields are optional during editing)\n * ```typescript\n * const schema = z.object({\n *   name: z.string().min(1),\n *   email: z.string().email(),\n *   age: z.number(),\n * }) satisfies z.ZodType<{ name: string; email: string; age: number }, any>;\n *\n * // ✅ No defaultValues needed - fields are optional during editing\n * const form = useZodForm({ schema });\n *\n * // Form fields can be set individually as user types\n * form.setValue('name', 'John');\n * form.setValue('email', 'john@example.com');\n * form.setValue('age', 25);\n *\n * // All fields must be valid on submit (per schema validation)\n * ```\n *\n * @example\n * With optional and nullable fields\n * ```typescript\n * const schema = z.object({\n *   title: z.string(),\n *   description: z.string().optional(), // Optional in output\n *   tags: z.array(z.string()).nullable(), // Nullable in output\n * }) satisfies z.ZodType<{\n *   title: string;\n *   description?: string;\n *   tags: string[] | null;\n * }, any>;\n *\n * const form = useZodForm({ schema });\n *\n * // All fields accept null/undefined during editing\n * form.setValue('title', null);\n * form.setValue('description', undefined);\n * form.setValue('tags', null);\n * ```\n *\n * @example\n * With zodResolver options\n * ```typescript\n * const form = useZodForm({\n *   schema,\n *   zodResolverOptions: {\n *     async: true, // Enable async validation\n *     errorMap: customErrorMap, // Custom error messages\n *   },\n * });\n * ```\n *\n * @example\n * Complete form example\n * ```typescript\n * const userSchema = z.object({\n *   name: z.string().min(1, 'Name is required'),\n *   email: z.string().email('Invalid email'),\n *   age: z.number().min(18, 'Must be 18+'),\n * }) satisfies z.ZodType<{ name: string; email: string; age: number }, any>;\n *\n * function UserForm() {\n *   const form = useZodForm({\n *     schema: userSchema,\n *     defaultValues: { name: '', email: '', age: null },\n *   });\n *\n *   const onSubmit = (data: { name: string; email: string; age: number }) => {\n *     // Type-safe: data has exact types, no null/undefined\n *     console.log(`${data.name} is ${data.age} years old`);\n *   };\n *\n *   return (\n *     <form onSubmit={form.handleSubmit(onSubmit)}>\n *       <input {...form.register('name')} />\n *       <input {...form.register('email')} type=\"email\" />\n *       <input {...form.register('age', { valueAsNumber: true })} type=\"number\" />\n *       <button type=\"submit\">Submit</button>\n *     </form>\n *   );\n * }\n * ```\n *\n * @see {@link PartialWithNullableObjects} for the type transformation utility\n * @see https://react-hook-form.com/docs/useform for React Hook Form documentation\n * @see https://zod.dev for Zod schema documentation\n * @since 0.1.0\n */\nexport const useZodForm = <\n  TInput extends FieldValues,\n  TOutput extends FieldValues,\n  TFormInput extends\n    PartialWithAllNullables<TInput> = PartialWithNullableObjects<TInput>,\n  TDefaultValues extends Partial<TFormInput> | undefined = undefined,\n>({\n  schema,\n  zodResolverOptions,\n  ...formOptions\n}: {\n  schema: z.ZodType<TOutput, TInput>;\n  defaultValues?: TDefaultValues;\n  zodResolverOptions?: Parameters<typeof zodResolver>[1];\n} & Omit<\n  UseFormProps<TFormInput, unknown, TOutput>,\n  'resolver' | 'defaultValues'\n>) => {\n  const resolver = zodResolver(schema, zodResolverOptions);\n\n  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n  return useForm({\n    resolver,\n    ...formOptions,\n  } as unknown as UseFormProps<TFormInput, unknown, TOutput>);\n};\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zod-utils/react-hook-form",
-  "version": "6.2.0",
+  "version": "7.0.0",
   "description": "React Hook Form integration and utilities for Zod schemas",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",