@conform-to/dom 1.8.1 → 1.9.0

package/README.md

@@ -7,7 +7,7 @@
  ╚══════╝  ╚═════╝  ╚═╝  ╚══╝ ╚═╝        ╚═════╝  ╚═╝   ╚═╝ ╚═╝   ╚═╝
 ```
 
-Version 1.8.1 / License MIT / Copyright (c) 2024 Edmund Hung
+Version 1.9.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.d.ts

@@ -10,11 +10,19 @@ export type Submitter = HTMLInputElement | HTMLButtonElement;
 export declare function isInputElement(element: Element): element is HTMLInputElement;
 export declare function isSelectElement(element: Element): element is HTMLSelectElement;
 export declare function isTextAreaElement(element: Element): element is HTMLTextAreaElement;
+/**
+ * A type guard to checks if the element is a submitter element.
+ * A submitter element is either an input or button element with type submit.
+ */
+export declare function isSubmitter(element: HTMLElement): element is HTMLInputElement | HTMLButtonElement;
 /**
  * A type guard to check if the provided element is a field element, which
  * is a form control excluding submit, button and reset type.
  */
 export declare function isFieldElement(element: unknown): element is FieldElement;
+export declare function isGlobalInstance<ClassName extends {
+    [K in keyof typeof globalThis]: (typeof globalThis)[K] extends new (...args: any) => any ? K : never;
+}[keyof typeof globalThis]>(obj: unknown, className: ClassName): obj is InstanceType<(typeof globalThis)[ClassName]>;
 /**
  * Resolves the action from the submit event
  * with respect to the submitter `formaction` attribute.
@@ -30,11 +38,20 @@ export declare function getFormEncType(event: SubmitEvent): 'application/x-www-f
  * with respect to the submitter `formmethod` attribute.
  */
 export declare function getFormMethod(event: SubmitEvent): 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * Creates a submit event that behaves like a real form submission.
+ */
+export declare function createSubmitEvent(submitter?: HTMLElement | null): SubmitEvent;
 /**
  * Trigger a form submit event with an optional submitter.
  * If the submitter is not mounted, it will be appended to the form and removed after submission.
  */
 export declare function requestSubmit(form: HTMLFormElement | null | undefined, submitter: Submitter | null): void;
+/**
+ * Triggers form submission with an intent value. This is achieved by
+ * creating a hidden button element with the intent value and then submitting it with the form.
+ */
+export declare function requestIntent(formElement: HTMLFormElement, intentName: string, intentValue: string): void;
 export declare function createFileList(value: File | File[]): FileList;
 type InputCallback = (event: {
     type: 'input' | 'reset' | 'mutation';
@@ -50,8 +67,20 @@ export declare function createGlobalFormsObserver(): {
     onFormUpdate(callback: FormCallback): () => void;
     dispose(): void;
 };
-export declare function change(element: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement, value: string | string[] | File | File[] | FileList | null): void;
+/**
+ * Change the value of the given field element.
+ * Dispatches both `input` and `change` events only if the value is changed.
+ */
+export declare function change(element: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement, value: string | string[] | File | File[] | FileList | null, options?: {
+    preventDefault?: boolean;
+}): void;
+/**
+ * Dispatches focus and focusin events on the given element.
+ */
 export declare function focus(element: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement): void;
+/**
+ * Dispatches blur and focusout events on the given element.
+ */
 export declare function blur(element: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement): void;
 export declare function normalizeStringValues(value: unknown): string[] | undefined;
 export declare function normalizeFileValues(value: unknown): FileList | undefined;
@@ -62,6 +91,7 @@ export declare function normalizeFileValues(value: unknown): FileList | undefine
 export declare function updateField(element: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement, options: {
     value?: unknown;
     defaultValue?: unknown;
-}): void;
+}): boolean;
+export declare function isDirtyInput(element: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement): boolean;
 export {};
 //# sourceMappingURL=dom.d.ts.map

package/dist/dom.js

@@ -2,7 +2,6 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var formdata = require('./formdata.js');
 var util = require('./util.js');
 
 /**
@@ -24,6 +23,14 @@ function isTextAreaElement(element) {
   return element.tagName === 'TEXTAREA';
 }
 
+/**
+ * A type guard to checks if the element is a submitter element.
+ * A submitter element is either an input or button element with type submit.
+ */
+function isSubmitter(element) {
+  return 'type' in element && element.type === 'submit';
+}
+
 /**
  * A type guard to check if the provided element is a field element, which
  * is a form control excluding submit, button and reset type.
@@ -39,6 +46,10 @@ function isFieldElement(element) {
   }
   return false;
 }
+function isGlobalInstance(obj, className) {
+  var Ctor = globalThis[className];
+  return typeof Ctor === 'function' && obj instanceof Ctor;
+}
 
 /**
  * Resolves the action from the submit event
@@ -85,6 +96,17 @@ function getFormMethod(event) {
   return 'GET';
 }
 
+/**
+ * Creates a submit event that behaves like a real form submission.
+ */
+function createSubmitEvent(submitter) {
+  return new SubmitEvent('submit', {
+    bubbles: true,
+    cancelable: true,
+    submitter
+  });
+}
+
 /**
  * Trigger a form submit event with an optional submitter.
  * If the submitter is not mounted, it will be appended to the form and removed after submission.
@@ -94,14 +116,24 @@ function requestSubmit(form, submitter) {
   if (typeof form.requestSubmit === 'function') {
     form.requestSubmit(submitter);
   } else {
-    var _event = new SubmitEvent('submit', {
-      bubbles: true,
-      cancelable: true,
-      submitter
-    });
-    form.dispatchEvent(_event);
+    form.dispatchEvent(createSubmitEvent(submitter));
   }
 }
+
+/**
+ * Triggers form submission with an intent value. This is achieved by
+ * creating a hidden button element with the intent value and then submitting it with the form.
+ */
+function requestIntent(formElement, intentName, intentValue) {
+  var submitter = document.createElement('button');
+  submitter.name = intentName;
+  submitter.value = intentValue;
+  submitter.hidden = true;
+  submitter.formNoValidate = true;
+  formElement.appendChild(submitter);
+  requestSubmit(formElement, submitter);
+  formElement.removeChild(submitter);
+}
 function createFileList(value) {
   var dataTransfer = new DataTransfer();
   if (Array.isArray(value)) {
@@ -301,21 +333,40 @@ function createGlobalFormsObserver() {
     }
   };
 }
-function change(element, value) {
+
+/**
+ * Change the value of the given field element.
+ * Dispatches both `input` and `change` events only if the value is changed.
+ */
+function change(element, value, options) {
   // The value should be set to the element before dispatching the event
-  updateField(element, {
+  var isChanged = updateField(element, {
     value
   });
+  if (isChanged) {
+    var inputEvent = new InputEvent('input', {
+      bubbles: true,
+      cancelable: true
+    });
+    var changeEvent = new Event('change', {
+      bubbles: true,
+      cancelable: true
+    });
+    if (options !== null && options !== void 0 && options.preventDefault) {
+      inputEvent.preventDefault();
+      changeEvent.preventDefault();
+    }
 
-  // Dispatch input event with the updated input value
-  element.dispatchEvent(new InputEvent('input', {
-    bubbles: true
-  }));
-  // Dispatch change event (necessary for select to update the selected option)
-  element.dispatchEvent(new Event('change', {
-    bubbles: true
-  }));
+    // Dispatch input event with the updated input value
+    element.dispatchEvent(inputEvent);
+    // Dispatch change event (necessary for select to update the selected option)
+    element.dispatchEvent(changeEvent);
+  }
 }
+
+/**
+ * Dispatches focus and focusin events on the given element.
+ */
 function focus(element) {
   // Only focusin event will be bubbled
   element.dispatchEvent(new FocusEvent('focusin', {
@@ -323,6 +374,10 @@ function focus(element) {
   }));
   element.dispatchEvent(new FocusEvent('focus'));
 }
+
+/**
+ * Dispatches blur and focusout events on the given element.
+ */
 function blur(element) {
   // Only focusout event will be bubbled
   element.dispatchEvent(new FocusEvent('focusout', {
@@ -342,9 +397,9 @@ function normalizeStringValues(value) {
 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'))) {
+  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);
   }
   throw new Error('Expected File, FileList or File[] for file input');
@@ -356,15 +411,17 @@ function normalizeFileValues(value) {
  */
 function updateField(element, options) {
   var _value$;
+  var isChanged = false;
   if (isInputElement(element)) {
     switch (element.type) {
       case 'file':
         {
           var files = normalizeFileValues(options.value);
-          if (files) {
+          if (files && element.files !== files) {
             element.files = files;
+            isChanged = true;
           }
-          return;
+          return isChanged;
         }
       case 'checkbox':
       case 'radio':
@@ -376,13 +433,14 @@ function updateField(element, options) {
             if (element.type === 'checkbox' ? checked !== element.checked : checked) {
               // Simulate a click to update the checked state
               element.click();
+              isChanged = true;
             }
             element.checked = checked;
           }
           if (_defaultValue) {
             element.defaultChecked = _defaultValue.includes(element.value);
           }
-          return;
+          return isChanged;
         }
     }
   } else if (isSelectElement(element)) {
@@ -397,6 +455,7 @@ function updateField(element, options) {
         // Update the selected state of the option
         if (option.selected !== selected) {
           option.selected = selected;
+          isChanged = true;
         }
 
         // Remove the option from the value array
@@ -424,14 +483,16 @@ function updateField(element, options) {
     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, _defaultValue2 === null || _defaultValue2 === void 0 ? void 0 : _defaultValue2.includes(optionValue), _value2 === null || _value2 === void 0 ? void 0 : _value2.includes(optionValue)));
+      isChanged = true;
     }
 
     // If the select element is not multiple and the value is an empty array, unset the selected index
     // This is to prevent the select element from showing the first option as selected
     if (shouldUnselect) {
       element.selectedIndex = -1;
+      isChanged = true;
     }
-    return;
+    return isChanged;
   }
   var value = normalizeStringValues(options.value);
   var defaultValue = normalizeStringValues(options.defaultValue);
@@ -457,26 +518,52 @@ function updateField(element, options) {
     } else {
       throw new Error('The given element does not have a value setter');
     }
+    isChanged = true;
   }
   if (defaultValue) {
     var _defaultValue$;
     element.defaultValue = (_defaultValue$ = defaultValue[0]) !== null && _defaultValue$ !== void 0 ? _defaultValue$ : '';
   }
+  return isChanged;
+}
+function isDirtyInput(element) {
+  var _element$files$length, _element$files;
+  if (isInputElement(element)) {
+    switch (element.type) {
+      case 'checkbox':
+      case 'radio':
+        return element.checked !== element.defaultChecked;
+      case 'file':
+        return ((_element$files$length = (_element$files = element.files) === null || _element$files === void 0 ? void 0 : _element$files.length) !== null && _element$files$length !== void 0 ? _element$files$length : 0) > 0;
+      default:
+        return element.value !== element.defaultValue;
+    }
+  } else if (isSelectElement(element)) {
+    return Array.from(element.options).some(option => option.selected !== option.defaultSelected);
+  } else if (isTextAreaElement(element)) {
+    return element.value !== element.defaultValue;
+  }
+  return false;
 }
 
 exports.blur = blur;
 exports.change = change;
 exports.createFileList = createFileList;
 exports.createGlobalFormsObserver = createGlobalFormsObserver;
+exports.createSubmitEvent = createSubmitEvent;
 exports.focus = focus;
 exports.getFormAction = getFormAction;
 exports.getFormEncType = getFormEncType;
 exports.getFormMethod = getFormMethod;
+exports.isDirtyInput = isDirtyInput;
 exports.isFieldElement = isFieldElement;
+exports.isGlobalInstance = isGlobalInstance;
 exports.isInputElement = isInputElement;
 exports.isSelectElement = isSelectElement;
+exports.isSubmitter = isSubmitter;
 exports.isTextAreaElement = isTextAreaElement;
 exports.normalizeFileValues = normalizeFileValues;
 exports.normalizeStringValues = normalizeStringValues;
+exports.requestIntent = requestIntent;
 exports.requestSubmit = requestSubmit;
 exports.updateField = updateField;

package/dist/dom.mjs

@@ -1,4 +1,3 @@
-import { isGlobalInstance } from './formdata.mjs';
 import { invariant } from './util.mjs';
 
 /**
@@ -20,6 +19,14 @@ function isTextAreaElement(element) {
   return element.tagName === 'TEXTAREA';
 }
 
+/**
+ * A type guard to checks if the element is a submitter element.
+ * A submitter element is either an input or button element with type submit.
+ */
+function isSubmitter(element) {
+  return 'type' in element && element.type === 'submit';
+}
+
 /**
  * A type guard to check if the provided element is a field element, which
  * is a form control excluding submit, button and reset type.
@@ -35,6 +42,10 @@ function isFieldElement(element) {
   }
   return false;
 }
+function isGlobalInstance(obj, className) {
+  var Ctor = globalThis[className];
+  return typeof Ctor === 'function' && obj instanceof Ctor;
+}
 
 /**
  * Resolves the action from the submit event
@@ -81,6 +92,17 @@ function getFormMethod(event) {
   return 'GET';
 }
 
+/**
+ * Creates a submit event that behaves like a real form submission.
+ */
+function createSubmitEvent(submitter) {
+  return new SubmitEvent('submit', {
+    bubbles: true,
+    cancelable: true,
+    submitter
+  });
+}
+
 /**
  * Trigger a form submit event with an optional submitter.
  * If the submitter is not mounted, it will be appended to the form and removed after submission.
@@ -90,14 +112,24 @@ function requestSubmit(form, submitter) {
   if (typeof form.requestSubmit === 'function') {
     form.requestSubmit(submitter);
   } else {
-    var _event = new SubmitEvent('submit', {
-      bubbles: true,
-      cancelable: true,
-      submitter
-    });
-    form.dispatchEvent(_event);
+    form.dispatchEvent(createSubmitEvent(submitter));
   }
 }
+
+/**
+ * Triggers form submission with an intent value. This is achieved by
+ * creating a hidden button element with the intent value and then submitting it with the form.
+ */
+function requestIntent(formElement, intentName, intentValue) {
+  var submitter = document.createElement('button');
+  submitter.name = intentName;
+  submitter.value = intentValue;
+  submitter.hidden = true;
+  submitter.formNoValidate = true;
+  formElement.appendChild(submitter);
+  requestSubmit(formElement, submitter);
+  formElement.removeChild(submitter);
+}
 function createFileList(value) {
   var dataTransfer = new DataTransfer();
   if (Array.isArray(value)) {
@@ -297,21 +329,40 @@ function createGlobalFormsObserver() {
     }
   };
 }
-function change(element, value) {
+
+/**
+ * Change the value of the given field element.
+ * Dispatches both `input` and `change` events only if the value is changed.
+ */
+function change(element, value, options) {
   // The value should be set to the element before dispatching the event
-  updateField(element, {
+  var isChanged = updateField(element, {
     value
   });
+  if (isChanged) {
+    var inputEvent = new InputEvent('input', {
+      bubbles: true,
+      cancelable: true
+    });
+    var changeEvent = new Event('change', {
+      bubbles: true,
+      cancelable: true
+    });
+    if (options !== null && options !== void 0 && options.preventDefault) {
+      inputEvent.preventDefault();
+      changeEvent.preventDefault();
+    }
 
-  // Dispatch input event with the updated input value
-  element.dispatchEvent(new InputEvent('input', {
-    bubbles: true
-  }));
-  // Dispatch change event (necessary for select to update the selected option)
-  element.dispatchEvent(new Event('change', {
-    bubbles: true
-  }));
+    // Dispatch input event with the updated input value
+    element.dispatchEvent(inputEvent);
+    // Dispatch change event (necessary for select to update the selected option)
+    element.dispatchEvent(changeEvent);
+  }
 }
+
+/**
+ * Dispatches focus and focusin events on the given element.
+ */
 function focus(element) {
   // Only focusin event will be bubbled
   element.dispatchEvent(new FocusEvent('focusin', {
@@ -319,6 +370,10 @@ function focus(element) {
   }));
   element.dispatchEvent(new FocusEvent('focus'));
 }
+
+/**
+ * Dispatches blur and focusout events on the given element.
+ */
 function blur(element) {
   // Only focusout event will be bubbled
   element.dispatchEvent(new FocusEvent('focusout', {
@@ -352,15 +407,17 @@ function normalizeFileValues(value) {
  */
 function updateField(element, options) {
   var _value$;
+  var isChanged = false;
   if (isInputElement(element)) {
     switch (element.type) {
       case 'file':
         {
           var files = normalizeFileValues(options.value);
-          if (files) {
+          if (files && element.files !== files) {
             element.files = files;
+            isChanged = true;
           }
-          return;
+          return isChanged;
         }
       case 'checkbox':
       case 'radio':
@@ -372,13 +429,14 @@ function updateField(element, options) {
             if (element.type === 'checkbox' ? checked !== element.checked : checked) {
               // Simulate a click to update the checked state
               element.click();
+              isChanged = true;
             }
             element.checked = checked;
           }
           if (_defaultValue) {
             element.defaultChecked = _defaultValue.includes(element.value);
           }
-          return;
+          return isChanged;
         }
     }
   } else if (isSelectElement(element)) {
@@ -393,6 +451,7 @@ function updateField(element, options) {
         // Update the selected state of the option
         if (option.selected !== selected) {
           option.selected = selected;
+          isChanged = true;
         }
 
         // Remove the option from the value array
@@ -420,14 +479,16 @@ function updateField(element, options) {
     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, _defaultValue2 === null || _defaultValue2 === void 0 ? void 0 : _defaultValue2.includes(optionValue), _value2 === null || _value2 === void 0 ? void 0 : _value2.includes(optionValue)));
+      isChanged = true;
     }
 
     // If the select element is not multiple and the value is an empty array, unset the selected index
     // This is to prevent the select element from showing the first option as selected
     if (shouldUnselect) {
       element.selectedIndex = -1;
+      isChanged = true;
     }
-    return;
+    return isChanged;
   }
   var value = normalizeStringValues(options.value);
   var defaultValue = normalizeStringValues(options.defaultValue);
@@ -453,11 +514,32 @@ function updateField(element, options) {
     } else {
       throw new Error('The given element does not have a value setter');
     }
+    isChanged = true;
   }
   if (defaultValue) {
     var _defaultValue$;
     element.defaultValue = (_defaultValue$ = defaultValue[0]) !== null && _defaultValue$ !== void 0 ? _defaultValue$ : '';
   }
+  return isChanged;
+}
+function isDirtyInput(element) {
+  var _element$files$length, _element$files;
+  if (isInputElement(element)) {
+    switch (element.type) {
+      case 'checkbox':
+      case 'radio':
+        return element.checked !== element.defaultChecked;
+      case 'file':
+        return ((_element$files$length = (_element$files = element.files) === null || _element$files === void 0 ? void 0 : _element$files.length) !== null && _element$files$length !== void 0 ? _element$files$length : 0) > 0;
+      default:
+        return element.value !== element.defaultValue;
+    }
+  } else if (isSelectElement(element)) {
+    return Array.from(element.options).some(option => option.selected !== option.defaultSelected);
+  } else if (isTextAreaElement(element)) {
+    return element.value !== element.defaultValue;
+  }
+  return false;
 }
 
-export { blur, change, createFileList, createGlobalFormsObserver, focus, getFormAction, getFormEncType, getFormMethod, isFieldElement, isInputElement, isSelectElement, isTextAreaElement, normalizeFileValues, normalizeStringValues, requestSubmit, updateField };
+export { blur, change, createFileList, createGlobalFormsObserver, createSubmitEvent, focus, getFormAction, getFormEncType, getFormMethod, isDirtyInput, isFieldElement, isGlobalInstance, isInputElement, isSelectElement, isSubmitter, isTextAreaElement, normalizeFileValues, normalizeStringValues, requestIntent, requestSubmit, updateField };