feat(usesubmittrigger): add useSubmitTrigger (#19)

Add a new trigger called useSubmitTrigger that is responsible for providing submit events for forms

README.md

@@ -21,6 +21,7 @@ Collector is a library of React components and hooks that facilitates contextual
   - [TrackingView](#trackingview)
   - [TrackingElement](#trackingelement)
   - [useClickTrigger](#useclicktrigger)
+  - [useSubmitTrigger](#usesubmittrigger)
   - [usePageViewTrigger](#usepageviewtrigger)
 - [Code of Conduct (CoC)](#code-of-conduct-coc)
   - [Maintainers](#maintainers)
@@ -263,6 +264,41 @@ function Button({ onClick, 'tracking-label': label, children }) {
 }
 ```
 
+### useSubmitTrigger
+
+`useSubmitTrigger` provides you a dispatch function for any kind of form submission event.
+
+The dispatch function accepts the following interface:
+
+```jsx
+interface Options {
+  component?: string;
+  label?: string;
+  customParameters?: {
+    [key: string]: any
+  };
+  event: 'submit'; // Added internally by the hook
+  timestamp: number; // Added internally when the dispatch function is called
+}
+```
+
+```jsx
+import React from 'react';
+import { useSubmitTrigger } from '@sumup/collector';
+
+function Form({ children }) {
+  const dispatch = useSubmitTrigger();
+
+  const submitHandler = (e) => {
+    e.preventDefault();
+
+    dispatch({ component: 'form' });
+  };
+
+  return <form onSubmit={handler}>{children}</form>;
+}
+```
+
 ### usePageViewTrigger
 
 `usePageViewTrigger()` lets you dispatch a [page view](#page-view) event.

src/hooks/useSubmitTrigger/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Copyright 2020, SumUp Ltd.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import useSubmitTrigger from './useSubmitTrigger';
+
+export default useSubmitTrigger;

src/hooks/useSubmitTrigger/useSubmitTrigger.spec.tsx

@@ -0,0 +1,70 @@
+/**
+ * Copyright 2019, SumUp Ltd.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as React from 'react';
+import { render, fireEvent } from '@testing-library/react';
+
+import { Events } from '../../types';
+import TrackingRoot from '../../components/TrackingRoot';
+
+import useSubmitTrigger from './useSubmitTrigger';
+
+const DispatchForm = () => {
+  const dispatch = useSubmitTrigger();
+
+  return (
+    <form
+      data-testid="dispatch-form"
+      onSubmit={(e) => {
+        e.preventDefault();
+
+        dispatch({
+          component: 'form'
+        });
+      }}
+    >
+      Dispatch button
+    </form>
+  );
+};
+
+describe('useSubmitTrigger', () => {
+  it('should provide a dispatch function that contains the submit event', () => {
+    const dispatch = jest.fn();
+    const app = 'test-app-hook';
+    const form = 'dispatch-form';
+    const component = 'form';
+
+    const expected = {
+      app,
+      view: undefined,
+      elementTree: [],
+      event: Events.submit,
+      component,
+      id: undefined,
+      timestamp: expect.any(Number)
+    };
+
+    const { getByTestId } = render(
+      <TrackingRoot name={app} onDispatch={dispatch}>
+        <DispatchForm />
+      </TrackingRoot>
+    );
+
+    fireEvent.submit(getByTestId(form));
+
+    expect(dispatch).toHaveBeenCalledWith(expected);
+  });
+});

src/hooks/useSubmitTrigger/useSubmitTrigger.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright 2019, SumUp Ltd.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import useBaseTrigger from '../useBaseTrigger';
+import { Events } from '../../types';
+
+const useSubmitTrigger = () => useBaseTrigger(Events.submit);
+
+export default useSubmitTrigger;