feat: onClickOutside

.changeset/bright-rabbits-obey.md

@@ -0,0 +1,5 @@
+---
+"runed": minor
+---
+
+feat: `useClickOutside`

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

@@ -1,4 +1,5 @@
 export * from "./activeElement/index.js";
+export * from "./useClickOutside/index.js";
 export * from "./useDebounce/index.js";
 export * from "./ElementSize/index.js";
 export * from "./useEventListener/index.js";

packages/runed/src/lib/utilities/useClickOutside/index.ts

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

packages/runed/src/lib/utilities/useClickOutside/useClickOutside.svelte.ts

@@ -0,0 +1,54 @@
+import type { MaybeGetter } from "../../internal/types.js";
+import { watch } from "../watch/watch.svelte.js";
+import { extract } from "../extract/extract.js";
+
+type ClickOutside = {
+	start: () => void;
+	stop: () => void;
+};
+
+/**
+ * Accepts a box which holds a container element and callback function.
+ * Invokes the callback function when the user clicks outside of the
+ * container.
+ *
+ * @returns an object with start and stop functions
+ *
+ * @see {@link https://runed.dev/docs/functions/use-click-outside}
+ */
+export function useClickOutside<T extends Element>(
+	container: MaybeGetter<T | undefined>,
+	callback: () => void
+): ClickOutside {
+	let isEnabled = $state<boolean>(true);
+	const el = $derived<T | undefined>(extract(container));
+
+	function start() {
+		isEnabled = true;
+	}
+
+	function stop() {
+		isEnabled = false;
+	}
+
+	function handleClick(event: MouseEvent) {
+		if (event.target && !el?.contains(event.target as Node)) {
+			callback();
+		}
+	}
+
+	watch([() => el, () => isEnabled], ([currentEl, currentIsEnabled]) => {
+		if (currentEl && currentIsEnabled) {
+			window.addEventListener("click", handleClick);
+		}
+
+		return () => {
+			window.removeEventListener("click", handleClick);
+		};
+	});
+
+	return {
+		start,
+		stop,
+	};
+}

packages/runed/src/lib/utilities/useClickOutside/useClickOutside.test.svelte.ts

@@ -0,0 +1,54 @@
+import { describe, expect, vi } from "vitest";
+import { tick } from "svelte";
+import { useClickOutside } from "./useClickOutside.svelte.js";
+import { testWithEffect } from "$lib/test/util.svelte.js";
+
+describe("useClickOutside", () => {
+	testWithEffect("calls a given callback on an outside of container click", async () => {
+		const container = document.createElement("div");
+		const innerButton = document.createElement("button");
+		const button = document.createElement("button");
+
+		document.body.appendChild(container);
+		document.body.appendChild(button);
+		container.appendChild(innerButton);
+
+		const callbackFn = vi.fn();
+
+		useClickOutside(() => container, callbackFn);
+		await tick();
+
+		button.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+		expect(callbackFn).toHaveBeenCalledOnce();
+
+		innerButton.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+		expect(callbackFn).toHaveBeenCalledOnce();
+
+		container.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+		expect(callbackFn).toHaveBeenCalledOnce();
+	});
+
+	testWithEffect("can be paused and resumed", async () => {
+		const container = document.createElement("div");
+		const button = document.createElement("button");
+
+		document.body.appendChild(container);
+		document.body.appendChild(button);
+
+		const callbackFn = vi.fn();
+
+		const clickOutside = useClickOutside(() => container, callbackFn);
+
+		clickOutside.stop();
+		await tick();
+
+		button.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+		expect(callbackFn).not.toHaveBeenCalled();
+
+		clickOutside.start();
+		await tick();
+
+		button.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+		expect(callbackFn).toHaveBeenCalledOnce();
+	});
+});

sites/docs/content/utilities/use-click-outside.md

@@ -0,0 +1,61 @@
+---
+title: useClickOutside
+description:
+  A function that calls a callback when a click event is triggered outside of a given container
+  element.
+category: Browser
+---
+
+<script>
+import Demo from '$lib/components/demos/use-click-outside.svelte';
+</script>
+
+## Demo
+
+<Demo />
+
+## Usage
+
+```svelte
+<script lang="ts">
+	import { useClickOutside } from "runed";
+
+	let el = $state<HTMLDivElement | undefined>(undefined);
+
+	useClickOutside(
+		() => el,
+		() => {
+			console.log("clicked outside of container");
+		}
+	);
+</script>
+
+<main>
+	<div bind:this={el}>Container</div>
+	<button>Click Me</button>
+</main>
+```
+
+You can also programmatically pause and resume `useClickOutside` using the `start` and `stop`
+functiosn returned by `useClickOutside`.
+
+```svelte
+<script lang="ts">
+	import { useClickOutside } from "runed";
+
+	let el = $state<HTMLDivElement | undefined>(undefined);
+
+	const outsideClick = useClickOutside(
+		() => el,
+		() => {
+			console.log("clicked outside of container");
+		}
+	);
+</script>
+
+<main>
+	<button onclick={outsideClick.stop}>Stop listening for outside clicks</button>
+	<button onclick={outsideClick.start}>Start listening again</button>
+	<div bind:this={el}></div>
+</main>
+```

sites/docs/src/lib/components/demos/use-click-outside.svelte

@@ -0,0 +1,37 @@
+<script lang="ts">
+	import { useClickOutside } from "runed";
+
+	let containerText = $state("Has not clicked yet");
+	let el = $state<HTMLDivElement | undefined>(undefined);
+
+	useClickOutside(
+		() => el,
+		() => {
+			containerText = "Has clicked outside of container";
+		}
+	);
+</script>
+
+<main>
+	<div bind:this={el}>
+		<p>{containerText}</p>
+
+		<button onclick={() => (containerText = "Has clicked within container")}>
+			Button within container
+		</button>
+	</div>
+	<button>Button outside container</button>
+</main>
+
+<style>
+	div {
+		padding: 40px;
+		border: 1px solid;
+		margin-bottom: 16px;
+	}
+
+	button {
+		border: 1px solid;
+		padding-inline: 8px;
+	}
+</style>