Add new form and inputs control methods (#68)

* Add ability to update input value manually

* Add ability to clear/reset all fields

* update test

* Add ability to clear/reset single inputs

* refactor, add callbacks & fix broken tests

* Add tests

* reset error and validity state on setField

* Update README.md

* update code, tests, docs

Author: wsmd

README.md

@@ -5,6 +5,12 @@
 </h1>
 
 <p align="center">
+  <a href="https://www.npmjs.com/package/react-use-form-state">
+    <img src="https://img.shields.io/npm/v/react-use-form-state.svg" alt="Current Release" />
+  </a>
+  <a href="https://www.npmjs.com/package/react-use-form-state">
+    <img src="https://badgen.net/npm/dt/react-use-form-state" alt="Downloads" />
+  </a>
   <a href="https://travis-ci.org/wsmd/react-use-form-state">
     <img src="https://travis-ci.org/wsmd/react-use-form-state.svg?branch=master" alt="CI Build">
   </a>
@@ -14,12 +20,6 @@
   <a href="https://github.com/wsmd/react-use-form-state/blob/master/LICENSE">
     <img src="https://img.shields.io/github/license/wsmd/react-use-form-state.svg" alt="Licence">
   </a>
-  <a href="https://www.npmjs.com/package/react-use-form-state">
-    <img src="https://img.shields.io/npm/v/react-use-form-state.svg" alt="Current Release" />
-  </a>
-  <a href="https://www.npmjs.com/package/react-use-form-state">
-    <img src="https://badgen.net/npm/dt/react-use-form-state" alt="Downloads" />
-  </a>
 </p>
 
 <details>
@@ -37,13 +37,16 @@
   - [Without Using a `<form />` Element](#without-using-a-form--element)
   - [Labels](#labels)
   - [Custom Controls](#custom-controls)
+  - [Updating Fields Manually](#updating-fields-manually)
+  - [Resetting The From State](#resetting-the-from-state)
 - [Working with TypeScript](#working-with-typescript)
 - [API](#api)
   - [`initialState`](#initialstate)
   - [`formOptions`](#formoptions)
     - [`formOptions.onBlur`](#formoptionsonblur)
     - [`formOptions.onChange`](#formoptionsonchange)
     - [`formOptions.onTouched`](#formoptionsontouched)
+    - [`formOptions.onClear`](#formoptionsonclear)
     - [`formOptions.withIds`](#formoptionswithids)
   - [`[formState, inputs]`](#formstate-inputs)
     - [Form State](#form-state)
@@ -79,10 +82,15 @@ Please note that `react-use-form-state` requires `react@^16.8.0` as a peer depen
 ```jsx
 import { useFormState } from 'react-use-form-state';
 
-export default function SignUpForm() {
+export default function SignUpForm({ onSubmit }) {
   const [formState, { text, email, password, radio }] = useFormState();
+
+  function handleSubmit(e) {
+    // ...
+  }
+
   return (
-    <form onSubmit={() => console.log(formState)}>
+    <form onSubmit={handleSubmit}>
       <input {...text('name')} />
       <input {...email('email')} required />
       <input {...password('password')} required minLength="8" />
@@ -93,31 +101,34 @@ export default function SignUpForm() {
 }
 ```
 
-From the example above, as the user fills in the form, `formState` will look something like this:
+From the example above, as the user fills in the form, the `formState` object will look something like this:
 
 ```js
 {
-  "values": {
-    "name": "Mary Poppins",
-    "email": "[email protected]",
-    "password": "1234",
-    "plan": "free",
+  values: {
+    name: 'Mary Poppins',
+    email: '[email protected]',
+    password: '1234',
+    plan: 'free',
   },
-  "touched": {
-    "name": true,
-    "email": true,
-    "password": true,
-    "plan": true,
+  touched: {
+    name: true,
+    email: true,
+    password: true,
+    plan: true,
   },
-  "validity": {
-    "name": true,
-    "email": true,
-    "password": false,
-    "plan": true,
+  validity: {
+    name: true,
+    email: true,
+    password: false,
+    plan: true,
   },
-  "errors": {
-    "password": "Please lengthen this text to 8 characters or more",
-  }
+  errors: {
+    password: 'Please lengthen this text to 8 characters or more',
+  },
+  clear: Function,
+  clearField: Function,
+  setField: Function,
 }
 ```
 
@@ -350,6 +361,50 @@ function Widget() {
 }
 ```
 
+### Updating Fields Manually
+
+There are cases where you may want to update the value of an input manually without user interaction. To do so, the `formState.setField` method can be used.
+
+```js
+function Form() {
+  const [formState, { text }] = useFormState();
+
+  function setNameField() {
+    // manually setting the value of the "name" input
+    formState.setField('name', 'Mary Poppins');
+  }
+
+  return (
+    <>
+      <input {...text('name')} readOnly />
+      <button onClick={setNameField}>Set Name</button>
+    </>
+  )
+}
+```
+
+Please note that when `formState.setField` is called, any existing errors that might have been set due to previous interactions from the user will be cleared, and both of the `validity` and the `touched` states of the input will be set to `true`.
+
+It's also possible to clear a single input's value using `formState.clearField`.
+
+### Resetting The From State
+
+All fields in the form can be cleared all at once at any time using `formState.clear`.
+
+```js
+function Form() {
+  const [formState, { text, email }] = useFormState();
+  return (
+    <>
+      <input {...text("first_name")} />
+      <input {...text("last_name")} />
+      <input {...email("email")} />
+      <button onClick={formState.clear}>Clear All Fields</button>
+    </>
+  );
+}
+```
+
 ## Working with TypeScript
 
 When working with TypeScript, the compiler needs to know what values and inputs `useFormState` is expected to be working with.
@@ -401,7 +456,9 @@ import { useFormState } from 'react-use-form-state';
 
 function FormComponent()
   const [formState, inputs] = useFormState(initialState, formOptions);
-  // ...
+  return (
+    // ...
+  )
 }
 ```
 
@@ -460,6 +517,20 @@ const [formState, inputs] = useFormState(null, {
 });
 ```
 
+#### `formOptions.onClear`
+
+A function that gets called after calling `formState.clear` indicating that all fields in the form state are cleared successfully.
+
+```js
+const [formState, inputs] = useFormState(null, {
+  onClear() {
+    // form state was cleared successfully
+  }
+});
+
+formState.clear(); // clearing the form state
+```
+
 #### `formOptions.withIds`
 
 Indicates whether `useFormState` should generate and pass an `id` attribute to its fields. This is helpful when [working with labels](#labels-and-ids).
@@ -497,29 +568,38 @@ The first item returned by `useFormState`.
 const [formState, inputs] = useFormState();
 ```
 
-An object describing the form state that updates during subsequent re-renders.
-
-Form state consists of three nested objects:
-
-- `values`: an object holding the state of each input being rendered.
-- `validity`: an object indicating whether the value of each input is valid.
-- `errors`: an object holding all errors resulting from input validations.
-- `touched`: an object indicating whether the input was touched (focused) by the user.
+An object containing the form state that updates during subsequent re-renders. It also include methods to update the form state manually.
 
 ```ts
 formState = {
+  // an object holding the values of all input being rendered
   values: {
-    [inputName: string]: string | string[] | boolean,
+    [name: string]: string | string[] | boolean,
   },
+
+  // an object indicating whether the value of each input is valid
   validity: {
-    [inputName: string]?: boolean,
+    [name: string]?: boolean,
   },
+
+  // an object holding all errors resulting from input validations
   errors: {
-    [input: name]?: any,
+    [name: string]?: any,
   },
+
+  // an object indicating whether the input was touched (focused) by the user
   touched: {
-    [inputName: string]?: boolean,
+    [name: string]?: boolean,
   },
+
+  // clears all fields in the form
+  clear(): void,
+
+  // clears the state of an input
+  clearField(name: string): void,
+
+  // updates the value of an input
+  setField(name: string, value: string): void,,
 }
 ```
 

src/index.d.ts

@@ -23,6 +23,9 @@ interface FormState<T, E = StateErrors<T, string>> {
   validity: StateValidity<T>;
   touched: StateValidity<T>;
   errors: E;
+  clear(): void;
+  setField<K extends keyof T>(name: K, value: T[K]): void;
+  clearField(name: keyof T): void;
 }
 
 interface FormOptions<T> {
@@ -32,6 +35,7 @@ interface FormOptions<T> {
     nextStateValues: StateValues<T>,
   ): void;
   onBlur(event: React.FocusEvent<InputElement>): void;
+  onClear(): void;
   onTouched(event: React.FocusEvent<InputElement>): void;
   withIds: boolean | ((name: string, value?: string) => string);
 }

src/useFormState.js

@@ -21,17 +21,17 @@ const defaultFromOptions = {
   onChange: noop,
   onBlur: noop,
   onTouched: noop,
+  onClear: noop,
   withIds: false,
 };
 
 export default function useFormState(initialState, options) {
   const formOptions = { ...defaultFromOptions, ...options };
 
-  const formState = useState({ initialState });
+  const formState = useState({ initialState, ...formOptions });
   const { getIdProp } = useInputId(formOptions.withIds);
   const { set: setDirty, has: isDirty } = useCache();
   const callbacks = useCache();
-
   const devWarnings = useCache();
 
   function warn(key, type, message) {
@@ -185,6 +185,12 @@ export default function useFormState(initialState, options) {
         if (!hasValueInState) {
           setInitialValue();
         }
+
+        // auto populating default values of touched
+        if (formState.current.touched[name] == null) {
+          formState.setTouched({ [name]: false });
+        }
+
         /**
          * Since checkbox and radio inputs have their own user-defined values,
          * and since checkbox inputs can be either an array or a boolean,
@@ -258,6 +264,7 @@ export default function useFormState(initialState, options) {
          * A) when it's either touched for the first time
          * B) when it's marked as dirty due to a value change
          */
+        /* istanbul ignore else */
         if (!formState.current.touched[name] || isDirty(name)) {
           validate(e);
           setDirty(name, false);
@@ -281,7 +288,10 @@ export default function useFormState(initialState, options) {
   );
 
   return [
-    formState.current,
+    {
+      ...formState.current,
+      ...formState.controls,
+    },
     {
       ...inputPropsCreators,
       [LABEL]: (name, ownValue) => getIdProp('htmlFor', name, ownValue),

src/useState.js

@@ -5,18 +5,27 @@ function stateReducer(state, newState) {
   return isFunction(newState) ? newState(state) : { ...state, ...newState };
 }
 
-export function useState({ initialState }) {
+export function useState({ initialState, onClear }) {
+  const state = useRef();
   const [values, setValues] = useReducer(stateReducer, initialState || {});
   const [touched, setTouched] = useReducer(stateReducer, {});
   const [validity, setValidity] = useReducer(stateReducer, {});
   const [errors, setError] = useReducer(stateReducer, {});
 
-  const state = useRef();
   state.current = { values, touched, validity, errors };
 
+  function setField(name, value, inputValidity, inputTouched, inputError) {
+    setValues({ [name]: value });
+    setTouched({ [name]: inputTouched });
+    setValidity({ [name]: inputValidity });
+    setError({ [name]: inputError });
+  }
+
+  const clearField = name => setField(name);
+
   return {
     /**
-     * @type {{ values, touched, current, errors }}
+     * @type {{ values, touched, validity, errors }}
      */
     get current() {
       return state.current;
@@ -25,5 +34,15 @@ export function useState({ initialState }) {
     setTouched,
     setValidity,
     setError,
+    controls: {
+      clearField,
+      clear() {
+        Object.keys(state.current.values).forEach(clearField);
+        onClear();
+      },
+      setField(name, value) {
+        setField(name, value, true, true);
+      },
+    },
   };
 }