Adding onSubmitFailed + tests + documentation. Fixes #539

Author: davidkpiano

docs/api/Form.md

@@ -140,6 +140,50 @@ export default connect(null)(MyForm);
 
 ### Notes
 - You can do anything in `onSubmit`; including firing off custom actions or handling (async) validation yourself.
+- `onSubmit` can also be triggered remotely by dispatching `actions.submit(model)` where `model` is the model of the form and no other arguments are provided. It will be called if the form is valid and able to be submitted.
+
+## `onSubmitFailed={...}`
+_(Function)_: The handler function called when the form fails to submit. This happens when:
+- attempting to submit an invalid form
+- submitting a valid form that later becomes invalid (due to async server/API validation, etc.)
+
+The callback function provided to `onSubmitFailed` will be called with one argument: the entire `formState` for the form's `model`.
+
+### Example
+```jsx
+import React from 'react';
+import { connect } from 'react-redux';
+import { Form, Control, actions } from 'react-redux-form';
+
+class MyForm extends React.Component {
+  handleSubmitFailed(userForm) {
+    // logs form-level errors
+    console.log(userForm.$form.errors);
+
+    // logs errors for user.email
+    console.log(userForm.email.errors);
+  }
+  
+  render() {
+    return (
+      <Form
+        model="user"
+        validators={{...}}
+        onSubmit={...}
+        onSubmitFailed={ (userForm) => this.handleSubmitFailed(userForm) }
+      >
+        <Control type="email" model=".email" />
+      </Form>
+    );
+  }
+}
+
+export default connect(null)(MyForm);
+```
+
+### Notes
+- This can also be used (and is extremely useful) with `<LocalForm>`.
+- Remotely triggering a submit on the form by dispatching `actions.submit(model)` will also call this callback if the form submission fails.
 
 ## `component={...}`
 _(Any)_ The `component` that the `<Form>` should be rendered to (default: `"form"`).

src/components/form-component.js

@@ -29,6 +29,7 @@ const propTypes = {
   modelValue: PropTypes.any,
   formValue: PropTypes.object,
   onSubmit: PropTypes.func,
+  onSubmitFailed: PropTypes.func,
   dispatch: PropTypes.func,
   children: PropTypes.oneOfType([
     PropTypes.func,
@@ -221,7 +222,15 @@ function createFormClass(s = defaultStrategy) {
     }
 
     handleInvalidSubmit() {
-      this.props.dispatch(s.actions.setSubmitFailed(this.props.model));
+      const { onSubmitFailed, formValue, dispatch } = this.props;
+
+      if (onSubmitFailed) {
+        onSubmitFailed(formValue);
+      }
+
+      if (!formValue.$form.submitFailed) {
+        dispatch(s.actions.setSubmitFailed(this.props.model));
+      }
     }
 
     handleReset(e) {

src/reducers/form-actions-reducer.js

@@ -60,11 +60,24 @@ const setInitialFieldState = (field, key) => {
   });
 };
 
+const addIntent = (intents, newIntent) => {
+  if (!intents) return [newIntent];
+  if (intents.some(intent => intent.type === newIntent.type)) return intents;
+
+  return intents.concat(newIntent);
+};
+
+const clearIntents = (intents, oldIntent) => {
+  if (!intents || typeof oldIntent === 'undefined') return [];
+  return intents.filter(intent => intent.type !== oldIntent.type);
+};
+
 export default function formActionsReducer(state, action, localPath) {
   const [field] = getFieldAndForm(state, localPath);
   const fieldState = field && field.$form
     ? field.$form
     : field;
+  const { intents } = fieldState;
 
   let fieldUpdates = {};
   let subFieldUpdates = {};
@@ -75,8 +88,8 @@ export default function formActionsReducer(state, action, localPath) {
       fieldUpdates = {
         focus: true,
         intents: action.silent
-          ? []
-          : [action],
+          ? intents
+          : addIntent(intents, action),
       };
 
       break;
@@ -261,15 +274,15 @@ export default function formActionsReducer(state, action, localPath) {
 
     case actionTypes.ADD_INTENT: {
       fieldUpdates = {
-        intents: [action.intent],
+        intents: addIntent(intents, action.intent),
       };
 
       break;
     }
 
     case actionTypes.CLEAR_INTENTS: {
       fieldUpdates = {
-        intents: [],
+        intents: clearIntents(intents, action.intent),
       };
 
       break;

test/form-component-spec.js

@@ -1837,5 +1837,55 @@ Object.keys(testContexts).forEach((testKey) => {
         assert.isTrue(handleSubmit.calledOnce);
       });
     });
+
+    describe('onSubmitFailed() prop', () => {
+      it('should call onSubmitFailed() prop if submit attempted with invalid form', () => {
+        const initialState = getInitialState({ foo: '' });
+
+        const store = testCreateStore({
+          test: modelReducer('test', initialState),
+          testForm: formReducer('test', initialState),
+        });
+
+        let handleSubmitFailedCalledWith = null;
+
+        function handleSubmitFailed(val) {
+          handleSubmitFailedCalledWith = val;
+        }
+
+        const form = TestUtils.renderIntoDocument(
+          <Provider store={store}>
+            <Form
+              model="test"
+              onSubmitFailed={handleSubmitFailed}
+              validators={{
+                foo: (val) => val.length,
+              }}
+            >
+              <Control model=".foo" />
+            </Form>
+          </Provider>
+        );
+
+        const formNode = TestUtils.findRenderedDOMComponentWithTag(form, 'form');
+
+        TestUtils.Simulate.submit(formNode);
+
+        assert.containSubset(handleSubmitFailedCalledWith, {
+          $form: {
+            model: 'test',
+            valid: false,
+          },
+          foo: {
+            model: 'test.foo',
+            valid: false,
+            errors: true,
+          },
+        });
+
+        assert.isFalse(store.getState().testForm.$form.pending);
+        assert.isTrue(store.getState().testForm.$form.submitFailed);
+      });
+    });
   });
 });