@conform-to/react 0.3.0 → 0.4.0-pre.0

package/README.md

@@ -2,15 +2,18 @@
 
 > [React](https://github.com/facebook/react) adapter for [conform](https://github.com/edmundhung/conform)
 
+<!-- aside -->
+
 ## API Reference
 
-- [useForm](#useForm)
-- [useFieldset](#useFieldset)
-- [useFieldList](#useFieldList)
-- [useControlledInput](#useControlledInput)
+- [useForm](#useform)
+- [useFieldset](#usefieldset)
+- [useFieldList](#usefieldlist)
+- [useControlledInput](#usecontrolledinput)
+- [createValidate](#createvalidate)
 - [conform](#conform)
 
----
+<!-- /aside -->
 
 ### useForm
 
@@ -219,31 +222,31 @@ function BookFieldset() {
    * This would be 'Invalid ISBN' initially as specified
    * in the initialError config
    */
-  console.log(book.error);
+  console.log(isbn.error);
 
   /**
    * This would be `book.isbn` instead of `isbn`
    * if the `name` option is provided
    */
-  console.log(book.config.name);
+  console.log(isbn.config.name);
 
   /**
    * This would be `0340013818` if specified
    * on the `initalValue` option
    */
-  console.log(book.config.defaultValue);
+  console.log(isbn.config.defaultValue);
 
   /**
    * Initial error message
    * This would be 'Invalid ISBN' if specified
    */
-  console.log(book.config.initialError);
+  console.log(isbn.config.initialError);
 
   /**
    * This would be `random-form-id`
    * because of the `form` option provided
    */
-  console.log(book.config.form);
+  console.log(isbn.config.form);
 
   /**
    * Constraint of the field (required, minLength etc)
@@ -254,8 +257,8 @@ function BookFieldset() {
    *   pattern: '[0-9]{10,13}'
    * }
    */
-  console.log(book.config.required);
-  console.log(book.config.pattern);
+  console.log(isbn.config.required);
+  console.log(isbn.config.pattern);
 
   return <form {...formProps}>{/* ... */}</form>;
 }
@@ -353,7 +356,7 @@ type Collection = {
 function CollectionFieldset() {
   const ref = useRef();
   const { books } = useFieldset<Collection>(ref);
-  const [bookList, control] = useFieldList(ref, books);
+  const [bookList, control] = useFieldList(ref, books.config);
 
   return (
     <fieldset ref={ref}>
@@ -392,14 +395,14 @@ import { useRef } from 'react';
 function CollectionFieldset() {
   const ref = useRef();
   const { books } = useFieldset<Collection>(ref);
-  const [bookList, control] = useFieldList(ref, books);
+  const [bookList, control] = useFieldList(ref, books.config);
 
   return (
     <fieldset ref={ref}>
       {bookList.map((book, index) => (
         <div key={book.key}>
-          {/* `book.props` is a FieldConfig object similar to `books` */}
-          <BookFieldset {...book.config}>
+          {/* `book.config` is a FieldConfig object similar to `books` */}
+          <BookFieldset {...book.config} />
 
           {/* To setup a delete button */}
           <button {...control.remove({ index })}>Delete</button>
@@ -426,11 +429,7 @@ function BookFieldset({ name, form, defaultValue, error }) {
     error,
   });
 
-  return (
-    <fieldset ref={ref}>
-      {/* ... */}
-    </fieldset>
-  );
+  return <fieldset ref={ref}>{/* ... */}</fieldset>;
 }
 ```
 
@@ -470,7 +469,7 @@ import { useRef } from 'react';
 function MuiForm() {
   const ref = useRef();
   const { category } = useFieldset(schema);
-  const [inputProps, control] = useControlledInput(category);
+  const [inputProps, control] = useControlledInput(category.config);
 
   return (
     <fieldset ref={ref}>
@@ -480,6 +479,7 @@ function MuiForm() {
       {/* MUI Select is a controlled component */}
       <Select
         label="Category"
+        inputRef={control.ref}
         value={control.value}
         onChange={control.onChange}
         onBlur={control.onBlur}
@@ -499,6 +499,57 @@ function MuiForm() {
 
 ---
 
+### 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>;
+}
+```
+
+---
+
 ### conform
 
 It provides several helpers to configure a native input field quickly:
@@ -509,13 +560,13 @@ import { useRef } from 'react';
 
 function RandomForm() {
   const ref = useRef();
-  const { cateogry } = useFieldset(ref);
+  const { category } = useFieldset(ref);
 
   return (
     <fieldset ref={ref}>
-      <input {...conform.input(cateogry, { type: 'text' })} />
-      <textarea {...conform.textarea(cateogry)} />
-      <select {...conform.select(cateogry)}>{/* ... */}</select>
+      <input {...conform.input(category.config, { type: 'text' })} />
+      <textarea {...conform.textarea(category.config)} />
+      <select {...conform.select(category.config)}>{/* ... */}</select>
     </fieldset>
   );
 }
@@ -526,37 +577,37 @@ This is equivalent to:
 ```tsx
 function RandomForm() {
   const ref = useRef();
-  const { cateogry } = useFieldset(ref);
+  const { category } = useFieldset(ref);
 
   return (
     <fieldset ref={ref}>
       <input
         type="text"
-        name={cateogry.name}
-        form={cateogry.form}
-        defaultValue={cateogry.defaultValue}
-        requried={cateogry.required}
-        minLength={cateogry.minLength}
-        maxLength={cateogry.maxLength}
-        min={cateogry.min}
-        max={cateogry.max}
-        multiple={cateogry.multiple}
-        pattern={cateogry.pattern}
+        name={category.config.name}
+        form={category.config.form}
+        defaultValue={category.config.defaultValue}
+        requried={category.config.required}
+        minLength={category.config.minLength}
+        maxLength={category.config.maxLength}
+        min={category.config.min}
+        max={category.config.max}
+        multiple={category.config.multiple}
+        pattern={category.config.pattern}
       >
       <textarea
-        name={cateogry.name}
-        form={cateogry.form}
-        defaultValue={cateogry.defaultValue}
-        requried={cateogry.required}
-        minLength={cateogry.minLength}
-        maxLength={cateogry.maxLength}
+        name={category.config.name}
+        form={category.config.form}
+        defaultValue={category.config.defaultValue}
+        requried={category.config.required}
+        minLength={category.config.minLength}
+        maxLength={category.config.maxLength}
       />
       <select
-        name={cateogry.name}
-        form={cateogry.form}
-        defaultValue={cateogry.defaultValue}
-        requried={cateogry.required}
-        multiple={cateogry.multiple}
+        name={category.config.name}
+        form={category.config.form}
+        defaultValue={category.config.defaultValue}
+        requried={category.config.required}
+        multiple={category.config.multiple}
       >
         {/* ... */}
       </select>

package/helpers.js

@@ -22,6 +22,10 @@ function input(config) {
     multiple: config.multiple
   };
 
+  if (config.initialError && config.initialError.length > 0) {
+    attributes.autoFocus = true;
+  }
+
   if (isCheckboxOrRadio) {
     attributes.value = value !== null && value !== void 0 ? value : 'on';
     attributes.defaultChecked = config.defaultValue === attributes.value;
@@ -34,25 +38,38 @@ function input(config) {
 function select(config) {
   var _config$defaultValue;
 
-  return {
+  var attributes = {
     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
   };
+
+  if (config.initialError && config.initialError.length > 0) {
+    attributes.autoFocus = true;
+  }
+
+  return attributes;
 }
 function textarea(config) {
   var _config$defaultValue2;
 
-  return {
+  var attributes = {
     name: config.name,
     form: config.form,
     defaultValue: "".concat((_config$defaultValue2 = config.defaultValue) !== null && _config$defaultValue2 !== void 0 ? _config$defaultValue2 : ''),
     required: config.required,
     minLength: config.minLength,
-    maxLength: config.maxLength
+    maxLength: config.maxLength,
+    autoFocus: Boolean(config.initialError)
   };
+
+  if (config.initialError && config.initialError.length > 0) {
+    attributes.autoFocus = true;
+  }
+
+  return attributes;
 }
 
 exports.input = input;

package/hooks.d.ts

@@ -1,6 +1,11 @@
-import { type FieldConfig, type FieldError, type FieldValue, type FieldElement, type FieldsetConstraint, type ListCommand, type Primitive } from '@conform-to/dom';
+import { type FieldConfig, type FieldElement, type FieldValue, type FieldsetConstraint, type FormState, type ListCommand, type Primitive, type Submission } from '@conform-to/dom';
 import { type InputHTMLAttributes, type FormEvent, type RefObject } from 'react';
-export interface FormConfig {
+interface FormContext<Schema extends Record<string, any>> {
+    form: HTMLFormElement;
+    formData: FormData;
+    submission: Submission<Schema>;
+}
+export interface FormConfig<Schema extends Record<string, any>> {
     /**
      * Define when the error should be reported initially.
      * Support "onSubmit", "onChange", "onBlur".
@@ -8,6 +13,14 @@ export interface FormConfig {
      * Default to `onSubmit`.
      */
     initialReport?: 'onSubmit' | 'onChange' | 'onBlur';
+    /**
+     * An object representing the initial value of the form.
+     */
+    defaultValue?: FieldValue<Schema>;
+    /**
+     * An object describing the state from the last submission
+     */
+    state?: FormState<Schema>;
     /**
      * Enable native validation before hydation.
      *
@@ -23,12 +36,12 @@ export interface FormConfig {
     /**
      * A function to be called when the form should be (re)validated.
      */
-    validate?: (form: HTMLFormElement, submitter?: HTMLInputElement | HTMLButtonElement | null) => void;
+    onValidate?: (context: FormContext<Schema>) => boolean;
     /**
      * The submit event handler of the form. It will be called
      * only when the form is considered valid.
      */
-    onSubmit?: (event: FormEvent<HTMLFormElement>) => void;
+    onSubmit?: (event: FormEvent<HTMLFormElement>, context: FormContext<Schema>) => void;
 }
 /**
  * Properties to be applied to the form element
@@ -38,13 +51,19 @@ interface FormProps {
     onSubmit: (event: FormEvent<HTMLFormElement>) => void;
     noValidate: boolean;
 }
+interface Form<Schema extends Record<string, any>> {
+    ref: RefObject<HTMLFormElement>;
+    error: string;
+    props: FormProps;
+    config: FieldsetConfig<Schema>;
+}
 /**
  * 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.3.0/packages/conform-react/README.md#useform
+ * @see https://github.com/edmundhung/conform/tree/v0.4.0-pre.0/packages/conform-react/README.md#useform
  */
-export declare function useForm(config?: FormConfig): FormProps;
+export declare function useForm<Schema extends Record<string, any>>(config?: FormConfig<Schema>): Form<Schema>;
 /**
  * All the information of the field, including state and config.
  */
@@ -70,7 +89,7 @@ export interface FieldsetConfig<Schema extends Record<string, any>> {
     /**
      * An object describing the initial error of each field
      */
-    initialError?: FieldError<Schema>['details'];
+    initialError?: Array<[string, string]>;
     /**
      * An object describing the constraint of each field
      */
@@ -83,7 +102,7 @@ export interface FieldsetConfig<Schema extends Record<string, any>> {
 /**
  * Returns all the information about the fieldset.
  *
- * @see https://github.com/edmundhung/conform/tree/v0.3.0/packages/conform-react/README.md#usefieldset
+ * @see https://github.com/edmundhung/conform/tree/v0.4.0-pre.0/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>;
@@ -110,7 +129,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.3.0/packages/conform-react/README.md#usefieldlist
+ * @see https://github.com/edmundhung/conform/tree/v0.4.0-pre.0/packages/conform-react/README.md#usefieldlist
  */
 export declare function useFieldList<Payload = any>(ref: RefObject<HTMLFormElement | HTMLFieldSetElement>, config: FieldConfig<Array<Payload>>): [
     Array<{
@@ -122,7 +141,10 @@ export declare function useFieldList<Payload = any>(ref: RefObject<HTMLFormEleme
 interface ShadowInputProps extends InputHTMLAttributes<HTMLInputElement> {
     ref: RefObject<HTMLInputElement>;
 }
-interface InputControl {
+interface InputControl<Element extends {
+    focus: () => void;
+}> {
+    ref: RefObject<Element>;
     value: string;
     onChange: (eventOrValue: {
         target: {
@@ -137,7 +159,9 @@ interface InputControl {
  * This is particular useful when integrating dropdown and datepicker whichs
  * introduces custom input mode.
  *
- * @see https://github.com/edmundhung/conform/tree/v0.3.0/packages/conform-react/README.md#usecontrolledinput
+ * @see https://github.com/edmundhung/conform/tree/v0.4.0-pre.0/packages/conform-react/README.md#usecontrolledinput
  */
-export declare function useControlledInput<Schema extends Primitive = Primitive>(field: FieldConfig<Schema>): [ShadowInputProps, InputControl];
+export declare function useControlledInput<Element extends {
+    focus: () => void;
+} = HTMLInputElement, Schema extends Primitive = Primitive>(config: FieldConfig<Schema>): [ShadowInputProps, InputControl<Element>];
 export {};