@conform-to/dom 0.9.0 → 1.0.0-pre.0

package/dom.d.ts

@@ -1,51 +1,43 @@
-export type FormControl = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement | HTMLButtonElement;
-export type Submitter = HTMLInputElement | HTMLButtonElement;
 /**
- * A type guard to check if the provided reference is a form control element, including
- * `input`, `select`, `textarea` or `button`
+ * Element that user can interact with,
+ * includes `<input>`, `<select>` and `<textarea>`.
  */
-export declare function isFormControl(element: unknown): element is FormControl;
+export type FieldElement = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
 /**
- * A type guard to check if the provided reference is a focusable form control element.
+ * HTML Element that can be used as a form control,
+ * includes `<input>`, `<select>`, `<textarea>` and `<button>`.
  */
-export declare function isFocusableFormControl(element: unknown): element is FormControl;
-/**
- * Resolves the form action based on the submit event
- */
-export declare function getFormAction(event: SubmitEvent): string;
+export type FormControl = FieldElement | HTMLButtonElement;
 /**
- * Resolves the form encoding type based on the submit event
+ * Form Control element. It can either be a submit button or a submit input.
  */
-export declare function getFormEncType(event: SubmitEvent): 'application/x-www-form-urlencoded' | 'multipart/form-data';
+export type Submitter = HTMLInputElement | HTMLButtonElement;
 /**
- * Resolves the form method based on the submit event
+ * A type guard to check if the provided element is a form control
  */
-export declare function getFormMethod(event: SubmitEvent): 'get' | 'post' | 'put' | 'patch' | 'delete';
+export declare function isFormControl(element: unknown): element is FormControl;
 /**
- * Resolve the form element
+ * 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 getFormElement(element: HTMLFormElement | HTMLFieldSetElement | HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement | HTMLButtonElement | null): HTMLFormElement | null;
+export declare function isFieldElement(element: unknown): element is FieldElement;
 /**
- * Returns a list of form control elements in the form
+ * Resolves the action from the submit event
+ * with respect to the submitter `formaction` attribute.
  */
-export declare function getFormControls(form: HTMLFormElement): FormControl[];
+export declare function getFormAction(event: SubmitEvent): string;
 /**
- * A function to create a submitter button element
+ * Resolves the encoding type from the submit event
+ * with respect to the submitter `formenctype` attribute.
  */
-export declare function createSubmitter(config: {
-    name: string;
-    value: string;
-    hidden?: boolean;
-    formAction?: string;
-    formEnctype?: ReturnType<typeof getFormEncType>;
-    formMethod?: ReturnType<typeof getFormMethod>;
-    formNoValidate?: boolean;
-}): HTMLButtonElement;
+export declare function getFormEncType(event: SubmitEvent): 'application/x-www-form-urlencoded' | 'multipart/form-data';
 /**
- * Trigger form submission with a submitter.
+ * Resolves the method from the submit event
+ * with respect to the submitter `formmethod` attribute.
  */
-export declare function requestSubmit(form: HTMLFormElement, submitter: Submitter | null): void;
+export declare function getFormMethod(event: SubmitEvent): 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 /**
- * Focus on the first invalid form control in the form
+ * 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 focusFirstInvalidControl(form: HTMLFormElement): void;
+export declare function requestSubmit(form: HTMLFormElement | null | undefined, submitter: Submitter | null): void;

package/dom.js

@@ -2,23 +2,40 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
+var util = require('./util.js');
+
+/**
+ * Element that user can interact with,
+ * includes `<input>`, `<select>` and `<textarea>`.
+ */
+
+/**
+ * HTML Element that can be used as a form control,
+ * includes `<input>`, `<select>`, `<textarea>` and `<button>`.
+ */
+
+/**
+ * Form Control element. It can either be a submit button or a submit input.
+ */
+
 /**
- * A type guard to check if the provided reference is a form control element, including
- * `input`, `select`, `textarea` or `button`
+ * A type guard to check if the provided element is a form control
  */
 function isFormControl(element) {
   return element instanceof Element && (element.tagName === 'INPUT' || element.tagName === 'SELECT' || element.tagName === 'TEXTAREA' || element.tagName === 'BUTTON');
 }
 
 /**
- * A type guard to check if the provided reference is a focusable form control element.
+ * A type guard to check if the provided element is a field element, which
+ * is a form control excluding submit, button and reset type.
  */
-function isFocusableFormControl(element) {
-  return isFormControl(element) && element.willValidate && element.type !== 'submit';
+function isFieldElement(element) {
+  return isFormControl(element) && element.type !== 'submit' && element.type !== 'button' && element.type !== 'reset';
 }
 
 /**
- * Resolves the form action based on the submit event
+ * Resolves the action from the submit event
+ * with respect to the submitter `formaction` attribute.
  */
 function getFormAction(event) {
   var _ref, _submitter$getAttribu;
@@ -28,7 +45,8 @@ function getFormAction(event) {
 }
 
 /**
- * Resolves the form encoding type based on the submit event
+ * Resolves the encoding type from the submit event
+ * with respect to the submitter `formenctype` attribute.
  */
 function getFormEncType(event) {
   var _submitter$getAttribu2;
@@ -42,67 +60,30 @@ function getFormEncType(event) {
 }
 
 /**
- * Resolves the form method based on the submit event
+ * Resolves the method from the submit event
+ * with respect to the submitter `formmethod` attribute.
  */
 function getFormMethod(event) {
-  var _submitter$getAttribu3;
+  var _ref2, _submitter$getAttribu3;
   var form = event.target;
   var submitter = event.submitter;
-  var method = (_submitter$getAttribu3 = submitter === null || submitter === void 0 ? void 0 : submitter.getAttribute('formmethod')) !== null && _submitter$getAttribu3 !== void 0 ? _submitter$getAttribu3 : form.getAttribute('method');
+  var method = (_ref2 = (_submitter$getAttribu3 = submitter === null || submitter === void 0 ? void 0 : submitter.getAttribute('formmethod')) !== null && _submitter$getAttribu3 !== void 0 ? _submitter$getAttribu3 : form.getAttribute('method')) === null || _ref2 === void 0 ? void 0 : _ref2.toUpperCase();
   switch (method) {
-    case 'post':
-    case 'put':
-    case 'patch':
-    case 'delete':
+    case 'POST':
+    case 'PUT':
+    case 'PATCH':
+    case 'DELETE':
       return method;
   }
-  return 'get';
-}
-
-/**
- * Resolve the form element
- */
-function getFormElement(element) {
-  var _element$form;
-  return element instanceof HTMLFormElement ? element : (_element$form = element === null || element === void 0 ? void 0 : element.form) !== null && _element$form !== void 0 ? _element$form : null;
-}
-
-/**
- * Returns a list of form control elements in the form
- */
-function getFormControls(form) {
-  return Array.from(form.elements).filter(isFormControl);
-}
-
-/**
- * A function to create a submitter button element
- */
-function createSubmitter(config) {
-  var button = document.createElement('button');
-  button.name = config.name;
-  button.value = config.value;
-  if (config.hidden) {
-    button.hidden = true;
-  }
-  if (config.formAction) {
-    button.formAction = config.formAction;
-  }
-  if (config.formEnctype) {
-    button.formEnctype = config.formEnctype;
-  }
-  if (config.formMethod) {
-    button.formMethod = config.formMethod;
-  }
-  if (config.formNoValidate) {
-    button.formNoValidate = true;
-  }
-  return button;
+  return 'GET';
 }
 
 /**
- * Trigger form submission with a 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.
  */
 function requestSubmit(form, submitter) {
+  util.invariant(!!form, 'Failed to submit the form. The element provided is null or undefined.');
   var shouldRemoveSubmitter = false;
   if (submitter && !submitter.isConnected) {
     shouldRemoveSubmitter = true;
@@ -123,25 +104,9 @@ function requestSubmit(form, submitter) {
   }
 }
 
-/**
- * Focus on the first invalid form control in the form
- */
-function focusFirstInvalidControl(form) {
-  for (var element of form.elements) {
-    if (isFocusableFormControl(element) && !element.validity.valid) {
-      element.focus();
-      break;
-    }
-  }
-}
-
-exports.createSubmitter = createSubmitter;
-exports.focusFirstInvalidControl = focusFirstInvalidControl;
 exports.getFormAction = getFormAction;
-exports.getFormControls = getFormControls;
-exports.getFormElement = getFormElement;
 exports.getFormEncType = getFormEncType;
 exports.getFormMethod = getFormMethod;
-exports.isFocusableFormControl = isFocusableFormControl;
+exports.isFieldElement = isFieldElement;
 exports.isFormControl = isFormControl;
 exports.requestSubmit = requestSubmit;

package/dom.mjs

@@ -1,20 +1,37 @@
+import { invariant } from './util.mjs';
+
+/**
+ * Element that user can interact with,
+ * includes `<input>`, `<select>` and `<textarea>`.
+ */
+
+/**
+ * HTML Element that can be used as a form control,
+ * includes `<input>`, `<select>`, `<textarea>` and `<button>`.
+ */
+
+/**
+ * Form Control element. It can either be a submit button or a submit input.
+ */
+
 /**
- * A type guard to check if the provided reference is a form control element, including
- * `input`, `select`, `textarea` or `button`
+ * A type guard to check if the provided element is a form control
  */
 function isFormControl(element) {
   return element instanceof Element && (element.tagName === 'INPUT' || element.tagName === 'SELECT' || element.tagName === 'TEXTAREA' || element.tagName === 'BUTTON');
 }
 
 /**
- * A type guard to check if the provided reference is a focusable form control element.
+ * A type guard to check if the provided element is a field element, which
+ * is a form control excluding submit, button and reset type.
  */
-function isFocusableFormControl(element) {
-  return isFormControl(element) && element.willValidate && element.type !== 'submit';
+function isFieldElement(element) {
+  return isFormControl(element) && element.type !== 'submit' && element.type !== 'button' && element.type !== 'reset';
 }
 
 /**
- * Resolves the form action based on the submit event
+ * Resolves the action from the submit event
+ * with respect to the submitter `formaction` attribute.
  */
 function getFormAction(event) {
   var _ref, _submitter$getAttribu;
@@ -24,7 +41,8 @@ function getFormAction(event) {
 }
 
 /**
- * Resolves the form encoding type based on the submit event
+ * Resolves the encoding type from the submit event
+ * with respect to the submitter `formenctype` attribute.
  */
 function getFormEncType(event) {
   var _submitter$getAttribu2;
@@ -38,67 +56,30 @@ function getFormEncType(event) {
 }
 
 /**
- * Resolves the form method based on the submit event
+ * Resolves the method from the submit event
+ * with respect to the submitter `formmethod` attribute.
  */
 function getFormMethod(event) {
-  var _submitter$getAttribu3;
+  var _ref2, _submitter$getAttribu3;
   var form = event.target;
   var submitter = event.submitter;
-  var method = (_submitter$getAttribu3 = submitter === null || submitter === void 0 ? void 0 : submitter.getAttribute('formmethod')) !== null && _submitter$getAttribu3 !== void 0 ? _submitter$getAttribu3 : form.getAttribute('method');
+  var method = (_ref2 = (_submitter$getAttribu3 = submitter === null || submitter === void 0 ? void 0 : submitter.getAttribute('formmethod')) !== null && _submitter$getAttribu3 !== void 0 ? _submitter$getAttribu3 : form.getAttribute('method')) === null || _ref2 === void 0 ? void 0 : _ref2.toUpperCase();
   switch (method) {
-    case 'post':
-    case 'put':
-    case 'patch':
-    case 'delete':
+    case 'POST':
+    case 'PUT':
+    case 'PATCH':
+    case 'DELETE':
       return method;
   }
-  return 'get';
-}
-
-/**
- * Resolve the form element
- */
-function getFormElement(element) {
-  var _element$form;
-  return element instanceof HTMLFormElement ? element : (_element$form = element === null || element === void 0 ? void 0 : element.form) !== null && _element$form !== void 0 ? _element$form : null;
-}
-
-/**
- * Returns a list of form control elements in the form
- */
-function getFormControls(form) {
-  return Array.from(form.elements).filter(isFormControl);
-}
-
-/**
- * A function to create a submitter button element
- */
-function createSubmitter(config) {
-  var button = document.createElement('button');
-  button.name = config.name;
-  button.value = config.value;
-  if (config.hidden) {
-    button.hidden = true;
-  }
-  if (config.formAction) {
-    button.formAction = config.formAction;
-  }
-  if (config.formEnctype) {
-    button.formEnctype = config.formEnctype;
-  }
-  if (config.formMethod) {
-    button.formMethod = config.formMethod;
-  }
-  if (config.formNoValidate) {
-    button.formNoValidate = true;
-  }
-  return button;
+  return 'GET';
 }
 
 /**
- * Trigger form submission with a 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.
  */
 function requestSubmit(form, submitter) {
+  invariant(!!form, 'Failed to submit the form. The element provided is null or undefined.');
   var shouldRemoveSubmitter = false;
   if (submitter && !submitter.isConnected) {
     shouldRemoveSubmitter = true;
@@ -119,16 +100,4 @@ function requestSubmit(form, submitter) {
   }
 }
 
-/**
- * Focus on the first invalid form control in the form
- */
-function focusFirstInvalidControl(form) {
-  for (var element of form.elements) {
-    if (isFocusableFormControl(element) && !element.validity.valid) {
-      element.focus();
-      break;
-    }
-  }
-}
-
-export { createSubmitter, focusFirstInvalidControl, getFormAction, getFormControls, getFormElement, getFormEncType, getFormMethod, isFocusableFormControl, isFormControl, requestSubmit };
+export { getFormAction, getFormEncType, getFormMethod, isFieldElement, isFormControl, requestSubmit };

package/form.d.ts

@@ -0,0 +1,101 @@
+import { getFormAction, getFormEncType, getFormMethod } from './dom';
+import { 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;
+} ? T[K] : undefined;
+export type FormValue<Schema> = Schema extends string | number | boolean | Date | null | undefined ? Schema | string : Schema extends File ? undefined : Schema extends Array<infer InnerType> ? Array<FormValue<InnerType>> : Schema extends Record<string, any> ? {
+    [Key in UnionKeyof<Schema>]?: FormValue<UnionKeyType<Schema, Key>>;
+} : any;
+export type FieldName<Schema> = string & {
+    __type?: Schema;
+};
+export type Constraint = {
+    required?: boolean;
+    minLength?: number;
+    maxLength?: number;
+    min?: string | number;
+    max?: string | number;
+    step?: string | number;
+    multiple?: boolean;
+    pattern?: string;
+};
+export type FormState = {
+    key: Record<string, string>;
+    validated: Record<string, boolean>;
+    valid: Record<string, boolean>;
+    dirty: Record<string, boolean>;
+};
+export type FormContext = {
+    defaultValue: Record<string, unknown>;
+    initialValue: Record<string, unknown>;
+    value: Record<string, unknown>;
+    error: Record<string, string[]>;
+    constraint: Record<string, Constraint>;
+    state: FormState;
+};
+export type FormOptions<Schema> = {
+    /**
+     * An object representing the initial value of the form.
+     */
+    defaultValue?: FormValue<Schema>;
+    /**
+     * An object describing the constraint of each field
+     */
+    constraint?: Record<string, Constraint>;
+    /**
+     * An object describing the result of the last submission
+     */
+    lastResult?: SubmissionResult;
+    /**
+     * Define when conform should start validation.
+     * Support "onSubmit", "onInput", "onBlur".
+     *
+     * @default "onSubmit"
+     */
+    shouldValidate?: 'onSubmit' | 'onBlur' | 'onInput';
+    /**
+     * Define when conform should revalidate again.
+     * Support "onSubmit", "onInput", "onBlur".
+     *
+     * @default Same as shouldValidate, or "onSubmit" if shouldValidate is not provided.
+     */
+    shouldRevalidate?: 'onSubmit' | 'onBlur' | 'onInput';
+    /**
+     * A function to be called when the form should be (re)validated.
+     */
+    onValidate?: (context: {
+        form: HTMLFormElement;
+        submitter: HTMLInputElement | HTMLButtonElement | null;
+        formData: FormData;
+    }) => Submission<Schema>;
+};
+export type SubscriptionSubject = {
+    [key in 'error' | 'initialValue' | 'value' | 'key' | 'validated' | 'valid' | 'dirty']?: SubscriptionScope;
+};
+export type SubscriptionScope = {
+    prefix?: string[];
+    name?: string[];
+};
+export type Form<Schema extends Record<string, any> = any> = {
+    id: string;
+    submit(event: SubmitEvent): {
+        formData: FormData;
+        action: ReturnType<typeof getFormAction>;
+        encType: ReturnType<typeof getFormEncType>;
+        method: ReturnType<typeof getFormMethod>;
+        submission?: Submission<Schema>;
+    };
+    reset(event: Event): void;
+    input(event: Event): void;
+    blur(event: Event): void;
+    initialize(): void;
+    report(result: SubmissionResult): void;
+    update(options: Omit<FormOptions<Schema>, 'lastResult'>): void;
+    subscribe(callback: () => void, getSubject?: () => SubscriptionSubject | undefined): () => void;
+    getContext(): FormContext;
+    getSerializedState(): string;
+};
+export declare const VALIDATION_UNDEFINED = "__undefined__";
+export declare const VALIDATION_SKIPPED = "__skipped__";
+export declare function createForm<Schema extends Record<string, any> = any>(formId: string, options: FormOptions<Schema>): Form<Schema>;