@conform-to/dom 1.17.1 → 1.19.0

package/dist/form.mjs

@@ -1,5 +1,5 @@
 import { objectSpread2 as _objectSpread2 } from './_virtual/_rollupPluginBabelHelpers.mjs';
-import { appendPathSegment, getValueAtPath, isPrefix, setValueAtPath, getFormData, getPathSegments, getRelativePath, formatPathSegments } from './formdata.mjs';
+import { appendPath, getPathValue, isPathPrefix, setPathValue, getFormData, parsePath, getRelativePath, formatPath } 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';
@@ -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[appendPathSegment(key, i)] = generateId();
+        result[appendPath(key, i)] = generateId();
       }
     }
     return result;
@@ -72,7 +72,7 @@ function handleIntent(meta, intent, fields, initialized) {
           validated,
           value
         } = intent.payload;
-        var _name2 = appendPathSegment(intent.payload.name, intent.payload.index);
+        var _name2 = appendPath(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 = appendPathSegment(intent.payload.name, intent.payload.index);
-        var _value = getValueAtPath(meta.defaultValue, _name3);
+        var _name3 = appendPath(intent.payload.name, intent.payload.index);
+        var _value = getPathValue(meta.defaultValue, _name3);
         updateValue(meta, _name3, _value);
         if (_name3) {
           setState(meta.validated, _name3, () => undefined);
@@ -137,7 +137,7 @@ function handleIntent(meta, intent, fields, initialized) {
   var validatedFields = (_fields$filter = fields === null || fields === void 0 ? void 0 : fields.filter(name => meta.validated[name])) !== null && _fields$filter !== void 0 ? _fields$filter : [];
   meta.error = Object.entries(meta.error).reduce((result, _ref3) => {
     var [name, error] = _ref3;
-    if (meta.validated[name] || validatedFields.some(field => isPrefix(name, field))) {
+    if (meta.validated[name] || validatedFields.some(field => isPathPrefix(name, field))) {
       result[name] = error;
     }
     return result;
@@ -155,8 +155,8 @@ function updateValue(meta, name, value) {
   meta.initialValue = clone(meta.initialValue);
   meta.value = clone(meta.value);
   meta.key = clone(meta.key);
-  setValueAtPath(meta.initialValue, name, () => value);
-  setValueAtPath(meta.value, name, () => value);
+  setPathValue(meta.initialValue, name, () => value);
+  setPathValue(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 path = getPathSegments(name);
-    var basename = formatPathSegments(path.slice(0, -1));
-    var key = formatPathSegments(path.slice(-1));
+    var path = parsePath(name);
+    var basename = formatPath(path.slice(0, -1));
+    var key = formatPath(path.slice(-1));
     var parentValue = proxy[basename];
-    return getValueAtPath(parentValue, key);
+    return getPathValue(parentValue, key);
   });
 }
 function createConstraintProxy(constraint) {
@@ -193,7 +193,7 @@ function createConstraintProxy(constraint) {
     var _result;
     var result = constraint[name];
     if (!result) {
-      var path = getPathSegments(name);
+      var path = parsePath(name);
       for (var i = path.length - 1; i >= 0; i--) {
         var segment = path[i];
 
@@ -206,7 +206,7 @@ function createConstraintProxy(constraint) {
           break;
         }
       }
-      var alternative = formatPathSegments(path);
+      var alternative = formatPath(path);
       if (name !== alternative) {
         result = proxy[alternative];
       }
@@ -217,11 +217,11 @@ function createConstraintProxy(constraint) {
 function createKeyProxy(key) {
   return createStateProxy((name, proxy) => {
     var currentKey = key[name];
-    var segments = getPathSegments(name);
+    var segments = parsePath(name);
     if (segments.length === 0) {
       return currentKey;
     }
-    var parentKey = proxy[formatPathSegments(segments.slice(0, -1))];
+    var parentKey = proxy[formatPath(segments.slice(0, -1))];
     if (typeof parentKey === 'undefined') {
       return currentKey;
     }
@@ -235,7 +235,7 @@ function createValidProxy(error) {
       return keys.length === 0;
     }
     for (var key of keys) {
-      if (isPrefix(key, name) && typeof error[key] !== 'undefined') {
+      if (isPathPrefix(key, name) && typeof error[key] !== 'undefined') {
         return false;
       }
     }
@@ -266,7 +266,7 @@ function shouldNotify(prev, next, cache, scope) {
     var names = (_scope$name = scope.name) !== null && _scope$name !== void 0 ? _scope$name : [];
     var list = prefixes.length === 0 ? names : Array.from(new Set([...Object.keys(prev), ...Object.keys(next)]));
     var _loop = function _loop(_name4) {
-        if (prefixes.length === 0 || names.includes(_name4) || prefixes.some(prefix => isPrefix(_name4, prefix))) {
+        if (prefixes.length === 0 || names.includes(_name4) || prefixes.some(prefix => isPathPrefix(_name4, prefix))) {
           var _cache$_name;
           (_cache$_name = cache[_name4]) !== null && _cache$_name !== void 0 ? _cache$_name : cache[_name4] = compareFn(prev[_name4], next[_name4]);
           if (cache[_name4]) {
@@ -576,13 +576,13 @@ function createFormContext(options) {
       switch (intent.type) {
         case 'update':
           {
-            var _name5 = appendPathSegment(intent.payload.name, intent.payload.index);
-            var baseSegments = getPathSegments(_name5);
+            var _name5 = appendPath(intent.payload.name, intent.payload.index);
+            var baseSegments = parsePath(_name5);
             for (var element of formElement.elements) {
               if (isFieldElement(element)) {
                 var paths = getRelativePath(element.name, baseSegments);
                 if (paths) {
-                  var value = getValueAtPath(intent.payload.value, paths);
+                  var value = getPathValue(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, {
@@ -599,10 +599,10 @@ function createFormContext(options) {
           }
         case 'reset':
           {
-            var prefix = appendPathSegment(intent.payload.name, intent.payload.index);
+            var prefix = appendPath(intent.payload.name, intent.payload.index);
             for (var _element of formElement.elements) {
-              if (isFieldElement(_element) && _element.name && isPrefix(_element.name, prefix)) {
-                var _value2 = getValueAtPath(meta.defaultValue, _element.name);
+              if (isFieldElement(_element) && _element.name && isPathPrefix(_element.name, prefix)) {
+                var _value2 = getPathValue(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;

package/dist/formdata.d.ts

@@ -1,36 +1,47 @@
-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
- * getPathSegments("object.key");       // → ['object', 'key']
- * getPathSegments("array[0].content"); // → ['array', 0, 'content']
- * getPathSegments("todos[]");          // → ['todos', '']
+ * parsePath("object.key");       // → ['object', 'key']
+ * parsePath("array[0].content"); // → ['array', 0, 'content']
+ * parsePath("todos[]");          // → ['todos', '']
  * ```
  */
-export declare function getPathSegments(path: string | undefined): Array<string | number>;
+export declare function parsePath(path: string | undefined): Array<string | number>;
 /**
  * Returns a formatted name from the path segments based on the dot and bracket notation.
  *
- * @example
+ * **Example:**
  * ```js
- * formatPathSegments(['object', 'key']); // → "object.key"
- * formatPathSegments(['array', 0, 'content']); // → "array[0].content"
- * formatPathSegments(['todos', '']); // → "todos[]"
+ * formatPath(['object', 'key']); // → "object.key"
+ * formatPath(['array', 0, 'content']); // → "array[0].content"
+ * formatPath(['todos', '']); // → "todos[]"
  * ```
  */
-export declare function formatPathSegments(segments: Readonly<Array<string | number>>): string;
+export declare function formatPath(segments: Readonly<Array<string | number>>): string;
 /**
  * Append one more segment onto an existing path string.
  *
@@ -39,53 +50,54 @@ export declare function formatPathSegments(segments: Readonly<Array<string | num
  * - segment = `number`     ⇒ bracket notation "[n]"
  * - segment = `string`     ⇒ dot-notation ".prop"
  */
-export declare function appendPathSegment(path: string | undefined, segment: string | number | undefined): string;
+export declare function appendPath(path: string | undefined, segment: string | number | undefined): string;
 /**
  * Returns true if `prefix` is a valid leading path of `name`.
  *
- * @example
+ * **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
+ * isPathPrefix("foo.bar.baz", "foo.bar")        // → true
+ * isPathPrefix("foo.bar[3].baz", "foo.bar[3]")  // → true
+ * isPathPrefix("foo.bar[3].baz", "foo.bar")     // → true
+ * isPathPrefix("foo.bar[3].baz", "foo.baz")     // → false
+ * isPathPrefix("foo", "foo.bar")                // → false
  * ```
  */
-export declare function isPrefix(name: string, prefix: string): boolean;
+export declare function isPathPrefix(name: string, prefix: string): boolean;
 /**
- * Return the segments of `fullPathStr` that come after the `baseSegments` prefix.
+ * Return the segments of `fullPath` that come after the `basePath` 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`
+ * @param fullPath     Full path as a dot/bracket string or array of segments
+ * @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"]
  * getRelativePath("foo", ["foo","bar"])             // → null
  * ```
  */
-export declare function getRelativePath(name: string, basePath: Array<string | number>): Array<string | number> | null;
+export declare function getRelativePath(fullPath: string | Array<string | number>, basePath: string | Array<string | number>): Array<string | number> | null;
 /**
  * Assign a value to a target object by following the path segments.
  */
-export declare function setValueAtPath<T extends Record<string, any>>(target: T, pathOrSegments: string | Array<string | number>, valueOrFn: unknown | ((current: unknown) => unknown), options?: {
+export declare function setPathValue<T extends Record<string, any>>(target: T, pathOrSegments: string | Array<string | number>, valueOrFn: unknown | ((current: unknown) => unknown), options?: {
     clone?: boolean;
     silent?: boolean;
 }): T;
 /**
  * Retrive the value from a target object by following the path segments.
  */
-export declare function getValueAtPath(target: unknown, pathOrSegments: string | Array<string | number>): unknown;
+export declare function getPathValue(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 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();
  *
@@ -122,8 +134,11 @@ export declare function parseSubmission(formData: FormData | URLSearchParams, op
     skipEntry?: (name: string) => boolean;
     /**
      * Whether to strip empty values (empty strings, empty files, arrays with all empty values)
-     * from the submission payload. Defaults to `true`.
-     * Set to `false` to preserve empty values in the payload.
+     * from the submission payload. Defaults to `false`.
+     *
+     * @deprecated This option will be removed in a future minor release.
+     * If you are using a schema library like Zod or Valibot, our integration
+     * already strips empty values for you. There is no need to use this option.
      */
     stripEmptyValues?: boolean;
 }): Submission;
@@ -133,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, {
@@ -158,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>>;
+}): 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[]>;
 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<string>;
+}): 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<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(
@@ -248,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 ISO string using `.toISOString()`
+     *   - 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',
@@ -278,17 +300,31 @@ formData: FormData | URLSearchParams | FormValue | null, options?: {
  * - null -> '' (empty string)
  * - boolean -> 'on' | '' (checked semantics)
  * - number | bigint -> value.toString()
- * - Date -> value.toISOString()
+ * - Date -> value.toISOString() without trailing `Z`
  * - 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 | 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`
+ * and removing empty containers (objects with no remaining keys, empty arrays).
+ *
+ * When serialize returns `undefined` for a value (i.e. it can't be represented
+ * as form data), the raw value is kept and recursed into if it's an object or array.
+ *
+ * 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, 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`
@@ -303,6 +339,7 @@ export declare function serialize(value: unknown): SerializedValue | null | unde
  * 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';