@conform-to/dom 1.8.1 → 1.9.0

package/dist/form.js

@@ -37,13 +37,13 @@ function createFormMeta(options, isResetting) {
   return result;
 }
 function getDefaultKey(defaultValue, prefix) {
-  return Object.entries(formdata.flatten(defaultValue, {
+  return Object.entries(submission.flatten(defaultValue, {
     prefix
   })).reduce((result, _ref2) => {
     var [key, value] = _ref2;
     if (Array.isArray(value)) {
       for (var i = 0; i < value.length; i++) {
-        result[formdata.formatName(key, i)] = util.generateId();
+        result[formdata.appendPathSegment(key, i)] = util.generateId();
       }
     }
     return result;
@@ -76,7 +76,7 @@ function handleIntent(meta, intent, fields, initialized) {
           validated,
           value
         } = intent.payload;
-        var _name2 = formdata.formatName(intent.payload.name, intent.payload.index);
+        var _name2 = formdata.appendPathSegment(intent.payload.name, intent.payload.index);
         if (typeof value !== 'undefined') {
           updateValue(meta, _name2 !== null && _name2 !== void 0 ? _name2 : '', value);
         }
@@ -88,8 +88,8 @@ function handleIntent(meta, intent, fields, initialized) {
             meta.validated = {};
           }
           if (validated) {
-            if (formdata.isPlainObject(value) || Array.isArray(value)) {
-              Object.assign(meta.validated, formdata.flatten(value, {
+            if (util.isPlainObject(value) || Array.isArray(value)) {
+              Object.assign(meta.validated, submission.flatten(value, {
                 resolve() {
                   return true;
                 },
@@ -105,8 +105,8 @@ function handleIntent(meta, intent, fields, initialized) {
       }
     case 'reset':
       {
-        var _name3 = formdata.formatName(intent.payload.name, intent.payload.index);
-        var _value = formdata.getValue(meta.defaultValue, _name3);
+        var _name3 = formdata.appendPathSegment(intent.payload.name, intent.payload.index);
+        var _value = formdata.getValueAtPath(meta.defaultValue, _name3);
         updateValue(meta, _name3, _value);
         if (_name3) {
           submission.setState(meta.validated, _name3, () => undefined);
@@ -124,7 +124,7 @@ function handleIntent(meta, intent, fields, initialized) {
           meta.initialValue = util.clone(meta.initialValue);
           meta.key = util.clone(meta.key);
           submission.setListState(meta.key, intent, defaultValue => {
-            if (!Array.isArray(defaultValue) && !formdata.isPlainObject(defaultValue)) {
+            if (!Array.isArray(defaultValue) && !util.isPlainObject(defaultValue)) {
               return util.generateId();
             }
             return Object.assign(getDefaultKey(defaultValue), {
@@ -159,9 +159,9 @@ function updateValue(meta, name, value) {
   meta.initialValue = util.clone(meta.initialValue);
   meta.value = util.clone(meta.value);
   meta.key = util.clone(meta.key);
-  formdata.setValue(meta.initialValue, name, () => value);
-  formdata.setValue(meta.value, name, () => value);
-  if (formdata.isPlainObject(value) || Array.isArray(value)) {
+  formdata.setValueAtPath(meta.initialValue, name, () => value);
+  formdata.setValueAtPath(meta.value, name, () => value);
+  if (util.isPlainObject(value) || Array.isArray(value)) {
     submission.setState(meta.key, name, () => undefined);
     Object.assign(meta.key, getDefaultKey(value, name));
   }
@@ -180,16 +180,16 @@ function createStateProxy(fn) {
   });
 }
 function createValueProxy(value) {
-  var val = formdata.normalize(value);
+  var val = submission.normalize(value);
   return createStateProxy((name, proxy) => {
     if (name === '') {
       return val;
     }
-    var paths = formdata.getPaths(name);
-    var basename = formdata.formatPaths(paths.slice(0, -1));
-    var key = formdata.formatPaths(paths.slice(-1));
+    var path = formdata.getPathSegments(name);
+    var basename = formdata.formatPathSegments(path.slice(0, -1));
+    var key = formdata.formatPathSegments(path.slice(-1));
     var parentValue = proxy[basename];
-    return formdata.getValue(parentValue, key);
+    return formdata.getValueAtPath(parentValue, key);
   });
 }
 function createConstraintProxy(constraint) {
@@ -197,15 +197,20 @@ function createConstraintProxy(constraint) {
     var _result;
     var result = constraint[name];
     if (!result) {
-      var paths = formdata.getPaths(name);
-      for (var i = paths.length - 1; i >= 0; i--) {
-        var path = paths[i];
-        if (typeof path === 'number' && !Number.isNaN(path)) {
-          paths[i] = Number.NaN;
+      var path = formdata.getPathSegments(name);
+      for (var i = path.length - 1; i >= 0; i--) {
+        var segment = path[i];
+
+        // Try searching a less specific path for the constraint
+        // e.g. `array[0].anotherArray[1].key` -> `array[0].anotherArray[].key` -> `array[].anotherArray[].key`
+        if (typeof segment === 'number') {
+          // This overrides the current number segment with an empty string
+          // which will be treated as an empty bracket
+          path[i] = '';
           break;
         }
       }
-      var alternative = formdata.formatPaths(paths);
+      var alternative = formdata.formatPathSegments(path);
       if (name !== alternative) {
         result = proxy[alternative];
       }
@@ -216,15 +221,15 @@ function createConstraintProxy(constraint) {
 function createKeyProxy(key) {
   return createStateProxy((name, proxy) => {
     var currentKey = key[name];
-    var paths = formdata.getPaths(name);
-    if (paths.length === 0) {
+    var segments = formdata.getPathSegments(name);
+    if (segments.length === 0) {
       return currentKey;
     }
-    var parentKey = proxy[formdata.formatPaths(paths.slice(0, -1))];
+    var parentKey = proxy[formdata.formatPathSegments(segments.slice(0, -1))];
     if (typeof parentKey === 'undefined') {
       return currentKey;
     }
-    return "".concat(parentKey, "/").concat(currentKey !== null && currentKey !== void 0 ? currentKey : paths.at(-1));
+    return "".concat(parentKey, "/").concat(currentKey !== null && currentKey !== void 0 ? currentKey : segments.at(-1));
   });
 }
 function createValidProxy(error) {
@@ -575,19 +580,22 @@ function createFormContext(options) {
       switch (intent.type) {
         case 'update':
           {
-            var _name5 = formdata.formatName(intent.payload.name, intent.payload.index);
-            var parentPaths = formdata.getPaths(_name5);
+            var _name5 = formdata.appendPathSegment(intent.payload.name, intent.payload.index);
+            var baseSegments = formdata.getPathSegments(_name5);
             for (var element of formElement.elements) {
               if (dom.isFieldElement(element)) {
-                var paths = formdata.getChildPaths(parentPaths, element.name);
+                var paths = formdata.getRelativePath(element.name, baseSegments);
                 if (paths) {
-                  var value = formdata.getValue(intent.payload.value, formdata.formatPaths(paths));
-                  dom.updateField(element, {
-                    value: typeof value === 'string' || Array.isArray(value) && value.every(item => typeof item === 'string') ? value : null
-                  });
+                  var value = formdata.getValueAtPath(intent.payload.value, paths);
+                  var inputValue = typeof value === 'string' || Array.isArray(value) && value.every(item => typeof item === 'string') ? value : undefined;
+                  if (typeof inputValue !== 'undefined' || _name5 === '' && paths.length > 1) {
+                    dom.updateField(element, {
+                      value: inputValue !== null && inputValue !== void 0 ? inputValue : null
+                    });
 
-                  // Update the element attribute to notify useControl / useInputControl hook
-                  element.dataset.conform = util.generateId();
+                    // Update the element attribute to notify useControl / useInputControl hook
+                    element.dataset.conform = util.generateId();
+                  }
                 }
               }
             }
@@ -595,14 +603,17 @@ function createFormContext(options) {
           }
         case 'reset':
           {
-            var prefix = formdata.formatName(intent.payload.name, intent.payload.index);
+            var prefix = formdata.appendPathSegment(intent.payload.name, intent.payload.index);
             for (var _element of formElement.elements) {
               if (dom.isFieldElement(_element) && _element.name && formdata.isPrefix(_element.name, prefix)) {
-                var _value2 = formdata.getValue(meta.defaultValue, _element.name);
-                var defaultValue = typeof _value2 === 'string' || Array.isArray(_value2) && _value2.every(item => typeof item === 'string') ? _value2 : null;
+                var _value2 = formdata.getValueAtPath(meta.defaultValue, _element.name);
+                var defaultValue = typeof _value2 === 'string' || Array.isArray(_value2) && _value2.every(item => typeof item === 'string') ? _value2 : undefined;
+                if (typeof defaultValue === 'undefined' && !_element.dataset.conform && 'defaultValue' in _element && !dom.isDirtyInput(_element)) {
+                  continue;
+                }
                 dom.updateField(_element, {
-                  defaultValue,
-                  value: defaultValue
+                  defaultValue: defaultValue,
+                  value: defaultValue !== null && defaultValue !== void 0 ? defaultValue : null
                 });
 
                 // Update the element attribute to notify useControl / useInputControl hook

package/dist/form.mjs

@@ -1,8 +1,8 @@
 import { objectSpread2 as _objectSpread2 } from './_virtual/_rollupPluginBabelHelpers.mjs';
-import { flatten, formatName, getValue, isPlainObject, isPrefix, setValue, normalize, getFormData, getPaths, getChildPaths, formatPaths } from './formdata.mjs';
-import { getFormAction, getFormEncType, getFormMethod, isFieldElement, requestSubmit, updateField } from './dom.mjs';
-import { generateId, clone, invariant } from './util.mjs';
-import { serialize, setListState, setListValue, setState, INTENT, serializeIntent, root, getSubmissionContext } from './submission.mjs';
+import { appendPathSegment, getValueAtPath, isPrefix, setValueAtPath, getFormData, getPathSegments, getRelativePath, formatPathSegments } from './formdata.mjs';
+import { getFormAction, getFormEncType, getFormMethod, isFieldElement, requestSubmit, isDirtyInput, updateField } from './dom.mjs';
+import { generateId, clone, isPlainObject, invariant } from './util.mjs';
+import { serialize, flatten, setListState, setListValue, setState, normalize, INTENT, serializeIntent, root, getSubmissionContext } from './submission.mjs';
 
 function createFormMeta(options, isResetting) {
   var _lastResult$initialVa, _options$constraint, _lastResult$state$val, _lastResult$state, _ref;
@@ -39,7 +39,7 @@ function getDefaultKey(defaultValue, prefix) {
     var [key, value] = _ref2;
     if (Array.isArray(value)) {
       for (var i = 0; i < value.length; i++) {
-        result[formatName(key, i)] = generateId();
+        result[appendPathSegment(key, i)] = generateId();
       }
     }
     return result;
@@ -72,7 +72,7 @@ function handleIntent(meta, intent, fields, initialized) {
           validated,
           value
         } = intent.payload;
-        var _name2 = formatName(intent.payload.name, intent.payload.index);
+        var _name2 = appendPathSegment(intent.payload.name, intent.payload.index);
         if (typeof value !== 'undefined') {
           updateValue(meta, _name2 !== null && _name2 !== void 0 ? _name2 : '', value);
         }
@@ -101,8 +101,8 @@ function handleIntent(meta, intent, fields, initialized) {
       }
     case 'reset':
       {
-        var _name3 = formatName(intent.payload.name, intent.payload.index);
-        var _value = getValue(meta.defaultValue, _name3);
+        var _name3 = appendPathSegment(intent.payload.name, intent.payload.index);
+        var _value = getValueAtPath(meta.defaultValue, _name3);
         updateValue(meta, _name3, _value);
         if (_name3) {
           setState(meta.validated, _name3, () => undefined);
@@ -155,8 +155,8 @@ function updateValue(meta, name, value) {
   meta.initialValue = clone(meta.initialValue);
   meta.value = clone(meta.value);
   meta.key = clone(meta.key);
-  setValue(meta.initialValue, name, () => value);
-  setValue(meta.value, name, () => value);
+  setValueAtPath(meta.initialValue, name, () => value);
+  setValueAtPath(meta.value, name, () => value);
   if (isPlainObject(value) || Array.isArray(value)) {
     setState(meta.key, name, () => undefined);
     Object.assign(meta.key, getDefaultKey(value, name));
@@ -181,11 +181,11 @@ function createValueProxy(value) {
     if (name === '') {
       return val;
     }
-    var paths = getPaths(name);
-    var basename = formatPaths(paths.slice(0, -1));
-    var key = formatPaths(paths.slice(-1));
+    var path = getPathSegments(name);
+    var basename = formatPathSegments(path.slice(0, -1));
+    var key = formatPathSegments(path.slice(-1));
     var parentValue = proxy[basename];
-    return getValue(parentValue, key);
+    return getValueAtPath(parentValue, key);
   });
 }
 function createConstraintProxy(constraint) {
@@ -193,15 +193,20 @@ function createConstraintProxy(constraint) {
     var _result;
     var result = constraint[name];
     if (!result) {
-      var paths = getPaths(name);
-      for (var i = paths.length - 1; i >= 0; i--) {
-        var path = paths[i];
-        if (typeof path === 'number' && !Number.isNaN(path)) {
-          paths[i] = Number.NaN;
+      var path = getPathSegments(name);
+      for (var i = path.length - 1; i >= 0; i--) {
+        var segment = path[i];
+
+        // Try searching a less specific path for the constraint
+        // e.g. `array[0].anotherArray[1].key` -> `array[0].anotherArray[].key` -> `array[].anotherArray[].key`
+        if (typeof segment === 'number') {
+          // This overrides the current number segment with an empty string
+          // which will be treated as an empty bracket
+          path[i] = '';
           break;
         }
       }
-      var alternative = formatPaths(paths);
+      var alternative = formatPathSegments(path);
       if (name !== alternative) {
         result = proxy[alternative];
       }
@@ -212,15 +217,15 @@ function createConstraintProxy(constraint) {
 function createKeyProxy(key) {
   return createStateProxy((name, proxy) => {
     var currentKey = key[name];
-    var paths = getPaths(name);
-    if (paths.length === 0) {
+    var segments = getPathSegments(name);
+    if (segments.length === 0) {
       return currentKey;
     }
-    var parentKey = proxy[formatPaths(paths.slice(0, -1))];
+    var parentKey = proxy[formatPathSegments(segments.slice(0, -1))];
     if (typeof parentKey === 'undefined') {
       return currentKey;
     }
-    return "".concat(parentKey, "/").concat(currentKey !== null && currentKey !== void 0 ? currentKey : paths.at(-1));
+    return "".concat(parentKey, "/").concat(currentKey !== null && currentKey !== void 0 ? currentKey : segments.at(-1));
   });
 }
 function createValidProxy(error) {
@@ -571,19 +576,22 @@ function createFormContext(options) {
       switch (intent.type) {
         case 'update':
           {
-            var _name5 = formatName(intent.payload.name, intent.payload.index);
-            var parentPaths = getPaths(_name5);
+            var _name5 = appendPathSegment(intent.payload.name, intent.payload.index);
+            var baseSegments = getPathSegments(_name5);
             for (var element of formElement.elements) {
               if (isFieldElement(element)) {
-                var paths = getChildPaths(parentPaths, element.name);
+                var paths = getRelativePath(element.name, baseSegments);
                 if (paths) {
-                  var value = getValue(intent.payload.value, formatPaths(paths));
-                  updateField(element, {
-                    value: typeof value === 'string' || Array.isArray(value) && value.every(item => typeof item === 'string') ? value : null
-                  });
+                  var value = getValueAtPath(intent.payload.value, paths);
+                  var inputValue = typeof value === 'string' || Array.isArray(value) && value.every(item => typeof item === 'string') ? value : undefined;
+                  if (typeof inputValue !== 'undefined' || _name5 === '' && paths.length > 1) {
+                    updateField(element, {
+                      value: inputValue !== null && inputValue !== void 0 ? inputValue : null
+                    });
 
-                  // Update the element attribute to notify useControl / useInputControl hook
-                  element.dataset.conform = generateId();
+                    // Update the element attribute to notify useControl / useInputControl hook
+                    element.dataset.conform = generateId();
+                  }
                 }
               }
             }
@@ -591,14 +599,17 @@ function createFormContext(options) {
           }
         case 'reset':
           {
-            var prefix = formatName(intent.payload.name, intent.payload.index);
+            var prefix = appendPathSegment(intent.payload.name, intent.payload.index);
             for (var _element of formElement.elements) {
               if (isFieldElement(_element) && _element.name && isPrefix(_element.name, prefix)) {
-                var _value2 = getValue(meta.defaultValue, _element.name);
-                var defaultValue = typeof _value2 === 'string' || Array.isArray(_value2) && _value2.every(item => typeof item === 'string') ? _value2 : null;
+                var _value2 = getValueAtPath(meta.defaultValue, _element.name);
+                var defaultValue = typeof _value2 === 'string' || Array.isArray(_value2) && _value2.every(item => typeof item === 'string') ? _value2 : undefined;
+                if (typeof defaultValue === 'undefined' && !_element.dataset.conform && 'defaultValue' in _element && !isDirtyInput(_element)) {
+                  continue;
+                }
                 updateField(_element, {
-                  defaultValue,
-                  value: defaultValue
+                  defaultValue: defaultValue,
+                  value: defaultValue !== null && defaultValue !== void 0 ? defaultValue : null
                 });
 
                 // Update the element attribute to notify useControl / useInputControl hook

package/dist/formdata.d.ts

@@ -1,3 +1,5 @@
+import type { FormError, FormValue, JsonPrimitive, Serialize, SerializedValue, Submission, SubmissionResult } from './types';
+export declare const DEFAULT_INTENT_NAME = "__INTENT__";
 /**
  * Construct a form data with the submitter value.
  * It utilizes the submitter argument on the FormData constructor from modern browsers
@@ -5,96 +7,83 @@
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/API/FormData/FormData#parameters
  */
-export declare function getFormData(form: HTMLFormElement, submitter?: HTMLInputElement | HTMLButtonElement | null): FormData;
+export declare function getFormData(form: HTMLFormElement, submitter?: HTMLElement | null): FormData;
 /**
- * Returns the paths from a name based on the JS syntax convention
+ * Convert a string path into an array of segments.
+ *
  * @example
  * ```js
- * const paths = getPaths('todos[0].content'); // ['todos', 0, 'content']
+ * getPathSegments("object.key");       // → ['object', 'key']
+ * getPathSegments("array[0].content"); // → ['array', 0, 'content']
+ * getPathSegments("todos[]");          // → ['todos', '']
  * ```
  */
-export declare function getPaths(name: string | undefined): Array<string | number>;
+export declare function getPathSegments(path: string | undefined): Array<string | number>;
 /**
- * Returns a formatted name from the paths based on the JS syntax convention
+ * Returns a formatted name from the path segments based on the dot and bracket notation.
+ *
  * @example
  * ```js
- * const name = formatPaths(['todos', 0, 'content']); // "todos[0].content"
+ * formatPathSegments(['object', 'key']); // → "object.key"
+ * formatPathSegments(['array', 0, 'content']); // → "array[0].content"
+ * formatPathSegments(['todos', '']); // → "todos[]"
  * ```
  */
-export declare function formatPaths(paths: Array<string | number>): string;
+export declare function formatPathSegments(segments: Readonly<Array<string | number>>): string;
 /**
- * Format based on a prefix and a path
+ * Append one more segment onto an existing path string.
+ *
+ * - segment = `undefined`  ⇒ no-op
+ * - segment = `""`         ⇒ empty brackets "[]"
+ * - segment = `number`     ⇒ bracket notation "[n]"
+ * - segment = `string`     ⇒ dot-notation ".prop"
  */
-export declare function formatName(prefix: string | undefined, path?: string | number): string;
+export declare function appendPathSegment(path: string | undefined, segment: string | number | undefined): string;
 /**
- * Check if a name match the prefix paths
+ * Returns true if `prefix` is a valid leading path of `name`.
+ *
+ * @example
+ * ```js
+ * isPrefix("foo.bar.baz", "foo.bar")        // → true
+ * isPrefix("foo.bar[3].baz", "foo.bar[3]")  // → true
+ * isPrefix("foo.bar[3].baz", "foo.bar")     // → true
+ * isPrefix("foo.bar[3].baz", "foo.baz")     // → false
+ * isPrefix("foo", "foo.bar")                // → false
+ * ```
  */
 export declare function isPrefix(name: string, prefix: string): boolean;
 /**
- * Compare the parent and child paths to get the relative paths
- * Returns null if the child paths do not start with the parent paths
- */
-export declare function getChildPaths(parentNameOrPaths: string | Array<string | number>, childName: string): (string | number)[] | null;
-/**
- * Assign a value to a target object by following the paths
- */
-export declare function setValue(target: Record<string, any>, name: string, valueFn: (currentValue?: unknown) => unknown): void;
-/**
- * Retrive the value from a target object by following the paths
- */
-export declare function getValue(target: unknown, name: string): unknown;
-/**
- * Check if the value is a plain object
- */
-export declare function isPlainObject(obj: unknown): obj is Record<string | number | symbol, unknown>;
-type GlobalConstructors = {
-    [K in keyof typeof globalThis]: (typeof globalThis)[K] extends new (...args: any) => any ? K : never;
-}[keyof typeof globalThis];
-export declare function isGlobalInstance<ClassName extends GlobalConstructors>(obj: unknown, className: ClassName): obj is InstanceType<(typeof globalThis)[ClassName]>;
-/**
- * Normalize value by removing empty object or array, empty string and null values
- */
-export declare function normalize<Type extends Record<string, unknown>>(value: Type, acceptFile?: boolean): Type | undefined;
-export declare function normalize<Type extends Array<unknown>>(value: Type, acceptFile?: boolean): Type | undefined;
-export declare function normalize(value: unknown, acceptFile?: boolean): unknown | undefined;
-/**
- * Flatten a tree into a dictionary
+ * Return the segments of `fullPathStr` that come after the `baseSegments` prefix.
+ *
+ * @param fullPathStr     Full path as a dot/bracket string
+ * @param basePath    Base path, already parsed into segments
+ * @returns               The “tail” segments, or `null` if `fullPathStr` isn’t nested under `baseSegments`
+ *
+ * @example
+ * ```js
+ * getRelativePath("foo.bar[0].qux", ["foo","bar"])  // → [0, "qux"]
+ * getRelativePath("a.b.c.d", ["a","b"])             // → ["c","d"]
+ * getRelativePath("foo", ["foo","bar"])             // → null
+ * ```
  */
-export declare function flatten(data: unknown, options?: {
-    resolve?: (data: unknown) => unknown;
-    prefix?: string;
-}): Record<string, unknown>;
-export declare function deepEqual(left: unknown, right: unknown): boolean;
-export type JsonPrimitive = string | number | boolean | null;
+export declare function getRelativePath(name: string, basePath: Array<string | number>): Array<string | number> | null;
 /**
- * The form value of a submission. This is usually constructed from a FormData or URLSearchParams.
- * It may contains JSON primitives if the value is updated based on a form intent.
+ * Assign a value to a target object by following the path segments.
  */
-export type FormValue<Type extends JsonPrimitive | FormDataEntryValue = JsonPrimitive | FormDataEntryValue> = Type | FormValue<Type | null>[] | {
-    [key: string]: FormValue<Type>;
-};
+export declare function setValueAtPath<T extends Record<string, any>>(target: T, pathOrSegments: string | Array<string | number>, valueOrFn: unknown | ((current: unknown) => unknown), options?: {
+    clone?: boolean;
+    silent?: boolean;
+}): T;
 /**
- * The data of a form submission.
+ * Retrive the value from a target object by following the path segments.
  */
-export type Submission<ValueType extends FormDataEntryValue = FormDataEntryValue> = {
-    /**
-     * The form value structured following the naming convention.
-     */
-    value: Record<string, FormValue<ValueType>>;
-    /**
-     * The field names that are included in the FormData or URLSearchParams.
-     */
-    fields: string[];
-    /**
-     * The intent of the submission. This is usally included by specifying a name and value on a submit button.
-     */
-    intent: string | null;
-};
+export declare function getValueAtPath(target: unknown, pathOrSegments: string | Array<string | number>): unknown;
 /**
  * Parse `FormData` or `URLSearchParams` into a submission object.
  * This function structures the form values based on the naming convention.
- * It also includes all the field names and the intent if the `intentName` option is provided.
+ * It also includes all the field names and extracts the intent from the submission.
  *
+ * @see https://conform.guide/api/react/future/parseSubmission
  * @example
  * ```ts
  * const formData = new FormData();
@@ -104,7 +93,7 @@ export type Submission<ValueType extends FormDataEntryValue = FormDataEntryValue
  *
  * parseSubmission(formData)
  * // {
- * //   value: { email: 'test@example.com', password: 'secret' },
+ * //   payload: { email: 'test@example.com', password: 'secret' },
  * //   fields: ['email', 'password'],
  * //   intent: null,
  * // }
@@ -113,7 +102,7 @@ export type Submission<ValueType extends FormDataEntryValue = FormDataEntryValue
  * formData.append('intent', 'login');
  * parseSubmission(formData, { intentName: 'intent' })
  * // {
- * //   value: { email: 'test@example.com', password: 'secret' },
+ * //   payload: { email: 'test@example.com', password: 'secret' },
  * //   fields: ['email', 'password'],
  * //   intent: 'login',
  * // }
@@ -121,18 +110,61 @@ export type Submission<ValueType extends FormDataEntryValue = FormDataEntryValue
  */
 export declare function parseSubmission(formData: FormData | URLSearchParams, options?: {
     /**
-     * The name of the submit button that triggered the form submission.
-     * Used to extract the submission's intent.
+     * The name of the submit button field that indicates the submission intent.
+     * Defaults to `__INTENT__`.
      */
     intentName?: string;
     /**
-     * A filter function that excludes specific entries from being parsed.
+     * A function to exclude specific form fields from being parsed.
      * Return `true` to skip the entry.
      */
     skipEntry?: (name: string) => boolean;
 }): Submission;
-export type ParseSubmissionOptions = Required<Parameters<typeof parseSubmission>>[1];
-export declare function defaultSerialize(value: unknown): FormDataEntryValue | undefined;
+/**
+ * Creates a SubmissionResult object from a submission, adding validation results and intended values.
+ * This function will remove all files in the submission payload by default since
+ * file inputs cannot be initialized with files.
+ * You can specify `keepFiles: true` to keep the files if needed.
+ *
+ * @see https://conform.guide/api/react/future/report
+ * @example
+ * ```ts
+ * // Report the submission with the field errors
+ * report(submission, {
+ *  error: {
+ *    fieldErrors: {
+ *      email: ['Invalid email format'],
+ *      password: ['Password is required'],
+ *    },
+ * })
+ *
+ * // Report the submission with a form error
+ * report(submission, {
+ *   error: {
+ *     formErrors: ['Invalid credentials'],
+ *   },
+ * })
+ *
+ * // Reset the form
+ * report(submission, {
+ *   reset: true,
+ * })
+ * ```
+ */
+export declare function report<ErrorShape = string>(submission: Submission, options?: {
+    keepFiles?: false;
+    error?: Partial<FormError<ErrorShape>> | null;
+    intendedValue?: Record<string, FormValue> | null;
+    hideFields?: string[];
+    reset?: boolean;
+}): SubmissionResult<ErrorShape, Exclude<JsonPrimitive | FormDataEntryValue, File>>;
+export declare function report<ErrorShape = string>(submission: Submission, options: {
+    keepFiles: true;
+    error?: Partial<FormError<ErrorShape>> | null;
+    intendedValue?: Record<string, FormValue> | null;
+    hideFields?: string[];
+    reset?: boolean;
+}): SubmissionResult<ErrorShape>;
 /**
  * A utility function that checks whether the current form data differs from the default values.
  *
@@ -160,7 +192,7 @@ export declare function isDirty(
  * - A `URLSearchParams` object
  * - A plain object that was parsed from form data (i.e. `submission.payload`)
  */
-formData: FormData | URLSearchParams | FormValue<FormDataEntryValue> | null, options?: {
+formData: FormData | URLSearchParams | FormValue | null, options?: {
     /**
      * An object representing the default values of the form to compare against.
      * Defaults to an empty object if not provided.
@@ -185,7 +217,7 @@ formData: FormData | URLSearchParams | FormValue<FormDataEntryValue> | null, opt
      * - Date:
      *   - Converted to ISO string using `.toISOString()`
      */
-    serialize?: (value: unknown, defaultSerialize: (value: unknown) => FormDataEntryValue | undefined) => FormDataEntryValue | undefined;
+    serialize?: (value: unknown, defaultSerialize: Serialize) => SerializedValue | undefined;
     /**
      * A function to exclude specific fields from the comparison.
      * Useful for ignoring hidden inputs like CSRF tokens or internal fields added by frameworks
@@ -200,5 +232,20 @@ formData: FormData | URLSearchParams | FormValue<FormDataEntryValue> | null, opt
      */
     skipEntry?: (name: string) => boolean;
 }): boolean | undefined;
-export {};
+/**
+ * Convert an unknown value into something acceptable for HTML form submission.
+ * Returns `undefined` when the value cannot be represented in form data.
+ *
+ * Input -> Output:
+ * - string -> string
+ * - null -> '' (empty string)
+ * - boolean -> 'on' | '' (checked semantics)
+ * - number | bigint -> value.toString()
+ * - Date -> value.toISOString()
+ * - File -> File
+ * - FileList -> File[]
+ * - Array -> string[] or File[] if all items serialize to the same kind; otherwise undefined
+ * - anything else -> undefined
+ */
+export declare function serialize(value: unknown): SerializedValue | undefined;
 //# sourceMappingURL=formdata.d.ts.map