Feat/use custom event (#235)

* Addition of use custom event hook

* feat: add docs for the useCustomEvent hook

* chore: add the changelog for useCustomEvent

Author: abhushanaj

.changeset/calm-clouds-move.md

@@ -0,0 +1,5 @@
+---
+'@abhushanaj/react-hooks': minor
+---
+
+Addition of the useCustomEvent() hook

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

@@ -0,0 +1,41 @@
+import { act, renderHook } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { useCustomEvent } from '.';
+
+describe('useCustomEvent() hook', () => {
+	it('should be defined', () => {
+		expect.hasAssertions();
+		expect(useCustomEvent).toBeDefined();
+	});
+
+	/**
+	 * Since the hook is composed of two other hooks, we simply check for integrity here.
+	 */
+	it('should dispatch, subscribe and unsubscribe', () => {
+		expect.hasAssertions();
+
+		const cb = vi.fn();
+		const customEventName = 'customEvt';
+
+		const { result } = renderHook(({ callback, eventName }) => useCustomEvent(eventName, callback), {
+			initialProps: {
+				eventName: customEventName,
+				callback: cb
+			}
+		});
+
+		act(() => {
+			result.current[0]();
+		});
+
+		expect(cb).toHaveBeenCalledTimes(1);
+
+		act(() => {
+			result.current[1]();
+			result.current[0]();
+		});
+
+		expect(cb).toHaveBeenCalledTimes(1);
+	});
+});

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

@@ -0,0 +1,14 @@
+import { useDispatchCustomEvent } from '../useDispatchCustomEvent';
+import { useSubscribeToCustomEvent } from '../useSubscribeToCustomEvent';
+
+/**
+ * useCustomEvent() - Custom react hook to manage the lifecycle of custom events
+ * @see - https://react-hooks.abhushan.dev/hooks/state/usecustomevent/
+ */
+export const useCustomEvent = <T>(eventName: string, callback: (e: CustomEvent<T>) => void) => {
+	const dispatch = useDispatchCustomEvent(eventName);
+
+	const unSub = useSubscribeToCustomEvent(eventName, callback);
+
+	return [dispatch, unSub] as const;
+};

react-hooks/src/index.ts

@@ -61,3 +61,4 @@ export { useDebounce } from './hooks/useDebounce';
 export { useThrottle } from './hooks/useThrottle';
 export { useDispatchCustomEvent } from './hooks/useDispatchCustomEvent';
 export { useSubscribeToCustomEvent } from './hooks/useSubscribeToCustomEvent';
+export { useCustomEvent } from './hooks/useCustomEvent';

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

@@ -0,0 +1,67 @@
+import React from 'react';
+import { useCustomEvent } from '@abhushanaj/react-hooks';
+
+import Button from '@/components/docs/button';
+
+type CustomWindow = Window &
+	typeof globalThis & {
+		state: {
+			value: number;
+		};
+	};
+
+function UseCustomEventExample() {
+	const [count, setCount] = React.useState(0);
+
+	const [dispatch, unSub] = useCustomEvent<{ newValue: number }>('valueChanged', (e) => {
+		setCount(e.detail.newValue);
+	});
+
+	React.useEffect(() => {
+		(window as CustomWindow).state = { value: 10 };
+		dispatch({ newValue: 0 });
+
+		(window as CustomWindow).state = new Proxy((window as CustomWindow).state, {
+			set(obj, prop, value) {
+				if (prop === 'value') {
+					dispatch({ newValue: value });
+				}
+
+				// @ts-expect-error
+				obj[prop] = value;
+
+				return true;
+			}
+		});
+	}, []);
+
+	const updateWindowValue = (newValue: number) => {
+		(window as CustomWindow).state.value = newValue;
+	};
+
+	return (
+		<div className="flex flex-col gap-2">
+			<p>window.state.value is :{JSON.stringify(count)}</p>
+
+			<Button variant="secondary" onClick={() => updateWindowValue(20)}>
+				Set window.state.value=20
+			</Button>
+			<Button variant="secondary" onClick={() => updateWindowValue(30)}>
+				Set window.state.value=30
+			</Button>
+
+			<Button variant="secondary" onClick={unSub}>
+				Unsubscribe
+			</Button>
+
+			<small>Update the window.state.value from console and see it reflect above.</small>
+
+			<small>
+				The example above is simply creating a proxy over window.state and for every set action performed on it,
+				dispatching action which the component is subscribing to.
+			</small>
+		</div>
+	);
+}
+
+export default UseCustomEventExample;

www/src/content/docs/hooks/utilities/useCustomEvent.mdx

@@ -0,0 +1,77 @@
+---
+title: useCustomEvent
+description: 'Manage the entire lifecycle for a custom event.'
+subtitle: 'Manage the entire lifecycle for a custom event.'
+sidebar:
+  badge: 'New'
+---
+
+import Example from '@/components/demo/useCustomEvent';
+import { DemoWrapper } from '@/components/demo/wrapper';
+
+The `useCustomEvent` hook is helpful when you want manage the entire lifecycle for a custom event. From dispatch, to subscribing and cleanup, it's a one off solution.
+
+This is helpful in scenarios like flushing pending actions after auth is completed, clearing pending analytics queue based on user action or sucessful load of analytics scripts.
+
+The hook is composed using the [useDispatchCustomEvent](/hooks/utilities/usedispatchcustomevent/) and [useSubscribeToCustomEvent](/hooks/utilities/usesubscribetocustomevent/) hooks.
+
+<DemoWrapper title="useCustomEvent">
+	<Example client:load />
+</DemoWrapper>
+
+## Usage
+
+Import the hook from `@abhushanaj/react-hooks` and use in required component.
+
+```tsx title="./src/App.tsx" ins={2,7-9} mark="useCustomEvent"
+import React from 'react';
+import { useCustomEvent } from '@abhushanaj/react-hooks';
+
+function App() {
+	const [value, setValue] = React.useState(0);
+
+	const [dispatch, unSub] = useCustomEvent<{ newValue: number }>('valueChanged', (e) => {
+		setCount(e.detail.newValue);
+	});
+
+	return (
+		<div>
+			<p>Value is: {value}</p>
+			<button onClick={unSubscribe}>Unsubscribe</button>
+			<button
+				onClick={() => {
+					dispatch({ newValue: value++ });
+				}}
+			>
+				Unsubscribe
+			</button>
+		</div>
+	);
+}
+
+export default App;
+```
+
+## Properties
+
+1. The `useCustomEvent` automatically unsubscribes from the event on component unmount, so you do not need to worry about cleanups. However it does return a `unsubscribe` function back for cases where you want to take control of this. Once unsubscribe the event cannot be subscribed to again.
+
+2. You can use the generic `useCustomEvent<Payload>(eventName, callback)` when you know the payload type. However, I recommend validating the payload first instead of relying on this approach.
+
+## API Reference
+
+### Parameters
+
+| Parameter     | Type                        | Description                                             | Default |
+| ------------- | --------------------------- | ------------------------------------------------------- | ------- |
+| eventName     | `string`                    | The name of the custom event name you want to dispatch. | N/A     |
+| eventCallback | `(e: CustomEvent<T>=>void)` | The callback which gets invoked when event is fired.    | N/A     |
+
+### Return Value
+
+The return value follows the `[dispatch, unsubscribe]` tuple.
+
+| Parameter   | Type                 | Description                                                            | Default |
+| ----------- | -------------------- | ---------------------------------------------------------------------- | ------- |
+| dispatch    | `(payload? T)=>void` | The dispatcher for the custom event which takes a payload as argument. | N/A     |
+| unsubscribe | `()=>void`           | The unsubscribe method for the event.                                  | N/A     |

www/src/content/docs/hooks/utilities/useDispatchCustomEvent.mdx

@@ -11,9 +11,11 @@ import { DemoWrapper } from '@/components/demo/wrapper';
 
 The `useDispatchCustomEvent` hook is helpful when you want to dispatch your own custom events with payloads that can be subscribed by any component in tree.
 
-This is helpful in scenarios like flushing pending actions after auth is completed, clearing pending analytics queue based om user action or sucessful load of analytics scripts.
+This is helpful in scenarios like flushing pending actions after auth is completed, clearing pending analytics queue based on user action or sucessful load of analytics scripts.
 
-The hook can be used in conjunction with[useSubscribeToCustomEvent](/hooks/utilities/usesubscribetocustomevent/).
+The hook can be used in conjunction with [useSubscribeToCustomEvent](/hooks/utilities/usesubscribetocustomevent/).
+
+For cases when you want to manage the entire lifecycle from one hook you can simply use [useCustomEvent](/hooks/utilities/usecustomevent/), with uses both `useDispatchCustomEvent` and `useSubscribeToCustomEvent` hooks internally.
 
 <DemoWrapper title="useDispatchCustomEvent">
 	<Example client:load />

www/src/content/docs/hooks/utilities/useSubscribeToCustomEvent.mdx

@@ -11,9 +11,11 @@ import { DemoWrapper } from '@/components/demo/wrapper';
 
 The `useSubscribeToCustomEvent` hook is helpful when you want to subscribe and manage the lifecycle of your own custom events with payloads.
 
-This is helpful in scenarios like flushing pending actions after auth is completed, clearing pending analytics queue based om user action or sucessful load of analytics scripts.
+This is helpful in scenarios like flushing pending actions after auth is completed, clearing pending analytics queue based on user action or sucessful load of analytics scripts.
 
-The hook can be used in conjunction with[useDispatchCustomEvent](/hooks/utilities/usedispatchcustomevent/).
+The hook can be used in conjunction with [useDispatchCustomEvent](/hooks/utilities/usedispatchcustomevent/).
+
+For cases when you want to manage the entire lifecycle from one hook you can simply use [useCustomEvent](/hooks/utilities/usecustomevent/), with uses both `useDispatchCustomEvent` and `useSubscribeToCustomEvent` hooks internally.
 
 <DemoWrapper title="useSubscribeToCustomEvent">
 	<Example client:load />
@@ -23,7 +25,7 @@ The hook can be used in conjunction with[useDispatchCustomEvent](/hooks/utilitie
 
 Import the hook from `@abhushanaj/react-hooks` and use in required component.
 
-```tsx title="./src/App.tsx" ins={2,10-13} mark="useSubscribeToCustomEvent"
+```tsx title="./src/App.tsx" ins={2,10-12} mark="useSubscribeToCustomEvent"
 import React from 'react';
 import { useSubscribeToCustomEvent } from '@abhushanaj/react-hooks';
 
@@ -49,7 +51,7 @@ export default App;
 
 ## Properties
 
-1. The `useSubscribeToCustomEvent` automatically unsubscribes from the event on component mount, so you do not need to worry about cleanups. However it does return a `unsubscribe` function back for cases where you want to take control of this. Once unsubscribe the event cannot be subscribed to again.
+1. The `useSubscribeToCustomEvent` automatically unsubscribes from the event on component unmount, so you do not need to worry about cleanups. However it does return a `unsubscribe` function back for cases where you want to take control of this. Once unsubscribe the event cannot be subscribed to again.
 
 2. You can use the generic `useSubscribeToCustomEvent<Payload>(eventName, callback)` when you know the payload type. However, I recommend validating the payload first instead of relying on this approach.