react-simple-formkit 1.3.6 → 2.0.1

package/README.md

@@ -1,10 +1,33 @@
 # React Simple FormKit
 
-Configuration is simple, fast, and efficient. There are also many other tools available for different special scenarios.
-
-# Examples
-
-- https://codesandbox.io/p/sandbox/react-simple-formkit-examples-rhmhjj
+Support manage forms as uncontrolled. State updates only when watched. Simple and quick to configure with outstanding efficiency.
+
+# Table of Contents
+
+- [Peer dependencies](#peer-dependencies)
+- [Features](#features)
+- [Quick start](#quick-start)
+- [Core concepts](#core-concepts)
+  - [Modes of input field](#modes-of-input-field)
+  - [Watching for updates](#watching-for-updates)
+- [Manage values](#manage-values)
+  - [Get value](#get-value)
+  - [Set value](#set-value)
+  - [Default values and reset](#default-values-and-reset)
+- [Manage states](#manage-states)
+  - [Get field states](#get-field-states)
+  - [Set field states](#set-field-states)
+- [Manage errors](#manage-errors)
+  - [Get field error](#get-field-error)
+  - [Set field error](#set-field-error)
+- [APIs](#apis)
+  - [useForm](#useForm)
+  - [Form](#form)
+  - [Controller](#controller)
+  - [useController](#useController)
+  - [useWatch](#useWatch)
+- [Examples](#examples)
+- [Contact](#contact)
 
 # Peer dependencies
 
@@ -15,161 +38,166 @@ Configuration is simple, fast, and efficient. There are also many other tools av
 },
 ```
 
+# Features
+
+- [Manage values](#manage-values) (get value, set value, default values, reset values,...)
+- [Manage states](#manage-states) (field dirty, field touched, custom states...)
+- [Manage errors](#manage-errors) (form error, field error...)
+
 # Quick start
 
 ```
-import { Form, useForm } form 'react-simple-formkit'
-
-const form = useForm();
+const { control } = useForm();
 
 const handleSubmit = (data) => {
   alert(JSON.stringify(data));
 };
 
 return (
-  <Form form={form} onSubmit={handleSubmit}>
+  <Form control={control} onSubmit={handleSubmit} onChange={console.log}>
+    <button type="submit">Submit</button>
     <input required name="email" placeholder="email" />
     <input required name="password" type="password" placeholder="password" />
-    <input required name="input1" placeholder="input 1" />
-    <input required name="input2" placeholder="input 2" />
-    {/* ... */}
-    <input required name="input100" placeholder="input 100" />
-    <button type="submit">Submit</button>
+    {Array.from({ length: 10 }).map((_, index) => (
+      <input name={`input${index + 1}`} placeholder={`input ${index + 1}`} />
+    ))}
   </Form>
 );
 ```
 
-# More kits
+# Core concepts
 
-## Number fields
+## Modes of input field
 
-- By default form, values are string at all. So, adding numberFields will catch the number value in on submit
+- `Uncontrolled`: Basic input types are supported by the browser and no need to control value
+- `Controlled`: Advanced input types (multiple select, date picker,...) that **require controlled value** or just need to control value
+- `Captured`: Advanced input types **but no need to control value**. Capture only because the browser doesn't support it
 
 ```
-const form = useForm( {numberFields: ['number'] } );
+const { control, actions } = useForm();
 
 return (
-    <Form form={form}>
-      <input name="number" placeholder=This is number field" />
-      <button type="submit">
-        Submit
-      </button>
-    </Form>
-);
+  <Form control={control} onChange={console.log}>
+    {/* Uncontrolled */}
+    <input name="number1" placeholder="Enter a number" />
+    {/* Controlled by Controller. And the value at this field can be controlled by actions.setValue() */}
+    <Controller
+      name="multipleSelect"
+      render={({ value = "", onChange, name }) => {
+        return (
+          <Select
+            multiple
+            name={name}
+            value={value.split(",")}
+            onChange={(e) => {
+              const value = e.target.value;
+              // value as array by default but on autofill value as string
+              onChange(typeof value === "string" ? value : value.join(","));
+            }}
+          >
+            <MenuItem value="10">Ten</MenuItem>
+            <MenuItem value="20">Twenty</MenuItem>
+            <MenuItem value="30">Thirty</MenuItem>
+          </Select>
+        );
+      }}
+    />
+    {/* Captured: This datepicker component changes value immediately with a click with custom onChange */}
+    <LocalizationProvider dateAdapter={AdapterDayjs}>
+      <DatePicker name="date" onChange={(newValue) => actions.setValue("date", newValue.format("MM/DD/YYYY"))} />
+    </LocalizationProvider>
+    <button type="button" onClick={() => alert(JSON.stringify(actions.getValues()))}>
+      Get value
+    </button>
+    <button type="submit">Submit</button>
+  </Form>
+)
 ```
 
-## JS Built-in validate on blur
+- **Noticed:** <span style="color:red">_All fields in the form must follow one of the three modes above to ensure the form works correctly_</span>
 
-```
-const form = useForm();
-const { isDirty, isError, errors, actions } = form;
+## Watching for updates
 
-return (
-    <Form form={form}>
-      <input required name="email" placeholder="email" type="email" onBlur={actions.checkValidity} />
-      {errors.email && <span>{errors.email}</span>}
-
-      <button type="submit" disabled={!isDirty || isError}>
-        Submit
-      </button>
-    </Form>
-);
-```
+State updates only when observed via `watch()` or `useWatch()`, or by tracking changes through the Form component's `onChange` callback.
 
-## Double validate on blur
+- `watch()` will trigger a re-render at the form level.
+- `useWatch()` will trigger a re-render only in the component where it is called.
+- `onChange` is just a handler callback that is called when field values change.
 
-```
-const form = useForm();
-const { isDirty, isError, errors, actions } = form;
+# Manage values
+
+## Get value
 
-return (
-    <Form form={form}>
-      <input
-        required
-        name="number"
-        onBlur={(e) => {
-          let error = null;
-          error = actions.getFieldValidity(e);
-
-          if (error) {
-            actions.changeError("number", error);
-            return;
-          }
-
-          const value = Number(e.target.value || 0);
-          if (value >= 10) error = "Number must be less than 10";
-          actions.changeError("number", error);
-          }}
-      />
-      {errors.number && <span className="error-message">{errors.number}</span>}
-
-      <button type="submit" disabled={!isDirty || isError}>
-        Submit
-      </button>
-    </Form>
-);
 ```
+// watch
+const fieldName = watch("fieldName")
+const fieldName2 = watch("fieldName2")
+// Or
+const { fieldName2, fieldName } = watch(["fieldName", "fieldName2"])
+// Or
+const values = watch("values")
+
+// useWatch
+useWatch({ name: "fieldName" })
+useWatch({ name: ["fieldName", "fieldName2"] })
+useWatch({ compute: (values) => values.number > 10 : true : false })
+
+// actions.getValues()
+const { actions } = useForm()
+console.log(actions.getValues())
+```
+
+## Set value
 
-## Validate by other field
+actions.setValue() can help to control value of a field. But that field must be controlled by Controller.
 
 ```
-const form = useForm();
-const { isDirty, isError, errors, actions } = form;
+const { control, actions, watch } = useForm()
+const number = watch("number")
 
 return (
-  <Form form={form}>
-    <input required name="number" onBlur={actions.checkValidity} />
-    {errors.number && <span className="error-message">{errors.number}</span>}
-
-    <input
-      required
-      name="number2"
-      onBlur={(e) => {
-        let error = null;
-        error = actions.getFieldValidity(e);
-
-        if (error) {
-          actions.changeError("number2", error);
-          return;
-        }
-
-        const value = Number(e.target.value || 0);
-        const formState = actions.getFormState();
-        const number = Number(formState.number || 0);
-
-        if (value >= number) error = "Number 2 must be less than number 1";
-        actions.changeError("number2", error);
-      }}
+  <Form control={control} onChange={console.log}>
+    <Controller
+      name="number"
+      render={({ name, value, onChange }) => (
+        <input name={name} value={value} onChange={(e) => onChange(e.target.value)} />
+      )}
     />
-    {errors.number2 && <span className="error-message">{errors.number2}</span>}
-    <button type="submit" disabled={!isDirty || isError}>
+    <button type="button" onClick={() => actions.setValue("number", Number(number || 0) + 1 )}>
+      Increase
+    </button>
+    <button type="submit" disabled={!isDirty}>
       Submit
     </button>
   </Form>
 )
 ```
 
-## Centralized processing with onChange
+## Default values and reset
 
 ```
-const handleChange = (data) => {
-  console.log(data);
+const dummyFields = Array.from({ length: 10 }).reduce(
+  (acc, _, index) => ({ ...acc, [`input${index + 1}`]: `input${index + 1}` }),
+  {}
+);
 
-  // setValue will trigger onChange by default and recall handle change making an infinite loop
-  // That why we put shouldOnChange = false here
-  actions.setValue("email2", data.email + "2", { shouldOnChange: false });
-};
+const { control, watch, actions } = useForm({ defaultValues: dummyFields });
+
+const handleSubmit = async (newValues) => {
+  // update to server
+  await new Promise(res => setTimeout(res, 1000))
+  // reset with new defaultValues
+  actions.reset(newValues)
+}
 
 return (
-  <Form form={form} onChange={handleChange}>
-    <input required name="email" />
-    {/* Controller make this field assignable */}
-    <Controller
-      name="email2"
-      render={({ ref, name, value, setValue }) => (
-        <input required ref={ref} name={name} value={value} onChange={(e) => setValue(e.target.value)} />
-      )}
-    />
+  <Form control={control} onSubmit={handleSubmit} onChange={console.log}>
+    {Object.keys(dummyFields).map((name) => (
+      <input name={name} placeholder={name} />
+    ))}
+    <button type="reset" disabled={!isDirty}>
+      Reset
+    </button>
     <button type="submit" disabled={!isDirty}>
       Submit
     </button>
@@ -177,79 +205,50 @@ return (
 );
 ```
 
-## Default values
+# Manage states
 
-- Just put defaultValue in input field, this library will load it when mounted and store to compare isDirty
-- You can also use actions.getDefaultValues() to check what is stored
+## Get field states
 
 ```
-const [loading, setLoading] = useState(false);
-const [defaultValues, setDefaultValues] = useState({ email: "email@example.com", password: "123456" });
-
-const form = useForm({ defaultValues });
-const { isDirty, actions } = form;
-
-const handleSubmit = async (data) => {
-  setLoading(true);
-  await new Promise((res) => setTimeout(res, 1500));
-  setDefaultValues(data);
-  // After update default values, reset the form to get new default values
-  // Because data updating is asynchronous. Catching it's change is ineffective.
-  actions.reset();
-  setLoading(false);
-};
+// watch() or useWatch()
+const isFormDirty = watch("isDirty")
+const { fieldName: {...}, fieldName2: {...} } = watch("fieldStates")
+const { isDirty, isTouched } = watch("fieldStates.fieldName")
+const isFieldDirty = watch("fieldStates.fieldName.isDirty")
+const fieldCustomState = watch("fieldStates.fieldName.customState")
+```
+
+## Set field states
 
-return (
-  <Form form={form} onSubmit={handleSubmit}>
-    <input required name="email" />
-    <Controller
-      name="password"
-      render={({ ref, name, defaultValue, value, setValue }) => (
-        <input
-          ref={ref}
-          required
-          name={name}
-          type="password"
-          defaultValue={defaultValue}
-          value={value}
-          onChange={(e) => setValue(e.target.value)}
-        />
-      )}
-    />
-    <button type="reset" disabled={!isDirty}>
-      Reset
-    </button>
-    <Button disableElevation variant="contained" type="submit" loading={loading} disabled={!isDirty}>
-      Submit
-    </Button>
-  </Form>
-);
 ```
+actions.setFieldStateProperty('fieldName', 'customState', { hello: "world" })
+// This will trigger re-render at watch(), useWatch() and render function in Controller
+```
+
+# Manage errors
 
-# Support for third party library
+## Get field error
 
-## Catch value instantly
+```
+// watch() or useWatch()
+const isFormError = watch("isError")
+const fieldError = watch("errors.fieldName")
+const { fieldName, fieldName2 } = watch("errors")
+```
 
-- Some input types like DatePicker, Select just change by click and don't dispatch input actions
-- You also catch this on submit, but cannot use for actions.getFormState() for validate and isDirty update
-- Just put the actions.instantChange where these components onchange
+## Set field error
 
 ```
-const form = useForm();
-const { isDirty, actions } = form;
+// actions.setError()
+const { control, actions, watch } = useForm()
+const { isError, ["errors.input1"]: input1Error  } = watch(["isError", "errors.input1"])
 
 return (
-  <Form form={form}>
-    <Select name="select" onChange={actions.instantChange}>
-      <MenuItem value={10}>Ten</MenuItem>
-      <MenuItem value={20}>Twenty</MenuItem>
-      <MenuItem value={30}>Thirty</MenuItem>
-    </Select>
-    <LocalizationProvider dateAdapter={AdapterDayjs}>
-      <DatePicker name="date" onChange={actions.instantChange} />
-    </LocalizationProvider>
-    <button type="button" onClick={() => alert(JSON.stringify(actions.getFormState()))}>
-      Get value
+  <Form control={control} onChange={console.log}>
+    <input name="input1" />
+    {errors.input1 && <span className="error-message">{input1Error}</span>}
+    <button type="button" onClick={() => actions.setError("number", "This is error message")}>
+      Set Error
     </button>
     <button type="submit" disabled={!isDirty}>
       Submit
@@ -258,87 +257,77 @@ return (
 )
 ```
 
-## More control with Controller
+# APIs
 
-- Control custom values like object and array
-- Make field assignable by actions.setValue
+## useForm
 
-```
-import { Controller, Form, useForm } from "react-simple-formkit";
+Generic props:
 
-const form = useForm({ numberFields: ["number1", "number2"] });
-const { isDirty, actions } = form;
+- `defaultValues`: `Object` [Example](#default-values-and-reset)
+- `shouldUnRegister`: `Boolean` Default is **false**,
+- `shouldConvertNumber`: `Boolean` Default is **false**
+- `numberFields`: `Array` if passed, shouldConvertNumber will set **true**. Lib auto load field with type **number** by default
 
-return (
-  <Form form={form}>
-    {/* Custom value as array */}
-    <Controller
-      name="multipleSelect"
-      defaultValue={[]}
-      render={({ ref, value, setValue, name }) => (
-        <Select
-          multiple
-          ref={ref}
-          name={name}
-          labelId="demo-multiple-name-label"
-          id="demo-multiple-name"
-          value={value}
-          onChange={(e) => {
-            const value = e.target.value;
-            // On autofill we get a stringified value.
-            setValue(typeof value === "string" ? value.split(",") : value);
-            // instantChange by select
-            actions.instantChange();
-          }}
-          input={<OutlinedInput label="Name" />}
-        >
-          <MenuItem value={10}>Ten</MenuItem>
-          <MenuItem value={20}>Twenty</MenuItem>
-          <MenuItem value={30}>Thirty</MenuItem>
-        </Select>
-      )}
-    />
-    {/* actions.setValue (target field of actions.setValue must use controller)*/}
-    <input
-      name="number1"
-      placeholder="number 1"
-      onBlur={(e) => {
-        const number1 = Number(e.target.value || 0);
-        const number2 = actions.getFormState().number2 || 0;
-        actions.setValue("sum", number1 + number2);
-      }}
-    />
-    <input
-      name="number2"
-      placeholder="number 2"
-      onBlur={(e) => {
-        const number2 = Number(e.target.value || 0);
-        const number1 = actions.getFormState().number1 || 0;
-        actions.setValue("sum", number1 + number2);
-      }}
-    />
-    <Controller
-      name="sum"
-      render={({ ref, value, setValue, name }) => (
-        <input
-          ref={ref}
-          value={value}
-          onChange={(e) => setValue(e.target.value)}
-          name={name}
-          placeholder="sum(number1, number2)"
-        />
-      )}
-    />
-    <button type="button" onClick={() => alert(JSON.stringify(actions.getFormState()))}>
-      Get value
-    </button>
-    <button type="submit" disabled={!isDirty}>
-      Submit
-    </button>
-  </Form>
-)
-```
+Return:
+
+- `control`: contains methods and utilities to control the form.
+- `watch(name)`: `Function` [Example](#manage-values)
+- `actions` is an object that contains utilities
+  - `actions.reset()`: [Example](#default-values-and-reset)
+  - `actions.getValues()`: [Example](#manage-values)
+  - `actions.setValue()`: [Example](#set-value)
+  - `actions.setError()`: [Example](#set-field-error)
+  - `actions.clearError()`
+  - `actions.clearErrors()`
+  - `actions.getNumberFields()`
+  - `actions.getDefaultValues()`
+  - `actions.setFieldStateProperty()`: [Example](#set-field-states)
+
+## Form
+
+Generic props:
+
+- `control`: received from useForm()
+- `onSubmit`: `(currentValues) => {}` call when form submit by button type='submit'
+- `onChange`: `(name, value, currentValues) => {}` call when any field changes
+
+## Controller
+
+Generic props:
+
+- `name`
+- `defaultValue`
+- `render({name, value, onChange, customState, setCustomState})`
+
+## useController
+
+Generic props:
+
+- `name`
+- `defaultValue`
+
+Return: everything in render function above
+
+## useWatch
+
+[Example](#manage-values)
+
+Generic props:
+
+- `name`: `String | Array`
+- compute: `Function` that will calculate from form values and return a value. It will make re-render when the result changes
+
+## useFormContext
+
+Return:
+
+- `watch`
+- `actions`
+
+# Examples
+
+- https://codesandbox.io/p/sandbox/react-simple-formkit-examples-rhmhjj
 
 # Contact
 
-For any ideas or issues, please get in touch with me at anhhuy2000@gmail.com
+For any ideas or issues, please get in touch with me at **anhhuy2000@gmail.com**