@conform-to/react 1.15.1 → 1.17.0

package/dist/future/hooks.d.ts

@@ -15,6 +15,28 @@ export declare function FormProvider(props: {
     context: FormContext;
     children: React.ReactNode;
 }): React.ReactElement;
+/**
+ * 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
+ */
+export declare function PreserveBoundary(props: {
+    /**
+     * A unique name for the boundary within the form. Used to ensure proper
+     * unmount/remount behavior and to isolate preserved inputs between boundaries.
+     */
+    name: string;
+    /**
+     * The id of the form to associate with. Only needed when the boundary
+     * is rendered outside the form element.
+     */
+    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;
@@ -206,18 +228,36 @@ export declare function useControl(options?: {
  * 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.
  *
+ * 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
  * ```ts
- * const value = useFormData(formRef, formData => formData?.get('fieldName') ?? '');
+ * const value = useFormData(
+ *   formRef,
+ *   formData => formData.get('fieldName') ?? '',
+ * );
  * ```
  */
-export declare function useFormData<Value = any>(formRef: FormRef, select: Selector<FormData, Value>, options: UseFormDataOptions & {
+export declare function useFormData<Value>(formRef: FormRef, select: Selector<FormData, Value>, options: UseFormDataOptions<Value> & {
     acceptFiles: true;
+    fallback: Value;
 }): Value;
-export declare function useFormData<Value = any>(formRef: FormRef, select: Selector<URLSearchParams, Value>, options?: UseFormDataOptions & {
-    acceptFiles?: boolean;
+export declare function useFormData<Value>(formRef: FormRef, select: Selector<FormData, Value>, options: UseFormDataOptions & {
+    acceptFiles: true;
+}): Value | undefined;
+export declare function useFormData<Value>(formRef: FormRef, select: Selector<URLSearchParams, Value>, options: UseFormDataOptions<Value> & {
+    acceptFiles?: false;
+    fallback: Value;
 }): Value;
+export declare function useFormData<Value>(formRef: FormRef, select: Selector<URLSearchParams, Value>, options?: UseFormDataOptions & {
+    acceptFiles?: false;
+}): Value | undefined;
+export declare function useFormData<Value>(formRef: FormRef, select: Selector<FormData, Value> | Selector<URLSearchParams, Value>, options?: UseFormDataOptions & {
+    acceptFiles?: boolean;
+    fallback?: Value;
+}): Value | undefined;
 /**
  * useLayoutEffect is client-only.
  * This basically makes it a no-op on server

package/dist/future/hooks.js

@@ -38,6 +38,51 @@ function FormProvider(props) {
     children: props.children
   });
 }
+
+/**
+ * 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
+ */
+function PreserveBoundary(props) {
+  // name is used as key so React properly unmounts/remounts when switching
+  // between boundaries. Without it, both sides of a ternary share
+  // key={undefined} and React reuses the instance (useId and key prop
+  // can't help here). This is why name is required.
+  return /*#__PURE__*/jsxRuntime.jsx(PreserveBoundaryImpl, _rollupPluginBabelHelpers.objectSpread2({}, props), props.name);
+}
+function PreserveBoundaryImpl(props) {
+  var fieldsetRef = react.useRef(null);
+
+  // useLayoutEffect to restore values before paint, avoiding flash of default values
+  useSafeLayoutEffect(() => {
+    var fieldset = fieldsetRef.current;
+    if (!fieldset || !fieldset.form) {
+      return;
+    }
+    var form = fieldset.form;
+
+    // On mount: restore values from preserved inputs
+    dom.cleanupPreservedInputs(fieldset, form, props.name);
+    return () => {
+      // On unmount: preserve input values
+      dom.preserveInputs(fieldset.querySelectorAll('input,select,textarea'), form, props.name);
+    };
+  }, [props.name]);
+  return /*#__PURE__*/jsxRuntime.jsx("fieldset", {
+    ref: fieldsetRef,
+    form: props.form,
+    style: {
+      display: 'contents'
+    },
+    children: props.children
+  });
+}
+
+/**
+ * @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`.
+ */
 function FormOptionsProvider(props) {
   var {
       children
@@ -73,11 +118,16 @@ function useConform(formRef, options) {
       resetKey: INITIAL_KEY
     });
     if (lastResult) {
-      state$1 = state.updateState(state$1, _rollupPluginBabelHelpers.objectSpread2(_rollupPluginBabelHelpers.objectSpread2({}, lastResult), {}, {
+      var intent$1 = lastResult.submission.intent ? intent.deserializeIntent(lastResult.submission.intent) : null;
+      var result = intent.applyIntent(lastResult, intent$1, {
+        handlers: intent.intentHandlers
+      });
+      state$1 = state.updateState(state$1, _rollupPluginBabelHelpers.objectSpread2(_rollupPluginBabelHelpers.objectSpread2({}, result), {}, {
         type: 'initialize',
-        intent: lastResult.submission.intent ? intent.deserializeIntent(lastResult.submission.intent) : null,
+        intent: intent$1,
         ctx: {
-          handlers: intent.actionHandlers,
+          handlers: intent.intentHandlers,
+          cancelled: result !== lastResult,
           reset: defaultValue => state.initializeState({
             defaultValue: defaultValue !== null && defaultValue !== void 0 ? defaultValue : options.defaultValue,
             resetKey: INITIAL_KEY
@@ -95,14 +145,17 @@ function useConform(formRef, options) {
   var lastAsyncResultRef = react.useRef(null);
   var abortControllerRef = react.useRef(null);
   var handleSubmission = react.useCallback(function (type, result) {
-    var _optionsRef$current$o, _optionsRef$current;
     var options = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : optionsRef.current;
     var intent$1 = result.submission.intent ? intent.deserializeIntent(result.submission.intent) : null;
-    setState(state$1 => state.updateState(state$1, _rollupPluginBabelHelpers.objectSpread2(_rollupPluginBabelHelpers.objectSpread2({}, result), {}, {
+    var finalResult = intent.applyIntent(result, intent$1, {
+      handlers: intent.intentHandlers
+    });
+    setState(state$1 => state.updateState(state$1, _rollupPluginBabelHelpers.objectSpread2(_rollupPluginBabelHelpers.objectSpread2({}, finalResult), {}, {
       type,
       intent: intent$1,
       ctx: {
-        handlers: intent.actionHandlers,
+        handlers: intent.intentHandlers,
+        cancelled: finalResult !== result,
         reset(defaultValue) {
           return state.initializeState({
             defaultValue: defaultValue !== null && defaultValue !== void 0 ? defaultValue : options.defaultValue
@@ -113,14 +166,15 @@ function useConform(formRef, options) {
 
     // TODO: move on error handler to a new effect
     var formElement = dom.getFormElement(formRef);
-    if (!formElement || !result.error) {
-      return;
+    if (formElement && result.error) {
+      var _optionsRef$current$o, _optionsRef$current;
+      (_optionsRef$current$o = (_optionsRef$current = optionsRef.current).onError) === null || _optionsRef$current$o === void 0 || _optionsRef$current$o.call(_optionsRef$current, {
+        formElement,
+        error: result.error,
+        intent: intent$1
+      });
     }
-    (_optionsRef$current$o = (_optionsRef$current = optionsRef.current).onError) === null || _optionsRef$current$o === void 0 || _optionsRef$current$o.call(_optionsRef$current, {
-      formElement,
-      error: result.error,
-      intent: intent$1
-    });
+    return finalResult;
   }, [formRef, optionsRef]);
   if (options.key !== keyRef.current) {
     keyRef.current = options.key;
@@ -196,17 +250,11 @@ function useConform(formRef, options) {
       if (pendingValueRef.current !== undefined) {
         submission.payload = pendingValueRef.current;
       }
-      var value = intent.applyIntent(submission);
+      var value = intent.resolveIntent(submission);
       var submissionResult = future.report(submission, {
         keepFiles: true,
         value
       });
-
-      // If there is target value, keep track of it as pending value
-      if (submission.payload !== value) {
-        var _ref;
-        pendingValueRef.current = (_ref = value !== null && value !== void 0 ? value : optionsRef.current.defaultValue) !== null && _ref !== void 0 ? _ref : {};
-      }
       var validateResult =
       // Skip validation on form reset
       value !== undefined ? (_optionsRef$current$o2 = (_optionsRef$current2 = optionsRef.current).onValidate) === null || _optionsRef$current$o2 === void 0 ? void 0 : _optionsRef$current$o2.call(_optionsRef$current2, {
@@ -233,11 +281,11 @@ function useConform(formRef, options) {
       }
       if (typeof asyncResult !== 'undefined') {
         // Update the form when the validation result is resolved
-        asyncResult.then(_ref2 => {
+        asyncResult.then(_ref => {
           var {
             error,
             value
-          } = _ref2;
+          } = _ref;
           // Update the form with the validation result
           // There is no need to flush the update in this case
           if (!abortController.signal.aborted) {
@@ -245,7 +293,7 @@ function useConform(formRef, options) {
             handleSubmission('server', submissionResult);
 
             // If the form is meant to be submitted and there is no error
-            if (error === null && !submission.intent) {
+            if (submissionResult.error === null && !submission.intent) {
               var _event = future.createSubmitEvent(submitEvent.submitter);
 
               // Keep track of the submit event so we can skip validation on the next submit
@@ -260,15 +308,19 @@ function useConform(formRef, options) {
           }
         });
       }
-      handleSubmission('client', submissionResult);
+      var clientResult = handleSubmission('client', submissionResult);
+      if (clientResult.reset || clientResult.targetValue !== undefined) {
+        var _ref2, _clientResult$targetV;
+        pendingValueRef.current = (_ref2 = (_clientResult$targetV = clientResult.targetValue) !== null && _clientResult$targetV !== void 0 ? _clientResult$targetV : optionsRef.current.defaultValue) !== null && _ref2 !== void 0 ? _ref2 : {};
+      }
       if (
       // If client validation happens
       (typeof syncResult !== 'undefined' || typeof asyncResult !== 'undefined') && (
       // Either the form is not meant to be submitted (i.e. intent is present) or there is an error / pending validation
-      submissionResult.submission.intent || submissionResult.error !== null)) {
+      clientResult.submission.intent || clientResult.error !== null)) {
         event.preventDefault();
       }
-      result = submissionResult;
+      result = clientResult;
     }
 
     // We might not prevent form submission if server validation is required
@@ -465,11 +517,11 @@ function useForm(schemaOrOptions, maybeOptions) {
   }), [formId, state$1, constraint, handleSubmit, intent, optionsRef, globalOptionsRef]);
   var form = react.useMemo(() => state.getFormMetadata(context, {
     serialize: globalOptions.serialize,
-    customize: globalOptions.defineCustomMetadata
+    extendFieldMetadata: globalOptions.defineCustomMetadata
   }), [context, globalOptions.serialize, globalOptions.defineCustomMetadata]);
   var fields = react.useMemo(() => state.getFieldset(context, {
     serialize: globalOptions.serialize,
-    customize: globalOptions.defineCustomMetadata
+    extendFieldMetadata: globalOptions.defineCustomMetadata
   }), [context, globalOptions.serialize, globalOptions.defineCustomMetadata]);
   return {
     form,
@@ -502,7 +554,7 @@ function useFormMetadata() {
   var context = useFormContext(options.formId);
   var formMetadata = react.useMemo(() => state.getFormMetadata(context, {
     serialize: globalOptions.serialize,
-    customize: globalOptions.defineCustomMetadata
+    extendFieldMetadata: globalOptions.defineCustomMetadata
   }), [context, globalOptions.serialize, globalOptions.defineCustomMetadata]);
   return formMetadata;
 }
@@ -534,7 +586,7 @@ function useField(name) {
   var field = react.useMemo(() => state.getField(context, {
     name,
     serialize: globalOptions.serialize,
-    customize: globalOptions.defineCustomMetadata
+    extendFieldMetadata: globalOptions.defineCustomMetadata
   }), [context, name, globalOptions.serialize, globalOptions.defineCustomMetadata]);
   return field;
 }
@@ -757,10 +809,16 @@ function useControl(options) {
  * 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.
  *
+ * 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
  * ```ts
- * const value = useFormData(formRef, formData => formData?.get('fieldName') ?? '');
+ * const value = useFormData(
+ *   formRef,
+ *   formData => formData.get('fieldName') ?? '',
+ * );
  * ```
  */
 
@@ -769,7 +827,7 @@ function useFormData(formRef, select, options) {
     observer
   } = react.useContext(GlobalFormOptionsContext);
   var valueRef = react.useRef();
-  var formDataRef = react.useRef(null);
+  var formDataRef = react.useRef();
   var value = react.useSyncExternalStore(react.useCallback(callback => {
     var formElement = dom.getFormElement(formRef);
     if (formElement) {
@@ -791,14 +849,17 @@ function useFormData(formRef, select, options) {
     });
     return unsubscribe;
   }, [observer, formRef, options === null || options === void 0 ? void 0 : options.acceptFiles]), () => {
-    // @ts-expect-error FIXME
+    // Return fallback if form is not available
+    if (formDataRef.current === undefined) {
+      return options === null || options === void 0 ? void 0 : options.fallback;
+    }
     var result = select(formDataRef.current, valueRef.current);
     if (typeof valueRef.current !== 'undefined' && future.deepEqual(result, valueRef.current)) {
       return valueRef.current;
     }
     valueRef.current = result;
     return result;
-  }, () => select(null, undefined));
+  }, () => options === null || options === void 0 ? void 0 : options.fallback);
   return value;
 }
 
@@ -825,6 +886,7 @@ exports.FormOptionsProvider = FormOptionsProvider;
 exports.FormProvider = FormProvider;
 exports.GlobalFormOptionsContext = GlobalFormOptionsContext;
 exports.INITIAL_KEY = INITIAL_KEY;
+exports.PreserveBoundary = PreserveBoundary;
 exports.useConform = useConform;
 exports.useControl = useControl;
 exports.useField = useField;

package/dist/future/hooks.mjs

@@ -1,11 +1,11 @@
 'use client';
-import { objectWithoutProperties as _objectWithoutProperties, objectSpread2 as _objectSpread2 } from '../_virtual/_rollupPluginBabelHelpers.mjs';
+import { objectSpread2 as _objectSpread2, objectWithoutProperties as _objectWithoutProperties } from '../_virtual/_rollupPluginBabelHelpers.mjs';
 import { DEFAULT_INTENT_NAME, createGlobalFormsObserver, serialize, isFieldElement, deepEqual, change, focus, blur, getFormData, parseSubmission, report, createSubmitEvent } from '@conform-to/dom/future';
-import { createContext, useContext, useMemo, useId, useRef, useEffect, useSyncExternalStore, useCallback, useState, useLayoutEffect } from 'react';
+import { createContext, useContext, useMemo, useRef, useId, useEffect, useSyncExternalStore, useCallback, useLayoutEffect, useState } from 'react';
 import { resolveStandardSchemaResult, resolveValidateResult, appendUniqueItem } from './util.mjs';
 import { isTouched, getFormMetadata, getFieldset, getField, initializeState, updateState } from './state.mjs';
-import { deserializeIntent, actionHandlers, applyIntent } from './intent.mjs';
-import { focusFirstInvalidField, getFormElement, createIntentDispatcher, createDefaultSnapshot, getRadioGroupValue, getCheckboxGroupValue, getInputSnapshot, makeInputFocusable, initializeField, resetFormValue, updateFormValue, getSubmitEvent } from './dom.mjs';
+import { deserializeIntent, applyIntent, intentHandlers, resolveIntent } from './intent.mjs';
+import { cleanupPreservedInputs, preserveInputs, focusFirstInvalidField, getFormElement, createIntentDispatcher, createDefaultSnapshot, getRadioGroupValue, getCheckboxGroupValue, getInputSnapshot, makeInputFocusable, initializeField, resetFormValue, updateFormValue, getSubmitEvent } from './dom.mjs';
 import { jsx } from 'react/jsx-runtime';
 
 var _excluded = ["children"];
@@ -34,6 +34,51 @@ function FormProvider(props) {
     children: props.children
   });
 }
+
+/**
+ * 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
+ */
+function PreserveBoundary(props) {
+  // name is used as key so React properly unmounts/remounts when switching
+  // between boundaries. Without it, both sides of a ternary share
+  // key={undefined} and React reuses the instance (useId and key prop
+  // can't help here). This is why name is required.
+  return /*#__PURE__*/jsx(PreserveBoundaryImpl, _objectSpread2({}, props), props.name);
+}
+function PreserveBoundaryImpl(props) {
+  var fieldsetRef = useRef(null);
+
+  // useLayoutEffect to restore values before paint, avoiding flash of default values
+  useSafeLayoutEffect(() => {
+    var fieldset = fieldsetRef.current;
+    if (!fieldset || !fieldset.form) {
+      return;
+    }
+    var form = fieldset.form;
+
+    // On mount: restore values from preserved inputs
+    cleanupPreservedInputs(fieldset, form, props.name);
+    return () => {
+      // On unmount: preserve input values
+      preserveInputs(fieldset.querySelectorAll('input,select,textarea'), form, props.name);
+    };
+  }, [props.name]);
+  return /*#__PURE__*/jsx("fieldset", {
+    ref: fieldsetRef,
+    form: props.form,
+    style: {
+      display: 'contents'
+    },
+    children: props.children
+  });
+}
+
+/**
+ * @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`.
+ */
 function FormOptionsProvider(props) {
   var {
       children
@@ -69,11 +114,16 @@ function useConform(formRef, options) {
       resetKey: INITIAL_KEY
     });
     if (lastResult) {
-      state = updateState(state, _objectSpread2(_objectSpread2({}, lastResult), {}, {
+      var intent = lastResult.submission.intent ? deserializeIntent(lastResult.submission.intent) : null;
+      var result = applyIntent(lastResult, intent, {
+        handlers: intentHandlers
+      });
+      state = updateState(state, _objectSpread2(_objectSpread2({}, result), {}, {
         type: 'initialize',
-        intent: lastResult.submission.intent ? deserializeIntent(lastResult.submission.intent) : null,
+        intent,
         ctx: {
-          handlers: actionHandlers,
+          handlers: intentHandlers,
+          cancelled: result !== lastResult,
           reset: defaultValue => initializeState({
             defaultValue: defaultValue !== null && defaultValue !== void 0 ? defaultValue : options.defaultValue,
             resetKey: INITIAL_KEY
@@ -91,14 +141,17 @@ function useConform(formRef, options) {
   var lastAsyncResultRef = useRef(null);
   var abortControllerRef = useRef(null);
   var handleSubmission = useCallback(function (type, result) {
-    var _optionsRef$current$o, _optionsRef$current;
     var options = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : optionsRef.current;
     var intent = result.submission.intent ? deserializeIntent(result.submission.intent) : null;
-    setState(state => updateState(state, _objectSpread2(_objectSpread2({}, result), {}, {
+    var finalResult = applyIntent(result, intent, {
+      handlers: intentHandlers
+    });
+    setState(state => updateState(state, _objectSpread2(_objectSpread2({}, finalResult), {}, {
       type,
       intent,
       ctx: {
-        handlers: actionHandlers,
+        handlers: intentHandlers,
+        cancelled: finalResult !== result,
         reset(defaultValue) {
           return initializeState({
             defaultValue: defaultValue !== null && defaultValue !== void 0 ? defaultValue : options.defaultValue
@@ -109,14 +162,15 @@ function useConform(formRef, options) {
 
     // TODO: move on error handler to a new effect
     var formElement = getFormElement(formRef);
-    if (!formElement || !result.error) {
-      return;
+    if (formElement && result.error) {
+      var _optionsRef$current$o, _optionsRef$current;
+      (_optionsRef$current$o = (_optionsRef$current = optionsRef.current).onError) === null || _optionsRef$current$o === void 0 || _optionsRef$current$o.call(_optionsRef$current, {
+        formElement,
+        error: result.error,
+        intent
+      });
     }
-    (_optionsRef$current$o = (_optionsRef$current = optionsRef.current).onError) === null || _optionsRef$current$o === void 0 || _optionsRef$current$o.call(_optionsRef$current, {
-      formElement,
-      error: result.error,
-      intent
-    });
+    return finalResult;
   }, [formRef, optionsRef]);
   if (options.key !== keyRef.current) {
     keyRef.current = options.key;
@@ -192,17 +246,11 @@ function useConform(formRef, options) {
       if (pendingValueRef.current !== undefined) {
         submission.payload = pendingValueRef.current;
       }
-      var value = applyIntent(submission);
+      var value = resolveIntent(submission);
       var submissionResult = report(submission, {
         keepFiles: true,
         value
       });
-
-      // If there is target value, keep track of it as pending value
-      if (submission.payload !== value) {
-        var _ref;
-        pendingValueRef.current = (_ref = value !== null && value !== void 0 ? value : optionsRef.current.defaultValue) !== null && _ref !== void 0 ? _ref : {};
-      }
       var validateResult =
       // Skip validation on form reset
       value !== undefined ? (_optionsRef$current$o2 = (_optionsRef$current2 = optionsRef.current).onValidate) === null || _optionsRef$current$o2 === void 0 ? void 0 : _optionsRef$current$o2.call(_optionsRef$current2, {
@@ -229,11 +277,11 @@ function useConform(formRef, options) {
       }
       if (typeof asyncResult !== 'undefined') {
         // Update the form when the validation result is resolved
-        asyncResult.then(_ref2 => {
+        asyncResult.then(_ref => {
           var {
             error,
             value
-          } = _ref2;
+          } = _ref;
           // Update the form with the validation result
           // There is no need to flush the update in this case
           if (!abortController.signal.aborted) {
@@ -241,7 +289,7 @@ function useConform(formRef, options) {
             handleSubmission('server', submissionResult);
 
             // If the form is meant to be submitted and there is no error
-            if (error === null && !submission.intent) {
+            if (submissionResult.error === null && !submission.intent) {
               var _event = createSubmitEvent(submitEvent.submitter);
 
               // Keep track of the submit event so we can skip validation on the next submit
@@ -256,15 +304,19 @@ function useConform(formRef, options) {
           }
         });
       }
-      handleSubmission('client', submissionResult);
+      var clientResult = handleSubmission('client', submissionResult);
+      if (clientResult.reset || clientResult.targetValue !== undefined) {
+        var _ref2, _clientResult$targetV;
+        pendingValueRef.current = (_ref2 = (_clientResult$targetV = clientResult.targetValue) !== null && _clientResult$targetV !== void 0 ? _clientResult$targetV : optionsRef.current.defaultValue) !== null && _ref2 !== void 0 ? _ref2 : {};
+      }
       if (
       // If client validation happens
       (typeof syncResult !== 'undefined' || typeof asyncResult !== 'undefined') && (
       // Either the form is not meant to be submitted (i.e. intent is present) or there is an error / pending validation
-      submissionResult.submission.intent || submissionResult.error !== null)) {
+      clientResult.submission.intent || clientResult.error !== null)) {
         event.preventDefault();
       }
-      result = submissionResult;
+      result = clientResult;
     }
 
     // We might not prevent form submission if server validation is required
@@ -461,11 +513,11 @@ function useForm(schemaOrOptions, maybeOptions) {
   }), [formId, state, constraint, handleSubmit, intent, optionsRef, globalOptionsRef]);
   var form = useMemo(() => getFormMetadata(context, {
     serialize: globalOptions.serialize,
-    customize: globalOptions.defineCustomMetadata
+    extendFieldMetadata: globalOptions.defineCustomMetadata
   }), [context, globalOptions.serialize, globalOptions.defineCustomMetadata]);
   var fields = useMemo(() => getFieldset(context, {
     serialize: globalOptions.serialize,
-    customize: globalOptions.defineCustomMetadata
+    extendFieldMetadata: globalOptions.defineCustomMetadata
   }), [context, globalOptions.serialize, globalOptions.defineCustomMetadata]);
   return {
     form,
@@ -498,7 +550,7 @@ function useFormMetadata() {
   var context = useFormContext(options.formId);
   var formMetadata = useMemo(() => getFormMetadata(context, {
     serialize: globalOptions.serialize,
-    customize: globalOptions.defineCustomMetadata
+    extendFieldMetadata: globalOptions.defineCustomMetadata
   }), [context, globalOptions.serialize, globalOptions.defineCustomMetadata]);
   return formMetadata;
 }
@@ -530,7 +582,7 @@ function useField(name) {
   var field = useMemo(() => getField(context, {
     name,
     serialize: globalOptions.serialize,
-    customize: globalOptions.defineCustomMetadata
+    extendFieldMetadata: globalOptions.defineCustomMetadata
   }), [context, name, globalOptions.serialize, globalOptions.defineCustomMetadata]);
   return field;
 }
@@ -753,10 +805,16 @@ function useControl(options) {
  * 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.
  *
+ * 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
  * ```ts
- * const value = useFormData(formRef, formData => formData?.get('fieldName') ?? '');
+ * const value = useFormData(
+ *   formRef,
+ *   formData => formData.get('fieldName') ?? '',
+ * );
  * ```
  */
 
@@ -765,7 +823,7 @@ function useFormData(formRef, select, options) {
     observer
   } = useContext(GlobalFormOptionsContext);
   var valueRef = useRef();
-  var formDataRef = useRef(null);
+  var formDataRef = useRef();
   var value = useSyncExternalStore(useCallback(callback => {
     var formElement = getFormElement(formRef);
     if (formElement) {
@@ -787,14 +845,17 @@ function useFormData(formRef, select, options) {
     });
     return unsubscribe;
   }, [observer, formRef, options === null || options === void 0 ? void 0 : options.acceptFiles]), () => {
-    // @ts-expect-error FIXME
+    // Return fallback if form is not available
+    if (formDataRef.current === undefined) {
+      return options === null || options === void 0 ? void 0 : options.fallback;
+    }
     var result = select(formDataRef.current, valueRef.current);
     if (typeof valueRef.current !== 'undefined' && deepEqual(result, valueRef.current)) {
       return valueRef.current;
     }
     valueRef.current = result;
     return result;
-  }, () => select(null, undefined));
+  }, () => options === null || options === void 0 ? void 0 : options.fallback);
   return value;
 }
 
@@ -816,4 +877,4 @@ function useLatest(value) {
   return ref;
 }
 
-export { FormContextContext, FormOptionsProvider, FormProvider, GlobalFormOptionsContext, INITIAL_KEY, useConform, useControl, useField, useForm, useFormContext, useFormData, useFormMetadata, useIntent, useLatest, useSafeLayoutEffect };
+export { FormContextContext, FormOptionsProvider, FormProvider, GlobalFormOptionsContext, INITIAL_KEY, PreserveBoundary, useConform, useControl, useField, useForm, useFormContext, useFormData, useFormMetadata, useIntent, useLatest, useSafeLayoutEffect };

package/dist/future/index.d.ts

@@ -1,6 +1,8 @@
 export type { FieldName, FormError, FormValue, Submission, SubmissionResult, } from '@conform-to/dom/future';
 export { getFieldValue, parseSubmission, report, isDirty, } from '@conform-to/dom/future';
-export type { Control, DefaultValue, BaseMetadata, CustomMetadata, CustomMetadataDefinition, BaseErrorShape, CustomTypes, FormContext, FormMetadata, FormOptions, FormRef, FieldMetadata, Fieldset, IntentDispatcher, } from './types';
-export { FormProvider, FormOptionsProvider, useControl, useField, useForm, useFormData, useFormMetadata, useIntent, } from './hooks';
+export type { Control, DefaultValue, BaseMetadata, BaseFieldMetadata, CustomMetadata, CustomMetadataDefinition, BaseErrorShape, CustomTypes, CustomSchemaTypes, FormsConfig, FormContext, FormMetadata, FormOptions, FormRef, FieldMetadata, Fieldset, IntentDispatcher, InferBaseErrorShape, InferCustomFormMetadata, InferCustomFieldMetadata, } from './types';
+export { configureForms } from './forms';
+export { PreserveBoundary, FormProvider, FormOptionsProvider, useControl, useField, useForm, useFormData, useFormMetadata, useIntent, } from './hooks';
+export { shape } from './util';
 export { memoize } from './memoize';
 //# sourceMappingURL=index.d.ts.map

package/dist/future/index.js

@@ -3,7 +3,9 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var future = require('@conform-to/dom/future');
+var forms = require('./forms.js');
 var hooks = require('./hooks.js');
+var util = require('./util.js');
 var memoize = require('./memoize.js');
 
 
@@ -24,12 +26,15 @@ Object.defineProperty(exports, 'report', {
 	enumerable: true,
 	get: function () { return future.report; }
 });
+exports.configureForms = forms.configureForms;
 exports.FormOptionsProvider = hooks.FormOptionsProvider;
 exports.FormProvider = hooks.FormProvider;
+exports.PreserveBoundary = hooks.PreserveBoundary;
 exports.useControl = hooks.useControl;
 exports.useField = hooks.useField;
 exports.useForm = hooks.useForm;
 exports.useFormData = hooks.useFormData;
 exports.useFormMetadata = hooks.useFormMetadata;
 exports.useIntent = hooks.useIntent;
+exports.shape = util.shape;
 exports.memoize = memoize.memoize;

package/dist/future/index.mjs

@@ -1,3 +1,5 @@
 export { getFieldValue, isDirty, parseSubmission, report } from '@conform-to/dom/future';
-export { FormOptionsProvider, FormProvider, useControl, useField, useForm, useFormData, useFormMetadata, useIntent } from './hooks.mjs';
+export { configureForms } from './forms.mjs';
+export { FormOptionsProvider, FormProvider, PreserveBoundary, useControl, useField, useForm, useFormData, useFormMetadata, useIntent } from './hooks.mjs';
+export { shape } from './util.mjs';
 export { memoize } from './memoize.mjs';