@conform-to/dom 1.13.2 → 1.14.0

package/README.md

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

package/dist/dom.d.ts

@@ -84,11 +84,6 @@ export declare function focus(element: HTMLInputElement | HTMLSelectElement | HT
 export declare function blur(element: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement): void;
 export declare function normalizeStringValues(value: unknown): string[] | undefined;
 export declare function normalizeFileValues(value: unknown): File[] | undefined;
-/**
- * Retrieves the default value of a form field element by reading the DOM's
- * defaultValue, defaultChecked, or defaultSelected properties.
- */
-export declare function getFieldDefaultValue(element: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement): string | string[] | File | File[] | FileList | null;
 /**
  * Updates the DOM element with the provided value and defaultValue.
  * If the value or defaultValue is undefined, it will keep the current value instead

package/dist/dom.js

@@ -405,43 +405,6 @@ function normalizeFileValues(value) {
   throw new Error('Expected File, FileList or File[] for file input');
 }
 
-/**
- * Retrieves the default value of a form field element by reading the DOM's
- * defaultValue, defaultChecked, or defaultSelected properties.
- */
-function getFieldDefaultValue(element) {
-  if (isInputElement(element)) {
-    switch (element.type) {
-      case 'file':
-        {
-          return null;
-        }
-      case 'checkbox':
-      case 'radio':
-        {
-          if (element.defaultChecked) {
-            return element.value;
-          }
-          return null;
-        }
-    }
-  } else if (isSelectElement(element)) {
-    if (element.multiple) {
-      var values = [];
-      for (var option of element.options) {
-        if (option.defaultSelected) {
-          values.push(option.value);
-        }
-      }
-      return values;
-    } else {
-      var selectedOption = Array.from(element.options).find(option => option.defaultSelected);
-      return selectedOption ? selectedOption.value : null;
-    }
-  }
-  return element.defaultValue;
-}
-
 /**
  * Updates the DOM element with the provided value and defaultValue.
  * If the value or defaultValue is undefined, it will keep the current value instead
@@ -591,7 +554,6 @@ exports.createFileList = createFileList;
 exports.createGlobalFormsObserver = createGlobalFormsObserver;
 exports.createSubmitEvent = createSubmitEvent;
 exports.focus = focus;
-exports.getFieldDefaultValue = getFieldDefaultValue;
 exports.getFormAction = getFormAction;
 exports.getFormEncType = getFormEncType;
 exports.getFormMethod = getFormMethod;

package/dist/dom.mjs

@@ -401,43 +401,6 @@ function normalizeFileValues(value) {
   throw new Error('Expected File, FileList or File[] for file input');
 }
 
-/**
- * Retrieves the default value of a form field element by reading the DOM's
- * defaultValue, defaultChecked, or defaultSelected properties.
- */
-function getFieldDefaultValue(element) {
-  if (isInputElement(element)) {
-    switch (element.type) {
-      case 'file':
-        {
-          return null;
-        }
-      case 'checkbox':
-      case 'radio':
-        {
-          if (element.defaultChecked) {
-            return element.value;
-          }
-          return null;
-        }
-    }
-  } else if (isSelectElement(element)) {
-    if (element.multiple) {
-      var values = [];
-      for (var option of element.options) {
-        if (option.defaultSelected) {
-          values.push(option.value);
-        }
-      }
-      return values;
-    } else {
-      var selectedOption = Array.from(element.options).find(option => option.defaultSelected);
-      return selectedOption ? selectedOption.value : null;
-    }
-  }
-  return element.defaultValue;
-}
-
 /**
  * Updates the DOM element with the provided value and defaultValue.
  * If the value or defaultValue is undefined, it will keep the current value instead
@@ -581,4 +544,4 @@ function isDirtyInput(element) {
   return false;
 }
 
-export { blur, change, createFileList, createGlobalFormsObserver, createSubmitEvent, focus, getFieldDefaultValue, getFormAction, getFormEncType, getFormMethod, isDirtyInput, isFieldElement, isGlobalInstance, isInputElement, isSelectElement, isSubmitter, isTextAreaElement, normalizeFileValues, normalizeStringValues, requestIntent, requestSubmit, updateField };
+export { blur, change, createFileList, createGlobalFormsObserver, createSubmitEvent, focus, getFormAction, getFormEncType, getFormMethod, isDirtyInput, isFieldElement, isGlobalInstance, isInputElement, isSelectElement, isSubmitter, isTextAreaElement, normalizeFileValues, normalizeStringValues, requestIntent, requestSubmit, updateField };

package/dist/formdata.d.ts

@@ -120,9 +120,15 @@ export declare function parseSubmission(formData: FormData | URLSearchParams, op
      * Return `true` to skip the entry.
      */
     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.
+     */
+    stripEmptyValues?: boolean;
 }): Submission;
 /**
- * Creates a SubmissionResult object from a submission, adding validation results and intended values.
+ * Creates a SubmissionResult object from a submission, adding validation results and target 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.
@@ -159,7 +165,7 @@ export declare function report<ErrorShape = string>(submission: Submission, opti
         formErrors?: ErrorShape[];
         fieldErrors?: Record<string, ErrorShape[]>;
     } | null;
-    intendedValue?: Record<string, FormValue> | null;
+    value?: Record<string, FormValue> | null;
     hideFields?: string[];
     reset?: boolean;
 }): SubmissionResult<ErrorShape, Exclude<JsonPrimitive | FormDataEntryValue, File>>;
@@ -170,7 +176,7 @@ export declare function report<ErrorShape = string>(submission: Submission, opti
         formErrors?: ErrorShape[];
         fieldErrors?: Record<string, ErrorShape[]>;
     } | null;
-    intendedValue?: Record<string, FormValue> | null;
+    value?: Record<string, FormValue> | null;
     hideFields?: string[];
     reset?: boolean;
 }): SubmissionResult<ErrorShape>;
@@ -181,7 +187,7 @@ export declare function report(submission: Submission, options?: {
         formErrors?: string[];
         fieldErrors?: Record<string, string[]>;
     };
-    intendedValue?: Record<string, FormValue> | null;
+    value?: Record<string, FormValue> | null;
     hideFields?: string[];
     reset?: boolean;
 }): SubmissionResult<string, Exclude<JsonPrimitive | FormDataEntryValue, File>>;
@@ -192,7 +198,7 @@ export declare function report(submission: Submission, options?: {
         formErrors?: string[];
         fieldErrors?: Record<string, string[]>;
     };
-    intendedValue?: Record<string, FormValue> | null;
+    value?: Record<string, FormValue> | null;
     hideFields?: string[];
     reset?: boolean;
 }): SubmissionResult<string>;

package/dist/formdata.js

@@ -237,6 +237,28 @@ function getValueAtPath(target, pathOrSegments) {
   return pointer;
 }
 
+/**
+ * Check if a form value is considered empty and should be stripped from the submission.
+ * A value is empty if:
+ * - It's an empty string ""
+ * - It's an empty File (size 0 and name "")
+ * - It's an array where all items are empty
+ */
+function isEmptyValue(value) {
+  if (value === '' || value === undefined) {
+    return true;
+  }
+  if (dom.isGlobalInstance(value, 'File')) {
+    // Empty File has size 0 and empty name
+    return value.size === 0 && value.name === '';
+  }
+  if (Array.isArray(value)) {
+    // If array is empty or all items are empty, consider it empty
+    return value.length === 0 || value.every(item => isEmptyValue(item));
+  }
+  return false;
+}
+
 /**
  * Parse `FormData` or `URLSearchParams` into a submission object.
  * This function structures the form values based on the naming convention.
@@ -278,8 +300,30 @@ function parseSubmission(formData, options) {
   for (var _name of new Set(formData.keys())) {
     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);
-      setValueAtPath(submission.payload, _name, _value.length > 1 ? _value : _value[0], {
+      var segments = getPathSegments(_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];
+      }
+
+      // 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;
+      if (stripEmptyValues) {
+        // For arrays, filter out individual empty items
+        if (Array.isArray(_value)) {
+          _value = _value.filter(item => !isEmptyValue(item));
+        }
+        if (isEmptyValue(_value)) {
+          _value = undefined;
+        }
+      }
+      setValueAtPath(submission.payload, segments, _value, {
         silent: true // Avoid errors if the path is invalid
       });
       submission.fields.push(_name);
@@ -296,7 +340,7 @@ function parseSubmission(formData, options) {
 }
 
 /**
- * Creates a SubmissionResult object from a submission, adding validation results and intended values.
+ * Creates a SubmissionResult object from a submission, adding validation results and target 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.
@@ -328,6 +372,7 @@ function parseSubmission(formData, options) {
  */
 
 function report(submission) {
+  var _options$value;
   var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
   var error;
   if (options.error == null) {
@@ -351,13 +396,13 @@ function report(submission) {
       }
     }
   }
-  var intendedValue = options.reset ? null : typeof options.intendedValue === 'undefined' || submission.payload === options.intendedValue ? undefined : options.intendedValue && !options.keepFiles ? util.stripFiles(options.intendedValue) : options.intendedValue;
+  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);
-      if (intendedValue) {
-        setValueAtPath(intendedValue, path, undefined);
+      if (targetValue) {
+        setValueAtPath(targetValue, path, undefined);
       }
     }
   }
@@ -365,7 +410,8 @@ function report(submission) {
     submission: options.keepFiles ? submission : _rollupPluginBabelHelpers.objectSpread2(_rollupPluginBabelHelpers.objectSpread2({}, submission), {}, {
       payload: util.stripFiles(submission.payload)
     }),
-    intendedValue,
+    reset: options.reset,
+    targetValue,
     error
   };
 }

package/dist/formdata.mjs

@@ -233,6 +233,28 @@ function getValueAtPath(target, pathOrSegments) {
   return pointer;
 }
 
+/**
+ * Check if a form value is considered empty and should be stripped from the submission.
+ * A value is empty if:
+ * - It's an empty string ""
+ * - It's an empty File (size 0 and name "")
+ * - It's an array where all items are empty
+ */
+function isEmptyValue(value) {
+  if (value === '' || value === undefined) {
+    return true;
+  }
+  if (isGlobalInstance(value, 'File')) {
+    // Empty File has size 0 and empty name
+    return value.size === 0 && value.name === '';
+  }
+  if (Array.isArray(value)) {
+    // If array is empty or all items are empty, consider it empty
+    return value.length === 0 || value.every(item => isEmptyValue(item));
+  }
+  return false;
+}
+
 /**
  * Parse `FormData` or `URLSearchParams` into a submission object.
  * This function structures the form values based on the naming convention.
@@ -274,8 +296,30 @@ function parseSubmission(formData, options) {
   for (var _name of new Set(formData.keys())) {
     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);
-      setValueAtPath(submission.payload, _name, _value.length > 1 ? _value : _value[0], {
+      var segments = getPathSegments(_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];
+      }
+
+      // 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;
+      if (stripEmptyValues) {
+        // For arrays, filter out individual empty items
+        if (Array.isArray(_value)) {
+          _value = _value.filter(item => !isEmptyValue(item));
+        }
+        if (isEmptyValue(_value)) {
+          _value = undefined;
+        }
+      }
+      setValueAtPath(submission.payload, segments, _value, {
         silent: true // Avoid errors if the path is invalid
       });
       submission.fields.push(_name);
@@ -292,7 +336,7 @@ function parseSubmission(formData, options) {
 }
 
 /**
- * Creates a SubmissionResult object from a submission, adding validation results and intended values.
+ * Creates a SubmissionResult object from a submission, adding validation results and target 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.
@@ -324,6 +368,7 @@ function parseSubmission(formData, options) {
  */
 
 function report(submission) {
+  var _options$value;
   var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
   var error;
   if (options.error == null) {
@@ -347,13 +392,13 @@ function report(submission) {
       }
     }
   }
-  var intendedValue = options.reset ? null : typeof options.intendedValue === 'undefined' || submission.payload === options.intendedValue ? undefined : options.intendedValue && !options.keepFiles ? stripFiles(options.intendedValue) : options.intendedValue;
+  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 = getPathSegments(_name3);
       setValueAtPath(submission.payload, path, undefined);
-      if (intendedValue) {
-        setValueAtPath(intendedValue, path, undefined);
+      if (targetValue) {
+        setValueAtPath(targetValue, path, undefined);
       }
     }
   }
@@ -361,7 +406,8 @@ function report(submission) {
     submission: options.keepFiles ? submission : _objectSpread2(_objectSpread2({}, submission), {}, {
       payload: stripFiles(submission.payload)
     }),
-    intendedValue,
+    reset: options.reset,
+    targetValue,
     error
   };
 }

package/dist/future/index.d.ts

@@ -1,6 +1,6 @@
 export type { Serialize, FormValue, FormError, Submission, SubmissionResult, ValidationAttributes, } from '../types';
 export { DEFAULT_INTENT_NAME, getFormData, isDirty, parseSubmission, getPathSegments, formatPathSegments, appendPathSegment, getRelativePath, getValueAtPath, setValueAtPath, report, serialize, } from '../formdata';
 export { isPlainObject, deepEqual } from '../util';
-export { isFieldElement, isGlobalInstance, updateField, createFileList, createSubmitEvent, createGlobalFormsObserver, focus, change, blur, getFieldDefaultValue, getFormAction, getFormEncType, getFormMethod, requestSubmit, requestIntent, } from '../dom';
+export { isFieldElement, isGlobalInstance, updateField, createFileList, createSubmitEvent, createGlobalFormsObserver, focus, change, blur, getFormAction, getFormEncType, getFormMethod, requestSubmit, requestIntent, } from '../dom';
 export { formatIssues } from '../standard-schema';
 //# sourceMappingURL=index.d.ts.map

package/dist/future/index.js

@@ -29,7 +29,6 @@ exports.createFileList = dom.createFileList;
 exports.createGlobalFormsObserver = dom.createGlobalFormsObserver;
 exports.createSubmitEvent = dom.createSubmitEvent;
 exports.focus = dom.focus;
-exports.getFieldDefaultValue = dom.getFieldDefaultValue;
 exports.getFormAction = dom.getFormAction;
 exports.getFormEncType = dom.getFormEncType;
 exports.getFormMethod = dom.getFormMethod;

package/dist/future/index.mjs

@@ -1,4 +1,4 @@
 export { DEFAULT_INTENT_NAME, appendPathSegment, formatPathSegments, getFormData, getPathSegments, getRelativePath, getValueAtPath, isDirty, parseSubmission, report, serialize, setValueAtPath } from '../formdata.mjs';
 export { deepEqual, isPlainObject } from '../util.mjs';
-export { blur, change, createFileList, createGlobalFormsObserver, createSubmitEvent, focus, getFieldDefaultValue, getFormAction, getFormEncType, getFormMethod, isFieldElement, isGlobalInstance, requestIntent, requestSubmit, updateField } from '../dom.mjs';
+export { blur, change, createFileList, createGlobalFormsObserver, createSubmitEvent, focus, getFormAction, getFormEncType, getFormMethod, isFieldElement, isGlobalInstance, requestIntent, requestSubmit, updateField } from '../dom.mjs';
 export { formatIssues } from '../standard-schema.mjs';

package/dist/types.d.ts

@@ -29,6 +29,21 @@ 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
+     * ```json
+     * {
+     *   "username": "johndoe",
+     *   "address": {
+     *     "street": "123 Main St",
+     *     "city": "Anytown"
+     *   },
+     *   "items": [
+     *     { "name": "item1", "quantity": "2" },
+     *     { "name": "item2", "quantity": "5" }
+     *   ]
+     * }
+     * ```
      */
     payload: Record<string, FormValue<ValueType>>;
     /**
@@ -49,27 +64,31 @@ export type SubmissionResult<ErrorShape = string, ValueType extends JsonPrimitiv
      */
     submission: Submission<ValueType>;
     /**
-     * The intended value of the submission. Defined only when the intended value is different from the submitted value.
+     * The target value of the submission. Defined only when the target value is different from the submitted value.
      */
-    intendedValue?: Record<string, FormValue<ValueType>> | null;
+    targetValue?: Record<string, FormValue<ValueType>>;
     /**
-     * Validation errors for `intendedValue` when present, otherwise for the original payload.
+     * Validation errors for `targetValue` when present, otherwise for the original payload.
      */
     error?: FormError<ErrorShape> | null;
+    /**
+     * Indicates whether the form should be reset to its initial state.
+     */
+    reset?: boolean;
 };
 /**
  * The input attributes with related to the Constraint Validation API
  * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation
  */
 export type ValidationAttributes = {
-    required?: boolean;
-    minLength?: number;
-    maxLength?: number;
-    min?: string | number;
-    max?: string | number;
-    step?: string | number;
-    multiple?: boolean;
-    pattern?: string;
+    required?: boolean | undefined;
+    minLength?: number | undefined;
+    maxLength?: number | undefined;
+    min?: string | number | undefined;
+    max?: string | number | undefined;
+    step?: string | number | undefined;
+    multiple?: boolean | undefined;
+    pattern?: string | undefined;
 };
 /**
  * A type helper that makes sure the FormError type is serializable.

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.13.2",
+  "version": "1.14.0",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",