@conform-to/react 1.15.0 → 1.16.0

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;
@@ -329,8 +499,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 +558,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 +614,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 +695,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

package/dist/future/util.d.ts

@@ -1,6 +1,6 @@
 import type { FormError } from '@conform-to/dom/future';
 import type { StandardSchemaV1 } from './standard-schema';
-import { ValidateHandler, ValidateResult } from './types';
+import { ValidateHandler, ValidateResult, BaseFieldMetadata, ConditionalFieldMetadata } from './types';
 export declare function isUndefined(value: unknown): value is undefined;
 export declare function isString(value: unknown): value is string;
 export declare function isNumber(value: unknown): value is number;
@@ -42,6 +42,9 @@ export declare function resolveValidateResult<ErrorShape, Value>(result: ReturnT
         value?: Value | undefined;
     }> | undefined;
 };
+/**
+ * Resolves a StandardSchema validation result to conform's format.
+ */
 export declare function resolveStandardSchemaResult<Value>(result: StandardSchemaV1.Result<Value>): {
     error: FormError<string> | null;
     value?: Value;
@@ -65,4 +68,44 @@ export declare function appendUniqueItem<Item>(list: Array<Item>, item: Item): I
  */
 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.
+ *
+ * This function always returns `true` at runtime. It exists
+ * purely to capture the generic type parameter for compile-time type checking.
+ * No runtime validation is performed.
+ *
+ * Common uses:
+ * - `isError`: Specify the error shape for type inference
+ * - `when`: Narrow field metadata to specific shapes for conditional props
+ *
+ * @example Specify error shape
+ * ```ts
+ * configureForms({
+ *   isError: shape<string>(),  // errors are strings
+ * });
+ * ```
+ *
+ * @example Conditional field metadata
+ * ```ts
+ * extendFieldMetadata(metadata, { when }) {
+ *   return {
+ *     get dateRangePickerProps() {
+ *       return when(metadata, shape<{ start: string; end: string }>(), (m) => ({
+ *         startName: m.getFieldset().start.name,
+ *         endName: m.getFieldset().end.name,
+ *       }));
+ *     },
+ *   };
+ * }
+ * ```
+ */
+export declare function shape<T>(): (value: unknown) => value is T;
+/**
+ * Creates a conditional field metadata property that is only available
+ * when the field shape matches the specified type.
+ */
+export declare function when<FieldShape, ErrorShape, Metadata>(metadata: BaseFieldMetadata<unknown, ErrorShape>, _shape: (value: unknown) => value is FieldShape, fn: (m: BaseFieldMetadata<FieldShape, ErrorShape>) => Metadata): ConditionalFieldMetadata<Metadata, FieldShape>;
+export declare function isStandardSchemaV1(schema: unknown): schema is StandardSchemaV1;
+export declare function validateStandardSchemaV1<Schema extends StandardSchemaV1>(schema: Schema, payload: Record<string, unknown>): any;
 //# sourceMappingURL=util.d.ts.map

package/dist/future/util.js

@@ -118,6 +118,10 @@ function resolveValidateResult(result) {
     asyncResult: asyncResult ? asyncResult.then(normalizeValidateResult) : undefined
   };
 }
+
+/**
+ * Resolves a StandardSchema validation result to conform's format.
+ */
 function resolveStandardSchemaResult(result) {
   if (!result.issues) {
     return {
@@ -149,10 +153,10 @@ function merge(obj, update) {
  */
 function transformKeys(obj, fn) {
   var result = {};
-  for (var [_key, _value] of Object.entries(obj)) {
+  for (var [_key, _value2] of Object.entries(obj)) {
     var _name = fn(_key);
     if (_name !== null) {
-      result[_name] = _value;
+      result[_name] = _value2;
     }
   }
   return result;
@@ -175,9 +179,9 @@ function appendUniqueItem(list, item) {
 function compactMap(list, fn) {
   var result = [];
   for (var item of list) {
-    var _value2 = fn(item);
-    if (_value2 !== null) {
-      result.push(_value2);
+    var _value3 = fn(item);
+    if (_value3 !== null) {
+      result.push(_value3);
     }
   }
   return result;
@@ -186,6 +190,60 @@ function generateUniqueKey() {
   return Math.trunc(Date.now() * Math.random()).toString(36);
 }
 
+/**
+ * Creates a type-only marker for TypeScript inference.
+ *
+ * This function always returns `true` at runtime. It exists
+ * purely to capture the generic type parameter for compile-time type checking.
+ * No runtime validation is performed.
+ *
+ * Common uses:
+ * - `isError`: Specify the error shape for type inference
+ * - `when`: Narrow field metadata to specific shapes for conditional props
+ *
+ * @example Specify error shape
+ * ```ts
+ * configureForms({
+ *   isError: shape<string>(),  // errors are strings
+ * });
+ * ```
+ *
+ * @example Conditional field metadata
+ * ```ts
+ * extendFieldMetadata(metadata, { when }) {
+ *   return {
+ *     get dateRangePickerProps() {
+ *       return when(metadata, shape<{ start: string; end: string }>(), (m) => ({
+ *         startName: m.getFieldset().start.name,
+ *         endName: m.getFieldset().end.name,
+ *       }));
+ *     },
+ *   };
+ * }
+ * ```
+ */
+function shape() {
+  return _value => true;
+}
+
+/**
+ * Creates a conditional field metadata property that is only available
+ * when the field shape matches the specified type.
+ */
+function when(metadata, _shape, fn) {
+  return fn(metadata);
+}
+function isStandardSchemaV1(schema) {
+  return typeof schema === 'object' && schema !== null && '~standard' in schema && typeof schema['~standard'] === 'object' && schema['~standard'] !== null && 'version' in schema['~standard'] && schema['~standard'].version === 1;
+}
+function validateStandardSchemaV1(schema, payload) {
+  var result = schema['~standard'].validate(payload);
+  if (result instanceof Promise) {
+    return result.then(actualResult => resolveStandardSchemaResult(actualResult));
+  }
+  return resolveStandardSchemaResult(result);
+}
+
 exports.appendUniqueItem = appendUniqueItem;
 exports.compactMap = compactMap;
 exports.createPathIndexUpdater = createPathIndexUpdater;
@@ -194,6 +252,7 @@ exports.getArrayAtPath = getArrayAtPath;
 exports.isNullable = isNullable;
 exports.isNumber = isNumber;
 exports.isOptional = isOptional;
+exports.isStandardSchemaV1 = isStandardSchemaV1;
 exports.isString = isString;
 exports.isUndefined = isUndefined;
 exports.merge = merge;
@@ -201,5 +260,8 @@ exports.normalizeFormError = normalizeFormError;
 exports.normalizeValidateResult = normalizeValidateResult;
 exports.resolveStandardSchemaResult = resolveStandardSchemaResult;
 exports.resolveValidateResult = resolveValidateResult;
+exports.shape = shape;
 exports.transformKeys = transformKeys;
 exports.updateValueAtPath = updateValueAtPath;
+exports.validateStandardSchemaV1 = validateStandardSchemaV1;
+exports.when = when;

package/dist/future/util.mjs

@@ -114,6 +114,10 @@ function resolveValidateResult(result) {
     asyncResult: asyncResult ? asyncResult.then(normalizeValidateResult) : undefined
   };
 }
+
+/**
+ * Resolves a StandardSchema validation result to conform's format.
+ */
 function resolveStandardSchemaResult(result) {
   if (!result.issues) {
     return {
@@ -145,10 +149,10 @@ function merge(obj, update) {
  */
 function transformKeys(obj, fn) {
   var result = {};
-  for (var [_key, _value] of Object.entries(obj)) {
+  for (var [_key, _value2] of Object.entries(obj)) {
     var _name = fn(_key);
     if (_name !== null) {
-      result[_name] = _value;
+      result[_name] = _value2;
     }
   }
   return result;
@@ -171,9 +175,9 @@ function appendUniqueItem(list, item) {
 function compactMap(list, fn) {
   var result = [];
   for (var item of list) {
-    var _value2 = fn(item);
-    if (_value2 !== null) {
-      result.push(_value2);
+    var _value3 = fn(item);
+    if (_value3 !== null) {
+      result.push(_value3);
     }
   }
   return result;
@@ -182,4 +186,58 @@ function generateUniqueKey() {
   return Math.trunc(Date.now() * Math.random()).toString(36);
 }
 
-export { appendUniqueItem, compactMap, createPathIndexUpdater, generateUniqueKey, getArrayAtPath, isNullable, isNumber, isOptional, isString, isUndefined, merge, normalizeFormError, normalizeValidateResult, resolveStandardSchemaResult, resolveValidateResult, transformKeys, updateValueAtPath };
+/**
+ * Creates a type-only marker for TypeScript inference.
+ *
+ * This function always returns `true` at runtime. It exists
+ * purely to capture the generic type parameter for compile-time type checking.
+ * No runtime validation is performed.
+ *
+ * Common uses:
+ * - `isError`: Specify the error shape for type inference
+ * - `when`: Narrow field metadata to specific shapes for conditional props
+ *
+ * @example Specify error shape
+ * ```ts
+ * configureForms({
+ *   isError: shape<string>(),  // errors are strings
+ * });
+ * ```
+ *
+ * @example Conditional field metadata
+ * ```ts
+ * extendFieldMetadata(metadata, { when }) {
+ *   return {
+ *     get dateRangePickerProps() {
+ *       return when(metadata, shape<{ start: string; end: string }>(), (m) => ({
+ *         startName: m.getFieldset().start.name,
+ *         endName: m.getFieldset().end.name,
+ *       }));
+ *     },
+ *   };
+ * }
+ * ```
+ */
+function shape() {
+  return _value => true;
+}
+
+/**
+ * Creates a conditional field metadata property that is only available
+ * when the field shape matches the specified type.
+ */
+function when(metadata, _shape, fn) {
+  return fn(metadata);
+}
+function isStandardSchemaV1(schema) {
+  return typeof schema === 'object' && schema !== null && '~standard' in schema && typeof schema['~standard'] === 'object' && schema['~standard'] !== null && 'version' in schema['~standard'] && schema['~standard'].version === 1;
+}
+function validateStandardSchemaV1(schema, payload) {
+  var result = schema['~standard'].validate(payload);
+  if (result instanceof Promise) {
+    return result.then(actualResult => resolveStandardSchemaResult(actualResult));
+  }
+  return resolveStandardSchemaResult(result);
+}
+
+export { appendUniqueItem, compactMap, createPathIndexUpdater, generateUniqueKey, getArrayAtPath, isNullable, isNumber, isOptional, isStandardSchemaV1, isString, isUndefined, merge, normalizeFormError, normalizeValidateResult, resolveStandardSchemaResult, resolveValidateResult, shape, transformKeys, updateValueAtPath, validateStandardSchemaV1, when };