@conform-to/dom 1.0.0-pre.5 → 1.0.0-pre.7

package/README

@@ -0,0 +1,32 @@
+
+
+ ███████╗  ██████╗  ███╗  ██╗ ████████╗  ██████╗  ███████╗  ███╗ ███╗
+██╔═════╝ ██╔═══██╗ ████╗ ██║ ██╔═════╝ ██╔═══██╗ ██╔═══██╗ ████████║
+██║       ██║   ██║ ██╔██╗██║ ███████╗  ██║   ██║ ███████╔╝ ██╔██╔██║
+██║       ██║   ██║ ██║╚████║ ██╔════╝  ██║   ██║ ██╔═══██╗ ██║╚═╝██║
+╚███████╗ ╚██████╔╝ ██║ ╚███║ ██║       ╚██████╔╝ ██║   ██║ ██║   ██║
+ ╚══════╝  ╚═════╝  ╚═╝  ╚══╝ ╚═╝        ╚═════╝  ╚═╝   ╚═╝ ╚═╝   ╚═╝
+
+
+Version 1.0.0-pre.7 / 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 route action and Next.js server actions.
+
+> Getting Started
+
+Check out the overview and tutorial at our website https://conform.guide
+
+> Documentation
+
+The documentation is divided into several sections:
+
+* Overview: https://conform.guide/overview
+* Example Usages: https://conform.guide/examples
+* Complex structures: https://conform.guide/complex-structures
+* UI Integrations: https://conform.guide/integrations
+* Accessibility Guide: https://conform.guide/accessibility
+* API Reference: https://conform.guide/references
+
+> Support
+
+To report a bug, please open an issue on the repository at https://github.com/edmundhung/conform. For feature requests and questions, you can post them in the Discussions section.

package/form.d.ts

@@ -1,5 +1,5 @@
 import { getFormAction, getFormEncType, getFormMethod } from './dom';
-import { type FormControl, type Submission, type SubmissionResult } from './submission';
+import { type Intent, type Submission, type SubmissionResult } from './submission';
 export type UnionKeyof<T> = T extends any ? keyof T : never;
 export type UnionKeyType<T, K extends UnionKeyof<T>> = T extends {
     [k in K]?: any;
@@ -10,14 +10,17 @@ export type DefaultValue<Schema> = Schema extends string | number | boolean | Da
 export type FormValue<Schema> = Schema extends string | number | boolean | Date | null | undefined ? string | undefined : Schema extends File ? File | undefined : Schema extends Array<infer Item> ? Array<FormValue<Item>> | undefined : Schema extends Record<string, any> ? {
     [Key in UnionKeyof<Schema>]?: FormValue<UnionKeyType<Schema, Key>>;
 } | undefined : unknown;
+declare const error: unique symbol;
+declare const field: unique symbol;
+declare const form: unique symbol;
 export type FormId<Schema extends Record<string, unknown> = Record<string, unknown>, Error = string[]> = string & {
-    __error?: Error;
-    __schema?: Schema;
+    [error]?: Error;
+    [form]?: Schema;
 };
-export type FieldName<FieldSchema, Error = string[], FormSchema extends Record<string, unknown> = Record<string, unknown>> = string & {
-    __field?: FieldSchema;
-    __error?: Error;
-    __form?: FormSchema;
+export type FieldName<FieldSchema, FormSchema extends Record<string, unknown> = Record<string, unknown>, Error = string[]> = string & {
+    [field]?: FieldSchema;
+    [error]?: Error;
+    [form]?: FormSchema;
 };
 export type Constraint = {
     required?: boolean;
@@ -43,7 +46,7 @@ export type FormState<FormError> = FormMeta<FormError> & {
     valid: Record<string, boolean>;
     dirty: Record<string, boolean>;
 };
-export type FormOptions<Schema, FormError, Value = Schema> = {
+export type FormOptions<Schema, FormError = string[], FormValue = Schema> = {
     /**
      * The id of the form.
      */
@@ -59,7 +62,7 @@ export type FormOptions<Schema, FormError, Value = Schema> = {
     /**
      * An object describing the result of the last submission
      */
-    lastResult?: SubmissionResult<FormError>;
+    lastResult?: SubmissionResult<FormError> | null;
     /**
      * Define when conform should start validation.
      * Support "onSubmit", "onInput", "onBlur".
@@ -74,6 +77,11 @@ export type FormOptions<Schema, FormError, Value = Schema> = {
      * @default Same as shouldValidate, or "onSubmit" if shouldValidate is not provided.
      */
     shouldRevalidate?: 'onSubmit' | 'onBlur' | 'onInput';
+    /**
+     * Define if conform should considered the field for dirty state.
+     * e.g. Excluding form fields that are not managed by Conform, such as CSRF token
+     */
+    shouldDirtyConsider?: (name: string) => boolean;
     /**
      * A function to be called when the form should be (re)validated.
      */
@@ -81,7 +89,7 @@ export type FormOptions<Schema, FormError, Value = Schema> = {
         form: HTMLFormElement;
         submitter: HTMLInputElement | HTMLButtonElement | null;
         formData: FormData;
-    }) => Submission<Schema, FormError, Value>;
+    }) => Submission<Schema, FormError, FormValue>;
     /**
      * A function to be called before the form is submitted.
      */
@@ -90,7 +98,7 @@ export type FormOptions<Schema, FormError, Value = Schema> = {
         action: ReturnType<typeof getFormAction>;
         encType: ReturnType<typeof getFormEncType>;
         method: ReturnType<typeof getFormMethod>;
-        submission?: Submission<Schema, FormError, Value>;
+        submission?: Submission<Schema, FormError, FormValue>;
     }) => void;
 };
 export type SubscriptionSubject = {
@@ -108,18 +116,32 @@ export type ControlButtonProps = {
     form: string;
     formNoValidate: boolean;
 };
-export type FormContext<Schema extends Record<string, any> = any, FormError = string[], Value = Schema> = {
+export type FormContext<Schema extends Record<string, any> = any, FormValue = Schema, FormError = string[]> = {
     formId: string;
-    submit(event: SubmitEvent): void;
-    reset(event: Event): void;
-    input(event: Event): void;
-    blur(event: Event): void;
-    report(result: SubmissionResult<FormError>): void;
-    update(options: Omit<FormOptions<Schema, FormError, Value>, 'lastResult'>): void;
+    submit(event: SubmitEvent): Submission<Schema, FormError, FormValue> | undefined;
+    onReset(event: Event): void;
+    onInput(event: Event): void;
+    onBlur(event: Event): void;
+    onUpdate(options: Partial<FormOptions<Schema, FormError, FormValue>>): void;
     subscribe(callback: () => void, getSubject?: () => SubscriptionSubject | undefined): () => void;
-    dispatch(control: FormControl): void;
-    getControlButtonProps(control: FormControl): ControlButtonProps;
     getState(): FormState<FormError>;
     getSerializedState(): string;
+} & {
+    [Type in Intent['type']]: {} extends Extract<Intent, {
+        type: Type;
+    }>['payload'] ? (<FieldSchema = Schema>(payload?: Extract<Intent<FieldSchema>, {
+        type: Type;
+    }>['payload']) => void) & {
+        getButtonProps<FieldSchema = Schema>(payload?: Extract<Intent<FieldSchema>, {
+            type: Type;
+        }>['payload']): ControlButtonProps;
+    } : (<FieldSchema = Schema>(payload: Extract<Intent<FieldSchema>, {
+        type: Type;
+    }>['payload']) => void) & {
+        getButtonProps<FieldSchema = Schema>(payload: Extract<Intent<FieldSchema>, {
+            type: Type;
+        }>['payload']): ControlButtonProps;
+    };
 };
-export declare function createFormContext<Schema extends Record<string, any>, FormError, Value>(options: FormOptions<Schema, FormError, Value>): FormContext<Schema, FormError, Value>;
+export declare function createFormContext<Schema extends Record<string, any>, FormValue, FormError>(options: FormOptions<Schema, FormError, FormValue>): FormContext<Schema, FormValue, FormError>;
+export {};

package/form.js

@@ -27,8 +27,8 @@ function createFormMeta(options, initialized) {
     // We can consider adding a warning if it happens
     error: (_ref = lastResult === null || lastResult === void 0 ? void 0 : lastResult.error) !== null && _ref !== void 0 ? _ref : {}
   };
-  if (lastResult !== null && lastResult !== void 0 && lastResult.control) {
-    handleControl(result, lastResult.control);
+  if (lastResult !== null && lastResult !== void 0 && lastResult.intent) {
+    handleIntent(result, lastResult.intent);
   }
   return result;
 }
@@ -45,24 +45,24 @@ function getDefaultKey(defaultValue, prefix) {
     return result;
   }, {});
 }
-function handleControl(meta, control, initialized) {
-  switch (control.type) {
-    case 'replace':
+function handleIntent(meta, intent, initialized) {
+  switch (intent.type) {
+    case 'update':
       {
-        var _control$payload$name;
-        var _name = (_control$payload$name = control.payload.name) !== null && _control$payload$name !== void 0 ? _control$payload$name : '';
-        var value = control.payload.value;
-        updateValue(meta, _name, value);
+        if (typeof intent.payload.value !== 'undefined') {
+          var _intent$payload$name;
+          var _name = (_intent$payload$name = intent.payload.name) !== null && _intent$payload$name !== void 0 ? _intent$payload$name : '';
+          var value = intent.payload.value;
+          updateValue(meta, _name, value);
+        }
         break;
       }
     case 'reset':
       {
-        if (typeof control.payload.value === 'undefined' || control.payload.value) {
-          var _control$payload$name2;
-          var _name2 = (_control$payload$name2 = control.payload.name) !== null && _control$payload$name2 !== void 0 ? _control$payload$name2 : '';
-          var _value = formdata.getValue(meta.defaultValue, _name2);
-          updateValue(meta, _name2, _value);
-        }
+        var _intent$payload$name2;
+        var _name2 = (_intent$payload$name2 = intent.payload.name) !== null && _intent$payload$name2 !== void 0 ? _intent$payload$name2 : '';
+        var _value = formdata.getValue(meta.defaultValue, _name2);
+        updateValue(meta, _name2, _value);
         break;
       }
     case 'insert':
@@ -72,8 +72,8 @@ function handleControl(meta, control, initialized) {
         if (initialized) {
           meta.initialValue = util.clone(meta.initialValue);
           meta.key = util.clone(meta.key);
-          submission.setListState(meta.key, control, util.generateId);
-          submission.setListValue(meta.initialValue, control);
+          submission.setListState(meta.key, intent, util.generateId);
+          submission.setListValue(meta.initialValue, intent);
         }
         break;
       }
@@ -149,10 +149,34 @@ function createKeyProxy(key) {
   });
 }
 function createValidProxy(error) {
-  return createStateProxy(name => typeof error[name] === 'undefined');
+  return createStateProxy(name => {
+    var keys = Object.keys(error);
+    if (name === '') {
+      return keys.length === 0;
+    }
+    for (var key of keys) {
+      if (formdata.isPrefix(key, name) && typeof error[key] !== 'undefined') {
+        return false;
+      }
+    }
+    return true;
+  });
 }
-function createDirtyProxy(defaultValue, value) {
-  return createStateProxy(name => JSON.stringify(defaultValue[name]) !== JSON.stringify(value[name]));
+function createDirtyProxy(defaultValue, value, shouldDirtyConsider) {
+  return createStateProxy(name => JSON.stringify(defaultValue[name]) !== JSON.stringify(value[name], (key, value) => {
+    if (name === '' && key === '' && value) {
+      return Object.entries(value).reduce((result, _ref3) => {
+        var [name, value] = _ref3;
+        if (!shouldDirtyConsider(name)) {
+          return result;
+        }
+        return Object.assign(result !== null && result !== void 0 ? result : {}, {
+          [name]: value
+        });
+      }, undefined);
+    }
+    return value;
+  }));
 }
 function shouldNotify(prev, next, cache, scope) {
   var compareFn = arguments.length > 4 && arguments[4] !== undefined ? arguments[4] : (prev, next) => JSON.stringify(prev) !== JSON.stringify(next);
@@ -180,25 +204,6 @@ function shouldNotify(prev, next, cache, scope) {
   }
   return false;
 }
-function createFormState(next) {
-  var prev = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : next;
-  var state = arguments.length > 2 ? arguments[2] : undefined;
-  var defaultValue = !state || prev.defaultValue !== next.defaultValue ? createValueProxy(next.defaultValue) : state.defaultValue;
-  var initialValue = next.initialValue === next.defaultValue ? defaultValue : !state || prev.initialValue !== next.initialValue ? createValueProxy(next.initialValue) : state.initialValue;
-  var value = next.value === next.initialValue ? initialValue : !state || prev.value !== next.value ? createValueProxy(next.value) : state.value;
-  return {
-    submissionStatus: next.submissionStatus,
-    defaultValue,
-    initialValue,
-    value,
-    error: !state || prev.error !== next.error ? next.error : state.error,
-    validated: next.validated,
-    constraint: !state || prev.constraint !== next.constraint ? createConstraintProxy(next.constraint) : state.constraint,
-    key: !state || prev.key !== next.key ? createKeyProxy(next.key) : state.key,
-    valid: !state || prev.error !== next.error ? createValidProxy(next.error) : state.valid,
-    dirty: !state || prev.defaultValue !== next.defaultValue || prev.value !== next.value ? createDirtyProxy(defaultValue, value) : state.dirty
-  };
-}
 function createFormContext(options) {
   var subscribers = [];
   var latestOptions = options;
@@ -209,6 +214,28 @@ function createFormContext(options) {
     util.invariant(element !== null, "Form#".concat(latestOptions.formId, " does not exist"));
     return element;
   }
+  function createFormState(next) {
+    var prev = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : next;
+    var state = arguments.length > 2 ? arguments[2] : undefined;
+    var defaultValue = !state || prev.defaultValue !== next.defaultValue ? createValueProxy(next.defaultValue) : state.defaultValue;
+    var initialValue = next.initialValue === next.defaultValue ? defaultValue : !state || prev.initialValue !== next.initialValue ? createValueProxy(next.initialValue) : state.initialValue;
+    var value = next.value === next.initialValue ? initialValue : !state || prev.value !== next.value ? createValueProxy(next.value) : state.value;
+    return {
+      submissionStatus: next.submissionStatus,
+      defaultValue,
+      initialValue,
+      value,
+      error: !state || prev.error !== next.error ? next.error : state.error,
+      validated: next.validated,
+      constraint: !state || prev.constraint !== next.constraint ? createConstraintProxy(next.constraint) : state.constraint,
+      key: !state || prev.key !== next.key ? createKeyProxy(next.key) : state.key,
+      valid: !state || prev.error !== next.error ? createValidProxy(next.error) : state.valid,
+      dirty: !state || prev.defaultValue !== next.defaultValue || prev.value !== next.value ? createDirtyProxy(defaultValue, value, key => {
+        var _latestOptions$should, _latestOptions$should2;
+        return (_latestOptions$should = (_latestOptions$should2 = latestOptions.shouldDirtyConsider) === null || _latestOptions$should2 === void 0 ? void 0 : _latestOptions$should2.call(latestOptions, key)) !== null && _latestOptions$should !== void 0 ? _latestOptions$should : true;
+      }) : state.dirty
+    };
+  }
   function updateFormMeta(nextMeta) {
     var prevMeta = meta;
     var prevState = state;
@@ -242,12 +269,12 @@ function createFormContext(options) {
     var element = form.elements.namedItem(submission.STATE);
     util.invariant(element === null || dom.isFieldElement(element), "The input name \"".concat(submission.STATE, "\" is reserved by Conform. Please use another name."));
     if (!element) {
-      var _input = document.createElement('input');
-      _input.type = 'hidden';
-      _input.name = submission.STATE;
-      _input.value = '';
-      form.append(_input);
-      return _input;
+      var input = document.createElement('input');
+      input.type = 'hidden';
+      input.name = submission.STATE;
+      input.value = '';
+      form.append(input);
+      return input;
     }
     return element;
   }
@@ -257,7 +284,6 @@ function createFormContext(options) {
     });
   }
   function submit(event) {
-    var _latestOptions;
     var form = event.target;
     var submitter = event.submitter;
     util.invariant(form === getFormElement(), "The submit event is dispatched by form#".concat(form.id, " instead of form#").concat(latestOptions.formId));
@@ -272,24 +298,25 @@ function createFormContext(options) {
       encType: dom.getFormEncType(event),
       method: dom.getFormMethod(event)
     };
-    if (typeof ((_latestOptions = latestOptions) === null || _latestOptions === void 0 ? void 0 : _latestOptions.onValidate) === 'undefined') {
-      var _latestOptions$onSubm, _latestOptions2;
-      (_latestOptions$onSubm = (_latestOptions2 = latestOptions).onSubmit) === null || _latestOptions$onSubm === void 0 || _latestOptions$onSubm.call(_latestOptions2, event, context);
+    if (typeof (latestOptions === null || latestOptions === void 0 ? void 0 : latestOptions.onValidate) === 'undefined') {
+      var _latestOptions$onSubm;
+      (_latestOptions$onSubm = latestOptions.onSubmit) === null || _latestOptions$onSubm === void 0 || _latestOptions$onSubm.call(latestOptions, event, context);
+      return;
+    }
+    var submission = latestOptions.onValidate({
+      form,
+      formData,
+      submitter
+    });
+    if (submission.status !== 'success' && submission.error !== null) {
+      report(submission.reply());
     } else {
-      var _latestOptions$onSubm2, _latestOptions3;
-      var submission = latestOptions.onValidate({
-        form,
-        formData,
-        submitter
-      });
-      if (submission.status !== 'success' && submission.error !== null) {
-        report(submission.reply());
-        event.preventDefault();
-      }
-      (_latestOptions$onSubm2 = (_latestOptions3 = latestOptions).onSubmit) === null || _latestOptions$onSubm2 === void 0 || _latestOptions$onSubm2.call(_latestOptions3, event, _rollupPluginBabelHelpers.objectSpread2(_rollupPluginBabelHelpers.objectSpread2({}, context), {}, {
+      var _latestOptions$onSubm2;
+      (_latestOptions$onSubm2 = latestOptions.onSubmit) === null || _latestOptions$onSubm2 === void 0 || _latestOptions$onSubm2.call(latestOptions, event, _rollupPluginBabelHelpers.objectSpread2(_rollupPluginBabelHelpers.objectSpread2({}, context), {}, {
         submission
       }));
     }
+    return submission;
   }
   function resolveTarget(event) {
     var form = getFormElement();
@@ -307,33 +334,39 @@ function createFormContext(options) {
     var validated = meta.validated[element.name];
     return validated ? shouldRevalidate === eventName : shouldValidate === eventName;
   }
-  function input(event) {
+  function onInput(event) {
     var element = resolveTarget(event);
     if (!element || !element.form) {
       return;
     }
     if (event.defaultPrevented || !willValidate(element, 'onInput')) {
       var formData = new FormData(element.form);
-      var _result2 = submission.getSubmissionContext(formData);
+      var result = submission.getSubmissionContext(formData);
       updateFormMeta(_rollupPluginBabelHelpers.objectSpread2(_rollupPluginBabelHelpers.objectSpread2({}, meta), {}, {
-        value: _result2.payload
+        value: result.payload
       }));
     } else {
-      dispatch(submission.control.validate({
-        name: element.name
-      }));
+      dispatch({
+        type: 'validate',
+        payload: {
+          name: element.name
+        }
+      });
     }
   }
-  function blur(event) {
+  function onBlur(event) {
     var element = resolveTarget(event);
     if (!element || event.defaultPrevented || !willValidate(element, 'onBlur')) {
       return;
     }
-    dispatch(submission.control.validate({
-      name: element.name
-    }));
+    dispatch({
+      type: 'validate',
+      payload: {
+        name: element.name
+      }
+    });
   }
-  function reset(event) {
+  function onReset(event) {
     var element = getFormElement();
     if (event.type !== 'reset' || event.target !== element || event.defaultPrevented) {
       return;
@@ -347,8 +380,8 @@ function createFormContext(options) {
       formElement.reset();
       return;
     }
-    var error = Object.entries((_result$error = result.error) !== null && _result$error !== void 0 ? _result$error : {}).reduce((result, _ref3) => {
-      var [name, newError] = _ref3;
+    var error = Object.entries((_result$error = result.error) !== null && _result$error !== void 0 ? _result$error : {}).reduce((result, _ref4) => {
+      var [name, newError] = _ref4;
       var error = newError === null ? meta.error[name] : newError;
       if (error) {
         result[name] = error;
@@ -361,8 +394,8 @@ function createFormContext(options) {
       error,
       validated: (_result$state$validat = (_result$state = result.state) === null || _result$state === void 0 ? void 0 : _result$state.validated) !== null && _result$state$validat !== void 0 ? _result$state$validat : {}
     });
-    if (result.control) {
-      handleControl(update, result.control, true);
+    if (result.intent) {
+      handleIntent(update, result.intent, true);
     }
     updateFormMeta(update);
     if (result.status === 'error') {
@@ -374,11 +407,16 @@ function createFormContext(options) {
       }
     }
   }
-  function update(options) {
+  function onUpdate(options) {
     var currentFormId = latestOptions.formId;
-    latestOptions = options;
+    var currentResult = latestOptions.lastResult;
+
+    // Merge new options with the latest options
+    Object.assign(latestOptions, options);
     if (latestOptions.formId !== currentFormId) {
       getFormElement().reset();
+    } else if (options.lastResult && options.lastResult !== currentResult) {
+      report(options.lastResult);
     }
   }
   function subscribe(callback, getSubject) {
@@ -394,10 +432,10 @@ function createFormContext(options) {
   function getState() {
     return state;
   }
-  function dispatch(control) {
+  function dispatch(intent) {
     var form = getFormElement();
     var submitter = document.createElement('button');
-    var buttonProps = getControlButtonProps(control);
+    var buttonProps = getControlButtonProps(intent);
     submitter.name = buttonProps.name;
     submitter.value = buttonProps.value;
     submitter.hidden = true;
@@ -406,26 +444,47 @@ function createFormContext(options) {
     dom.requestSubmit(form, submitter);
     form === null || form === void 0 || form.removeChild(submitter);
   }
-  function getControlButtonProps(control) {
+  function getControlButtonProps(intent) {
     return {
-      name: submission.CONTROL,
-      value: submission.serializeControl(control),
+      name: submission.INTENT,
+      value: submission.serializeIntent(intent),
       form: latestOptions.formId,
       formNoValidate: true
     };
   }
+  function createFormControl(type) {
+    var control = function control() {
+      var payload = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+      return dispatch({
+        type,
+        payload
+      });
+    };
+    return Object.assign(control, {
+      getButtonProps() {
+        var payload = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+        return getControlButtonProps({
+          type,
+          payload
+        });
+      }
+    });
+  }
   return {
     get formId() {
       return latestOptions.formId;
     },
     submit,
-    reset,
-    input,
-    blur,
-    dispatch,
-    getControlButtonProps,
-    report,
-    update,
+    onReset,
+    onInput,
+    onBlur,
+    onUpdate,
+    validate: createFormControl('validate'),
+    reset: createFormControl('reset'),
+    update: createFormControl('update'),
+    insert: createFormControl('insert'),
+    remove: createFormControl('remove'),
+    reorder: createFormControl('reorder'),
     subscribe,
     getState,
     getSerializedState