@conform-to/react 1.17.1 → 1.19.0

package/dist/future/hooks.d.ts

@@ -1,25 +1,28 @@
-import { type FieldName, type FormValue, type Serialize, type SubmissionResult, createGlobalFormsObserver } from '@conform-to/dom/future';
+import { type FormValue, type Serialize, type SubmissionResult } from '@conform-to/dom/future';
 import { useEffect } from 'react';
-import type { FormContext, IntentDispatcher, FormMetadata, Fieldset, GlobalFormOptions, FormOptions, FieldMetadata, Control, Selector, UseFormDataOptions, ValidateHandler, ErrorHandler, SubmitHandler, FormState, FormRef, BaseErrorShape, DefaultErrorShape, BaseSchemaType, InferInput, InferOutput } from './types';
-import { StandardSchemaV1 } from './standard-schema';
+import type { FormContext, Control, Selector, UseFormDataOptions, ValidateHandler, ErrorHandler, SubmitHandler, FormState, FormRef, BaseControlProps, StandardControlOptions, DefaultControlValue, CheckedControlOptions, CustomControlOptions } from './types';
 export declare const INITIAL_KEY = "INITIAL_KEY";
-export declare const GlobalFormOptionsContext: import("react").Context<GlobalFormOptions & {
-    observer: ReturnType<typeof createGlobalFormsObserver>;
+export declare const GlobalFormsObserverContext: import("react").Context<{
+    onFieldUpdate(callback: (event: {
+        type: "input" | "reset" | "mutation";
+        target: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
+    }) => void): () => void;
+    onFormUpdate(callback: (event: {
+        type: "submit" | "input" | "reset" | "mutation";
+        target: HTMLFormElement;
+        submitter?: HTMLInputElement | HTMLButtonElement | null;
+    }) => void): () => void;
+    onInternalUpdate(callback: (event: {
+        target: HTMLFormElement;
+    }) => void): () => void;
+    dispose(): void;
 }>;
-export declare const FormContextContext: import("react").Context<FormContext<string>[]>;
-/**
- * Provides form context to child components.
- * Stacks contexts to support nested forms, with latest context taking priority.
- */
-export declare function FormProvider(props: {
-    context: FormContext;
-    children: React.ReactNode;
-}): React.ReactElement;
+export declare const FormContextContext: import("react").Context<FormContext<any>[]>;
 /**
  * Preserves form field values when its contents are unmounted.
  * Useful for multi-step forms and virtualized lists.
  *
- * @see https://conform.guide/api/react/future/PreserveBoundary
+ * See https://conform.guide/api/react/future/PreserveBoundary
  */
 export declare function PreserveBoundary(props: {
     /**
@@ -34,196 +37,34 @@ export declare function PreserveBoundary(props: {
     form?: string;
     children: React.ReactNode;
 }): React.ReactElement;
-/**
- * @deprecated Replaced by the `configureForms` factory API. This will be removed in the next minor version. If you are not ready to migrate, please pin to `v1.16.0`.
- */
-export declare function FormOptionsProvider(props: Partial<GlobalFormOptions> & {
-    children: React.ReactNode;
-}): React.ReactElement;
 export declare function useFormContext(formId?: string): FormContext;
 /**
  * Core form hook that manages form state, validation, and submission.
  * Handles both sync and async validation, intent dispatching, and DOM updates.
  */
-export declare function useConform<FormShape extends Record<string, any>, ErrorShape, Value = undefined, SchemaValue = undefined>(formRef: FormRef, options: {
+export declare function useConform<FormShape extends Record<string, any>, ErrorShape, Value = undefined, SchemaValue = undefined, SchemaErrorShape = unknown>(formRef: FormRef, options: {
     key?: string | undefined;
     defaultValue?: Record<string, FormValue> | null | undefined;
     serialize: Serialize;
     intentName: string;
     lastResult?: SubmissionResult<NoInfer<ErrorShape>> | null | undefined;
-    onValidate?: ValidateHandler<ErrorShape, Value, SchemaValue> | undefined;
+    onValidate?: ValidateHandler<ErrorShape, Value, SchemaValue, SchemaErrorShape> | undefined;
     onError?: ErrorHandler<ErrorShape> | undefined;
     onSubmit?: SubmitHandler<FormShape, NoInfer<ErrorShape>, NoInfer<Value>> | undefined;
 }): [FormState<ErrorShape>, (event: React.FormEvent<HTMLFormElement>) => void];
-/**
- * The main React hook for form management. Handles form state, validation, and submission
- * while providing access to form metadata, field objects, and form actions.
- *
- * It can be called in two ways:
- * - **Schema first**: Pass a schema as the first argument for automatic validation with type inference
- * - **Manual configuration**: Pass options with custom `onValidate` handler for manual validation
- *
- * @see https://conform.guide/api/react/future/useForm
- * @example Schema first setup with zod:
- *
- * ```tsx
- * const { form, fields } = useForm(zodSchema, {
- *   lastResult,
- *   shouldValidate: 'onBlur',
- * });
- *
- * return (
- *   <form {...form.props}>
- *     <input name={fields.email.name} defaultValue={fields.email.defaultValue} />
- *     <div>{fields.email.errors}</div>
- *   </form>
- * );
- * ```
- *
- * @example Manual configuration setup with custom validation:
- *
- * ```tsx
- * const { form, fields } = useForm({
- *    onValidate({ payload, error }) {
- *     if (!payload.email) {
- * 		 error.fieldErrors.email = ['Required'];
- *     }
- *     return error;
- *   }
- * });
- *
- * return (
- *   <form {...form.props}>
- *     <input name={fields.email.name} defaultValue={fields.email.defaultValue} />
- *     <div>{fields.email.errors}</div>
- *   </form>
- * );
- * ```
- */
-export declare function useForm<Schema extends BaseSchemaType, ErrorShape extends BaseErrorShape = DefaultErrorShape, Value = InferOutput<Schema>>(schema: Schema, options: FormOptions<InferInput<Schema>, ErrorShape, Value, Schema, string extends ErrorShape ? never : 'onValidate'>): {
-    form: FormMetadata<ErrorShape>;
-    fields: Fieldset<InferInput<Schema>, ErrorShape>;
-    intent: IntentDispatcher<InferInput<Schema>>;
-};
-/**
- * @deprecated Use `useForm(schema, options)` instead for better type inference.
- */
-export declare function useForm<FormShape extends Record<string, any> = Record<string, any>, ErrorShape extends BaseErrorShape = DefaultErrorShape, Value = undefined>(options: FormOptions<FormShape, ErrorShape, Value, undefined, undefined extends Value ? 'onValidate' : never> & {
-    /**
-     * @deprecated Use `useForm(schema, options)` instead for better type inference.
-     *
-     * Optional standard schema for validation (e.g., Zod, Valibot, Yup).
-     * Removes the need for manual onValidate setup.
-     *
-     */
-    schema: StandardSchemaV1<FormShape, Value>;
-}): {
-    form: FormMetadata<ErrorShape>;
-    fields: Fieldset<FormShape, ErrorShape>;
-    intent: IntentDispatcher<FormShape>;
-};
-export declare function useForm<FormShape extends Record<string, any> = Record<string, any>, ErrorShape extends BaseErrorShape = DefaultErrorShape, Value = undefined>(options: FormOptions<FormShape, ErrorShape, Value, undefined, 'onValidate'>): {
-    form: FormMetadata<ErrorShape>;
-    fields: Fieldset<FormShape, ErrorShape>;
-    intent: IntentDispatcher<FormShape>;
-};
-/**
- * A React hook that provides access to form-level metadata and state.
- * Requires `FormProvider` context when used in child components.
- *
- * @see https://conform.guide/api/react/future/useFormMetadata
- * @example
- * ```tsx
- * function ErrorSummary() {
- *   const form = useFormMetadata();
- *
- *   if (form.valid) return null;
- *
- *   return (
- *     <div>Please fix {Object.keys(form.fieldErrors).length} errors</div>
- *   );
- * }
- * ```
- */
-export declare function useFormMetadata(options?: {
-    formId?: string;
-}): FormMetadata;
-/**
- * A React hook that provides access to a specific field's metadata and state.
- * Requires `FormProvider` context when used in child components.
- *
- * @see https://conform.guide/api/react/future/useField
- * @example
- * ```tsx
- * function FormField({ name, label }) {
- *   const field = useField(name);
- *
- *   return (
- *     <div>
- *       <label htmlFor={field.id}>{label}</label>
- *       <input id={field.id} name={field.name} defaultValue={field.defaultValue} />
- *       {field.errors && <div>{field.errors.join(', ')}</div>}
- *     </div>
- *   );
- * }
- * ```
- */
-export declare function useField<FieldShape = any>(name: FieldName<FieldShape>, options?: {
-    formId?: string;
-}): FieldMetadata<FieldShape>;
-/**
- * A React hook that provides an intent dispatcher for programmatic form actions.
- * Intent dispatchers allow you to trigger form operations like validation, field updates,
- * and array manipulations without manual form submission.
- *
- * @see https://conform.guide/api/react/future/useIntent
- * @example
- * ```tsx
- * function ResetButton() {
- *   const buttonRef = useRef<HTMLButtonElement>(null);
- *   const intent = useIntent(buttonRef);
- *
- *   return (
- *     <button type="button" ref={buttonRef} onClick={() => intent.reset()}>
- *       Reset Form
- *     </button>
- *   );
- * }
- * ```
- */
-export declare function useIntent<FormShape extends Record<string, any>>(formRef: FormRef): IntentDispatcher<FormShape>;
 /**
  * A React hook that lets you sync the state of an input and dispatch native form events from it.
- * This is useful when emulating native input behavior — typically by rendering a hidden base input
+ * This is useful when emulating native input behavior — typically by rendering a hidden base control
  * and syncing it with a custom input.
  *
- * @example
+ * **Example:**
  * ```ts
  * const control = useControl(options);
  * ```
  */
-export declare function useControl(options?: {
-    /**
-     * The initial value of the base input. It will be used to set the value
-     * when the input is first registered.
-     */
-    defaultValue?: string | string[] | File | File[] | null | undefined;
-    /**
-     * Whether the base input should be checked by default. It will be applied
-     * when the input is first registered.
-     */
-    defaultChecked?: boolean | undefined;
-    /**
-     * The value of a checkbox or radio input when checked. This sets the
-     * value attribute of the base input.
-     */
-    value?: string;
-    /**
-     * A callback function that is triggered when the base input is focused.
-     * Use this to delegate focus to a custom input.
-     */
-    onFocus?: () => void;
-}): Control;
+export declare function useControl<Value, DefaultValue>(options: CustomControlOptions<Value, DefaultValue>): Control<Value, DefaultValue, Value>;
+export declare function useControl<Value extends DefaultControlValue>(options?: StandardControlOptions<Value>): Control<Value>;
+export declare function useControl(options: CheckedControlOptions): Control<boolean, string>;
 /**
  * A React hook that lets you subscribe to the current `FormData` of a form and derive a custom value from it.
  * The selector runs whenever the form's structure or data changes, and the hook re-renders only when the result is deeply different.
@@ -231,8 +72,9 @@ export declare function useControl(options?: {
  * Returns `undefined` when the form element is not available (e.g., on SSR or initial client render),
  * unless a `fallback` is provided.
  *
- * @see https://conform.guide/api/react/future/useFormData
- * @example
+ * See https://conform.guide/api/react/future/useFormData
+ *
+ * **Example:**
  * ```ts
  * const value = useFormData(
  *   formRef,
@@ -268,4 +110,37 @@ export declare const useSafeLayoutEffect: typeof useEffect;
  * Useful to avoid stale closures in event handlers or async callbacks.
  */
 export declare function useLatest<Value>(value: Value): import("react").MutableRefObject<Value>;
+/**
+ * A component that renders hidden base control(s) based on the shape of defaultValue.
+ * Used with useControl to sync complex values with form data.
+ *
+ * **Example:**
+ * ```tsx
+ * const control = useControl<{ street: string; city: string }>({
+ *   defaultValue: { street: '123 Main St', city: 'Anytown' },
+ *   parse(payload) {
+ * 	   if (
+ *       typeof payload === 'object' &&
+ *       payload !== null &&
+ *       'street' in payload &&
+ *       'city' in payload &&
+ *       typeof payload.street === 'string' &&
+ *       typeof payload.city === 'string'
+ *     ) {
+ *       return payload;
+ *     }
+ *
+ *     throw new Error('Unexpected payload shape');
+ *   },
+ * });
+ *
+ * <BaseControl
+ *   type="fieldset"
+ *   name="address"
+ *   ref={control.register}
+ *   defaultValue={control.defaultValue}
+ * />
+ * ```
+ */
+export declare const BaseControl: import("react").ForwardRefExoticComponent<BaseControlProps & import("react").RefAttributes<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement | HTMLFieldSetElement>>;
 //# sourceMappingURL=hooks.d.ts.map