@conform-to/react 1.15.1 → 1.17.0

package/dist/future/state.mjs

@@ -1,6 +1,6 @@
 import { objectSpread2 as _objectSpread2 } from '../_virtual/_rollupPluginBabelHelpers.mjs';
-import { getPathSegments, getRelativePath, appendPathSegment, deepEqual, getValueAtPath, formatPathSegments, serialize } from '@conform-to/dom/future';
-import { generateUniqueKey, merge, getArrayAtPath } from './util.mjs';
+import { getPathSegments, getRelativePath, serialize, appendPathSegment, deepEqual, getValueAtPath, formatPathSegments } from '@conform-to/dom/future';
+import { when, generateUniqueKey, merge, getArrayAtPath } from './util.mjs';
 
 function initializeState(options) {
   var _options$resetKey, _options$defaultValue;
@@ -53,12 +53,13 @@ function updateState(state, action) {
     type: 'validate'
   };
   var handler = (_action$ctx$handlers = action.ctx.handlers) === null || _action$ctx$handlers === void 0 ? void 0 : _action$ctx$handlers[intent.type];
-  if (typeof (handler === null || handler === void 0 ? void 0 : handler.onUpdate) === 'function') {
-    var _handler$validatePayl, _handler$validatePayl2;
-    if ((_handler$validatePayl = (_handler$validatePayl2 = handler.validatePayload) === null || _handler$validatePayl2 === void 0 ? void 0 : _handler$validatePayl2.call(handler, intent.payload)) !== null && _handler$validatePayl !== void 0 ? _handler$validatePayl : true) {
-      return handler.onUpdate(state, _objectSpread2(_objectSpread2({}, action), {}, {
+  if (typeof (handler === null || handler === void 0 ? void 0 : handler.update) === 'function') {
+    var _handler$validate, _handler$validate2;
+    if ((_handler$validate = (_handler$validate2 = handler.validate) === null || _handler$validate2 === void 0 ? void 0 : _handler$validate2.call(handler, intent.payload)) !== null && _handler$validate !== void 0 ? _handler$validate : true) {
+      return handler.update(state, _objectSpread2(_objectSpread2({}, action), {}, {
         ctx: {
-          reset: action.ctx.reset
+          reset: action.ctx.reset,
+          cancelled: action.ctx.cancelled
         },
         intent: {
           type: intent.type,
@@ -237,7 +238,8 @@ function getConstraint(context, name) {
   return constraint;
 }
 function getFormMetadata(context, options) {
-  return {
+  var _options$extendFormMe, _options$extendFormMe2;
+  var metadata = {
     key: context.state.resetKey,
     id: context.formId,
     errorId: "".concat(context.formId, "-form-error"),
@@ -270,31 +272,41 @@ function getFormMetadata(context, options) {
       return getField(context, {
         name,
         serialize: options === null || options === void 0 ? void 0 : options.serialize,
-        customize: options === null || options === void 0 ? void 0 : options.customize
+        extendFieldMetadata: options === null || options === void 0 ? void 0 : options.extendFieldMetadata
       });
     },
     getFieldset(name) {
       return getFieldset(context, {
         name,
         serialize: options === null || options === void 0 ? void 0 : options.serialize,
-        customize: options === null || options === void 0 ? void 0 : options.customize
+        extendFieldMetadata: options === null || options === void 0 ? void 0 : options.extendFieldMetadata
       });
     },
     getFieldList(name) {
       return getFieldList(context, {
         name,
         serialize: options === null || options === void 0 ? void 0 : options.serialize,
-        customize: options === null || options === void 0 ? void 0 : options.customize
+        extendFieldMetadata: options === null || options === void 0 ? void 0 : options.extendFieldMetadata
       });
     }
   };
+  var customMetadata = (_options$extendFormMe = options === null || options === void 0 || (_options$extendFormMe2 = options.extendFormMetadata) === null || _options$extendFormMe2 === void 0 ? void 0 : _options$extendFormMe2.call(options, metadata)) !== null && _options$extendFormMe !== void 0 ? _options$extendFormMe : {};
+  var descriptors = Object.getOwnPropertyDescriptors(customMetadata);
+  var extended = Object.create(metadata);
+  Object.defineProperties(extended, descriptors);
+  return extended;
 }
 function getField(context, options) {
+  var _extendFieldMetadata;
   var {
     key,
     name,
     serialize: serialize$1 = serialize,
-    customize
+    extendFieldMetadata,
+    form = getFormMetadata(context, {
+      serialize: serialize$1,
+      extendFieldMetadata
+    })
   } = options;
   var id = "".concat(context.formId, "-field-").concat(name.replace(/[^a-zA-Z0-9._-]/g, '_'));
   var constraint = getConstraint(context, name);
@@ -313,6 +325,7 @@ function getField(context, options) {
     max: constraint === null || constraint === void 0 ? void 0 : constraint.max,
     step: constraint === null || constraint === void 0 ? void 0 : constraint.step,
     multiple: constraint === null || constraint === void 0 ? void 0 : constraint.multiple,
+    accept: constraint === null || constraint === void 0 ? void 0 : constraint.accept,
     get defaultValue() {
       return getDefaultValue(context, name, serialize$1);
     },
@@ -347,40 +360,27 @@ function getField(context, options) {
       return getFieldset(context, {
         name: name,
         serialize: serialize$1,
-        customize
+        extendFieldMetadata
       });
     },
+    // @ts-expect-error The return type includes CustomFieldMetadata which BaseFieldMetadata
+    // doesn't account for. This is a type-level limitation; runtime behavior is correct.
     getFieldList() {
       return getFieldList(context, {
-        name: name,
+        name,
         serialize: serialize$1,
-        customize
+        extendFieldMetadata
       });
     }
   };
-  if (typeof customize !== 'function') {
-    return metadata;
-  }
-  var customMetadata = null;
-  return new Proxy(metadata, {
-    get(target, prop, receiver) {
-      var _customMetadata;
-      if (Reflect.has(target, prop)) {
-        return Reflect.get(target, prop, receiver);
-      }
-      (_customMetadata = customMetadata) !== null && _customMetadata !== void 0 ? _customMetadata : customMetadata = customize(metadata);
-      if (Reflect.has(customMetadata, prop)) {
-        return Reflect.get(customMetadata, prop, receiver);
-      }
-
-      // Allow React DevTools to inspect the object
-      // without throwing errors for internal properties
-      if (typeof prop === 'symbol' || prop === '$$typeof') {
-        return undefined;
-      }
-      throw new Error("Property \"".concat(String(prop), "\" does not exist on field metadata. ") + "If you have defined the CustomMetadata interface to include \"".concat(String(prop), "\", make sure to also implement it through the \"defineCustomMetadata\" property on <FormOptionsProvider />."));
-    }
-  });
+  var customMetadata = (_extendFieldMetadata = extendFieldMetadata === null || extendFieldMetadata === void 0 ? void 0 : extendFieldMetadata(metadata, {
+    form,
+    when
+  })) !== null && _extendFieldMetadata !== void 0 ? _extendFieldMetadata : {};
+  var descriptors = Object.getOwnPropertyDescriptors(customMetadata);
+  var extended = Object.create(metadata);
+  Object.defineProperties(extended, descriptors);
+  return extended;
 }
 
 /**
@@ -390,10 +390,16 @@ function getFieldset(context, options) {
   return new Proxy({}, {
     get(target, name, receiver) {
       if (typeof name === 'string') {
+        var _options$form;
+        (_options$form = options.form) !== null && _options$form !== void 0 ? _options$form : options.form = getFormMetadata(context, {
+          serialize: options === null || options === void 0 ? void 0 : options.serialize,
+          extendFieldMetadata: options === null || options === void 0 ? void 0 : options.extendFieldMetadata
+        });
         return getField(context, {
           name: appendPathSegment(options === null || options === void 0 ? void 0 : options.name, name),
           serialize: options.serialize,
-          customize: options.customize
+          extendFieldMetadata: options.extendFieldMetadata,
+          form: options.form
         });
       }
       return Reflect.get(target, name, receiver);
@@ -410,7 +416,7 @@ function getFieldList(context, options) {
     return getField(context, {
       name: appendPathSegment(options.name, index),
       serialize: options.serialize,
-      customize: options.customize,
+      extendFieldMetadata: options.extendFieldMetadata,
       key
     });
   });

package/dist/future/types.d.ts

@@ -46,28 +46,33 @@ 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;
+    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;
+    focus: () => 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
      * if you want to move focus to the input.
      */
-    blur(): void;
+    blur: () => void;
 };
-export type Selector<FormValue, Result> = (formData: FormValue | null, lastResult: Result | undefined) => Result;
-export type UseFormDataOptions = {
+export type Selector<FormValue, Result> = (formData: FormValue, lastResult: Result | undefined) => Result;
+export type UseFormDataOptions<Value = undefined> = {
     /**
      * Set to `true` to preserve file inputs and receive a `FormData` object in the selector.
      * If omitted or `false`, the selector receives a `URLSearchParams` object, where all values are coerced to strings.
      */
     acceptFiles?: boolean;
+    /**
+     * The fallback value to return when the form element is not available (e.g., on SSR or initial client render).
+     * If not provided, the hook returns `undefined` when the form is unavailable.
+     */
+    fallback?: Value;
 };
 export type DefaultValue<Shape> = Shape extends Record<string, any> ? {
     [Key in keyof Shape]?: DefaultValue<Shape[Key]>;
@@ -95,6 +100,152 @@ export type FormAction<ErrorShape extends BaseErrorShape = DefaultErrorShape, In
     intent: Intent;
     ctx: Context;
 };
+/**
+ * Augment this interface to customize schema type inference for your schema library.
+ *
+ * @example
+ * ```ts
+ * import type { ZodTypeAny, input, output } from 'zod';
+ * import type { ZodSchemaOptions } from '@conform-to/zod/v3/future';
+ *
+ * declare module '@conform-to/react/future' {
+ *   interface CustomSchemaTypes<Schema> {
+ *     input: Schema extends ZodTypeAny ? input<Schema> : never;
+ *     output: Schema extends ZodTypeAny ? output<Schema> : never;
+ *     options: Schema extends ZodTypeAny ? ZodSchemaOptions : never;
+ *   }
+ * }
+ * ```
+ */
+export interface CustomSchemaTypes<Schema = unknown> {
+}
+/**
+ * Infer schema options type.
+ * Uses CustomSchemaTypes if augmented, otherwise returns never.
+ */
+export type InferOptions<Schema> = [Schema] extends [undefined] ? never : CustomSchemaTypes<Schema> extends {
+    options: infer T;
+} ? T : never;
+/**
+ * Marker type for conditional field metadata properties.
+ * Used to indicate that a property should only be present when FieldShape matches a condition.
+ */
+export type ConditionalFieldMetadata<T, Condition> = T & {
+    '~condition': Condition;
+};
+/**
+ * Check if T is a FieldName type by checking if '~shape' is a known key.
+ * Plain strings don't have '~shape' in their keyof, but FieldName<T> does.
+ */
+type IsFieldName<T> = '~shape' extends keyof T ? true : false;
+/**
+ * Transforms a single value, restoring FieldName<unknown> to FieldName<FieldShape>.
+ */
+type RestoreFieldShapeValue<T, FieldShape> = T extends ConditionalFieldMetadata<infer Inner, infer Condition> ? FieldShape extends Condition ? Inner : never : IsFieldName<T> extends true ? FieldName<FieldShape> : T;
+/**
+ * Restores FieldShape-dependent types that were inferred as `unknown`.
+ * This is needed because TypeScript infers generic return types with unresolved type parameters.
+ * Also handles conditional field metadata by checking if FieldShape extends the condition.
+ *
+ * Transforms up to 2 levels deep to handle cases like `textFieldProps.name`.
+ */
+export type RestoreFieldShape<T, FieldShape> = {
+    [K in keyof T]: RestoreFieldShapeValue<T[K], FieldShape> extends infer V ? V extends Record<string, unknown> ? {
+        [P in keyof V]: RestoreFieldShapeValue<V[P], FieldShape>;
+    } : V : never;
+};
+/**
+ * Type guard function for conditional field metadata.
+ * Used to specify when a custom field metadata property should be available.
+ */
+export type FieldShapeGuard<Condition> = (shape: unknown) => shape is Condition;
+/**
+ * Function type for creating conditional field metadata based on shape constraints.
+ */
+export type DefineConditionalField = <FieldShape, ErrorShape, Metadata>(metadata: BaseFieldMetadata<unknown, ErrorShape>, shape: FieldShapeGuard<FieldShape>, fn: (metadata: BaseFieldMetadata<FieldShape, ErrorShape>) => Metadata) => ConditionalFieldMetadata<Metadata, FieldShape>;
+/**
+ * Extract the condition type from a FieldShapeGuard.
+ */
+export type ExtractFieldCondition<T> = T extends FieldShapeGuard<infer C> ? C : never;
+/**
+ * Extract conditions from a record of field shape guards.
+ */
+export type ExtractFieldConditions<T extends Record<string, FieldShapeGuard<any>>> = {
+    [K in keyof T]: ExtractFieldCondition<T[K]>;
+};
+/**
+ * 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>> = {
+    /**
+     * 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';
+    /**
+     * 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
+     * ```ts
+     * import { configureForms } from '@conform-to/react/future';
+     * import {
+     *   isSchema,
+     *   validateSchema,
+     *   getConstraints,
+     * } from '@conform-to/zod/v3/future';
+     *
+     * const { useForm } = configureForms({
+     *   isSchema,
+     *   validateSchema,
+     *   getConstraints,
+     * });
+     * ```
+     */
+    isSchema: (schema: unknown) => schema is BaseSchema;
+    /**
+     * Validates a schema against form payload.
+     */
+    validateSchema: <Schema extends BaseSchema>(schema: Schema, payload: Record<string, FormValue>, options?: InferOptions<Schema>) => MaybePromise<{
+        error: FormError<string> | null;
+        value?: InferOutput<Schema>;
+    }>;
+    /**
+     * A type guard function to specify the shape of error objects.
+     */
+    isError?: (error: unknown) => error is BaseErrorShape;
+    /**
+     * Extracts HTML validation constraints from a schema.
+     */
+    getConstraints?: <Schema extends BaseSchema>(schema: Schema) => Record<string, ValidationAttributes> | undefined;
+    /**
+     * Extends form metadata with custom properties.
+     */
+    extendFormMetadata?: <ErrorShape extends BaseErrorShape>(metadata: BaseFormMetadata<ErrorShape>) => 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>;
+        when: DefineConditionalField;
+    }) => CustomFieldMetadata;
+};
 export type GlobalFormOptions = {
     /**
      * The name of the submit button field that indicates the submission intent.
@@ -129,9 +280,23 @@ export type NonPartial<T> = {
 };
 export type RequireKey<T, K extends keyof T> = Prettify<T & Pick<NonPartial<T>, K>>;
 export type BaseSchemaType = StandardSchemaV1<any, any>;
-export type InferInput<Schema> = Schema extends StandardSchemaV1<infer input, any> ? input : unknown;
-export type InferOutput<Schema> = Schema extends StandardSchemaV1<any, infer output> ? output : undefined;
-export type BaseFormOptions<FormShape extends Record<string, any> = Record<string, any>, ErrorShape extends BaseErrorShape = string extends BaseErrorShape ? string : BaseErrorShape, Value = undefined, Schema = undefined> = {
+/**
+ * Infer schema input type.
+ * For StandardSchemaV1 schemas (zod, valibot, etc.), uses StandardSchemaV1.InferInput.
+ * For other schemas, uses CustomSchemaTypes if augmented.
+ */
+export type InferInput<Schema> = Schema extends StandardSchemaV1 ? StandardSchemaV1.InferInput<Schema> : CustomSchemaTypes<Schema> extends {
+    input: infer T;
+} ? T : Record<string, any>;
+/**
+ * Infer schema output type.
+ * For StandardSchemaV1 schemas (zod, valibot, etc.), uses StandardSchemaV1.InferOutput.
+ * For other schemas, uses CustomSchemaTypes if augmented.
+ */
+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> = {
     /** 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. */
@@ -144,6 +309,11 @@ export type BaseFormOptions<FormShape extends Record<string, any> = Record<strin
     defaultValue?: DefaultValue<FormShape> | undefined;
     /** HTML validation attributes for fields (required, minLength, pattern, etc.). */
     constraint?: Record<string, ValidationAttributes> | undefined;
+    /**
+     * Schema-specific validation options (e.g., Zod's errorMap).
+     * The available options depend on the schema library configured in `configureForms`.
+     */
+    schemaOptions?: InferOptions<Schema>;
     /**
      * Determines when validation should run for the first time on a field.
      * Overrides the global default set by FormOptionsProvider if provided.
@@ -167,7 +337,7 @@ export type BaseFormOptions<FormShape extends Record<string, any> = Record<strin
     /** 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;
 };
-export type FormOptions<FormShape extends Record<string, any> = Record<string, any>, ErrorShape extends BaseErrorShape = string extends BaseErrorShape ? string : BaseErrorShape, Value = undefined, Schema = undefined, RequiredKeys extends keyof BaseFormOptions<FormShape, ErrorShape, Value, Schema> = never> = RequireKey<BaseFormOptions<FormShape, ErrorShape, Value, Schema>, RequiredKeys>;
+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> {
     /** The form's unique identifier */
     formId: string;
@@ -252,7 +422,7 @@ export interface IntentDispatcher<FormShape extends Record<string, any> = Record
     /**
      * Insert a new item into an array field.
      */
-    insert<FieldShape extends Array<any>>(options: {
+    insert<FieldShape extends Array<any> | null | undefined>(options: {
         /**
          * The name of the array field to insert into.
          */
@@ -265,20 +435,45 @@ export interface IntentDispatcher<FormShape extends Record<string, any> = Record
         /**
          * The default value for the new item.
          */
-        defaultValue?: FieldShape extends Array<infer ItemShape> ? DefaultValue<ItemShape> : never;
+        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(options: {
+    remove<FieldShape extends Array<any> | null | undefined>(options: {
         /**
          * The name of the array field to remove from.
          */
-        name: FieldName<Array<any>>;
+        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.
@@ -295,14 +490,16 @@ export type FormIntent<Dispatcher extends IntentDispatcher = IntentDispatcher> =
         payload: Args extends [infer Payload] ? Payload : undefined;
     } : never;
 }[keyof Dispatcher];
-export type ActionHandler<Signature extends (payload: any) => void = (payload: any) => void> = {
-    validatePayload?(...args: UnknownArgs<Parameters<Signature>>): boolean;
-    onApply?(value: Record<string, FormValue>, ...args: Parameters<Signature>): Record<string, FormValue> | undefined;
-    onUpdate?<ErrorShape extends BaseErrorShape>(state: FormState<ErrorShape>, action: FormAction<ErrorShape, {
+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, {
         type: string;
         payload: Signature extends (payload: infer Payload) => void ? Payload : undefined;
     }, {
         reset: (defaultValue?: Record<string, unknown> | null) => FormState<ErrorShape>;
+        cancelled?: boolean;
     }>): FormState<ErrorShape>;
 };
 type BaseCombine<T, K extends PropertyKey = T extends unknown ? keyof T : never> = T extends unknown ? T & Partial<Record<Exclude<K, keyof T>, never>> : never;
@@ -329,8 +526,16 @@ export type BaseErrorShape = CustomTypes extends {
 export type DefaultErrorShape = CustomTypes extends {
     errorShape: infer Shape;
 } ? Shape : string;
-/** Base field metadata object containing field state, validation attributes, and accessibility IDs. */
-export type BaseMetadata<FieldShape, ErrorShape extends BaseErrorShape> = ValidationAttributes & {
+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 & {
     /** Unique key for React list rendering (for array fields). */
     key: string | undefined;
     /** The field name path exactly as provided. */
@@ -380,27 +585,31 @@ export type BaseMetadata<FieldShape, ErrorShape extends BaseErrorShape> = Valida
     /** 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}`). */
     ariaDescribedBy: string | undefined;
     /** Method to get nested fieldset for object fields under this field. */
-    getFieldset<FieldsetShape = keyof NonNullable<FieldShape> extends never ? unknown : FieldShape>(): Fieldset<FieldsetShape, ErrorShape>;
+    getFieldset<FieldsetShape = keyof NonNullable<FieldShape> extends never ? unknown : FieldShape>(): Fieldset<FieldsetShape, ErrorShape, CustomFieldMetadata>;
     /** Method to get array of fields for list/array fields under this field. */
     getFieldList<FieldItemShape = [FieldShape] extends [
         Array<infer ItemShape> | null | undefined
-    ] ? ItemShape : unknown>(): Array<FieldMetadata<FieldItemShape, ErrorShape>>;
-};
-export type SatisfyComponentProps<ElementType extends React.ElementType, CustomProps extends React.ComponentPropsWithoutRef<ElementType>> = CustomProps;
+    ] ? ItemShape : unknown>(): Array<FieldMetadata<FieldItemShape, ErrorShape, CustomFieldMetadata>>;
+} & RestoreFieldShape<CustomFieldMetadata, FieldShape>>>;
 /**
- * Interface for extending field metadata with additional properties.
+ * Field metadata without custom extensions. This is the type received in `extendFieldMetadata`.
+ * Equivalent to `FieldMetadata<FieldShape, ErrorShape, {}>`.
  */
-export interface CustomMetadata<FieldShape = any, ErrorShape extends BaseErrorShape = DefaultErrorShape> {
-}
-export type CustomMetadataDefinition = <FieldShape, ErrorShape extends BaseErrorShape>(metadata: BaseMetadata<FieldShape, ErrorShape>) => keyof CustomMetadata<FieldShape, ErrorShape> extends never ? {} : CustomMetadata<any, any>;
-/** Field metadata object containing field state, validation attributes, and nested field access methods. */
-export type FieldMetadata<FieldShape, ErrorShape extends BaseErrorShape = DefaultErrorShape> = Readonly<(keyof CustomMetadata<FieldShape, ErrorShape> extends never ? {} : CustomMetadata<FieldShape, ErrorShape>) & BaseMetadata<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>;
 /** Fieldset object containing all form fields as properties with their respective field metadata. */
-export type Fieldset<FieldShape, ErrorShape extends BaseErrorShape = DefaultErrorShape> = {
-    [Key in keyof Combine<FieldShape>]-?: FieldMetadata<Combine<FieldShape>[Key], ErrorShape>;
+export type Fieldset<FieldShape, ErrorShape extends BaseErrorShape = DefaultErrorShape, CustomFieldMetadata extends Record<string, unknown> = DefaultCustomMetadata<FieldShape, ErrorShape>> = {
+    [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> = Readonly<{
+export type FormMetadata<ErrorShape extends BaseErrorShape = DefaultErrorShape, 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. */
@@ -432,14 +641,19 @@ export type FormMetadata<ErrorShape extends BaseErrorShape = DefaultErrorShape>
     /** The current state of the form */
     context: FormContext<ErrorShape>;
     /** Method to get metadata for a specific field by name. */
-    getField<FieldShape>(name: FieldName<FieldShape>): FieldMetadata<FieldShape, ErrorShape>;
+    getField<FieldShape>(name: FieldName<FieldShape>): FieldMetadata<FieldShape, ErrorShape, CustomFieldMetadata>;
     /** Method to get a fieldset object for nested object fields. */
-    getFieldset<FieldShape>(name?: FieldName<FieldShape>): Fieldset<keyof NonNullable<FieldShape> extends never ? unknown : FieldShape, ErrorShape>;
+    getFieldset<FieldShape>(name?: FieldName<FieldShape>): Fieldset<keyof NonNullable<FieldShape> extends never ? unknown : FieldShape, ErrorShape, CustomFieldMetadata>;
     /** Method to get an array of field objects for array fields. */
     getFieldList<FieldShape>(name: FieldName<FieldShape>): Array<FieldMetadata<[
         FieldShape
-    ] extends [Array<infer ItemShape> | null | undefined] ? ItemShape : unknown, ErrorShape>>;
-}>;
+    ] extends [Array<infer ItemShape> | null | undefined] ? ItemShape : unknown, ErrorShape, CustomFieldMetadata>>;
+} & CustomFormMetadata>;
+/**
+ * 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 ValidateResult<ErrorShape, Value> = FormError<ErrorShape> | null | {
     error: FormError<ErrorShape> | null;
     value?: Value;
@@ -508,5 +722,65 @@ export type SubmitContext<FormShape extends Record<string, any> = Record<string,
     }) => 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>;
+/**
+ * Infer the base error shape from a FormsConfig.
+ *
+ * @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;
+/**
+ * Infer the custom form metadata extension from a FormsConfig.
+ * Use this to compose with FormMetadata, FieldMetadata, or Fieldset types.
+ *
+ * @example
+ * ```ts
+ * const { config } = configureForms({
+ *   extendFormMetadata: (meta) => ({ customProp: meta.id })
+ * });
+ * type MyFormMetadata = FormMetadata<
+ *   InferBaseErrorShape<typeof config>,
+ *   InferCustomFormMetadata<typeof config>,
+ *   InferCustomFieldMetadata<typeof config>
+ * >;
+ * ```
+ */
+export type InferCustomFormMetadata<Config> = Config extends FormsConfig<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
+ * ```ts
+ * const { config } = configureForms({
+ *   extendFieldMetadata: (meta) => ({ inputProps: { name: meta.name } })
+ * });
+ * type MyFieldMetadata<T> = FieldMetadata<T, InferBaseErrorShape<typeof config>, InferCustomFieldMetadata<typeof config>>;
+ * type MyFieldset<T> = Fieldset<T, InferBaseErrorShape<typeof config>, InferCustomFieldMetadata<typeof config>>;
+ * ```
+ */
+export type InferCustomFieldMetadata<Config> = Config extends FormsConfig<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
+ * ```ts
+ * type Result = MakeConditional<
+ *   { textFieldProps: {...}, dateRangePickerProps: {...} },
+ *   { dateRangePickerProps: { start: string; end: string } }
+ * >;
+ * // dateRangePickerProps is wrapped with ConditionalFieldMetadata
+ * // and will only be present when FieldShape extends { start: string; end: string }
+ * ```
+ */
+export type MakeConditional<T, ConditionalKeys extends Record<string, unknown>> = Omit<T, keyof ConditionalKeys> & {
+    [K in keyof ConditionalKeys]: K extends keyof T ? ConditionalFieldMetadata<T[K], ConditionalKeys[K]> : never;
+};
+export type MaybePromise<T> = T | Promise<T>;
 export {};
 //# sourceMappingURL=types.d.ts.map