@conform-to/react 0.6.0-pre.0 → 0.6.1

package/README.md

@@ -11,13 +11,12 @@
 - [useFieldList](#usefieldlist)
 - [useInputEvent](#useinputevent)
 - [conform](#conform)
+- [parse](#parse)
+- [validateConstraint](#validateconstraint)
 - [list](#list)
 - [validate](#validate)
 - [requestIntent](#requestintent)
-- [getFormElements](#getformelements)
-- [hasError](#haserror)
-- [parse](#parse)
-- [shouldValidate](#shouldvalidate)
+- [isFieldElement](#isfieldelement)
 
 <!-- /aside -->
 
@@ -27,9 +26,9 @@ By default, the browser calls the [reportValidity()](https://developer.mozilla.o
 
 This hook enhances the form validation behaviour by:
 
-- Enabling customizing form validation behaviour.
-- Capturing the error message and removes the error bubbles.
-- Preparing all properties required to configure the dom elements.
+- Enabling customizing validation logic.
+- Capturing error message and removes the error bubbles.
+- Preparing all properties required to configure the form elements.
 
 ```tsx
 import { useForm } from '@conform-to/react';
@@ -43,27 +42,35 @@ function LoginForm() {
     id: undefined,
 
     /**
-     * Define when the error should be reported initially.
+     * Define when conform should start validation.
      * Support "onSubmit", "onChange", "onBlur".
      *
      * Default to `onSubmit`.
      */
-    initialReport: 'onBlur',
+    shouldValidate: 'onSubmit',
+
+    /**
+     * Define when conform should revalidate again.
+     * Support "onSubmit", "onChange", "onBlur".
+     *
+     * Default to `onInput`.
+     */
+    shouldRevalidate: 'onInput',
 
     /**
      * An object representing the initial value of the form.
      */
-    defaultValue: undefined;
+    defaultValue: undefined,
 
     /**
-     * An object describing the state from the last submission
+     * The last submission result from the server
      */
-    state: undefined;
+    lastSubmission: undefined,
 
     /**
      * An object describing the constraint of each field
      */
-    constraint: undefined;
+    constraint: undefined,
 
     /**
      * Enable native validation before hydation.
@@ -90,7 +97,7 @@ function LoginForm() {
     /**
      * The submit event handler of the form.
      */
-    onSubmit(event, { formData, submission }) {
+    onSubmit(event, { formData, submission, action, encType, method }) {
       // ...
     },
   });
@@ -165,20 +172,20 @@ function Example() {
   const [form, { address }] = useForm<{ address: Address }>();
   const { city, zipcode, street, country } = useFieldset(
     form.ref,
-    address.config,
+    address,
   );
 
   return (
     <form {...form.props}>
       <fieldset>
         <legned>Address</legend>
-        <input {...conform.input(street.config)} />
+        <input {...conform.input(street)} />
         <div>{street.error}</div>
-        <input {...conform.input(zipcode.config)} />
+        <input {...conform.input(zipcode)} />
         <div>{zipcode.error}</div>
-        <input {...conform.input(city.config)} />
+        <input {...conform.input(city)} />
         <div>{city.error}</div>
-        <input {...conform.input(country.config)} />
+        <input {...conform.input(country)} />
         <div>{country.error}</div>
       </fieldset>
       <button>Submit</button>
@@ -204,7 +211,7 @@ function Fieldset(config: FieldConfig<Address>) {
 <details>
 <summary>Why does `useFieldset` require a ref object of the form or fieldset?</summary>
 
-**conform** utilises the DOM as its context provider / input registry, which maintains a link between each input / button / fieldset with the form through the [form property](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement#properties). The ref object allows it to restrict the scope to elements associated to the same form only.
+**conform** utilises the DOM as its context provider / input registry, which maintains a link between each input / button / fieldset with the form through the [form property](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement#properties). The ref object allows it to restrict the scope to form elements associated to the same form only.
 
 ```tsx
 function ExampleForm() {
@@ -231,7 +238,7 @@ function ExampleForm() {
 
 ### useFieldList
 
-This hook enables you to work with [array](/docs/configuration.md#array) and support [list](#list) command button builder to modify a list. It can also be used with [useFieldset](#usefieldset) for [nested list](/docs/configuration.md#nested-list) at the same time.
+This hook enables you to work with [array](/docs/configuration.md#array) and support the [list](#list) intent button builder to modify a list. It can also be used with [useFieldset](#usefieldset) for [nested list](/docs/configuration.md#nested-list) at the same time.
 
 ```tsx
 import { useForm, useFieldList, list } from '@conform-to/react';
@@ -245,27 +252,25 @@ type Schema = {
 
 function Example() {
   const [form, { items }] = useForm<Schema>();
-  const list = useFieldList(form.ref, items.config);
+  const itemsList = useFieldList(form.ref, items);
 
   return (
     <fieldset ref={ref}>
-      {list.map((item, index) => (
+      {itemsList.map((item, index) => (
         <div key={item.key}>
           {/* Setup an input per item */}
-          <input {...conform.input(item.config)} />
+          <input {...conform.input(item)} />
 
           {/* Error of each item */}
           <span>{item.error}</span>
 
           {/* Setup a delete button (Note: It is `items` not `item`) */}
-          <button {...list.remove(items.config.name, { index })}>Delete</button>
+          <button {...list.remove(items.name, { index })}>Delete</button>
         </div>
       ))}
 
       {/* Setup a button that can append a new row with optional default value */}
-      <button {...list.append(items.config.name, { defaultValue: '' })}>
-        add
-      </button>
+      <button {...list.append(items.name, { defaultValue: '' })}>add</button>
     </fieldset>
   );
 }
@@ -284,9 +289,9 @@ import { useState, useRef } from 'react';
 
 function MuiForm() {
   const [form, { category }] = useForm();
-  const [value, setValue] = useState(category.config.defaultValue ?? '');
+  const [value, setValue] = useState(category.defaultValue ?? '');
   const [ref, control] = useInputEvent({
-    onReset: () => setValue(category.config.defaultValue ?? ''),
+    onReset: () => setValue(category.defaultValue ?? ''),
   });
   const inputRef = useRef<HTMLInputElement>(null);
 
@@ -295,7 +300,7 @@ function MuiForm() {
       {/* Render a shadow input somewhere */}
       <input
         ref={ref}
-        {...conform.input(category.config, { hidden: true })}
+        {...conform.input(category, { hidden: true })}
         onChange={(e) => setValue(e.target.value)}
         onFocus={() => inputRef.current?.focus()}
       />
@@ -323,9 +328,9 @@ function MuiForm() {
 
 ### conform
 
-It provides several helpers to remove the boilerplate when configuring a form control.
+It provides several helpers to remove the boilerplate when configuring a form control and derives attributes for [accessibility](/docs/accessibility.md#configuration) concerns and helps [focus management](/docs/focus-management.md#focusing-before-javascript-is-loaded).
 
-You are recommended to create a wrapper on top if you need to integrate with custom input component. As the helper derives attributes for [accessibility](/docs/accessibility.md#configuration) concerns and helps [focus management](/docs/focus-management.md#focusing-before-javascript-is-loaded).
+You can also create a wrapper on top if you need to integrate with custom input component.
 
 Before:
 
@@ -339,31 +344,31 @@ function Example() {
     <form {...form.props}>
       <input
         type="text"
-        name={title.config.name}
-        form={title.config.form}
-        defaultValue={title.config.defaultValue}
-        requried={title.config.required}
-        minLength={title.config.minLength}
-        maxLength={title.config.maxLength}
-        min={title.config.min}
-        max={title.config.max}
-        multiple={title.config.multiple}
-        pattern={title.config.pattern}
+        name={title.name}
+        form={title.form}
+        defaultValue={title.defaultValue}
+        requried={title.required}
+        minLength={title.minLength}
+        maxLength={title.maxLength}
+        min={title.min}
+        max={title.max}
+        multiple={title.multiple}
+        pattern={title.pattern}
       />
       <textarea
-        name={description.config.name}
-        form={description.config.form}
-        defaultValue={description.config.defaultValue}
-        requried={description.config.required}
-        minLength={description.config.minLength}
-        maxLength={description.config.maxLength}
+        name={description.name}
+        form={description.form}
+        defaultValue={description.defaultValue}
+        requried={description.required}
+        minLength={description.minLength}
+        maxLength={description.maxLength}
       />
       <select
-        name={category.config.name}
-        form={category.config.form}
-        defaultValue={category.config.defaultValue}
-        requried={category.config.required}
-        multiple={category.config.multiple}
+        name={category.name}
+        form={category.form}
+        defaultValue={category.defaultValue}
+        requried={category.required}
+        multiple={category.multiple}
       >
         {/* ... */}
       </select>
@@ -382,9 +387,9 @@ function Example() {
 
   return (
     <form {...form.props}>
-      <input {...conform.input(title.config, { type: 'text' })} />
-      <textarea {...conform.textarea(description.config)} />
-      <select {...conform.select(category.config)}>{/* ... */}</select>
+      <input {...conform.input(title, { type: 'text' })} />
+      <textarea {...conform.textarea(description)} />
+      <select {...conform.select(category)}>{/* ... */}</select>
     </form>
   );
 }
@@ -392,9 +397,117 @@ function Example() {
 
 ---
 
+### parse
+
+It parses the formData based on the [naming convention](/docs/configuration.md#naming-convention) with the validation result from the resolver.
+
+```tsx
+import { parse } from '@conform-to/react';
+
+const formData = new FormData();
+const submission = parse(formData, {
+  resolve({ email, password }) {
+    const error: Record<string, string> = {};
+
+    if (typeof email !== 'string') {
+      error.email = 'Email is required';
+    } else if (!/^[^@]+@[^@]+$/.test(email)) {
+      error.email = 'Email is invalid';
+    }
+
+    if (typeof password !== 'string') {
+      error.password = 'Password is required';
+    }
+
+    if (error.email || error.password) {
+      return { error };
+    }
+
+    return {
+      value: { email, password },
+    };
+  },
+});
+```
+
+---
+
+### validateConstraint
+
+This enable Constraint Validation with ability to enable custom constraint using data-attribute and customizing error messages. By default, the error message would be the attribute that triggered the error (e.g. `required` / `type` / 'minLength' etc).
+
+```tsx
+import { useForm, validateConstraint } from '@conform-to/react';
+import { Form } from 'react-router-dom';
+
+export default function SignupForm() {
+    const [form, { email, password, confirmPassword }] = useForm({
+        onValidate(context) {
+            // This enables validating each field based on the validity state and custom cosntraint if defined
+            return validateConstraint(
+              ...context,
+              constraint: {
+                // Define custom constraint
+                match(value, { formData, attributeValue }) {
+                    // Check if the value of the field match the value of another field
+                    return value === formData.get(attributeValue);
+                },
+            });
+        }
+    });
+
+    return (
+        <Form method="post" {...form.props}>
+            <div>
+                <label>Email</label>
+                <input
+                    name="email"
+                    type="email"
+                    required
+                    pattern="[^@]+@[^@]+\\.[^@]+"
+                />
+                {email.error === 'required' ? (
+                    <div>Email is required</div>
+                ) : email.error === 'type' ? (
+                    <div>Email is invalid</div>
+                ) : null}
+            </div>
+            <div>
+                <label>Password</label>
+                <input
+                    name="password"
+                    type="password"
+                    required
+                />
+                {password.error === 'required' ? (
+                    <div>Password is required</div>
+                ) : null}
+            </div>
+            <div>
+                <label>Confirm Password</label>
+                <input
+                    name="confirmPassword"
+                    type="password"
+                    required
+                    data-constraint-match="password"
+                />
+                {confirmPassword.error === 'required' ? (
+                    <div>Confirm Password is required</div>
+                ) : confirmPassword.error === 'match' ? (
+                    <div>Password does not match</div>
+                ) : null}
+            </div>
+            <button>Signup</button>
+        </Form>
+    );
+}
+```
+
+---
+
 ### list
 
-It provides serveral helpers to configure a command button for [modifying a list](/docs/commands.md#modifying-a-list).
+It provides serveral helpers to configure an intent button for [modifying a list](/docs/commands.md#modifying-a-list).
 
 ```tsx
 import { list } from '@conform-to/react';
@@ -427,7 +540,7 @@ function Example() {
 
 ### validate
 
-It returns the properties required to configure a command button for [validation](/docs/commands.md#validation).
+It returns the properties required to configure an intent button for [validation](/docs/commands.md#validation).
 
 ```tsx
 import { validate } from '@conform-to/react';
@@ -463,7 +576,7 @@ import DragAndDrop from 'awesome-dnd-example';
 
 export default function Todos() {
   const [form, { tasks }] = useForm();
-  const taskList = useFieldList(form.ref, tasks.config);
+  const taskList = useFieldList(form.ref, tasks);
 
   const handleDrop = (from, to) =>
     requestIntent(form.ref.current, list.reorder({ from, to }));
@@ -473,7 +586,7 @@ export default function Todos() {
       <DragAndDrop onDrop={handleDrop}>
         {taskList.map((task, index) => (
           <div key={task.key}>
-            <input {...conform.input(task.config)} />
+            <input {...conform.input(task)} />
           </div>
         ))}
       </DragAndDrop>
@@ -485,81 +598,22 @@ export default function Todos() {
 
 ---
 
-### getFormElements
+### isFieldElement
 
-It returns all _input_ / _select_ / _textarea_ or _button_ in the forms. Useful when looping through the form elements to validate each field manually.
+This is an utility for checking if the provided element is a form element (_input_ / _select_ / _textarea_ or _button_) which also works as a type guard.
 
 ```tsx
-import { useForm, parse, getFormElements } from '@conform-to/react';
-
-export default function LoginForm() {
-  const [form] = useForm({
-    onValidate({ form, formData }) {
-      const submission = parse(formData);
-
-      for (const element of getFormElements(form)) {
-        switch (element.name) {
-          case 'email': {
-            if (element.validity.valueMissing) {
-              submission.error.push([element.name, 'Email is required']);
-            } else if (element.validity.typeMismatch) {
-              submission.error.push([element.name, 'Email is invalid']);
-            }
-            break;
-          }
-          case 'password': {
-            if (element.validity.valueMissing) {
-              submission.error.push([element.name, 'Password is required']);
-            }
-            break;
-          }
+function Example() {
+  return (
+    <form
+      onFocus={(event) => {
+        if (isFieldElement(event.target)) {
+          // event.target is now considered one of the form elements type
         }
-      }
-
-      return submission;
-    },
-
-    // ....
-  });
-
-  // ...
+      }}
+    >
+      {/* ... */}
+    </form>
+  );
 }
 ```
-
----
-
-### parse
-
-It parses the formData based on the [naming convention](/docs/submission).
-
-```tsx
-import { parse } from '@conform-to/react';
-
-const formData = new FormData();
-const submission = parse(formData);
-
-console.log(submission);
-```
-
----
-
-### 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 intent give us hint on what should be valdiated.
- * If the intent is 'validate/:field', only the field with name matching must be validated.
- * If the intent is undefined, everything should be validated (Default submission)
- */
-const intent = 'validate/email';
-
-// This will log 'true'
-console.log(shouldValidate(intent, 'email'));
-
-// This will log 'false'
-console.log(shouldValidate(intent, 'password'));
-```

package/helpers.d.ts

@@ -1,6 +1,6 @@
-import { type FieldConfig, VALIDATION_SKIPPED, VALIDATION_UNDEFINED } from '@conform-to/dom';
+import { type FieldConfig, type Primitive, VALIDATION_UNDEFINED, VALIDATION_SKIPPED, INTENT } from '@conform-to/dom';
 import type { CSSProperties, HTMLInputTypeAttribute } from 'react';
-interface FieldProps {
+interface FormControlProps {
     id?: string;
     name: string;
     form?: string;
@@ -8,11 +8,11 @@ interface FieldProps {
     autoFocus?: boolean;
     tabIndex?: number;
     style?: CSSProperties;
-    'aria-invalid': boolean;
     'aria-describedby'?: string;
+    'aria-invalid'?: boolean;
     'aria-hidden'?: boolean;
 }
-interface InputProps<Schema> extends FieldProps {
+interface InputProps<Schema> extends FormControlProps {
     type?: HTMLInputTypeAttribute;
     minLength?: number;
     maxLength?: number;
@@ -25,33 +25,30 @@ interface InputProps<Schema> extends FieldProps {
     defaultChecked?: boolean;
     defaultValue?: string;
 }
-interface SelectProps extends FieldProps {
+interface SelectProps extends FormControlProps {
     defaultValue?: string | number | readonly string[] | undefined;
     multiple?: boolean;
 }
-interface TextareaProps extends FieldProps {
+interface TextareaProps extends FormControlProps {
     minLength?: number;
     maxLength?: number;
     defaultValue?: string;
 }
-type InputOptions = {
-    type: 'checkbox' | 'radio';
+type BaseOptions = {
+    description?: boolean;
     hidden?: boolean;
+};
+type InputOptions = BaseOptions & ({
+    type: 'checkbox' | 'radio';
     value?: string;
 } | {
     type?: Exclude<HTMLInputTypeAttribute, 'button' | 'submit' | 'hidden'>;
-    hidden?: boolean;
     value?: never;
-};
-export declare function input<Schema extends File | File[]>(config: FieldConfig<Schema>, options: {
+});
+export declare function input<Schema extends File | File[]>(config: FieldConfig<Schema>, options: InputOptions & {
     type: 'file';
 }): InputProps<Schema>;
-export declare function input<Schema extends any>(config: FieldConfig<Schema>, options?: InputOptions): InputProps<Schema>;
-export declare function select<Schema>(config: FieldConfig<Schema>, options?: {
-    hidden?: boolean;
-}): SelectProps;
-export declare function textarea<Schema>(config: FieldConfig<Schema>, options?: {
-    hidden?: boolean;
-}): TextareaProps;
-export declare const intent = "__intent__";
-export { VALIDATION_UNDEFINED, VALIDATION_SKIPPED };
+export declare function input<Schema extends Primitive>(config: FieldConfig<Schema>, options?: InputOptions): InputProps<Schema>;
+export declare function select(config: FieldConfig<Primitive | Primitive[]>, options?: BaseOptions): SelectProps;
+export declare function textarea(config: FieldConfig<Primitive>, options?: BaseOptions): TextareaProps;
+export { INTENT, VALIDATION_UNDEFINED, VALIDATION_SKIPPED };