Added useEventListener

packages/runed/src/lib/functions/index.ts

@@ -1,3 +1,4 @@
 export * from "./useActiveElement/index.js";
 export * from "./useDebounce/index.js";
 export * from "./useElementSize/index.js";
+export * from "./useEventListener/index.js";

packages/runed/src/lib/functions/useEventListener/index.ts

@@ -0,0 +1 @@
+export * from "./useEventListener.js";

packages/runed/src/lib/functions/useEventListener/useEventListener.ts

@@ -0,0 +1,45 @@
+import type { ValueOrGetter } from "$lib/internal/types.js";
+import { boxed } from "$lib/internal/utils/boxed.svelte.js";
+import { addEventListener } from "$lib/internal/utils/event.js";
+
+export function useEventListener<TEvent extends keyof WindowEventMap>(
+	target: ValueOrGetter<Window>,
+	event: TEvent,
+	handler: (this: Window, event: WindowEventMap[TEvent]) => unknown,
+	options?: boolean | AddEventListenerOptions
+): void;
+
+export function useEventListener<TEvent extends keyof DocumentEventMap>(
+	target: ValueOrGetter<Document>,
+	event: TEvent,
+	handler: (this: Document, event: DocumentEventMap[TEvent]) => unknown,
+	options?: boolean | AddEventListenerOptions
+): void;
+
+export function useEventListener<
+	TElement extends HTMLElement,
+	TEvent extends keyof HTMLElementEventMap,
+>(
+	target: ValueOrGetter<TElement>,
+	event: TEvent,
+	handler: (this: TElement, event: HTMLElementEventMap[TEvent]) => unknown,
+	options?: boolean | AddEventListenerOptions
+): void;
+
+export function useEventListener(
+	target: ValueOrGetter<EventTarget>,
+	event: string,
+	handler: EventListenerOrEventListenerObject,
+	options?: boolean | AddEventListenerOptions
+): void;
+
+export function useEventListener(
+	target: ValueOrGetter<EventTarget>,
+	event: string,
+	handler: EventListenerOrEventListenerObject,
+	options?: boolean | AddEventListenerOptions
+) {
+	const $target = boxed(target);
+
+	$effect(() => addEventListener($target.value, event, handler, options));
+}

packages/runed/src/lib/internal/utils/event.ts

@@ -0,0 +1,58 @@
+/**
+ *  Overloaded function signatures for addEventListener
+ */
+export function addEventListener<TEvent extends keyof WindowEventMap>(
+	target: Window,
+	event: TEvent,
+	handler: (this: Window, event: WindowEventMap[TEvent]) => unknown,
+	options?: boolean | AddEventListenerOptions
+): VoidFunction;
+
+export function addEventListener<TEvent extends keyof DocumentEventMap>(
+	target: Document,
+	event: TEvent,
+	handler: (this: Document, event: DocumentEventMap[TEvent]) => unknown,
+	options?: boolean | AddEventListenerOptions
+): VoidFunction;
+
+export function addEventListener<
+	TElement extends HTMLElement,
+	TEvent extends keyof HTMLElementEventMap,
+>(
+	target: TElement,
+	event: TEvent,
+	handler: (this: TElement, event: HTMLElementEventMap[TEvent]) => unknown,
+	options?: boolean | AddEventListenerOptions
+): VoidFunction;
+
+export function addEventListener(
+	target: EventTarget,
+	event: string,
+	handler: EventListenerOrEventListenerObject,
+	options?: boolean | AddEventListenerOptions
+): VoidFunction;
+
+/**
+ * Adds an event listener to the specified target element(s) for the given event(s), and returns a function to remove it.
+ * @param target The target element(s) to add the event listener to.
+ * @param event The event(s) to listen for.
+ * @param handler The function to be called when the event is triggered.
+ * @param options An optional object that specifies characteristics about the event listener.
+ * @returns A function that removes the event listener from the target element(s).
+ */
+export function addEventListener(
+	target: Window | Document | EventTarget,
+	event: string | string[],
+	handler: EventListenerOrEventListenerObject,
+	options?: boolean | AddEventListenerOptions
+) {
+	const events = Array.isArray(event) ? event : [event];
+
+	// Add the event listener to each specified event for the target element(s).
+	events.forEach((_event) => target.addEventListener(_event, handler, options));
+
+	// Return a function that removes the event listener from the target element(s).
+	return () => {
+		events.forEach((_event) => target.removeEventListener(_event, handler, options));
+	};
+}

sites/docs/content/functions/use-active-element.md

@@ -18,16 +18,16 @@ import { UseActiveElementDemo } from '$lib/components/demos';
 	import { useActiveElement } from "runed";
 
 	const activeElement = useActiveElement();
+	const text = $derived(
+		`Currently active element: ${
+			activeElement.value !== nulla
+				? activeElement.value.localName
+				: "No active element found"
+		}`a
+	);
 </script>
 
 <div class="rounded-md bg-card p-8">
-	<p>
-		Currently active element:
-		<span class="font-bold">
-			{activeElement.value !== null
-				? activeElement.value.localName
-				: "No active element found"}
-		</span>
-	</p>
+	<p>{text}</p>
 </div>
 ```

sites/docs/content/functions/use-event-listener.md

@@ -0,0 +1,33 @@
+---
+title: UseEventListener
+description: A function that attaches an automatically disposed event listener.
+---
+
+<script>
+import { UseEventListenerDemo } from '$lib/components/demos';
+</script>
+
+## Demo
+
+<UseEventListenerDemo />
+
+## Usage
+
+```svelte
+<script lang="ts">
+	import { useEventListener } from "runed";
+
+	const activeElement = useActiveElement();
+	const text = $derived(
+		`Currently active element: ${
+			activeElement.value !== nulla
+				? activeElement.value.localName
+				: "No active element found"
+		}`a
+	);
+</script>
+
+<div class="rounded-md bg-card p-8">
+	<p>{text}</p>
+</div>
+```

sites/docs/src/lib/components/demos/index.ts

@@ -1,3 +1,4 @@
 export { default as UseActiveElementDemo } from "./use-active-element.svelte";
 export { default as UseDebounceDemo } from "./use-debounce.svelte";
 export { default as UseElementSizeDemo } from "./use-element-size.svelte";
+export { default as UseEventListenerDemo } from "./use-event-listener.svelte";

sites/docs/src/lib/components/demos/use-active-element.svelte

@@ -2,15 +2,13 @@
 	import { useActiveElement } from "runed";
 
 	const activeElement = useActiveElement();
+	const text = $derived(
+		`Currently active element: ${
+			activeElement.value !== null ? activeElement.value.localName : "No active element found"
+		}`
+	);
 </script>
 
 <div class="rounded-md bg-card p-8">
-	<p>
-		Currently active element:
-		<span class="font-bold">
-			{activeElement.value !== null
-				? activeElement.value.localName
-				: "No active element found"}
-		</span>
-	</p>
+	<p>{text}</p>
 </div>

sites/docs/src/lib/components/demos/use-event-listener.svelte

@@ -0,0 +1,13 @@
+<script lang="ts">
+	import { useEventListener } from "runed";
+
+	let count = $state(0);
+
+	$effect(() => {
+		useEventListener(document, "click", () => count++);
+	});
+</script>
+
+<div class="rounded-md bg-card p-8">
+	<p>You've clicked {count} {count === 1 ? "Time" : "Times"}</p>
+</div>

sites/docs/src/lib/config/navigation.ts

@@ -76,6 +76,11 @@ export const navigation: Navigation = {
 					href: "/docs/functions/use-element-size",
 					items: [],
 				},
+				{
+					title: "useEventListener",
+					href: "/docs/functions/use-event-listener",
+					items: [],
+				},
 			],
 		},
 	],