@conform-to/react 1.17.1 → 1.19.0

package/dist/future/hooks.js

@@ -10,40 +10,22 @@ var util = require('./util.js');
 var state = require('./state.js');
 var intent = require('./intent.js');
 var dom = require('./dom.js');
+var reactDom = require('react-dom');
 var jsxRuntime = require('react/jsx-runtime');
 
-var _excluded = ["children"];
-// Static reset key for consistent hydration during Next.js prerendering
-// See: https://nextjs.org/docs/messages/next-prerender-current-time-client
+var _excluded = ["name", "form", "defaultValue", "hidden"],
+  _excluded2 = ["defaultValue", "multiple", "hidden"],
+  _excluded3 = ["defaultValue", "hidden"],
+  _excluded4 = ["defaultValue", "value", "hidden"],
+  _excluded5 = ["defaultValue", "hidden"];
 var INITIAL_KEY = 'INITIAL_KEY';
-var GlobalFormOptionsContext = /*#__PURE__*/react.createContext({
-  intentName: future.DEFAULT_INTENT_NAME,
-  observer: future.createGlobalFormsObserver(),
-  serialize: future.serialize,
-  shouldValidate: 'onSubmit'
-});
-var FormContextContext = /*#__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(FormContextContext);
-  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(FormContextContext.Provider, {
-    value: value,
-    children: props.children
-  });
-}
+var GlobalFormsObserverContext = /*#__PURE__*/react.createContext(future.createGlobalFormsObserver());
 
 /**
  * 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
  */
 function PreserveBoundary(props) {
   // name is used as key so React properly unmounts/remounts when switching
@@ -80,30 +62,6 @@ function PreserveBoundaryImpl(props) {
   });
 }
 
-/**
- * @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
-    } = props,
-    providedOptions = _rollupPluginBabelHelpers.objectWithoutProperties(props, _excluded);
-  var defaultOptions = react.useContext(GlobalFormOptionsContext);
-  var options = react.useMemo(() => _rollupPluginBabelHelpers.objectSpread2(_rollupPluginBabelHelpers.objectSpread2({}, defaultOptions), providedOptions), [defaultOptions, providedOptions]);
-  return /*#__PURE__*/jsxRuntime.jsx(GlobalFormOptionsContext.Provider, {
-    value: options,
-    children: children
-  });
-}
-function useFormContext(formId) {
-  var contexts = react.useContext(FormContextContext);
-  var context = formId ? contexts.find(context => formId === context.formId) : contexts[0];
-  if (!context) {
-    throw new Error('No form context found; Have you render a <FormProvider /> with the corresponding form context?');
-  }
-  return context;
-}
-
 /**
  * Core form hook that manages form state, validation, and submission.
  * Handles both sync and async validation, intent dispatching, and DOM updates.
@@ -146,16 +104,23 @@ function useConform(formRef, options) {
   var abortControllerRef = react.useRef(null);
   var handleSubmission = react.useCallback(function (type, result) {
     var options = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : optionsRef.current;
+    var normalizedResult = !result.error ? result : _rollupPluginBabelHelpers.objectSpread2(_rollupPluginBabelHelpers.objectSpread2({}, result), {}, {
+      error: future.normalizeFormError(result.error)
+    });
     var intent$1 = result.submission.intent ? intent.deserializeIntent(result.submission.intent) : null;
-    var finalResult = intent.applyIntent(result, intent$1, {
+    var finalResult = intent.applyIntent(normalizedResult, intent$1, {
       handlers: intent.intentHandlers
     });
+    var formElement = dom.getFormElement(formRef);
+    if (formElement && (finalResult.reset || typeof finalResult.targetValue !== 'undefined')) {
+      future.dispatchInternalUpdateEvent(formElement);
+    }
     setState(state$1 => state.updateState(state$1, _rollupPluginBabelHelpers.objectSpread2(_rollupPluginBabelHelpers.objectSpread2({}, finalResult), {}, {
       type,
       intent: intent$1,
       ctx: {
         handlers: intent.intentHandlers,
-        cancelled: finalResult !== result,
+        cancelled: finalResult !== normalizedResult,
         reset(defaultValue) {
           return state.initializeState({
             defaultValue: defaultValue !== null && defaultValue !== void 0 ? defaultValue : options.defaultValue
@@ -165,12 +130,11 @@ function useConform(formRef, options) {
     })));
 
     // TODO: move on error handler to a new effect
-    var formElement = dom.getFormElement(formRef);
-    if (formElement && result.error) {
+    if (formElement && finalResult.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,
+        error: finalResult.error,
         intent: intent$1
       });
     }
@@ -178,6 +142,10 @@ function useConform(formRef, options) {
   }, [formRef, optionsRef]);
   if (options.key !== keyRef.current) {
     keyRef.current = options.key;
+    var formElement = dom.getFormElement(formRef);
+    if (formElement) {
+      future.dispatchInternalUpdateEvent(formElement);
+    }
     setState(state.initializeState({
       defaultValue: options.defaultValue
     }));
@@ -204,52 +172,56 @@ function useConform(formRef, options) {
   }, [formRef, state$1.resetKey, state$1.defaultValue, optionsRef]);
   useSafeLayoutEffect(() => {
     if (state$1.targetValue) {
-      var formElement = dom.getFormElement(formRef);
-      if (!formElement) {
+      var _formElement = dom.getFormElement(formRef);
+      if (!_formElement) {
         // eslint-disable-next-line no-console
         console.error('Failed to update form value; No form element found');
         return;
       }
-      dom.updateFormValue(formElement, state$1.targetValue, optionsRef.current.serialize);
+      dom.updateFormValue(_formElement, state$1.targetValue, optionsRef.current.serialize);
     }
     pendingValueRef.current = undefined;
   }, [formRef, state$1.targetValue, optionsRef]);
   var handleSubmit = react.useCallback(event => {
-    var _abortControllerRef$c2, _lastAsyncResultRef$c;
+    var _abortControllerRef$c2;
     var abortController = new AbortController();
 
     // Keep track of the abort controller so we can cancel the previous request if a new one is made
     (_abortControllerRef$c2 = abortControllerRef.current) === null || _abortControllerRef$c2 === void 0 || _abortControllerRef$c2.abort('A new submission is made');
     abortControllerRef.current = abortController;
-    var formData;
     var result;
     var resolvedValue;
+    var formElement = event.currentTarget;
+    var submitEvent = dom.getSubmitEvent(event);
+    var formData = future.getFormData(formElement, submitEvent.submitter);
+    var submission = future.parseSubmission(formData, {
+      intentName: optionsRef.current.intentName
+    });
 
-    // The form might be re-submitted manually if there was an async validation
-    if (event.nativeEvent === ((_lastAsyncResultRef$c = lastAsyncResultRef.current) === null || _lastAsyncResultRef$c === void 0 ? void 0 : _lastAsyncResultRef$c.event)) {
-      formData = lastAsyncResultRef.current.formData;
-      result = lastAsyncResultRef.current.result;
-      resolvedValue = lastAsyncResultRef.current.resolvedValue;
-    } else {
-      var _optionsRef$current$o2, _optionsRef$current2;
-      var formElement = event.currentTarget;
-      var submitEvent = dom.getSubmitEvent(event);
-      formData = future.getFormData(formElement, submitEvent.submitter);
-      var submission = future.parseSubmission(formData, {
-        intentName: optionsRef.current.intentName
-      });
-
-      // Patch missing fields in the submission object
-      for (var element of formElement.elements) {
-        if (future.isFieldElement(element) && element.name) {
-          submission.fields = util.appendUniqueItem(submission.fields, element.name);
-        }
+    // Patch missing fields in the submission object
+    for (var element of formElement.elements) {
+      if (future.isFieldElement(element) && element.name) {
+        submission.fields = util.appendUniqueItem(submission.fields, element.name);
       }
+    }
 
-      // Override submission value if the pending value is not applied yet (i.e. batch updates)
-      if (pendingValueRef.current !== undefined) {
-        submission.payload = pendingValueRef.current;
-      }
+    // Override submission value if the pending value is not applied yet (i.e. batch updates)
+    if (pendingValueRef.current !== undefined) {
+      submission.payload = pendingValueRef.current;
+    }
+    var lastAsyncResult = lastAsyncResultRef.current;
+
+    // Clear the last async result so it won't affect the next submission
+    lastAsyncResultRef.current = null;
+    if (lastAsyncResult &&
+    // Only default submission will be re-submitted after async validation
+    !submission.intent &&
+    // Ensure the submission payload is the same as the one being validated
+    future.deepEqual(submission.payload, lastAsyncResult.result.submission.payload)) {
+      result = lastAsyncResult.result;
+      resolvedValue = lastAsyncResult.resolvedValue;
+    } else {
+      var _optionsRef$current$o2, _optionsRef$current2;
       var value = intent.resolveIntent(submission);
       var submissionResult = future.report(submission, {
         keepFiles: true,
@@ -260,7 +232,7 @@ function useConform(formRef, options) {
       value !== undefined ? (_optionsRef$current$o2 = (_optionsRef$current2 = optionsRef.current).onValidate) === null || _optionsRef$current$o2 === void 0 ? void 0 : _optionsRef$current$o2.call(_optionsRef$current2, {
         payload: value,
         error: {
-          formErrors: [],
+          formErrors: null,
           fieldErrors: {}
         },
         intent: submission.intent ? intent.deserializeIntent(submission.intent) : null,
@@ -294,16 +266,20 @@ function useConform(formRef, options) {
 
             // If the form is meant to be submitted and there is no error
             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
-              lastAsyncResultRef.current = {
-                event: _event,
-                formData,
-                resolvedValue: value,
-                result: submissionResult
-              };
-              formElement.dispatchEvent(_event);
+              // Keep track of the validated payload and resume submission on the next task.
+              // Calling requestSubmit() directly from the async callback, or from a
+              // microtask, can still be ignored before the native submission lifecycle
+              // has fully settled.
+              setTimeout(() => {
+                if (abortController.signal.aborted) {
+                  return;
+                }
+                lastAsyncResultRef.current = {
+                  resolvedValue: value,
+                  result: submissionResult
+                };
+                future.requestSubmit(formElement, submitEvent.submitter);
+              }, 0);
             }
           }
         });
@@ -349,287 +325,20 @@ function useConform(formRef, options) {
   return [state$1, handleSubmit];
 }
 
-/**
- * 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$onError;
-  var schema;
-  var options;
-  if (maybeOptions) {
-    schema = schemaOrOptions;
-    options = maybeOptions;
-  } else {
-    var fullOptions = schemaOrOptions;
-    options = fullOptions;
-    schema = fullOptions.schema;
-  }
-  var {
-    id,
-    constraint
-  } = options;
-  var globalOptions = react.useContext(GlobalFormOptionsContext);
-  var optionsRef = useLatest(options);
-  var globalOptionsRef = useLatest(globalOptions);
-  var fallbackId = react.useId();
-  var formId = id !== null && id !== void 0 ? id : "form-".concat(fallbackId);
-  var [state$1, handleSubmit] = useConform(formId, _rollupPluginBabelHelpers.objectSpread2(_rollupPluginBabelHelpers.objectSpread2({}, options), {}, {
-    serialize: globalOptions.serialize,
-    intentName: globalOptions.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 standardResult = schema['~standard'].validate(ctx.payload);
-        if (standardResult instanceof Promise) {
-          return standardResult.then(actualStandardResult => {
-            if (typeof options.onValidate === 'function') {
-              throw new Error('The "onValidate" handler is not supported when used with asynchronous schema validation.');
-            }
-            return util.resolveStandardSchemaResult(actualStandardResult);
-          });
-        }
-        var resolvedResult = util.resolveStandardSchemaResult(standardResult);
-        if (!options.onValidate) {
-          return resolvedResult;
-        }
-
-        // Update the schema error in the context
-        if (resolvedResult.error) {
-          ctx.error = resolvedResult.error;
-        }
-        ctx.schemaValue = resolvedResult.value;
-        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 = resolvedResult.value;
-        }
-        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 = resolvedResult.value;
-            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$o4, _optionsRef$current4, _globalOptionsRef$cur;
-      if (!future.isFieldElement(event.target) || event.target.name === '' || event.target.form === null || event.target.form !== dom.getFormElement(formId)) {
-        return;
-      }
-      (_optionsRef$current$o4 = (_optionsRef$current4 = optionsRef.current).onInput) === null || _optionsRef$current$o4 === void 0 || _optionsRef$current$o4.call(_optionsRef$current4, _rollupPluginBabelHelpers.objectSpread2(_rollupPluginBabelHelpers.objectSpread2({}, event), {}, {
-        target: event.target,
-        currentTarget: event.target.form
-      }));
-      if (event.defaultPrevented) {
-        return;
-      }
-      var {
-        shouldValidate = globalOptionsRef.current.shouldValidate,
-        shouldRevalidate = (_globalOptionsRef$cur = globalOptionsRef.current.shouldRevalidate) !== null && _globalOptionsRef$cur !== void 0 ? _globalOptionsRef$cur : shouldValidate
-      } = optionsRef.current;
-      if (state.isTouched(state$1, event.target.name) ? shouldRevalidate === 'onInput' : shouldValidate === 'onInput') {
-        intent.validate(event.target.name);
-      }
-    },
-    handleBlur(event) {
-      var _optionsRef$current$o5, _optionsRef$current5, _globalOptionsRef$cur2;
-      if (!future.isFieldElement(event.target) || event.target.name === '' || event.target.form === null || event.target.form !== dom.getFormElement(formId)) {
-        return;
-      }
-      (_optionsRef$current$o5 = (_optionsRef$current5 = optionsRef.current).onBlur) === null || _optionsRef$current$o5 === void 0 || _optionsRef$current$o5.call(_optionsRef$current5, _rollupPluginBabelHelpers.objectSpread2(_rollupPluginBabelHelpers.objectSpread2({}, event), {}, {
-        target: event.target,
-        currentTarget: event.target.form
-      }));
-      if (event.defaultPrevented) {
-        return;
-      }
-      var {
-        shouldValidate = globalOptionsRef.current.shouldValidate,
-        shouldRevalidate = (_globalOptionsRef$cur2 = globalOptionsRef.current.shouldRevalidate) !== null && _globalOptionsRef$cur2 !== void 0 ? _globalOptionsRef$cur2 : shouldValidate
-      } = optionsRef.current;
-      if (state.isTouched(state$1, event.target.name) ? shouldRevalidate === 'onBlur' : shouldValidate === 'onBlur') {
-        intent.validate(event.target.name);
-      }
-    }
-  }), [formId, state$1, constraint, handleSubmit, intent, optionsRef, globalOptionsRef]);
-  var form = react.useMemo(() => state.getFormMetadata(context, {
-    serialize: globalOptions.serialize,
-    extendFieldMetadata: globalOptions.defineCustomMetadata
-  }), [context, globalOptions.serialize, globalOptions.defineCustomMetadata]);
-  var fields = react.useMemo(() => state.getFieldset(context, {
-    serialize: globalOptions.serialize,
-    extendFieldMetadata: globalOptions.defineCustomMetadata
-  }), [context, globalOptions.serialize, globalOptions.defineCustomMetadata]);
-  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 globalOptions = react.useContext(GlobalFormOptionsContext);
-  var context = useFormContext(options.formId);
-  var formMetadata = react.useMemo(() => state.getFormMetadata(context, {
-    serialize: globalOptions.serialize,
-    extendFieldMetadata: globalOptions.defineCustomMetadata
-  }), [context, globalOptions.serialize, globalOptions.defineCustomMetadata]);
-  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 globalOptions = react.useContext(GlobalFormOptionsContext);
-  var context = useFormContext(options.formId);
-  var field = react.useMemo(() => state.getField(context, {
-    name,
-    serialize: globalOptions.serialize,
-    extendFieldMetadata: globalOptions.defineCustomMetadata
-  }), [context, name, globalOptions.serialize, globalOptions.defineCustomMetadata]);
-  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) {
-  var globalOptions = react.useContext(GlobalFormOptionsContext);
-  return react.useMemo(() => dom.createIntentDispatcher(() => dom.getFormElement(formRef), globalOptions.intentName), [formRef, globalOptions.intentName]);
-}
-
 /**
  * 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);
  * ```
  */
-function useControl(options) {
-  var {
-    observer
-  } = react.useContext(GlobalFormOptionsContext);
+
+function useControl() {
+  var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  var observer = react.useContext(GlobalFormsObserverContext);
   var inputRef = react.useRef(null);
   var formRef = react.useMemo(() => ({
     get current() {
@@ -641,29 +350,40 @@ function useControl(options) {
       return Array.isArray(input) ? (_input$0$form = (_input$ = input[0]) === null || _input$ === void 0 ? void 0 : _input$.form) !== null && _input$0$form !== void 0 ? _input$0$form : null : input.form;
     }
   }), []);
+  var [defaultValue, setDefaultValue] = react.useState(() => dom.deriveDefaultPayload(options));
+  var pendingDefaultValueSyncRef = react.useRef(false);
+
+  /**
+   * Keep defaultValue in sync with external option updates during render.
+   * This is required for structural controls where hidden descendants must be
+   * rendered in the same cycle as form state updates (e.g. update intents).
+   */
+  if (pendingDefaultValueSyncRef.current && inputRef.current && future.isGlobalInstance(inputRef.current, 'HTMLFieldSetElement')) {
+    pendingDefaultValueSyncRef.current = false;
+    setDefaultValue(() => dom.deriveDefaultPayload(options));
+  }
   var eventDispatched = react.useRef({});
-  var defaultSnapshot = dom.createDefaultSnapshot(options === null || options === void 0 ? void 0 : options.defaultValue, options === null || options === void 0 ? void 0 : options.defaultChecked, options === null || options === void 0 ? void 0 : options.value);
-  var snapshotRef = react.useRef(defaultSnapshot);
+  var snapshotRef = react.useRef(defaultValue);
   var optionsRef = react.useRef(options);
   react.useEffect(() => {
     optionsRef.current = options;
   });
-
-  // This is necessary to ensure that input is re-registered
-  // if the onFocus handler changes
-  var shouldHandleFocus = typeof (options === null || options === void 0 ? void 0 : options.onFocus) === 'function';
-  var snapshot = react.useSyncExternalStore(react.useCallback(callback => observer.onFieldUpdate(event => {
+  react.useEffect(() => observer.onInternalUpdate(event => {
+    var input = inputRef.current;
+    if (input && input instanceof HTMLFieldSetElement && event.target === input.form) {
+      pendingDefaultValueSyncRef.current = true;
+    }
+  }), [observer]);
+  var payloadSnapshot = react.useSyncExternalStore(react.useCallback(callback => observer.onFieldUpdate(event => {
+    var _inputRef$current;
     var input = event.target;
-    if (Array.isArray(inputRef.current) ? inputRef.current.some(item => item === input) : inputRef.current === input) {
+    if (Array.isArray(inputRef.current) ? inputRef.current.some(item => item === input) : (_inputRef$current = inputRef.current) === null || _inputRef$current === void 0 ? void 0 : _inputRef$current.contains(input)) {
       callback();
     }
   }), [observer]), () => {
     var input = inputRef.current;
     var prev = snapshotRef.current;
-    var next = !input ? defaultSnapshot : Array.isArray(input) ? {
-      value: dom.getRadioGroupValue(input),
-      options: dom.getCheckboxGroupValue(input)
-    } : dom.getInputSnapshot(input);
+    var next = input ? dom.resolveControlPayload(input) : defaultValue;
     if (future.deepEqual(prev, next)) {
       return prev;
     }
@@ -673,7 +393,8 @@ function useControl(options) {
   react.useEffect(() => {
     var createEventListener = listener => {
       return event => {
-        if (Array.isArray(inputRef.current) ? inputRef.current.some(item => item === event.target) : inputRef.current === event.target) {
+        var _inputRef$current2;
+        if (Array.isArray(inputRef.current) ? inputRef.current.some(item => item === event.target) : event.target instanceof Node && ((_inputRef$current2 = inputRef.current) === null || _inputRef$current2 === void 0 ? void 0 : _inputRef$current2.contains(event.target))) {
           var timer = eventDispatched.current[listener];
           if (timer) {
             clearTimeout(timer);
@@ -682,8 +403,8 @@ function useControl(options) {
             eventDispatched.current[listener] = undefined;
           });
           if (listener === 'focus') {
-            var _optionsRef$current6, _optionsRef$current6$;
-            (_optionsRef$current6 = optionsRef.current) === null || _optionsRef$current6 === void 0 || (_optionsRef$current6$ = _optionsRef$current6.onFocus) === null || _optionsRef$current6$ === void 0 || _optionsRef$current6$.call(_optionsRef$current6);
+            var _optionsRef$current4, _optionsRef$current4$;
+            (_optionsRef$current4 = optionsRef.current) === null || _optionsRef$current4 === void 0 || (_optionsRef$current4$ = _optionsRef$current4.onFocus) === null || _optionsRef$current4$ === void 0 || _optionsRef$current4$.call(_optionsRef$current4);
           }
         }
       };
@@ -701,10 +422,62 @@ function useControl(options) {
     };
   }, []);
   return {
-    value: snapshot.value,
-    checked: snapshot.checked,
-    options: snapshot.options,
-    files: snapshot.files,
+    defaultValue,
+    get payload() {
+      if (payloadSnapshot != null && 'parse' in options) {
+        try {
+          return options.parse(payloadSnapshot);
+        } catch (error) {
+          var payloadText = '';
+          try {
+            payloadText = JSON.stringify(payloadSnapshot, null, 2);
+          } catch (_unused) {
+            payloadText = '<unserializable payload>';
+          }
+          throw new Error("Failed to parse the payload. Received ".concat(payloadText, "."), {
+            cause: error
+          });
+        }
+      }
+      return payloadSnapshot;
+    },
+    get value() {
+      if (payloadSnapshot === null) {
+        return '';
+      }
+      if (typeof payloadSnapshot === 'string') {
+        return payloadSnapshot;
+      }
+      return undefined;
+    },
+    get checked() {
+      if (payloadSnapshot === null) {
+        return false;
+      }
+      var value = 'value' in options && options.value ? options.value : 'on';
+      if (payloadSnapshot === value) {
+        return true;
+      }
+      return undefined;
+    },
+    get options() {
+      if (payloadSnapshot === null) {
+        return [];
+      }
+      if (Array.isArray(payloadSnapshot) && payloadSnapshot.every(item => typeof item === 'string')) {
+        return payloadSnapshot;
+      }
+      return undefined;
+    },
+    get files() {
+      if (payloadSnapshot === null) {
+        return [];
+      }
+      if (Array.isArray(payloadSnapshot) && payloadSnapshot.every(item => future.isGlobalInstance(item, 'File'))) {
+        return payloadSnapshot;
+      }
+      return undefined;
+    },
     formRef,
     register: react.useCallback(element => {
       if (!element) {
@@ -718,17 +491,16 @@ function useControl(options) {
           element.hidden = true;
           element.removeAttribute('type');
         }
-        if (shouldHandleFocus) {
-          dom.makeInputFocusable(element);
-        }
         if (element.type === 'checkbox' || element.type === 'radio') {
-          var _optionsRef$current$v, _optionsRef$current7;
           // React set the value as empty string incorrectly when the value is undefined
           // This make sure the checkbox value falls back to the default value "on" properly
-          // @see https://github.com/facebook/react/issues/17590
-          element.value = (_optionsRef$current$v = (_optionsRef$current7 = optionsRef.current) === null || _optionsRef$current7 === void 0 ? void 0 : _optionsRef$current7.value) !== null && _optionsRef$current$v !== void 0 ? _optionsRef$current$v : 'on';
+          // See https://github.com/facebook/react/issues/17590
+          var value = 'value' in optionsRef.current && optionsRef.current.value ? optionsRef.current.value : 'on';
+          element.value = value;
         }
         dom.initializeField(element, optionsRef.current);
+      } else if (element instanceof HTMLFieldSetElement) {
+        inputRef.current = element;
       } else {
         var _inputs$0$name, _inputs$, _inputs$0$type, _inputs$2;
         var inputs = Array.from(element);
@@ -738,39 +510,36 @@ function useControl(options) {
           throw new Error('You can only register a checkbox or radio group with the same name');
         }
         inputRef.current = inputs;
-        for (var input of inputs) {
-          var _optionsRef$current8;
-          if (shouldHandleFocus) {
-            dom.makeInputFocusable(input);
+        if ('defaultValue' in optionsRef.current) {
+          for (var input of inputs) {
+            var _optionsRef$current5;
+            dom.initializeField(input, {
+              // We will not be uitlizing defaultChecked / value on checkbox / radio group
+              defaultValue: (_optionsRef$current5 = optionsRef.current) === null || _optionsRef$current5 === void 0 ? void 0 : _optionsRef$current5.defaultValue
+            });
           }
-          dom.initializeField(input, {
-            // We will not be uitlizing defaultChecked / value on checkbox / radio group
-            defaultValue: (_optionsRef$current8 = optionsRef.current) === null || _optionsRef$current8 === void 0 ? void 0 : _optionsRef$current8.defaultValue
-          });
         }
       }
-    }, [shouldHandleFocus]),
+    }, []),
     change: react.useCallback(value => {
       if (!eventDispatched.current.change) {
-        var _inputRef$current;
-        var element = Array.isArray(inputRef.current) ? (_inputRef$current = inputRef.current) === null || _inputRef$current === void 0 ? void 0 : _inputRef$current.find(input => {
-          var wasChecked = input.checked;
-          var isChecked = Array.isArray(value) ? value.some(item => item === input.value) : input.value === value;
-          switch (input.type) {
-            case 'checkbox':
-              // We assume that only one checkbox can be checked at a time
-              // So we will pick the first element with checked state changed
-              return wasChecked !== isChecked;
-            case 'radio':
-              // We cannot uncheck a radio button
-              // So we will pick the first element that should be checked
-              return isChecked;
-            default:
-              return false;
-          }
-        }) : inputRef.current;
+        var element = inputRef.current;
+        var isFieldset = element instanceof HTMLFieldSetElement;
+        var serializedValue = value == null ? value : 'serialize' in optionsRef.current && optionsRef.current.serialize ? optionsRef.current.serialize(value) : value;
+        if (isFieldset) {
+          // Fieldset mode renders hidden descendant inputs from defaultValue.
+          // Flush this update before dispatching events so listeners see the
+          // latest form structure in the same input/change cycle.
+          reactDom.flushSync(() => {
+            setDefaultValue(serializedValue);
+          });
+        }
         if (element) {
-          future.change(element, typeof value === 'boolean' ? value ? element.value : null : value);
+          future.change(element, serializedValue, {
+            // Sometimes no change is made on the inputs but done through DOM mutation.
+            // But we still want to dispatch the event to notify listeners.
+            forceDispatch: isFieldset
+          });
         }
       }
       if (eventDispatched.current.change) {
@@ -812,8 +581,9 @@ 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,
@@ -823,9 +593,7 @@ function useControl(options) {
  */
 
 function useFormData(formRef, select, options) {
-  var {
-    observer
-  } = react.useContext(GlobalFormOptionsContext);
+  var observer = react.useContext(GlobalFormsObserverContext);
   var valueRef = react.useRef();
   var formDataRef = react.useRef();
   var value = react.useSyncExternalStore(react.useCallback(callback => {
@@ -881,19 +649,154 @@ function useLatest(value) {
   return ref;
 }
 
-exports.FormContextContext = FormContextContext;
-exports.FormOptionsProvider = FormOptionsProvider;
-exports.FormProvider = FormProvider;
-exports.GlobalFormOptionsContext = GlobalFormOptionsContext;
+/**
+ * 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}
+ * />
+ * ```
+ */
+var BaseControl = /*#__PURE__*/react.forwardRef(function BaseControl(props, ref) {
+  function formatValue(value) {
+    var serialized = future.defaultSerialize(value);
+    if (typeof serialized === 'string') {
+      return serialized;
+    }
+
+    // null, undefined, File, or array - fallback to empty string
+    return '';
+  }
+  function renderInput(name, value, form) {
+    if (Array.isArray(value)) {
+      return value.map((item, index) => renderInput("".concat(name, "[").concat(index, "]"), item, form));
+    }
+    if (future.isPlainObject(value)) {
+      return Object.entries(value).map(_ref5 => {
+        var [key, val] = _ref5;
+        return renderInput("".concat(name, ".").concat(key), val, form);
+      });
+    }
+    return /*#__PURE__*/jsxRuntime.jsx("input", {
+      name: name,
+      defaultValue: formatValue(value),
+      form: form
+    }, name);
+  }
+  if (props.type === 'fieldset') {
+    var {
+        name,
+        form,
+        defaultValue: _defaultValue,
+        hidden: _hidden = true
+      } = props,
+      fieldsetProps = _rollupPluginBabelHelpers.objectWithoutProperties(props, _excluded);
+    return /*#__PURE__*/jsxRuntime.jsx("fieldset", _rollupPluginBabelHelpers.objectSpread2(_rollupPluginBabelHelpers.objectSpread2({}, fieldsetProps), {}, {
+      ref: ref,
+      name: name,
+      form: form,
+      hidden: _hidden,
+      children: _defaultValue != null ? renderInput(name, _defaultValue, form) : null
+    }));
+  }
+  if (props.type === 'select') {
+    var {
+        defaultValue: _defaultValue2,
+        multiple = Array.isArray(_defaultValue2),
+        hidden: _hidden2 = true
+      } = props,
+      selectProps = _rollupPluginBabelHelpers.objectWithoutProperties(props, _excluded2);
+    if (multiple) {
+      var defaultOptions = Array.isArray(_defaultValue2) ? _defaultValue2.map(formatValue) : [formatValue(_defaultValue2)];
+      return /*#__PURE__*/jsxRuntime.jsx("select", _rollupPluginBabelHelpers.objectSpread2(_rollupPluginBabelHelpers.objectSpread2({}, selectProps), {}, {
+        ref: ref,
+        defaultValue: defaultOptions,
+        hidden: _hidden2,
+        multiple: true,
+        children: defaultOptions.map((option, index) => /*#__PURE__*/jsxRuntime.jsx("option", {
+          value: option,
+          children: option
+        }, index))
+      }));
+    }
+    var defaultOption = formatValue(_defaultValue2);
+    return /*#__PURE__*/jsxRuntime.jsx("select", _rollupPluginBabelHelpers.objectSpread2(_rollupPluginBabelHelpers.objectSpread2({}, selectProps), {}, {
+      ref: ref,
+      defaultValue: defaultOption,
+      hidden: _hidden2,
+      children: [defaultOption].map((option, index) => /*#__PURE__*/jsxRuntime.jsx("option", {
+        value: option,
+        children: option
+      }, index))
+    }));
+  }
+  if (props.type === 'textarea') {
+    var {
+        defaultValue: _defaultValue3,
+        hidden: _hidden3 = true
+      } = props,
+      textareaProps = _rollupPluginBabelHelpers.objectWithoutProperties(props, _excluded3);
+    return /*#__PURE__*/jsxRuntime.jsx("textarea", _rollupPluginBabelHelpers.objectSpread2(_rollupPluginBabelHelpers.objectSpread2({}, textareaProps), {}, {
+      defaultValue: formatValue(_defaultValue3),
+      ref: ref,
+      hidden: _hidden3
+    }));
+  }
+  if (props.type === 'checkbox' || props.type === 'radio') {
+    var {
+        defaultValue: _defaultValue4 = 'on',
+        value = _defaultValue4,
+        hidden: _hidden4 = true
+      } = props,
+      _inputProps = _rollupPluginBabelHelpers.objectWithoutProperties(props, _excluded4);
+    return /*#__PURE__*/jsxRuntime.jsx("input", _rollupPluginBabelHelpers.objectSpread2(_rollupPluginBabelHelpers.objectSpread2({}, _inputProps), {}, {
+      ref: ref,
+      value: value,
+      hidden: _hidden4
+    }));
+  }
+  var {
+      defaultValue,
+      hidden = true
+    } = props,
+    inputProps = _rollupPluginBabelHelpers.objectWithoutProperties(props, _excluded5);
+  return /*#__PURE__*/jsxRuntime.jsx("input", _rollupPluginBabelHelpers.objectSpread2(_rollupPluginBabelHelpers.objectSpread2({}, inputProps), {}, {
+    ref: ref,
+    defaultValue: defaultValue !== undefined ? formatValue(defaultValue) : undefined,
+    hidden: hidden
+  }));
+});
+
+exports.BaseControl = BaseControl;
+exports.GlobalFormsObserverContext = GlobalFormsObserverContext;
 exports.INITIAL_KEY = INITIAL_KEY;
 exports.PreserveBoundary = PreserveBoundary;
 exports.useConform = useConform;
 exports.useControl = useControl;
-exports.useField = useField;
-exports.useForm = useForm;
-exports.useFormContext = useFormContext;
 exports.useFormData = useFormData;
-exports.useFormMetadata = useFormMetadata;
-exports.useIntent = useIntent;
 exports.useLatest = useLatest;
 exports.useSafeLayoutEffect = useSafeLayoutEffect;