📝 docs: useEventListener 문서 추가

Author: bicochan

docs/pages/hooks/_meta.json

@@ -5,14 +5,17 @@
   "useDeepCompareEffect": "useDeepCompareEffect",
   "useDelayFlag": "useDelayFlag",
   "useDetectDevice": "useDetectDevice",
+  "useEventListener": "useEventListener",
   "useGeolocation": "useGeolocation",
   "useHover": "useHover",
+  "useIntersectionObserver": "useIntersectionObserver",
   "useInterval": "useInterval",
   "useKeyCombination": "useKeyCombination",
+  "useKeyDown": "useKeyDown",
   "useLongPress": "useLongPress",
   "useMousePosition": "useMousePosition",
-  "useIntersectionObserver": "useIntersectionObserver",
   "useOnlineStatus": "useOnlineStatus",
+  "useOutsideClick": "useOutsideClick",
   "usePrefersColorScheme": "usePrefersColorScheme",
   "usePreventCopy": "usePreventCopy",
   "useScrollLock": "useScrollLock",
@@ -22,8 +25,6 @@
   "useToggle": "useToggle",
   "useTranslation": "useTranslation",
   "useUnmountEffect": "useUnmountEffect",
-  "useOutsideClick": "useOutsideClick",
-  "useKeyDown": "useKeyDown",
   "_template": {
     "display": "hidden"
   }

docs/pages/hooks/useEventListener.mdx

@@ -0,0 +1,65 @@
+# useEventListener
+
+## Introduce
+
+특정 객체에 이벤트 리스너를 손쉽게 추가할 수 있는 훅입니다.
+
+```ts
+export type EventMap = {
+  window: WindowEventMap;
+  document: DocumentEventMap;
+  htmlElement: HTMLElementEventMap;
+  svgElement: SVGElementEventMap;
+};
+
+export type EventElement = {
+  window: Window;
+  document: Document;
+  htmlElement: RefObject<HTMLElement> | HTMLElement;
+  svgElement: RefObject<SVGElement> | SVGElement;
+};
+
+const useEventListener = <
+  K extends keyof EventMap,
+  E extends keyof EventMap[K] & string,
+>(
+  eventName: E,
+  handler: (event: EventMap[K][E]) => void,
+  element?: EventElement[K] | null,
+  options?: AddEventListenerOptions
+): void
+```
+
+- 현재 이벤트 리스너를 추가할 수 있는 객체는 `window`, `document`, `htmlElement`, `svgElement` 4가지입니다.
+
+### Props
+
+- `eventName`: 추가할 이벤트의 이름
+- `handler`: 이벤트 발생 시 실행되는 핸들러 함수
+- `element`: 이벤트를 추가할 대상 Element
+  - default: `window`
+- `options`: 이벤트 리스너 기본 옵션
+
+{/* 훅 사용중에 로그가 나올 수 있는 부분은 Callout type="warning"을 사용하여 표기합니다. */}
+
+## Examples
+
+```tsx copy filename="TestComponent.tsx"
+import { useEventListener } from '@frontend-opensource/use-react-hooks';
+
+const TestComponent = () => {
+  const buttonRef = useRef<HTMLButtonElement>(null);
+
+  const handleClick = () => {
+    console.log('Button clicked!');
+  };
+
+  useEventListener('click', handleClick, buttonRef);
+
+  return (
+    <div>
+      <button ref={buttonRef}>Click</button>
+    </div>
+  );
+};
+```

src/hooks/useEventListener/useEventListener.ts

@@ -3,16 +3,15 @@ import { isClient } from '@/utils';
 import { EventMap, EventElement } from './type';
 
 /**
- * 특정 이벤트에 대한 이벤트 리스너를 추가하여, 이벤트 발생 시 핸들러를 실행하는 훅.
+ * 특정 객체에 이벤트 리스너를 손쉽게 추가할 수 있는 훅
  *
- * @param {E} eventName - 추가할 이벤트의 이름.
- * @param {(event: EventMap[K][E]) => void} handler - 이벤트 발생 시 호출되는 콜백 함수.
- * @param {EventElement[K] | null} [element=window] - 이벤트를 추가할 대상 Element, 기본값은 window.
- * @param {AddEventListenerOptions} [options] - 이벤트 리스너 기본 옵션.
+ * @param {E} eventName - 추가할 이벤트의 이름
+ * @param {(event: EventMap[K][E]) => void} handler - 이벤트 발생 시 실행되는 콜백 함수
+ * @param {EventElement[K] | null} [element=window] - 이벤트를 추가할 대상 Element, 기본값은 window
+ * @param {AddEventListenerOptions} [options] - 이벤트 리스너 기본 옵션
  *
  * @description
- * 지정된 이벤트가 발생할 때마다 제공된 핸들러를 호출합니다.
- * 가능한 Element로 window, document, htmlElement, svgElement
+ * 현재 이벤트 리스너를 추가할 수 있는 객체는 `window`, `document`, `htmlElement`, `svgElement` 4가지입니다.
  */
 
 function useEventListener<