@conform-to/react 1.19.4 → 1.20.0

package/dist/future/types.d.ts

@@ -1,4 +1,4 @@
-import type { CustomSerialize, FieldName, FormError, FormValue, Serialize, SubmissionResult, ValidationAttributes } from '@conform-to/dom/future';
+import type { CustomSerialize, FieldName, FormError, FormValue, Serialize, Submission, SubmissionResult, ValidationAttributes } from '@conform-to/dom/future';
 import type { StandardSchemaV1 } from './standard-schema';
 export type Prettify<T> = {
     [K in keyof T]: T[K];
@@ -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 = any> = {
+export type FormState<ErrorShape = any, CustomState extends Record<string, unknown> = {}> = {
     /** Unique identifier that changes on form reset to trigger reset side effects */
     resetKey: string;
     /** Initial form values */
@@ -156,10 +156,13 @@ export type FormState<ErrorShape = any> = {
     touchedFields: string[];
     /** Mapping of array field names to their item keys for React list rendering */
     listKeys: Record<string, string[]>;
+    /** Current custom state for the form */
+    customState: CustomState;
 };
-export type FormAction<ErrorShape = any, Intent extends UnknownIntent | null | undefined = UnknownIntent | null, Context = {}> = SubmissionResult<ErrorShape> & {
-    type: 'initialize' | 'server' | 'client';
+export type FormAction<ErrorShape = any, Intent extends UnknownIntent = UnknownIntent, Context = {}> = {
+    type: 'initialize' | 'server' | 'client' | 'client:async';
     intent: Intent;
+    result: SubmissionResult<ErrorShape>;
     ctx: Context;
 };
 /**
@@ -239,7 +242,7 @@ 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, SchemaErrorShape, 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>, CustomIntentHandlers extends Record<string, IntentHandler<any, any>>, CustomStateHandlers extends Record<string, CustomStateHandler<any, any, BaseErrorShape>>> = {
     /**
      * The name of the submit button field that indicates the submission intent.
      * @default "__intent__"
@@ -249,6 +252,14 @@ export type FormsConfig<BaseErrorShape, BaseSchema, SchemaErrorShape, CustomForm
      * A custom serializer for converting form values.
      */
     serialize?: CustomSerialize | undefined;
+    /**
+     * Intent handlers available to every form created by this factory.
+     */
+    intents?: CustomIntentHandlers;
+    /**
+     * Custom state available to every form created by this factory.
+     */
+    customState?: CustomStateDefinition<CustomStateHandlers, CustomIntentHandlers>;
     /**
      * Determines when validation should run for the first time on a field.
      * @default "onSubmit"
@@ -298,13 +309,13 @@ export type FormsConfig<BaseErrorShape, BaseSchema, SchemaErrorShape, CustomForm
     /**
      * Extends form metadata with custom properties.
      */
-    extendFormMetadata?: <ErrorShape extends BaseErrorShape>(metadata: BaseFormMetadata<ErrorShape>) => CustomFormMetadata;
+    extendFormMetadata?: <ErrorShape extends BaseErrorShape>(metadata: BaseFormMetadata<ErrorShape, FormCustomState<CustomStateHandlers>>) => CustomFormMetadata;
     /**
      * Extends field metadata with custom properties.
      * Use `when` for properties that depend on the field shape.
      */
     extendFieldMetadata?: <FieldShape, ErrorShape extends BaseErrorShape>(metadata: BaseFieldMetadata<FieldShape, ErrorShape>, ctx: {
-        form: BaseFormMetadata<ErrorShape>;
+        form: BaseFormMetadata<ErrorShape, FormCustomState<CustomStateHandlers>>;
         when: DefineConditionalField;
     }) => CustomFieldMetadata;
 };
@@ -332,7 +343,7 @@ export type InferFormShape<Schema> = InferInput<Schema> extends Record<string, a
 export type InferOutput<Schema> = Schema extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<Schema> : CustomSchemaTypes<Schema> extends {
     output: infer T;
 } ? T : undefined;
-export type FormOptions<FormShape extends Record<string, any> = Record<string, any>, ErrorShape = any, Value = undefined, Schema = unknown, SchemaErrorShape = ErrorShape> = {
+export type FormOptions<FormShape extends Record<string, any> = Record<string, any>, ErrorShape = any, Value = undefined, Schema = unknown, SchemaErrorShape = ErrorShape, CustomIntentHandlers extends Record<string, IntentHandler<any, any>> = {}, GlobalIntentHandlers extends Record<string, IntentHandler<any, any>> = {}, CustomStateHandlers extends Record<string, CustomStateHandler<any, any, any>> = {}> = {
     /** 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. */
@@ -348,6 +359,14 @@ export type FormOptions<FormShape extends Record<string, any> = Record<string, a
      * to the configured global serializer.
      */
     serialize?: CustomSerialize | undefined;
+    /**
+     * Custom intent handlers available only to this form instance.
+     */
+    intents?: CustomIntentHandlers | undefined;
+    /**
+     * Custom state available only to this form instance.
+     */
+    customState?: CustomStateDefinition<CustomStateHandlers, GlobalIntentHandlers & CustomIntentHandlers> | undefined;
     /** HTML validation attributes for fields (required, minLength, pattern, etc.). */
     constraint?: Record<string, ValidationAttributes> | undefined;
     /**
@@ -376,25 +395,25 @@ export type FormOptions<FormShape extends Record<string, any> = Record<string, a
     /** Blur event handler for custom focus handling logic. */
     onBlur?: BlurHandler | 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;
+    onValidate?: ValidateHandler<ErrorShape, Value, InferOutput<Schema>, SchemaErrorShape, FormIntent<FormShape, DefaultIntentHandlers & GlobalIntentHandlers & CustomIntentHandlers> | undefined> | 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> = {}> = {
+export type FormHandle<FormShape extends Record<string, any>, ErrorShape, CustomFormMetadata extends Record<string, unknown> = {}, CustomFieldMetadata extends Record<string, unknown> = {}, CustomIntentHandlers extends Record<string, IntentHandler<any, any>> = {}, CustomState extends Record<string, unknown> = {}> = {
     /** Form-level metadata and helpers. */
-    form: FormMetadata<ErrorShape, CustomFormMetadata, CustomFieldMetadata>;
+    form: FormMetadata<ErrorShape, CustomFormMetadata, CustomFieldMetadata, CustomState>;
     /** 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>;
+    intent: IntentDispatcher<FormShape, CustomIntentHandlers>;
 };
-export interface FormContext<ErrorShape = any> {
+export interface FormContext<ErrorShape = any, CustomState extends Record<string, unknown> = {}> {
     /** The form's unique identifier */
     formId: string;
     /** Internal form state with validation results and field data */
-    state: FormState<ErrorShape>;
+    state: FormState<ErrorShape, CustomState>;
     /** Serializer used to derive field defaults and sync values for this form. */
     serialize: Serialize;
     /** HTML validation attributes for fields */
@@ -408,153 +427,134 @@ export interface FormContext<ErrorShape = any> {
 }
 export type UnknownIntent = {
     type: string;
-    payload?: unknown;
+    payload: unknown;
+};
+export type TransportIntent = {
+    type: string;
+    args: unknown[];
 };
 export type UnknownArgs<Args extends any[]> = {
     [Key in keyof Args]: unknown;
 };
-export interface IntentDispatcher<FormShape extends Record<string, any> = Record<string, any>> {
-    /**
-     * Validate the whole form or a specific field?
-     */
-    validate(name?: string): void;
-    /**
-     * Reset the form to a specific default value.
-     *
-     * @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:**
-     * ```tsx
-     * // Reset to initial default value
-     * intent.reset()
-     *
-     * // Clear all fields
-     * intent.reset({ defaultValue: null })
-     *
-     * // Restore to a specific snapshot
-     * intent.reset({ defaultValue: snapshotValue })
-     * ```
-     */
-    reset(options?: {
-        /**
-         * The value to reset the form to. If not provided, resets to the default value from `useForm`. Pass `null` to clear all fields instead.
-         */
+export interface TypedIntentDefinition {
+    readonly FormShape: unknown;
+    dispatch(...args: any[]): void;
+}
+export type IntentDefinition = ((...args: any[]) => void) | TypedIntentDefinition;
+export type ExtractDispatchSignature<Intent extends IntentDefinition, FormShape extends Record<string, any>> = Intent extends (...args: any[]) => void ? Intent : Intent extends TypedIntentDefinition ? (Intent & {
+    readonly FormShape: FormShape;
+})['dispatch'] : never;
+export type IntentPayload<Intent extends IntentDefinition, FormShape extends Record<string, any> = Record<string, any>> = Parameters<ExtractDispatchSignature<Intent, FormShape>> extends [] ? undefined : Parameters<ExtractDispatchSignature<Intent, FormShape>>[0];
+export type NormalizeIntentType<T> = T extends IntentDefinition ? T : (payload: T) => void;
+export type ApplyStatus = 'applied' | 'reverted' | 'modified';
+export type IntentDispatch<Intent extends IntentDefinition, FormShape extends Record<string, any> = Record<string, any>> = ExtractDispatchSignature<NormalizeIntentType<Intent>, FormShape>;
+export type IntentHandlerPayload<Dispatch extends IntentDefinition, Payload, FormShape extends Record<string, any>> = [Payload] extends [never] ? IntentPayload<NormalizeIntentType<Dispatch>, FormShape> : Payload;
+export type SubmitIntent = () => void;
+export interface ResetIntent extends TypedIntentDefinition {
+    dispatch<FormShape extends Record<string, any> = this['FormShape'] extends Record<string, any> ? this['FormShape'] : never>(options?: {
         defaultValue?: DefaultValue<FormShape>;
     }): void;
-    /**
-     * Update a field or a fieldset.
-     * If you provide a fieldset name, it will update all fields within that fieldset
-     */
-    update<FieldShape = FormShape>(options: {
-        /**
-         * The name of the field. If you provide a fieldset name, it will update all fields within that fieldset.
-         */
+}
+export type ValidateIntent = (name?: string) => void;
+export type IsUntypedFormShape<FormShape> = unknown extends FormShape ? true : string extends keyof FormShape ? true : false;
+export interface UpdateIntent extends TypedIntentDefinition {
+    dispatch<FieldShape = this['FormShape']>(options: IsUntypedFormShape<this['FormShape']> extends true ? {
+        name?: string | undefined;
+        index?: number | undefined;
+        value: unknown;
+    } : {
         name?: FieldName<FieldShape>;
-        /**
-         * Specify the index of the item to update if the field is an array.
-         */
         index?: undefined;
-        /**
-         * The new value for the field or fieldset.
-         */
         value: DefaultValue<FieldShape>;
     } | {
-        /**
-         * The name of the field. If you provide a fieldset name, it will update all fields within that fieldset.
-         */
-        name: FieldName<FieldShape>;
-        /**
-         * Specify the index of the item to update if the field is an array.
-         */
+        name: FieldName<FieldShape extends Array<any> | null | undefined ? FieldShape : never>;
         index: number;
-        /**
-         * The new value for the field or fieldset.
-         * When index is specified, this should be the item type, not the array type.
-         */
-        value: unknown extends FieldShape ? any : FieldShape extends Array<infer ItemShape> ? ItemShape : any;
+        value: NonNullable<FieldShape> extends Array<infer ItemShape> ? DefaultValue<ItemShape> : never;
     }): void;
-    /**
-     * Insert a new item into an array field.
-     */
-    insert<FieldShape extends Array<any> | null | undefined>(options: {
-        /**
-         * The name of the array field to insert into.
-         */
+}
+export interface InsertIntent extends TypedIntentDefinition {
+    dispatch<FieldShape extends Array<any> | null | undefined>(options: {
         name: FieldName<FieldShape>;
-        /**
-         * The index at which to insert the new item.
-         * If not provided, it will be added to the end of the array.
-         */
         index?: number;
-        /**
-         * The default value for the new item.
-         */
         defaultValue?: NonNullable<FieldShape> extends Array<infer ItemShape> ? DefaultValue<ItemShape> : never;
-        /**
-         * The name of a field to read the value from.
-         * When specified, the value is read from this field, validated,
-         * and if valid, inserted into the array and the source field is cleared.
-         * If validation fails, the error is shown on the source field instead.
-         * Requires the validation error to be available synchronously.
-         */
         from?: string;
-        /**
-         * What to do when the insert causes a validation error on the array.
-         * - 'revert': Don't insert, keep original array state.
-         * Requires the validation error to be available synchronously.
-         */
         onInvalid?: 'revert';
     }): void;
-    /**
-     * Remove an item from an array field.
-     */
-    remove<FieldShape extends Array<any> | null | undefined>(options: {
-        /**
-         * The name of the array field to remove from.
-         */
+}
+export interface RemoveIntent extends TypedIntentDefinition {
+    dispatch<FieldShape extends Array<any> | null | undefined>(options: {
         name: FieldName<FieldShape>;
-        /**
-         * The index of the item to remove.
-         */
         index: number;
-        /**
-         * What to do when the remove causes a validation error on the array.
-         * - 'revert': Don't remove, keep original item as-is.
-         * - 'insert': Remove the item but insert a new blank item at the end.
-         * Requires the validation error to be available synchronously.
-         */
         onInvalid?: 'revert' | 'insert';
-        /**
-         * The default value for the new item when onInvalid is 'insert'.
-         */
         defaultValue?: NonNullable<FieldShape> extends Array<infer ItemShape> ? DefaultValue<ItemShape> : never;
     }): void;
-    /**
-     * Reorder items in an array field.
-     */
-    reorder(options: {
-        name: FieldName<Array<any>>;
-        from: number;
-        to: number;
-    }): void;
 }
-export type FormIntent<Dispatcher extends IntentDispatcher = IntentDispatcher> = {
-    [Type in keyof Dispatcher]: Dispatcher[Type] extends (...args: infer Args) => void ? {
-        type: Type;
-        payload: Args extends [infer Payload] ? Payload : undefined;
+export type ReorderIntent = (options: {
+    name: FieldName<Array<any>>;
+    from: number;
+    to: number;
+}) => void;
+export type DefaultIntentHandlers = {
+    submit: IntentHandler<SubmitIntent>;
+    reset: IntentHandler<ResetIntent>;
+    validate: IntentHandler<ValidateIntent>;
+    update: IntentHandler<UpdateIntent>;
+    insert: IntentHandler<InsertIntent>;
+    remove: IntentHandler<RemoveIntent>;
+    reorder: IntentHandler<ReorderIntent>;
+};
+export type IntentDispatcher<FormShape extends Record<string, any>, CustomIntentHandlers extends Record<string, IntentHandler<any, any>> = {}> = {
+    [Type in keyof (DefaultIntentHandlers & ([CustomIntentHandlers] extends [never] ? {} : CustomIntentHandlers))]: (DefaultIntentHandlers & ([CustomIntentHandlers] extends [never] ? {} : CustomIntentHandlers))[Type] extends IntentHandler<infer Dispatch, any> ? IntentDispatch<Dispatch, FormShape> : never;
+};
+export type FormIntent<FormShape extends Record<string, any>, Handlers extends Record<string, IntentHandler<any, any>>> = {
+    [K in keyof ([Handlers] extends [never] ? {} : Handlers)]: ([
+        Handlers
+    ] extends [never] ? {} : Handlers)[K] extends IntentHandler<infer Dispatch, infer Payload> ? {
+        type: K & string;
+        payload: IntentHandlerPayload<Dispatch, Payload, FormShape>;
     } : never;
-}[keyof Dispatcher];
-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>(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;
-    }, {
-        reset: (defaultValue?: Record<string, unknown> | null) => FormState<ErrorShape>;
-        cancelled?: boolean;
-    }>): FormState<ErrorShape>;
+}[keyof ([Handlers] extends [never] ? {} : Handlers)];
+export type IntentHandler<Dispatch extends IntentDefinition = (payload: any) => void, Payload = never> = {
+    parse<FormShape extends Record<string, any>>(...args: Parameters<IntentDispatch<Dispatch, FormShape>>): IntentHandlerPayload<Dispatch, Payload, FormShape>;
+    resolve?<FormShape extends Record<string, any>>(ctx: {
+        value: Record<string, FormValue>;
+        payload: IntentHandlerPayload<Dispatch, Payload, FormShape>;
+    }): Record<string, FormValue> | undefined;
+    apply?<FormShape extends Record<string, any>, ErrorShape>(ctx: {
+        result: SubmissionResult<ErrorShape>;
+        payload: IntentHandlerPayload<Dispatch, Payload, FormShape>;
+    }): SubmissionResult<ErrorShape>;
+    touch?<FormShape extends Record<string, any>>(ctx: {
+        name: string;
+        payload: IntentHandlerPayload<Dispatch, Payload, FormShape>;
+    }): boolean;
+    move?<FormShape extends Record<string, any>>(ctx: {
+        name: string;
+        status: ApplyStatus;
+        targetValue: Record<string, FormValue> | undefined;
+        payload: IntentHandlerPayload<Dispatch, Payload, FormShape>;
+    }): string | null;
+};
+export type CustomStateHandler<State, CustomIntentHandlers extends Record<string, IntentHandler<any, any>> = {}, ErrorShape = any> = {
+    initialize(): State;
+    reset?: boolean | ((state: State, ctx: {
+        result: SubmissionResult<ErrorShape> | undefined;
+    }) => State);
+    handleIntent?(state: State, ctx: {
+        intent: FormIntent<any, DefaultIntentHandlers & CustomIntentHandlers>;
+        submission: Submission;
+    }): State;
+    handleResult?(state: State, ctx: {
+        intent: FormIntent<any, DefaultIntentHandlers & CustomIntentHandlers>;
+        result: SubmissionResult<ErrorShape>;
+        phase: 'client' | 'server';
+    }): State;
+};
+export type FormCustomState<Handlers extends Record<string, CustomStateHandler<any, any, any>>> = {
+    [Key in keyof Handlers]: Handlers[Key] extends CustomStateHandler<infer State, any, any> ? State : never;
+};
+type CustomStateDefinition<CustomStateHandlers extends Record<string, CustomStateHandler<any, any, any>>, IntentHandlers extends Record<string, IntentHandler<any, any>>> = {
+    [Key in keyof CustomStateHandlers]: CustomStateHandlers[Key] extends CustomStateHandler<any, infer RequiredIntents, any> ? Exclude<keyof RequiredIntents, keyof IntentHandlers> extends never ? RequiredIntents extends Pick<IntentHandlers, Extract<keyof RequiredIntents, keyof IntentHandlers>> ? CustomStateHandlers[Key] : never : never : never;
 };
 type BaseCombine<T, K extends PropertyKey = T extends unknown ? keyof T : never> = T extends unknown ? T & Partial<Record<Exclude<K, keyof T>, never>> : never;
 export type Combine<T> = {
@@ -635,7 +635,7 @@ export type Fieldset<FieldShape, ErrorShape = any, CustomFieldMetadata extends R
     [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 = any, 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> = {}, CustomState extends Record<string, unknown> = {}> = Readonly<{
     /** Unique identifier that changes on form reset */
     key: string;
     /** The form's unique identifier. */
@@ -656,6 +656,8 @@ export type FormMetadata<ErrorShape = any, CustomFormMetadata extends Record<str
     fieldErrors: Record<string, ErrorShape>;
     /** The form's initial default values. */
     defaultValue: Record<string, unknown>;
+    /** Current custom state for the form. */
+    customState: CustomState;
     /** Form props object for spreading onto the <form> element. */
     props: Readonly<{
         id: string;
@@ -665,7 +667,7 @@ export type FormMetadata<ErrorShape = any, CustomFormMetadata extends Record<str
         noValidate: boolean;
     }>;
     /** The current state of the form */
-    context: FormContext<ErrorShape>;
+    context: FormContext<ErrorShape, CustomState>;
     /** Method to get metadata for a specific field by name. */
     getField<FieldShape>(name: FieldName<FieldShape>): FieldMetadata<FieldShape, ErrorShape, CustomFieldMetadata>;
     /** Method to get a fieldset object for nested object fields. */
@@ -679,12 +681,18 @@ export type FormMetadata<ErrorShape = any, CustomFormMetadata extends Record<str
  * Form metadata without custom extensions. This is the type received in `extendFormMetadata`.
  * Equivalent to `FormMetadata<ErrorShape, {}, CustomFieldMetadata>`.
  */
-export type BaseFormMetadata<ErrorShape = any, CustomFieldMetadata extends Record<string, unknown> = {}> = FormMetadata<ErrorShape, {}, CustomFieldMetadata>;
+export type BaseFormMetadata<ErrorShape = any, CustomState extends Record<string, unknown> = {}> = FormMetadata<ErrorShape, {}, {}, CustomState>;
 export type ValidateResult<ErrorShape, Value> = FormError<ErrorShape> | null | {
     error: FormError<ErrorShape> | null;
     value?: Value;
 };
-export type ValidateContext<SchemaValue, SchemaErrorShape> = {
+export type StagedValidateResult<ErrorShape, Value> = {
+    /** The validation result available immediately. */
+    result: ValidateResult<ErrorShape, Value>;
+    /** A complete validation result that replaces the immediate result when resolved. */
+    pending: Promise<ValidateResult<ErrorShape, Value>>;
+};
+export type ValidateContext<SchemaValue, SchemaErrorShape, Intent extends UnknownIntent | undefined = UnknownIntent | undefined> = {
     /**
      * The submitted values mapped by field name.
      * Supports nested names like `user.email` and indexed names like `items[0].id`.
@@ -698,7 +706,7 @@ export type ValidateContext<SchemaValue, SchemaErrorShape> = {
     /**
      * The submission intent derived from the button that triggered the form submission.
      */
-    intent: UnknownIntent | null;
+    intent: Intent;
     /**
      * The raw FormData object of the submission.
      */
@@ -717,10 +725,7 @@ export type ValidateContext<SchemaValue, SchemaErrorShape> = {
      */
     schemaValue: SchemaValue;
 };
-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 type ValidateHandler<ErrorShape, Value, SchemaValue = undefined, SchemaErrorShape = ErrorShape, Intent extends UnknownIntent | undefined = UnknownIntent | undefined> = (ctx: ValidateContext<SchemaValue, SchemaErrorShape, Intent>) => ValidateResult<ErrorShape, Value> | Promise<ValidateResult<ErrorShape, Value>> | StagedValidateResult<ErrorShape, Value> | undefined;
 export interface FormInputEvent extends React.FormEvent<HTMLFormElement> {
     currentTarget: EventTarget & HTMLFormElement;
     target: EventTarget & (HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement | HTMLFieldSetElement);
@@ -733,7 +738,7 @@ export interface FormFocusEvent extends React.FormEvent<HTMLFormElement> {
 export type ErrorContext<ErrorShape> = {
     formElement: HTMLFormElement;
     error: FormError<ErrorShape>;
-    intent: UnknownIntent | null;
+    intent: UnknownIntent | undefined;
 };
 export type ErrorHandler<ErrorShape> = (ctx: ErrorContext<ErrorShape>) => void;
 export type InputHandler = (event: FormInputEvent) => void;
@@ -757,7 +762,7 @@ export type SubmitHandler<FormShape extends Record<string, any> = Record<string,
  * type ErrorShape = InferBaseErrorShape<typeof config>; // { message: string }
  * ```
  */
-export type InferBaseErrorShape<Config> = Config extends FormsConfig<infer ErrorShape, any, any, any, any> ? ErrorShape : string;
+export type InferBaseErrorShape<Config> = Config extends FormsConfig<infer ErrorShape, any, any, 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.
@@ -774,7 +779,7 @@ export type InferBaseErrorShape<Config> = Config extends FormsConfig<infer Error
  * >;
  * ```
  */
-export type InferCustomFormMetadata<Config> = Config extends FormsConfig<any, any, any, infer CustomFormMetadata, any> ? CustomFormMetadata : {};
+export type InferCustomFormMetadata<Config> = Config extends FormsConfig<any, any, any, infer CustomFormMetadata, any, any, any> ? CustomFormMetadata : {};
 /**
  * Infer the custom field metadata extension from a FormsConfig.
  * Use this to compose with FieldMetadata or Fieldset types.
@@ -788,7 +793,11 @@ 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, any, infer CustomFieldMetadata> ? CustomFieldMetadata : {};
+export type InferCustomFieldMetadata<Config> = Config extends FormsConfig<any, any, any, any, infer CustomFieldMetadata, any, any> ? CustomFieldMetadata : {};
+/**
+ * Infer the configured custom-state shape from a FormsConfig.
+ */
+export type InferCustomState<Config> = Config extends FormsConfig<any, any, any, any, any, any, infer CustomStateHandlers> ? FormCustomState<CustomStateHandlers> : {};
 /**
  * Transform a type to make specific keys conditional based on FieldShape.
  * Keys in ConditionalKeys will only be present when FieldShape extends the specified type.

package/dist/future/util.d.ts

@@ -13,10 +13,10 @@ export declare function getPathArray<Type>(formValue: Record<string, Type> | nul
  */
 export declare function updatePathValue<Data>(data: Record<string, Data>, name: string, value: Data | Record<string, Data>): Record<string, Data>;
 /**
- * Creates a function that updates array indices in field paths.
- * Returns null to remove fields, or updated path with new index.
+ * Updates array indices in a field path.
+ * Returns null to remove fields, or the updated path with a new index.
  */
-export declare function createPathIndexUpdater(listName: string, update: (index: number) => number | null): (name: string) => string | null;
+export declare function updatePathIndex(name: string, listName: string, update: (index: number) => number | null): string | 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;
@@ -25,7 +25,7 @@ export declare function normalizeValidateResult<ErrorShape, Value>(result: Valid
 /**
  * Handles different validation result formats:
  * - Promise: async validation only
- * - Array: [syncResult, asyncPromise]
+ * - Staged result: immediate result with a pending result
  * - Object: sync validation only
  */
 export declare function resolveValidateResult<ErrorShape, Value>(result: ReturnType<ValidateHandler<ErrorShape, Value>>): {
@@ -59,10 +59,6 @@ export declare function transformKeys<Value>(obj: Record<string, Value>, fn: (ke
  * Returns original array if item exists, new array if added.
  */
 export declare function appendUniqueItem<Item>(list: Array<Item>, item: Item): Item[];
-/**
- * Maps over array and filters out null results.
- */
-export declare function compactMap<Item>(list: Array<NonNullable<Item>>, fn: (value: Item) => Item | null): Array<Item>;
 export declare function generateUniqueKey(): string;
 /**
  * Creates a type-only marker for TypeScript inference.