Feat/use document evt listener (#85)

* feat: add docs for the use document event listener

* fix: docs for useWindowEventListener

* feat: addition of changeset

* feat: add once options to the event listener

Author: abhushanaj

.changeset/happy-buckets-grab.md

@@ -0,0 +1,5 @@
+---
+'@abhushanaj/react-hooks': minor
+---
+
+Addition of the useDocumentEventListener

react-hooks/src/hooks/useDocumentEventListener/index.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest';
+
+import { useDocumentEventListener } from '.';
+
+/**
+ * Other test are not required since this is just a wrapper over _useEventListener which already has the necessary tests
+ */
+describe('useDocumentEventListener() hook', () => {
+	it('should be defined', () => {
+		expect.hasAssertions();
+		expect(useDocumentEventListener).toBeDefined();
+	});
+});

react-hooks/src/hooks/useDocumentEventListener/index.ts

@@ -0,0 +1,18 @@
+import type { UseEventListenerCallback, UseEventListenerEventMap, UseEventListenerOptions } from '../_useEventListener';
+
+import { _useEventListener } from '../_useEventListener';
+import { useIsClient } from '../useIsClient';
+
+/**
+ * useDocumentEventListener() - Custom react hook to attch event listeners to document object.
+ * @see - https://react-hooks.abhushan.dev/hooks/dom/usedocumenteventlistener/
+ */
+export function useDocumentEventListener(
+	eventName: keyof UseEventListenerEventMap<Document>,
+	callback: UseEventListenerCallback,
+	options?: UseEventListenerOptions
+) {
+	const client = useIsClient();
+
+	return _useEventListener(client ? document : (null as unknown as Document), eventName, callback, options);
+}

react-hooks/src/index.ts

@@ -2,6 +2,7 @@
 export { useDocumentTitle } from './hooks/useDocumentTitle';
 export type { DocumentTitleOptions, UseDocumentTitleOptions } from './hooks/useDocumentTitle';
 export { useIsDocumentVisible } from './hooks/useIsDocumentVisible';
+export { useDocumentEventListener } from './hooks/useDocumentEventListener';
 
 // ======= Window =======
 export { useWindowSize } from './hooks/useWindowSize';

www/src/components/demo/useDocumentEventListener/index.tsx

@@ -0,0 +1,21 @@
+import { useDocumentEventListener } from '@abhushanaj/react-hooks';
+
+function UseDocumentEventListenerExample() {
+	useDocumentEventListener(
+		'click',
+		() => {
+			alert('Document Clicked');
+		},
+		{
+			once: true
+		}
+	);
+
+	return (
+		<div className="flex flex-col gap-2">
+			<small>Click anywhere on document to trigger an event (only once)</small>
+		</div>
+	);
+}
+
+export default UseDocumentEventListenerExample;

www/src/content/docs/hooks/dom/useDocumentEventListener.mdx

@@ -0,0 +1,50 @@
+---
+title: useDocumentEventListener
+description: 'Adds an event listener to the document object.'
+subtitle: 'Adds an event listener to the document object.'
+sidebar:
+  badge: 'New'
+---
+
+import Example from '@/components/demo/useDocumentEventListener';
+import { DemoWrapper } from '@/components/demo/wrapper';
+
+The `useDocumentEventListener` hook is helpful when you want attach event listener to the document object and run callbacks after the event is triggered.
+
+The event listener attached will automatically be cleanuped once the component is unmounted.
+
+This hook is exactly to [useEventListenerOnRef](/hooks/ui/useeventlisteneronref/), but with [`document`](https://developer.mozilla.org/en-US/docs/Web/API/Document) object as target.
+
+<DemoWrapper title="useDocumentEventListener">
+	<Example client:load />
+</DemoWrapper>
+
+## Usage
+
+Import the hook from `@abhushanaj/react-hooks` and use in required component.
+
+```tsx title="./src/App.tsx" ins={1,4-6}
+import { useDocumentEventListener } from '@abhushanaj/react-hooks';
+
+function App() {
+	useDocumentEventListener('click', () => {
+		alert('Click event triggered');
+	});
+
+	return <p>Click anywhere on document to trigger the event.</p>;
+}
+
+export default App;
+```
+
+## API Reference
+
+### Parameters
+
+| Parameter | Type                                            | Description                                                            | Default     |
+| --------- | ----------------------------------------------- | ---------------------------------------------------------------------- | ----------- |
+| eventName | `string`                                        | The name of the event to listen to.                                    | N/A         |
+| callback  | `EventListenerOrEventListenerObject`            | The event handler function to be executed when the event is triggered. | N/A         |
+| options   | `AddEventListenerOptions \| boolean` (optional) | Additional options for the event listener.                             | `undefined` |
+
+**Note:** The `EventListenerOrEventListenerObject` and `AddEventListenerOptions` are standard types defined by [`lib.dom.d.ts`](https://github.com/microsoft/TypeScript/blob/main/src/lib/dom.generated.d.ts). You can refer the [MDN spec](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#parameters) for additional information.

www/src/content/docs/hooks/window/useWindowEventListener.mdx

@@ -35,7 +35,7 @@ function App() {
 	});
 
 	return (
-		<div className="flex flex-col gap-2">
+		<div>
 			<p>Y Scroll : {yScroll}px</p>
 		</div>
 	);