@conform-to/react 1.8.1 → 1.9.0

package/dist/future/hooks.d.ts

@@ -1,49 +1,139 @@
-import { type FormRef } from './util';
-export type Control = {
-    /**
-     * Current value of the base input. Undefined if the registered input
-     * is a multi-select, file input, or checkbox group.
-     */
-    value: string | undefined;
-    /**
-     * Selected options of the base input. Defined only when the registered input
-     * is a multi-select or checkbox group.
-     */
-    checked: boolean | undefined;
-    /**
-     * Checked state of the base input. Defined only when the registered input
-     * is a single checkbox or radio input.
-     */
-    options: string[] | undefined;
-    /**
-     * Selected files of the base input. Defined only when the registered input
-     * is a file input.
-     */
-    files: File[] | undefined;
-    /**
-     * Registers the base input element(s). Accepts a single input or an array for groups.
-     */
-    register: (element: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement | HTMLCollectionOf<HTMLInputElement> | NodeListOf<HTMLInputElement> | null | undefined) => void;
-    /**
-     * Programmatically updates the input value and emits
-     * both [change](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event) and
-     * [input](https://developer.mozilla.org/en-US/docs/Web/API/Element/input_event) events.
-     */
-    change(value: string | string[] | boolean | File | File[] | FileList | null): void;
-    /**
-     * Emits [blur](https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event) and
-     * [focusout](https://developer.mozilla.org/en-US/docs/Web/API/Element/focusout_event) events.
-     * Does not actually move focus.
-     */
-    focus(): void;
-    /**
-     * 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;
+import { type Serialize, type SubmissionResult, serialize } from '@conform-to/dom/future';
+import { useEffect } from 'react';
+import type { FormContext, DefaultFieldMetadata, IntentDispatcher, FormMetadata, Fieldset, FormOptions, FieldName, Field, Control, Selector, UseFormDataOptions, ValidateHandler, ErrorHandler, SubmitHandler, FormState, FormRef } from './types';
+export declare const FormConfig: import("react").Context<{
+    intentName: string;
+    observer: {
+        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;
+        dispose(): void;
+    };
+    serialize: typeof serialize;
+}>;
+export declare const Form: 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 function useFormContext(formId?: string): FormContext<any>;
+/**
+ * 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<ErrorShape, Value = undefined>(formRef: FormRef, options: {
+    key?: string;
+    serialize: Serialize;
+    intentName: string;
+    lastResult?: SubmissionResult<NoInfer<ErrorShape>> | null;
+    onValidate?: ValidateHandler<ErrorShape, Value>;
+    onError?: ErrorHandler<ErrorShape>;
+    onSubmit?: SubmitHandler<NoInfer<ErrorShape>, NoInfer<Value>>;
+}): [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.
+ *
+ * @see https://conform.guide/api/react/future/useForm
+ * @example
+ * ```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<FormShape extends Record<string, any> = Record<string, any>, ErrorShape = string, Value = undefined>(options: FormOptions<FormShape, ErrorShape, Value>): {
+    form: FormMetadata<ErrorShape>;
+    fields: Fieldset<FormShape, DefaultFieldMetadata<ErrorShape>>;
+    intent: IntentDispatcher;
 };
+/**
+ * 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.invalid) return null;
+ *
+ *   return (
+ *     <div>Please fix {Object.keys(form.fieldErrors).length} errors</div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useFormMetadata<ErrorShape = string[]>(options?: {
+    formId?: string;
+}): FormMetadata<ErrorShape>;
+/**
+ * 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;
+}): Field<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(formRef: FormRef): IntentDispatcher;
 /**
  * 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
@@ -76,14 +166,6 @@ export declare function useControl(options?: {
      */
     onFocus?: () => void;
 }): Control;
-type Selector<FormValue, Result> = (formData: FormValue | null, lastResult: Result | undefined) => Result;
-type UseFormDataOptions = {
-    /**
-     * 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;
-};
 /**
  * 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.
@@ -100,5 +182,14 @@ export declare function useFormData<Value = any>(formRef: FormRef, select: Selec
 export declare function useFormData<Value = any>(formRef: FormRef, select: Selector<URLSearchParams, Value>, options?: UseFormDataOptions & {
     acceptFiles?: boolean;
 }): Value;
-export {};
+/**
+ * useLayoutEffect is client-only.
+ * This basically makes it a no-op on server
+ */
+export declare const useSafeLayoutEffect: typeof useEffect;
+/**
+ * Keep a mutable ref in sync with the latest value.
+ * Useful to avoid stale closures in event handlers or async callbacks.
+ */
+export declare function useLatest<Value>(value: Value): import("react").MutableRefObject<Value>;
 //# sourceMappingURL=hooks.d.ts.map