Add ability to reset fields (#100)

Author: wsmd

README.md

@@ -47,6 +47,7 @@
     - [`formOptions.onChange`](#formoptionsonchange)
     - [`formOptions.onTouched`](#formoptionsontouched)
     - [`formOptions.onClear`](#formoptionsonclear)
+    - [`formOptions.onReset`](#formoptionsonreset)
     - [`formOptions.withIds`](#formoptionswithids)
   - [`[formState, inputs]`](#formstate-inputs)
     - [Form State](#form-state)
@@ -128,6 +129,8 @@ From the example above, as the user fills in the form, the `formState` object wi
   },
   clear: Function,
   clearField: Function,
+  reset: Function,
+  resetField: Function,
   setField: Function,
 }
 ```
@@ -385,21 +388,26 @@ function Form() {
 
 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 set the error value for a single input using `formState.setFieldError` and to clear a single input's value using `formState.clearField`.
+It's also possible to clear a single input's value or to reset it to its initial value, if provided, using `formState.clearField` and `formState.resetField` respectively.
+
+As a convenience you can also set the error value for a single input using `formState.setFieldError`.
 
 ### Resetting The From State
 
-All fields in the form can be cleared all at once at any time using `formState.clear`.
+The form state can be cleared or reset back to its initial state if provided at any time using `formState.clear` and `formState.reset` respectively.
 
 ```js
 function Form() {
-  const [formState, { text, email }] = useFormState();
+  const [formState, { text, email }] = useFormState({
+    email: '[email protected]',
+  });
   return (
     <>
-      <input {...text("first_name")} />
-      <input {...text("last_name")} />
-      <input {...email("email")} />
+      <input {...text('first_name')} />
+      <input {...text('last_name')} />
+      <input {...email('email')} />
       <button onClick={formState.clear}>Clear All Fields</button>
+      <button onClick={formState.reset}>Reset to Initial State</button>
     </>
   );
 }
@@ -531,6 +539,19 @@ const [formState, inputs] = useFormState(null, {
 formState.clear(); // clearing the form state
 ```
 
+#### `formOptions.onReset`
+
+A function that gets called after calling `formState.reset` indicating that all fields in the form state are set to their initial values.
+
+```js
+const [formState, inputs] = useFormState(null, {
+  onReset() {
+    // form state was reset successfully
+  }
+});
+ formState.reset(); // resetting 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).
@@ -598,6 +619,12 @@ formState = {
   // clears the state of an input
   clearField(name: string): void,
 
+  // resets all fields the form back to their initial state if provided
+  reset(): void,
+
+  // resets the state of an input back to its initial state if provided
+  resetField(name: string): void,
+
   // updates the value of an input
   setField(name: string, value: string): void,
 

src/index.d.ts

@@ -23,10 +23,12 @@ interface FormState<T, E = StateErrors<T, string>> {
   validity: StateValidity<T>;
   touched: StateValidity<T>;
   errors: E;
+  reset(): void;
   clear(): void;
   setField<K extends keyof T>(name: K, value: T[K]): void;
   setFieldError(name: keyof T, error: string): void;
   clearField(name: keyof T): void;
+  resetField(name: keyof T): void;
 }
 
 interface FormOptions<T> {
@@ -37,6 +39,7 @@ interface FormOptions<T> {
   ): void;
   onBlur(event: React.FocusEvent<InputElement>): void;
   onClear(): void;
+  onReset(): void;
   onTouched(event: React.FocusEvent<InputElement>): void;
   withIds: boolean | ((name: string, value?: string) => string);
 }

src/useFormState.js

@@ -18,10 +18,11 @@ import {
 } from './constants';
 
 const defaultFormOptions = {
-  onChange: noop,
   onBlur: noop,
-  onTouched: noop,
+  onChange: noop,
   onClear: noop,
+  onReset: noop,
+  onTouched: noop,
   withIds: false,
 };
 
@@ -59,7 +60,7 @@ export default function useFormState(initialState, options) {
     // probably fine.
     const key = `${type}.${name}.${toString(ownValue)}`;
 
-    function setInitialValue() {
+    function setDefaultValue() {
       /* istanbul ignore else */
       if (process.env.NODE_ENV === 'development') {
         if (isRaw && formState.current.values[name] === undefined) {
@@ -181,9 +182,12 @@ export default function useFormState(initialState, options) {
         }
       },
       get value() {
-        // auto populating initial state values on first render
         if (!hasValueInState) {
-          setInitialValue();
+          // auto populating default values if an initial value is not provided
+          setDefaultValue();
+        } else if (!formState.initialValues.has(name)) {
+          // keep track of user-provided initial values on first render
+          formState.initialValues.set(name, formState.current.values[name]);
         }
 
         // auto populating default values of touched

src/useState.js

@@ -1,12 +1,14 @@
 import { useReducer, useRef } from 'react';
 import { isFunction } from './utils';
+import { useCache } from './useCache';
 
 function stateReducer(state, newState) {
   return isFunction(newState) ? newState(state) : { ...state, ...newState };
 }
 
-export function useState({ initialState, onClear }) {
+export function useState({ initialState, onClear, onReset }) {
   const state = useRef();
+  const initialValues = useCache();
   const [values, setValues] = useReducer(stateReducer, initialState || {});
   const [touched, setTouched] = useReducer(stateReducer, {});
   const [validity, setValidity] = useReducer(stateReducer, {});
@@ -22,6 +24,7 @@ export function useState({ initialState, onClear }) {
   }
 
   const clearField = name => setField(name);
+  const resetField = name => setField(name, initialValues.get(name));
 
   return {
     /**
@@ -34,12 +37,18 @@ export function useState({ initialState, onClear }) {
     setTouched,
     setValidity,
     setError,
+    initialValues,
     controls: {
       clearField,
+      resetField,
       clear() {
         Object.keys(state.current.values).forEach(clearField);
         onClear();
       },
+      reset() {
+        Object.keys(state.current.values).forEach(resetField);
+        onReset();
+      },
       setField(name, value) {
         setField(name, value, true, true);
       },

test/useFormState-manual-updates.test.js

@@ -14,6 +14,19 @@ describe('useFormState manual updates', () => {
     expect(formState.current.values.name).toEqual('');
   });
 
+  it('resets a field to its initial value on form.resetField', () => {
+    const { formState, change } = renderWithFormState(
+      ([, input]) => <input {...input.text('name')} />,
+      { name: 'waseem' },
+    );
+
+    change({ value: 'cool' });
+    expect(formState.current.values.name).toEqual('cool');
+
+    formState.current.resetField('name');
+    expect(formState.current.values.name).toEqual('waseem');
+  });
+
   it('clears the entire all form fields using form.clear', () => {
     const onClear = jest.fn();
     const { root, formState, change, click } = renderWithFormState(
@@ -47,6 +60,41 @@ describe('useFormState manual updates', () => {
     expect(onClear).toHaveBeenCalled();
   });
 
+  it('resets the entire all form fields to their initial values using form.reset', () => {
+    const onReset = jest.fn();
+    const initialState = {
+      first: 'waseem',
+      last: 'dahman',
+      role: ['user'],
+    };
+
+    const { root, formState, change, click } = renderWithFormState(
+      ([, input]) => (
+        <div>
+          <input {...input.text('first')} />
+          <input {...input.text('last')} />
+          <input {...input.checkbox('role', 'admin')} />
+          <input {...input.checkbox('role', 'user')} />
+        </div>
+      ),
+      initialState,
+      { onReset },
+    );
+
+    change({ value: 'bruce' }, root.childNodes[0]);
+    change({ value: 'wayne' }, root.childNodes[1]);
+    click({}, root.childNodes[3]);
+    expect(formState.current.values).toEqual({
+      first: 'bruce',
+      last: 'wayne',
+      role: [],
+    });
+
+    formState.current.reset();
+    expect(formState.current.values).toEqual(initialState);
+    expect(onReset).toHaveBeenCalled();
+  });
+
   it('sets the value of an input programmatically using from.setField', () => {
     const { formState } = renderWithFormState(([, input]) => (
       <input {...input.text('name')} />

test/useFormState.test.js

@@ -11,9 +11,11 @@ describe('useFormState API', () => {
         touched: {},
         errors: {},
         clear: expect.any(Function),
+        reset: expect.any(Function),
         setField: expect.any(Function),
         setFieldError: expect.any(Function),
         clearField: expect.any(Function),
+        resetField: expect.any(Function),
       },
       expect.any(Object),
     ]);