@conform-to/react 1.18.0 → 1.19.0

package/dist/future/types.d.ts

@@ -1,4 +1,4 @@
-import type { FieldName, FormError, FormValue, Serialize, SubmissionResult, ValidationAttributes } from '@conform-to/dom/future';
+import type { CustomSerialize, FieldName, FormError, FormValue, Serialize, SubmissionResult, ValidationAttributes } from '@conform-to/dom/future';
 import type { StandardSchemaV1 } from './standard-schema';
 export type Prettify<T> = {
     [K in keyof T]: T[K];
@@ -111,7 +111,7 @@ export type CustomControlOptions<Value = unknown, DefaultValue = Value> = {
      * Use this to coerce unknown DOM-derived data into a typed shape.
      * Any thrown error is surfaced to the caller.
      */
-    parse: (payload: unknown) => Value | null | undefined;
+    parse: (payload: unknown) => Value | null;
     /**
      * Optional serializer to convert the parsed payload back to a form value for populating the base control(s).
      */
@@ -139,7 +139,7 @@ export type UseFormDataOptions<Value = undefined> = {
 export type DefaultValue<Shape> = Shape extends Record<string, any> ? {
     [Key in keyof Shape]?: DefaultValue<Shape[Key]>;
 } | null | undefined : Shape extends Array<infer Item> ? Array<DefaultValue<Item>> | null | undefined : Shape extends File | File[] ? null | undefined : Shape | string | null | undefined;
-export type FormState<ErrorShape extends BaseErrorShape = DefaultErrorShape> = {
+export type FormState<ErrorShape = any> = {
     /** Unique identifier that changes on form reset to trigger reset side effects */
     resetKey: string;
     /** Initial form values */
@@ -157,7 +157,7 @@ export type FormState<ErrorShape extends BaseErrorShape = DefaultErrorShape> = {
     /** Mapping of array field names to their item keys for React list rendering */
     listKeys: Record<string, string[]>;
 };
-export type FormAction<ErrorShape extends BaseErrorShape = DefaultErrorShape, Intent extends UnknownIntent | null | undefined = UnknownIntent | null, Context = {}> = SubmissionResult<ErrorShape> & {
+export type FormAction<ErrorShape = any, Intent extends UnknownIntent | null | undefined = UnknownIntent | null, Context = {}> = SubmissionResult<ErrorShape> & {
     type: 'initialize' | 'server' | 'client';
     intent: Intent;
     ctx: Context;
@@ -165,7 +165,7 @@ export type FormAction<ErrorShape extends BaseErrorShape = DefaultErrorShape, In
 /**
  * Augment this interface to customize schema type inference for your schema library.
  *
- * @example
+ * **Example:**
  * ```ts
  * import type { ZodTypeAny, input, output } from 'zod';
  * import type { ZodSchemaOptions } from '@conform-to/zod/v3/future';
@@ -239,16 +239,16 @@ export type ExtractFieldConditions<T extends Record<string, FieldShapeGuard<any>
  * Resolved configuration from configureForms factory.
  * Properties with defaults are required, others remain optional.
  */
-export type FormsConfig<BaseErrorShape, BaseSchema, CustomFormMetadata extends Record<string, unknown>, CustomFieldMetadata extends Record<string, unknown>> = {
+export type FormsConfig<BaseErrorShape, BaseSchema, SchemaErrorShape, CustomFormMetadata extends Record<string, unknown>, CustomFieldMetadata extends Record<string, unknown>> = {
     /**
      * The name of the submit button field that indicates the submission intent.
      * @default "__intent__"
      */
     intentName: string;
     /**
-     * A custom serialization function for converting form data.
+     * A custom serializer for converting form values.
      */
-    serialize: Serialize;
+    serialize?: CustomSerialize | undefined;
     /**
      * Determines when validation should run for the first time on a field.
      * @default "onSubmit"
@@ -263,7 +263,7 @@ export type FormsConfig<BaseErrorShape, BaseSchema, CustomFormMetadata extends R
      * Runtime type guard to check if a value is a schema.
      * Used to determine if the first argument to useForm is a schema or options object.
      *
-     * @example
+     * **Example:**
      * ```ts
      * import { configureForms } from '@conform-to/react/future';
      * import {
@@ -284,7 +284,7 @@ export type FormsConfig<BaseErrorShape, BaseSchema, CustomFormMetadata extends R
      * Validates a schema against form payload.
      */
     validateSchema: <Schema extends BaseSchema>(schema: Schema, payload: Record<string, FormValue>, options?: InferOptions<Schema>) => MaybePromise<{
-        error: FormError<string> | null;
+        error: FormError<SchemaErrorShape> | null;
         value?: InferOutput<Schema>;
     }>;
     /**
@@ -308,35 +308,6 @@ export type FormsConfig<BaseErrorShape, BaseSchema, CustomFormMetadata extends R
         when: DefineConditionalField;
     }) => CustomFieldMetadata;
 };
-export type GlobalFormOptions = {
-    /**
-     * The name of the submit button field that indicates the submission intent.
-     *
-     * @default "__intent__"
-     */
-    intentName: string;
-    /**
-     * A custom serialization function for converting form data.
-     */
-    serialize: Serialize;
-    /**
-     * Determines when validation should run for the first time on a field.
-     *
-     * @default "onSubmit"
-     */
-    shouldValidate: 'onSubmit' | 'onBlur' | 'onInput';
-    /**
-     * Determines when validation should run again after the field has been validated once.
-     *
-     * @default Same as shouldValidate
-     */
-    shouldRevalidate?: 'onSubmit' | 'onBlur' | 'onInput';
-    /**
-     * A function that defines custom metadata properties for form fields.
-     * Useful for integrating with UI libraries or custom form components.
-     */
-    defineCustomMetadata?: CustomMetadataDefinition;
-};
 export type NonPartial<T> = {
     [K in keyof Required<T>]: T[K];
 };
@@ -352,6 +323,7 @@ export type BaseSchemaType = StandardSchemaV1<any, any>;
 export type InferInput<Schema> = Schema extends StandardSchemaV1 ? StandardSchemaV1.InferInput<Schema> : CustomSchemaTypes<Schema> extends {
     input: infer T;
 } ? T : Record<string, any>;
+export type InferFormShape<Schema> = InferInput<Schema> extends Record<string, any> ? InferInput<Schema> : Record<string, any>;
 /**
  * Infer schema output type.
  * For StandardSchemaV1 schemas (zod, valibot, etc.), uses StandardSchemaV1.InferOutput.
@@ -360,7 +332,7 @@ export type InferInput<Schema> = Schema extends StandardSchemaV1 ? StandardSchem
 export type InferOutput<Schema> = Schema extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<Schema> : CustomSchemaTypes<Schema> extends {
     output: infer T;
 } ? T : undefined;
-export type BaseFormOptions<FormShape extends Record<string, any> = Record<string, any>, ErrorShape extends BaseErrorShape = string extends BaseErrorShape ? string : BaseErrorShape, Value = undefined, Schema = unknown> = {
+export type FormOptions<FormShape extends Record<string, any> = Record<string, any>, ErrorShape = any, Value = undefined, Schema = unknown, SchemaErrorShape = ErrorShape> = {
     /** Optional form identifier. If not provided, a unique ID is automatically generated. */
     id?: string | undefined;
     /** Optional key for form state reset. When the key changes, the form resets to its initial state. */
@@ -371,6 +343,11 @@ export type BaseFormOptions<FormShape extends Record<string, any> = Record<strin
     onSubmit?: SubmitHandler<FormShape, NoInfer<ErrorShape>, NoInfer<Value>> | undefined;
     /** Initial form values. Can be a partial object matching your form structure. */
     defaultValue?: DefaultValue<FormShape> | undefined;
+    /**
+     * Override serialization for specific fields on this form and delegate the rest
+     * to the configured global serializer.
+     */
+    serialize?: CustomSerialize | undefined;
     /** HTML validation attributes for fields (required, minLength, pattern, etc.). */
     constraint?: Record<string, ValidationAttributes> | undefined;
     /**
@@ -380,16 +357,16 @@ export type BaseFormOptions<FormShape extends Record<string, any> = Record<strin
     schemaOptions?: InferOptions<Schema>;
     /**
      * Determines when validation should run for the first time on a field.
-     * Overrides the global default set by FormOptionsProvider if provided.
+     * Overrides the default configured through `configureForms()` if provided.
      *
-     * @default Inherits from FormOptionsProvider, or "onSubmit" if not configured
+     * @default Inherits from `configureForms()`, or "onSubmit" if not configured
      */
     shouldValidate?: 'onSubmit' | 'onBlur' | 'onInput' | undefined;
     /**
      * Determines when validation should run again after the field has been validated once.
-     * Overrides the global default set by FormOptionsProvider if provided.
+     * Overrides the default configured through `configureForms()` if provided.
      *
-     * @default Inherits from FormOptionsProvider, or same as shouldValidate
+     * @default Inherits from `configureForms()`, or same as shouldValidate
      */
     shouldRevalidate?: 'onSubmit' | 'onBlur' | 'onInput' | undefined;
     /** Error handling callback triggered when validation errors occur. By default, it focuses the first invalid field. */
@@ -398,15 +375,28 @@ export type BaseFormOptions<FormShape extends Record<string, any> = Record<strin
     onInput?: InputHandler | undefined;
     /** Blur event handler for custom focus handling logic. */
     onBlur?: BlurHandler | undefined;
-    /** Custom validation handler. Can be skipped if using the schema property, or combined with schema to customize validation errors. */
-    onValidate?: ValidateHandler<ErrorShape, Value, InferOutput<Schema>> | undefined;
+    /** Custom validation handler. Can be skipped when a schema is passed as the first argument, or combined with schema validation to customize errors. */
+    onValidate?: ValidateHandler<ErrorShape, Value, InferOutput<Schema>, SchemaErrorShape> | undefined;
+};
+/**
+ * The object returned by `useForm()`, containing form-level metadata,
+ * typed field metadata, and the intent dispatcher for programmatic updates.
+ */
+export type FormHandle<FormShape extends Record<string, any>, ErrorShape, CustomFormMetadata extends Record<string, unknown> = {}, CustomFieldMetadata extends Record<string, unknown> = {}> = {
+    /** Form-level metadata and helpers. */
+    form: FormMetadata<ErrorShape, CustomFormMetadata, CustomFieldMetadata>;
+    /** Field metadata mapped from the form shape. */
+    fields: Fieldset<FormShape, ErrorShape, CustomFieldMetadata>;
+    /** Intent dispatcher for validate, reset, insert, remove, reorder, and update actions. */
+    intent: IntentDispatcher<FormShape>;
 };
-export type FormOptions<FormShape extends Record<string, any> = Record<string, any>, ErrorShape extends BaseErrorShape = string extends BaseErrorShape ? string : BaseErrorShape, Value = undefined, Schema = unknown, RequiredKeys extends keyof BaseFormOptions<FormShape, ErrorShape, Value, Schema> = never> = RequireKey<BaseFormOptions<FormShape, ErrorShape, Value, Schema>, RequiredKeys>;
-export interface FormContext<ErrorShape extends BaseErrorShape = DefaultErrorShape> {
+export interface FormContext<ErrorShape = any> {
     /** The form's unique identifier */
     formId: string;
     /** Internal form state with validation results and field data */
     state: FormState<ErrorShape>;
+    /** Serializer used to derive field defaults and sync values for this form. */
+    serialize: Serialize;
     /** HTML validation attributes for fields */
     constraint: Record<string, ValidationAttributes> | null;
     /** Form submission event handler */
@@ -433,7 +423,7 @@ export interface IntentDispatcher<FormShape extends Record<string, any> = Record
      *
      * @param options.defaultValue - The value to reset the form to. Pass `null` to clear all fields, or omit to reset to the initial default value from `useForm`.
      *
-     * @example
+     * **Example:**
      * ```tsx
      * // Reset to initial default value
      * intent.reset()
@@ -557,8 +547,8 @@ export type FormIntent<Dispatcher extends IntentDispatcher = IntentDispatcher> =
 export type IntentHandler<Signature extends (payload: any) => void = (payload: any) => void> = {
     validate?(...args: UnknownArgs<Parameters<Signature>>): boolean;
     resolve?(value: Record<string, FormValue>, ...args: Parameters<Signature>): Record<string, FormValue> | undefined;
-    apply?<ErrorShape extends BaseErrorShape>(result: SubmissionResult<ErrorShape>, ...args: Parameters<Signature>): SubmissionResult<ErrorShape>;
-    update?<ErrorShape extends BaseErrorShape>(state: FormState<ErrorShape>, action: FormAction<ErrorShape, {
+    apply?<ErrorShape>(result: SubmissionResult<ErrorShape>, ...args: Parameters<Signature>): SubmissionResult<ErrorShape>;
+    update?<ErrorShape>(state: FormState<ErrorShape>, action: FormAction<ErrorShape, {
         type: string;
         payload: Signature extends (payload: infer Payload) => void ? Payload : undefined;
     }, {
@@ -570,36 +560,9 @@ type BaseCombine<T, K extends PropertyKey = T extends unknown ? keyof T : never>
 export type Combine<T> = {
     [K in keyof BaseCombine<T>]: BaseCombine<T>[K];
 };
-/**
- * Extend this interface to define the base error shape for validation.
- *
- * @example
- * ```ts
- * declare module '@conform-to/react/future' {
- *   interface CustomTypes {
- *     errorShape: { message: string; code: string };
- *   }
- * }
- * ```
- */
-export interface CustomTypes {
-}
-export type BaseErrorShape = CustomTypes extends {
-    errorShape: infer Shape;
-} ? Shape : unknown;
-export type DefaultErrorShape = CustomTypes extends {
-    errorShape: infer Shape;
-} ? Shape : string;
 export type SatisfyComponentProps<ElementType extends React.ElementType, CustomProps extends React.ComponentPropsWithoutRef<ElementType>> = CustomProps;
-/**
- * Interface for extending field metadata with additional properties.
- * @deprecated Use `configureForms()` with the `extendFieldMetadata` option for full type inference support.
- */
-export interface CustomMetadata<FieldShape = any, ErrorShape extends BaseErrorShape = DefaultErrorShape> {
-}
-export type DefaultCustomMetadata<FieldShape, ErrorShape> = keyof CustomMetadata<FieldShape, ErrorShape> extends never ? {} : CustomMetadata<FieldShape, ErrorShape>;
 /** Field metadata object containing field state, validation attributes, and nested field access methods. */
-export type FieldMetadata<FieldShape, ErrorShape extends BaseErrorShape = DefaultErrorShape, CustomFieldMetadata extends Record<string, unknown> = DefaultCustomMetadata<FieldShape, ErrorShape>> = Readonly<Prettify<ValidationAttributes & {
+export type FieldMetadata<FieldShape, ErrorShape = any, CustomFieldMetadata extends Record<string, unknown> = {}> = Readonly<Prettify<ValidationAttributes & {
     /** Unique key for React list rendering (for array fields). */
     key: string | undefined;
     /** The field name path exactly as provided. */
@@ -647,10 +610,10 @@ export type FieldMetadata<FieldShape, ErrorShape extends BaseErrorShape = Defaul
     valid: boolean;
     /** @deprecated Use `.valid` instead. This was not an intentionl breaking change and would be removed in the next minor version soon  */
     invalid: boolean;
-    /** Array of validation error messages for this field. */
-    errors: ErrorShape[] | undefined;
-    /** Object containing errors for all touched subfields. */
-    fieldErrors: Record<string, ErrorShape[]>;
+    /** Validation error for this field. */
+    errors: ErrorShape | undefined;
+    /** Object containing validation errors for all touched subfields. */
+    fieldErrors: Record<string, ErrorShape>;
     /** Boolean value for the `aria-invalid` attribute. Indicates whether the field has validation errors for screen readers. */
     ariaInvalid: boolean | undefined;
     /** String value for the `aria-describedby` attribute. Contains the errorId when invalid, undefined otherwise. Merge with descriptionId manually if needed (e.g. `${metadata.descriptionId} ${metadata.ariaDescribedBy}`). */
@@ -666,21 +629,13 @@ export type FieldMetadata<FieldShape, ErrorShape extends BaseErrorShape = Defaul
  * Field metadata without custom extensions. This is the type received in `extendFieldMetadata`.
  * Equivalent to `FieldMetadata<FieldShape, ErrorShape, {}>`.
  */
-export type BaseFieldMetadata<FieldShape, ErrorShape extends BaseErrorShape> = FieldMetadata<FieldShape, ErrorShape, {}>;
-/**
- * @deprecated Renamed to `BaseFieldMetadata`. This will be removed in the next minor version.
- */
-export type BaseMetadata<FieldShape, ErrorShape extends BaseErrorShape> = BaseFieldMetadata<FieldShape, ErrorShape>;
-/**
- * @deprecated Use `configureForms()` with the `extendFieldMetadata` option instead.
- */
-export type CustomMetadataDefinition = <FieldShape, ErrorShape extends BaseErrorShape>(metadata: BaseFieldMetadata<FieldShape, ErrorShape>) => keyof CustomMetadata<FieldShape, ErrorShape> extends never ? {} : CustomMetadata<any, any>;
+export type BaseFieldMetadata<FieldShape, ErrorShape = any> = FieldMetadata<FieldShape, ErrorShape, {}>;
 /** Fieldset object containing all form fields as properties with their respective field metadata. */
-export type Fieldset<FieldShape, ErrorShape extends BaseErrorShape = DefaultErrorShape, CustomFieldMetadata extends Record<string, unknown> = DefaultCustomMetadata<FieldShape, ErrorShape>> = {
+export type Fieldset<FieldShape, ErrorShape = any, CustomFieldMetadata extends Record<string, unknown> = {}> = {
     [Key in keyof Combine<FieldShape>]-?: FieldMetadata<Combine<FieldShape>[Key], ErrorShape, CustomFieldMetadata>;
 };
 /** Form-level metadata and state object containing validation status, errors, and field access methods. */
-export type FormMetadata<ErrorShape extends BaseErrorShape = DefaultErrorShape, CustomFormMetadata extends Record<string, unknown> = {}, CustomFieldMetadata extends Record<string, unknown> = {}> = Readonly<{
+export type FormMetadata<ErrorShape = any, CustomFormMetadata extends Record<string, unknown> = {}, CustomFieldMetadata extends Record<string, unknown> = {}> = Readonly<{
     /** Unique identifier that changes on form reset */
     key: string;
     /** The form's unique identifier. */
@@ -695,10 +650,10 @@ export type FormMetadata<ErrorShape extends BaseErrorShape = DefaultErrorShape,
     valid: boolean;
     /** @deprecated Use `.valid` instead. This was not an intentional breaking change and would be removed in the next minor version soon  */
     invalid: boolean;
-    /** Form-level validation errors, if any exist. */
-    errors: ErrorShape[] | undefined;
-    /** Object containing errors for all touched fields. */
-    fieldErrors: Record<string, ErrorShape[]>;
+    /** Form-level validation error, if any exists. */
+    errors: ErrorShape | undefined;
+    /** Object containing validation errors for all touched fields. */
+    fieldErrors: Record<string, ErrorShape>;
     /** The form's initial default values. */
     defaultValue: Record<string, unknown>;
     /** Form props object for spreading onto the <form> element. */
@@ -724,12 +679,12 @@ export type FormMetadata<ErrorShape extends BaseErrorShape = DefaultErrorShape,
  * Form metadata without custom extensions. This is the type received in `extendFormMetadata`.
  * Equivalent to `FormMetadata<ErrorShape, {}, CustomFieldMetadata>`.
  */
-export type BaseFormMetadata<ErrorShape extends BaseErrorShape = DefaultErrorShape, CustomFieldMetadata extends Record<string, unknown> = {}> = FormMetadata<ErrorShape, {}, CustomFieldMetadata>;
+export type BaseFormMetadata<ErrorShape = any, CustomFieldMetadata extends Record<string, unknown> = {}> = FormMetadata<ErrorShape, {}, CustomFieldMetadata>;
 export type ValidateResult<ErrorShape, Value> = FormError<ErrorShape> | null | {
     error: FormError<ErrorShape> | null;
     value?: Value;
 };
-export type ValidateContext<SchemaValue> = {
+export type ValidateContext<SchemaValue, SchemaErrorShape> = {
     /**
      * The submitted values mapped by field name.
      * Supports nested names like `user.email` and indexed names like `items[0].id`.
@@ -739,7 +694,7 @@ export type ValidateContext<SchemaValue> = {
      * Form error object. Initially empty, but populated with schema validation
      * errors when a schema is provided and validation fails.
      */
-    error: FormError<string>;
+    error: FormError<SchemaErrorShape>;
     /**
      * The submission intent derived from the button that triggered the form submission.
      */
@@ -762,7 +717,7 @@ export type ValidateContext<SchemaValue> = {
      */
     schemaValue: SchemaValue;
 };
-export type ValidateHandler<ErrorShape, Value, SchemaValue = undefined> = (ctx: ValidateContext<SchemaValue>) => ValidateResult<ErrorShape, Value> | Promise<ValidateResult<ErrorShape, Value>> | [
+export type ValidateHandler<ErrorShape, Value, SchemaValue = undefined, SchemaErrorShape = ErrorShape> = (ctx: ValidateContext<SchemaValue, SchemaErrorShape>) => ValidateResult<ErrorShape, Value> | Promise<ValidateResult<ErrorShape, Value>> | [
     ValidateResult<ErrorShape, Value> | undefined,
     Promise<ValidateResult<ErrorShape, Value>> | undefined
 ] | undefined;
@@ -783,7 +738,7 @@ export type ErrorContext<ErrorShape> = {
 export type ErrorHandler<ErrorShape> = (ctx: ErrorContext<ErrorShape>) => void;
 export type InputHandler = (event: FormInputEvent) => void;
 export type BlurHandler = (event: FormFocusEvent) => void;
-export type SubmitContext<FormShape extends Record<string, any> = Record<string, any>, ErrorShape extends BaseErrorShape = DefaultErrorShape, Value = undefined> = {
+export type SubmitContext<FormShape extends Record<string, any> = Record<string, any>, ErrorShape = any, Value = undefined> = {
     formData: FormData;
     value: Value;
     update: (options: {
@@ -792,22 +747,22 @@ export type SubmitContext<FormShape extends Record<string, any> = Record<string,
         reset?: boolean | undefined;
     }) => void;
 };
-export type SubmitHandler<FormShape extends Record<string, any> = Record<string, any>, ErrorShape extends BaseErrorShape = DefaultErrorShape, Value = undefined> = (event: React.FormEvent<HTMLFormElement>, ctx: SubmitContext<FormShape, ErrorShape, Value>) => void | Promise<void>;
+export type SubmitHandler<FormShape extends Record<string, any> = Record<string, any>, ErrorShape = any, Value = undefined> = (event: React.FormEvent<HTMLFormElement>, ctx: SubmitContext<FormShape, ErrorShape, Value>) => void | Promise<void>;
 /**
  * Infer the base error shape from a FormsConfig.
  *
- * @example
+ * **Example:**
  * ```ts
  * const { config } = configureForms({ isError: shape<{ message: string }>() });
  * type ErrorShape = InferBaseErrorShape<typeof config>; // { message: string }
  * ```
  */
-export type InferBaseErrorShape<Config> = Config extends FormsConfig<infer ErrorShape, any, any, any> ? ErrorShape : string;
+export type InferBaseErrorShape<Config> = Config extends FormsConfig<infer ErrorShape, any, any, any, any> ? ErrorShape : string;
 /**
  * Infer the custom form metadata extension from a FormsConfig.
  * Use this to compose with FormMetadata, FieldMetadata, or Fieldset types.
  *
- * @example
+ * **Example:**
  * ```ts
  * const { config } = configureForms({
  *   extendFormMetadata: (meta) => ({ customProp: meta.id })
@@ -819,12 +774,12 @@ export type InferBaseErrorShape<Config> = Config extends FormsConfig<infer Error
  * >;
  * ```
  */
-export type InferCustomFormMetadata<Config> = Config extends FormsConfig<any, any, infer CustomFormMetadata, any> ? CustomFormMetadata : {};
+export type InferCustomFormMetadata<Config> = Config extends FormsConfig<any, any, any, infer CustomFormMetadata, any> ? CustomFormMetadata : {};
 /**
  * Infer the custom field metadata extension from a FormsConfig.
  * Use this to compose with FieldMetadata or Fieldset types.
  *
- * @example
+ * **Example:**
  * ```ts
  * const { config } = configureForms({
  *   extendFieldMetadata: (meta) => ({ inputProps: { name: meta.name } })
@@ -833,13 +788,13 @@ export type InferCustomFormMetadata<Config> = Config extends FormsConfig<any, an
  * type MyFieldset<T> = Fieldset<T, InferBaseErrorShape<typeof config>, InferCustomFieldMetadata<typeof config>>;
  * ```
  */
-export type InferCustomFieldMetadata<Config> = Config extends FormsConfig<any, any, any, infer CustomFieldMetadata> ? CustomFieldMetadata : {};
+export type InferCustomFieldMetadata<Config> = Config extends FormsConfig<any, any, any, any, infer CustomFieldMetadata> ? CustomFieldMetadata : {};
 /**
  * Transform a type to make specific keys conditional based on FieldShape.
  * Keys in ConditionalKeys will only be present when FieldShape extends the specified type.
  * Uses ConditionalFieldMetadata wrapper that RestoreFieldShape will detect and evaluate.
  *
- * @example
+ * **Example:**
  * ```ts
  * type Result = MakeConditional<
  *   { textFieldProps: {...}, dateRangePickerProps: {...} },

package/dist/future/util.d.ts

@@ -1,4 +1,4 @@
-import type { FormError } from '@conform-to/dom/future';
+import type { CustomSerialize, FormError, Serialize } from '@conform-to/dom/future';
 import type { StandardSchemaV1 } from './standard-schema';
 import { ValidateHandler, ValidateResult, BaseFieldMetadata, ConditionalFieldMetadata } from './types';
 export declare function isUndefined(value: unknown): value is undefined;
@@ -17,11 +17,7 @@ export declare function updatePathValue<Data>(data: Record<string, Data>, name:
  * Returns null to remove fields, or updated path with new index.
  */
 export declare function createPathIndexUpdater(listName: string, update: (index: number) => number | null): (name: string) => string | null;
-/**
- * Returns null if error object has no actual error messages,
- * otherwise returns the error as-is.
- */
-export declare function normalizeFormError<ErrorShape>(error: FormError<ErrorShape> | null): FormError<ErrorShape> | null;
+export declare function resolveSerialize(customSerialize: CustomSerialize | undefined, defaultSerialize: Serialize): Serialize;
 export declare function normalizeValidateResult<ErrorShape, Value>(result: ValidateResult<ErrorShape, Value>): {
     error: FormError<ErrorShape> | null;
     value?: Value;
@@ -46,7 +42,7 @@ export declare function resolveValidateResult<ErrorShape, Value>(result: ReturnT
  * Resolves a StandardSchema validation result to conform's format.
  */
 export declare function resolveStandardSchemaResult<Value>(result: StandardSchemaV1.Result<Value>): {
-    error: FormError<string> | null;
+    error: FormError<string[]> | null;
     value?: Value;
 };
 /**
@@ -79,14 +75,14 @@ export declare function generateUniqueKey(): string;
  * - `isError`: Specify the error shape for type inference
  * - `when`: Narrow field metadata to specific shapes for conditional props
  *
- * @example Specify error shape
+ * **Example: Specify error shape**
  * ```ts
  * configureForms({
- *   isError: shape<string>(),  // errors are strings
+ *   isError: shape<string[]>(),  // errors are string arrays
  * });
  * ```
  *
- * @example Conditional field metadata
+ * **Example: Conditional field metadata**
  * ```ts
  * extendFieldMetadata(metadata, { when }) {
  *   return {

package/dist/future/util.js

@@ -70,29 +70,26 @@ function createPathIndexUpdater(listName, update) {
     return name;
   };
 }
-
-/**
- * Returns null if error object has no actual error messages,
- * otherwise returns the error as-is.
- */
-function normalizeFormError(error) {
-  if (error && error.formErrors.length === 0 && Object.entries(error.fieldErrors).every(_ref => {
-    var [, messages] = _ref;
-    return Array.isArray(messages) ? messages.length === 0 : !messages;
-  })) {
-    return null;
+function resolveSerialize(customSerialize, _defaultSerialize) {
+  if (typeof customSerialize === 'undefined') {
+    return _defaultSerialize;
   }
-  return error;
+  return function serializeValue(value, context) {
+    return customSerialize(value, {
+      name: context.name,
+      defaultSerialize: value => _defaultSerialize(value, context)
+    });
+  };
 }
 function normalizeValidateResult(result) {
   if (result !== null && 'error' in result) {
     return {
-      error: normalizeFormError(result.error),
+      error: future.normalizeFormError(result.error),
       value: result.value
     };
   }
   return {
-    error: normalizeFormError(result)
+    error: future.normalizeFormError(result)
   };
 }
 
@@ -138,8 +135,8 @@ function resolveStandardSchemaResult(result) {
  * Create a copy of the object with the updated properties if there is any change
  */
 function merge(obj, update) {
-  if (obj === update || Object.entries(update).every(_ref2 => {
-    var [key, value] = _ref2;
+  if (obj === update || Object.entries(update).every(_ref => {
+    var [key, value] = _ref;
     return obj[key] === value;
   })) {
     return obj;
@@ -201,14 +198,14 @@ function generateUniqueKey() {
  * - `isError`: Specify the error shape for type inference
  * - `when`: Narrow field metadata to specific shapes for conditional props
  *
- * @example Specify error shape
+ * **Example: Specify error shape**
  * ```ts
  * configureForms({
- *   isError: shape<string>(),  // errors are strings
+ *   isError: shape<string[]>(),  // errors are string arrays
  * });
  * ```
  *
- * @example Conditional field metadata
+ * **Example: Conditional field metadata**
  * ```ts
  * extendFieldMetadata(metadata, { when }) {
  *   return {
@@ -256,8 +253,8 @@ exports.isStandardSchemaV1 = isStandardSchemaV1;
 exports.isString = isString;
 exports.isUndefined = isUndefined;
 exports.merge = merge;
-exports.normalizeFormError = normalizeFormError;
 exports.normalizeValidateResult = normalizeValidateResult;
+exports.resolveSerialize = resolveSerialize;
 exports.resolveStandardSchemaResult = resolveStandardSchemaResult;
 exports.resolveValidateResult = resolveValidateResult;
 exports.shape = shape;

package/dist/future/util.mjs

@@ -1,4 +1,4 @@
-import { formatIssues, getPathValue, isPlainObject, setPathValue, parsePath, formatPath } from '@conform-to/dom/future';
+import { formatIssues, normalizeFormError, getPathValue, isPlainObject, setPathValue, parsePath, formatPath } from '@conform-to/dom/future';
 
 function isUndefined(value) {
   return value === undefined;
@@ -66,19 +66,16 @@ function createPathIndexUpdater(listName, update) {
     return name;
   };
 }
-
-/**
- * Returns null if error object has no actual error messages,
- * otherwise returns the error as-is.
- */
-function normalizeFormError(error) {
-  if (error && error.formErrors.length === 0 && Object.entries(error.fieldErrors).every(_ref => {
-    var [, messages] = _ref;
-    return Array.isArray(messages) ? messages.length === 0 : !messages;
-  })) {
-    return null;
+function resolveSerialize(customSerialize, _defaultSerialize) {
+  if (typeof customSerialize === 'undefined') {
+    return _defaultSerialize;
   }
-  return error;
+  return function serializeValue(value, context) {
+    return customSerialize(value, {
+      name: context.name,
+      defaultSerialize: value => _defaultSerialize(value, context)
+    });
+  };
 }
 function normalizeValidateResult(result) {
   if (result !== null && 'error' in result) {
@@ -134,8 +131,8 @@ function resolveStandardSchemaResult(result) {
  * Create a copy of the object with the updated properties if there is any change
  */
 function merge(obj, update) {
-  if (obj === update || Object.entries(update).every(_ref2 => {
-    var [key, value] = _ref2;
+  if (obj === update || Object.entries(update).every(_ref => {
+    var [key, value] = _ref;
     return obj[key] === value;
   })) {
     return obj;
@@ -197,14 +194,14 @@ function generateUniqueKey() {
  * - `isError`: Specify the error shape for type inference
  * - `when`: Narrow field metadata to specific shapes for conditional props
  *
- * @example Specify error shape
+ * **Example: Specify error shape**
  * ```ts
  * configureForms({
- *   isError: shape<string>(),  // errors are strings
+ *   isError: shape<string[]>(),  // errors are string arrays
  * });
  * ```
  *
- * @example Conditional field metadata
+ * **Example: Conditional field metadata**
  * ```ts
  * extendFieldMetadata(metadata, { when }) {
  *   return {
@@ -240,4 +237,4 @@ function validateStandardSchemaV1(schema, payload) {
   return resolveStandardSchemaResult(result);
 }
 
-export { appendUniqueItem, compactMap, createPathIndexUpdater, generateUniqueKey, getPathArray, isNullable, isNumber, isOptional, isStandardSchemaV1, isString, isUndefined, merge, normalizeFormError, normalizeValidateResult, resolveStandardSchemaResult, resolveValidateResult, shape, transformKeys, updatePathValue, validateStandardSchemaV1, when };
+export { appendUniqueItem, compactMap, createPathIndexUpdater, generateUniqueKey, getPathArray, isNullable, isNumber, isOptional, isStandardSchemaV1, isString, isUndefined, merge, normalizeValidateResult, resolveSerialize, resolveStandardSchemaResult, resolveValidateResult, shape, transformKeys, updatePathValue, validateStandardSchemaV1, when };