@conform-to/dom 1.7.2 → 1.8.0

package/README.md

@@ -7,7 +7,7 @@
  ╚══════╝  ╚═════╝  ╚═╝  ╚══╝ ╚═╝        ╚═════╝  ╚═╝   ╚═╝ ╚═╝   ╚═╝
 ```
 
-Version 1.7.2 / License MIT / Copyright (c) 2024 Edmund Hung
+Version 1.8.0 / 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.js

@@ -121,6 +121,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 +189,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 +207,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 +240,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;
           }

package/dist/dom.mjs

@@ -117,6 +117,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 +185,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 +203,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 +236,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;
           }

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