Merge pull request #8 from commitd/sh-useEventHandler

✨ Adds useEventListener hook

Author: stuarthendren

src/hooks/index.ts

@@ -1,6 +1,7 @@
+export * from './useDebounce'
+export * from './useEventListener'
 export * from './useInterval'
 export * from './useLocalState'
 export * from './usePoll'
 export * from './useTimeout'
 export * from './useToggle'
-export * from './useDebounce'

src/hooks/useEventListener/index.ts

@@ -0,0 +1 @@
+export * from './useEventListener'

src/hooks/useEventListener/useEventListener.stories.tsx

@@ -0,0 +1,88 @@
+import { Meta, Story } from '@storybook/react'
+import { Button, Typography } from '@committed/components'
+import React, { RefObject } from 'react'
+import { useEventListener } from '.'
+
+export interface UseEventListenerDocsProps<
+  T extends HTMLElement = HTMLDivElement
+> {
+  /** the name of the event to listen to  */
+  eventName: string
+  /** the callback function to call on the event firing  */
+  handler: ((event: Event) => void) | null
+  /** (optional) reference for the element to add the listener too */
+  element?: RefObject<T>
+}
+
+/**
+ * useEventListener hook adds an event listener to the given event type and calls the handler when fired.
+ * The listener is added to the `window` by default or the target element if provided using a ref object.
+ * It is removed automatically on unmounting.
+ *
+ * For event types reference see <https://developer.mozilla.org/en-US/docs/Web/Events>.
+ *
+ * (Derived from <https://usehooks-typescript.com/use-event-listener>)
+ *
+ * @param eventName the name of the event to listen to
+ * @param handler the callback function
+ * @param element (optional) reference for the element
+ */
+export const UseEventListenerDocs: React.FC<UseEventListenerDocsProps> = () =>
+  null
+
+export default {
+  title: 'Hooks/useEventListener',
+  component: UseEventListenerDocs,
+  excludeStories: ['UseEventListenerDocs'],
+  argTypes: {
+    eventName: {
+      description:
+        'the name of the event to listen to (some examples to select from here)',
+      defaultValue: 'click',
+      control: {
+        type: 'select',
+        options: ['click', 'dblclick', 'auxclick', 'mouseenter', 'mouseout'],
+      },
+    },
+    element: { control: { type: 'none' } },
+  },
+} as Meta
+
+const Template: Story<UseEventListenerDocsProps> = ({
+  eventName,
+}: UseEventListenerDocsProps) => {
+  const [count, setCount] = React.useState(0)
+  const divRef = React.useRef<HTMLDivElement>(null)
+  useEventListener(eventName, () => setCount(count + 1), divRef)
+  return (
+    <div>
+      <Typography>{`Counter: ${count}`}</Typography>
+      {/* Using div, see https://github.com/commitd/components/issues/68 */}
+      <div ref={divRef}>
+        <Button color="primary">{eventName}</Button>
+      </div>
+    </div>
+  )
+}
+
+export const Default = Template.bind({})
+Default.args = {}
+
+export const WindowAndEvents = () => {
+  const [x, setX] = React.useState(0)
+  const [y, setY] = React.useState(0)
+  useEventListener('mousemove', (event: MouseEvent) => {
+    setX(event.offsetX)
+    setY(event.offsetY)
+  })
+  return <Typography>{`Mouse Position: ${x}, ${y}`}</Typography>
+}
+WindowAndEvents.parameters = {
+  docs: {
+    description: {
+      story: `If a ref is not specified then we listen to the \`window\` (or, as here, the \`iframe\`).
+
+The event is passed to the handler and can be the relevant generic extension of \`Event\`.`,
+    },
+  },
+}

src/hooks/useEventListener/useEventListener.test.ts

@@ -0,0 +1,111 @@
+import { renderHook } from '@testing-library/react-hooks'
+import { RefObject } from 'react'
+import { useEventListener } from '.'
+
+interface Handler {
+  (e: Event): void
+}
+
+test('Should add listener, call handler, and remove listener, all on ref node', () => {
+  const listeners: Record<string, Handler> = {}
+
+  const current = ({
+    addEventListener: jest.fn((event: string, handler: Handler) => {
+      listeners[event] = handler
+    }),
+    removeEventListener: jest.fn((event: string, _handler: Handler) => {
+      delete listeners[event]
+    }),
+  } as unknown) as HTMLDivElement
+
+  const ref = {
+    current,
+  } as RefObject<HTMLDivElement>
+
+  const handler = jest.fn()
+  const { unmount } = renderHook(() => useEventListener('click', handler, ref))
+
+  expect(listeners.click).toBeTruthy()
+
+  const event = ({} as unknown) as Event
+  expect(handler).toHaveBeenCalledTimes(0)
+  ;(listeners.click as EventListener)(event)
+
+  expect(handler).toHaveBeenCalledTimes(1)
+  expect(handler).toHaveBeenCalledWith(event)
+
+  unmount()
+
+  expect(listeners.click).toBeFalsy()
+})
+
+test('Should add listener, call handler, and remove listener, all on window', () => {
+  const listeners: Record<string, EventListenerOrEventListenerObject> = {}
+
+  jest
+    .spyOn(window, 'addEventListener')
+    .mockImplementation(
+      (
+        type: string,
+        listener: EventListenerOrEventListenerObject,
+        _options?: boolean | AddEventListenerOptions | undefined
+      ) => {
+        listeners[type] = listener
+      }
+    )
+  jest
+    .spyOn(window, 'removeEventListener')
+    .mockImplementation(
+      (
+        type: string,
+        _listener: EventListenerOrEventListenerObject,
+        _options?: boolean | AddEventListenerOptions | undefined
+      ) => {
+        delete listeners[type]
+      }
+    )
+
+  const handler = jest.fn()
+  const { unmount } = renderHook(() => useEventListener('mouseout', handler))
+
+  expect(listeners.mouseout).toBeTruthy()
+
+  const event = ({} as unknown) as Event
+  expect(handler).toHaveBeenCalledTimes(0)
+  ;(listeners.mouseout as EventListener)(event)
+
+  expect(handler).toHaveBeenCalledTimes(1)
+  expect(handler).toHaveBeenCalledWith(event)
+
+  unmount()
+
+  expect(listeners.mouseout).toBeFalsy()
+})
+
+test('Should cope is handler is null', () => {
+  const listeners: Record<string, Handler> = {}
+
+  const current = ({
+    addEventListener: jest.fn((event: string, handler: Handler) => {
+      listeners[event] = handler
+    }),
+    removeEventListener: jest.fn((event: string, _handler: Handler) => {
+      delete listeners[event]
+    }),
+  } as unknown) as HTMLDivElement
+
+  const ref = {
+    current,
+  } as RefObject<HTMLDivElement>
+  const { unmount } = renderHook(() => useEventListener('custom', null, ref))
+
+  expect(listeners.custom).toBeTruthy()
+
+  const event = ({} as unknown) as Event
+
+  ;(listeners.custom as EventListener)(event)
+
+  unmount()
+
+  expect(listeners.custom).toBeFalsy()
+})

src/hooks/useEventListener/useEventListener.ts

@@ -0,0 +1,45 @@
+import { useRef, useEffect, RefObject } from 'react'
+
+/**
+ * useEventListener hook adds an event listener to the given event type and calls the handler when fired.
+ * The listener is added to the `window` by default or the target element if provided using a ref object.
+ * It is removed automatically on unmounting.
+ *
+ * For event types reference see <https://developer.mozilla.org/en-US/docs/Web/Events>.
+ *
+ * (Derived from <https://usehooks-typescript.com/use-event-listener>)
+ *
+ * @param eventName the name of the event to listen to
+ * @param handler the callback function to call on the event firing
+ * @param element (optional) reference for the element to add the listener too
+ */
+export function useEventListener<
+  T extends HTMLElement = HTMLDivElement,
+  E extends Event = Event
+>(
+  eventName: string,
+  handler: ((event: E) => void) | null,
+  element?: RefObject<T>
+): void {
+  const savedHandler = useRef<((event: E) => void) | null>()
+
+  useEffect(() => {
+    savedHandler.current = handler
+  }, [handler])
+
+  useEffect(() => {
+    function eventListener(event: Event): void {
+      const current = savedHandler.current
+      if (current != null) current(event as E)
+    }
+
+    const targetElement: T | Window = element?.current ?? window
+    targetElement.addEventListener(eventName, eventListener)
+
+    return () => {
+      targetElement.removeEventListener(eventName, eventListener)
+    }
+    // False positive request for E and T
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [eventName, element])
+}