@conform-to/dom 1.0.0-pre.6 → 1.0.0-rc.0

package/README

@@ -0,0 +1,32 @@
+
+
+ ███████╗  ██████╗  ███╗  ██╗ ████████╗  ██████╗  ███████╗  ███╗ ███╗
+██╔═════╝ ██╔═══██╗ ████╗ ██║ ██╔═════╝ ██╔═══██╗ ██╔═══██╗ ████████║
+██║       ██║   ██║ ██╔██╗██║ ███████╗  ██║   ██║ ███████╔╝ ██╔██╔██║
+██║       ██║   ██║ ██║╚████║ ██╔════╝  ██║   ██║ ██╔═══██╗ ██║╚═╝██║
+╚███████╗ ╚██████╔╝ ██║ ╚███║ ██║       ╚██████╔╝ ██║   ██║ ██║   ██║
+ ╚══════╝  ╚═════╝  ╚═╝  ╚══╝ ╚═╝        ╚═════╝  ╚═╝   ╚═╝ ╚═╝   ╚═╝
+
+
+Version 1.0.0-rc.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 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".
@@ -86,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.
      */
@@ -95,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 = {
@@ -113,17 +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;
-    update(options: Partial<FormOptions<Schema, FormError, Value>>): 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,7 +149,18 @@ 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, shouldDirtyConsider) {
   return createStateProxy(name => JSON.stringify(defaultValue[name]) !== JSON.stringify(value[name], (key, value) => {
@@ -258,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;
   }
@@ -290,21 +301,22 @@ function createFormContext(options) {
     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;
-      var submission = latestOptions.onValidate({
-        form,
-        formData,
-        submitter
-      });
-      if (submission.status !== 'success' && submission.error !== null) {
-        report(submission.reply());
-        event.preventDefault();
-      }
       (_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();
@@ -322,7 +334,7 @@ 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;
@@ -334,21 +346,27 @@ function createFormContext(options) {
         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;
@@ -376,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') {
@@ -389,7 +407,7 @@ function createFormContext(options) {
       }
     }
   }
-  function update(options) {
+  function onUpdate(options) {
     var currentFormId = latestOptions.formId;
     var currentResult = latestOptions.lastResult;
 
@@ -397,7 +415,7 @@ function createFormContext(options) {
     Object.assign(latestOptions, options);
     if (latestOptions.formId !== currentFormId) {
       getFormElement().reset();
-    } else if (typeof options.lastResult !== 'undefined' && options.lastResult !== currentResult) {
+    } else if (options.lastResult && options.lastResult !== currentResult) {
       report(options.lastResult);
     }
   }
@@ -414,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;
@@ -426,25 +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,
-    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