feat: Implement useSectionExpandedTrigger hook (#151)

* Implement useExpandTrigger hook

* feat: rename useExpandTrigger to useSectionExpandedTrigger

* feat: add documentation and unit tests

Author: marielakas

README.md

@@ -21,6 +21,7 @@ Collector is a library of React components and hooks that facilitates contextual
   - [TrackingView](#trackingview)
   - [TrackingElement](#trackingelement)
   - [useClickTrigger](#useclicktrigger)
+  - [useSectionExpandedTrigger](#usesectionexpandedtrigger)
   - [useSubmitTrigger](#usesubmittrigger)
   - [usePageViewTrigger](#usepageviewtrigger)
 - [Plugin](#plugin)
@@ -115,7 +116,8 @@ interface Event {
     | 'page-view'
     | 'page-reactivated'
     | 'submit'
-    | 'browser-back'; // This property is added internally based on the kind of event you dispatched.
+    | 'browser-back'
+    | 'section-expanded'; // This property is added internally based on the kind of event you dispatched.
   timestamp: number; // This property is added internally when the dispatch function is called
   customParameters?: {
     [key: string]: any;
@@ -274,6 +276,42 @@ function Button({ onClick, 'tracking-label': label, children }) {
   return <button onClick={handler}>{children}</button>;
 }
 ```
+### useSectionExpandedTrigger
+
+`useSectionExpandedTrigger` provides you a dispatch function for a section expanded event.
+
+The dispatch function accepts the following interface:
+
+```jsx
+interface Options {
+  component?: string;
+  label?: string;
+  customParameters?: {
+    [key: string]: any
+  };
+  event: 'section-expanded'; // Added internally by the hook
+  timestamp: number; // Added internally when the dispatch function is called
+}
+```
+
+```jsx
+import React from 'react';
+import { useSectionExpandedTrigger } from '@sumup/collector';
+
+function Section({ onClick, 'tracking-label': label, children }) {
+  const dispatch = useSectionExpandedTrigger();
+  let expandHandler = onClick;
+
+  if (label) {
+    expandHandler = (e) => {
+      dispatch({ label, component: 'section' });
+      onClick && onClick(e);
+    };
+  }
+
+  return <div onClick={expandHandler}>{children}</div>;
+}
+```
 
 ### useSubmitTrigger
 

src/hooks/useSectionExpandedTrigger/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 useSectionExpandedTrigger from './useSectionExpandedTrigger';
+
+export default useSectionExpandedTrigger;

src/hooks/useSectionExpandedTrigger/useSectionExpandedTrigger.spec.tsx

@@ -0,0 +1,68 @@
+/**
+ * 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 useSectionExpandedTrigger from './useSectionExpandedTrigger';
+
+const DispatchButton = () => {
+  const dispatch = useSectionExpandedTrigger();
+
+  return (
+    <button
+      data-testid="section"
+      onClick={() =>
+        dispatch({
+          component: 'section'
+        })
+      }
+    >
+      Dispatch button
+    </button>
+  );
+};
+
+describe('useSectionExpandedTrigger', () => {
+  it('should provide a dispatch function that contains the section-expanded event', () => {
+    const dispatch = jest.fn();
+    const app = 'test-app-hook';
+    const btn = 'section';
+    const component = 'section';
+
+    const expected = {
+      app,
+      view: undefined,
+      elementTree: [],
+      event: Events.sectionExpanded,
+      component,
+      id: undefined,
+      timestamp: expect.any(Number)
+    };
+
+    const { getByTestId } = render(
+      <TrackingRoot name={app} onDispatch={dispatch}>
+        <DispatchButton />
+      </TrackingRoot>
+    );
+
+    fireEvent.click(getByTestId(btn));
+
+    expect(dispatch).toHaveBeenCalledWith(expected);
+  });
+});

src/hooks/useSectionExpandedTrigger/useSectionExpandedTrigger.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 useSectionExpandedTrigger = () => useBaseTrigger(Events.sectionExpanded);
+
+export default useSectionExpandedTrigger;

src/index.ts

@@ -20,6 +20,7 @@ import useClickTrigger from './hooks/useClickTrigger';
 import useSubmitTrigger from './hooks/useSubmitTrigger';
 import usePageViewTrigger from './hooks/usePageViewTrigger';
 import usePageActiveTrigger from './hooks/usePageActiveTrigger';
+import useSectionExpandedTrigger from './hooks/useSectionExpandedTrigger';
 import getFlushedPayload from './plugins/getFlushedPayload';
 import * as Types from './types';
 
@@ -31,6 +32,7 @@ export {
   useSubmitTrigger,
   usePageViewTrigger,
   usePageActiveTrigger,
+  useSectionExpandedTrigger,
   getFlushedPayload
 };
 

src/types.ts

@@ -22,7 +22,8 @@ export enum Events {
   pageView = 'page-view',
   pageReactivated = 'page-reactivated',
   submit = 'submit',
-  browserBack = 'browser-back'
+  browserBack = 'browser-back',
+  sectionExpanded = 'section-expanded'
 }
 
 export interface Payload {
@@ -45,7 +46,6 @@ export interface Dispatch {
     [key: string]: unknown;
   };
 }
-
 export interface TrackingContextKeys {
   app?: string;
   view?: string;