@conform-to/react 0.4.0-pre.1 → 0.4.0-pre.2

package/README.md

@@ -10,8 +10,12 @@
 - [useFieldset](#usefieldset)
 - [useFieldList](#usefieldlist)
 - [useControlledInput](#usecontrolledinput)
-- [createValidate](#createvalidate)
 - [conform](#conform)
+- [hasError](#haserror)
+- [isFieldElement](#isfieldelement)
+- [parse](#parse)
+- [setFormError](#setformerror)
+- [shouldValidate](#shouldvalidate)
 
 <!-- /aside -->
 
@@ -21,15 +25,23 @@ By default, the browser calls the [reportValidity()](https://developer.mozilla.o
 
 This hook enhances the form validation behaviour in 3 parts:
 
-1. It lets you hook up custom validation logic into different form events. For example, revalidation will be triggered whenever something changed.
-2. It provides options for you to decide the best timing to start reporting errors. This could be as earliest as the user start typing, or also as late as the user try submitting the form.
+1. It enhances form validation with custom rules by subscribing to different DOM events and reporting the errors only when it is configured to do so.
+2. It unifies client and server validation in one place.
 3. It exposes the state of each field in the form of [data attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/data-*), such as `data-conform-touched`, allowing flexible styling across your form without the need to manipulate the class names.
 
 ```tsx
 import { useForm } from '@conform-to/react';
 
 function LoginForm() {
-  const formProps = useForm({
+  const form = useForm({
+    /**
+     * Validation mode.
+     * Support "client-only" or "server-validation".
+     *
+     * Default to `client-only`.
+     */
+    mode: 'client-only',
+
     /**
      * Define when the error should be reported initially.
      * Support "onSubmit", "onChange", "onBlur".
@@ -38,6 +50,16 @@ function LoginForm() {
      */
     initialReport: 'onBlur',
 
+    /**
+     * An object representing the initial value of the form.
+     */
+    defaultValue: undefined;
+
+    /**
+     * An object describing the state from the last submission
+     */
+    state: undefined;
+
     /**
      * Enable native validation before hydation.
      *
@@ -54,43 +76,38 @@ function LoginForm() {
 
     /**
      * A function to be called when the form should be (re)validated.
+     * Only sync validation is supported
      */
-    validate(form, submitter) {
+    onValidate({ form, formData, submission }) {
       // ...
     },
 
     /**
      * The submit event handler of the form.
      */
-    onSubmit(event) {
+    onSubmit(event, { form, formData, submission }) {
       // ...
     },
   });
 
-  return (
-    <form {...formProps}>
-      <input type="email" name="email" required />
-      <input type="password" name="password" required />
-      <button type="submit">Login</button>
-    </form>
-  );
+  // ...
 }
 ```
 
 <details>
-<summary>What is `formProps`?</summary>
+<summary>What is `form.props`?</summary>
 
 It is a group of properties properties required to hook into form events. They can also be set explicitly as shown below:
 
 ```tsx
 function RandomForm() {
-  const formProps = useForm();
+  const form = useForm();
 
   return (
     <form
-      ref={formProps.ref}
-      onSubmit={formProps.onSubmit}
-      noValidate={formProps.noValidate}
+      ref={form.props.ref}
+      onSubmit={form.props.onSubmit}
+      noValidate={form.props.noValidate}
     >
       {/* ... */}
     </form>
@@ -103,17 +120,17 @@ function RandomForm() {
 <details>
 <summary>Does it work with custom form component like Remix Form?</summary>
 
-Yes! It will fallback to native form submission if the submit event handler is omitted or the event is not default prevented.
+Yes! It will fallback to native form submission as long as the submit event is not default prevented.
 
 ```tsx
 import { useFrom } from '@conform-to/react';
 import { Form } from '@remix-run/react';
 
 function LoginForm() {
-  const formProps = useForm();
+  const form = useForm();
 
   return (
-    <Form method="post" action="/login" {...formProps}>
+    <Form method="post" action="/login" {...form.props}>
       {/* ... */}
     </Form>
   );
@@ -123,9 +140,9 @@ function LoginForm() {
 </details>
 
 <details>
-<summary>Is the `validate` function required?</summary>
+<summary>Is the `onValidate` function required?</summary>
 
-The `validate` function is not required if the validation logic can be fully covered by the [native constraints](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Constraint_validation#validation-related_attributes), e.g. **required** / **min** / **pattern** etc.
+The `onValidate` function is not required if the validation logic can be fully covered by the [native constraints](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Constraint_validation#validation-related_attributes), e.g. **required** / **min** / **pattern** etc.
 
 ```tsx
 import { useForm, useFieldset } from '@conform-to/react';
@@ -156,10 +173,10 @@ function LoginForm() {
 
 ### useFieldset
 
-This hook can be used to monitor the state of each field and help fields configuration. It lets you:
+This hook can be used to monitor the state of each field and help configuration. It lets you:
 
 1. Capturing errors at the form/fieldset level, removing the need to setup invalid handler on each field.
-2. Defining config in one central place. e.g. name, default value and constraint, then distributing it to each field using the [conform](#conform) helpers.
+2. Defining config in one central place. e.g. name, default value and constraint, then distributing it to each field with the [conform](#conform) helpers.
 
 ```tsx
 import { useForm, useFieldset } from '@conform-to/react';
@@ -493,58 +510,7 @@ function MuiForm() {
         <MenuItem value="c">Category C</MenuItem>
       </TextField>
     </fieldset>
-  )
-}
-```
-
----
-
-### createValidate
-
-This help you configure a validate function to check the validity of each fields and setup custom messages using the Constraint Validation APIs.
-
-```tsx
-import { useForm, createValidate } from '@conform-to/react';
-
-export default function SignupForm() {
-  const formProps = useForm({
-    validate: createValidate((field, formData) => {
-      switch (field.name) {
-        case 'email':
-          if (field.validity.valueMissing) {
-            field.setCustomValidity('Email is required');
-          } else if (field.validity.typeMismatch) {
-            field.setCustomValidity('Please enter a valid email');
-          } else {
-            field.setCustomValidity('');
-          }
-          break;
-        case 'password':
-          if (field.validity.valueMissing) {
-            field.setCustomValidity('Password is required');
-          } else if (field.validity.tooShort) {
-            field.setCustomValidity(
-              'The password should be at least 10 characters long',
-            );
-          } else {
-            field.setCustomValidity('');
-          }
-          break;
-        case 'confirm-password': {
-          if (field.validity.valueMissing) {
-            field.setCustomValidity('Confirm Password is required');
-          } else if (field.value !== formData.get('password')) {
-            field.setCustomValidity('The password does not match');
-          } else {
-            field.setCustomValidity('');
-          }
-          break;
-        }
-      }
-    }),
-  });
-
-  return <form {...formProps}>{/* ... */}</form>;
+  );
 }
 ```
 
@@ -615,3 +581,146 @@ function RandomForm() {
   );
 }
 ```
+
+### hasError
+
+This helper checks if there is any message defined in error array with the provided name.
+
+```ts
+import { hasError } from '@conform-to/react';
+
+/**
+ * Assume the error looks like this:
+ */
+const error = [['email', 'Email is required']];
+
+// This will log `true`
+console.log(hasError(error, 'email'));
+
+// This will log `false`
+console.log(hasError(error, 'password'));
+```
+
+---
+
+### isFieldElement
+
+This checks if the provided element is an `input` / `select` / `textarea` or `button` HTML element with type guard. Useful when you need to access the validityState of the fields and modify the validation message manually.
+
+```tsx
+import { isFieldElement } from '@conform-to/react';
+
+export default function SignupForm() {
+  const form = useForm({
+    onValidate({ form }) {
+      for (const element of form.elements) {
+        if (isFieldElement(element)) {
+          switch (field.name) {
+            case 'email':
+              if (field.validity.valueMissing) {
+                field.setCustomValidity('Email is required');
+              } else if (field.validity.typeMismatch) {
+                field.setCustomValidity('Please enter a valid email');
+              } else {
+                field.setCustomValidity('');
+              }
+              break;
+            case 'password':
+              if (field.validity.valueMissing) {
+                field.setCustomValidity('Password is required');
+              } else if (field.validity.tooShort) {
+                field.setCustomValidity(
+                  'The password should be at least 10 characters long',
+                );
+              } else {
+                field.setCustomValidity('');
+              }
+              break;
+            case 'confirm-password': {
+              if (field.validity.valueMissing) {
+                field.setCustomValidity('Confirm Password is required');
+              } else if (field.value !== formData.get('password')) {
+                field.setCustomValidity('The password does not match');
+              } else {
+                field.setCustomValidity('');
+              }
+              break;
+            }
+          }
+        }
+      }
+    },
+  });
+
+  // ...
+}
+```
+
+---
+
+### parse
+
+It parses the formData based on the [naming convention](/docs/submission).
+
+```tsx
+import { parse } from '@conform-to/react';
+
+const formData = new FormData(formElement);
+const submission = parse(formData);
+
+console.log(submission);
+```
+
+---
+
+### setFormError
+
+This helpers updates the form error based on the submission result by looping through all elements in the form and update the error with the [setCustomValidity](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity) API.
+
+```tsx
+import { setFormError } from '@conform-to/react';
+
+function ExampleForm() {
+  const form = useForm({
+    onValidate({ form, submission }) {
+      const error = validate(submission);
+
+      setFormError(form, {
+        ...submission,
+        error,
+      });
+    },
+  });
+
+  // ...
+}
+```
+
+---
+
+### shouldValidate
+
+This helper checks if the scope of validation includes a specific field by checking the submission:
+
+```tsx
+import { shouldValidate } from '@conform-to/react';
+
+/**
+ * The submission type and metadata give us hint on what should be valdiated.
+ * If the type is 'validate', only the field with name matching the metadata must be validated.
+ *
+ * However, if the type is `undefined`, both will log true (Default submission)
+ */
+const submission = {
+  type: 'validate',
+  metadata: 'email',
+  value: {},
+  error: [],
+};
+
+// This will log 'true'
+console.log(shouldValidate(submission, 'email'));
+
+// This will log 'false'
+console.log(shouldValidate(submission, 'password'));
+```

package/hooks.d.ts

@@ -40,7 +40,7 @@ export interface FormConfig<Schema extends Record<string, any>> {
     /**
      * A function to be called when the form should be (re)validated.
      */
-    onValidate?: (context: FormContext<Schema>) => void;
+    onValidate?: (context: FormContext<Schema>) => Array<[string, string]>;
     /**
      * The submit event handler of the form. It will be called
      * only when the form is considered valid.
@@ -65,7 +65,7 @@ interface Form<Schema extends Record<string, any>> {
  * Returns properties required to hook into form events.
  * Applied custom validation and define when error should be reported.
  *
- * @see https://github.com/edmundhung/conform/tree/v0.4.0-pre.1/packages/conform-react/README.md#useform
+ * @see https://github.com/edmundhung/conform/tree/v0.4.0-pre.2/packages/conform-react/README.md#useform
  */
 export declare function useForm<Schema extends Record<string, any>>(config?: FormConfig<Schema>): Form<Schema>;
 /**
@@ -106,7 +106,7 @@ export interface FieldsetConfig<Schema extends Record<string, any>> {
 /**
  * Returns all the information about the fieldset.
  *
- * @see https://github.com/edmundhung/conform/tree/v0.4.0-pre.1/packages/conform-react/README.md#usefieldset
+ * @see https://github.com/edmundhung/conform/tree/v0.4.0-pre.2/packages/conform-react/README.md#usefieldset
  */
 export declare function useFieldset<Schema extends Record<string, any>>(ref: RefObject<HTMLFormElement | HTMLFieldSetElement>, config?: FieldsetConfig<Schema>): Fieldset<Schema>;
 export declare function useFieldset<Schema extends Record<string, any>>(ref: RefObject<HTMLFormElement | HTMLFieldSetElement>, config?: FieldConfig<Schema>): Fieldset<Schema>;
@@ -133,7 +133,7 @@ interface ListControl<Schema> {
  * Returns a list of key and config, with a group of helpers
  * configuring buttons for list manipulation
  *
- * @see https://github.com/edmundhung/conform/tree/v0.4.0-pre.1/packages/conform-react/README.md#usefieldlist
+ * @see https://github.com/edmundhung/conform/tree/v0.4.0-pre.2/packages/conform-react/README.md#usefieldlist
  */
 export declare function useFieldList<Payload = any>(ref: RefObject<HTMLFormElement | HTMLFieldSetElement>, config: FieldConfig<Array<Payload>>): [
     Array<{
@@ -163,7 +163,7 @@ interface InputControl<Element extends {
  * This is particular useful when integrating dropdown and datepicker whichs
  * introduces custom input mode.
  *
- * @see https://github.com/edmundhung/conform/tree/v0.4.0-pre.1/packages/conform-react/README.md#usecontrolledinput
+ * @see https://github.com/edmundhung/conform/tree/v0.4.0-pre.2/packages/conform-react/README.md#usecontrolledinput
  */
 export declare function useControlledInput<Element extends {
     focus: () => void;

package/hooks.js

@@ -11,7 +11,7 @@ var helpers = require('./helpers.js');
  * Returns properties required to hook into form events.
  * Applied custom validation and define when error should be reported.
  *
- * @see https://github.com/edmundhung/conform/tree/v0.4.0-pre.1/packages/conform-react/README.md#useform
+ * @see https://github.com/edmundhung/conform/tree/v0.4.0-pre.2/packages/conform-react/README.md#useform
  */
 function useForm() {
   var config = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
@@ -182,48 +182,62 @@ function useForm() {
           return;
         }
 
-        var formData = dom.getFormData(form, submitter);
-        var submission = dom.parse(formData);
-        var context = {
-          form,
-          formData,
-          submission
-        }; // Touch all fields only if the submitter is not a command button
-
-        if (!submission.type) {
-          for (var field of form.elements) {
-            if (dom.isFieldElement(field)) {
-              // Mark the field as touched
-              field.dataset.conformTouched = 'true';
+        try {
+          var formData = dom.getFormData(form, submitter);
+          var submission = dom.parse(formData);
+          var _context = {
+            form,
+            formData,
+            submission
+          }; // Touch all fields only if the submitter is not a command button
+
+          if (submission.context === 'submit') {
+            for (var field of form.elements) {
+              if (dom.isFieldElement(field)) {
+                // Mark the field as touched
+                field.dataset.conformTouched = 'true';
+              }
             }
           }
-        }
 
-        try {
-          if (!config.noValidate && !submitter.formNoValidate) {
-            var _config$onValidate;
+          var _error;
 
-            (_config$onValidate = config.onValidate) === null || _config$onValidate === void 0 ? void 0 : _config$onValidate.call(config, context);
-
-            if (!form.reportValidity()) {
-              dom.focusFirstInvalidField(form);
-              event.preventDefault();
+          if (typeof config.onValidate === 'function') {
+            _error = config.onValidate(_context);
+          } else {
+            if (config.mode !== 'server-validation') {
+              // Clear previous result
+              dom.setFormError(form, {
+                context: 'submit',
+                value: {},
+                error: []
+              });
             }
+
+            _error = dom.getFormError(form);
           }
-        } catch (e) {
-          if (e !== form) {
-            console.warn(e);
+
+          if (_error.length > 0) {
+            submission.error.push(..._error);
           }
-        }
 
-        if (!event.defaultPrevented) {
-          if (config.mode !== 'server-validation' && submission.type === 'validate') {
+          if (!config.noValidate && !submitter.formNoValidate && dom.hasError(submission.error) || submission.context === 'validate' && config.mode !== 'server-validation') {
             event.preventDefault();
           } else {
             var _config$onSubmit;
 
-            (_config$onSubmit = config.onSubmit) === null || _config$onSubmit === void 0 ? void 0 : _config$onSubmit.call(config, event, context);
+            (_config$onSubmit = config.onSubmit) === null || _config$onSubmit === void 0 ? void 0 : _config$onSubmit.call(config, event, _context);
           }
+
+          if (event.defaultPrevented) {
+            dom.setFormError(form, submission);
+
+            if (!form.reportValidity()) {
+              dom.focusFirstInvalidField(form);
+            }
+          }
+        } catch (e) {
+          console.warn(e);
         }
       }
 
@@ -423,7 +437,7 @@ function useFieldset(ref, config) {
  * Returns a list of key and config, with a group of helpers
  * configuring buttons for list manipulation
  *
- * @see https://github.com/edmundhung/conform/tree/v0.4.0-pre.1/packages/conform-react/README.md#usefieldlist
+ * @see https://github.com/edmundhung/conform/tree/v0.4.0-pre.2/packages/conform-react/README.md#usefieldlist
  */
 function useFieldList(ref, config) {
   var configRef = react.useRef(config);
@@ -567,7 +581,7 @@ function useFieldList(ref, config) {
  * This is particular useful when integrating dropdown and datepicker whichs
  * introduces custom input mode.
  *
- * @see https://github.com/edmundhung/conform/tree/v0.4.0-pre.1/packages/conform-react/README.md#usecontrolledinput
+ * @see https://github.com/edmundhung/conform/tree/v0.4.0-pre.2/packages/conform-react/README.md#usecontrolledinput
  */
 function useControlledInput(config) {
   var _config$defaultValue4;

package/index.d.ts

@@ -1,3 +1,3 @@
-export { type FieldsetConstraint, type Submission, hasError, isFieldElement, parse, setFormError, shouldValidate, } from '@conform-to/dom';
+export { type FieldsetConstraint, type Submission, getFormError, hasError, isFieldElement, parse, shouldValidate, } from '@conform-to/dom';
 export * from './hooks';
 export * as conform from './helpers';

package/index.js

@@ -8,6 +8,10 @@ var helpers = require('./helpers.js');
 
 
 
+Object.defineProperty(exports, 'getFormError', {
+	enumerable: true,
+	get: function () { return dom.getFormError; }
+});
 Object.defineProperty(exports, 'hasError', {
 	enumerable: true,
 	get: function () { return dom.hasError; }
@@ -20,10 +24,6 @@ Object.defineProperty(exports, 'parse', {
 	enumerable: true,
 	get: function () { return dom.parse; }
 });
-Object.defineProperty(exports, 'setFormError', {
-	enumerable: true,
-	get: function () { return dom.setFormError; }
-});
 Object.defineProperty(exports, 'shouldValidate', {
 	enumerable: true,
 	get: function () { return dom.shouldValidate; }

package/module/hooks.js

@@ -1,5 +1,5 @@
 import { objectSpread2 as _objectSpread2 } from './_virtual/_rollupPluginBabelHelpers.js';
-import { getSubmissionType, setFormError, focusFirstInvalidField, requestSubmit, isFieldElement, getFormData, parse, getPaths, getName, requestValidate, getFormElement, parseListCommand, updateList } from '@conform-to/dom';
+import { getSubmissionType, setFormError, focusFirstInvalidField, requestSubmit, isFieldElement, getFormData, parse, getFormError, hasError, getPaths, getName, requestValidate, getFormElement, parseListCommand, updateList } from '@conform-to/dom';
 import { useRef, useState, useEffect } from 'react';
 import { input } from './helpers.js';
 
@@ -7,7 +7,7 @@ import { input } from './helpers.js';
  * Returns properties required to hook into form events.
  * Applied custom validation and define when error should be reported.
  *
- * @see https://github.com/edmundhung/conform/tree/v0.4.0-pre.1/packages/conform-react/README.md#useform
+ * @see https://github.com/edmundhung/conform/tree/v0.4.0-pre.2/packages/conform-react/README.md#useform
  */
 function useForm() {
   var config = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
@@ -178,48 +178,62 @@ function useForm() {
           return;
         }
 
-        var formData = getFormData(form, submitter);
-        var submission = parse(formData);
-        var context = {
-          form,
-          formData,
-          submission
-        }; // Touch all fields only if the submitter is not a command button
-
-        if (!submission.type) {
-          for (var field of form.elements) {
-            if (isFieldElement(field)) {
-              // Mark the field as touched
-              field.dataset.conformTouched = 'true';
+        try {
+          var formData = getFormData(form, submitter);
+          var submission = parse(formData);
+          var _context = {
+            form,
+            formData,
+            submission
+          }; // Touch all fields only if the submitter is not a command button
+
+          if (submission.context === 'submit') {
+            for (var field of form.elements) {
+              if (isFieldElement(field)) {
+                // Mark the field as touched
+                field.dataset.conformTouched = 'true';
+              }
             }
           }
-        }
 
-        try {
-          if (!config.noValidate && !submitter.formNoValidate) {
-            var _config$onValidate;
+          var _error;
 
-            (_config$onValidate = config.onValidate) === null || _config$onValidate === void 0 ? void 0 : _config$onValidate.call(config, context);
-
-            if (!form.reportValidity()) {
-              focusFirstInvalidField(form);
-              event.preventDefault();
+          if (typeof config.onValidate === 'function') {
+            _error = config.onValidate(_context);
+          } else {
+            if (config.mode !== 'server-validation') {
+              // Clear previous result
+              setFormError(form, {
+                context: 'submit',
+                value: {},
+                error: []
+              });
             }
+
+            _error = getFormError(form);
           }
-        } catch (e) {
-          if (e !== form) {
-            console.warn(e);
+
+          if (_error.length > 0) {
+            submission.error.push(..._error);
           }
-        }
 
-        if (!event.defaultPrevented) {
-          if (config.mode !== 'server-validation' && submission.type === 'validate') {
+          if (!config.noValidate && !submitter.formNoValidate && hasError(submission.error) || submission.context === 'validate' && config.mode !== 'server-validation') {
             event.preventDefault();
           } else {
             var _config$onSubmit;
 
-            (_config$onSubmit = config.onSubmit) === null || _config$onSubmit === void 0 ? void 0 : _config$onSubmit.call(config, event, context);
+            (_config$onSubmit = config.onSubmit) === null || _config$onSubmit === void 0 ? void 0 : _config$onSubmit.call(config, event, _context);
           }
+
+          if (event.defaultPrevented) {
+            setFormError(form, submission);
+
+            if (!form.reportValidity()) {
+              focusFirstInvalidField(form);
+            }
+          }
+        } catch (e) {
+          console.warn(e);
         }
       }
 
@@ -419,7 +433,7 @@ function useFieldset(ref, config) {
  * Returns a list of key and config, with a group of helpers
  * configuring buttons for list manipulation
  *
- * @see https://github.com/edmundhung/conform/tree/v0.4.0-pre.1/packages/conform-react/README.md#usefieldlist
+ * @see https://github.com/edmundhung/conform/tree/v0.4.0-pre.2/packages/conform-react/README.md#usefieldlist
  */
 function useFieldList(ref, config) {
   var configRef = useRef(config);
@@ -563,7 +577,7 @@ function useFieldList(ref, config) {
  * This is particular useful when integrating dropdown and datepicker whichs
  * introduces custom input mode.
  *
- * @see https://github.com/edmundhung/conform/tree/v0.4.0-pre.1/packages/conform-react/README.md#usecontrolledinput
+ * @see https://github.com/edmundhung/conform/tree/v0.4.0-pre.2/packages/conform-react/README.md#usecontrolledinput
  */
 function useControlledInput(config) {
   var _config$defaultValue4;

package/module/index.js

@@ -1,4 +1,4 @@
-export { hasError, isFieldElement, parse, setFormError, shouldValidate } from '@conform-to/dom';
+export { getFormError, hasError, isFieldElement, parse, shouldValidate } from '@conform-to/dom';
 export { useControlledInput, useFieldList, useFieldset, useForm } from './hooks.js';
 import * as helpers from './helpers.js';
 export { helpers as conform };

package/package.json

@@ -2,7 +2,7 @@
 	"name": "@conform-to/react",
 	"description": "Conform view adapter for react",
 	"license": "MIT",
-	"version": "0.4.0-pre.1",
+	"version": "0.4.0-pre.2",
 	"main": "index.js",
 	"module": "module/index.js",
 	"repository": {
@@ -19,7 +19,7 @@
 		"url": "https://github.com/edmundhung/conform/issues"
 	},
 	"dependencies": {
-		"@conform-to/dom": "0.4.0-pre.1"
+		"@conform-to/dom": "0.4.0-pre.2"
 	},
 	"peerDependencies": {
 		"react": ">=16.8"