@conform-to/dom 1.18.0 → 1.19.0

package/README.md

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

package/dist/dom.js

@@ -570,8 +570,8 @@ function updateField(element, options) {
       /**
        * Triggering react custom change event
        * Solution based on dom-testing-library
-       * @see https://github.com/facebook/react/issues/10135#issuecomment-401496776
-       * @see https://github.com/testing-library/dom-testing-library/blob/main/src/events.js#L104-L123
+       * See https://github.com/facebook/react/issues/10135#issuecomment-401496776
+       * See https://github.com/testing-library/dom-testing-library/blob/main/src/events.js#L104-L123
        */
       var {
         set: valueSetter

package/dist/dom.mjs

@@ -566,8 +566,8 @@ function updateField(element, options) {
       /**
        * Triggering react custom change event
        * Solution based on dom-testing-library
-       * @see https://github.com/facebook/react/issues/10135#issuecomment-401496776
-       * @see https://github.com/testing-library/dom-testing-library/blob/main/src/events.js#L104-L123
+       * See https://github.com/facebook/react/issues/10135#issuecomment-401496776
+       * See https://github.com/testing-library/dom-testing-library/blob/main/src/events.js#L104-L123
        */
       var {
         set: valueSetter

package/dist/formdata.d.ts

@@ -1,18 +1,29 @@
-import type { FormValue, FieldName, JsonPrimitive, Serialize, SerializedValue, Submission, SubmissionResult, UnknownObject } from './types';
-import type { StandardSchemaIssue } from './standard-schema';
+import type { FormError, FormValue, FieldName, JsonPrimitive, CustomSerialize, Submission, SubmissionResult, UnknownObject, Serialize, StandardSchemaError, CustomError } from './types';
 export declare const DEFAULT_INTENT_NAME = "__INTENT__";
+/**
+ * Returns whether an error payload contains a meaningful value.
+ * Empty strings and empty arrays are treated as no error.
+ */
+export declare function hasError<ErrorShape>(error: ErrorShape | null | undefined): error is ErrorShape;
+/**
+ * Normalizes a form error object by removing empty error payloads such as
+ * empty strings and empty arrays.
+ *
+ * Returns `null` when no form-level or field-level errors remain.
+ */
+export declare function normalizeFormError<ErrorShape>(error: CustomError<ErrorShape> | null): FormError<ErrorShape> | null;
 /**
  * Construct a form data with the submitter value.
  * It utilizes the submitter argument on the FormData constructor from modern browsers
  * with fallback to append the submitter value in case it is not unsupported.
  *
- * @see https://developer.mozilla.org/en-US/docs/Web/API/FormData/FormData#parameters
+ * See https://developer.mozilla.org/en-US/docs/Web/API/FormData/FormData#parameters
  */
 export declare function getFormData(form: HTMLFormElement, submitter?: HTMLElement | null): FormData;
 /**
  * Convert a string path into an array of segments.
  *
- * @example
+ * **Example:**
  * ```js
  * parsePath("object.key");       // → ['object', 'key']
  * parsePath("array[0].content"); // → ['array', 0, 'content']
@@ -23,7 +34,7 @@ export declare function parsePath(path: string | undefined): Array<string | numb
 /**
  * Returns a formatted name from the path segments based on the dot and bracket notation.
  *
- * @example
+ * **Example:**
  * ```js
  * formatPath(['object', 'key']); // → "object.key"
  * formatPath(['array', 0, 'content']); // → "array[0].content"
@@ -43,7 +54,7 @@ export declare function appendPath(path: string | undefined, segment: string | n
 /**
  * Returns true if `prefix` is a valid leading path of `name`.
  *
- * @example
+ * **Example:**
  * ```js
  * isPathPrefix("foo.bar.baz", "foo.bar")        // → true
  * isPathPrefix("foo.bar[3].baz", "foo.bar[3]")  // → true
@@ -60,7 +71,7 @@ export declare function isPathPrefix(name: string, prefix: string): boolean;
  * @param basePath     Base path as a dot/bracket string or array of segments
  * @returns               The “tail” segments, or `null` if `fullPath` isn’t nested under `basePath`
  *
- * @example
+ * **Example:**
  * ```js
  * getRelativePath("foo.bar[0].qux", ["foo","bar"])  // → [0, "qux"]
  * getRelativePath("a.b.c.d", ["a","b"])             // → ["c","d"]
@@ -84,8 +95,9 @@ export declare function getPathValue(target: unknown, pathOrSegments: string | A
  * This function structures the form values based on the naming convention.
  * It also includes all the field names and extracts the intent from the submission.
  *
- * @see https://conform.guide/api/react/future/parseSubmission
- * @example
+ * See https://conform.guide/api/react/future/parseSubmission
+ *
+ * **Example:**
  * ```ts
  * const formData = new FormData();
  *
@@ -136,8 +148,9 @@ export declare function parseSubmission(formData: FormData | URLSearchParams, op
  * 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
+ * See https://conform.guide/api/react/future/report
+ *
+ * **Example:**
  * ```ts
  * // Report the submission with the field errors
  * report(submission, {
@@ -161,55 +174,61 @@ export declare function parseSubmission(formData: FormData | URLSearchParams, op
  * })
  * ```
  */
-export declare function report<ErrorShape = string>(submission: Submission, options?: {
+export declare function report<ErrorShape>(submission: Submission, options: {
     keepFiles?: false;
-    error?: {
-        issues?: undefined;
-        formErrors?: ErrorShape[];
-        fieldErrors?: Record<string, ErrorShape[]>;
-    } | null;
+    error: CustomError<ErrorShape>;
     value?: Record<string, FormValue> | null;
     hideFields?: string[];
     reset?: boolean;
 }): SubmissionResult<ErrorShape, Exclude<JsonPrimitive | FormDataEntryValue, File>>;
-export declare function report<ErrorShape = string>(submission: Submission, options: {
+export declare function report<ErrorShape>(submission: Submission, options: {
     keepFiles: true;
-    error?: {
-        issues?: undefined;
-        formErrors?: ErrorShape[];
-        fieldErrors?: Record<string, ErrorShape[]>;
-    } | null;
+    error: CustomError<ErrorShape>;
     value?: Record<string, FormValue> | null;
     hideFields?: string[];
     reset?: boolean;
 }): SubmissionResult<ErrorShape>;
-export declare function report(submission: Submission, options?: {
+export declare function report(submission: Submission, options: {
     keepFiles?: false;
-    error?: {
-        issues: ReadonlyArray<StandardSchemaIssue>;
-        formErrors?: string[];
-        fieldErrors?: Record<string, string[]>;
-    };
+    error: StandardSchemaError;
+    value?: Record<string, FormValue> | null;
+    hideFields?: string[];
+    reset?: boolean;
+}): SubmissionResult<string[], Exclude<JsonPrimitive | FormDataEntryValue, File>>;
+export declare function report(submission: Submission, options: {
+    keepFiles: true;
+    error: StandardSchemaError;
     value?: Record<string, FormValue> | null;
     hideFields?: string[];
     reset?: boolean;
-}): SubmissionResult<string, Exclude<JsonPrimitive | FormDataEntryValue, File>>;
+}): SubmissionResult<string[]>;
 export declare function report(submission: Submission, options?: {
+    keepFiles?: false;
+    error?: null;
+    value?: Record<string, FormValue> | null;
+    hideFields?: string[];
+    reset?: boolean;
+}): SubmissionResult<never, Exclude<JsonPrimitive | FormDataEntryValue, File>>;
+export declare function report(submission: Submission, options: {
     keepFiles: true;
-    error?: {
-        issues: ReadonlyArray<StandardSchemaIssue>;
-        formErrors?: string[];
-        fieldErrors?: Record<string, string[]>;
-    };
+    error?: null;
+    value?: Record<string, FormValue> | null;
+    hideFields?: string[];
+    reset?: boolean;
+}): SubmissionResult<never>;
+export declare function report<ErrorShape>(submission: Submission, options?: {
+    keepFiles?: boolean;
+    error?: CustomError<ErrorShape> | null;
     value?: Record<string, FormValue> | null;
     hideFields?: string[];
     reset?: boolean;
-}): SubmissionResult<string>;
+}): SubmissionResult<ErrorShape>;
 /**
  * A utility function that checks whether the current form data differs from the default values.
  *
- * @see https://conform.guide/api/react/future/isDirty
- * @example Enable a submit button only if the form is dirty
+ * See https://conform.guide/api/react/future/isDirty
+ *
+ * **Example: Enable a submit button only if the form is dirty**
  *
  * ```tsx
  * const dirty = useFormData(
@@ -251,19 +270,19 @@ formData: FormData | URLSearchParams | FormValue | null, options?: {
      *   - Returned as-is
      * - boolean:
      *   - true → 'on'
-     *   - false → undefined
+     *   - false → null
      * - number / bigint:
      *   - Converted to string using `.toString()`
      * - Date:
      *   - Converted to UTC datetime string without trailing `Z` (e.g. `2026-01-01T12:00:00.000`)
      */
-    serialize?: (value: unknown, defaultSerialize: Serialize) => SerializedValue | null | undefined;
+    serialize?: CustomSerialize;
     /**
      * A function to exclude specific fields from the comparison.
      * Useful for ignoring hidden inputs like CSRF tokens or internal fields added by frameworks
      * (e.g. Next.js uses hidden inputs to support server actions).
      *
-     * @example
+     * **Example:**
      * ```ts
      * isDirty(formData, {
      *   skipEntry: (name) => name === 'csrf-token',
@@ -287,7 +306,7 @@ formData: FormData | URLSearchParams | FormValue | null, options?: {
  * - Array -> string[] or File[] if all items serialize to the same kind; otherwise undefined
  * - anything else -> undefined
  */
-export declare function serialize(value: unknown): SerializedValue | null | undefined;
+export declare function defaultSerialize(value: unknown): ReturnType<Serialize>;
 /**
  * Recursively serializes a value using the provided serialize function,
  * collapsing empty leaves (`null`, `''`, empty files) to `undefined`
@@ -299,11 +318,13 @@ export declare function serialize(value: unknown): SerializedValue | null | unde
  * Single-element arrays where the element is a string or undefined are unwrapped
  * to handle the case where a multi-value field (e.g. checkboxes) has only one value.
  */
-export declare function normalize(value: unknown, serializeValue?: Serialize): unknown;
+export declare function normalize(value: unknown, serialize?: Serialize, name?: string): unknown;
 /**
  * Retrieve a field value from FormData with optional type guards.
  *
- * @example
+ * **Example:**
+ *
+ * ```ts
  * // Basic field access: return `unknown`
  * const email = getFieldValue(formData, 'email');
  * // String type: returns `string`
@@ -318,6 +339,7 @@ export declare function normalize(value: unknown, serializeValue?: Serialize): u
  * const items = getFieldValue<Item[]>(formData, 'items', { type: 'object', array: true });
  * // Optional string type: returns `string | undefined`
  * const bio = getFieldValue(formData, 'bio', { type: 'string', optional: true });
+ * ```
  */
 export declare function getFieldValue<FieldShape extends Array<Record<string, unknown>>>(formData: FormData | URLSearchParams, name: FieldName<FieldShape>, options: {
     type: 'object';

package/dist/formdata.js

@@ -9,12 +9,48 @@ var standardSchema = require('./standard-schema.js');
 
 var DEFAULT_INTENT_NAME = '__INTENT__';
 
+/**
+ * Returns whether an error payload contains a meaningful value.
+ * Empty strings and empty arrays are treated as no error.
+ */
+function hasError(error) {
+  return error != null && error !== '' && (!Array.isArray(error) || error.length > 0);
+}
+
+/**
+ * Normalizes a form error object by removing empty error payloads such as
+ * empty strings and empty arrays.
+ *
+ * Returns `null` when no form-level or field-level errors remain.
+ */
+function normalizeFormError(error) {
+  var _error$fieldErrors;
+  if (error === null) {
+    return null;
+  }
+  var formErrors = hasError(error.formErrors) ? error.formErrors : null;
+  var fieldErrors = Object.entries((_error$fieldErrors = error.fieldErrors) !== null && _error$fieldErrors !== void 0 ? _error$fieldErrors : {}).reduce((result, _ref) => {
+    var [name, value] = _ref;
+    if (hasError(value)) {
+      result[name] = value;
+    }
+    return result;
+  }, {});
+  if (formErrors === null && Object.keys(fieldErrors).length === 0) {
+    return null;
+  }
+  return {
+    formErrors,
+    fieldErrors
+  };
+}
+
 /**
  * Construct a form data with the submitter value.
  * It utilizes the submitter argument on the FormData constructor from modern browsers
  * with fallback to append the submitter value in case it is not unsupported.
  *
- * @see https://developer.mozilla.org/en-US/docs/Web/API/FormData/FormData#parameters
+ * See https://developer.mozilla.org/en-US/docs/Web/API/FormData/FormData#parameters
  */
 function getFormData(form, submitter) {
   var payload = new FormData(form, submitter);
@@ -37,7 +73,7 @@ function getFormData(form, submitter) {
 /**
  * Convert a string path into an array of segments.
  *
- * @example
+ * **Example:**
  * ```js
  * parsePath("object.key");       // → ['object', 'key']
  * parsePath("array[0].content"); // → ['array', 0, 'content']
@@ -83,7 +119,7 @@ function parsePath(path) {
 /**
  * Returns a formatted name from the path segments based on the dot and bracket notation.
  *
- * @example
+ * **Example:**
  * ```js
  * formatPath(['object', 'key']); // → "object.key"
  * formatPath(['array', 0, 'content']); // → "array[0].content"
@@ -103,30 +139,32 @@ function formatPath(segments) {
  * - segment = `string`     ⇒ dot-notation ".prop"
  */
 function appendPath(path, segment) {
+  var base = path !== null && path !== void 0 ? path : '';
+
   // 1) nothing to append
   if (typeof segment === 'undefined') {
-    return path !== null && path !== void 0 ? path : '';
+    return base;
   }
 
   // 2) explicit empty-segment => empty bracket
   if (segment === '') {
     // even as first segment, "[]" is valid
-    return "".concat(path, "[]");
+    return "".concat(base, "[]");
   }
 
   // 3) numeric index => [n]
   if (typeof segment === 'number') {
-    return "".concat(path, "[").concat(segment, "]");
+    return "".concat(base, "[").concat(segment, "]");
   }
 
   // 4) non-empty string => .prop (no leading dot if no base)
-  return path ? "".concat(path, ".").concat(segment) : segment;
+  return base ? "".concat(base, ".").concat(segment) : segment;
 }
 
 /**
  * Returns true if `prefix` is a valid leading path of `name`.
  *
- * @example
+ * **Example:**
  * ```js
  * isPathPrefix("foo.bar.baz", "foo.bar")        // → true
  * isPathPrefix("foo.bar[3].baz", "foo.bar[3]")  // → true
@@ -146,7 +184,7 @@ function isPathPrefix(name, prefix) {
  * @param basePath     Base path as a dot/bracket string or array of segments
  * @returns               The “tail” segments, or `null` if `fullPath` isn’t nested under `basePath`
  *
- * @example
+ * **Example:**
  * ```js
  * getRelativePath("foo.bar[0].qux", ["foo","bar"])  // → [0, "qux"]
  * getRelativePath("a.b.c.d", ["a","b"])             // → ["c","d"]
@@ -265,8 +303,9 @@ function isEmptyValue(value) {
  * This function structures the form values based on the naming convention.
  * It also includes all the field names and extracts the intent from the submission.
  *
- * @see https://conform.guide/api/react/future/parseSubmission
- * @example
+ * See https://conform.guide/api/react/future/parseSubmission
+ *
+ * **Example:**
  * ```ts
  * const formData = new FormData();
  *
@@ -302,7 +341,7 @@ function parseSubmission(formData, options) {
     var _options$skipEntry;
     if (_name !== intentName && !(options !== null && options !== void 0 && (_options$skipEntry = options.skipEntry) !== null && _options$skipEntry !== void 0 && _options$skipEntry.call(options, _name))) {
       var _options$stripEmptyVa;
-      var _value = formData.getAll(_name);
+      var value = formData.getAll(_name);
       var segments = parsePath(_name);
 
       // If the name ends with [], remove the empty segment and keep the full array
@@ -310,19 +349,19 @@ function parseSubmission(formData, options) {
       if (segments.length > 0 && segments[segments.length - 1] === '') {
         segments.pop();
       } else {
-        _value = _value.length > 1 ? _value : _value[0];
+        value = value.length > 1 ? value : value[0];
       }
       var stripEmptyValues = (_options$stripEmptyVa = options === null || options === void 0 ? void 0 : options.stripEmptyValues) !== null && _options$stripEmptyVa !== void 0 ? _options$stripEmptyVa : false;
       if (stripEmptyValues) {
         // For arrays, filter out individual empty items
-        if (Array.isArray(_value)) {
-          _value = _value.filter(item => !isEmptyValue(item));
+        if (Array.isArray(value)) {
+          value = value.filter(item => !isEmptyValue(item));
         }
-        if (isEmptyValue(_value)) {
-          _value = undefined;
+        if (isEmptyValue(value)) {
+          value = undefined;
         }
       }
-      setPathValue(submission.payload, segments, _value, {
+      setPathValue(submission.payload, segments, value, {
         silent: true // Avoid errors if the path is invalid
       });
       submission.fields.push(_name);
@@ -344,8 +383,9 @@ function parseSubmission(formData, options) {
  * 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
+ * See https://conform.guide/api/react/future/report
+ *
+ * **Example:**
  * ```ts
  * // Report the submission with the field errors
  * report(submission, {
@@ -376,29 +416,16 @@ function report(submission) {
   var error;
   if (options.error == null) {
     error = options.error;
-  } else {
+  } else if ('issues' in options.error) {
     var _options$error$issues;
     error = standardSchema.formatIssues((_options$error$issues = options.error.issues) !== null && _options$error$issues !== void 0 ? _options$error$issues : []);
-    if (options.error.formErrors) {
-      error.formErrors.push(...options.error.formErrors);
-    }
-    if (options.error.fieldErrors) {
-      for (var [_name2, messages] of Object.entries(options.error.fieldErrors)) {
-        if (messages.length === 0) {
-          continue;
-        }
-        if (!error.fieldErrors[_name2]) {
-          error.fieldErrors[_name2] = messages;
-        } else {
-          error.fieldErrors[_name2].push(...messages);
-        }
-      }
-    }
+  } else {
+    error = normalizeFormError(options.error);
   }
   var targetValue = typeof options.value === 'undefined' || submission.payload === options.value && !options.reset ? undefined : options.value && !options.keepFiles ? util.stripFiles(options.value) : (_options$value = options.value) !== null && _options$value !== void 0 ? _options$value : {};
   if (options.hideFields) {
-    for (var _name3 of options.hideFields) {
-      var path = parsePath(_name3);
+    for (var _name2 of options.hideFields) {
+      var path = parsePath(_name2);
       setPathValue(submission.payload, path, undefined);
       if (targetValue) {
         setPathValue(targetValue, path, undefined);
@@ -418,8 +445,9 @@ function report(submission) {
 /**
  * A utility function that checks whether the current form data differs from the default values.
  *
- * @see https://conform.guide/api/react/future/isDirty
- * @example Enable a submit button only if the form is dirty
+ * See https://conform.guide/api/react/future/isDirty
+ *
+ * **Example: Enable a submit button only if the form is dirty**
  *
  * ```tsx
  * const dirty = useFormData(
@@ -450,9 +478,16 @@ formData, options) {
     intentName: options === null || options === void 0 ? void 0 : options.intentName,
     skipEntry: options === null || options === void 0 ? void 0 : options.skipEntry
   }).payload : formData;
-  var defaultValue = options === null || options === void 0 ? void 0 : options.defaultValue;
-  var serializeValue = options !== null && options !== void 0 && options.serialize ? value => options.serialize(value, serialize) : serialize;
-  return !util.deepEqual(normalize(formValue, serializeValue), normalize(defaultValue, serializeValue));
+  var serialize = (value, context) => {
+    if (options !== null && options !== void 0 && options.serialize) {
+      return options.serialize(value, {
+        name: context.name,
+        defaultSerialize
+      });
+    }
+    return defaultSerialize(value);
+  };
+  return !util.deepEqual(normalize(formValue, serialize), normalize(options === null || options === void 0 ? void 0 : options.defaultValue, serialize));
 }
 
 /**
@@ -470,13 +505,13 @@ formData, options) {
  * - Array -> string[] or File[] if all items serialize to the same kind; otherwise undefined
  * - anything else -> undefined
  */
-function serialize(value) {
+function defaultSerialize(value) {
   function serializePrimitive(value) {
     if (typeof value === 'string' || value === null) {
       return value;
     }
     if (typeof value === 'boolean') {
-      return value ? 'on' : '';
+      return value ? 'on' : null;
     }
     if (typeof value === 'number' || typeof value === 'bigint') {
       return value.toString();
@@ -537,8 +572,11 @@ function serialize(value) {
  * to handle the case where a multi-value field (e.g. checkboxes) has only one value.
  */
 function normalize(value) {
-  var serializeValue = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : serialize;
-  var data = serializeValue(value);
+  var serialize = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : defaultSerialize;
+  var name = arguments.length > 2 ? arguments[2] : undefined;
+  var data = serialize(value, {
+    name
+  });
   if (typeof data === 'undefined') {
     data = value;
   }
@@ -555,16 +593,16 @@ function normalize(value) {
     if (data.length === 0) {
       return undefined;
     }
-    var array = data.map(item => normalize(item, serializeValue));
+    var array = data.map((item, index) => normalize(item, serialize, appendPath(name, index)));
     if (array.length === 1 && (typeof array[0] === 'string' || array[0] === undefined)) {
       return array[0];
     }
     return array;
   }
   if (util.isPlainObject(data)) {
-    var entries = Object.entries(data).reduce((list, _ref) => {
-      var [key, value] = _ref;
-      var normalizedValue = normalize(value, serializeValue);
+    var entries = Object.entries(data).reduce((list, _ref2) => {
+      var [key, value] = _ref2;
+      var normalizedValue = normalize(value, serialize, appendPath(name, key));
       if (typeof normalizedValue !== 'undefined') {
         list.push([key, normalizedValue]);
       }
@@ -581,7 +619,9 @@ function normalize(value) {
 /**
  * Retrieve a field value from FormData with optional type guards.
  *
- * @example
+ * **Example:**
+ *
+ * ```ts
  * // Basic field access: return `unknown`
  * const email = getFieldValue(formData, 'email');
  * // String type: returns `string`
@@ -596,6 +636,7 @@ function normalize(value) {
  * const items = getFieldValue<Item[]>(formData, 'items', { type: 'object', array: true });
  * // Optional string type: returns `string | undefined`
  * const bio = getFieldValue(formData, 'bio', { type: 'string', optional: true });
+ * ```
  */
 
 function getFieldValue(formData, name, options) {
@@ -649,16 +690,18 @@ function getFieldValue(formData, name, options) {
 
 exports.DEFAULT_INTENT_NAME = DEFAULT_INTENT_NAME;
 exports.appendPath = appendPath;
+exports.defaultSerialize = defaultSerialize;
 exports.formatPath = formatPath;
 exports.getFieldValue = getFieldValue;
 exports.getFormData = getFormData;
 exports.getPathValue = getPathValue;
 exports.getRelativePath = getRelativePath;
+exports.hasError = hasError;
 exports.isDirty = isDirty;
 exports.isPathPrefix = isPathPrefix;
 exports.normalize = normalize;
+exports.normalizeFormError = normalizeFormError;
 exports.parsePath = parsePath;
 exports.parseSubmission = parseSubmission;
 exports.report = report;
-exports.serialize = serialize;
 exports.setPathValue = setPathValue;

package/dist/formdata.mjs

@@ -5,12 +5,48 @@ import { formatIssues } from './standard-schema.mjs';
 
 var DEFAULT_INTENT_NAME = '__INTENT__';
 
+/**
+ * Returns whether an error payload contains a meaningful value.
+ * Empty strings and empty arrays are treated as no error.
+ */
+function hasError(error) {
+  return error != null && error !== '' && (!Array.isArray(error) || error.length > 0);
+}
+
+/**
+ * Normalizes a form error object by removing empty error payloads such as
+ * empty strings and empty arrays.
+ *
+ * Returns `null` when no form-level or field-level errors remain.
+ */
+function normalizeFormError(error) {
+  var _error$fieldErrors;
+  if (error === null) {
+    return null;
+  }
+  var formErrors = hasError(error.formErrors) ? error.formErrors : null;
+  var fieldErrors = Object.entries((_error$fieldErrors = error.fieldErrors) !== null && _error$fieldErrors !== void 0 ? _error$fieldErrors : {}).reduce((result, _ref) => {
+    var [name, value] = _ref;
+    if (hasError(value)) {
+      result[name] = value;
+    }
+    return result;
+  }, {});
+  if (formErrors === null && Object.keys(fieldErrors).length === 0) {
+    return null;
+  }
+  return {
+    formErrors,
+    fieldErrors
+  };
+}
+
 /**
  * Construct a form data with the submitter value.
  * It utilizes the submitter argument on the FormData constructor from modern browsers
  * with fallback to append the submitter value in case it is not unsupported.
  *
- * @see https://developer.mozilla.org/en-US/docs/Web/API/FormData/FormData#parameters
+ * See https://developer.mozilla.org/en-US/docs/Web/API/FormData/FormData#parameters
  */
 function getFormData(form, submitter) {
   var payload = new FormData(form, submitter);
@@ -33,7 +69,7 @@ function getFormData(form, submitter) {
 /**
  * Convert a string path into an array of segments.
  *
- * @example
+ * **Example:**
  * ```js
  * parsePath("object.key");       // → ['object', 'key']
  * parsePath("array[0].content"); // → ['array', 0, 'content']
@@ -79,7 +115,7 @@ function parsePath(path) {
 /**
  * Returns a formatted name from the path segments based on the dot and bracket notation.
  *
- * @example
+ * **Example:**
  * ```js
  * formatPath(['object', 'key']); // → "object.key"
  * formatPath(['array', 0, 'content']); // → "array[0].content"
@@ -99,30 +135,32 @@ function formatPath(segments) {
  * - segment = `string`     ⇒ dot-notation ".prop"
  */
 function appendPath(path, segment) {
+  var base = path !== null && path !== void 0 ? path : '';
+
   // 1) nothing to append
   if (typeof segment === 'undefined') {
-    return path !== null && path !== void 0 ? path : '';
+    return base;
   }
 
   // 2) explicit empty-segment => empty bracket
   if (segment === '') {
     // even as first segment, "[]" is valid
-    return "".concat(path, "[]");
+    return "".concat(base, "[]");
   }
 
   // 3) numeric index => [n]
   if (typeof segment === 'number') {
-    return "".concat(path, "[").concat(segment, "]");
+    return "".concat(base, "[").concat(segment, "]");
   }
 
   // 4) non-empty string => .prop (no leading dot if no base)
-  return path ? "".concat(path, ".").concat(segment) : segment;
+  return base ? "".concat(base, ".").concat(segment) : segment;
 }
 
 /**
  * Returns true if `prefix` is a valid leading path of `name`.
  *
- * @example
+ * **Example:**
  * ```js
  * isPathPrefix("foo.bar.baz", "foo.bar")        // → true
  * isPathPrefix("foo.bar[3].baz", "foo.bar[3]")  // → true
@@ -142,7 +180,7 @@ function isPathPrefix(name, prefix) {
  * @param basePath     Base path as a dot/bracket string or array of segments
  * @returns               The “tail” segments, or `null` if `fullPath` isn’t nested under `basePath`
  *
- * @example
+ * **Example:**
  * ```js
  * getRelativePath("foo.bar[0].qux", ["foo","bar"])  // → [0, "qux"]
  * getRelativePath("a.b.c.d", ["a","b"])             // → ["c","d"]
@@ -261,8 +299,9 @@ function isEmptyValue(value) {
  * This function structures the form values based on the naming convention.
  * It also includes all the field names and extracts the intent from the submission.
  *
- * @see https://conform.guide/api/react/future/parseSubmission
- * @example
+ * See https://conform.guide/api/react/future/parseSubmission
+ *
+ * **Example:**
  * ```ts
  * const formData = new FormData();
  *
@@ -298,7 +337,7 @@ function parseSubmission(formData, options) {
     var _options$skipEntry;
     if (_name !== intentName && !(options !== null && options !== void 0 && (_options$skipEntry = options.skipEntry) !== null && _options$skipEntry !== void 0 && _options$skipEntry.call(options, _name))) {
       var _options$stripEmptyVa;
-      var _value = formData.getAll(_name);
+      var value = formData.getAll(_name);
       var segments = parsePath(_name);
 
       // If the name ends with [], remove the empty segment and keep the full array
@@ -306,19 +345,19 @@ function parseSubmission(formData, options) {
       if (segments.length > 0 && segments[segments.length - 1] === '') {
         segments.pop();
       } else {
-        _value = _value.length > 1 ? _value : _value[0];
+        value = value.length > 1 ? value : value[0];
       }
       var stripEmptyValues = (_options$stripEmptyVa = options === null || options === void 0 ? void 0 : options.stripEmptyValues) !== null && _options$stripEmptyVa !== void 0 ? _options$stripEmptyVa : false;
       if (stripEmptyValues) {
         // For arrays, filter out individual empty items
-        if (Array.isArray(_value)) {
-          _value = _value.filter(item => !isEmptyValue(item));
+        if (Array.isArray(value)) {
+          value = value.filter(item => !isEmptyValue(item));
         }
-        if (isEmptyValue(_value)) {
-          _value = undefined;
+        if (isEmptyValue(value)) {
+          value = undefined;
         }
       }
-      setPathValue(submission.payload, segments, _value, {
+      setPathValue(submission.payload, segments, value, {
         silent: true // Avoid errors if the path is invalid
       });
       submission.fields.push(_name);
@@ -340,8 +379,9 @@ function parseSubmission(formData, options) {
  * 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
+ * See https://conform.guide/api/react/future/report
+ *
+ * **Example:**
  * ```ts
  * // Report the submission with the field errors
  * report(submission, {
@@ -372,29 +412,16 @@ function report(submission) {
   var error;
   if (options.error == null) {
     error = options.error;
-  } else {
+  } else if ('issues' in options.error) {
     var _options$error$issues;
     error = formatIssues((_options$error$issues = options.error.issues) !== null && _options$error$issues !== void 0 ? _options$error$issues : []);
-    if (options.error.formErrors) {
-      error.formErrors.push(...options.error.formErrors);
-    }
-    if (options.error.fieldErrors) {
-      for (var [_name2, messages] of Object.entries(options.error.fieldErrors)) {
-        if (messages.length === 0) {
-          continue;
-        }
-        if (!error.fieldErrors[_name2]) {
-          error.fieldErrors[_name2] = messages;
-        } else {
-          error.fieldErrors[_name2].push(...messages);
-        }
-      }
-    }
+  } else {
+    error = normalizeFormError(options.error);
   }
   var targetValue = typeof options.value === 'undefined' || submission.payload === options.value && !options.reset ? undefined : options.value && !options.keepFiles ? stripFiles(options.value) : (_options$value = options.value) !== null && _options$value !== void 0 ? _options$value : {};
   if (options.hideFields) {
-    for (var _name3 of options.hideFields) {
-      var path = parsePath(_name3);
+    for (var _name2 of options.hideFields) {
+      var path = parsePath(_name2);
       setPathValue(submission.payload, path, undefined);
       if (targetValue) {
         setPathValue(targetValue, path, undefined);
@@ -414,8 +441,9 @@ function report(submission) {
 /**
  * A utility function that checks whether the current form data differs from the default values.
  *
- * @see https://conform.guide/api/react/future/isDirty
- * @example Enable a submit button only if the form is dirty
+ * See https://conform.guide/api/react/future/isDirty
+ *
+ * **Example: Enable a submit button only if the form is dirty**
  *
  * ```tsx
  * const dirty = useFormData(
@@ -446,9 +474,16 @@ formData, options) {
     intentName: options === null || options === void 0 ? void 0 : options.intentName,
     skipEntry: options === null || options === void 0 ? void 0 : options.skipEntry
   }).payload : formData;
-  var defaultValue = options === null || options === void 0 ? void 0 : options.defaultValue;
-  var serializeValue = options !== null && options !== void 0 && options.serialize ? value => options.serialize(value, serialize) : serialize;
-  return !deepEqual(normalize(formValue, serializeValue), normalize(defaultValue, serializeValue));
+  var serialize = (value, context) => {
+    if (options !== null && options !== void 0 && options.serialize) {
+      return options.serialize(value, {
+        name: context.name,
+        defaultSerialize
+      });
+    }
+    return defaultSerialize(value);
+  };
+  return !deepEqual(normalize(formValue, serialize), normalize(options === null || options === void 0 ? void 0 : options.defaultValue, serialize));
 }
 
 /**
@@ -466,13 +501,13 @@ formData, options) {
  * - Array -> string[] or File[] if all items serialize to the same kind; otherwise undefined
  * - anything else -> undefined
  */
-function serialize(value) {
+function defaultSerialize(value) {
   function serializePrimitive(value) {
     if (typeof value === 'string' || value === null) {
       return value;
     }
     if (typeof value === 'boolean') {
-      return value ? 'on' : '';
+      return value ? 'on' : null;
     }
     if (typeof value === 'number' || typeof value === 'bigint') {
       return value.toString();
@@ -533,8 +568,11 @@ function serialize(value) {
  * to handle the case where a multi-value field (e.g. checkboxes) has only one value.
  */
 function normalize(value) {
-  var serializeValue = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : serialize;
-  var data = serializeValue(value);
+  var serialize = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : defaultSerialize;
+  var name = arguments.length > 2 ? arguments[2] : undefined;
+  var data = serialize(value, {
+    name
+  });
   if (typeof data === 'undefined') {
     data = value;
   }
@@ -551,16 +589,16 @@ function normalize(value) {
     if (data.length === 0) {
       return undefined;
     }
-    var array = data.map(item => normalize(item, serializeValue));
+    var array = data.map((item, index) => normalize(item, serialize, appendPath(name, index)));
     if (array.length === 1 && (typeof array[0] === 'string' || array[0] === undefined)) {
       return array[0];
     }
     return array;
   }
   if (isPlainObject(data)) {
-    var entries = Object.entries(data).reduce((list, _ref) => {
-      var [key, value] = _ref;
-      var normalizedValue = normalize(value, serializeValue);
+    var entries = Object.entries(data).reduce((list, _ref2) => {
+      var [key, value] = _ref2;
+      var normalizedValue = normalize(value, serialize, appendPath(name, key));
       if (typeof normalizedValue !== 'undefined') {
         list.push([key, normalizedValue]);
       }
@@ -577,7 +615,9 @@ function normalize(value) {
 /**
  * Retrieve a field value from FormData with optional type guards.
  *
- * @example
+ * **Example:**
+ *
+ * ```ts
  * // Basic field access: return `unknown`
  * const email = getFieldValue(formData, 'email');
  * // String type: returns `string`
@@ -592,6 +632,7 @@ function normalize(value) {
  * const items = getFieldValue<Item[]>(formData, 'items', { type: 'object', array: true });
  * // Optional string type: returns `string | undefined`
  * const bio = getFieldValue(formData, 'bio', { type: 'string', optional: true });
+ * ```
  */
 
 function getFieldValue(formData, name, options) {
@@ -643,4 +684,4 @@ function getFieldValue(formData, name, options) {
   return value;
 }
 
-export { DEFAULT_INTENT_NAME, appendPath, formatPath, getFieldValue, getFormData, getPathValue, getRelativePath, isDirty, isPathPrefix, normalize, parsePath, parseSubmission, report, serialize, setPathValue };
+export { DEFAULT_INTENT_NAME, appendPath, defaultSerialize, formatPath, getFieldValue, getFormData, getPathValue, getRelativePath, hasError, isDirty, isPathPrefix, normalize, normalizeFormError, parsePath, parseSubmission, report, setPathValue };

package/dist/future/index.d.ts

@@ -1,5 +1,5 @@
-export type { Serialize, FieldName, FormValue, FormError, Submission, SubmissionResult, ValidationAttributes, } from '../types';
-export { DEFAULT_INTENT_NAME, getFormData, isDirty, normalize, parseSubmission, parsePath, formatPath, appendPath, getRelativePath, getPathValue, setPathValue, report, serialize, getFieldValue, } from '../formdata';
+export type { Serialize, CustomSerialize, FieldName, FormValue, FormError, Submission, SubmissionResult, ValidationAttributes, } from '../types';
+export { DEFAULT_INTENT_NAME, getFormData, isDirty, normalize, parseSubmission, parsePath, formatPath, appendPath, getRelativePath, getPathValue, setPathValue, report, defaultSerialize, getFieldValue, normalizeFormError, } from '../formdata';
 export { isPlainObject, deepEqual } from '../util';
 export { isFieldElement, isGlobalInstance, updateField, createFileList, createGlobalFormsObserver, dispatchInternalUpdateEvent, focus, change, blur, getFormAction, getFormEncType, getFormMethod, requestSubmit, requestIntent, } from '../dom';
 export { formatIssues } from '../standard-schema';

package/dist/future/index.js

@@ -11,6 +11,7 @@ var standardSchema = require('../standard-schema.js');
 
 exports.DEFAULT_INTENT_NAME = formdata.DEFAULT_INTENT_NAME;
 exports.appendPath = formdata.appendPath;
+exports.defaultSerialize = formdata.defaultSerialize;
 exports.formatPath = formdata.formatPath;
 exports.getFieldValue = formdata.getFieldValue;
 exports.getFormData = formdata.getFormData;
@@ -18,10 +19,10 @@ exports.getPathValue = formdata.getPathValue;
 exports.getRelativePath = formdata.getRelativePath;
 exports.isDirty = formdata.isDirty;
 exports.normalize = formdata.normalize;
+exports.normalizeFormError = formdata.normalizeFormError;
 exports.parsePath = formdata.parsePath;
 exports.parseSubmission = formdata.parseSubmission;
 exports.report = formdata.report;
-exports.serialize = formdata.serialize;
 exports.setPathValue = formdata.setPathValue;
 exports.deepEqual = util.deepEqual;
 exports.isPlainObject = util.isPlainObject;

package/dist/future/index.mjs

@@ -1,4 +1,4 @@
-export { DEFAULT_INTENT_NAME, appendPath, formatPath, getFieldValue, getFormData, getPathValue, getRelativePath, isDirty, normalize, parsePath, parseSubmission, report, serialize, setPathValue } from '../formdata.mjs';
+export { DEFAULT_INTENT_NAME, appendPath, defaultSerialize, formatPath, getFieldValue, getFormData, getPathValue, getRelativePath, isDirty, normalize, normalizeFormError, parsePath, parseSubmission, report, setPathValue } from '../formdata.mjs';
 export { deepEqual, isPlainObject } from '../util.mjs';
 export { blur, change, createFileList, createGlobalFormsObserver, dispatchInternalUpdateEvent, focus, getFormAction, getFormEncType, getFormMethod, isFieldElement, isGlobalInstance, requestIntent, requestSubmit, updateField } from '../dom.mjs';
 export { formatIssues } from '../standard-schema.mjs';

package/dist/standard-schema.d.ts

@@ -1,15 +1,3 @@
-import type { FormError } from './types';
-/**
- * A widened version of `StandardSchemaV1.Issue`.
- *
- * The `path` elements and `PropertyKey` fields are loosened to `unknown`
- * to stay compatible with Valibot's native issue type.
- */
-export type StandardSchemaIssue = {
-    readonly message: string;
-    readonly path?: ReadonlyArray<unknown | {
-        key: unknown;
-    }> | undefined;
-};
-export declare function formatIssues(issues: Readonly<StandardSchemaIssue[]>): FormError<string>;
+import type { FormError, StandardSchemaIssue } from './types';
+export declare function formatIssues(issues: Readonly<StandardSchemaIssue[]>): FormError<string[]>;
 //# sourceMappingURL=standard-schema.d.ts.map

package/dist/standard-schema.js

@@ -5,16 +5,9 @@ Object.defineProperty(exports, '__esModule', { value: true });
 var formdata = require('./formdata.js');
 var util = require('./util.js');
 
-/**
- * A widened version of `StandardSchemaV1.Issue`.
- *
- * The `path` elements and `PropertyKey` fields are loosened to `unknown`
- * to stay compatible with Valibot's native issue type.
- */
-
 function formatIssues(issues) {
   var error = {
-    formErrors: [],
+    formErrors: null,
     fieldErrors: {}
   };
   for (var issue of issues) {
@@ -28,6 +21,8 @@ function formatIssues(issues) {
     })) !== null && _issue$path$map !== void 0 ? _issue$path$map : [];
     var name = formdata.formatPath(segments !== null && segments !== void 0 ? segments : []);
     if (!name) {
+      var _error$formErrors;
+      (_error$formErrors = error.formErrors) !== null && _error$formErrors !== void 0 ? _error$formErrors : error.formErrors = [];
       error.formErrors.push(issue.message);
     } else {
       var _error$fieldErrors, _error$fieldErrors$na;

package/dist/standard-schema.mjs

@@ -1,16 +1,9 @@
 import { formatPath } from './formdata.mjs';
 import { isPlainObject } from './util.mjs';
 
-/**
- * A widened version of `StandardSchemaV1.Issue`.
- *
- * The `path` elements and `PropertyKey` fields are loosened to `unknown`
- * to stay compatible with Valibot's native issue type.
- */
-
 function formatIssues(issues) {
   var error = {
-    formErrors: [],
+    formErrors: null,
     fieldErrors: {}
   };
   for (var issue of issues) {
@@ -24,6 +17,8 @@ function formatIssues(issues) {
     })) !== null && _issue$path$map !== void 0 ? _issue$path$map : [];
     var name = formatPath(segments !== null && segments !== void 0 ? segments : []);
     if (!name) {
+      var _error$formErrors;
+      (_error$formErrors = error.formErrors) !== null && _error$formErrors !== void 0 ? _error$formErrors : error.formErrors = [];
       error.formErrors.push(issue.message);
     } else {
       var _error$fieldErrors, _error$fieldErrors$na;

package/dist/types.d.ts

@@ -12,15 +12,35 @@ export type FormValue<Type extends JsonPrimitive | FormDataEntryValue = JsonPrim
 /**
  * Form error object that contains both form errors and field errors.
  */
-export type FormError<ErrorShape = string> = {
+export type FormError<ErrorShape = string[]> = {
     /**
-     * The error of the form.
+     * The form-level error payload.
+     * Set to `null` when there is no form-level error.
      */
-    formErrors: ErrorShape[];
+    formErrors: ErrorShape | null;
     /**
-     * The field errors based on the field name.
+     * Field-level error payloads mapped by field name.
+     * Use `null` to explicitly clear a field error.
      */
-    fieldErrors: Record<string, ErrorShape[]>;
+    fieldErrors: Record<string, ErrorShape | null>;
+};
+/**
+ * A widened version of `StandardSchemaV1.Issue`.
+ *
+ * The `path` elements and `PropertyKey` fields are loosened to `unknown`
+ * to stay compatible with Valibot's native issue type.
+ */
+export type StandardSchemaIssue = {
+    readonly message: string;
+    readonly path?: ReadonlyArray<unknown | {
+        key: unknown;
+    }> | undefined;
+};
+export type StandardSchemaError = Partial<Record<keyof FormError, never>> & {
+    issues: ReadonlyArray<StandardSchemaIssue>;
+};
+export type CustomError<ErrorShape> = Partial<FormError<ErrorShape>> & {
+    issues?: never;
 };
 /**
  * Structured data parsed from a form submission.
@@ -30,7 +50,7 @@ export type Submission<ValueType extends JsonPrimitive | FormDataEntryValue = Js
      * The submitted values mapped by field name.
      * Supports nested names like `user.email` or indexed names like `items[0].id`.
      *
-     * @example
+     * **Example:**
      * ```json
      * {
      *   "username": "johndoe",
@@ -58,7 +78,7 @@ export type Submission<ValueType extends JsonPrimitive | FormDataEntryValue = Js
 /**
  * The result of a submission.
  */
-export type SubmissionResult<ErrorShape = string, ValueType extends JsonPrimitive | FormDataEntryValue = JsonPrimitive | FormDataEntryValue> = {
+export type SubmissionResult<ErrorShape = string[], ValueType extends JsonPrimitive | FormDataEntryValue = JsonPrimitive | FormDataEntryValue> = {
     /**
      * The original submission data.
      */
@@ -81,8 +101,9 @@ export type FieldName<FieldShape> = string & {
     '~shape'?: FieldShape;
 };
 /**
- * The input attributes related to form field constraints
- * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation
+ * The input attributes related to form field constraints.
+ *
+ * See https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation
  */
 export type ValidationAttributes = {
     required?: boolean | undefined;
@@ -103,23 +124,22 @@ export type Serializable<T> = T extends File ? undefined : T extends Array<infer
     [K in keyof T]: Serializable<T[K]>;
 } : T;
 /**
- * Converts an arbitrary value into a {@link SerializedValue}.
+ * Converts an arbitrary value into a form value.
  *
  * This function is used to prepare field values for submission,
  * ensuring they are compatible with the browser's `FormData` API.
- *
- * @param value - The original value to serialize.
- * @returns A `SerializedValue` if the input can be represented in `FormData`,
- *          or `undefined` if it cannot be serialized.
  */
-export type Serialize = (value: unknown) => SerializedValue | null | undefined;
+export type Serialize = (value: unknown, ctx: {
+    name: string | undefined;
+}) => FormValue<FormDataEntryValue> | null | undefined;
 /**
- * A value that can be serialized into `FormData`.
- *
- * - `string` and `File` are supported natively by `FormData`.
- * - Arrays allow representing multi-value fields.
+ * A custom serializer that can override specific values and delegate everything
+ * else back to the default serializer.
  */
-export type SerializedValue = string | string[] | File | File[];
+export type CustomSerialize = (value: unknown, ctx: {
+    name: string | undefined;
+    defaultSerialize: (value: unknown) => ReturnType<Serialize>;
+}) => FormValue<FormDataEntryValue> | null | undefined;
 /**
  * Flatten a discriminated union into a single type with all properties.
  */

package/package.json

@@ -3,7 +3,7 @@
   "description": "A set of opinionated helpers built on top of the Constraint Validation API",
   "homepage": "https://conform.guide",
   "license": "MIT",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",