@conform-to/react 0.5.1 → 0.6.0

package/README.md

@@ -10,15 +10,13 @@
 - [useFieldset](#usefieldset)
 - [useFieldList](#usefieldlist)
 - [useInputEvent](#useinputevent)
-- [useControlledInput](#usecontrolledinput)
 - [conform](#conform)
+- [parse](#parse)
+- [validateConstraint](#validateconstraint)
 - [list](#list)
 - [validate](#validate)
-- [requestCommand](#requestcommand)
-- [getFormElements](#getformelements)
-- [hasError](#haserror)
-- [parse](#parse)
-- [shouldValidate](#shouldvalidate)
+- [requestIntent](#requestintent)
+- [isFieldElement](#isfieldelement)
 
 <!-- /aside -->
 
@@ -28,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,14 +41,6 @@ function LoginForm() {
      */
     id: undefined,
 
-    /**
-     * 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".
@@ -62,17 +52,17 @@ function LoginForm() {
     /**
      * 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.
@@ -99,7 +89,7 @@ function LoginForm() {
     /**
      * The submit event handler of the form.
      */
-    onSubmit(event, { formData, submission }) {
+    onSubmit(event, { formData, submission, action, encType, method }) {
       // ...
     },
   });
@@ -174,20 +164,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>
@@ -213,7 +203,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() {
@@ -240,7 +230,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';
@@ -254,27 +244,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>
   );
 }
@@ -293,9 +281,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);
 
@@ -304,7 +292,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()}
       />
@@ -330,54 +318,11 @@ function MuiForm() {
 
 ---
 
-### useControlledInput
-
-> This API is deprecated and replaced with the [useInputEvent](#useinputevent) hook.
-
-It returns the properties required to configure a shadow input for validation and helper to integrate it. This is particularly useful when [integrating custom input components](/docs/integrations.md#custom-input-component) like dropdown and datepicker.
-
-```tsx
-import { useForm, useControlledInput } from '@conform-to/react';
-import { Select, MenuItem } from '@mui/material';
-
-function MuiForm() {
-  const [form, { category }] = useForm();
-  const [inputProps, control] = useControlledInput(category.config);
-
-  return (
-    <form {...form.props}>
-      {/* Render a shadow input somewhere */}
-      <input {...inputProps} />
-
-      {/* MUI Select is a controlled component */}
-      <TextField
-        label="Category"
-        inputRef={control.ref}
-        value={control.value}
-        onChange={control.onChange}
-        onBlur={control.onBlur}
-        inputProps={{
-          onInvalid: control.onInvalid,
-        }}
-        select
-      >
-        <MenuItem value="">Please select</MenuItem>
-        <MenuItem value="a">Category A</MenuItem>
-        <MenuItem value="b">Category B</MenuItem>
-        <MenuItem value="c">Category C</MenuItem>
-      </TextField>
-    </form>
-  );
-}
-```
-
----
-
 ### 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:
 
@@ -391,31 +336,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>
@@ -434,9 +379,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>
   );
 }
@@ -444,9 +389,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';
@@ -479,7 +532,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';
@@ -499,9 +552,9 @@ function Example() {
 
 ---
 
-### requestCommand
+### requestIntent
 
-It lets you [trigger a command](/docs/commands.md#triggering-a-command) without requiring users to click on a button. It supports both [list](#list) and [validate](#validate) command.
+It lets you [trigger an intent](/docs/commands.md#triggering-an-intent) without requiring users to click on a button. It supports both [list](#list) and [validate](#validate) intent.
 
 ```tsx
 import {
@@ -509,23 +562,23 @@ import {
   useFieldList,
   conform,
   list,
-  requestCommand,
+  requestIntent,
 } from '@conform-to/react';
 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) =>
-    requestCommand(form.ref.current, list.reorder({ from, to }));
+    requestIntent(form.ref.current, list.reorder({ from, to }));
 
   return (
     <form {...form.props}>
       <DragAndDrop onDrop={handleDrop}>
         {taskList.map((task, index) => (
           <div key={task.key}>
-            <input {...conform.input(task.config)} />
+            <input {...conform.input(task)} />
           </div>
         ))}
       </DragAndDrop>
@@ -537,107 +590,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>
+  );
 }
 ```
-
----
-
-### 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'));
-```
-
----
-
-### 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 type and intent give us hint on what should be valdiated.
- * If the type is 'validate', only the field with name matching the metadata must be validated.
- * If the type is 'submit', everything should be validated (Default submission)
- */
-const submission = {
-  context: 'validate',
-  intent: 'email',
-  value: {},
-  error: [],
-};
-
-// This will log 'true'
-console.log(shouldValidate(submission, 'email'));
-
-// This will log 'false'
-console.log(shouldValidate(submission, 'password'));
-```

package/_virtual/_rollupPluginBabelHelpers.js

@@ -24,6 +24,7 @@ function _objectSpread2(target) {
   return target;
 }
 function _defineProperty(obj, key, value) {
+  key = _toPropertyKey(key);
   if (key in obj) {
     Object.defineProperty(obj, key, {
       value: value,
@@ -36,6 +37,22 @@ function _defineProperty(obj, key, value) {
   }
   return obj;
 }
+function _toPrimitive(input, hint) {
+  if (typeof input !== "object" || input === null) return input;
+  var prim = input[Symbol.toPrimitive];
+  if (prim !== undefined) {
+    var res = prim.call(input, hint || "default");
+    if (typeof res !== "object") return res;
+    throw new TypeError("@@toPrimitive must return a primitive value.");
+  }
+  return (hint === "string" ? String : Number)(input);
+}
+function _toPropertyKey(arg) {
+  var key = _toPrimitive(arg, "string");
+  return typeof key === "symbol" ? key : String(key);
+}
 
 exports.defineProperty = _defineProperty;
 exports.objectSpread2 = _objectSpread2;
+exports.toPrimitive = _toPrimitive;
+exports.toPropertyKey = _toPropertyKey;

package/helpers.d.ts

@@ -1,6 +1,6 @@
-import type { FieldConfig } 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,16 +25,16 @@ 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;
 }
-declare type InputOptions = {
+type InputOptions = {
     type: 'checkbox' | 'radio';
     hidden?: boolean;
     value?: string;
@@ -46,11 +46,11 @@ declare type InputOptions = {
 export declare function input<Schema extends File | File[]>(config: FieldConfig<Schema>, options: {
     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?: {
+export declare function input<Schema extends Primitive>(config: FieldConfig<Schema>, options?: InputOptions): InputProps<Schema>;
+export declare function select(config: FieldConfig<Primitive | Primitive[]>, options?: {
     hidden?: boolean;
 }): SelectProps;
-export declare function textarea<Schema>(config: FieldConfig<Schema>, options?: {
+export declare function textarea(config: FieldConfig<Primitive>, options?: {
     hidden?: boolean;
 }): TextareaProps;
-export {};
+export { INTENT, VALIDATION_UNDEFINED, VALIDATION_SKIPPED };