@conform-to/react 1.17.1 → 1.19.0

package/dist/future/hooks.mjs

@@ -1,45 +1,27 @@
 'use client';
 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, 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 { createGlobalFormsObserver, isGlobalInstance, deepEqual, isFieldElement, change, focus, blur, getFormData, defaultSerialize, isPlainObject, normalizeFormError, dispatchInternalUpdateEvent, parseSubmission, report, requestSubmit } from '@conform-to/dom/future';
+import { createContext, useRef, useContext, useMemo, useState, useEffect, useSyncExternalStore, useCallback, useLayoutEffect, forwardRef } from 'react';
+import { appendUniqueItem, resolveValidateResult } from './util.mjs';
+import { initializeState, updateState } from './state.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 { cleanupPreservedInputs, preserveInputs, deriveDefaultPayload, resolveControlPayload, initializeField, getFormElement, resetFormValue, updateFormValue, getSubmitEvent } from './dom.mjs';
+import { flushSync } from 'react-dom';
 import { jsx } from '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__*/createContext({
-  intentName: DEFAULT_INTENT_NAME,
-  observer: createGlobalFormsObserver(),
-  serialize,
-  shouldValidate: 'onSubmit'
-});
-var FormContextContext = /*#__PURE__*/createContext([]);
-
-/**
- * Provides form context to child components.
- * Stacks contexts to support nested forms, with latest context taking priority.
- */
-function FormProvider(props) {
-  var stack = useContext(FormContextContext);
-  var value = 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__*/jsx(FormContextContext.Provider, {
-    value: value,
-    children: props.children
-  });
-}
+var GlobalFormsObserverContext = /*#__PURE__*/createContext(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
@@ -76,30 +58,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 = _objectWithoutProperties(props, _excluded);
-  var defaultOptions = useContext(GlobalFormOptionsContext);
-  var options = useMemo(() => _objectSpread2(_objectSpread2({}, defaultOptions), providedOptions), [defaultOptions, providedOptions]);
-  return /*#__PURE__*/jsx(GlobalFormOptionsContext.Provider, {
-    value: options,
-    children: children
-  });
-}
-function useFormContext(formId) {
-  var contexts = 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.
@@ -142,16 +100,23 @@ function useConform(formRef, options) {
   var abortControllerRef = useRef(null);
   var handleSubmission = useCallback(function (type, result) {
     var options = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : optionsRef.current;
+    var normalizedResult = !result.error ? result : _objectSpread2(_objectSpread2({}, result), {}, {
+      error: normalizeFormError(result.error)
+    });
     var intent = result.submission.intent ? deserializeIntent(result.submission.intent) : null;
-    var finalResult = applyIntent(result, intent, {
+    var finalResult = applyIntent(normalizedResult, intent, {
       handlers: intentHandlers
     });
+    var formElement = getFormElement(formRef);
+    if (formElement && (finalResult.reset || typeof finalResult.targetValue !== 'undefined')) {
+      dispatchInternalUpdateEvent(formElement);
+    }
     setState(state => updateState(state, _objectSpread2(_objectSpread2({}, finalResult), {}, {
       type,
       intent,
       ctx: {
         handlers: intentHandlers,
-        cancelled: finalResult !== result,
+        cancelled: finalResult !== normalizedResult,
         reset(defaultValue) {
           return initializeState({
             defaultValue: defaultValue !== null && defaultValue !== void 0 ? defaultValue : options.defaultValue
@@ -161,12 +126,11 @@ function useConform(formRef, options) {
     })));
 
     // TODO: move on error handler to a new effect
-    var formElement = 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
       });
     }
@@ -174,6 +138,10 @@ function useConform(formRef, options) {
   }, [formRef, optionsRef]);
   if (options.key !== keyRef.current) {
     keyRef.current = options.key;
+    var formElement = getFormElement(formRef);
+    if (formElement) {
+      dispatchInternalUpdateEvent(formElement);
+    }
     setState(initializeState({
       defaultValue: options.defaultValue
     }));
@@ -200,52 +168,56 @@ function useConform(formRef, options) {
   }, [formRef, state.resetKey, state.defaultValue, optionsRef]);
   useSafeLayoutEffect(() => {
     if (state.targetValue) {
-      var formElement = getFormElement(formRef);
-      if (!formElement) {
+      var _formElement = getFormElement(formRef);
+      if (!_formElement) {
         // eslint-disable-next-line no-console
         console.error('Failed to update form value; No form element found');
         return;
       }
-      updateFormValue(formElement, state.targetValue, optionsRef.current.serialize);
+      updateFormValue(_formElement, state.targetValue, optionsRef.current.serialize);
     }
     pendingValueRef.current = undefined;
   }, [formRef, state.targetValue, optionsRef]);
   var handleSubmit = 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 = getSubmitEvent(event);
+    var formData = getFormData(formElement, submitEvent.submitter);
+    var submission = 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 = getSubmitEvent(event);
-      formData = getFormData(formElement, submitEvent.submitter);
-      var submission = parseSubmission(formData, {
-        intentName: optionsRef.current.intentName
-      });
-
-      // Patch missing fields in the submission object
-      for (var element of formElement.elements) {
-        if (isFieldElement(element) && element.name) {
-          submission.fields = appendUniqueItem(submission.fields, element.name);
-        }
+    // Patch missing fields in the submission object
+    for (var element of formElement.elements) {
+      if (isFieldElement(element) && element.name) {
+        submission.fields = 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
+    deepEqual(submission.payload, lastAsyncResult.result.submission.payload)) {
+      result = lastAsyncResult.result;
+      resolvedValue = lastAsyncResult.resolvedValue;
+    } else {
+      var _optionsRef$current$o2, _optionsRef$current2;
       var value = resolveIntent(submission);
       var submissionResult = report(submission, {
         keepFiles: true,
@@ -256,7 +228,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 ? deserializeIntent(submission.intent) : null,
@@ -290,16 +262,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 = 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
+                };
+                requestSubmit(formElement, submitEvent.submitter);
+              }, 0);
             }
           }
         });
@@ -345,287 +321,20 @@ function useConform(formRef, options) {
   return [state, 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 = useContext(GlobalFormOptionsContext);
-  var optionsRef = useLatest(options);
-  var globalOptionsRef = useLatest(globalOptions);
-  var fallbackId = useId();
-  var formId = id !== null && id !== void 0 ? id : "form-".concat(fallbackId);
-  var [state, handleSubmit] = useConform(formId, _objectSpread2(_objectSpread2({}, options), {}, {
-    serialize: globalOptions.serialize,
-    intentName: globalOptions.intentName,
-    onError: (_options$onError = options.onError) !== null && _options$onError !== void 0 ? _options$onError : 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 resolveStandardSchemaResult(actualStandardResult);
-          });
-        }
-        var resolvedResult = 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 = 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 = useMemo(() => ({
-    formId,
-    state,
-    constraint: constraint !== null && constraint !== void 0 ? constraint : null,
-    handleSubmit,
-    handleInput(event) {
-      var _optionsRef$current$o4, _optionsRef$current4, _globalOptionsRef$cur;
-      if (!isFieldElement(event.target) || event.target.name === '' || event.target.form === null || event.target.form !== getFormElement(formId)) {
-        return;
-      }
-      (_optionsRef$current$o4 = (_optionsRef$current4 = optionsRef.current).onInput) === null || _optionsRef$current$o4 === void 0 || _optionsRef$current$o4.call(_optionsRef$current4, _objectSpread2(_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 (isTouched(state, event.target.name) ? shouldRevalidate === 'onInput' : shouldValidate === 'onInput') {
-        intent.validate(event.target.name);
-      }
-    },
-    handleBlur(event) {
-      var _optionsRef$current$o5, _optionsRef$current5, _globalOptionsRef$cur2;
-      if (!isFieldElement(event.target) || event.target.name === '' || event.target.form === null || event.target.form !== getFormElement(formId)) {
-        return;
-      }
-      (_optionsRef$current$o5 = (_optionsRef$current5 = optionsRef.current).onBlur) === null || _optionsRef$current$o5 === void 0 || _optionsRef$current$o5.call(_optionsRef$current5, _objectSpread2(_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 (isTouched(state, event.target.name) ? shouldRevalidate === 'onBlur' : shouldValidate === 'onBlur') {
-        intent.validate(event.target.name);
-      }
-    }
-  }), [formId, state, constraint, handleSubmit, intent, optionsRef, globalOptionsRef]);
-  var form = useMemo(() => getFormMetadata(context, {
-    serialize: globalOptions.serialize,
-    extendFieldMetadata: globalOptions.defineCustomMetadata
-  }), [context, globalOptions.serialize, globalOptions.defineCustomMetadata]);
-  var fields = useMemo(() => 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 = useContext(GlobalFormOptionsContext);
-  var context = useFormContext(options.formId);
-  var formMetadata = useMemo(() => 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 = useContext(GlobalFormOptionsContext);
-  var context = useFormContext(options.formId);
-  var field = useMemo(() => 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 = useContext(GlobalFormOptionsContext);
-  return useMemo(() => createIntentDispatcher(() => 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
-  } = useContext(GlobalFormOptionsContext);
+
+function useControl() {
+  var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  var observer = useContext(GlobalFormsObserverContext);
   var inputRef = useRef(null);
   var formRef = useMemo(() => ({
     get current() {
@@ -637,29 +346,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] = useState(() => deriveDefaultPayload(options));
+  var pendingDefaultValueSyncRef = 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 && isGlobalInstance(inputRef.current, 'HTMLFieldSetElement')) {
+    pendingDefaultValueSyncRef.current = false;
+    setDefaultValue(() => deriveDefaultPayload(options));
+  }
   var eventDispatched = useRef({});
-  var defaultSnapshot = 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 = useRef(defaultSnapshot);
+  var snapshotRef = useRef(defaultValue);
   var optionsRef = useRef(options);
   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 = useSyncExternalStore(useCallback(callback => observer.onFieldUpdate(event => {
+  useEffect(() => observer.onInternalUpdate(event => {
+    var input = inputRef.current;
+    if (input && input instanceof HTMLFieldSetElement && event.target === input.form) {
+      pendingDefaultValueSyncRef.current = true;
+    }
+  }), [observer]);
+  var payloadSnapshot = useSyncExternalStore(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: getRadioGroupValue(input),
-      options: getCheckboxGroupValue(input)
-    } : getInputSnapshot(input);
+    var next = input ? resolveControlPayload(input) : defaultValue;
     if (deepEqual(prev, next)) {
       return prev;
     }
@@ -669,7 +389,8 @@ function useControl(options) {
   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);
@@ -678,8 +399,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);
           }
         }
       };
@@ -697,10 +418,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 => isGlobalInstance(item, 'File'))) {
+        return payloadSnapshot;
+      }
+      return undefined;
+    },
     formRef,
     register: useCallback(element => {
       if (!element) {
@@ -714,17 +487,16 @@ function useControl(options) {
           element.hidden = true;
           element.removeAttribute('type');
         }
-        if (shouldHandleFocus) {
-          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;
         }
         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);
@@ -734,39 +506,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) {
-            makeInputFocusable(input);
+        if ('defaultValue' in optionsRef.current) {
+          for (var input of inputs) {
+            var _optionsRef$current5;
+            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
+            });
           }
-          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: 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.
+          flushSync(() => {
+            setDefaultValue(serializedValue);
+          });
+        }
         if (element) {
-          change(element, typeof value === 'boolean' ? value ? element.value : null : value);
+          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) {
@@ -808,8 +577,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,
@@ -819,9 +589,7 @@ function useControl(options) {
  */
 
 function useFormData(formRef, select, options) {
-  var {
-    observer
-  } = useContext(GlobalFormOptionsContext);
+  var observer = useContext(GlobalFormsObserverContext);
   var valueRef = useRef();
   var formDataRef = useRef();
   var value = useSyncExternalStore(useCallback(callback => {
@@ -877,4 +645,146 @@ function useLatest(value) {
   return ref;
 }
 
-export { FormContextContext, FormOptionsProvider, FormProvider, GlobalFormOptionsContext, INITIAL_KEY, PreserveBoundary, useConform, useControl, useField, useForm, useFormContext, useFormData, useFormMetadata, useIntent, useLatest, useSafeLayoutEffect };
+/**
+ * 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__*/forwardRef(function BaseControl(props, ref) {
+  function formatValue(value) {
+    var serialized = 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 (isPlainObject(value)) {
+      return Object.entries(value).map(_ref5 => {
+        var [key, val] = _ref5;
+        return renderInput("".concat(name, ".").concat(key), val, form);
+      });
+    }
+    return /*#__PURE__*/jsx("input", {
+      name: name,
+      defaultValue: formatValue(value),
+      form: form
+    }, name);
+  }
+  if (props.type === 'fieldset') {
+    var {
+        name,
+        form,
+        defaultValue: _defaultValue,
+        hidden: _hidden = true
+      } = props,
+      fieldsetProps = _objectWithoutProperties(props, _excluded);
+    return /*#__PURE__*/jsx("fieldset", _objectSpread2(_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 = _objectWithoutProperties(props, _excluded2);
+    if (multiple) {
+      var defaultOptions = Array.isArray(_defaultValue2) ? _defaultValue2.map(formatValue) : [formatValue(_defaultValue2)];
+      return /*#__PURE__*/jsx("select", _objectSpread2(_objectSpread2({}, selectProps), {}, {
+        ref: ref,
+        defaultValue: defaultOptions,
+        hidden: _hidden2,
+        multiple: true,
+        children: defaultOptions.map((option, index) => /*#__PURE__*/jsx("option", {
+          value: option,
+          children: option
+        }, index))
+      }));
+    }
+    var defaultOption = formatValue(_defaultValue2);
+    return /*#__PURE__*/jsx("select", _objectSpread2(_objectSpread2({}, selectProps), {}, {
+      ref: ref,
+      defaultValue: defaultOption,
+      hidden: _hidden2,
+      children: [defaultOption].map((option, index) => /*#__PURE__*/jsx("option", {
+        value: option,
+        children: option
+      }, index))
+    }));
+  }
+  if (props.type === 'textarea') {
+    var {
+        defaultValue: _defaultValue3,
+        hidden: _hidden3 = true
+      } = props,
+      textareaProps = _objectWithoutProperties(props, _excluded3);
+    return /*#__PURE__*/jsx("textarea", _objectSpread2(_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 = _objectWithoutProperties(props, _excluded4);
+    return /*#__PURE__*/jsx("input", _objectSpread2(_objectSpread2({}, _inputProps), {}, {
+      ref: ref,
+      value: value,
+      hidden: _hidden4
+    }));
+  }
+  var {
+      defaultValue,
+      hidden = true
+    } = props,
+    inputProps = _objectWithoutProperties(props, _excluded5);
+  return /*#__PURE__*/jsx("input", _objectSpread2(_objectSpread2({}, inputProps), {}, {
+    ref: ref,
+    defaultValue: defaultValue !== undefined ? formatValue(defaultValue) : undefined,
+    hidden: hidden
+  }));
+});
+
+export { BaseControl, GlobalFormsObserverContext, INITIAL_KEY, PreserveBoundary, useConform, useControl, useFormData, useLatest, useSafeLayoutEffect };