Added 'useTrackingProps'-hook

Author: Gijs Nieuwenhuis

README.md

@@ -27,6 +27,7 @@ A library containing javascript utilities that we until now often copy between p
     -   [Hooks](#hooks)
         -   [`useStateWithRef`](#usestatewithref)
         -   [`useScrollToTopOnDependencyChange`](#usescrolltotopondependencychange)
+        -   [`useTrackingProps`](#usetrackingprops)
 -   [Storage](#storage)
     -   [`localStorage`](#localstorage)
     -   [`sessionStorage`](#sessionstorage)
@@ -380,6 +381,32 @@ const location = useLocation(); // react-router-dom
 useScrollToTopOnDependencyChange(location.pathname, location.search);
 ```
 
+#### `useTrackingProps`
+
+Applies uniform setup for tracking events, using attributes on DOM elements. In Google Tag Manager these can be registered and used to, in turn, push events to Google Analytics or other (tracking) platforms.
+
+Usage:
+
+```jsx
+import useTrackingProps from '@freshheads/javascript-essentials/build/react/hooks/useTrackingProps';
+
+type Props = {
+    subscribeToNewsletter: boolean,
+};
+
+const PreorderSubmitButton: React.FC<Props> = (subscribeToNewsletter) => {
+    const trackingProps = useTrackingProps('preorder', 'submit', {
+        subscribeToNewsletter,
+    });
+
+    return (
+        <button {...trackingProps} type="submit">
+            Submit
+        </button>
+    );
+};
+```
+
 ## Routing
 
 ### `createPathFromRoute`

src/react/hooks/__tests__/__snapshots__/useTrackingProps.test.tsx.snap

@@ -0,0 +1,20 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`useTrackingProps() When applied on a JSX element ..with context supplied should render the tracking props on it correctly 1`] = `
+<DocumentFragment>
+  <button
+    data-tracking-event-action="submit"
+    data-tracking-event-context="{\\"subscribeToNewsletter\\":true}"
+    data-tracking-event-name="preorder"
+  />
+</DocumentFragment>
+`;
+
+exports[`useTrackingProps() When applied on a JSX element ..without context supplied should render the tracking props on it correctly 1`] = `
+<DocumentFragment>
+  <button
+    data-tracking-event-action="submit"
+    data-tracking-event-name="preorder"
+  />
+</DocumentFragment>
+`;

src/react/hooks/__tests__/useTrackingProps.test.tsx

@@ -0,0 +1,30 @@
+import { render } from '@testing-library/react';
+import useTrackingProps from '../useTrackingProps';
+
+import React from 'react';
+
+describe('useTrackingProps()', () => {
+    describe('When applied on a JSX element', () => {
+        describe('..with context supplied', () => {
+            it('should render the tracking props on it correctly', () => {
+                const trackingProps = useTrackingProps('preorder', 'submit', {
+                    subscribeToNewsletter: true,
+                });
+
+                const { asFragment } = render(<button {...trackingProps} />);
+
+                expect(asFragment()).toMatchSnapshot();
+            });
+        });
+
+        describe('..without context supplied', () => {
+            it('should render the tracking props on it correctly', () => {
+                const trackingProps = useTrackingProps('preorder', 'submit');
+
+                const { asFragment } = render(<button {...trackingProps} />);
+
+                expect(asFragment()).toMatchSnapshot();
+            });
+        });
+    });
+});

src/react/hooks/useTrackingProps.ts

@@ -0,0 +1,33 @@
+import { Serializable } from '../../types/utility';
+
+export type TrackingProps = {
+    'data-tracking-event-name': string;
+    'data-tracking-event-action': string;
+    'data-tracking-event-context'?: Serializable;
+};
+
+/**
+ * Applies uniform setup for tracking events, using attributes on DOM elements.
+ * In Google Tag Manager these can be registered and used to, in turn, push
+ * events to Google Analytics or other (tracking) platforms.
+ *
+ * @param {string} eventName        i.e. "preorder"
+ * @param {string} eventAction      i.e. "submit"
+ * @param {Serializable=} context   i.e. "{ subscribeToNewsletter: false }"
+ */
+export default function useTrackingProps(
+    eventName: string,
+    eventAction: string,
+    context?: Serializable
+): TrackingProps {
+    let props: TrackingProps = {
+        'data-tracking-event-name': eventName,
+        'data-tracking-event-action': eventAction,
+    };
+
+    if (context) {
+        props['data-tracking-event-context'] = JSON.stringify(context);
+    }
+
+    return props;
+}