@conform-to/dom 1.7.2 → 1.8.1

package/README.md

@@ -7,7 +7,7 @@
  ╚══════╝  ╚═════╝  ╚═╝  ╚══╝ ╚═╝        ╚═════╝  ╚═╝   ╚═╝ ╚═╝   ╚═╝
 ```
 
-Version 1.7.2 / License MIT / Copyright (c) 2024 Edmund Hung
+Version 1.8.1 / License MIT / Copyright (c) 2024 Edmund Hung
 
 A type-safe form validation library utilizing web fundamentals to progressively enhance HTML Forms with full support for server frameworks like Remix and Next.js.
 

package/dist/dom.d.ts

@@ -53,9 +53,11 @@ export declare function createGlobalFormsObserver(): {
 export declare function change(element: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement, value: string | string[] | File | File[] | FileList | null): void;
 export declare function focus(element: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement): void;
 export declare function blur(element: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement): void;
-export declare function normalizeFieldValue(value: unknown): [string[] | null, FileList | null];
+export declare function normalizeStringValues(value: unknown): string[] | undefined;
+export declare function normalizeFileValues(value: unknown): FileList | undefined;
 /**
  * Updates the DOM element with the provided value and defaultValue.
+ * If the value or defaultValue is undefined, it will keep the current value instead
  */
 export declare function updateField(element: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement, options: {
     value?: unknown;

package/dist/dom.js

@@ -2,6 +2,7 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
+var formdata = require('./formdata.js');
 var util = require('./util.js');
 
 /**
@@ -121,6 +122,8 @@ function createGlobalFormsObserver() {
     observer.observe(document.body, {
       subtree: true,
       childList: true,
+      attributes: true,
+      attributeOldValue: true,
       attributeFilter: ['form', 'name', 'data-conform']
     });
     document.addEventListener('input', handleInput);
@@ -187,6 +190,15 @@ function createGlobalFormsObserver() {
       }));
     }
   }
+  function getAssociatedFormElement(formId, node) {
+    if (formId !== null) {
+      return document.forms.namedItem(formId);
+    }
+    if (node instanceof Element) {
+      return node.closest('form');
+    }
+    return null;
+  }
   function handleMutation(mutations) {
     var seenForms = new Set();
     var seenInputs = new Set();
@@ -196,16 +208,27 @@ function createGlobalFormsObserver() {
       }
       return node instanceof Element ? Array.from(node.querySelectorAll('input,select,textarea')) : [];
     };
+    var collectForms = node => {
+      if (node instanceof HTMLFormElement) {
+        return [node];
+      }
+      return node instanceof Element ? Array.from(node.querySelectorAll('form')) : [];
+    };
     for (var mutation of mutations) {
       switch (mutation.type) {
         case 'childList':
           {
             var nodes = [...mutation.addedNodes, ...mutation.removedNodes];
             for (var node of nodes) {
+              for (var form of collectForms(node)) {
+                seenForms.add(form);
+              }
               for (var input of collectInputs(node)) {
+                var _input$form;
                 seenInputs.add(input);
-                if (input.form) {
-                  seenForms.add(input.form);
+                var _form = (_input$form = input.form) !== null && _input$form !== void 0 ? _input$form : getAssociatedFormElement(input.getAttribute('form'), mutation.target);
+                if (_form) {
+                  seenForms.add(_form);
                 }
               }
             }
@@ -218,6 +241,12 @@ function createGlobalFormsObserver() {
               if (mutation.target.form) {
                 seenForms.add(mutation.target.form);
               }
+              if (mutation.attributeName === 'form') {
+                var oldForm = getAssociatedFormElement(mutation.oldValue, mutation.target);
+                if (oldForm) {
+                  seenForms.add(oldForm);
+                }
+              }
             }
             break;
           }
@@ -301,69 +330,68 @@ function blur(element) {
   }));
   element.dispatchEvent(new FocusEvent('blur'));
 }
-function normalizeFieldValue(value) {
-  if (typeof value === 'undefined') {
-    return [null, null];
-  }
-  if (value === null) {
-    return [[], createFileList([])];
+function normalizeStringValues(value) {
+  if (typeof value === 'undefined') return undefined;
+  if (value === null) return [];
+  if (typeof value === 'string') return [value];
+  if (Array.isArray(value) && value.every(v => typeof v === 'string')) {
+    return Array.from(value);
   }
-  if (typeof value === 'string') {
-    return [[value], null];
-  }
-  if (Array.isArray(value)) {
-    if (value.every(item => typeof item === 'string')) {
-      return [Array.from(value), null];
-    }
-    if (value.every(item => item instanceof File)) {
-      return [null, createFileList(value)];
-    }
-  }
-  if (value instanceof FileList) {
-    return [null, value];
-  }
-  if (value instanceof File) {
-    return [null, createFileList([value])];
+  throw new Error('Expected string or string[] value for string based input');
+}
+function normalizeFileValues(value) {
+  if (typeof value === 'undefined') return undefined;
+  if (value === null) return createFileList([]);
+  if (formdata.isGlobalInstance(value, 'File')) return createFileList([value]);
+  if (formdata.isGlobalInstance(value, 'FileList')) return value;
+  if (Array.isArray(value) && value.every(item => formdata.isGlobalInstance(item, 'File'))) {
+    return createFileList(value);
   }
-  return [null, null];
+  throw new Error('Expected File, FileList or File[] for file input');
 }
 
 /**
  * Updates the DOM element with the provided value and defaultValue.
+ * If the value or defaultValue is undefined, it will keep the current value instead
  */
 function updateField(element, options) {
   var _value$;
-  var [value, file] = normalizeFieldValue(options.value);
-  var [defaultValue] = normalizeFieldValue(options.defaultValue);
   if (isInputElement(element)) {
     switch (element.type) {
       case 'file':
         {
-          element.files = file;
+          var files = normalizeFileValues(options.value);
+          if (files) {
+            element.files = files;
+          }
           return;
         }
       case 'checkbox':
       case 'radio':
         {
-          if (value) {
-            var checked = value.includes(element.value);
+          var _value = normalizeStringValues(options.value);
+          var _defaultValue = normalizeStringValues(options.defaultValue);
+          if (_value) {
+            var checked = _value.includes(element.value);
             if (element.type === 'checkbox' ? checked !== element.checked : checked) {
               // Simulate a click to update the checked state
               element.click();
             }
             element.checked = checked;
           }
-          if (defaultValue) {
-            element.defaultChecked = defaultValue.includes(element.value);
+          if (_defaultValue) {
+            element.defaultChecked = _defaultValue.includes(element.value);
           }
           return;
         }
     }
   } else if (isSelectElement(element)) {
-    var shouldUnselect = value && value.length === 0;
+    var _value2 = normalizeStringValues(options.value);
+    var _defaultValue2 = normalizeStringValues(options.defaultValue);
+    var shouldUnselect = _value2 && _value2.length === 0;
     for (var option of element.options) {
-      if (value) {
-        var index = value.indexOf(option.value);
+      if (_value2) {
+        var index = _value2.indexOf(option.value);
         var selected = index > -1;
 
         // Update the selected state of the option
@@ -373,11 +401,11 @@ function updateField(element, options) {
 
         // Remove the option from the value array
         if (selected) {
-          value.splice(index, 1);
+          _value2.splice(index, 1);
         }
       }
-      if (defaultValue) {
-        var _index = defaultValue.indexOf(option.value);
+      if (_defaultValue2) {
+        var _index = _defaultValue2.indexOf(option.value);
         var _selected = _index > -1;
 
         // Update the selected state of the option
@@ -387,15 +415,15 @@ function updateField(element, options) {
 
         // Remove the option from the defaultValue array
         if (_selected) {
-          defaultValue.splice(_index, 1);
+          _defaultValue2.splice(_index, 1);
         }
       }
     }
 
     // We have already removed all selected options from the value and defaultValue array at this point
-    var missingOptions = new Set([...(value !== null && value !== void 0 ? value : []), ...(defaultValue !== null && defaultValue !== void 0 ? defaultValue : [])]);
+    var missingOptions = new Set([...(_value2 !== null && _value2 !== void 0 ? _value2 : []), ...(_defaultValue2 !== null && _defaultValue2 !== void 0 ? _defaultValue2 : [])]);
     for (var optionValue of missingOptions) {
-      element.options.add(new Option(optionValue, optionValue, defaultValue === null || defaultValue === void 0 ? void 0 : defaultValue.includes(optionValue), value === null || value === void 0 ? void 0 : value.includes(optionValue)));
+      element.options.add(new Option(optionValue, optionValue, _defaultValue2 === null || _defaultValue2 === void 0 ? void 0 : _defaultValue2.includes(optionValue), _value2 === null || _value2 === void 0 ? void 0 : _value2.includes(optionValue)));
     }
 
     // If the select element is not multiple and the value is an empty array, unset the selected index
@@ -405,6 +433,8 @@ function updateField(element, options) {
     }
     return;
   }
+  var value = normalizeStringValues(options.value);
+  var defaultValue = normalizeStringValues(options.defaultValue);
   var inputValue = (_value$ = value === null || value === void 0 ? void 0 : value[0]) !== null && _value$ !== void 0 ? _value$ : '';
   if (element.value !== inputValue) {
     /**
@@ -422,12 +452,10 @@ function updateField(element, options) {
     } = Object.getOwnPropertyDescriptor(prototype, 'value') || {};
     if (prototypeValueSetter && valueSetter !== prototypeValueSetter) {
       prototypeValueSetter.call(element, inputValue);
+    } else if (valueSetter) {
+      valueSetter.call(element, inputValue);
     } else {
-      if (valueSetter) {
-        valueSetter.call(element, inputValue);
-      } else {
-        throw new Error('The given element does not have a value setter');
-      }
+      throw new Error('The given element does not have a value setter');
     }
   }
   if (defaultValue) {
@@ -448,6 +476,7 @@ exports.isFieldElement = isFieldElement;
 exports.isInputElement = isInputElement;
 exports.isSelectElement = isSelectElement;
 exports.isTextAreaElement = isTextAreaElement;
-exports.normalizeFieldValue = normalizeFieldValue;
+exports.normalizeFileValues = normalizeFileValues;
+exports.normalizeStringValues = normalizeStringValues;
 exports.requestSubmit = requestSubmit;
 exports.updateField = updateField;

package/dist/dom.mjs

@@ -1,3 +1,4 @@
+import { isGlobalInstance } from './formdata.mjs';
 import { invariant } from './util.mjs';
 
 /**
@@ -117,6 +118,8 @@ function createGlobalFormsObserver() {
     observer.observe(document.body, {
       subtree: true,
       childList: true,
+      attributes: true,
+      attributeOldValue: true,
       attributeFilter: ['form', 'name', 'data-conform']
     });
     document.addEventListener('input', handleInput);
@@ -183,6 +186,15 @@ function createGlobalFormsObserver() {
       }));
     }
   }
+  function getAssociatedFormElement(formId, node) {
+    if (formId !== null) {
+      return document.forms.namedItem(formId);
+    }
+    if (node instanceof Element) {
+      return node.closest('form');
+    }
+    return null;
+  }
   function handleMutation(mutations) {
     var seenForms = new Set();
     var seenInputs = new Set();
@@ -192,16 +204,27 @@ function createGlobalFormsObserver() {
       }
       return node instanceof Element ? Array.from(node.querySelectorAll('input,select,textarea')) : [];
     };
+    var collectForms = node => {
+      if (node instanceof HTMLFormElement) {
+        return [node];
+      }
+      return node instanceof Element ? Array.from(node.querySelectorAll('form')) : [];
+    };
     for (var mutation of mutations) {
       switch (mutation.type) {
         case 'childList':
           {
             var nodes = [...mutation.addedNodes, ...mutation.removedNodes];
             for (var node of nodes) {
+              for (var form of collectForms(node)) {
+                seenForms.add(form);
+              }
               for (var input of collectInputs(node)) {
+                var _input$form;
                 seenInputs.add(input);
-                if (input.form) {
-                  seenForms.add(input.form);
+                var _form = (_input$form = input.form) !== null && _input$form !== void 0 ? _input$form : getAssociatedFormElement(input.getAttribute('form'), mutation.target);
+                if (_form) {
+                  seenForms.add(_form);
                 }
               }
             }
@@ -214,6 +237,12 @@ function createGlobalFormsObserver() {
               if (mutation.target.form) {
                 seenForms.add(mutation.target.form);
               }
+              if (mutation.attributeName === 'form') {
+                var oldForm = getAssociatedFormElement(mutation.oldValue, mutation.target);
+                if (oldForm) {
+                  seenForms.add(oldForm);
+                }
+              }
             }
             break;
           }
@@ -297,69 +326,68 @@ function blur(element) {
   }));
   element.dispatchEvent(new FocusEvent('blur'));
 }
-function normalizeFieldValue(value) {
-  if (typeof value === 'undefined') {
-    return [null, null];
-  }
-  if (value === null) {
-    return [[], createFileList([])];
+function normalizeStringValues(value) {
+  if (typeof value === 'undefined') return undefined;
+  if (value === null) return [];
+  if (typeof value === 'string') return [value];
+  if (Array.isArray(value) && value.every(v => typeof v === 'string')) {
+    return Array.from(value);
   }
-  if (typeof value === 'string') {
-    return [[value], null];
-  }
-  if (Array.isArray(value)) {
-    if (value.every(item => typeof item === 'string')) {
-      return [Array.from(value), null];
-    }
-    if (value.every(item => item instanceof File)) {
-      return [null, createFileList(value)];
-    }
-  }
-  if (value instanceof FileList) {
-    return [null, value];
-  }
-  if (value instanceof File) {
-    return [null, createFileList([value])];
+  throw new Error('Expected string or string[] value for string based input');
+}
+function normalizeFileValues(value) {
+  if (typeof value === 'undefined') return undefined;
+  if (value === null) return createFileList([]);
+  if (isGlobalInstance(value, 'File')) return createFileList([value]);
+  if (isGlobalInstance(value, 'FileList')) return value;
+  if (Array.isArray(value) && value.every(item => isGlobalInstance(item, 'File'))) {
+    return createFileList(value);
   }
-  return [null, null];
+  throw new Error('Expected File, FileList or File[] for file input');
 }
 
 /**
  * Updates the DOM element with the provided value and defaultValue.
+ * If the value or defaultValue is undefined, it will keep the current value instead
  */
 function updateField(element, options) {
   var _value$;
-  var [value, file] = normalizeFieldValue(options.value);
-  var [defaultValue] = normalizeFieldValue(options.defaultValue);
   if (isInputElement(element)) {
     switch (element.type) {
       case 'file':
         {
-          element.files = file;
+          var files = normalizeFileValues(options.value);
+          if (files) {
+            element.files = files;
+          }
           return;
         }
       case 'checkbox':
       case 'radio':
         {
-          if (value) {
-            var checked = value.includes(element.value);
+          var _value = normalizeStringValues(options.value);
+          var _defaultValue = normalizeStringValues(options.defaultValue);
+          if (_value) {
+            var checked = _value.includes(element.value);
             if (element.type === 'checkbox' ? checked !== element.checked : checked) {
               // Simulate a click to update the checked state
               element.click();
             }
             element.checked = checked;
           }
-          if (defaultValue) {
-            element.defaultChecked = defaultValue.includes(element.value);
+          if (_defaultValue) {
+            element.defaultChecked = _defaultValue.includes(element.value);
           }
           return;
         }
     }
   } else if (isSelectElement(element)) {
-    var shouldUnselect = value && value.length === 0;
+    var _value2 = normalizeStringValues(options.value);
+    var _defaultValue2 = normalizeStringValues(options.defaultValue);
+    var shouldUnselect = _value2 && _value2.length === 0;
     for (var option of element.options) {
-      if (value) {
-        var index = value.indexOf(option.value);
+      if (_value2) {
+        var index = _value2.indexOf(option.value);
         var selected = index > -1;
 
         // Update the selected state of the option
@@ -369,11 +397,11 @@ function updateField(element, options) {
 
         // Remove the option from the value array
         if (selected) {
-          value.splice(index, 1);
+          _value2.splice(index, 1);
         }
       }
-      if (defaultValue) {
-        var _index = defaultValue.indexOf(option.value);
+      if (_defaultValue2) {
+        var _index = _defaultValue2.indexOf(option.value);
         var _selected = _index > -1;
 
         // Update the selected state of the option
@@ -383,15 +411,15 @@ function updateField(element, options) {
 
         // Remove the option from the defaultValue array
         if (_selected) {
-          defaultValue.splice(_index, 1);
+          _defaultValue2.splice(_index, 1);
         }
       }
     }
 
     // We have already removed all selected options from the value and defaultValue array at this point
-    var missingOptions = new Set([...(value !== null && value !== void 0 ? value : []), ...(defaultValue !== null && defaultValue !== void 0 ? defaultValue : [])]);
+    var missingOptions = new Set([...(_value2 !== null && _value2 !== void 0 ? _value2 : []), ...(_defaultValue2 !== null && _defaultValue2 !== void 0 ? _defaultValue2 : [])]);
     for (var optionValue of missingOptions) {
-      element.options.add(new Option(optionValue, optionValue, defaultValue === null || defaultValue === void 0 ? void 0 : defaultValue.includes(optionValue), value === null || value === void 0 ? void 0 : value.includes(optionValue)));
+      element.options.add(new Option(optionValue, optionValue, _defaultValue2 === null || _defaultValue2 === void 0 ? void 0 : _defaultValue2.includes(optionValue), _value2 === null || _value2 === void 0 ? void 0 : _value2.includes(optionValue)));
     }
 
     // If the select element is not multiple and the value is an empty array, unset the selected index
@@ -401,6 +429,8 @@ function updateField(element, options) {
     }
     return;
   }
+  var value = normalizeStringValues(options.value);
+  var defaultValue = normalizeStringValues(options.defaultValue);
   var inputValue = (_value$ = value === null || value === void 0 ? void 0 : value[0]) !== null && _value$ !== void 0 ? _value$ : '';
   if (element.value !== inputValue) {
     /**
@@ -418,12 +448,10 @@ function updateField(element, options) {
     } = Object.getOwnPropertyDescriptor(prototype, 'value') || {};
     if (prototypeValueSetter && valueSetter !== prototypeValueSetter) {
       prototypeValueSetter.call(element, inputValue);
+    } else if (valueSetter) {
+      valueSetter.call(element, inputValue);
     } else {
-      if (valueSetter) {
-        valueSetter.call(element, inputValue);
-      } else {
-        throw new Error('The given element does not have a value setter');
-      }
+      throw new Error('The given element does not have a value setter');
     }
   }
   if (defaultValue) {
@@ -432,4 +460,4 @@ function updateField(element, options) {
   }
 }
 
-export { blur, change, createFileList, createGlobalFormsObserver, focus, getFormAction, getFormEncType, getFormMethod, isFieldElement, isInputElement, isSelectElement, isTextAreaElement, normalizeFieldValue, requestSubmit, updateField };
+export { blur, change, createFileList, createGlobalFormsObserver, focus, getFormAction, getFormEncType, getFormMethod, isFieldElement, isInputElement, isSelectElement, isTextAreaElement, normalizeFileValues, normalizeStringValues, requestSubmit, updateField };

package/dist/formdata.d.ts

@@ -64,6 +64,141 @@ export declare function flatten(data: unknown, options?: {
     resolve?: (data: unknown) => unknown;
     prefix?: string;
 }): Record<string, unknown>;
-export declare function deepEqual<Value>(prev: Value, next: Value): boolean;
+export declare function deepEqual(left: unknown, right: unknown): boolean;
+export type JsonPrimitive = string | number | boolean | null;
+/**
+ * The form value of a submission. This is usually constructed from a FormData or URLSearchParams.
+ * It may contains JSON primitives if the value is updated based on a form intent.
+ */
+export type FormValue<Type extends JsonPrimitive | FormDataEntryValue = JsonPrimitive | FormDataEntryValue> = Type | FormValue<Type | null>[] | {
+    [key: string]: FormValue<Type>;
+};
+/**
+ * The data of a form submission.
+ */
+export type Submission<ValueType extends FormDataEntryValue = FormDataEntryValue> = {
+    /**
+     * The form value structured following the naming convention.
+     */
+    value: Record<string, FormValue<ValueType>>;
+    /**
+     * The field names that are included in the FormData or URLSearchParams.
+     */
+    fields: string[];
+    /**
+     * The intent of the submission. This is usally included by specifying a name and value on a submit button.
+     */
+    intent: string | null;
+};
+/**
+ * Parse `FormData` or `URLSearchParams` into a submission object.
+ * This function structures the form values based on the naming convention.
+ * It also includes all the field names and the intent if the `intentName` option is provided.
+ *
+ * @example
+ * ```ts
+ * const formData = new FormData();
+ *
+ * formData.append('email', 'test@example.com');
+ * formData.append('password', 'secret');
+ *
+ * parseSubmission(formData)
+ * // {
+ * //   value: { email: 'test@example.com', password: 'secret' },
+ * //   fields: ['email', 'password'],
+ * //   intent: null,
+ * // }
+ *
+ * // If you have an intent field
+ * formData.append('intent', 'login');
+ * parseSubmission(formData, { intentName: 'intent' })
+ * // {
+ * //   value: { email: 'test@example.com', password: 'secret' },
+ * //   fields: ['email', 'password'],
+ * //   intent: 'login',
+ * // }
+ * ```
+ */
+export declare function parseSubmission(formData: FormData | URLSearchParams, options?: {
+    /**
+     * The name of the submit button that triggered the form submission.
+     * Used to extract the submission's intent.
+     */
+    intentName?: string;
+    /**
+     * A filter function that excludes specific entries from being parsed.
+     * Return `true` to skip the entry.
+     */
+    skipEntry?: (name: string) => boolean;
+}): Submission;
+export type ParseSubmissionOptions = Required<Parameters<typeof parseSubmission>>[1];
+export declare function defaultSerialize(value: unknown): FormDataEntryValue | undefined;
+/**
+ * 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
+ *
+ * ```tsx
+ * const dirty = useFormData(
+ *   formRef,
+ *   (formData) => isDirty(formData, { defaultValue }) ?? false,
+ * );
+ *
+ * return (
+ *   <button type="submit" disabled={!dirty}>
+ *     Save changes
+ *   </button>
+ * );
+ * ```
+ */
+export declare function isDirty(
+/**
+ * The current form data to compare. It can be:
+ *
+ * - A `FormData` object
+ * - A `URLSearchParams` object
+ * - A plain object that was parsed from form data (i.e. `submission.payload`)
+ */
+formData: FormData | URLSearchParams | FormValue<FormDataEntryValue> | null, options?: {
+    /**
+     * An object representing the default values of the form to compare against.
+     * Defaults to an empty object if not provided.
+     */
+    defaultValue?: unknown;
+    /**
+     * The name of the submit button that triggered the submission.
+     * It will be excluded from the dirty comparison.
+     */
+    intentName?: string;
+    /**
+     * A function to serialize values in defaultValue before comparing them to the form data.
+     * If not provided, a default serializer is used that behaves as follows:
+     *
+     * - string / File:
+     *   - Returned as-is
+     * - boolean:
+     *   - true → 'on'
+     *   - false → undefined
+     * - number / bigint:
+     *   - Converted to string using `.toString()`
+     * - Date:
+     *   - Converted to ISO string using `.toISOString()`
+     */
+    serialize?: (value: unknown, defaultSerialize: (value: unknown) => FormDataEntryValue | undefined) => FormDataEntryValue | undefined;
+    /**
+     * 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
+     * ```ts
+     * isDirty(formData, {
+     *   skipEntry: (name) => name === 'csrf-token',
+     * });
+     * ```
+     */
+    skipEntry?: (name: string) => boolean;
+}): boolean | undefined;
 export {};
 //# sourceMappingURL=formdata.d.ts.map

package/dist/formdata.js

@@ -2,6 +2,8 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
+var submission = require('./submission.js');
+
 /**
  * Construct a form data with the submitter value.
  * It utilizes the submitter argument on the FormData constructor from modern browsers
@@ -104,11 +106,11 @@ function setValue(target, name, valueFn) {
   var index = -1;
   var pointer = target;
   while (pointer != null && ++index < length) {
-    var key = paths[index];
+    var _key = paths[index];
     var nextKey = paths[index + 1];
-    var newValue = index != lastIndex ? Object.prototype.hasOwnProperty.call(pointer, key) && pointer[key] !== null ? pointer[key] : typeof nextKey === 'number' ? [] : {} : valueFn(pointer[key]);
-    pointer[key] = newValue;
-    pointer = pointer[key];
+    var newValue = index != lastIndex ? Object.prototype.hasOwnProperty.call(pointer, _key) && pointer[_key] !== null ? pointer[_key] : typeof nextKey === 'number' ? [] : {} : valueFn(pointer[_key]);
+    pointer[_key] = newValue;
+    pointer = pointer[_key];
   }
 }
 
@@ -195,8 +197,8 @@ function flatten(data) {
         process(data[i], "".concat(prefix, "[").concat(i, "]"));
       }
     } else if (isPlainObject(data)) {
-      for (var [key, _value] of Object.entries(data)) {
-        process(_value, prefix ? "".concat(prefix, ".").concat(key) : key);
+      for (var [_key2, _value] of Object.entries(data)) {
+        process(_value, prefix ? "".concat(prefix, ".").concat(_key2) : _key2);
       }
     }
   }
@@ -206,34 +208,36 @@ function flatten(data) {
   }
   return result;
 }
-function deepEqual(prev, next) {
-  if (prev === next) {
+function deepEqual(left, right) {
+  if (Object.is(left, right)) {
     return true;
   }
-  if (!prev || !next) {
+  if (left == null || right == null) {
     return false;
   }
-  if (Array.isArray(prev) && Array.isArray(next)) {
-    if (prev.length !== next.length) {
+
+  // Compare plain objects
+  if (isPlainObject(left) && isPlainObject(right)) {
+    var prevKeys = Object.keys(left);
+    var nextKeys = Object.keys(right);
+    if (prevKeys.length !== nextKeys.length) {
       return false;
     }
-    for (var i = 0; i < prev.length; i++) {
-      if (!deepEqual(prev[i], next[i])) {
+    for (var _key3 of prevKeys) {
+      if (!Object.prototype.hasOwnProperty.call(right, _key3) || !deepEqual(left[_key3], right[_key3])) {
         return false;
       }
     }
     return true;
   }
-  if (isPlainObject(prev) && isPlainObject(next)) {
-    var prevKeys = Object.keys(prev);
-    var nextKeys = Object.keys(next);
-    if (prevKeys.length !== nextKeys.length) {
+
+  // Compare arrays
+  if (Array.isArray(left) && Array.isArray(right)) {
+    if (left.length !== right.length) {
       return false;
     }
-    for (var key of prevKeys) {
-      if (!Object.prototype.hasOwnProperty.call(next, key) ||
-      // @ts-expect-error FIXME
-      !deepEqual(prev[key], next[key])) {
+    for (var i = 0; i < left.length; i++) {
+      if (!deepEqual(left[i], right[i])) {
         return false;
       }
     }
@@ -242,7 +246,170 @@ function deepEqual(prev, next) {
   return false;
 }
 
+/**
+ * The form value of a submission. This is usually constructed from a FormData or URLSearchParams.
+ * It may contains JSON primitives if the value is updated based on a form intent.
+ */
+
+/**
+ * The data of a form submission.
+ */
+
+/**
+ * Parse `FormData` or `URLSearchParams` into a submission object.
+ * This function structures the form values based on the naming convention.
+ * It also includes all the field names and the intent if the `intentName` option is provided.
+ *
+ * @example
+ * ```ts
+ * const formData = new FormData();
+ *
+ * formData.append('email', 'test@example.com');
+ * formData.append('password', 'secret');
+ *
+ * parseSubmission(formData)
+ * // {
+ * //   value: { email: 'test@example.com', password: 'secret' },
+ * //   fields: ['email', 'password'],
+ * //   intent: null,
+ * // }
+ *
+ * // If you have an intent field
+ * formData.append('intent', 'login');
+ * parseSubmission(formData, { intentName: 'intent' })
+ * // {
+ * //   value: { email: 'test@example.com', password: 'secret' },
+ * //   fields: ['email', 'password'],
+ * //   intent: 'login',
+ * // }
+ * ```
+ */
+function parseSubmission(formData, options) {
+  var _options$intentName;
+  var intentName = (_options$intentName = options === null || options === void 0 ? void 0 : options.intentName) !== null && _options$intentName !== void 0 ? _options$intentName : submission.INTENT;
+  var submission$1 = {
+    value: {},
+    fields: [],
+    intent: null
+  };
+  var _loop = function _loop() {
+    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 _value2 = formData.getAll(_name);
+      setValue(submission$1.value, _name, () => _value2.length > 1 ? _value2 : _value2[0]);
+      submission$1.fields.push(_name);
+    }
+  };
+  for (var _name of new Set(formData.keys())) {
+    _loop();
+  }
+  if (intentName) {
+    // We take the first value of the intent field if it exists.
+    var intent = formData.get(intentName);
+    if (typeof intent === 'string') {
+      submission$1.intent = intent;
+    }
+  }
+  return submission$1;
+}
+function defaultSerialize(value) {
+  if (typeof value === 'string' || isGlobalInstance(value, 'File')) {
+    return value;
+  }
+  if (typeof value === 'boolean') {
+    return value ? 'on' : undefined;
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  return value === null || value === void 0 ? void 0 : value.toString();
+}
+
+/**
+ * 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
+ *
+ * ```tsx
+ * const dirty = useFormData(
+ *   formRef,
+ *   (formData) => isDirty(formData, { defaultValue }) ?? false,
+ * );
+ *
+ * return (
+ *   <button type="submit" disabled={!dirty}>
+ *     Save changes
+ *   </button>
+ * );
+ * ```
+ */
+function isDirty(
+/**
+ * The current form data to compare. It can be:
+ *
+ * - A `FormData` object
+ * - A `URLSearchParams` object
+ * - A plain object that was parsed from form data (i.e. `submission.payload`)
+ */
+formData, options) {
+  var _options$serialize;
+  if (!formData) {
+    return;
+  }
+  var formValue = formData instanceof FormData || formData instanceof URLSearchParams ? parseSubmission(formData, {
+    intentName: options === null || options === void 0 ? void 0 : options.intentName,
+    skipEntry: options === null || options === void 0 ? void 0 : options.skipEntry
+  }).value : formData;
+  var defaultValue = options === null || options === void 0 ? void 0 : options.defaultValue;
+  var serialize = (_options$serialize = options === null || options === void 0 ? void 0 : options.serialize) !== null && _options$serialize !== void 0 ? _options$serialize : defaultSerialize;
+  function normalize(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 (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);
+    }
+
+    // If the value is null or undefined, treat it as undefined
+    if (value == null) {
+      return undefined;
+    }
+
+    // Removes empty strings, so that bpth empty string and undefined are treated as the same
+    if (typeof value === 'string' && value === '') {
+      return undefined;
+    }
+
+    // Remove empty File as well, which happens if no File was selected
+    if (isGlobalInstance(value, 'File') && value.name === '' && value.size === 0) {
+      return undefined;
+    }
+    return serialize(value, defaultSerialize);
+  }
+  return !deepEqual(normalize(formValue), normalize(defaultValue));
+}
+
 exports.deepEqual = deepEqual;
+exports.defaultSerialize = defaultSerialize;
 exports.flatten = flatten;
 exports.formatName = formatName;
 exports.formatPaths = formatPaths;
@@ -250,8 +417,10 @@ exports.getChildPaths = getChildPaths;
 exports.getFormData = getFormData;
 exports.getPaths = getPaths;
 exports.getValue = getValue;
+exports.isDirty = isDirty;
 exports.isGlobalInstance = isGlobalInstance;
 exports.isPlainObject = isPlainObject;
 exports.isPrefix = isPrefix;
 exports.normalize = normalize;
+exports.parseSubmission = parseSubmission;
 exports.setValue = setValue;

package/dist/formdata.mjs

@@ -1,3 +1,5 @@
+import { INTENT } from './submission.mjs';
+
 /**
  * Construct a form data with the submitter value.
  * It utilizes the submitter argument on the FormData constructor from modern browsers
@@ -100,11 +102,11 @@ function setValue(target, name, valueFn) {
   var index = -1;
   var pointer = target;
   while (pointer != null && ++index < length) {
-    var key = paths[index];
+    var _key = paths[index];
     var nextKey = paths[index + 1];
-    var newValue = index != lastIndex ? Object.prototype.hasOwnProperty.call(pointer, key) && pointer[key] !== null ? pointer[key] : typeof nextKey === 'number' ? [] : {} : valueFn(pointer[key]);
-    pointer[key] = newValue;
-    pointer = pointer[key];
+    var newValue = index != lastIndex ? Object.prototype.hasOwnProperty.call(pointer, _key) && pointer[_key] !== null ? pointer[_key] : typeof nextKey === 'number' ? [] : {} : valueFn(pointer[_key]);
+    pointer[_key] = newValue;
+    pointer = pointer[_key];
   }
 }
 
@@ -191,8 +193,8 @@ function flatten(data) {
         process(data[i], "".concat(prefix, "[").concat(i, "]"));
       }
     } else if (isPlainObject(data)) {
-      for (var [key, _value] of Object.entries(data)) {
-        process(_value, prefix ? "".concat(prefix, ".").concat(key) : key);
+      for (var [_key2, _value] of Object.entries(data)) {
+        process(_value, prefix ? "".concat(prefix, ".").concat(_key2) : _key2);
       }
     }
   }
@@ -202,34 +204,36 @@ function flatten(data) {
   }
   return result;
 }
-function deepEqual(prev, next) {
-  if (prev === next) {
+function deepEqual(left, right) {
+  if (Object.is(left, right)) {
     return true;
   }
-  if (!prev || !next) {
+  if (left == null || right == null) {
     return false;
   }
-  if (Array.isArray(prev) && Array.isArray(next)) {
-    if (prev.length !== next.length) {
+
+  // Compare plain objects
+  if (isPlainObject(left) && isPlainObject(right)) {
+    var prevKeys = Object.keys(left);
+    var nextKeys = Object.keys(right);
+    if (prevKeys.length !== nextKeys.length) {
       return false;
     }
-    for (var i = 0; i < prev.length; i++) {
-      if (!deepEqual(prev[i], next[i])) {
+    for (var _key3 of prevKeys) {
+      if (!Object.prototype.hasOwnProperty.call(right, _key3) || !deepEqual(left[_key3], right[_key3])) {
         return false;
       }
     }
     return true;
   }
-  if (isPlainObject(prev) && isPlainObject(next)) {
-    var prevKeys = Object.keys(prev);
-    var nextKeys = Object.keys(next);
-    if (prevKeys.length !== nextKeys.length) {
+
+  // Compare arrays
+  if (Array.isArray(left) && Array.isArray(right)) {
+    if (left.length !== right.length) {
       return false;
     }
-    for (var key of prevKeys) {
-      if (!Object.prototype.hasOwnProperty.call(next, key) ||
-      // @ts-expect-error FIXME
-      !deepEqual(prev[key], next[key])) {
+    for (var i = 0; i < left.length; i++) {
+      if (!deepEqual(left[i], right[i])) {
         return false;
       }
     }
@@ -238,4 +242,166 @@ function deepEqual(prev, next) {
   return false;
 }
 
-export { deepEqual, flatten, formatName, formatPaths, getChildPaths, getFormData, getPaths, getValue, isGlobalInstance, isPlainObject, isPrefix, normalize, setValue };
+/**
+ * The form value of a submission. This is usually constructed from a FormData or URLSearchParams.
+ * It may contains JSON primitives if the value is updated based on a form intent.
+ */
+
+/**
+ * The data of a form submission.
+ */
+
+/**
+ * Parse `FormData` or `URLSearchParams` into a submission object.
+ * This function structures the form values based on the naming convention.
+ * It also includes all the field names and the intent if the `intentName` option is provided.
+ *
+ * @example
+ * ```ts
+ * const formData = new FormData();
+ *
+ * formData.append('email', 'test@example.com');
+ * formData.append('password', 'secret');
+ *
+ * parseSubmission(formData)
+ * // {
+ * //   value: { email: 'test@example.com', password: 'secret' },
+ * //   fields: ['email', 'password'],
+ * //   intent: null,
+ * // }
+ *
+ * // If you have an intent field
+ * formData.append('intent', 'login');
+ * parseSubmission(formData, { intentName: 'intent' })
+ * // {
+ * //   value: { email: 'test@example.com', password: 'secret' },
+ * //   fields: ['email', 'password'],
+ * //   intent: 'login',
+ * // }
+ * ```
+ */
+function parseSubmission(formData, options) {
+  var _options$intentName;
+  var intentName = (_options$intentName = options === null || options === void 0 ? void 0 : options.intentName) !== null && _options$intentName !== void 0 ? _options$intentName : INTENT;
+  var submission = {
+    value: {},
+    fields: [],
+    intent: null
+  };
+  var _loop = function _loop() {
+    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 _value2 = formData.getAll(_name);
+      setValue(submission.value, _name, () => _value2.length > 1 ? _value2 : _value2[0]);
+      submission.fields.push(_name);
+    }
+  };
+  for (var _name of new Set(formData.keys())) {
+    _loop();
+  }
+  if (intentName) {
+    // We take the first value of the intent field if it exists.
+    var intent = formData.get(intentName);
+    if (typeof intent === 'string') {
+      submission.intent = intent;
+    }
+  }
+  return submission;
+}
+function defaultSerialize(value) {
+  if (typeof value === 'string' || isGlobalInstance(value, 'File')) {
+    return value;
+  }
+  if (typeof value === 'boolean') {
+    return value ? 'on' : undefined;
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  return value === null || value === void 0 ? void 0 : value.toString();
+}
+
+/**
+ * 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
+ *
+ * ```tsx
+ * const dirty = useFormData(
+ *   formRef,
+ *   (formData) => isDirty(formData, { defaultValue }) ?? false,
+ * );
+ *
+ * return (
+ *   <button type="submit" disabled={!dirty}>
+ *     Save changes
+ *   </button>
+ * );
+ * ```
+ */
+function isDirty(
+/**
+ * The current form data to compare. It can be:
+ *
+ * - A `FormData` object
+ * - A `URLSearchParams` object
+ * - A plain object that was parsed from form data (i.e. `submission.payload`)
+ */
+formData, options) {
+  var _options$serialize;
+  if (!formData) {
+    return;
+  }
+  var formValue = formData instanceof FormData || formData instanceof URLSearchParams ? parseSubmission(formData, {
+    intentName: options === null || options === void 0 ? void 0 : options.intentName,
+    skipEntry: options === null || options === void 0 ? void 0 : options.skipEntry
+  }).value : formData;
+  var defaultValue = options === null || options === void 0 ? void 0 : options.defaultValue;
+  var serialize = (_options$serialize = options === null || options === void 0 ? void 0 : options.serialize) !== null && _options$serialize !== void 0 ? _options$serialize : defaultSerialize;
+  function normalize(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 (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);
+    }
+
+    // If the value is null or undefined, treat it as undefined
+    if (value == null) {
+      return undefined;
+    }
+
+    // Removes empty strings, so that bpth empty string and undefined are treated as the same
+    if (typeof value === 'string' && value === '') {
+      return undefined;
+    }
+
+    // Remove empty File as well, which happens if no File was selected
+    if (isGlobalInstance(value, 'File') && value.name === '' && value.size === 0) {
+      return undefined;
+    }
+    return serialize(value, defaultSerialize);
+  }
+  return !deepEqual(normalize(formValue), normalize(defaultValue));
+}
+
+export { deepEqual, defaultSerialize, flatten, formatName, formatPaths, getChildPaths, getFormData, getPaths, getValue, isDirty, isGlobalInstance, isPlainObject, isPrefix, normalize, parseSubmission, setValue };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { type Combine, type Constraint, type ControlButtonProps, type FormId, type FieldName, type DefaultValue, type FormValue, type FormOptions, type FormState, type FormContext, type SubscriptionSubject, type SubscriptionScope, createFormContext as unstable_createFormContext, } from './form';
 export { type FieldElement, isFieldElement, updateField as unstable_updateField, createFileList, createGlobalFormsObserver as unstable_createGlobalFormsObserver, focus as unstable_focus, change as unstable_change, blur as unstable_blur, } from './dom';
 export { type Submission, type SubmissionResult, type Intent, INTENT, STATE, serializeIntent, parse, } from './submission';
-export { getPaths, formatPaths, isPrefix, isGlobalInstance, deepEqual as unstable_deepEqual, } from './formdata';
+export { getFormData, getPaths, formatPaths, isPrefix, isGlobalInstance, deepEqual as unstable_deepEqual, isDirty as unstable_isDirty, } from './formdata';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -22,7 +22,9 @@ exports.STATE = submission.STATE;
 exports.parse = submission.parse;
 exports.serializeIntent = submission.serializeIntent;
 exports.formatPaths = formdata.formatPaths;
+exports.getFormData = formdata.getFormData;
 exports.getPaths = formdata.getPaths;
 exports.isGlobalInstance = formdata.isGlobalInstance;
 exports.isPrefix = formdata.isPrefix;
 exports.unstable_deepEqual = formdata.deepEqual;
+exports.unstable_isDirty = formdata.isDirty;

package/dist/index.mjs

@@ -1,4 +1,4 @@
 export { createFormContext as unstable_createFormContext } from './form.mjs';
 export { createFileList, isFieldElement, blur as unstable_blur, change as unstable_change, createGlobalFormsObserver as unstable_createGlobalFormsObserver, focus as unstable_focus, updateField as unstable_updateField } from './dom.mjs';
 export { INTENT, STATE, parse, serializeIntent } from './submission.mjs';
-export { formatPaths, getPaths, isGlobalInstance, isPrefix, deepEqual as unstable_deepEqual } from './formdata.mjs';
+export { formatPaths, getFormData, getPaths, isGlobalInstance, isPrefix, deepEqual as unstable_deepEqual, isDirty as unstable_isDirty } from './formdata.mjs';

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