@conform-to/react 1.12.0 → 1.13.0

package/README.md

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

package/dist/future/dom.d.ts

@@ -32,5 +32,5 @@ export declare function updateFormValue(form: HTMLFormElement, intendedValue: Re
  * Creates a proxy that dynamically generates intent dispatch functions.
  * Each property access returns a function that submits the intent to the form.
  */
-export declare function createIntentDispatcher(formElement: HTMLFormElement | (() => HTMLFormElement | null), intentName: string): IntentDispatcher;
+export declare function createIntentDispatcher<FormShape extends Record<string, any>>(formElement: HTMLFormElement | (() => HTMLFormElement | null), intentName: string): IntentDispatcher<FormShape>;
 //# sourceMappingURL=dom.d.ts.map

package/dist/future/dom.js

@@ -176,13 +176,16 @@ function focusFirstInvalidField(ctx) {
 function updateFormValue(form, intendedValue, serialize) {
   for (var element of form.elements) {
     if (future.isFieldElement(element) && element.name) {
-      var value = future.getValueAtPath(intendedValue, element.name);
-      var serializedValue = serialize(value);
-      if (typeof serializedValue !== 'undefined') {
-        future.change(element, serializedValue, {
-          preventDefault: true
-        });
+      var fieldValue = future.getValueAtPath(intendedValue, element.name);
+      if (element.type === 'file' && typeof fieldValue === 'undefined') {
+        // Do not update file inputs unless there's an intended value
+        continue;
       }
+      var serializedValue = serialize(fieldValue);
+      var value = typeof serializedValue !== 'undefined' ? serializedValue : future.getFieldDefaultValue(element);
+      future.change(element, value, {
+        preventDefault: true
+      });
     }
   }
 }

package/dist/future/dom.mjs

@@ -1,4 +1,4 @@
-import { updateField, isGlobalInstance, isFieldElement, requestIntent, getValueAtPath, change } from '@conform-to/dom/future';
+import { updateField, isGlobalInstance, isFieldElement, requestIntent, getValueAtPath, getFieldDefaultValue, change } from '@conform-to/dom/future';
 import { serializeIntent } from './intent.mjs';
 
 function getFormElement(formRef) {
@@ -172,13 +172,16 @@ function focusFirstInvalidField(ctx) {
 function updateFormValue(form, intendedValue, serialize) {
   for (var element of form.elements) {
     if (isFieldElement(element) && element.name) {
-      var value = getValueAtPath(intendedValue, element.name);
-      var serializedValue = serialize(value);
-      if (typeof serializedValue !== 'undefined') {
-        change(element, serializedValue, {
-          preventDefault: true
-        });
+      var fieldValue = getValueAtPath(intendedValue, element.name);
+      if (element.type === 'file' && typeof fieldValue === 'undefined') {
+        // Do not update file inputs unless there's an intended value
+        continue;
       }
+      var serializedValue = serialize(fieldValue);
+      var value = typeof serializedValue !== 'undefined' ? serializedValue : getFieldDefaultValue(element);
+      change(element, value, {
+        preventDefault: true
+      });
     }
   }
 }

package/dist/future/hooks.d.ts

@@ -58,7 +58,7 @@ export declare function useConform<ErrorShape, Value = undefined>(formRef: FormR
 export declare function useForm<FormShape extends Record<string, any> = Record<string, any>, ErrorShape extends BaseErrorShape = DefaultErrorShape, Value = undefined>(options: FormOptions<FormShape, ErrorShape, Value>): {
     form: FormMetadata<ErrorShape>;
     fields: Fieldset<FormShape, ErrorShape>;
-    intent: IntentDispatcher;
+    intent: IntentDispatcher<FormShape>;
 };
 /**
  * A React hook that provides access to form-level metadata and state.
@@ -124,7 +124,7 @@ export declare function useField<FieldShape = any>(name: FieldName<FieldShape>,
  * }
  * ```
  */
-export declare function useIntent(formRef: FormRef): IntentDispatcher;
+export declare function useIntent<FormShape extends Record<string, any>>(formRef: FormRef): IntentDispatcher<FormShape>;
 /**
  * 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
@@ -164,7 +164,7 @@ export declare function useControl(options?: {
  * @see https://conform.guide/api/react/future/useFormData
  * @example
  * ```ts
- * const value = useFormData(formRef, formData => formData?.get('fieldName').toString() ?? '');
+ * const value = useFormData(formRef, formData => formData?.get('fieldName') ?? '');
  * ```
  */
 export declare function useFormData<Value = any>(formRef: FormRef, select: Selector<FormData, Value>, options: UseFormDataOptions & {

package/dist/future/hooks.js

@@ -534,6 +534,16 @@ function useControl(options) {
     observer
   } = react.useContext(GlobalFormOptionsContext);
   var inputRef = react.useRef(null);
+  var formRef = react.useMemo(() => ({
+    get current() {
+      var _input$0$form, _input$;
+      var input = inputRef.current;
+      if (!input) {
+        return null;
+      }
+      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 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);
@@ -598,6 +608,7 @@ function useControl(options) {
     checked: snapshot.checked,
     options: snapshot.options,
     files: snapshot.files,
+    formRef,
     register: react.useCallback(element => {
       if (!element) {
         inputRef.current = null;
@@ -697,7 +708,7 @@ function useControl(options) {
  * @see https://conform.guide/api/react/future/useFormData
  * @example
  * ```ts
- * const value = useFormData(formRef, formData => formData?.get('fieldName').toString() ?? '');
+ * const value = useFormData(formRef, formData => formData?.get('fieldName') ?? '');
  * ```
  */
 

package/dist/future/hooks.mjs

@@ -530,6 +530,16 @@ function useControl(options) {
     observer
   } = useContext(GlobalFormOptionsContext);
   var inputRef = useRef(null);
+  var formRef = useMemo(() => ({
+    get current() {
+      var _input$0$form, _input$;
+      var input = inputRef.current;
+      if (!input) {
+        return null;
+      }
+      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 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);
@@ -594,6 +604,7 @@ function useControl(options) {
     checked: snapshot.checked,
     options: snapshot.options,
     files: snapshot.files,
+    formRef,
     register: useCallback(element => {
       if (!element) {
         inputRef.current = null;
@@ -693,7 +704,7 @@ function useControl(options) {
  * @see https://conform.guide/api/react/future/useFormData
  * @example
  * ```ts
- * const value = useFormData(formRef, formData => formData?.get('fieldName').toString() ?? '');
+ * const value = useFormData(formRef, formData => formData?.get('fieldName') ?? '');
  * ```
  */
 

package/dist/future/intent.js

@@ -92,22 +92,38 @@ function updateListKeys() {
  */
 var actionHandlers = {
   reset: {
-    onApply() {
-      return null;
+    validatePayload(options) {
+      return util.isOptional(options, future.isPlainObject) && (util.isUndefined(options === null || options === void 0 ? void 0 : options.defaultValue) || util.isNullable(options === null || options === void 0 ? void 0 : options.defaultValue, future.isPlainObject));
+    },
+    onApply(_, options) {
+      var {
+        defaultValue
+      } = options !== null && options !== void 0 ? options : {};
+      return defaultValue !== null && defaultValue !== void 0 ? defaultValue : defaultValue === null ? {} : null;
+    },
+    onUpdate(_, _ref) {
+      var _intent$payload;
+      var {
+        intent
+      } = _ref;
+      var defaultValue = (_intent$payload = intent.payload) === null || _intent$payload === void 0 ? void 0 : _intent$payload.defaultValue;
+      return util.merge(state.initializeState(), {
+        serverIntendedValue: defaultValue !== null && defaultValue !== void 0 ? defaultValue : defaultValue === null ? {} : null
+      });
     }
   },
   validate: {
     validatePayload(name) {
       return util.isOptional(name, util.isString);
     },
-    onUpdate(state, _ref) {
-      var _intent$payload;
+    onUpdate(state, _ref2) {
+      var _intent$payload2;
       var {
         submission,
         intent,
         error
-      } = _ref;
-      var name = (_intent$payload = intent.payload) !== null && _intent$payload !== void 0 ? _intent$payload : '';
+      } = _ref2;
+      var name = (_intent$payload2 = intent.payload) !== null && _intent$payload2 !== void 0 ? _intent$payload2 : '';
       var basePath = future.getPathSegments(name);
       var allFields = error ?
       // Consider fields / fieldset with errors as touched too
@@ -129,14 +145,17 @@ var actionHandlers = {
       return future.isPlainObject(options) && util.isOptional(options.name, util.isString) && util.isOptional(options.index, util.isNumber) && !util.isUndefined(options.value);
     },
     onApply(value, options) {
-      return util.updateValueAtPath(value, future.appendPathSegment(options.name, options.index), options.value);
+      var _options$value;
+      var name = future.appendPathSegment(options.name, options.index);
+      var newValue = (_options$value = options.value) !== null && _options$value !== void 0 ? _options$value : name === '' ? {} : null;
+      return util.updateValueAtPath(value, name, newValue);
     },
-    onUpdate(state, _ref2) {
+    onUpdate(state, _ref3) {
       var {
         type,
         submission,
         intent
-      } = _ref2;
+      } = _ref3;
       if (type === 'server') {
         return state;
       }
@@ -172,13 +191,13 @@ var actionHandlers = {
       insertItem(list, options.defaultValue, (_options$index = options.index) !== null && _options$index !== void 0 ? _options$index : list.length);
       return util.updateValueAtPath(value, options.name, list);
     },
-    onUpdate(state$1, _ref3) {
+    onUpdate(state$1, _ref4) {
       var _intent$payload$index;
       var {
         type,
         submission,
         intent
-      } = _ref3;
+      } = _ref4;
       if (type === 'server') {
         return state$1;
       }
@@ -214,12 +233,12 @@ var actionHandlers = {
       removeItem(list, options.index);
       return util.updateValueAtPath(value, options.name, list);
     },
-    onUpdate(state$1, _ref4) {
+    onUpdate(state$1, _ref5) {
       var {
         type,
         submission,
         intent
-      } = _ref4;
+      } = _ref5;
       if (type === 'server') {
         return state$1;
       }
@@ -258,12 +277,12 @@ var actionHandlers = {
       reorderItems(list, options.from, options.to);
       return util.updateValueAtPath(value, options.name, list);
     },
-    onUpdate(state$1, _ref5) {
+    onUpdate(state$1, _ref6) {
       var {
         type,
         submission,
         intent
-      } = _ref5;
+      } = _ref6;
       if (type === 'server') {
         return state$1;
       }

package/dist/future/intent.mjs

@@ -1,7 +1,7 @@
 import { objectSpread2 as _objectSpread2 } from '../_virtual/_rollupPluginBabelHelpers.mjs';
 import { getPathSegments, getRelativePath, isPlainObject, appendPathSegment } from '@conform-to/dom/future';
-import { isOptional, appendUniqueItem, merge, isUndefined, updateValueAtPath, isString, getArrayAtPath, createPathIndexUpdater, compactMap, generateUniqueKey, isNumber, transformKeys } from './util.mjs';
-import { getDefaultListKey } from './state.mjs';
+import { isOptional, isUndefined, isNullable, merge, appendUniqueItem, updateValueAtPath, isString, getArrayAtPath, createPathIndexUpdater, compactMap, generateUniqueKey, isNumber, transformKeys } from './util.mjs';
+import { initializeState, getDefaultListKey } from './state.mjs';
 
 /**
  * Serializes intent to string format: "type" or "type(payload)".
@@ -88,22 +88,38 @@ function updateListKeys() {
  */
 var actionHandlers = {
   reset: {
-    onApply() {
-      return null;
+    validatePayload(options) {
+      return isOptional(options, isPlainObject) && (isUndefined(options === null || options === void 0 ? void 0 : options.defaultValue) || isNullable(options === null || options === void 0 ? void 0 : options.defaultValue, isPlainObject));
+    },
+    onApply(_, options) {
+      var {
+        defaultValue
+      } = options !== null && options !== void 0 ? options : {};
+      return defaultValue !== null && defaultValue !== void 0 ? defaultValue : defaultValue === null ? {} : null;
+    },
+    onUpdate(_, _ref) {
+      var _intent$payload;
+      var {
+        intent
+      } = _ref;
+      var defaultValue = (_intent$payload = intent.payload) === null || _intent$payload === void 0 ? void 0 : _intent$payload.defaultValue;
+      return merge(initializeState(), {
+        serverIntendedValue: defaultValue !== null && defaultValue !== void 0 ? defaultValue : defaultValue === null ? {} : null
+      });
     }
   },
   validate: {
     validatePayload(name) {
       return isOptional(name, isString);
     },
-    onUpdate(state, _ref) {
-      var _intent$payload;
+    onUpdate(state, _ref2) {
+      var _intent$payload2;
       var {
         submission,
         intent,
         error
-      } = _ref;
-      var name = (_intent$payload = intent.payload) !== null && _intent$payload !== void 0 ? _intent$payload : '';
+      } = _ref2;
+      var name = (_intent$payload2 = intent.payload) !== null && _intent$payload2 !== void 0 ? _intent$payload2 : '';
       var basePath = getPathSegments(name);
       var allFields = error ?
       // Consider fields / fieldset with errors as touched too
@@ -125,14 +141,17 @@ var actionHandlers = {
       return isPlainObject(options) && isOptional(options.name, isString) && isOptional(options.index, isNumber) && !isUndefined(options.value);
     },
     onApply(value, options) {
-      return updateValueAtPath(value, appendPathSegment(options.name, options.index), options.value);
+      var _options$value;
+      var name = appendPathSegment(options.name, options.index);
+      var newValue = (_options$value = options.value) !== null && _options$value !== void 0 ? _options$value : name === '' ? {} : null;
+      return updateValueAtPath(value, name, newValue);
     },
-    onUpdate(state, _ref2) {
+    onUpdate(state, _ref3) {
       var {
         type,
         submission,
         intent
-      } = _ref2;
+      } = _ref3;
       if (type === 'server') {
         return state;
       }
@@ -168,13 +187,13 @@ var actionHandlers = {
       insertItem(list, options.defaultValue, (_options$index = options.index) !== null && _options$index !== void 0 ? _options$index : list.length);
       return updateValueAtPath(value, options.name, list);
     },
-    onUpdate(state, _ref3) {
+    onUpdate(state, _ref4) {
       var _intent$payload$index;
       var {
         type,
         submission,
         intent
-      } = _ref3;
+      } = _ref4;
       if (type === 'server') {
         return state;
       }
@@ -210,12 +229,12 @@ var actionHandlers = {
       removeItem(list, options.index);
       return updateValueAtPath(value, options.name, list);
     },
-    onUpdate(state, _ref4) {
+    onUpdate(state, _ref5) {
       var {
         type,
         submission,
         intent
-      } = _ref4;
+      } = _ref5;
       if (type === 'server') {
         return state;
       }
@@ -254,12 +273,12 @@ var actionHandlers = {
       reorderItems(list, options.from, options.to);
       return updateValueAtPath(value, options.name, list);
     },
-    onUpdate(state, _ref5) {
+    onUpdate(state, _ref6) {
       var {
         type,
         submission,
         intent
-      } = _ref5;
+      } = _ref6;
       if (type === 'server') {
         return state;
       }

package/dist/future/state.d.ts

@@ -11,8 +11,8 @@ export declare function updateState<ErrorShape>(state: FormState<ErrorShape>, ac
     handlers: Record<string, ActionHandler>;
     reset: () => FormState<ErrorShape>;
 }>): FormState<ErrorShape>;
-export declare function getDefaultValue(context: FormContext<any>, name: string, serialize?: Serialize): string | undefined;
-export declare function getDefaultOptions(context: FormContext<any>, name: string, serialize?: Serialize): string[] | undefined;
+export declare function getDefaultValue(context: FormContext<any>, name: string, serialize?: Serialize): string;
+export declare function getDefaultOptions(context: FormContext<any>, name: string, serialize?: Serialize): string[];
 export declare function isDefaultChecked(context: FormContext<any>, name: string, serialize?: Serialize): boolean;
 /**
  * Determine if the field is touched

package/dist/future/state.js

@@ -74,6 +74,7 @@ function getDefaultValue(context, name) {
   if (typeof serializedValue === 'string') {
     return serializedValue;
   }
+  return '';
 }
 function getDefaultOptions(context, name) {
   var _ref2, _context$state$server2;
@@ -86,13 +87,17 @@ function getDefaultOptions(context, name) {
   if (typeof serializedValue === 'string') {
     return [serializedValue];
   }
+  return [];
 }
 function isDefaultChecked(context, name) {
   var _ref3, _context$state$server3;
   var serialize = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : future.serialize;
   var value = future.getValueAtPath((_ref3 = (_context$state$server3 = context.state.serverIntendedValue) !== null && _context$state$server3 !== void 0 ? _context$state$server3 : context.state.clientIntendedValue) !== null && _ref3 !== void 0 ? _ref3 : context.defaultValue, name);
   var serializedValue = serialize(value);
-  return serializedValue === 'on';
+  if (typeof serializedValue === 'string') {
+    return serializedValue === 'on';
+  }
+  return false;
 }
 
 /**
@@ -328,15 +333,23 @@ function getField(context, options) {
   if (typeof customize !== 'function') {
     return metadata;
   }
+  var customMetadata = null;
   return new Proxy(metadata, {
     get(target, prop, receiver) {
+      var _customMetadata;
       if (Reflect.has(target, prop)) {
         return Reflect.get(target, prop, receiver);
       }
-      var customMetadata = customize(metadata);
+      (_customMetadata = customMetadata) !== null && _customMetadata !== void 0 ? _customMetadata : customMetadata = customize(metadata);
       if (Reflect.has(customMetadata, prop)) {
         return Reflect.get(customMetadata, prop, receiver);
       }
+
+      // Allow React DevTools to inspect the object
+      // without throwing errors for internal properties
+      if (typeof prop === 'symbol' || prop === '$$typeof') {
+        return undefined;
+      }
       throw new Error("Property \"".concat(String(prop), "\" does not exist on field metadata. ") + "If you have defined the CustomMetadata interface to include \"".concat(String(prop), "\", make sure to also implement it through the \"defineCustomMetadata\" property on <FormOptionsProvider />."));
     }
   });

package/dist/future/state.mjs

@@ -70,6 +70,7 @@ function getDefaultValue(context, name) {
   if (typeof serializedValue === 'string') {
     return serializedValue;
   }
+  return '';
 }
 function getDefaultOptions(context, name) {
   var _ref2, _context$state$server2;
@@ -82,13 +83,17 @@ function getDefaultOptions(context, name) {
   if (typeof serializedValue === 'string') {
     return [serializedValue];
   }
+  return [];
 }
 function isDefaultChecked(context, name) {
   var _ref3, _context$state$server3;
   var serialize$1 = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : serialize;
   var value = getValueAtPath((_ref3 = (_context$state$server3 = context.state.serverIntendedValue) !== null && _context$state$server3 !== void 0 ? _context$state$server3 : context.state.clientIntendedValue) !== null && _ref3 !== void 0 ? _ref3 : context.defaultValue, name);
   var serializedValue = serialize$1(value);
-  return serializedValue === 'on';
+  if (typeof serializedValue === 'string') {
+    return serializedValue === 'on';
+  }
+  return false;
 }
 
 /**
@@ -324,15 +329,23 @@ function getField(context, options) {
   if (typeof customize !== 'function') {
     return metadata;
   }
+  var customMetadata = null;
   return new Proxy(metadata, {
     get(target, prop, receiver) {
+      var _customMetadata;
       if (Reflect.has(target, prop)) {
         return Reflect.get(target, prop, receiver);
       }
-      var customMetadata = customize(metadata);
+      (_customMetadata = customMetadata) !== null && _customMetadata !== void 0 ? _customMetadata : customMetadata = customize(metadata);
       if (Reflect.has(customMetadata, prop)) {
         return Reflect.get(customMetadata, prop, receiver);
       }
+
+      // Allow React DevTools to inspect the object
+      // without throwing errors for internal properties
+      if (typeof prop === 'symbol' || prop === '$$typeof') {
+        return undefined;
+      }
       throw new Error("Property \"".concat(String(prop), "\" does not exist on field metadata. ") + "If you have defined the CustomMetadata interface to include \"".concat(String(prop), "\", make sure to also implement it through the \"defineCustomMetadata\" property on <FormOptionsProvider />."));
     }
   });

package/dist/future/types.d.ts

@@ -36,6 +36,11 @@ export type Control = {
      * Registers the base input element(s). Accepts a single input or an array for groups.
      */
     register: (element: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement | HTMLCollectionOf<HTMLInputElement> | NodeListOf<HTMLInputElement> | null | undefined) => void;
+    /**
+     * A ref object containing the form element associated with the registered input.
+     * Use this with hooks like useFormData() and useIntent().
+     */
+    formRef: React.RefObject<HTMLFormElement | null>;
     /**
      * Programmatically updates the input value and emits
      * both [change](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event) and
@@ -64,9 +69,9 @@ export type UseFormDataOptions = {
      */
     acceptFiles?: boolean;
 };
-export type DefaultValue<FormShape> = FormShape extends Array<infer Item> | null | undefined ? Array<DefaultValue<Item>> | null | undefined : FormShape extends Record<string, any> | null | undefined ? {
-    [Key in keyof FormShape]?: DefaultValue<FormShape[Key]>;
-} | null | undefined : FormShape | string | null | undefined;
+export type DefaultValue<Shape> = Shape extends Record<string, any> ? {
+    [Key in keyof Shape]?: DefaultValue<Shape[Key]>;
+} | null : Shape extends Array<infer Item> ? Array<DefaultValue<Item>> | null : Shape extends File | File[] ? null : Shape | string | null;
 export type FormState<ErrorShape extends BaseErrorShape = DefaultErrorShape> = {
     /** Unique identifier that changes on form reset to trigger reset side effects */
     resetKey: string;
@@ -117,7 +122,7 @@ export type GlobalFormOptions = {
      */
     defineCustomMetadata?: CustomMetadataDefinition;
 };
-export type FormOptions<FormShape, ErrorShape extends BaseErrorShape = string extends BaseErrorShape ? string : BaseErrorShape, Value = undefined> = {
+export type FormOptions<FormShape extends Record<string, any> = Record<string, any>, ErrorShape extends BaseErrorShape = string extends BaseErrorShape ? string : BaseErrorShape, Value = undefined> = {
     /** Optional form identifier. If not provided, a unique ID is automatically generated. */
     id?: string;
     /** Optional key for form state reset. When the key changes, the form resets to its initial state. */
@@ -186,20 +191,39 @@ export type UnknownIntent = {
 export type UnknownArgs<Args extends any[]> = {
     [Key in keyof Args]: unknown;
 };
-export interface IntentDispatcher {
+export interface IntentDispatcher<FormShape extends Record<string, any> = Record<string, any>> {
     /**
      * Validate the whole form or a specific field?
      */
     validate(name?: string): void;
     /**
-     * Reset the form to its initial state.
+     * Reset the form to a specific default value.
+     *
+     * @param options.defaultValue - The value to reset the form to. Pass `null` to clear all fields, or omit to reset to the initial default value from `useForm`.
+     *
+     * @example
+     * ```tsx
+     * // Reset to initial default value
+     * intent.reset()
+     *
+     * // Clear all fields
+     * intent.reset({ defaultValue: null })
+     *
+     * // Restore to a specific snapshot
+     * intent.reset({ defaultValue: snapshotValue })
+     * ```
      */
-    reset(): void;
+    reset(options?: {
+        /**
+         * The value to reset the form to. If not provided, resets to the default value from `useForm`. Pass `null` to clear all fields instead.
+         */
+        defaultValue?: DefaultValue<FormShape>;
+    }): void;
     /**
      * Update a field or a fieldset.
      * If you provide a fieldset name, it will update all fields within that fieldset
      */
-    update<FieldShape>(options: {
+    update<FieldShape = FormShape>(options: {
         /**
          * The name of the field. If you provide a fieldset name, it will update all fields within that fieldset.
          */
@@ -207,11 +231,11 @@ export interface IntentDispatcher {
         /**
          * Specify the index of the item to update if the field is an array.
          */
-        index?: [FieldShape] extends [Array<any> | null | undefined] ? number : never;
+        index?: FieldShape extends Array<any> ? number : unknown extends FieldShape ? number : never;
         /**
          * The new value for the field or fieldset.
          */
-        value: Partial<FieldShape>;
+        value: DefaultValue<FieldShape>;
     }): void;
     /**
      * Insert a new item into an array field.
@@ -229,9 +253,7 @@ export interface IntentDispatcher {
         /**
          * The default value for the new item.
          */
-        defaultValue?: [FieldShape] extends [
-            Array<infer ItemShape> | null | undefined
-        ] ? Partial<ItemShape> : never;
+        defaultValue?: FieldShape extends Array<infer ItemShape> ? DefaultValue<ItemShape> : never;
     }): void;
     /**
      * Remove an item from an array field.
@@ -307,12 +329,28 @@ export type BaseMetadata<FieldShape, ErrorShape extends BaseErrorShape> = Valida
     errorId: string;
     /** The form's unique identifier for associating field via the `form` attribute. */
     formId: string;
-    /** The field's default value as a string. */
-    defaultValue: string | undefined;
-    /** Default selected options for multi-select fields or checkbox group. */
-    defaultOptions: string[] | undefined;
-    /** Default checked state for checkbox/radio inputs. */
-    defaultChecked: boolean | undefined;
+    /**
+     * The field's default value as a string.
+     *
+     * Returns an empty string `''` when:
+     * - No default value is set (field value is `null` or `undefined`)
+     * - The field value cannot be serialized to a string (e.g., objects or arrays)
+     */
+    defaultValue: string;
+    /**
+     * Default selected options for multi-select fields or checkbox group.
+     *
+     * Returns an empty array `[]` when:
+     * - No default options are set (field value is `null` or `undefined`)
+     * - The field value cannot be serialized to a string array (e.g., nested objects or arrays of objects)
+     */
+    defaultOptions: string[];
+    /**
+     * Default checked state for checkbox inputs. Returns `true` if the field value is `'on'`.
+     *
+     * For radio buttons, compare the field's `defaultValue` with the radio button's value attribute instead.
+     */
+    defaultChecked: boolean;
     /** Whether this field has been touched (through intent.validate() or the shouldValidate option). */
     touched: boolean;
     /** Whether this field currently has no validation errors. */

package/dist/future/util.d.ts

@@ -4,6 +4,7 @@ import { ValidateHandler, ValidateResult } from './types';
 export declare function isUndefined(value: unknown): value is undefined;
 export declare function isString(value: unknown): value is string;
 export declare function isNumber(value: unknown): value is number;
+export declare function isNullable<T>(value: unknown, typeGuard: (value: unknown) => value is T): value is T | null;
 export declare function isOptional<T>(value: unknown, typeGuard: (value: unknown) => value is T): value is T | undefined;
 export declare function getArrayAtPath<Type>(formValue: Record<string, Type> | null, name: string): Array<Type>;
 /**

package/dist/future/util.js

@@ -13,6 +13,9 @@ function isString(value) {
 function isNumber(value) {
   return typeof value === 'number';
 }
+function isNullable(value, typeGuard) {
+  return value === null || typeGuard(value);
+}
 function isOptional(value, typeGuard) {
   return isUndefined(value) || typeGuard(value);
 }
@@ -188,6 +191,7 @@ exports.compactMap = compactMap;
 exports.createPathIndexUpdater = createPathIndexUpdater;
 exports.generateUniqueKey = generateUniqueKey;
 exports.getArrayAtPath = getArrayAtPath;
+exports.isNullable = isNullable;
 exports.isNumber = isNumber;
 exports.isOptional = isOptional;
 exports.isString = isString;

package/dist/future/util.mjs

@@ -9,6 +9,9 @@ function isString(value) {
 function isNumber(value) {
   return typeof value === 'number';
 }
+function isNullable(value, typeGuard) {
+  return value === null || typeGuard(value);
+}
 function isOptional(value, typeGuard) {
   return isUndefined(value) || typeGuard(value);
 }
@@ -179,4 +182,4 @@ function generateUniqueKey() {
   return Math.trunc(Date.now() * Math.random()).toString(36);
 }
 
-export { appendUniqueItem, compactMap, createPathIndexUpdater, generateUniqueKey, getArrayAtPath, isNumber, isOptional, isString, isUndefined, merge, normalizeFormError, normalizeValidateResult, resolveStandardSchemaResult, resolveValidateResult, transformKeys, updateValueAtPath };
+export { appendUniqueItem, compactMap, createPathIndexUpdater, generateUniqueKey, getArrayAtPath, isNullable, isNumber, isOptional, isString, isUndefined, merge, normalizeFormError, normalizeValidateResult, resolveStandardSchemaResult, resolveValidateResult, transformKeys, updateValueAtPath };

package/package.json

@@ -3,7 +3,7 @@
   "description": "Conform view adapter for react",
   "homepage": "https://conform.guide",
   "license": "MIT",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -41,7 +41,7 @@
     "url": "https://github.com/edmundhung/conform/issues"
   },
   "dependencies": {
-    "@conform-to/dom": "1.12.0"
+    "@conform-to/dom": "1.13.0"
   },
   "devDependencies": {
     "@babel/core": "^7.17.8",
@@ -56,7 +56,8 @@
     "react-dom": "^18.2.0",
     "rollup-plugin-copy": "^3.4.0",
     "rollup": "^2.79.1",
-    "vitest-browser-react": "^0.3.0"
+    "typescript": "^5.8.3",
+    "vitest-browser-react": "^1.0.1"
   },
   "peerDependencies": {
     "react": ">=18"