@conform-to/react 1.15.1 → 1.16.0

package/README.md

@@ -7,7 +7,7 @@
  ╚══════╝  ╚═════╝  ╚═╝  ╚══╝ ╚═╝        ╚═════╝  ╚═╝   ╚═╝ ╚═╝   ╚═╝
 ```
 
-Version 1.15.1 / License MIT / Copyright (c) 2025 Edmund Hung
+Version 1.16.0 / License MIT / Copyright (c) 2025 Edmund Hung
 
 Progressively enhance HTML forms with React. Build resilient, type-safe forms with no hassle using web standards.
 

package/dist/future/forms.d.ts

@@ -0,0 +1,43 @@
+import { FieldName } from '@conform-to/dom';
+import { StandardSchemaV1 } from './standard-schema';
+import { FormRef, FormsConfig, FormContext, FormMetadata, FormOptions, Fieldset, FieldMetadata, InferOutput, InferInput, IntentDispatcher } from './types';
+export declare function configureForms<BaseErrorShape = string, BaseSchema = StandardSchemaV1, CustomFormMetadata extends Record<string, unknown> = {}, CustomFieldMetadata extends Record<string, unknown> = {}>(config?: Partial<FormsConfig<BaseErrorShape, BaseSchema, CustomFormMetadata, CustomFieldMetadata>>): {
+    FormProvider: (props: {
+        context: FormContext<BaseErrorShape>;
+        children: React.ReactNode;
+    }) => React.ReactElement;
+    useForm: {
+        <Schema extends BaseSchema, ErrorShape extends BaseErrorShape = BaseErrorShape, Value = InferOutput<Schema>>(schema: Schema, options: FormOptions<InferInput<Schema> extends Record<string, any> ? InferInput<Schema> : never, ErrorShape, Value, Schema, string extends ErrorShape ? never : "onValidate">): {
+            form: FormMetadata<ErrorShape, CustomFormMetadata, CustomFieldMetadata>;
+            fields: Fieldset<InferInput<Schema>, ErrorShape, CustomFieldMetadata>;
+            intent: IntentDispatcher<InferInput<Schema> extends Record<string, any> ? InferInput<Schema> : never>;
+        };
+        <FormShape extends Record<string, any> = Record<string, any>, ErrorShape extends BaseErrorShape = BaseErrorShape, 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, CustomFormMetadata, CustomFieldMetadata>;
+            fields: Fieldset<FormShape, ErrorShape, CustomFieldMetadata>;
+            intent: IntentDispatcher<FormShape>;
+        };
+        <FormShape extends Record<string, any> = Record<string, any>, ErrorShape extends BaseErrorShape = BaseErrorShape, Value = undefined>(options: FormOptions<FormShape, ErrorShape, Value, undefined, "onValidate">): {
+            form: FormMetadata<ErrorShape, CustomFormMetadata, CustomFieldMetadata>;
+            fields: Fieldset<FormShape, ErrorShape, CustomFieldMetadata>;
+            intent: IntentDispatcher<FormShape>;
+        };
+    };
+    useFormMetadata: (options?: {
+        formId?: string;
+    }) => FormMetadata<BaseErrorShape, CustomFormMetadata, CustomFieldMetadata>;
+    useField: <FieldShape = any>(name: FieldName<FieldShape>, options?: {
+        formId?: string;
+    }) => FieldMetadata<FieldShape, BaseErrorShape, CustomFieldMetadata>;
+    useIntent: <FormShape extends Record<string, any>>(formRef: FormRef) => IntentDispatcher<FormShape>;
+    config: FormsConfig<BaseErrorShape, BaseSchema, CustomFormMetadata, CustomFieldMetadata>;
+};
+//# sourceMappingURL=forms.d.ts.map

package/dist/future/forms.js

@@ -0,0 +1,322 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var _rollupPluginBabelHelpers = require('../_virtual/_rollupPluginBabelHelpers.js');
+var dom$1 = require('@conform-to/dom');
+var future = require('@conform-to/dom/future');
+var react = require('react');
+var dom = require('./dom.js');
+var hooks = require('./hooks.js');
+var state = require('./state.js');
+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 = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  /**
+   * 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,
+    validateSchema: (_config$validateSchem = config.validateSchema) !== null && _config$validateSchem !== void 0 ? _config$validateSchem : util.validateStandardSchemaV1
+  });
+
+  /**
+   * React context
+   */
+  var ReactFormContext = /*#__PURE__*/react.createContext([]);
+
+  /**
+   * Provides form context to child components.
+   * Stacks contexts to support nested forms, with latest context taking priority.
+   */
+  function FormProvider(props) {
+    var stack = react.useContext(ReactFormContext);
+    var value = react.useMemo(
+    // Put the latest form context first to ensure that to be the first one found
+    () => [props.context].concat(stack), [stack, props.context]);
+    return /*#__PURE__*/jsxRuntime.jsx(ReactFormContext.Provider, {
+      value: value,
+      children: props.children
+    });
+  }
+  function useFormContext(formId) {
+    var contexts = react.useContext(ReactFormContext);
+    var context = formId ? contexts.find(context => formId === context.formId) : contexts[0];
+    if (!context) {
+      throw new Error('No form context found. ' + 'Wrap your component with <FormProvider context={form.context}> ' + 'where `form` is returned from useForm().');
+    }
+    return context;
+  }
+
+  /**
+   * 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>
+   * );
+   * ```
+   */
+
+  /**
+   * @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;
+    var options;
+    if (globalConfig.isSchema(schemaOrOptions)) {
+      schema = schemaOrOptions;
+      options = maybeOptions !== null && maybeOptions !== void 0 ? maybeOptions : {};
+    } else {
+      options = schemaOrOptions;
+    }
+    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 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,
+      intentName: globalConfig.intentName,
+      onError: (_options$onError = options.onError) !== null && _options$onError !== void 0 ? _options$onError : dom.focusFirstInvalidField,
+      onValidate(ctx) {
+        var _options$onValidate, _options$onValidate2, _options;
+        if (schema) {
+          var schemaResult = globalConfig.validateSchema(schema, ctx.payload, options.schemaOptions);
+          if (schemaResult instanceof Promise) {
+            return schemaResult.then(resolvedResult => {
+              if (typeof options.onValidate === 'function') {
+                throw new Error('The "onValidate" handler is not supported when used with asynchronous schema validation.');
+              }
+              return resolvedResult;
+            });
+          }
+          if (!options.onValidate) {
+            return schemaResult;
+          }
+
+          // Update the schema error in the context
+          if (schemaResult.error) {
+            ctx.error = schemaResult.error;
+          }
+          var schemaValue = schemaResult.value;
+          ctx.schemaValue = schemaValue;
+          var validateResult = util.resolveValidateResult(options.onValidate(ctx));
+          if (validateResult.syncResult) {
+            var _validateResult$syncR, _validateResult$syncR2;
+            (_validateResult$syncR2 = (_validateResult$syncR = validateResult.syncResult).value) !== null && _validateResult$syncR2 !== void 0 ? _validateResult$syncR2 : _validateResult$syncR.value = schemaValue;
+          }
+          if (validateResult.asyncResult) {
+            validateResult.asyncResult = validateResult.asyncResult.then(result => {
+              var _result$value;
+              (_result$value = result.value) !== null && _result$value !== void 0 ? _result$value : result.value = schemaValue;
+              return result;
+            });
+          }
+          return [validateResult.syncResult, validateResult.asyncResult];
+        }
+        return (_options$onValidate = (_options$onValidate2 = (_options = options).onValidate) === null || _options$onValidate2 === void 0 ? void 0 : _options$onValidate2.call(_options, ctx)) !== null && _options$onValidate !== void 0 ? _options$onValidate : {
+          // To avoid conform falling back to server validation,
+          // if neither schema nor validation handler is provided,
+          // we just treat it as a valid client submission
+          error: null
+        };
+      }
+    }));
+    var intent = useIntent(formId);
+    var context = react.useMemo(() => ({
+      formId,
+      state: state$1,
+      constraint: constraint !== null && constraint !== void 0 ? constraint : null,
+      handleSubmit,
+      handleInput(event) {
+        var _optionsRef$current$o, _optionsRef$current, _optionsRef$current$s, _ref2, _optionsRef$current$s2;
+        if (!dom$1.isFieldElement(event.target) || event.target.name === '' || event.target.form === null || event.target.form !== dom.getFormElement(formId)) {
+          return;
+        }
+        (_optionsRef$current$o = (_optionsRef$current = optionsRef.current).onInput) === null || _optionsRef$current$o === void 0 || _optionsRef$current$o.call(_optionsRef$current, _rollupPluginBabelHelpers.objectSpread2(_rollupPluginBabelHelpers.objectSpread2({}, event), {}, {
+          target: event.target,
+          currentTarget: event.target.form
+        }));
+        if (event.defaultPrevented) {
+          return;
+        }
+        var shouldValidate = (_optionsRef$current$s = optionsRef.current.shouldValidate) !== null && _optionsRef$current$s !== void 0 ? _optionsRef$current$s : globalConfig.shouldValidate;
+        var shouldRevalidate = (_ref2 = (_optionsRef$current$s2 = optionsRef.current.shouldRevalidate) !== null && _optionsRef$current$s2 !== void 0 ? _optionsRef$current$s2 : optionsRef.current.shouldValidate) !== null && _ref2 !== void 0 ? _ref2 : globalConfig.shouldRevalidate;
+        if (state.isTouched(state$1, event.target.name) ? shouldRevalidate === 'onInput' : shouldValidate === 'onInput') {
+          intent.validate(event.target.name);
+        }
+      },
+      handleBlur(event) {
+        var _optionsRef$current$o2, _optionsRef$current2, _optionsRef$current$s3, _ref3, _optionsRef$current$s4;
+        if (!dom$1.isFieldElement(event.target) || event.target.name === '' || event.target.form === null || event.target.form !== dom.getFormElement(formId)) {
+          return;
+        }
+        (_optionsRef$current$o2 = (_optionsRef$current2 = optionsRef.current).onBlur) === null || _optionsRef$current$o2 === void 0 || _optionsRef$current$o2.call(_optionsRef$current2, _rollupPluginBabelHelpers.objectSpread2(_rollupPluginBabelHelpers.objectSpread2({}, event), {}, {
+          target: event.target,
+          currentTarget: event.target.form
+        }));
+        if (event.defaultPrevented) {
+          return;
+        }
+        var shouldValidate = (_optionsRef$current$s3 = optionsRef.current.shouldValidate) !== null && _optionsRef$current$s3 !== void 0 ? _optionsRef$current$s3 : globalConfig.shouldValidate;
+        var shouldRevalidate = (_ref3 = (_optionsRef$current$s4 = optionsRef.current.shouldRevalidate) !== null && _optionsRef$current$s4 !== void 0 ? _optionsRef$current$s4 : optionsRef.current.shouldValidate) !== null && _ref3 !== void 0 ? _ref3 : globalConfig.shouldRevalidate;
+        if (state.isTouched(state$1, event.target.name) ? shouldRevalidate === 'onBlur' : shouldValidate === 'onBlur') {
+          intent.validate(event.target.name);
+        }
+      }
+    }), [formId, state$1, 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 {
+      form,
+      fields,
+      intent
+    };
+  }
+
+  /**
+   * 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>
+   *   );
+   * }
+   * ```
+   */
+  function useFormMetadata() {
+    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]);
+    return 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>
+   *   );
+   * }
+   * ```
+   */
+  function useField(name) {
+    var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+    var context = useFormContext(options.formId);
+    var field = react.useMemo(() => state.getField(context, {
+      name,
+      serialize: globalConfig.serialize,
+      extendFieldMetadata: globalConfig.extendFieldMetadata
+    }), [context, name]);
+    return field;
+  }
+
+  /**
+   * 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>
+   *   );
+   * }
+   * ```
+   */
+  function useIntent(formRef) {
+    return react.useMemo(() => dom.createIntentDispatcher(() => dom.getFormElement(formRef), globalConfig.intentName), [formRef]);
+  }
+  return {
+    FormProvider,
+    useForm,
+    useFormMetadata,
+    useField,
+    useIntent,
+    config: globalConfig
+  };
+}
+
+exports.configureForms = configureForms;