@conform-to/react 1.17.1 → 1.19.0

package/dist/future/types.d.ts

@@ -1,43 +1,52 @@
-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];
 } & {};
 /** Reference to a form element. Can be either a React ref object or a form ID string. */
 export type FormRef = React.RefObject<HTMLFormElement | HTMLFieldSetElement | HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement | HTMLButtonElement | null> | string;
-export type InputSnapshot = {
-    value?: string | undefined;
-    options?: string[] | undefined;
-    checked?: boolean | undefined;
-    files?: File[] | undefined;
-};
-export type Control = {
+export type DefaultControlValue = string | string[] | File | File[] | FileList;
+export type Control<Value = DefaultControlValue, DefaultValue = Value, Payload = unknown> = {
     /**
-     * Current value of the base input. Undefined if the registered input
-     * is a multi-select, file input, or checkbox group.
+     * Current string value derived from the control payload.
      */
     value: string | undefined;
     /**
-     * Selected options of the base input. Defined only when the registered input
-     * is a multi-select or checkbox group.
+     * Checked state derived from the control payload.
      */
     checked: boolean | undefined;
     /**
-     * Checked state of the base input. Defined only when the registered input
-     * is a single checkbox or radio input.
+     * Current string array derived from the control payload.
      */
     options: string[] | undefined;
     /**
-     * Selected files of the base input. Defined only when the registered input
-     * is a file input.
+     * Current file array derived from the control payload.
      */
     files: File[] | undefined;
     /**
-     * Registers the base input element(s). Accepts a single input or an array for groups.
+     * The rendered payload used as the source for base control(s).
+     *
+     * For simple native controls, this mirrors `defaultValue` / `defaultChecked`.
+     * For structural controls (i.e. `<fieldset>`), this is the latest payload
+     * snapshot that drives which hidden inputs are rendered.
+     */
+    defaultValue: DefaultValue | null | undefined;
+    /**
+     * Current payload snapshot derived from the registered base control(s).
+     *
+     * For structural controls (i.e. `<fieldset>`), this is reconstructed from
+     * descendant fields under the registered fieldset name.
+     */
+    payload: Payload | null | undefined;
+    /**
+     * Registers the base control element.
+     *
+     * Accepts `<input>`, `<select>`, `<textarea>`, `<fieldset>`,
+     * or a collection of checkbox / radio inputs with the same name.
      */
-    register: (element: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement | HTMLCollectionOf<HTMLInputElement> | NodeListOf<HTMLInputElement> | null | undefined) => void;
+    register: (element: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement | HTMLFieldSetElement | HTMLCollectionOf<HTMLInputElement> | NodeListOf<HTMLInputElement> | null | undefined) => void;
     /**
-     * A ref object containing the form element associated with the registered input.
+     * A ref object containing the form element associated with the registered base control.
      * Use this with hooks like useFormData() and useIntent().
      */
     formRef: React.RefObject<HTMLFormElement | null>;
@@ -46,21 +55,74 @@ export type Control = {
      * both [change](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event) and
      * [input](https://developer.mozilla.org/en-US/docs/Web/API/Element/input_event) events.
      */
-    change: (value: string | string[] | boolean | File | File[] | FileList | null) => void;
-    /**
-     * Emits [blur](https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event) and
-     * [focusout](https://developer.mozilla.org/en-US/docs/Web/API/Element/focusout_event) events.
-     * Does not actually move focus.
-     */
-    focus: () => void;
+    change: (value: Value | null) => void;
     /**
      * Emits [focus](https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event) and
      * [focusin](https://developer.mozilla.org/en-US/docs/Web/API/Element/focusin_event) events.
-     * This does not move the actual keyboard focus to the input. Use `element.focus()` instead
+     *
+     * This does not move the actual keyboard focus to the input.
+     * Use [HTMLElement.focus()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus)
      * if you want to move focus to the input.
      */
+    focus: () => void;
+    /**
+     * Emits [blur](https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event) and
+     * [focusout](https://developer.mozilla.org/en-US/docs/Web/API/Element/focusout_event) events.
+     *
+     * This does not move the actual keyboard focus away from the input.
+     */
     blur: () => void;
 };
+export type StandardControlOptions<Value extends DefaultControlValue = DefaultControlValue> = {
+    /**
+     * The initial value of the base control.
+     */
+    defaultValue?: Value | null | undefined;
+    /**
+     * A callback function that is triggered when the base control is focused.
+     * Use this to delegate focus to a custom input.
+     */
+    onFocus?: () => void;
+};
+export type CheckedControlOptions = {
+    /**
+     * Whether the base control should be checked by default.
+     */
+    defaultChecked?: boolean | undefined;
+    /**
+     * The value of a checkbox or radio control when checked.
+     */
+    value?: string;
+    /**
+     * A callback function that is triggered when the base control is focused.
+     * Use this to delegate focus to a custom input.
+     */
+    onFocus?: () => void;
+};
+export type CustomControlOptions<Value = unknown, DefaultValue = Value> = {
+    /**
+     * Initial value used to seed the control.
+     * For structural controls, this is the payload used to render hidden inputs.
+     */
+    defaultValue?: DefaultValue | null | undefined;
+    /**
+     * Payload parser applied to the current payload snapshot.
+     *
+     * 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;
+    /**
+     * Optional serializer to convert the parsed payload back to a form value for populating the base control(s).
+     */
+    serialize?: (value: Value) => FormValue;
+    /**
+     * A callback function that is triggered when the base control is focused.
+     * Use this to delegate focus to a custom input.
+     */
+    onFocus?: () => void;
+};
+export type ControlOptions = StandardControlOptions | CheckedControlOptions | CustomControlOptions;
 export type Selector<FormValue, Result> = (formData: FormValue, lastResult: Result | undefined) => Result;
 export type UseFormDataOptions<Value = undefined> = {
     /**
@@ -77,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 */
@@ -95,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;
@@ -103,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';
@@ -177,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"
@@ -201,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 {
@@ -222,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>;
     }>;
     /**
@@ -246,39 +308,12 @@ 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];
 };
-export type RequireKey<T, K extends keyof T> = Prettify<T & Pick<NonPartial<T>, K>>;
+export type RequireKey<T, K extends keyof T> = Prettify<Omit<T, K> & {
+    [P in K]-?: Exclude<T[P], undefined>;
+}>;
 export type BaseSchemaType = StandardSchemaV1<any, any>;
 /**
  * Infer schema input type.
@@ -288,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.
@@ -296,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. */
@@ -307,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;
     /**
@@ -316,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. */
@@ -334,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 */
@@ -369,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()
@@ -493,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;
     }, {
@@ -506,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. */
@@ -570,16 +597,23 @@ export type FieldMetadata<FieldShape, ErrorShape extends BaseErrorShape = Defaul
      * For radio buttons, compare the field's `defaultValue` with the radio button's value attribute instead.
      */
     defaultChecked: boolean;
+    /**
+     * The normalized default payload at this field path.
+     *
+     * This is useful for non-native field shapes that need to render a set of
+     * hidden inputs before user interaction.
+     */
+    defaultPayload: unknown;
     /** Whether this field has been touched (through intent.validate() or the shouldValidate option). */
     touched: boolean;
     /** Whether this field currently has no validation errors. */
     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}`). */
@@ -595,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. */
@@ -624,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. */
@@ -653,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`.
@@ -668,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.
      */
@@ -691,18 +717,18 @@ 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;
 export interface FormInputEvent extends React.FormEvent<HTMLFormElement> {
     currentTarget: EventTarget & HTMLFormElement;
-    target: EventTarget & (HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement);
+    target: EventTarget & (HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement | HTMLFieldSetElement);
 }
 export interface FormFocusEvent extends React.FormEvent<HTMLFormElement> {
     currentTarget: EventTarget & HTMLFormElement;
     relatedTarget: EventTarget | null;
-    target: EventTarget & (HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement);
+    target: EventTarget & (HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement | HTMLFieldSetElement);
 }
 export type ErrorContext<ErrorShape> = {
     formElement: HTMLFormElement;
@@ -712,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: {
@@ -721,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 })
@@ -748,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 } })
@@ -762,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: {...} },
@@ -782,5 +808,47 @@ export type MakeConditional<T, ConditionalKeys extends Record<string, unknown>>
     [K in keyof ConditionalKeys]: K extends keyof T ? ConditionalFieldMetadata<T[K], ConditionalKeys[K]> : never;
 };
 export type MaybePromise<T> = T | Promise<T>;
+type BaseFieldsetProps = RequireKey<Omit<React.ComponentPropsWithoutRef<'fieldset'>, 'children' | 'defaultValue'>, 'name'> & {
+    /**
+     * Renders a hidden `<fieldset>` base control with nested hidden `<input>` elements
+     * derived from `defaultValue`.
+     */
+    type: 'fieldset';
+    /**
+     * Structured default value used to render nested hidden inputs.
+     */
+    defaultValue: unknown;
+};
+type BaseSelectProps = RequireKey<Omit<React.ComponentPropsWithoutRef<'select'>, 'children' | 'value'>, 'name' | 'defaultValue'> & {
+    /**
+     * Renders a hidden `<select>` base control.
+     */
+    type: 'select';
+};
+type BaseTextareaProps = RequireKey<Omit<React.ComponentPropsWithoutRef<'textarea'>, 'children' | 'value'>, 'name' | 'defaultValue'> & {
+    /**
+     * Renders a hidden `<textarea>` base control.
+     */
+    type: 'textarea';
+};
+type BaseCheckedInputProps = RequireKey<Omit<React.ComponentPropsWithoutRef<'input'>, 'children' | 'type' | 'checked'>, 'name' | 'defaultChecked'> & {
+    /**
+     * Renders a hidden checkbox or radio base control.
+     */
+    type: 'checkbox' | 'radio';
+};
+type BaseFileInputProps = RequireKey<Omit<React.ComponentPropsWithoutRef<'input'>, 'children' | 'type' | 'value' | 'checked'>, 'name'> & {
+    /**
+     * Renders a hidden `<input type="file">` base control.
+     */
+    type: 'file';
+};
+type BaseInputProps = RequireKey<Omit<React.ComponentPropsWithoutRef<'input'>, 'children' | 'type' | 'value' | 'checked'>, 'name' | 'defaultValue'> & {
+    /**
+     * Renders a hidden `<input type="...">` base control.
+     */
+    type?: 'color' | 'date' | 'datetime-local' | 'email' | 'hidden' | 'month' | 'number' | 'password' | 'range' | 'search' | 'tel' | 'text' | 'time' | 'url' | 'week';
+};
+export type BaseControlProps = BaseFieldsetProps | BaseSelectProps | BaseTextareaProps | BaseCheckedInputProps | BaseFileInputProps | BaseInputProps;
 export {};
 //# sourceMappingURL=types.d.ts.map