@conform-to/dom 1.17.1 → 1.19.0

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,14 +73,14 @@ function getFormData(form, submitter) {
 /**
  * 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', '']
  * ```
  */
-function getPathSegments(path) {
+function parsePath(path) {
   if (!path) return [];
   var tokenRegex = /([^.[\]]+)|\[(\d*)\]/g;
   var segments = [];
@@ -83,15 +119,15 @@ function getPathSegments(path) {
 /**
  * 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[]"
  * ```
  */
-function formatPathSegments(segments) {
-  return segments.reduce((path, segment) => appendPathSegment(path, segment), '');
+function formatPath(segments) {
+  return segments.reduce((path, segment) => appendPath(path, segment), '');
 }
 
 /**
@@ -102,63 +138,66 @@ function formatPathSegments(segments) {
  * - segment = `number`     ⇒ bracket notation "[n]"
  * - segment = `string`     ⇒ dot-notation ".prop"
  */
-function appendPathSegment(path, segment) {
+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
- * 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
  * ```
  */
-function isPrefix(name, prefix) {
-  return getRelativePath(name, getPathSegments(prefix)) !== null;
+function isPathPrefix(name, prefix) {
+  return getRelativePath(name, parsePath(prefix)) !== null;
 }
 
 /**
- * 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
  * ```
  */
-function getRelativePath(name, basePath) {
-  var fullPath = getPathSegments(name);
+function getRelativePath(fullPath, basePath) {
+  var fullPathSegments = typeof fullPath === 'string' ? parsePath(fullPath) : fullPath;
+  var basePathSegments = typeof basePath === 'string' ? parsePath(basePath) : basePath;
 
   // if full is at least as long *and* starts with the base…
-  if (fullPath.length >= basePath.length && basePath.every((segment, i) => segment === fullPath[i])) {
-    return fullPath.slice(basePath.length);
+  if (fullPathSegments.length >= basePathSegments.length && basePathSegments.every((segment, i) => segment === fullPathSegments[i])) {
+    return fullPathSegments.slice(basePathSegments.length);
   }
   return null;
 }
@@ -166,11 +205,11 @@ function getRelativePath(name, basePath) {
 /**
  * Assign a value to a target object by following the path segments.
  */
-function setValueAtPath(target, pathOrSegments, valueOrFn) {
+function setPathValue(target, pathOrSegments, valueOrFn) {
   var options = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : {};
   try {
     // 1) normalize + validate path
-    var segments = typeof pathOrSegments === 'string' ? getPathSegments(pathOrSegments) : pathOrSegments;
+    var segments = typeof pathOrSegments === 'string' ? parsePath(pathOrSegments) : pathOrSegments;
     if (segments.length === 0) {
       throw new Error('Cannot set value at the object root');
     }
@@ -222,9 +261,9 @@ function setValueAtPath(target, pathOrSegments, valueOrFn) {
 /**
  * Retrive the value from a target object by following the path segments.
  */
-function getValueAtPath(target, pathOrSegments) {
+function getPathValue(target, pathOrSegments) {
   var pointer = target;
-  var segments = typeof pathOrSegments === 'string' ? getPathSegments(pathOrSegments) : pathOrSegments;
+  var segments = typeof pathOrSegments === 'string' ? parsePath(pathOrSegments) : pathOrSegments;
   for (var segment of segments) {
     if (segment === '') {
       throw new Error("Cannot access empty segment \"[]\" in \"".concat(pathOrSegments, "\""));
@@ -264,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();
  *
@@ -301,29 +341,27 @@ 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 segments = getPathSegments(_name);
+      var value = formData.getAll(_name);
+      var segments = parsePath(_name);
 
       // If the name ends with [], remove the empty segment and keep the full array
       // Otherwise, unwrap single values
       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];
       }
-
-      // Check if the value is empty and should be skipped (defaults to true)
-      var stripEmptyValues = (_options$stripEmptyVa = options === null || options === void 0 ? void 0 : options.stripEmptyValues) !== null && _options$stripEmptyVa !== void 0 ? _options$stripEmptyVa : true;
+      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;
         }
       }
-      setValueAtPath(submission.payload, segments, _value, {
+      setPathValue(submission.payload, segments, value, {
         silent: true // Avoid errors if the path is invalid
       });
       submission.fields.push(_name);
@@ -345,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, {
@@ -377,32 +416,19 @@ 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 = getPathSegments(_name3);
-      setValueAtPath(submission.payload, path, undefined);
+    for (var _name2 of options.hideFields) {
+      var path = parsePath(_name2);
+      setPathValue(submission.payload, path, undefined);
       if (targetValue) {
-        setValueAtPath(targetValue, path, undefined);
+        setPathValue(targetValue, path, undefined);
       }
     }
   }
@@ -419,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(
@@ -451,59 +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 serializeData = value => {
+  var serialize = (value, context) => {
     if (options !== null && options !== void 0 && options.serialize) {
-      return options.serialize(value, serialize);
+      return options.serialize(value, {
+        name: context.name,
+        defaultSerialize
+      });
     }
-    return serialize(value);
+    return defaultSerialize(value);
   };
-  function normalize(data) {
-    var value = serializeData(data);
-    if (typeof value === 'undefined') {
-      value = data;
-    }
-
-    // Removes empty strings, so that both empty string, empty file, null and undefined are treated as the same
-    if (value === '' || value === null) {
-      return undefined;
-    }
-    if (dom.isGlobalInstance(value, 'File')) {
-      // Remove empty File as well, which happens if no File was selected
-      if (value.name === '' && value.size === 0) {
-        return undefined;
-      }
-
-      // If the value is a File, no need to serialize it
-      return value;
-    }
-    if (Array.isArray(value)) {
-      if (value.length === 0) {
-        return undefined;
-      }
-      var array = value.map(normalize);
-      if (array.length === 1 && (typeof array[0] === 'string' || array[0] === undefined)) {
-        return array[0];
-      }
-      return array;
-    }
-    if (util.isPlainObject(value)) {
-      var entries = Object.entries(value).reduce((list, _ref) => {
-        var [key, value] = _ref;
-        var normalizedValue = normalize(value);
-        if (typeof normalizedValue !== 'undefined') {
-          list.push([key, normalizedValue]);
-        }
-        return list;
-      }, []);
-      if (entries.length === 0) {
-        return undefined;
-      }
-      return Object.fromEntries(entries);
-    }
-    return value;
-  }
-  return !util.deepEqual(normalize(formValue), normalize(defaultValue));
+  return !util.deepEqual(normalize(formValue, serialize), normalize(options === null || options === void 0 ? void 0 : options.defaultValue, serialize));
 }
 
 /**
@@ -515,25 +499,25 @@ formData, 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
  */
-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();
     }
     if (value instanceof Date) {
-      return value.toISOString();
+      return value.toISOString().slice(0, -1);
     }
     if (dom.isGlobalInstance(value, 'File')) {
       return value;
@@ -576,10 +560,68 @@ function serialize(value) {
   return serializePrimitive(value);
 }
 
+/**
+ * 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.
+ */
+function normalize(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;
+  }
+  if (data === '' || data === null) {
+    return undefined;
+  }
+  if (dom.isGlobalInstance(data, 'File')) {
+    if (data.name === '' && data.size === 0) {
+      return undefined;
+    }
+    return data;
+  }
+  if (Array.isArray(data)) {
+    if (data.length === 0) {
+      return undefined;
+    }
+    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, _ref2) => {
+      var [key, value] = _ref2;
+      var normalizedValue = normalize(value, serialize, appendPath(name, key));
+      if (typeof normalizedValue !== 'undefined') {
+        list.push([key, normalizedValue]);
+      }
+      return list;
+    }, []);
+    if (entries.length === 0) {
+      return undefined;
+    }
+    return Object.fromEntries(entries);
+  }
+  return data;
+}
+
 /**
  * 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`
@@ -594,6 +636,7 @@ function serialize(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) {
@@ -609,11 +652,9 @@ function getFieldValue(formData, name, options) {
     // Get value based on array option
     value = array ? formData.getAll(name) : formData.get(name);
   } else {
-    // Parse formData and use getValueAtPath
-    var _submission = parseSubmission(formData, {
-      stripEmptyValues: false
-    });
-    value = getValueAtPath(_submission.payload, name);
+    // Parse formData and use getPathValue
+    var _submission = parseSubmission(formData);
+    value = getPathValue(_submission.payload, name);
   }
 
   // If optional and value is undefined, skip validation and return early
@@ -648,16 +689,19 @@ function getFieldValue(formData, name, options) {
 }
 
 exports.DEFAULT_INTENT_NAME = DEFAULT_INTENT_NAME;
-exports.appendPathSegment = appendPathSegment;
-exports.formatPathSegments = formatPathSegments;
+exports.appendPath = appendPath;
+exports.defaultSerialize = defaultSerialize;
+exports.formatPath = formatPath;
 exports.getFieldValue = getFieldValue;
 exports.getFormData = getFormData;
-exports.getPathSegments = getPathSegments;
+exports.getPathValue = getPathValue;
 exports.getRelativePath = getRelativePath;
-exports.getValueAtPath = getValueAtPath;
+exports.hasError = hasError;
 exports.isDirty = isDirty;
-exports.isPrefix = isPrefix;
+exports.isPathPrefix = isPathPrefix;
+exports.normalize = normalize;
+exports.normalizeFormError = normalizeFormError;
+exports.parsePath = parsePath;
 exports.parseSubmission = parseSubmission;
 exports.report = report;
-exports.serialize = serialize;
-exports.setValueAtPath = setValueAtPath;
+exports.setPathValue = setPathValue;