@conform-to/react 1.17.1 → 1.19.0

package/README.md

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

package/dist/future/dom.d.ts

@@ -1,27 +1,14 @@
 import { Serialize } from '@conform-to/dom/future';
-import type { ErrorContext, FormRef, InputSnapshot, IntentDispatcher } from './types';
+import type { ControlOptions, ErrorContext, FormRef, IntentDispatcher } from './types';
 export declare function getFormElement(formRef: FormRef | undefined): HTMLFormElement | null;
 export declare function getSubmitEvent(event: React.FormEvent<HTMLFormElement>): SubmitEvent;
 export declare function initializeField(element: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement, options: {
-    defaultValue?: string | string[] | File | File[] | null | undefined;
+    defaultValue?: unknown;
     defaultChecked?: boolean | undefined;
     value?: string | undefined;
 } | undefined): void;
-/**
- * Makes hidden form inputs focusable with visually hidden styles
- */
-export declare function makeInputFocusable(element: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement): void;
-export declare function getRadioGroupValue(inputs: Array<HTMLInputElement>): string | undefined;
-export declare function getCheckboxGroupValue(inputs: Array<HTMLInputElement>): string[] | undefined;
-export declare function getInputSnapshot(input: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement): InputSnapshot;
-/**
- * Creates an InputSnapshot based on the provided options:
- * - checkbox/radio: value / defaultChecked
- * - file inputs: defaultValue is File or FileList
- * - select multiple: defaultValue is string array
- * - others: defaultValue is string
- */
-export declare function createDefaultSnapshot(defaultValue: string | string[] | File | File[] | FileList | null | undefined, defaultChecked: boolean | undefined, value: string | undefined): InputSnapshot;
+export declare function resolveControlPayload(input: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement | HTMLFieldSetElement | Array<HTMLInputElement>): unknown;
+export declare function deriveDefaultPayload(options: ControlOptions): unknown;
 /**
  * Focuses the first field with validation errors on default form submission.
  * Does nothing if the submission was triggered with a specific intent (e.g. validate / insert)

package/dist/future/dom.js

@@ -4,17 +4,20 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 var future = require('@conform-to/dom/future');
 var intent = require('./intent.js');
+var state = require('./state.js');
 
 function getFormElement(formRef) {
-  var _element$form;
-  if (typeof formRef === 'string') {
-    return document.forms.namedItem(formRef);
+  if (typeof formRef === 'undefined') {
+    return null;
   }
-  var element = formRef === null || formRef === void 0 ? void 0 : formRef.current;
-  if (element instanceof HTMLFormElement) {
-    return element;
+  if (typeof formRef !== 'string') {
+    var element = formRef.current;
+    if (!element) {
+      return null;
+    }
+    return future.isGlobalInstance(element, 'HTMLFormElement') ? element : element.form;
   }
-  return (_element$form = element === null || element === void 0 ? void 0 : element.form) !== null && _element$form !== void 0 ? _element$form : null;
+  return document.forms.namedItem(formRef);
 }
 function getSubmitEvent(event) {
   if (event.type !== 'submit') {
@@ -45,125 +48,69 @@ function initializeField(element, options) {
   });
   element.dataset.conform = 'initialized';
 }
-
-/**
- * Makes hidden form inputs focusable with visually hidden styles
- */
-function makeInputFocusable(element) {
-  if (!element.hidden && element.type !== 'hidden') {
-    return;
-  }
-
-  // Style the element to be visually hidden
-  element.style.position = 'absolute';
-  element.style.width = '1px';
-  element.style.height = '1px';
-  element.style.padding = '0';
-  element.style.margin = '-1px';
-  element.style.overflow = 'hidden';
-  element.style.clip = 'rect(0,0,0,0)';
-  element.style.whiteSpace = 'nowrap';
-  element.style.border = '0';
-
-  // Hide the element from screen readers
-  element.setAttribute('aria-hidden', 'true');
-
-  // Make sure people won't tab to this element
-  element.tabIndex = -1;
-
-  // Set the element to be visible again so it can be focused
-  if (element.hidden) {
-    element.hidden = false;
-  }
-  if (element.type === 'hidden') {
-    element.setAttribute('type', 'text');
-  }
-}
-function getRadioGroupValue(inputs) {
-  for (var input of inputs) {
-    if (input.type === 'radio' && input.checked) {
-      return input.value;
-    }
-  }
-}
-function getCheckboxGroupValue(inputs) {
-  var values;
-  for (var input of inputs) {
-    if (input.type === 'checkbox') {
-      var _values;
-      (_values = values) !== null && _values !== void 0 ? _values : values = [];
-      if (input.checked) {
-        values.push(input.value);
+function resolveControlPayload(input) {
+  if (Array.isArray(input)) {
+    var options;
+    for (var element of input) {
+      if (element.type === 'radio' && element.checked) {
+        return element.value;
+      }
+      if (element.type === 'checkbox') {
+        var _options;
+        (_options = options) !== null && _options !== void 0 ? _options : options = [];
+        if (element.checked) {
+          options.push(element.value);
+        }
       }
     }
+    return options;
   }
-  return values;
-}
-function getInputSnapshot(input) {
   if (input instanceof HTMLInputElement) {
     switch (input.type) {
       case 'file':
-        return {
-          files: input.files ? Array.from(input.files) : undefined
-        };
+        {
+          return input.files ? Array.from(input.files) : [];
+        }
       case 'radio':
       case 'checkbox':
-        return {
-          value: input.value,
-          checked: input.checked
-        };
+        return input.checked ? input.value : null;
     }
   } else if (input instanceof HTMLSelectElement && input.multiple) {
-    return {
-      options: Array.from(input.selectedOptions).map(option => option.value)
-    };
-  }
-  return {
-    value: input.value
-  };
-}
-
-/**
- * Creates an InputSnapshot based on the provided options:
- * - checkbox/radio: value / defaultChecked
- * - file inputs: defaultValue is File or FileList
- * - select multiple: defaultValue is string array
- * - others: defaultValue is string
- */
-function createDefaultSnapshot(defaultValue, defaultChecked, value) {
-  if (typeof value === 'string' || typeof defaultChecked === 'boolean') {
-    return {
-      value: value !== null && value !== void 0 ? value : 'on',
-      checked: defaultChecked
-    };
-  }
-  if (typeof defaultValue === 'string') {
-    return {
-      value: defaultValue
-    };
-  }
-  if (Array.isArray(defaultValue)) {
-    if (defaultValue.every(item => typeof item === 'string')) {
-      return {
-        options: defaultValue
-      };
-    } else {
-      return {
-        files: defaultValue
-      };
+    return Array.from(input.selectedOptions).map(option => option.value);
+  } else if (input instanceof HTMLFieldSetElement) {
+    if (input.elements.length === 0) {
+      return null;
     }
+    var result = {};
+    var entries = new Map();
+    for (var _element of input.elements) {
+      if (future.isFieldElement(_element)) {
+        var payload = resolveControlPayload(_element);
+        var value = entries.get(_element.name);
+        if (_element.type === 'checkbox') {
+          entries.set(_element.name, value === undefined ? payload : (Array.isArray(value) ? [...value, payload] : [value, payload]).filter(v => v !== null));
+        } else if (_element.type === 'radio') {
+          entries.set(_element.name, value == null ? payload : payload === null ? value : payload);
+        } else {
+          entries.set(_element.name, value === undefined ? payload : Array.isArray(value) ? [...value, payload] : [value, payload]);
+        }
+      }
+    }
+    for (var [name, _value] of entries) {
+      future.setPathValue(result, name, _value);
+    }
+    return future.getPathValue(result, input.name);
   }
-  if (future.isGlobalInstance(defaultValue, 'File')) {
-    return {
-      files: [defaultValue]
-    };
+  return input.value;
+}
+function deriveDefaultPayload(options) {
+  if ('defaultChecked' in options && typeof options.defaultChecked === 'boolean') {
+    var _options$value2;
+    return options.defaultChecked ? (_options$value2 = options.value) !== null && _options$value2 !== void 0 ? _options$value2 : 'on' : null;
   }
-  if (future.isGlobalInstance(defaultValue, 'FileList')) {
-    return {
-      files: Array.from(defaultValue)
-    };
+  if ('defaultValue' in options) {
+    return options.defaultValue;
   }
-  return {};
 }
 
 /**
@@ -175,22 +122,33 @@ function focusFirstInvalidField(ctx) {
     return;
   }
   for (var element of ctx.formElement.elements) {
-    var _ctx$error$fieldError;
-    if (future.isFieldElement(element) && (_ctx$error$fieldError = ctx.error.fieldErrors[element.name]) !== null && _ctx$error$fieldError !== void 0 && _ctx$error$fieldError.length) {
+    if (!(future.isFieldElement(element) || element instanceof HTMLFieldSetElement) || element.name === '' || !state.hasFieldError(ctx.error, element.name)) {
+      continue;
+    }
+
+    // Treat fieldset as a focusable field only if it is hidden
+    if (element.type === 'fieldset' && !element.hidden) {
+      continue;
+    }
+    if (element.hidden || element.type === 'hidden' || element.type === 'fieldset') {
+      future.focus(element);
+    } else {
       element.focus();
-      break;
     }
+    break;
   }
 }
 function updateFormValue(form, targetValue, serialize) {
   for (var element of form.elements) {
     if (future.isFieldElement(element) && element.name && element.type !== 'hidden') {
-      var fieldValue = future.getValueAtPath(targetValue, element.name);
+      var fieldValue = future.getPathValue(targetValue, element.name);
       if (element.type === 'file' && fieldValue === undefined) {
         // Do not update file inputs unless there's a target value
         continue;
       }
-      var value = serialize(fieldValue);
+      var value = serialize(fieldValue, {
+        name: element.name
+      });
 
       // Treat undefined as null to clear the field value
       future.change(element, value !== undefined ? value : null, {
@@ -202,8 +160,10 @@ function updateFormValue(form, targetValue, serialize) {
 function resetFormValue(form, defaultValue, serialize) {
   for (var element of form.elements) {
     if (future.isFieldElement(element) && element.name && element.type !== 'hidden' && element.type !== 'file') {
-      var fieldValue = future.getValueAtPath(defaultValue, element.name);
-      var value = serialize(fieldValue);
+      var fieldValue = future.getPathValue(defaultValue, element.name);
+      var value = serialize(fieldValue, {
+        name: element.name
+      });
       future.updateField(element, {
         defaultValue: value !== undefined ? value : null
       });
@@ -363,16 +323,13 @@ function preserveInputs(inputs, form, name) {
 }
 
 exports.cleanupPreservedInputs = cleanupPreservedInputs;
-exports.createDefaultSnapshot = createDefaultSnapshot;
 exports.createIntentDispatcher = createIntentDispatcher;
+exports.deriveDefaultPayload = deriveDefaultPayload;
 exports.focusFirstInvalidField = focusFirstInvalidField;
-exports.getCheckboxGroupValue = getCheckboxGroupValue;
 exports.getFormElement = getFormElement;
-exports.getInputSnapshot = getInputSnapshot;
-exports.getRadioGroupValue = getRadioGroupValue;
 exports.getSubmitEvent = getSubmitEvent;
 exports.initializeField = initializeField;
-exports.makeInputFocusable = makeInputFocusable;
 exports.preserveInputs = preserveInputs;
 exports.resetFormValue = resetFormValue;
+exports.resolveControlPayload = resolveControlPayload;
 exports.updateFormValue = updateFormValue;

package/dist/future/dom.mjs

@@ -1,16 +1,19 @@
-import { change, updateField, isGlobalInstance, isFieldElement, requestIntent, getValueAtPath } from '@conform-to/dom/future';
+import { isGlobalInstance, change, updateField, isFieldElement, setPathValue, getPathValue, focus, requestIntent } from '@conform-to/dom/future';
 import { serializeIntent } from './intent.mjs';
+import { hasFieldError } from './state.mjs';
 
 function getFormElement(formRef) {
-  var _element$form;
-  if (typeof formRef === 'string') {
-    return document.forms.namedItem(formRef);
+  if (typeof formRef === 'undefined') {
+    return null;
   }
-  var element = formRef === null || formRef === void 0 ? void 0 : formRef.current;
-  if (element instanceof HTMLFormElement) {
-    return element;
+  if (typeof formRef !== 'string') {
+    var element = formRef.current;
+    if (!element) {
+      return null;
+    }
+    return isGlobalInstance(element, 'HTMLFormElement') ? element : element.form;
   }
-  return (_element$form = element === null || element === void 0 ? void 0 : element.form) !== null && _element$form !== void 0 ? _element$form : null;
+  return document.forms.namedItem(formRef);
 }
 function getSubmitEvent(event) {
   if (event.type !== 'submit') {
@@ -41,125 +44,69 @@ function initializeField(element, options) {
   });
   element.dataset.conform = 'initialized';
 }
-
-/**
- * Makes hidden form inputs focusable with visually hidden styles
- */
-function makeInputFocusable(element) {
-  if (!element.hidden && element.type !== 'hidden') {
-    return;
-  }
-
-  // Style the element to be visually hidden
-  element.style.position = 'absolute';
-  element.style.width = '1px';
-  element.style.height = '1px';
-  element.style.padding = '0';
-  element.style.margin = '-1px';
-  element.style.overflow = 'hidden';
-  element.style.clip = 'rect(0,0,0,0)';
-  element.style.whiteSpace = 'nowrap';
-  element.style.border = '0';
-
-  // Hide the element from screen readers
-  element.setAttribute('aria-hidden', 'true');
-
-  // Make sure people won't tab to this element
-  element.tabIndex = -1;
-
-  // Set the element to be visible again so it can be focused
-  if (element.hidden) {
-    element.hidden = false;
-  }
-  if (element.type === 'hidden') {
-    element.setAttribute('type', 'text');
-  }
-}
-function getRadioGroupValue(inputs) {
-  for (var input of inputs) {
-    if (input.type === 'radio' && input.checked) {
-      return input.value;
-    }
-  }
-}
-function getCheckboxGroupValue(inputs) {
-  var values;
-  for (var input of inputs) {
-    if (input.type === 'checkbox') {
-      var _values;
-      (_values = values) !== null && _values !== void 0 ? _values : values = [];
-      if (input.checked) {
-        values.push(input.value);
+function resolveControlPayload(input) {
+  if (Array.isArray(input)) {
+    var options;
+    for (var element of input) {
+      if (element.type === 'radio' && element.checked) {
+        return element.value;
+      }
+      if (element.type === 'checkbox') {
+        var _options;
+        (_options = options) !== null && _options !== void 0 ? _options : options = [];
+        if (element.checked) {
+          options.push(element.value);
+        }
       }
     }
+    return options;
   }
-  return values;
-}
-function getInputSnapshot(input) {
   if (input instanceof HTMLInputElement) {
     switch (input.type) {
       case 'file':
-        return {
-          files: input.files ? Array.from(input.files) : undefined
-        };
+        {
+          return input.files ? Array.from(input.files) : [];
+        }
       case 'radio':
       case 'checkbox':
-        return {
-          value: input.value,
-          checked: input.checked
-        };
+        return input.checked ? input.value : null;
     }
   } else if (input instanceof HTMLSelectElement && input.multiple) {
-    return {
-      options: Array.from(input.selectedOptions).map(option => option.value)
-    };
-  }
-  return {
-    value: input.value
-  };
-}
-
-/**
- * Creates an InputSnapshot based on the provided options:
- * - checkbox/radio: value / defaultChecked
- * - file inputs: defaultValue is File or FileList
- * - select multiple: defaultValue is string array
- * - others: defaultValue is string
- */
-function createDefaultSnapshot(defaultValue, defaultChecked, value) {
-  if (typeof value === 'string' || typeof defaultChecked === 'boolean') {
-    return {
-      value: value !== null && value !== void 0 ? value : 'on',
-      checked: defaultChecked
-    };
-  }
-  if (typeof defaultValue === 'string') {
-    return {
-      value: defaultValue
-    };
-  }
-  if (Array.isArray(defaultValue)) {
-    if (defaultValue.every(item => typeof item === 'string')) {
-      return {
-        options: defaultValue
-      };
-    } else {
-      return {
-        files: defaultValue
-      };
+    return Array.from(input.selectedOptions).map(option => option.value);
+  } else if (input instanceof HTMLFieldSetElement) {
+    if (input.elements.length === 0) {
+      return null;
     }
+    var result = {};
+    var entries = new Map();
+    for (var _element of input.elements) {
+      if (isFieldElement(_element)) {
+        var payload = resolveControlPayload(_element);
+        var value = entries.get(_element.name);
+        if (_element.type === 'checkbox') {
+          entries.set(_element.name, value === undefined ? payload : (Array.isArray(value) ? [...value, payload] : [value, payload]).filter(v => v !== null));
+        } else if (_element.type === 'radio') {
+          entries.set(_element.name, value == null ? payload : payload === null ? value : payload);
+        } else {
+          entries.set(_element.name, value === undefined ? payload : Array.isArray(value) ? [...value, payload] : [value, payload]);
+        }
+      }
+    }
+    for (var [name, _value] of entries) {
+      setPathValue(result, name, _value);
+    }
+    return getPathValue(result, input.name);
   }
-  if (isGlobalInstance(defaultValue, 'File')) {
-    return {
-      files: [defaultValue]
-    };
+  return input.value;
+}
+function deriveDefaultPayload(options) {
+  if ('defaultChecked' in options && typeof options.defaultChecked === 'boolean') {
+    var _options$value2;
+    return options.defaultChecked ? (_options$value2 = options.value) !== null && _options$value2 !== void 0 ? _options$value2 : 'on' : null;
   }
-  if (isGlobalInstance(defaultValue, 'FileList')) {
-    return {
-      files: Array.from(defaultValue)
-    };
+  if ('defaultValue' in options) {
+    return options.defaultValue;
   }
-  return {};
 }
 
 /**
@@ -171,22 +118,33 @@ function focusFirstInvalidField(ctx) {
     return;
   }
   for (var element of ctx.formElement.elements) {
-    var _ctx$error$fieldError;
-    if (isFieldElement(element) && (_ctx$error$fieldError = ctx.error.fieldErrors[element.name]) !== null && _ctx$error$fieldError !== void 0 && _ctx$error$fieldError.length) {
+    if (!(isFieldElement(element) || element instanceof HTMLFieldSetElement) || element.name === '' || !hasFieldError(ctx.error, element.name)) {
+      continue;
+    }
+
+    // Treat fieldset as a focusable field only if it is hidden
+    if (element.type === 'fieldset' && !element.hidden) {
+      continue;
+    }
+    if (element.hidden || element.type === 'hidden' || element.type === 'fieldset') {
+      focus(element);
+    } else {
       element.focus();
-      break;
     }
+    break;
   }
 }
 function updateFormValue(form, targetValue, serialize) {
   for (var element of form.elements) {
     if (isFieldElement(element) && element.name && element.type !== 'hidden') {
-      var fieldValue = getValueAtPath(targetValue, element.name);
+      var fieldValue = getPathValue(targetValue, element.name);
       if (element.type === 'file' && fieldValue === undefined) {
         // Do not update file inputs unless there's a target value
         continue;
       }
-      var value = serialize(fieldValue);
+      var value = serialize(fieldValue, {
+        name: element.name
+      });
 
       // Treat undefined as null to clear the field value
       change(element, value !== undefined ? value : null, {
@@ -198,8 +156,10 @@ function updateFormValue(form, targetValue, serialize) {
 function resetFormValue(form, defaultValue, serialize) {
   for (var element of form.elements) {
     if (isFieldElement(element) && element.name && element.type !== 'hidden' && element.type !== 'file') {
-      var fieldValue = getValueAtPath(defaultValue, element.name);
-      var value = serialize(fieldValue);
+      var fieldValue = getPathValue(defaultValue, element.name);
+      var value = serialize(fieldValue, {
+        name: element.name
+      });
       updateField(element, {
         defaultValue: value !== undefined ? value : null
       });
@@ -358,4 +318,4 @@ function preserveInputs(inputs, form, name) {
   }
 }
 
-export { cleanupPreservedInputs, createDefaultSnapshot, createIntentDispatcher, focusFirstInvalidField, getCheckboxGroupValue, getFormElement, getInputSnapshot, getRadioGroupValue, getSubmitEvent, initializeField, makeInputFocusable, preserveInputs, resetFormValue, updateFormValue };
+export { cleanupPreservedInputs, createIntentDispatcher, deriveDefaultPayload, focusFirstInvalidField, getFormElement, getSubmitEvent, initializeField, preserveInputs, resetFormValue, resolveControlPayload, updateFormValue };