Merge pull request #7 from Hugos68/feat/event-listener

Added useEventListener

.changeset/lazy-windows-help.md

@@ -0,0 +1,5 @@
+---
+"runed": patch
+---
+
+New Function: `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.svelte.js";

packages/runed/src/lib/functions/useEventListener/useEventListener.svelte.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-event-listener.md

@@ -0,0 +1,29 @@
+---
+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";
+
+	let count = $state(0);
+	function increment() {
+		count++;
+	}
+
+	useEventListener(() => document, "click", increment);
+</script>
+
+<p>You've clicked {count} {count === 1 ? "Time" : "Times"}</p>
+```

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-event-listener.svelte

@@ -0,0 +1,14 @@
+<script lang="ts">
+	import { useEventListener } from "runed";
+
+	let count = $state(0);
+	function increment() {
+		count++;
+	}
+
+	useEventListener(() => document, "click", increment);
+</script>
+
+<div class="select-none 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: [],
+				},
 			],
 		},
 	],