@conform-to/react 1.18.0 → 1.19.0

package/dist/future/forms.js

@@ -14,14 +14,18 @@ var util = require('./util.js');
 var jsxRuntime = require('react/jsx-runtime');
 
 function configureForms() {
-  var _config$intentName, _config$serialize, _config$shouldValidat, _ref, _config$shouldRevalid, _config$isSchema, _config$validateSchem;
+  var _config$intentName, _config$shouldValidat, _ref, _config$shouldRevalid, _config$isSchema, _config$validateSchem;
   var config = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  /**
+   * Global serializer that composes the user-provided serializer with the default serializer.
+   */
+  var globalSerialize = util.resolveSerialize(config.serialize, future.defaultSerialize);
+
   /**
    * Global configuration with defaults applied
    */
   var globalConfig = _rollupPluginBabelHelpers.objectSpread2(_rollupPluginBabelHelpers.objectSpread2({}, config), {}, {
     intentName: (_config$intentName = config.intentName) !== null && _config$intentName !== void 0 ? _config$intentName : future.DEFAULT_INTENT_NAME,
-    serialize: (_config$serialize = config.serialize) !== null && _config$serialize !== void 0 ? _config$serialize : future.serialize,
     shouldValidate: (_config$shouldValidat = config.shouldValidate) !== null && _config$shouldValidat !== void 0 ? _config$shouldValidat : 'onSubmit',
     shouldRevalidate: (_ref = (_config$shouldRevalid = config.shouldRevalidate) !== null && _config$shouldRevalid !== void 0 ? _config$shouldRevalid : config.shouldValidate) !== null && _ref !== void 0 ? _ref : 'onSubmit',
     isSchema: (_config$isSchema = config.isSchema) !== null && _config$isSchema !== void 0 ? _config$isSchema : util.isStandardSchemaV1,
@@ -64,8 +68,9 @@ function configureForms() {
    * - **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:
+   * See https://conform.guide/api/react/future/useForm
+   *
+   * **Schema first setup with zod:**
    *
    * ```tsx
    * const { form, fields } = useForm(zodSchema, {
@@ -81,13 +86,13 @@ function configureForms() {
    * );
    * ```
    *
-   * @example Manual configuration setup with custom validation:
+   * **Manual configuration setup with custom validation:**
    *
    * ```tsx
    * const { form, fields } = useForm({
-   *    onValidate({ payload, error }) {
+   *   onValidate({ payload, error }) {
    *     if (!payload.email) {
-   * 		 error.fieldErrors.email = ['Required'];
+   *       error.fieldErrors.email = ['Required'];
    *     }
    *     return error;
    *   }
@@ -102,10 +107,6 @@ function configureForms() {
    * ```
    */
 
-  /**
-   * @deprecated Use `useForm(schema, options)` instead for better type inference.
-   */
-
   function useForm(schemaOrOptions, maybeOptions) {
     var _options$constraint, _globalConfig$getCons, _options$id, _options$onError;
     var schema;
@@ -118,10 +119,11 @@ function configureForms() {
     }
     var constraint = (_options$constraint = options.constraint) !== null && _options$constraint !== void 0 ? _options$constraint : schema ? (_globalConfig$getCons = globalConfig.getConstraints) === null || _globalConfig$getCons === void 0 ? void 0 : _globalConfig$getCons.call(globalConfig, schema) : undefined;
     var optionsRef = hooks.useLatest(options);
+    var serialize = react.useMemo(() => util.resolveSerialize(options.serialize, globalSerialize), [options.serialize]);
     var fallbackId = react.useId();
     var formId = (_options$id = options.id) !== null && _options$id !== void 0 ? _options$id : "form-".concat(fallbackId);
     var [state$1, handleSubmit] = hooks.useConform(formId, _rollupPluginBabelHelpers.objectSpread2(_rollupPluginBabelHelpers.objectSpread2({}, options), {}, {
-      serialize: globalConfig.serialize,
+      serialize,
       intentName: globalConfig.intentName,
       onError: (_options$onError = options.onError) !== null && _options$onError !== void 0 ? _options$onError : dom.focusFirstInvalidField,
       onValidate(ctx) {
@@ -172,6 +174,7 @@ function configureForms() {
     var context = react.useMemo(() => ({
       formId,
       state: state$1,
+      serialize,
       constraint: constraint !== null && constraint !== void 0 ? constraint : null,
       handleSubmit,
       handleInput(event) {
@@ -210,14 +213,12 @@ function configureForms() {
           intent.validate(event.target.name);
         }
       }
-    }), [formId, state$1, constraint, handleSubmit, intent, optionsRef]);
+    }), [formId, state$1, serialize, constraint, handleSubmit, intent, optionsRef]);
     var form = react.useMemo(() => state.getFormMetadata(context, {
-      serialize: globalConfig.serialize,
       extendFormMetadata: globalConfig.extendFormMetadata,
       extendFieldMetadata: globalConfig.extendFieldMetadata
     }), [context]);
     var fields = react.useMemo(() => state.getFieldset(context, {
-      serialize: globalConfig.serialize,
       extendFieldMetadata: globalConfig.extendFieldMetadata
     }), [context]);
     return {
@@ -231,8 +232,9 @@ function configureForms() {
    * 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
+   * See https://conform.guide/api/react/future/useFormMetadata
+   *
+   * **Example:**
    * ```tsx
    * function ErrorSummary() {
    *   const form = useFormMetadata();
@@ -249,7 +251,6 @@ function configureForms() {
     var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
     var context = useFormContext(options.formId);
     var formMetadata = react.useMemo(() => state.getFormMetadata(context, {
-      serialize: globalConfig.serialize,
       extendFormMetadata: globalConfig.extendFormMetadata,
       extendFieldMetadata: globalConfig.extendFieldMetadata
     }), [context]);
@@ -260,8 +261,9 @@ function configureForms() {
    * 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
+   * See https://conform.guide/api/react/future/useField
+   *
+   * **Example:**
    * ```tsx
    * function FormField({ name, label }) {
    *   const field = useField(name);
@@ -281,7 +283,6 @@ function configureForms() {
     var context = useFormContext(options.formId);
     var field = react.useMemo(() => state.getField(context, {
       name,
-      serialize: globalConfig.serialize,
       extendFieldMetadata: globalConfig.extendFieldMetadata
     }), [context, name]);
     return field;
@@ -292,8 +293,9 @@ function configureForms() {
    * 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
+   * See https://conform.guide/api/react/future/useIntent
+   *
+   * **Example:**
    * ```tsx
    * function ResetButton() {
    *   const buttonRef = useRef<HTMLButtonElement>(null);
@@ -319,5 +321,132 @@ function configureForms() {
     config: globalConfig
   };
 }
+var defaultForms = configureForms();
+
+/**
+ * Provides form context to child components.
+ * Stacks contexts to support nested forms, with latest context taking priority.
+ */
+var FormProvider = defaultForms.FormProvider;
+
+/**
+ * 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
+ *
+ * **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>
+ * );
+ * ```
+ *
+ * **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>
+ * );
+ * ```
+ */
+var useForm = defaultForms.useForm;
+
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+var useFormMetadata = defaultForms.useFormMetadata;
+
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+var useField = defaultForms.useField;
+
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+var useIntent = defaultForms.useIntent;
 
+exports.FormProvider = FormProvider;
 exports.configureForms = configureForms;
+exports.useField = useField;
+exports.useForm = useForm;
+exports.useFormMetadata = useFormMetadata;
+exports.useIntent = useIntent;

package/dist/future/forms.mjs

@@ -1,23 +1,27 @@
 'use client';
 import { objectSpread2 as _objectSpread2 } from '../_virtual/_rollupPluginBabelHelpers.mjs';
 import { isFieldElement } from '@conform-to/dom';
-import { DEFAULT_INTENT_NAME, serialize } from '@conform-to/dom/future';
+import { DEFAULT_INTENT_NAME, defaultSerialize } from '@conform-to/dom/future';
 import { useContext, useMemo, useId, createContext } from 'react';
 import { focusFirstInvalidField, getFormElement, createIntentDispatcher } from './dom.mjs';
 import { useLatest, useConform } from './hooks.mjs';
 import { isTouched, getFormMetadata, getFieldset, getField } from './state.mjs';
-import { isStandardSchemaV1, validateStandardSchemaV1, resolveValidateResult } from './util.mjs';
+import { resolveSerialize, isStandardSchemaV1, validateStandardSchemaV1, resolveValidateResult } from './util.mjs';
 import { jsx } from 'react/jsx-runtime';
 
 function configureForms() {
-  var _config$intentName, _config$serialize, _config$shouldValidat, _ref, _config$shouldRevalid, _config$isSchema, _config$validateSchem;
+  var _config$intentName, _config$shouldValidat, _ref, _config$shouldRevalid, _config$isSchema, _config$validateSchem;
   var config = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  /**
+   * Global serializer that composes the user-provided serializer with the default serializer.
+   */
+  var globalSerialize = resolveSerialize(config.serialize, defaultSerialize);
+
   /**
    * Global configuration with defaults applied
    */
   var globalConfig = _objectSpread2(_objectSpread2({}, config), {}, {
     intentName: (_config$intentName = config.intentName) !== null && _config$intentName !== void 0 ? _config$intentName : DEFAULT_INTENT_NAME,
-    serialize: (_config$serialize = config.serialize) !== null && _config$serialize !== void 0 ? _config$serialize : serialize,
     shouldValidate: (_config$shouldValidat = config.shouldValidate) !== null && _config$shouldValidat !== void 0 ? _config$shouldValidat : 'onSubmit',
     shouldRevalidate: (_ref = (_config$shouldRevalid = config.shouldRevalidate) !== null && _config$shouldRevalid !== void 0 ? _config$shouldRevalid : config.shouldValidate) !== null && _ref !== void 0 ? _ref : 'onSubmit',
     isSchema: (_config$isSchema = config.isSchema) !== null && _config$isSchema !== void 0 ? _config$isSchema : isStandardSchemaV1,
@@ -60,8 +64,9 @@ function configureForms() {
    * - **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:
+   * See https://conform.guide/api/react/future/useForm
+   *
+   * **Schema first setup with zod:**
    *
    * ```tsx
    * const { form, fields } = useForm(zodSchema, {
@@ -77,13 +82,13 @@ function configureForms() {
    * );
    * ```
    *
-   * @example Manual configuration setup with custom validation:
+   * **Manual configuration setup with custom validation:**
    *
    * ```tsx
    * const { form, fields } = useForm({
-   *    onValidate({ payload, error }) {
+   *   onValidate({ payload, error }) {
    *     if (!payload.email) {
-   * 		 error.fieldErrors.email = ['Required'];
+   *       error.fieldErrors.email = ['Required'];
    *     }
    *     return error;
    *   }
@@ -98,10 +103,6 @@ function configureForms() {
    * ```
    */
 
-  /**
-   * @deprecated Use `useForm(schema, options)` instead for better type inference.
-   */
-
   function useForm(schemaOrOptions, maybeOptions) {
     var _options$constraint, _globalConfig$getCons, _options$id, _options$onError;
     var schema;
@@ -114,10 +115,11 @@ function configureForms() {
     }
     var constraint = (_options$constraint = options.constraint) !== null && _options$constraint !== void 0 ? _options$constraint : schema ? (_globalConfig$getCons = globalConfig.getConstraints) === null || _globalConfig$getCons === void 0 ? void 0 : _globalConfig$getCons.call(globalConfig, schema) : undefined;
     var optionsRef = useLatest(options);
+    var serialize = useMemo(() => resolveSerialize(options.serialize, globalSerialize), [options.serialize]);
     var fallbackId = useId();
     var formId = (_options$id = options.id) !== null && _options$id !== void 0 ? _options$id : "form-".concat(fallbackId);
     var [state, handleSubmit] = useConform(formId, _objectSpread2(_objectSpread2({}, options), {}, {
-      serialize: globalConfig.serialize,
+      serialize,
       intentName: globalConfig.intentName,
       onError: (_options$onError = options.onError) !== null && _options$onError !== void 0 ? _options$onError : focusFirstInvalidField,
       onValidate(ctx) {
@@ -168,6 +170,7 @@ function configureForms() {
     var context = useMemo(() => ({
       formId,
       state,
+      serialize,
       constraint: constraint !== null && constraint !== void 0 ? constraint : null,
       handleSubmit,
       handleInput(event) {
@@ -206,14 +209,12 @@ function configureForms() {
           intent.validate(event.target.name);
         }
       }
-    }), [formId, state, constraint, handleSubmit, intent, optionsRef]);
+    }), [formId, state, serialize, constraint, handleSubmit, intent, optionsRef]);
     var form = useMemo(() => getFormMetadata(context, {
-      serialize: globalConfig.serialize,
       extendFormMetadata: globalConfig.extendFormMetadata,
       extendFieldMetadata: globalConfig.extendFieldMetadata
     }), [context]);
     var fields = useMemo(() => getFieldset(context, {
-      serialize: globalConfig.serialize,
       extendFieldMetadata: globalConfig.extendFieldMetadata
     }), [context]);
     return {
@@ -227,8 +228,9 @@ function configureForms() {
    * 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
+   * See https://conform.guide/api/react/future/useFormMetadata
+   *
+   * **Example:**
    * ```tsx
    * function ErrorSummary() {
    *   const form = useFormMetadata();
@@ -245,7 +247,6 @@ function configureForms() {
     var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
     var context = useFormContext(options.formId);
     var formMetadata = useMemo(() => getFormMetadata(context, {
-      serialize: globalConfig.serialize,
       extendFormMetadata: globalConfig.extendFormMetadata,
       extendFieldMetadata: globalConfig.extendFieldMetadata
     }), [context]);
@@ -256,8 +257,9 @@ function configureForms() {
    * 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
+   * See https://conform.guide/api/react/future/useField
+   *
+   * **Example:**
    * ```tsx
    * function FormField({ name, label }) {
    *   const field = useField(name);
@@ -277,7 +279,6 @@ function configureForms() {
     var context = useFormContext(options.formId);
     var field = useMemo(() => getField(context, {
       name,
-      serialize: globalConfig.serialize,
       extendFieldMetadata: globalConfig.extendFieldMetadata
     }), [context, name]);
     return field;
@@ -288,8 +289,9 @@ function configureForms() {
    * 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
+   * See https://conform.guide/api/react/future/useIntent
+   *
+   * **Example:**
    * ```tsx
    * function ResetButton() {
    *   const buttonRef = useRef<HTMLButtonElement>(null);
@@ -315,5 +317,127 @@ function configureForms() {
     config: globalConfig
   };
 }
+var defaultForms = configureForms();
+
+/**
+ * Provides form context to child components.
+ * Stacks contexts to support nested forms, with latest context taking priority.
+ */
+var FormProvider = defaultForms.FormProvider;
+
+/**
+ * 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
+ *
+ * **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>
+ * );
+ * ```
+ *
+ * **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>
+ * );
+ * ```
+ */
+var useForm = defaultForms.useForm;
+
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+var useFormMetadata = defaultForms.useFormMetadata;
+
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+var useField = defaultForms.useField;
+
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+var useIntent = defaultForms.useIntent;
 
-export { configureForms };
+export { FormProvider, configureForms, useField, useForm, useFormMetadata, useIntent };