feat: add IsHovered

.changeset/empty-papayas-wash.md

@@ -0,0 +1,5 @@
+---
+"runed": minor
+---
+
+add `IsHovered`

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

@@ -0,0 +1,58 @@
+import { extract } from "../extract/extract.js";
+
+import type { MaybeGetter } from "$lib/internal/types.js";
+import { addEventListener } from "$lib/internal/utils/event.js";
+
+// Whether the primary input device supports hover
+function isHoverSupported() {
+	return window.matchMedia("(hover: hover)").matches;
+}
+
+// Whether the primary input device supports fine pointer accuracy
+function hasFinePointer() {
+	return window.matchMedia("(pointer: fine)").matches;
+}
+
+function canHover() {
+	return isHoverSupported() && hasFinePointer();
+}
+
+/**
+ * Tracks whether the user is hovering over the target element.
+ * @see {@link https://runed.dev/docs/utilities/is-hovered}
+ */
+export class IsHovered<T extends HTMLElement | undefined> {
+	#node: MaybeGetter<T>;
+	#target = $derived.by(() => extract(this.#node));
+	#current = $state<boolean>(false);
+
+	constructor(node: MaybeGetter<T>) {
+		this.#node = node;
+
+		const handleMouseEnter = () => {
+			this.#current = true;
+		};
+		const handleMouseLeave = () => {
+			this.#current = false;
+		};
+
+		$effect(() => {
+			if (!this.#target || !canHover()) {
+				return;
+			}
+
+			const callbacks: VoidFunction[] = [];
+
+			callbacks.push(addEventListener(this.#target, "mouseenter", handleMouseEnter));
+			callbacks.push(addEventListener(this.#target, "mouseleave", handleMouseLeave));
+
+			return () => {
+				return () => callbacks.forEach((c) => c());
+			};
+		});
+	}
+
+	get current(): boolean {
+		return this.#current;
+	}
+}

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

@@ -0,0 +1,33 @@
+import { fireEvent, render } from "@testing-library/svelte/svelte5";
+import { describe, expect, it } from "vitest";
+import TestIsHovered from "./TestIsHovered.svelte";
+
+function setup() {
+	const result = render(TestIsHovered);
+	const hoverTarget = result.getByTestId("hover-target");
+	return {
+		...result,
+		hoverTarget,
+	};
+}
+
+describe("IsHovered", () => {
+	it("should be false on initial render", () => {
+		const { hoverTarget } = setup();
+		expect(hoverTarget).toHaveTextContent("false");
+	});
+
+	it("should be true when hovered", async () => {
+		const { hoverTarget } = setup();
+		await fireEvent.mouseEnter(hoverTarget);
+		expect(hoverTarget).toHaveTextContent("true");
+	});
+
+	it("should be false when unhovered", async () => {
+		const { hoverTarget } = setup();
+		await fireEvent.mouseEnter(hoverTarget);
+		expect(hoverTarget).toHaveTextContent("true");
+		await fireEvent.mouseLeave(hoverTarget);
+		expect(hoverTarget).toHaveTextContent("false");
+	});
+});

packages/runed/src/lib/utilities/IsHovered/TestIsHovered.svelte

@@ -0,0 +1,11 @@
+<script lang="ts">
+	import { IsHovered } from "runed";
+
+	let el = $state<HTMLElement>();
+
+	const isHovered = new IsHovered(() => el);
+</script>
+
+<div data-testid="hover-target" bind:this={el}>
+	{isHovered.current ? "true" : "false"}
+</div>

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

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

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

@@ -20,3 +20,4 @@ export * from "./AnimationFrames/index.js";
 export * from "./useIntersectionObserver/index.js";
 export * from "./IsFocusWithin/index.js";
 export * from "./FiniteStateMachine/index.js";
+export * from "./IsHovered/index.js";

sites/docs/content/utilities/is-hovered.md

@@ -0,0 +1,30 @@
+---
+title: IsHovered
+description: Determine if an element is hovered.
+category: Utilities
+---
+
+<script>
+import Demo from '$lib/components/demos/is-hovered.svelte';
+</script>
+
+## Demo
+
+<Demo />
+
+## Usage
+
+```svelte
+<script lang="ts">
+	import { IsHovered } from "runed";
+
+	let el = $state<HTMLElement>();
+	const isHovered = new IsHovered(() => el);
+</script>
+
+<button bind:this={el}>
+	{!isHovered.current ? "Hover me!" : "Unhover me!"}
+</button>
+
+<p>Is hovered: <b>{isHovered.current ? "true" : "false"}</b></p>
+```

sites/docs/src/lib/components/demos/is-hovered.svelte

@@ -0,0 +1,21 @@
+<script lang="ts">
+	import { IsHovered } from "runed";
+	import Button from "../ui/button/button.svelte";
+	import DemoContainer from "$lib/components/demo-container.svelte";
+
+	let el = $state<HTMLElement>();
+
+	const isHovered = new IsHovered(() => el);
+</script>
+
+<DemoContainer>
+	<span bind:this={el}>
+		<Button variant={!isHovered.current ? "brand" : "subtle"}>
+			{!isHovered.current ? "Hover me!" : "Unhover me!"}
+		</Button>
+	</span>
+
+	<p class="mt-2">
+		Is hovered: <span class="font-bold text-brand">{isHovered.current ? "true" : "false"}</span>
+	</p>
+</DemoContainer>