@zod-utils/react-hook-form 0.11.0 → 0.12.0

package/README.md

@@ -63,6 +63,9 @@ npm install @zod-utils/react-hook-form zod react react-hook-form @hookform/resol
 ## Features
 
 - 🎣 **useZodForm** - Automatic type transformation for form inputs (nullable/undefined) while preserving Zod schema validation
+- 📋 **FormSchemaProvider** - React Context for providing schema to form components
+- ✅ **useIsRequiredField** - Hook to check if a field requires valid input
+- 🔄 **Discriminated Union Support** - Full type-safe support for discriminated unions
 - 📦 **All core utilities** - Re-exports everything from `@zod-utils/core`
 - ⚛️ **React-optimized** - Built specifically for React applications
 
@@ -273,6 +276,116 @@ const form2 = useZodForm<
 
 ---
 
+## Form Schema Context
+
+The Form Schema Context system allows you to provide Zod schema context to deeply nested form components without prop drilling.
+
+### `FormSchemaProvider`
+
+Provides schema context to all child components. Use this to wrap your form.
+
+```tsx
+import { FormSchemaProvider } from "@zod-utils/react-hook-form";
+import { z } from "zod";
+
+const schema = z.object({
+  username: z.string().min(3).max(20),
+  email: z.string().email(),
+});
+
+function MyForm() {
+  return (
+    <FormSchemaProvider schema={schema}>
+      <form>
+        <UsernameField />
+        <EmailField />
+      </form>
+    </FormSchemaProvider>
+  );
+}
+```
+
+#### With Discriminated Union
+
+For discriminated unions, pass the discriminator to enable type-safe field access:
+
+```tsx
+const schema = z.discriminatedUnion("mode", [
+  z.object({ mode: z.literal("create"), name: z.string().min(1) }),
+  z.object({ mode: z.literal("edit"), id: z.number() }),
+]);
+
+function CreateModeForm() {
+  return (
+    <FormSchemaProvider
+      schema={schema}
+      discriminator={{ key: "mode", value: "create" }}
+    >
+      <NameField /> {/* Only fields from 'create' variant are available */}
+    </FormSchemaProvider>
+  );
+}
+```
+
+### `useFormSchema()`
+
+Access the schema context from child components:
+
+```tsx
+import { useFormSchema } from "@zod-utils/react-hook-form";
+
+function FieldComponent() {
+  const context = useFormSchema();
+  if (!context) return null;
+
+  const { schema, discriminator } = context;
+  // Use schema for field-level logic
+}
+```
+
+### `useIsRequiredField({ schema, fieldName, discriminator? })`
+
+Hook to check if a field requires valid input (shows validation errors on submit).
+The schema parameter is used for type inference only - the actual schema is retrieved from context.
+
+```tsx
+import { useIsRequiredField } from "@zod-utils/react-hook-form";
+
+function FormLabel({ name, schema }: { name: string; schema: z.ZodType }) {
+  const isRequired = useIsRequiredField({ schema, fieldName: name });
+
+  return (
+    <label>
+      {name}
+      {isRequired && <span className="text-red-500">*</span>}
+    </label>
+  );
+}
+```
+
+### `isRequiredField({ schema, fieldName, discriminator? })`
+
+Standalone function to check if a field requires valid input:
+
+```tsx
+import { isRequiredField } from "@zod-utils/react-hook-form";
+import { z } from "zod";
+
+const schema = z.object({
+  username: z.string().min(1), // Required - min(1) rejects empty
+  email: z.string(), // Not required - accepts empty string
+  age: z.number(), // Required - numbers reject empty input
+  bio: z.string().optional(), // Not required - optional
+});
+
+isRequiredField({ schema, fieldName: "username" }); // true
+isRequiredField({ schema, fieldName: "email" }); // false
+isRequiredField({ schema, fieldName: "age" }); // true
+isRequiredField({ schema, fieldName: "bio" }); // false
+```
+
+---
+
 ## Core Utilities (Re-exported)
 
 All utilities from `@zod-utils/core` are re-exported for convenience:
@@ -286,10 +399,23 @@ import {
   removeDefault,
   extractDefaultValue,
   type Simplify,
+  type ZodUnionCheck,
+
+  // Form schema context
+  FormSchemaContext,
+  FormSchemaProvider,
+  useFormSchema,
+  useIsRequiredField,
+  isRequiredField,
 
-  // Type utilities (react-hook-form specific)
+  // Type utilities
   type PartialWithNullableObjects,
   type PartialWithAllNullables,
+  type Discriminator,
+  type DiscriminatorKey,
+  type DiscriminatorValue,
+  type InferredFieldValues,
+  type ValidFieldName,
 } from "@zod-utils/react-hook-form";
 ```
 

package/dist/index.d.mts

@@ -1,9 +1,185 @@
-import { Simplify } from '@zod-utils/core';
+import { DiscriminatorKey, DiscriminatorValue, Discriminator, Simplify } from '@zod-utils/core';
 export * from '@zod-utils/core';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { Context, ReactNode } from 'react';
+import { z } from 'zod';
 import * as react_hook_form from 'react-hook-form';
-import { FieldValues, UseFormProps } from 'react-hook-form';
+import { FieldValues, Path, UseFormProps } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
-import { z } from 'zod';
+
+/**
+ * Type for the FormSchemaContext with full generic support.
+ * @internal
+ */
+type FormSchemaContextType<TSchema extends z.ZodType, TDiscriminatorKey extends DiscriminatorKey<TSchema>, TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>> = Context<{
+    schema: TSchema;
+    discriminator?: Discriminator<TSchema, TDiscriminatorKey, TDiscriminatorValue>;
+} | null>;
+/**
+ * Context value type for FormSchemaContext.
+ */
+type FormSchemaContextValue<TSchema extends z.ZodType, TDiscriminatorKey extends DiscriminatorKey<TSchema>, TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>> = {
+    schema: TSchema;
+    discriminator?: Discriminator<TSchema, TDiscriminatorKey, TDiscriminatorValue>;
+} | null;
+/**
+ * React Context for providing Zod schema to form components.
+ *
+ * Use with {@link FormSchemaProvider} to provide schema context, and
+ * {@link useFormSchema} to consume it in child components.
+ */
+declare const FormSchemaContext: Context<{
+    schema: z.ZodType;
+    discriminator?: {
+        key: unknown;
+        value: unknown;
+    };
+} | null>;
+/**
+ * Hook to access the form schema from context.
+ *
+ * The optional `_params` argument is used for TypeScript type inference only.
+ * Pass your schema to get proper type narrowing of the context value.
+ *
+ * @param _params - Optional params for type inference (not used at runtime)
+ * @returns The schema context value or null if not within a provider
+ *
+ * @example
+ * ```tsx
+ * // Without type params (returns generic context)
+ * function MyFormField() {
+ *   const context = useFormSchema();
+ *   if (!context) return null;
+ *
+ *   const { schema, discriminator } = context;
+ *   // Use schema for validation or field extraction
+ * }
+ *
+ * // With type params (for type-safe schema access)
+ * function TypedFormField() {
+ *   const context = useFormSchema({ schema: mySchema });
+ *   // context.schema is now typed as typeof mySchema
+ * }
+ * ```
+ */
+declare function useFormSchema<TSchema extends z.ZodType = z.ZodType, TDiscriminatorKey extends DiscriminatorKey<TSchema> = DiscriminatorKey<TSchema>, TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey> = DiscriminatorValue<TSchema, TDiscriminatorKey>>(_params?: {
+    schema: TSchema;
+    discriminator?: Discriminator<TSchema, TDiscriminatorKey, TDiscriminatorValue>;
+}): FormSchemaContextValue<TSchema, TDiscriminatorKey, TDiscriminatorValue>;
+/**
+ * Provider component that makes Zod schema available to all child components.
+ *
+ * Use this to wrap your form and provide schema context to nested components
+ * like field labels and validation indicators.
+ *
+ * @example
+ * Basic usage with ZodObject
+ * ```tsx
+ * const schema = z.object({
+ *   name: z.string(),
+ *   email: z.string().email().optional()
+ * });
+ *
+ * <FormSchemaProvider schema={schema}>
+ *   <YourFormComponents />
+ * </FormSchemaProvider>
+ * ```
+ *
+ * @example
+ * Usage with discriminated union
+ * ```tsx
+ * const schema = z.discriminatedUnion('mode', [
+ *   z.object({ mode: z.literal('create'), name: z.string() }),
+ *   z.object({ mode: z.literal('edit'), id: z.number() })
+ * ]);
+ *
+ * <FormSchemaProvider
+ *   schema={schema}
+ *   discriminator={{ key: 'mode', value: 'create' }}
+ * >
+ *   <YourFormComponents />
+ * </FormSchemaProvider>
+ * ```
+ */
+declare function FormSchemaProvider<TSchema extends z.ZodType, TDiscriminatorKey extends DiscriminatorKey<TSchema>, TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>>({ schema, discriminator, children, }: {
+    schema: TSchema;
+    discriminator?: Discriminator<TSchema, TDiscriminatorKey, TDiscriminatorValue>;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to check if a field requires valid input based on the Zod schema.
+ *
+ * Uses the schema from {@link FormSchemaContext} to determine if a field
+ * will show validation errors when submitted with empty/invalid input.
+ *
+ * @param params - Schema, field name, and optional discriminator (schema used for type inference)
+ * @returns true if the field requires valid input, false otherwise
+ *
+ * @example
+ * ```tsx
+ * function MyFieldLabel({ name, schema }: { name: string; schema: z.ZodType }) {
+ *   const isRequired = useIsRequiredField({ schema, fieldName: name });
+ *
+ *   return (
+ *     <label>
+ *       {name}
+ *       {isRequired && <span className="text-red-500">*</span>}
+ *     </label>
+ *   );
+ * }
+ * ```
+ */
+declare function useIsRequiredField<TSchema extends z.ZodType, TName extends keyof Extract<Required<z.input<TSchema>>, Record<TDiscriminatorKey, TDiscriminatorValue>>, TDiscriminatorKey extends DiscriminatorKey<TSchema>, TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>>({ fieldName, ...props }: {
+    schema: TSchema;
+    fieldName: TName;
+    discriminator?: Discriminator<TSchema, TDiscriminatorKey, TDiscriminatorValue>;
+}): boolean;
+/**
+ * Determines if a field requires valid input (will show validation errors on empty/invalid input).
+ *
+ * Uses `requiresValidInput` from `@zod-utils/core` which checks the underlying field after
+ * removing defaults. This tells you if the field will error when user submits empty input.
+ *
+ * Returns false if the underlying field accepts:
+ * - `undefined` (via `.optional()`)
+ * - `null` (via `.nullable()`)
+ * - Empty strings (plain `z.string()` without `.min(1)`)
+ * - Empty arrays (plain `z.array()` without `.min(1)`)
+ *
+ * @param options - Schema, field name, and optional discriminator
+ * @returns true if the field requires valid input, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   name: z.string().min(1),
+ *   bio: z.string().optional(),
+ * });
+ *
+ * isRequiredField({ schema, fieldName: 'name' }); // true
+ * isRequiredField({ schema, fieldName: 'bio' });  // false
+ * ```
+ *
+ * @example
+ * With discriminated union
+ * ```typescript
+ * const schema = z.discriminatedUnion('mode', [
+ *   z.object({ mode: z.literal('create'), name: z.string().min(1) }),
+ *   z.object({ mode: z.literal('edit'), id: z.number() }),
+ * ]);
+ *
+ * isRequiredField({
+ *   schema,
+ *   fieldName: 'name',
+ *   discriminator: { key: 'mode', value: 'create' },
+ * }); // true
+ * ```
+ */
+declare function isRequiredField<TSchema extends z.ZodType, TName extends keyof Extract<Required<z.input<TSchema>>, Record<TDiscriminatorKey, TDiscriminatorValue>>, TDiscriminatorKey extends DiscriminatorKey<TSchema>, TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>>({ schema, fieldName, discriminator, }: {
+    schema: TSchema;
+    fieldName: TName;
+    discriminator?: Discriminator<TSchema, TDiscriminatorKey, TDiscriminatorValue>;
+}): boolean;
 
 /**
  * Helper type that adds `null` to object-type fields only (excludes arrays).
@@ -52,6 +228,38 @@ type PartialWithNullableObjects<T> = Simplify<Partial<AddNullToObjects<T>>>;
 type PartialWithAllNullables<T> = {
     [K in keyof T]?: T[K] | null;
 };
+/**
+ * Infers field values from a Zod schema compatible with React Hook Form's FieldValues.
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({ name: z.string() });
+ * type Values = InferredFieldValues<typeof schema>;
+ * // { name: string } & FieldValues
+ * ```
+ */
+type InferredFieldValues<TSchema extends z.ZodType> = z.input<TSchema> & FieldValues;
+/**
+ * Type-safe field names for a specific discriminator value.
+ *
+ * Narrows field names to only those that exist for the given discriminator value
+ * in a discriminated union schema.
+ *
+ * @example
+ * ```typescript
+ * const schema = z.discriminatedUnion('mode', [
+ *   z.object({ mode: z.literal('create'), name: z.string() }),
+ *   z.object({ mode: z.literal('edit'), id: z.number() }),
+ * ]);
+ *
+ * type CreateFields = ValidFieldName<typeof schema, 'mode', 'create'>;
+ * // "mode" | "name"
+ *
+ * type EditFields = ValidFieldName<typeof schema, 'mode', 'edit'>;
+ * // "mode" | "id"
+ * ```
+ */
+type ValidFieldName<TSchema extends z.ZodType, TDiscriminatorKey extends DiscriminatorKey<TSchema>, TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>, TFieldValues extends InferredFieldValues<TSchema> = InferredFieldValues<TSchema>> = keyof Extract<Required<z.input<TSchema>>, Record<TDiscriminatorKey, TDiscriminatorValue>> & Path<TFieldValues>;
 
 /**
  * Type-safe React Hook Form wrapper with automatic Zod v4 schema validation and type transformation.
@@ -223,4 +431,4 @@ declare const useZodForm: <TInput extends FieldValues, TOutput extends FieldValu
     zodResolverOptions?: Parameters<typeof zodResolver>[1];
 } & Omit<UseFormProps<TFormInput, unknown, TOutput>, "resolver" | "defaultValues">) => react_hook_form.UseFormReturn<TFormInput, unknown, TOutput>;
 
-export { type PartialWithAllNullables, type PartialWithNullableObjects, useZodForm };
+export { FormSchemaContext, type FormSchemaContextType, type FormSchemaContextValue, FormSchemaProvider, type InferredFieldValues, type PartialWithAllNullables, type PartialWithNullableObjects, type ValidFieldName, isRequiredField, useFormSchema, useIsRequiredField, useZodForm };

package/dist/index.d.ts

@@ -1,9 +1,185 @@
-import { Simplify } from '@zod-utils/core';
+import { DiscriminatorKey, DiscriminatorValue, Discriminator, Simplify } from '@zod-utils/core';
 export * from '@zod-utils/core';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { Context, ReactNode } from 'react';
+import { z } from 'zod';
 import * as react_hook_form from 'react-hook-form';
-import { FieldValues, UseFormProps } from 'react-hook-form';
+import { FieldValues, Path, UseFormProps } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
-import { z } from 'zod';
+
+/**
+ * Type for the FormSchemaContext with full generic support.
+ * @internal
+ */
+type FormSchemaContextType<TSchema extends z.ZodType, TDiscriminatorKey extends DiscriminatorKey<TSchema>, TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>> = Context<{
+    schema: TSchema;
+    discriminator?: Discriminator<TSchema, TDiscriminatorKey, TDiscriminatorValue>;
+} | null>;
+/**
+ * Context value type for FormSchemaContext.
+ */
+type FormSchemaContextValue<TSchema extends z.ZodType, TDiscriminatorKey extends DiscriminatorKey<TSchema>, TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>> = {
+    schema: TSchema;
+    discriminator?: Discriminator<TSchema, TDiscriminatorKey, TDiscriminatorValue>;
+} | null;
+/**
+ * React Context for providing Zod schema to form components.
+ *
+ * Use with {@link FormSchemaProvider} to provide schema context, and
+ * {@link useFormSchema} to consume it in child components.
+ */
+declare const FormSchemaContext: Context<{
+    schema: z.ZodType;
+    discriminator?: {
+        key: unknown;
+        value: unknown;
+    };
+} | null>;
+/**
+ * Hook to access the form schema from context.
+ *
+ * The optional `_params` argument is used for TypeScript type inference only.
+ * Pass your schema to get proper type narrowing of the context value.
+ *
+ * @param _params - Optional params for type inference (not used at runtime)
+ * @returns The schema context value or null if not within a provider
+ *
+ * @example
+ * ```tsx
+ * // Without type params (returns generic context)
+ * function MyFormField() {
+ *   const context = useFormSchema();
+ *   if (!context) return null;
+ *
+ *   const { schema, discriminator } = context;
+ *   // Use schema for validation or field extraction
+ * }
+ *
+ * // With type params (for type-safe schema access)
+ * function TypedFormField() {
+ *   const context = useFormSchema({ schema: mySchema });
+ *   // context.schema is now typed as typeof mySchema
+ * }
+ * ```
+ */
+declare function useFormSchema<TSchema extends z.ZodType = z.ZodType, TDiscriminatorKey extends DiscriminatorKey<TSchema> = DiscriminatorKey<TSchema>, TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey> = DiscriminatorValue<TSchema, TDiscriminatorKey>>(_params?: {
+    schema: TSchema;
+    discriminator?: Discriminator<TSchema, TDiscriminatorKey, TDiscriminatorValue>;
+}): FormSchemaContextValue<TSchema, TDiscriminatorKey, TDiscriminatorValue>;
+/**
+ * Provider component that makes Zod schema available to all child components.
+ *
+ * Use this to wrap your form and provide schema context to nested components
+ * like field labels and validation indicators.
+ *
+ * @example
+ * Basic usage with ZodObject
+ * ```tsx
+ * const schema = z.object({
+ *   name: z.string(),
+ *   email: z.string().email().optional()
+ * });
+ *
+ * <FormSchemaProvider schema={schema}>
+ *   <YourFormComponents />
+ * </FormSchemaProvider>
+ * ```
+ *
+ * @example
+ * Usage with discriminated union
+ * ```tsx
+ * const schema = z.discriminatedUnion('mode', [
+ *   z.object({ mode: z.literal('create'), name: z.string() }),
+ *   z.object({ mode: z.literal('edit'), id: z.number() })
+ * ]);
+ *
+ * <FormSchemaProvider
+ *   schema={schema}
+ *   discriminator={{ key: 'mode', value: 'create' }}
+ * >
+ *   <YourFormComponents />
+ * </FormSchemaProvider>
+ * ```
+ */
+declare function FormSchemaProvider<TSchema extends z.ZodType, TDiscriminatorKey extends DiscriminatorKey<TSchema>, TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>>({ schema, discriminator, children, }: {
+    schema: TSchema;
+    discriminator?: Discriminator<TSchema, TDiscriminatorKey, TDiscriminatorValue>;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to check if a field requires valid input based on the Zod schema.
+ *
+ * Uses the schema from {@link FormSchemaContext} to determine if a field
+ * will show validation errors when submitted with empty/invalid input.
+ *
+ * @param params - Schema, field name, and optional discriminator (schema used for type inference)
+ * @returns true if the field requires valid input, false otherwise
+ *
+ * @example
+ * ```tsx
+ * function MyFieldLabel({ name, schema }: { name: string; schema: z.ZodType }) {
+ *   const isRequired = useIsRequiredField({ schema, fieldName: name });
+ *
+ *   return (
+ *     <label>
+ *       {name}
+ *       {isRequired && <span className="text-red-500">*</span>}
+ *     </label>
+ *   );
+ * }
+ * ```
+ */
+declare function useIsRequiredField<TSchema extends z.ZodType, TName extends keyof Extract<Required<z.input<TSchema>>, Record<TDiscriminatorKey, TDiscriminatorValue>>, TDiscriminatorKey extends DiscriminatorKey<TSchema>, TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>>({ fieldName, ...props }: {
+    schema: TSchema;
+    fieldName: TName;
+    discriminator?: Discriminator<TSchema, TDiscriminatorKey, TDiscriminatorValue>;
+}): boolean;
+/**
+ * Determines if a field requires valid input (will show validation errors on empty/invalid input).
+ *
+ * Uses `requiresValidInput` from `@zod-utils/core` which checks the underlying field after
+ * removing defaults. This tells you if the field will error when user submits empty input.
+ *
+ * Returns false if the underlying field accepts:
+ * - `undefined` (via `.optional()`)
+ * - `null` (via `.nullable()`)
+ * - Empty strings (plain `z.string()` without `.min(1)`)
+ * - Empty arrays (plain `z.array()` without `.min(1)`)
+ *
+ * @param options - Schema, field name, and optional discriminator
+ * @returns true if the field requires valid input, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   name: z.string().min(1),
+ *   bio: z.string().optional(),
+ * });
+ *
+ * isRequiredField({ schema, fieldName: 'name' }); // true
+ * isRequiredField({ schema, fieldName: 'bio' });  // false
+ * ```
+ *
+ * @example
+ * With discriminated union
+ * ```typescript
+ * const schema = z.discriminatedUnion('mode', [
+ *   z.object({ mode: z.literal('create'), name: z.string().min(1) }),
+ *   z.object({ mode: z.literal('edit'), id: z.number() }),
+ * ]);
+ *
+ * isRequiredField({
+ *   schema,
+ *   fieldName: 'name',
+ *   discriminator: { key: 'mode', value: 'create' },
+ * }); // true
+ * ```
+ */
+declare function isRequiredField<TSchema extends z.ZodType, TName extends keyof Extract<Required<z.input<TSchema>>, Record<TDiscriminatorKey, TDiscriminatorValue>>, TDiscriminatorKey extends DiscriminatorKey<TSchema>, TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>>({ schema, fieldName, discriminator, }: {
+    schema: TSchema;
+    fieldName: TName;
+    discriminator?: Discriminator<TSchema, TDiscriminatorKey, TDiscriminatorValue>;
+}): boolean;
 
 /**
  * Helper type that adds `null` to object-type fields only (excludes arrays).
@@ -52,6 +228,38 @@ type PartialWithNullableObjects<T> = Simplify<Partial<AddNullToObjects<T>>>;
 type PartialWithAllNullables<T> = {
     [K in keyof T]?: T[K] | null;
 };
+/**
+ * Infers field values from a Zod schema compatible with React Hook Form's FieldValues.
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({ name: z.string() });
+ * type Values = InferredFieldValues<typeof schema>;
+ * // { name: string } & FieldValues
+ * ```
+ */
+type InferredFieldValues<TSchema extends z.ZodType> = z.input<TSchema> & FieldValues;
+/**
+ * Type-safe field names for a specific discriminator value.
+ *
+ * Narrows field names to only those that exist for the given discriminator value
+ * in a discriminated union schema.
+ *
+ * @example
+ * ```typescript
+ * const schema = z.discriminatedUnion('mode', [
+ *   z.object({ mode: z.literal('create'), name: z.string() }),
+ *   z.object({ mode: z.literal('edit'), id: z.number() }),
+ * ]);
+ *
+ * type CreateFields = ValidFieldName<typeof schema, 'mode', 'create'>;
+ * // "mode" | "name"
+ *
+ * type EditFields = ValidFieldName<typeof schema, 'mode', 'edit'>;
+ * // "mode" | "id"
+ * ```
+ */
+type ValidFieldName<TSchema extends z.ZodType, TDiscriminatorKey extends DiscriminatorKey<TSchema>, TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>, TFieldValues extends InferredFieldValues<TSchema> = InferredFieldValues<TSchema>> = keyof Extract<Required<z.input<TSchema>>, Record<TDiscriminatorKey, TDiscriminatorValue>> & Path<TFieldValues>;
 
 /**
  * Type-safe React Hook Form wrapper with automatic Zod v4 schema validation and type transformation.
@@ -223,4 +431,4 @@ declare const useZodForm: <TInput extends FieldValues, TOutput extends FieldValu
     zodResolverOptions?: Parameters<typeof zodResolver>[1];
 } & Omit<UseFormProps<TFormInput, unknown, TOutput>, "resolver" | "defaultValues">) => react_hook_form.UseFormReturn<TFormInput, unknown, TOutput>;
 
-export { type PartialWithAllNullables, type PartialWithNullableObjects, useZodForm };
+export { FormSchemaContext, type FormSchemaContextType, type FormSchemaContextValue, FormSchemaProvider, type InferredFieldValues, type PartialWithAllNullables, type PartialWithNullableObjects, type ValidFieldName, isRequiredField, useFormSchema, useIsRequiredField, useZodForm };

package/dist/index.js

@@ -1,6 +1,8 @@
 'use strict';
 
 var core = require('@zod-utils/core');
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
 var zod = require('@hookform/resolvers/zod');
 var reactHookForm = require('react-hook-form');
 
@@ -32,6 +34,51 @@ var __objRest = (source, exclude) => {
     }
   return target;
 };
+var FormSchemaContext = react.createContext(null);
+function useFormSchema(_params) {
+  return react.useContext(
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    FormSchemaContext
+  );
+}
+function FormSchemaProvider({
+  schema,
+  discriminator,
+  children
+}) {
+  return /* @__PURE__ */ jsxRuntime.jsx(FormSchemaContext.Provider, { value: { schema, discriminator }, children });
+}
+function useIsRequiredField(_a) {
+  var _b = _a, {
+    fieldName
+  } = _b; __objRest(_b, [
+    "fieldName"
+  ]);
+  const context = useFormSchema();
+  if (!context) {
+    return false;
+  }
+  return isRequiredField({
+    schema: context.schema,
+    fieldName,
+    discriminator: context.discriminator
+  });
+}
+function isRequiredField({
+  schema,
+  fieldName,
+  discriminator
+}) {
+  const field = core.extractFieldFromSchema({
+    schema,
+    fieldName,
+    discriminator
+  });
+  if (!field) {
+    return false;
+  }
+  return core.requiresValidInput(field);
+}
 var useZodForm = (_a) => {
   var _b = _a, {
     schema,
@@ -46,6 +93,11 @@ var useZodForm = (_a) => {
   }, formOptions));
 };
 
+exports.FormSchemaContext = FormSchemaContext;
+exports.FormSchemaProvider = FormSchemaProvider;
+exports.isRequiredField = isRequiredField;
+exports.useFormSchema = useFormSchema;
+exports.useIsRequiredField = useIsRequiredField;
 exports.useZodForm = useZodForm;
 Object.keys(core).forEach(function (k) {
   if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/use-zod-form.ts"],"names":["zodResolver","useForm"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4KO,IAAM,UAAA,GAAa,CAKxB,EAAA,KAWI;AAXJ,EAAA,IAAA,EAAA,GAAA,EAAA,EACA;AAAA,IAAA,MAAA;AAAA,IACA;AAAA,GAnLF,GAiLE,EAAA,EAGG,WAAA,GAAA,SAAA,CAHH,EAAA,EAGG;AAAA,IAFH,QAAA;AAAA,IACA;AAAA,GAAA,CAAA;AAUA,EAAA,MAAM,QAAA,GAAWA,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 { 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 TOutput - The Zod schema output type (extends FieldValues)\n * @template TInput - The Zod schema input type (accepts nullable/undefined values during form editing)\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>({\n  schema,\n  zodResolverOptions,\n  ...formOptions\n}: {\n  schema: z.ZodType<TOutput, TInput>;\n  defaultValues?: TFormInput;\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/context.tsx","../src/use-zod-form.ts"],"names":["createContext","useContext","jsx","extractFieldFromSchema","requiresValidInput","zodResolver","useForm"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmDO,IAAM,iBAAA,GAAoBA,oBAMvB,IAAI;AA6BP,SAAS,cAUd,OAAA,EAQyE;AACzE,EAAA,OAAOC,gBAAA;AAAA;AAAA,IAEL;AAAA,GAQF;AACF;AAqCO,SAAS,kBAAA,CAId;AAAA,EACA,MAAA;AAAA,EACA,aAAA;AAAA,EACA;AACF,CAAA,EAQG;AACD,EAAA,uBACEC,cAAA,CAAC,kBAAkB,QAAA,EAAlB,EAA2B,OAAO,EAAE,MAAA,EAAQ,aAAA,EAAc,EACxD,QAAA,EACH,CAAA;AAEJ;AAyBO,SAAS,mBAQd,EAAA,EAWU;AAXV,EAAA,IAAA,EAAA,GAAA,EAAA,CAAA,CACA;AAAA,IAAA;AAAA,GAjNF,GAgNE,EAAA,CAAA,CAEG,SAAA,CAFH,EAAA,EAEG;AAAA,IADH;AAAA,GAAA;AAWA,EAAA,MAAM,OAAA,GAAU,cAIT,CAAA;AAEP,EAAA,IAAI,CAAC,OAAA,EAAS;AACZ,IAAA,OAAO,KAAA;AAAA,EACT;AAEA,EAAA,OAAO,eAAA,CAAgB;AAAA,IACrB,QAAQ,OAAA,CAAQ,MAAA;AAAA,IAChB,SAAA;AAAA,IACA,eAAe,OAAA,CAAQ;AAAA,GACxB,CAAA;AACH;AA2CO,SAAS,eAAA,CAQd;AAAA,EACA,MAAA;AAAA,EACA,SAAA;AAAA,EACA;AACF,CAAA,EAQY;AACV,EAAA,MAAM,QAAQC,2BAAA,CAAuB;AAAA,IACnC,MAAA;AAAA,IACA,SAAA;AAAA,IACA;AAAA,GACD,CAAA;AAED,EAAA,IAAI,CAAC,KAAA,EAAO;AACV,IAAA,OAAO,KAAA;AAAA,EACT;AAEA,EAAA,OAAOC,wBAAmB,KAAK,CAAA;AACjC;AC1IO,IAAM,UAAA,GAAa,CAKxB,EAAA,KAWI;AAXJ,EAAA,IAAA,EAAA,GAAA,EAAA,EACA;AAAA,IAAA,MAAA;AAAA,IACA;AAAA,GAnLF,GAiLE,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":["'use client';\n\nimport {\n  type Discriminator,\n  type DiscriminatorKey,\n  type DiscriminatorValue,\n  extractFieldFromSchema,\n  requiresValidInput,\n} from '@zod-utils/core';\nimport { type Context, createContext, type ReactNode, useContext } from 'react';\nimport type { z } from 'zod';\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<{\n  schema: TSchema;\n  discriminator?: Discriminator<\n    TSchema,\n    TDiscriminatorKey,\n    TDiscriminatorValue\n  >;\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> = {\n  schema: TSchema;\n  discriminator?: Discriminator<\n    TSchema,\n    TDiscriminatorKey,\n    TDiscriminatorValue\n  >;\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?: {\n    schema: TSchema;\n    discriminator?: Discriminator<\n      TSchema,\n      TDiscriminatorKey,\n      TDiscriminatorValue\n    >;\n  },\n): FormSchemaContextValue<TSchema, TDiscriminatorKey, TDiscriminatorValue> {\n  return useContext(\n    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n    FormSchemaContext as Context<{\n      schema: TSchema;\n      discriminator?: Discriminator<\n        TSchema,\n        TDiscriminatorKey,\n        TDiscriminatorValue\n      >;\n    } | null>,\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}: {\n  schema: TSchema;\n  discriminator?: Discriminator<\n    TSchema,\n    TDiscriminatorKey,\n    TDiscriminatorValue\n  >;\n  children: ReactNode;\n}) {\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 * Uses the schema from {@link FormSchemaContext} to determine if a field\n * will show validation errors when submitted with empty/invalid input.\n *\n * @param params - Schema, field name, and optional discriminator (schema used for type inference)\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, fieldName: 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  TName extends keyof Extract<\n    Required<z.input<TSchema>>,\n    Record<TDiscriminatorKey, TDiscriminatorValue>\n  >,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema>,\n  TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>,\n>({\n  fieldName,\n  ...props\n}: {\n  schema: TSchema;\n  fieldName: TName;\n  discriminator?: Discriminator<\n    TSchema,\n    TDiscriminatorKey,\n    TDiscriminatorValue\n  >;\n}): boolean {\n  const context = useFormSchema<\n    TSchema,\n    TDiscriminatorKey,\n    TDiscriminatorValue\n  >(props);\n\n  if (!context) {\n    return false;\n  }\n\n  return isRequiredField({\n    schema: context.schema,\n    fieldName,\n    discriminator: context.discriminator,\n  });\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, fieldName: 'name' }); // true\n * isRequiredField({ schema, fieldName: '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 *   fieldName: 'name',\n *   discriminator: { key: 'mode', value: 'create' },\n * }); // true\n * ```\n */\nexport function isRequiredField<\n  TSchema extends z.ZodType,\n  TName extends keyof Extract<\n    Required<z.input<TSchema>>,\n    Record<TDiscriminatorKey, TDiscriminatorValue>\n  >,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema>,\n  TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>,\n>({\n  schema,\n  fieldName,\n  discriminator,\n}: {\n  schema: TSchema;\n  fieldName: TName;\n  discriminator?: Discriminator<\n    TSchema,\n    TDiscriminatorKey,\n    TDiscriminatorValue\n  >;\n}): boolean {\n  const field = extractFieldFromSchema({\n    schema,\n    fieldName,\n    discriminator,\n  });\n\n  if (!field) {\n    return false;\n  }\n\n  return requiresValidInput(field);\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 TOutput - The Zod schema output type (extends FieldValues)\n * @template TInput - The Zod schema input type (accepts nullable/undefined values during form editing)\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>({\n  schema,\n  zodResolverOptions,\n  ...formOptions\n}: {\n  schema: z.ZodType<TOutput, TInput>;\n  defaultValues?: TFormInput;\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

@@ -1,4 +1,7 @@
+import { extractFieldFromSchema, requiresValidInput } from '@zod-utils/core';
 export * from '@zod-utils/core';
+import { createContext, useContext } from 'react';
+import { jsx } from 'react/jsx-runtime';
 import { zodResolver } from '@hookform/resolvers/zod';
 import { useForm } from 'react-hook-form';
 
@@ -30,6 +33,51 @@ var __objRest = (source, exclude) => {
     }
   return target;
 };
+var FormSchemaContext = createContext(null);
+function useFormSchema(_params) {
+  return useContext(
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    FormSchemaContext
+  );
+}
+function FormSchemaProvider({
+  schema,
+  discriminator,
+  children
+}) {
+  return /* @__PURE__ */ jsx(FormSchemaContext.Provider, { value: { schema, discriminator }, children });
+}
+function useIsRequiredField(_a) {
+  var _b = _a, {
+    fieldName
+  } = _b; __objRest(_b, [
+    "fieldName"
+  ]);
+  const context = useFormSchema();
+  if (!context) {
+    return false;
+  }
+  return isRequiredField({
+    schema: context.schema,
+    fieldName,
+    discriminator: context.discriminator
+  });
+}
+function isRequiredField({
+  schema,
+  fieldName,
+  discriminator
+}) {
+  const field = extractFieldFromSchema({
+    schema,
+    fieldName,
+    discriminator
+  });
+  if (!field) {
+    return false;
+  }
+  return requiresValidInput(field);
+}
 var useZodForm = (_a) => {
   var _b = _a, {
     schema,
@@ -44,6 +92,6 @@ var useZodForm = (_a) => {
   }, formOptions));
 };
 
-export { useZodForm };
+export { FormSchemaContext, FormSchemaProvider, isRequiredField, useFormSchema, useIsRequiredField, useZodForm };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/use-zod-form.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4KO,IAAM,UAAA,GAAa,CAKxB,EAAA,KAWI;AAXJ,EAAA,IAAA,EAAA,GAAA,EAAA,EACA;AAAA,IAAA,MAAA;AAAA,IACA;AAAA,GAnLF,GAiLE,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 { 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 TOutput - The Zod schema output type (extends FieldValues)\n * @template TInput - The Zod schema input type (accepts nullable/undefined values during form editing)\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>({\n  schema,\n  zodResolverOptions,\n  ...formOptions\n}: {\n  schema: z.ZodType<TOutput, TInput>;\n  defaultValues?: TFormInput;\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/context.tsx","../src/use-zod-form.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmDO,IAAM,iBAAA,GAAoB,cAMvB,IAAI;AA6BP,SAAS,cAUd,OAAA,EAQyE;AACzE,EAAA,OAAO,UAAA;AAAA;AAAA,IAEL;AAAA,GAQF;AACF;AAqCO,SAAS,kBAAA,CAId;AAAA,EACA,MAAA;AAAA,EACA,aAAA;AAAA,EACA;AACF,CAAA,EAQG;AACD,EAAA,uBACE,GAAA,CAAC,kBAAkB,QAAA,EAAlB,EAA2B,OAAO,EAAE,MAAA,EAAQ,aAAA,EAAc,EACxD,QAAA,EACH,CAAA;AAEJ;AAyBO,SAAS,mBAQd,EAAA,EAWU;AAXV,EAAA,IAAA,EAAA,GAAA,EAAA,CAAA,CACA;AAAA,IAAA;AAAA,GAjNF,GAgNE,EAAA,CAAA,CAEG,SAAA,CAFH,EAAA,EAEG;AAAA,IADH;AAAA,GAAA;AAWA,EAAA,MAAM,OAAA,GAAU,cAIT,CAAA;AAEP,EAAA,IAAI,CAAC,OAAA,EAAS;AACZ,IAAA,OAAO,KAAA;AAAA,EACT;AAEA,EAAA,OAAO,eAAA,CAAgB;AAAA,IACrB,QAAQ,OAAA,CAAQ,MAAA;AAAA,IAChB,SAAA;AAAA,IACA,eAAe,OAAA,CAAQ;AAAA,GACxB,CAAA;AACH;AA2CO,SAAS,eAAA,CAQd;AAAA,EACA,MAAA;AAAA,EACA,SAAA;AAAA,EACA;AACF,CAAA,EAQY;AACV,EAAA,MAAM,QAAQ,sBAAA,CAAuB;AAAA,IACnC,MAAA;AAAA,IACA,SAAA;AAAA,IACA;AAAA,GACD,CAAA;AAED,EAAA,IAAI,CAAC,KAAA,EAAO;AACV,IAAA,OAAO,KAAA;AAAA,EACT;AAEA,EAAA,OAAO,mBAAmB,KAAK,CAAA;AACjC;AC1IO,IAAM,UAAA,GAAa,CAKxB,EAAA,KAWI;AAXJ,EAAA,IAAA,EAAA,GAAA,EAAA,EACA;AAAA,IAAA,MAAA;AAAA,IACA;AAAA,GAnLF,GAiLE,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":["'use client';\n\nimport {\n  type Discriminator,\n  type DiscriminatorKey,\n  type DiscriminatorValue,\n  extractFieldFromSchema,\n  requiresValidInput,\n} from '@zod-utils/core';\nimport { type Context, createContext, type ReactNode, useContext } from 'react';\nimport type { z } from 'zod';\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<{\n  schema: TSchema;\n  discriminator?: Discriminator<\n    TSchema,\n    TDiscriminatorKey,\n    TDiscriminatorValue\n  >;\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> = {\n  schema: TSchema;\n  discriminator?: Discriminator<\n    TSchema,\n    TDiscriminatorKey,\n    TDiscriminatorValue\n  >;\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?: {\n    schema: TSchema;\n    discriminator?: Discriminator<\n      TSchema,\n      TDiscriminatorKey,\n      TDiscriminatorValue\n    >;\n  },\n): FormSchemaContextValue<TSchema, TDiscriminatorKey, TDiscriminatorValue> {\n  return useContext(\n    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n    FormSchemaContext as Context<{\n      schema: TSchema;\n      discriminator?: Discriminator<\n        TSchema,\n        TDiscriminatorKey,\n        TDiscriminatorValue\n      >;\n    } | null>,\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}: {\n  schema: TSchema;\n  discriminator?: Discriminator<\n    TSchema,\n    TDiscriminatorKey,\n    TDiscriminatorValue\n  >;\n  children: ReactNode;\n}) {\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 * Uses the schema from {@link FormSchemaContext} to determine if a field\n * will show validation errors when submitted with empty/invalid input.\n *\n * @param params - Schema, field name, and optional discriminator (schema used for type inference)\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, fieldName: 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  TName extends keyof Extract<\n    Required<z.input<TSchema>>,\n    Record<TDiscriminatorKey, TDiscriminatorValue>\n  >,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema>,\n  TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>,\n>({\n  fieldName,\n  ...props\n}: {\n  schema: TSchema;\n  fieldName: TName;\n  discriminator?: Discriminator<\n    TSchema,\n    TDiscriminatorKey,\n    TDiscriminatorValue\n  >;\n}): boolean {\n  const context = useFormSchema<\n    TSchema,\n    TDiscriminatorKey,\n    TDiscriminatorValue\n  >(props);\n\n  if (!context) {\n    return false;\n  }\n\n  return isRequiredField({\n    schema: context.schema,\n    fieldName,\n    discriminator: context.discriminator,\n  });\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, fieldName: 'name' }); // true\n * isRequiredField({ schema, fieldName: '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 *   fieldName: 'name',\n *   discriminator: { key: 'mode', value: 'create' },\n * }); // true\n * ```\n */\nexport function isRequiredField<\n  TSchema extends z.ZodType,\n  TName extends keyof Extract<\n    Required<z.input<TSchema>>,\n    Record<TDiscriminatorKey, TDiscriminatorValue>\n  >,\n  TDiscriminatorKey extends DiscriminatorKey<TSchema>,\n  TDiscriminatorValue extends DiscriminatorValue<TSchema, TDiscriminatorKey>,\n>({\n  schema,\n  fieldName,\n  discriminator,\n}: {\n  schema: TSchema;\n  fieldName: TName;\n  discriminator?: Discriminator<\n    TSchema,\n    TDiscriminatorKey,\n    TDiscriminatorValue\n  >;\n}): boolean {\n  const field = extractFieldFromSchema({\n    schema,\n    fieldName,\n    discriminator,\n  });\n\n  if (!field) {\n    return false;\n  }\n\n  return requiresValidInput(field);\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 TOutput - The Zod schema output type (extends FieldValues)\n * @template TInput - The Zod schema input type (accepts nullable/undefined values during form editing)\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>({\n  schema,\n  zodResolverOptions,\n  ...formOptions\n}: {\n  schema: z.ZodType<TOutput, TInput>;\n  defaultValues?: TFormInput;\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": "0.11.0",
+  "version": "0.12.0",
   "description": "React Hook Form integration and utilities for Zod schemas",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",