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

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';
@@ -53,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.
@@ -90,7 +89,7 @@ function LoginForm() {
     /**
      * The submit event handler of the form.
      */
-    onSubmit(event, { formData, submission }) {
+    onSubmit(event, { formData, submission, action, encType, method }) {
       // ...
     },
   });
@@ -165,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>
@@ -204,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() {
@@ -231,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';
@@ -245,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>
   );
 }
@@ -284,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);
 
@@ -295,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()}
       />
@@ -323,9 +320,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 +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>
@@ -382,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>
   );
 }
@@ -392,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';
@@ -427,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';
@@ -463,7 +568,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 +578,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 +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>
+  );
 }
 ```
-
----
-
-### 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,11 +25,11 @@ 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;
@@ -46,12 +46,11 @@ 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 declare const intent = "__intent__";
-export { VALIDATION_UNDEFINED, VALIDATION_SKIPPED };
+export { INTENT, VALIDATION_UNDEFINED, VALIDATION_SKIPPED };

package/helpers.js

@@ -2,6 +2,7 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
+var _rollupPluginBabelHelpers = require('./_virtual/_rollupPluginBabelHelpers.js');
 var dom = require('@conform-to/dom');
 
 /**
@@ -19,90 +20,72 @@ var hiddenStyle = {
   whiteSpace: 'nowrap',
   border: 0
 };
-function input(config) {
-  var _config$initialError;
-  var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
-  var attributes = {
+function getFormControlProps(config, options) {
+  var _config$error;
+  var props = {
     id: config.id,
-    type: options.type,
     name: config.name,
     form: config.form,
-    required: config.required,
+    required: config.required
+  };
+  if (config.id) {
+    props.id = config.id;
+    props['aria-describedby'] = config.errorId;
+  }
+  if (config.errorId && (_config$error = config.error) !== null && _config$error !== void 0 && _config$error.length) {
+    props['aria-invalid'] = true;
+  }
+  if (config.initialError && Object.entries(config.initialError).length > 0) {
+    props.autoFocus = true;
+  }
+  if (options !== null && options !== void 0 && options.hidden) {
+    props.style = hiddenStyle;
+    props.tabIndex = -1;
+    props['aria-hidden'] = true;
+  }
+  return props;
+}
+function input(config) {
+  var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  var props = _rollupPluginBabelHelpers.objectSpread2(_rollupPluginBabelHelpers.objectSpread2({}, getFormControlProps(config, options)), {}, {
+    type: options.type,
     minLength: config.minLength,
     maxLength: config.maxLength,
     min: config.min,
     max: config.max,
     step: config.step,
     pattern: config.pattern,
-    multiple: config.multiple,
-    'aria-invalid': Boolean((_config$initialError = config.initialError) === null || _config$initialError === void 0 ? void 0 : _config$initialError.length),
-    'aria-describedby': config.errorId
-  };
-  if (options !== null && options !== void 0 && options.hidden) {
-    attributes.style = hiddenStyle;
-    attributes.tabIndex = -1;
-    attributes['aria-hidden'] = true;
-  }
-  if (config.initialError && Object.entries(config.initialError).length > 0) {
-    attributes.autoFocus = true;
-  }
+    multiple: config.multiple
+  });
   if (options.type === 'checkbox' || options.type === 'radio') {
     var _options$value;
-    attributes.value = (_options$value = options.value) !== null && _options$value !== void 0 ? _options$value : 'on';
-    attributes.defaultChecked = config.defaultValue === attributes.value;
+    props.value = (_options$value = options.value) !== null && _options$value !== void 0 ? _options$value : 'on';
+    props.defaultChecked = config.defaultValue === props.value;
   } else if (options.type !== 'file') {
-    attributes.defaultValue = config.defaultValue;
+    props.defaultValue = config.defaultValue;
   }
-  return attributes;
+  return props;
 }
 function select(config, options) {
-  var _config$defaultValue, _config$initialError2;
-  var attributes = {
-    id: config.id,
-    name: config.name,
-    form: config.form,
-    defaultValue: config.multiple ? Array.isArray(config.defaultValue) ? config.defaultValue : [] : "".concat((_config$defaultValue = config.defaultValue) !== null && _config$defaultValue !== void 0 ? _config$defaultValue : ''),
-    required: config.required,
-    multiple: config.multiple,
-    'aria-invalid': Boolean((_config$initialError2 = config.initialError) === null || _config$initialError2 === void 0 ? void 0 : _config$initialError2.length),
-    'aria-describedby': config.errorId
-  };
-  if (options !== null && options !== void 0 && options.hidden) {
-    attributes.style = hiddenStyle;
-    attributes.tabIndex = -1;
-    attributes['aria-hidden'] = true;
-  }
-  if (config.initialError && Object.entries(config.initialError).length > 0) {
-    attributes.autoFocus = true;
-  }
-  return attributes;
+  var props = _rollupPluginBabelHelpers.objectSpread2(_rollupPluginBabelHelpers.objectSpread2({}, getFormControlProps(config, options)), {}, {
+    defaultValue: config.defaultValue,
+    multiple: config.multiple
+  });
+  return props;
 }
 function textarea(config, options) {
-  var _config$defaultValue2, _config$initialError3;
-  var attributes = {
-    id: config.id,
-    name: config.name,
-    form: config.form,
-    defaultValue: "".concat((_config$defaultValue2 = config.defaultValue) !== null && _config$defaultValue2 !== void 0 ? _config$defaultValue2 : ''),
-    required: config.required,
+  var props = _rollupPluginBabelHelpers.objectSpread2(_rollupPluginBabelHelpers.objectSpread2({}, getFormControlProps(config, options)), {}, {
+    defaultValue: config.defaultValue,
     minLength: config.minLength,
-    maxLength: config.maxLength,
-    autoFocus: Boolean(config.initialError),
-    'aria-invalid': Boolean((_config$initialError3 = config.initialError) === null || _config$initialError3 === void 0 ? void 0 : _config$initialError3.length),
-    'aria-describedby': config.errorId
-  };
-  if (options !== null && options !== void 0 && options.hidden) {
-    attributes.style = hiddenStyle;
-    attributes.tabIndex = -1;
-    attributes['aria-hidden'] = true;
-  }
-  if (config.initialError && Object.entries(config.initialError).length > 0) {
-    attributes.autoFocus = true;
-  }
-  return attributes;
+    maxLength: config.maxLength
+  });
+  return props;
 }
-var intent = '__intent__';
 
+Object.defineProperty(exports, 'INTENT', {
+	enumerable: true,
+	get: function () { return dom.INTENT; }
+});
 Object.defineProperty(exports, 'VALIDATION_SKIPPED', {
 	enumerable: true,
 	get: function () { return dom.VALIDATION_SKIPPED; }
@@ -112,6 +95,5 @@ Object.defineProperty(exports, 'VALIDATION_UNDEFINED', {
 	get: function () { return dom.VALIDATION_UNDEFINED; }
 });
 exports.input = input;
-exports.intent = intent;
 exports.select = select;
 exports.textarea = textarea;