From de37f2ab852c4bd16f1833fc5a6c97bb2b25284c Mon Sep 17 00:00:00 2001
From: oppiliappan <me@oppi.li>
Date: Wed, 12 Aug 2026 10:02:27 +0100
Subject: [PATCH] web/components/ui: add generic Hovercard component

---
 .../components/ui/Hovercard.stories.svelte    |  49 +++++
 web/src/lib/components/ui/Hovercard.svelte    | 206 ++++++++++++++++++
 2 files changed, 255 insertions(+)
 create mode 100644 web/src/lib/components/ui/Hovercard.stories.svelte
 create mode 100644 web/src/lib/components/ui/Hovercard.svelte

diff --git a/web/src/lib/components/ui/Hovercard.stories.svelte b/web/src/lib/components/ui/Hovercard.stories.svelte
new file mode 100644
index 00000000..2c82b019
--- /dev/null
+++ b/web/src/lib/components/ui/Hovercard.stories.svelte
@@ -0,0 +1,49 @@
+<script module lang="ts">
+	import { defineMeta } from "@storybook/addon-svelte-csf";
+	import Hovercard from "./Hovercard.svelte";
+	import Button from "./Button.svelte";
+
+	// generic hover-triggered card. the trigger goes in the default slot, the card body
+	// in the `content` snippet; `onOpen` fires when it opens (lazy-load content there).
+	const { Story } = defineMeta({
+		title: "UI/Hovercard",
+		component: Hovercard,
+		tags: ["autodocs"]
+	});
+</script>
+
+{#snippet card()}
+	<div class="w-64 p-3">
+		<p class="font-semibold">Rich content</p>
+		<p class="text-sm text-foreground-subtle">
+			Any markup can live in the card — it stays open while you move the pointer into it.
+		</p>
+	</div>
+{/snippet}
+
+<!-- hover the trigger; the card hangs below and flips up near the viewport edge -->
+<Story name="Default" asChild>
+	<div class="flex justify-center p-24">
+		<Hovercard content={card}>
+			<Button>Hover me</Button>
+		</Hovercard>
+	</div>
+</Story>
+
+<!-- opens instantly, no hover delay -->
+<Story name="No delay" asChild>
+	<div class="flex justify-center p-24">
+		<Hovercard content={card} openDelay={0}>
+			<Button>Instant</Button>
+		</Hovercard>
+	</div>
+</Story>
+
+<!-- disabled skips the card without changing the markup around the trigger -->
+<Story name="Disabled" asChild>
+	<div class="flex justify-center p-24">
+		<Hovercard content={card} disabled>
+			<Button>No card</Button>
+		</Hovercard>
+	</div>
+</Story>
diff --git a/web/src/lib/components/ui/Hovercard.svelte b/web/src/lib/components/ui/Hovercard.svelte
new file mode 100644
index 00000000..ba65a5a5
--- /dev/null
+++ b/web/src/lib/components/ui/Hovercard.svelte
@@ -0,0 +1,206 @@
+<script module lang="ts">
+	import { tv } from "tailwind-variants";
+
+	export const hovercard = tv({
+		slots: {
+			// the wrapper is the anchor: inline-flex so it hugs the trigger and the card
+			// lines up with it rather than with a full-width box
+			wrapper: "inline-flex",
+			// overflow-visible so the card's own content (e.g. a nested popover) isn't clipped
+			card: "hovercard-card fixed z-50 m-0 overflow-visible rounded-sm border border-border-default bg-background-default text-foreground-default shadow-regular"
+		}
+	});
+
+	// hovering a second trigger should swap cards, not stack them. native popover="hint"
+	// would do this for us but isn't widely supported yet, so keep a module-level
+	// singleton the way Tooltip and Dropdown do.
+	let openCard: (() => void) | undefined;
+</script>
+
+<script lang="ts">
+	import type { Snippet } from "svelte";
+	import { onMount } from "svelte";
+
+	interface Props {
+		// the trigger — an avatar, a name, anything
+		children: Snippet;
+		// the card body, rendered inside the popover
+		content: Snippet;
+		// ms to wait on hover before opening
+		openDelay?: number;
+		// ms to wait before closing, bridging the gap so the pointer can reach the card
+		closeDelay?: number;
+		// skip the card entirely — handy where a hovercard would only be noise
+		disabled?: boolean;
+		// wrapper (anchor) class
+		class?: string;
+		// extends the card's own classes, e.g. width and padding
+		cardClass?: string;
+		// fired when the card opens; a good place to lazily load its content
+		onOpen?: () => void;
+	}
+
+	let {
+		children,
+		content,
+		openDelay = 500,
+		closeDelay = 150,
+		disabled = false,
+		class: className,
+		cardClass,
+		onOpen
+	}: Props = $props();
+
+	const classes = hovercard();
+
+	let wrapperEl = $state<HTMLElement>();
+	let cardEl = $state<HTMLElement>();
+
+	const uid = $props.id();
+	const cardId = `hovercard-${uid}`;
+	// anchor-name must be a unique custom ident per instance, so derive it from the id
+	const anchorName = `--hovercard-${uid.replace(/[^a-zA-Z0-9_-]/g, "-")}`;
+
+	let openTimer: ReturnType<typeof setTimeout> | undefined;
+	let closeTimer: ReturnType<typeof setTimeout> | undefined;
+	let open = $state(false);
+
+	const clearTimers = () => {
+		clearTimeout(openTimer);
+		clearTimeout(closeTimer);
+		openTimer = closeTimer = undefined;
+	};
+
+	const show = () => {
+		clearTimers();
+		if (openCard && openCard !== hide) openCard();
+		openCard = hide;
+		// showPopover throws if already open, which the hover bridge can retrigger
+		if (cardEl && !cardEl.matches(":popover-open")) cardEl.showPopover();
+	};
+
+	const hide = () => {
+		clearTimers();
+		if (!cardEl?.matches(":popover-open")) return;
+		// keep the card up while a nested popover (e.g. a modal launched from it) is open,
+		// otherwise clicking into it from the card would dismiss the card out from under it
+		if (cardEl.querySelector(":popover-open")) return;
+		if (openCard === hide) openCard = undefined;
+		cardEl.hidePopover();
+	};
+
+	const scheduleShow = (event: PointerEvent) => {
+		// touch has no hover; a tap would open the card and swallow the tap's own action
+		if (disabled || event.pointerType === "touch") return;
+		clearTimeout(closeTimer);
+		openTimer = setTimeout(show, openDelay);
+	};
+
+	const scheduleHide = () => {
+		clearTimeout(openTimer);
+		closeTimer = setTimeout(hide, closeDelay);
+	};
+
+	const keepOpen = () => clearTimeout(closeTimer);
+
+	const onToggle = (event: Event) => {
+		const isOpen = (event as ToggleEvent).newState === "open";
+		open = isOpen;
+		if (isOpen) onOpen?.();
+		else if (openCard === hide) openCard = undefined;
+	};
+
+	onMount(() => {
+		const wrapper = wrapperEl;
+		const cardNode = cardEl;
+		if (!wrapper) return;
+
+		// handlers live here rather than in the markup: a span carrying pointer handlers
+		// has no honest ARIA role for the a11y lint, and pointerenter/leave fire on the
+		// wrapper's own boundary, which encloses whatever trigger the caller passed
+		wrapper.addEventListener("pointerenter", scheduleShow);
+		wrapper.addEventListener("pointerleave", scheduleHide);
+		cardNode?.addEventListener("pointerenter", keepOpen);
+		cardNode?.addEventListener("pointerleave", scheduleHide);
+
+		return () => {
+			wrapper.removeEventListener("pointerenter", scheduleShow);
+			wrapper.removeEventListener("pointerleave", scheduleHide);
+			cardNode?.removeEventListener("pointerenter", keepOpen);
+			cardNode?.removeEventListener("pointerleave", scheduleHide);
+			clearTimers();
+			if (openCard === hide) openCard = undefined;
+		};
+	});
+
+	$effect(() => {
+		if (disabled) hide();
+	});
+
+	$effect(() => {
+		if (!open) return;
+		const onKeydown = (event: KeyboardEvent) => {
+			if (event.key === "Escape") hide();
+		};
+		document.addEventListener("keydown", onKeydown);
+		return () => document.removeEventListener("keydown", onKeydown);
+	});
+</script>
+
+<span
+	bind:this={wrapperEl}
+	class={classes.wrapper({ class: className })}
+	style="anchor-name: {anchorName}"
+>
+	{@render children()}
+</span>
+
+{#if !disabled}
+	<div
+		bind:this={cardEl}
+		id={cardId}
+		popover="manual"
+		style="position-anchor: {anchorName}"
+		class={classes.card({ class: cardClass })}
+		ontoggle={onToggle}
+	>
+		{@render content()}
+	</div>
+{/if}
+
+<style>
+	/* anchor positioning went Baseline in early 2026; without it the card falls back to
+	   the UA's centred position, the same trade-off Tooltip and Dropdown take. the card
+	   hangs below the trigger, left edges aligned, and flips up near the bottom. */
+	@supports (position-area: bottom) and (position-try: flip-block) {
+		.hovercard-card {
+			margin-block: 0.375rem;
+			position-area: block-end span-inline-end;
+			position-try: flip-block, flip-inline;
+		}
+	}
+
+	.hovercard-card {
+		opacity: 0;
+		transition:
+			opacity 120ms ease-out,
+			overlay 120ms allow-discrete,
+			display 120ms allow-discrete;
+	}
+
+	.hovercard-card:popover-open {
+		opacity: 1;
+	}
+
+	@starting-style {
+		.hovercard-card:popover-open {
+			opacity: 0;
+		}
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.hovercard-card {
+			transition: none;
+		}
+	}
+</style>
-- 
2.51.2