react-simple-formkit 2.0.3 → 2.0.4

package/README.md

@@ -1,6 +1,6 @@
 # React Simple FormKit
 
-Support manage forms as uncontrolled. State updates only when watched. Simple and quick to configure with outstanding efficiency.
+Supports managing forms as uncontrolled. State updates only when watched. Simple and quick to configure with outstanding efficiency.
 
 # Table of Contents
 
@@ -40,9 +40,13 @@ Support manage forms as uncontrolled. State updates only when watched. Simple an
 
 # 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...)
+- **Lightweight**: only ~**15KB**
+- **Easy setup**: simple and quick configuration
+- **Optimized for uncontrolled forms**: no unnecessary re-renders
+- Comprehensive form management:
+  - [Values](#manage-values): get/set values, defaults, reset, ...
+  - [States](#manage-states): dirty, touched, custom states, ...
+  - [Errors](#manage-errors): form-level and field-level errors, ...
 
 # Quick start
 
@@ -69,9 +73,67 @@ return (
 
 ## Modes of input field
 
-- `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
+### `Uncontrolled`:
+
+Basic HTML form elements whose value is natively managed by the browser. Such as  
+`<input type="text">`, `<input type="checkbox">`, `<select>`, or `<textarea>`.
+
+> **Note:** Or also **UI library components** that are simple wrappers around these native elements that **still follow the browser’s standard behavior**
+
+### `Controlled`:
+
+Advanced UI components with complex **INPUT AND OUTPUT** . For example, a multiple select component expects an array as its input/output, but your form state might need to store the value as a string.
+
+By using `Controller`, you can transform the value in both directions:
+
+- On `input`: split the stored string into an array to pass to the UI component.
+- On `change`: join the selected array back into a string before updating the form state.
+
+> **Note:** Or whenever you want to **control the value of a field** (e.g. by calling `actions.setValue`), you **must** wrap that field with a `Controller`.
+> Without `Controller`, the field will not respond to external value changes.
+
+Example:
+
+```
+<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`
+
+Advanced UI components with complex **OUTPUT ONLY**
+
+In these cases, the field is **captured**:
+
+- You only listen to its value changes through a custom `onChange`.
+- You can sync the final value into the form when needed (via `actions.setValue`).
+
+Example:
+
+```
+<LocalizationProvider dateAdapter={AdapterDayjs}>
+  <DatePicker name="date" onChange={(newValue) => actions.setValue("date", newValue.format("MM/DD/YYYY"))} />
+</LocalizationProvider>
+```
 
 ```
 const { control, actions } = useForm();
@@ -114,7 +176,7 @@ return (
 )
 ```
 
-- **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>
+> **Note\*:** All fields in the form must follow one of the three modes above to ensure the form works correctly
 
 ## Watching for updates
 
@@ -140,7 +202,7 @@ const values = watch("values")
 // useWatch
 useWatch({ name: "fieldName" })
 useWatch({ name: ["fieldName", "fieldName2"] })
-useWatch({ compute: (values) => values.number > 10 : true : false })
+useWatch({ compute: (values) => values.number > 10 ? true : false })
 
 // actions.getValues()
 const { actions } = useForm()
@@ -241,12 +303,12 @@ const { fieldName, fieldName2 } = watch("errors")
 ```
 // actions.setError()
 const { control, actions, watch } = useForm()
-const { isError, ["errors.input1"]: input1Error  } = watch(["isError", "errors.input1"])
+const { isError, "errors.input1": input1Error  } = watch(["isError", "errors.input1"])
 
 return (
   <Form control={control} onChange={console.log}>
     <input name="input1" />
-    {errors.input1 && <span className="error-message">{input1Error}</span>}
+    {input1Error && <span className="error-message">{input1Error}</span>}
     <button type="button" onClick={() => actions.setError("number", "This is error message")}>
       Set Error
     </button>
@@ -288,8 +350,8 @@ Return:
 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
+- `onSubmit`: `(currentValues) => {}` called when the form is submitted via a button with `type='submit'`
+- `onChange`: `(name, value, currentValues) => {}` called when any field value changes
 
 ## Controller
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-simple-formkit",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "keywords": [
     "react formkit",
     "react ez formkit",