fancy-ui-svelte 0.9.1 → 0.10.0

package/dist/fancy-ui/toast/Toast.test.js

@@ -0,0 +1,274 @@
+import { render, cleanup, fireEvent } from "@testing-library/svelte";
+import { afterEach, beforeEach, describe, it, expect, vi } from "vitest";
+import Toaster from "./Toaster.svelte";
+import { toast, dismissToast, toastStore } from "./store.svelte.js";
+/** The store is a module-level singleton — clear it between tests so none leak into the next. */
+function resetStore() {
+    for (const item of [...toastStore.items]) {
+        dismissToast(item.id);
+    }
+}
+function politeRegion() {
+    return document.querySelector('[aria-live="polite"]');
+}
+function assertiveRegion() {
+    return document.querySelector('[aria-live="assertive"]');
+}
+function toastPanels() {
+    return Array.from(document.querySelectorAll(".ft-toast"));
+}
+describe("Toast / Toaster", () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+    });
+    afterEach(() => {
+        cleanup();
+        resetStore();
+        document.body.innerHTML = "";
+        vi.useRealTimers();
+        vi.unstubAllGlobals();
+    });
+    it("mounts both live regions empty, before any toast exists", () => {
+        render(Toaster);
+        expect(politeRegion()).not.toBeNull();
+        expect(assertiveRegion()).not.toBeNull();
+        expect(politeRegion().textContent).toBe("");
+        expect(assertiveRegion().textContent).toBe("");
+    });
+    it("announces a success toast through the polite region only", async () => {
+        render(Toaster);
+        toast({
+            title: "Theme saved",
+            description: "CSS copied to the clipboard.",
+            variant: "success",
+        });
+        await vi.advanceTimersByTimeAsync(0);
+        expect(politeRegion().textContent).toBe("Theme saved. CSS copied to the clipboard.");
+        expect(assertiveRegion().textContent).toBe("");
+    });
+    it("announces an info toast through the polite region", async () => {
+        render(Toaster);
+        toast({ title: "Heads up", variant: "info" });
+        await vi.advanceTimersByTimeAsync(0);
+        expect(politeRegion().textContent).toBe("Heads up");
+    });
+    it("announces a loading toast through the polite region", async () => {
+        render(Toaster);
+        toast({ title: "Publishing…", variant: "loading" });
+        await vi.advanceTimersByTimeAsync(0);
+        expect(politeRegion().textContent).toBe("Publishing…");
+    });
+    it("announces an error toast through the assertive region only", async () => {
+        render(Toaster);
+        toast({ title: "Failed to send", description: "Check your connection.", variant: "error" });
+        await vi.advanceTimersByTimeAsync(0);
+        expect(assertiveRegion().textContent).toBe("Failed to send. Check your connection.");
+        expect(politeRegion().textContent).toBe("");
+    });
+    it("renders each variant with its own chrome", async () => {
+        render(Toaster);
+        toast({ title: "Saved", variant: "success" });
+        toast({ title: "Failed", variant: "error" });
+        toast({ title: "Working", variant: "loading" });
+        await vi.advanceTimersByTimeAsync(0);
+        expect(toastPanels().map((el) => el.getAttribute("data-variant"))).toEqual([
+            "success",
+            "error",
+            "loading",
+        ]);
+    });
+    it("fires the action callback without dismissing the toast", async () => {
+        const onClick = vi.fn();
+        render(Toaster);
+        toast({
+            title: "Failed to send",
+            variant: "error",
+            duration: Infinity,
+            action: { label: "Retry", onClick },
+        });
+        await vi.advanceTimersByTimeAsync(0);
+        const actionButton = toastPanels()[0].querySelector("button.ft-toast-action");
+        await fireEvent.click(actionButton);
+        expect(onClick).toHaveBeenCalledTimes(1);
+        expect(toastPanels()).toHaveLength(1);
+    });
+    it("does not auto-dismiss a toast with an action while the pointer is on it", async () => {
+        render(Toaster);
+        toast({
+            title: "Failed to send",
+            variant: "error",
+            duration: 1000,
+            action: { label: "Retry", onClick: () => { } },
+        });
+        await vi.advanceTimersByTimeAsync(0);
+        const panel = toastPanels()[0];
+        panel.dispatchEvent(new PointerEvent("pointerenter", { bubbles: true }));
+        await vi.advanceTimersByTimeAsync(5000);
+        expect(toastPanels()).toHaveLength(1);
+        panel.dispatchEvent(new PointerEvent("pointerleave", { bubbles: true }));
+        await vi.advanceTimersByTimeAsync(1000);
+        expect(toastPanels()).toHaveLength(0);
+    });
+    // The pause/resume wiring (`hovering`/`focusedWithin`/`syncTimer` in
+    // Toast.svelte) is on every toast's root unconditionally — nothing there
+    // reads `item.action`. The two tests above only ever construct toasts
+    // with an action, so on their own they'd equally pass a version of the
+    // code that gated pausing on `item.action` existing. This test is the one
+    // that actually proves the protection is unconditional, not incidental
+    // to always having tested it alongside an action.
+    it("pauses on hover even without an action — the protection isn't scoped to actionable toasts", async () => {
+        render(Toaster);
+        toast({ title: "Theme saved", variant: "success", duration: 1000 });
+        await vi.advanceTimersByTimeAsync(0);
+        const panel = toastPanels()[0];
+        expect(panel.querySelector(".ft-toast-action")).toBeNull();
+        panel.dispatchEvent(new PointerEvent("pointerenter", { bubbles: true }));
+        await vi.advanceTimersByTimeAsync(5000);
+        expect(toastPanels()).toHaveLength(1);
+        panel.dispatchEvent(new PointerEvent("pointerleave", { bubbles: true }));
+        await vi.advanceTimersByTimeAsync(1000);
+        expect(toastPanels()).toHaveLength(0);
+    });
+    it("pauses on focus within and resumes on blur, not just on hover", async () => {
+        render(Toaster);
+        toast({
+            title: "Failed to send",
+            variant: "error",
+            duration: 1000,
+            action: { label: "Retry", onClick: () => { } },
+        });
+        await vi.advanceTimersByTimeAsync(0);
+        const actionButton = toastPanels()[0].querySelector("button.ft-toast-action");
+        actionButton.focus();
+        await vi.advanceTimersByTimeAsync(5000);
+        expect(toastPanels()).toHaveLength(1);
+        actionButton.blur();
+        await vi.advanceTimersByTimeAsync(1000);
+        expect(toastPanels()).toHaveLength(0);
+    });
+    it("never auto-dismisses when duration is Infinity", async () => {
+        render(Toaster);
+        toast({ title: "Sticky", duration: Infinity });
+        await vi.advanceTimersByTimeAsync(0);
+        expect(toastPanels()).toHaveLength(1);
+        await vi.advanceTimersByTimeAsync(10_000_000);
+        expect(toastPanels()).toHaveLength(1);
+    });
+    it("defaults loading toasts to sticky", async () => {
+        render(Toaster);
+        toast({ title: "Publishing…", variant: "loading" });
+        await vi.advanceTimersByTimeAsync(0);
+        expect(toastPanels()).toHaveLength(1);
+        await vi.advanceTimersByTimeAsync(60_000);
+        expect(toastPanels()).toHaveLength(1);
+    });
+    it("dismisses programmatically by id", async () => {
+        render(Toaster);
+        const id = toast({ title: "Bye", duration: Infinity });
+        await vi.advanceTimersByTimeAsync(0);
+        expect(toastPanels()).toHaveLength(1);
+        dismissToast(id);
+        await vi.advanceTimersByTimeAsync(0);
+        expect(toastPanels()).toHaveLength(0);
+    });
+    it("dismisses via its own close button", async () => {
+        render(Toaster);
+        toast({ title: "Bye", duration: Infinity });
+        await vi.advanceTimersByTimeAsync(0);
+        const closeButton = toastPanels()[0].querySelector('button[aria-label="Dismiss"]');
+        await fireEvent.click(closeButton);
+        expect(toastPanels()).toHaveLength(0);
+    });
+    it("keeps at most 4 toasts, dismissing the oldest to make room for the newest", async () => {
+        render(Toaster);
+        toast({ title: "One", duration: Infinity });
+        toast({ title: "Two", duration: Infinity });
+        toast({ title: "Three", duration: Infinity });
+        toast({ title: "Four", duration: Infinity });
+        toast({ title: "Five", duration: Infinity });
+        await vi.advanceTimersByTimeAsync(0);
+        const panels = toastPanels();
+        expect(panels).toHaveLength(4);
+        expect(panels[0].textContent).toContain("Two");
+        expect(panels[3].textContent).toContain("Five");
+        expect(panels.some((el) => el.textContent?.includes("One"))).toBe(false);
+    });
+    it("preserves DOM identity of surviving toasts when one in the middle is dismissed", async () => {
+        render(Toaster);
+        const aId = toast({ title: "A", duration: Infinity });
+        const bId = toast({ title: "B", duration: Infinity });
+        const cId = toast({ title: "C", duration: Infinity });
+        void aId;
+        void cId;
+        await vi.advanceTimersByTimeAsync(0);
+        const [aEl, , cEl] = toastPanels();
+        dismissToast(bId);
+        await vi.advanceTimersByTimeAsync(0);
+        const remaining = toastPanels();
+        expect(remaining).toHaveLength(2);
+        expect(remaining[0]).toBe(aEl);
+        expect(remaining[1]).toBe(cEl);
+    });
+    it("tells apart two toasts with identical content by id, not position", async () => {
+        render(Toaster);
+        const firstId = toast({ title: "Same title", duration: Infinity });
+        const secondId = toast({ title: "Same title", duration: Infinity });
+        await vi.advanceTimersByTimeAsync(0);
+        expect(toastPanels()).toHaveLength(2);
+        dismissToast(firstId);
+        await vi.advanceTimersByTimeAsync(0);
+        expect(toastPanels()).toHaveLength(1);
+        expect(toastStore.items[0]?.id).toBe(secondId);
+    });
+    it("stops its live timer on unmount, without losing the toast's deadline", async () => {
+        const { unmount } = render(Toaster);
+        toast({ title: "Paused between viewports", duration: 1000 });
+        await vi.advanceTimersByTimeAsync(0);
+        expect(toastStore.items).toHaveLength(1);
+        unmount();
+        // A timer left running through this gap would have fired well before
+        // now — this proves it's genuinely stopped, not merely not-yet-due.
+        await vi.advanceTimersByTimeAsync(5000);
+        expect(toastStore.items).toHaveLength(1);
+    });
+    it("re-arms a toast a new Toaster inherits, rather than leaving it stuck forever", async () => {
+        const { unmount } = render(Toaster);
+        toast({ title: "Will resume elsewhere", duration: 1000 });
+        await vi.advanceTimersByTimeAsync(200); // 800ms left when the viewport goes away
+        expect(toastStore.items).toHaveLength(1);
+        unmount();
+        await vi.advanceTimersByTimeAsync(5000); // the gap between viewports
+        expect(toastStore.items).toHaveLength(1); // still here, still stopped
+        // A different Toaster mounts later and inherits the still-pending toast.
+        render(Toaster);
+        await vi.advanceTimersByTimeAsync(0);
+        // Its deadline was already in the past by the time anything remounted
+        // to re-arm it, so it dismisses on the very next tick rather than
+        // waiting out a fresh duration.
+        expect(toastStore.items).toHaveLength(0);
+    });
+    it("re-arms a toast to its real remaining time, not a fresh duration", async () => {
+        const { unmount } = render(Toaster);
+        toast({ title: "Resumes with what was left", duration: 2000 });
+        await vi.advanceTimersByTimeAsync(0);
+        unmount();
+        await vi.advanceTimersByTimeAsync(500); // 1500ms still owed when it comes back
+        render(Toaster);
+        await vi.advanceTimersByTimeAsync(1499);
+        expect(toastStore.items).toHaveLength(1); // not yet — this is real remaining time, not 2000ms again
+        await vi.advanceTimersByTimeAsync(1);
+        expect(toastStore.items).toHaveLength(0);
+    });
+    it("queues toasts even before any Toaster is mounted", async () => {
+        toast({ title: "Early bird", duration: Infinity });
+        render(Toaster);
+        await vi.advanceTimersByTimeAsync(0);
+        expect(toastPanels()).toHaveLength(1);
+    });
+    it("is a no-op outside the browser", () => {
+        vi.stubGlobal("window", undefined);
+        const id = toast({ title: "Server side" });
+        expect(id).toBe("");
+        expect(toastStore.items).toHaveLength(0);
+    });
+});

package/dist/fancy-ui/toast/Toaster.svelte

@@ -0,0 +1,111 @@
+<script lang="ts" module>
+	export type ToasterPosition =
+		| "top-left"
+		| "top-center"
+		| "top-right"
+		| "bottom-left"
+		| "bottom-center"
+		| "bottom-right";
+
+	export interface ToasterProps {
+		/** Corner (or edge-center) the stack anchors to. Defaults to `"bottom-right"`. */
+		position?: ToasterPosition;
+		/** Additional classes for the viewport that stacks the toasts. */
+		class?: string;
+		/** Element reference for the root node. */
+		ref?: HTMLDivElement | null;
+	}
+</script>
+
+<script lang="ts">
+	import { onDestroy, onMount } from "svelte";
+	import { cn } from "../../utils.js";
+	import { portal } from "../_internals/portal.js";
+	import { toastStore, clearAllToastTimers, rearmToastTimers } from "./store.svelte.js";
+	import type { ToastItem } from "./store.svelte.js";
+	import Toast from "./Toast.svelte";
+
+	let {
+		position = "bottom-right",
+		class: className,
+		ref = $bindable(null),
+	}: ToasterProps = $props();
+
+	// Two regions, mounted empty and never re-created — only their *content*
+	// changes. A live region created at the moment of the announcement is not
+	// reliably picked up by screen readers; existing from mount and being
+	// updated in place is what makes the announcement land. Two of them, not
+	// one, because politeness is fixed per region: `polite` must never be
+	// upgraded to `assertive` (or the reverse) by mutating the same element's
+	// aria-live attribute, which most screen readers do not pick up reliably
+	// after the region already exists.
+	let politeAnnouncement = $state("");
+	let assertiveAnnouncement = $state("");
+
+	// Ids already announced, refreshed to exactly the current stack on every
+	// run — bounded to "currently visible", rather than growing forever for
+	// the life of the page.
+	let announcedIds = new Set<string>();
+
+	function announcementText(item: ToastItem): string {
+		return item.description ? `${item.title}. ${item.description}` : item.title;
+	}
+
+	$effect(() => {
+		const current = toastStore.items;
+		for (const item of current) {
+			if (announcedIds.has(item.id)) continue;
+			if (item.variant === "error") {
+				assertiveAnnouncement = announcementText(item);
+			} else {
+				politeAnnouncement = announcementText(item);
+			}
+		}
+		announcedIds = new Set(current.map((item) => item.id));
+	});
+
+	// The other half of `onDestroy` below: a toast that was already ticking
+	// down when the *previous* `<Toaster>` unmounted has a real deadline but
+	// no live timer counting toward it (that timer was cleared, deliberately
+	// — see `clearAllToastTimers`). Re-arming on mount is what stops such a
+	// toast from being stuck on screen forever with nothing left to dismiss
+	// it — `onMount` rather than a bare call in the script body so this only
+	// ever runs in the browser, never during SSR.
+	onMount(() => {
+		rearmToastTimers();
+	});
+
+	// Stops the live timers, not the toasts or their deadlines — see
+	// `clearAllToastTimers`'s own doc comment for why unmounting isn't
+	// treated as pausing.
+	onDestroy(() => {
+		clearAllToastTimers();
+	});
+
+	const POSITION_CLASSES: Record<ToasterPosition, string> = {
+		"top-left": "top-4 left-4 items-start",
+		"top-center": "top-4 left-1/2 -translate-x-1/2 items-center",
+		"top-right": "top-4 right-4 items-end",
+		"bottom-left": "bottom-4 left-4 items-start",
+		"bottom-center": "bottom-4 left-1/2 -translate-x-1/2 items-center",
+		"bottom-right": "bottom-4 right-4 items-end",
+	};
+</script>
+
+<div bind:this={ref} class={cn("ft-toaster contents", className)} use:portal>
+	<div aria-live="polite" aria-atomic="true" class="sr-only">{politeAnnouncement}</div>
+	<div aria-live="assertive" aria-atomic="true" class="sr-only">{assertiveAnnouncement}</div>
+
+	<div
+		class={cn(
+			"ft-toaster-viewport pointer-events-none fixed z-50 flex flex-col gap-2",
+			POSITION_CLASSES[position]
+		)}
+	>
+		{#each toastStore.items as item (item.id)}
+			<div class="pointer-events-auto">
+				<Toast {item} />
+			</div>
+		{/each}
+	</div>
+</div>

package/dist/fancy-ui/toast/Toaster.svelte.d.ts

@@ -0,0 +1,12 @@
+export type ToasterPosition = "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right";
+export interface ToasterProps {
+    /** Corner (or edge-center) the stack anchors to. Defaults to `"bottom-right"`. */
+    position?: ToasterPosition;
+    /** Additional classes for the viewport that stacks the toasts. */
+    class?: string;
+    /** Element reference for the root node. */
+    ref?: HTMLDivElement | null;
+}
+declare const Toaster: import("svelte").Component<ToasterProps, {}, "ref">;
+type Toaster = ReturnType<typeof Toaster>;
+export default Toaster;

package/dist/fancy-ui/toast/index.d.ts

@@ -0,0 +1,4 @@
+import Toast, { type ToastProps } from "./Toast.svelte";
+import Toaster, { type ToasterProps, type ToasterPosition } from "./Toaster.svelte";
+import { toast, dismissToast, type ToastVariant, type ToastAction, type ToastOptions, type ToastItem } from "./store.svelte.js";
+export { Toast, type ToastProps, Toaster, type ToasterProps, type ToasterPosition, toast, dismissToast, type ToastVariant, type ToastAction, type ToastOptions, type ToastItem, };

package/dist/fancy-ui/toast/index.js

@@ -0,0 +1,4 @@
+import Toast, {} from "./Toast.svelte";
+import Toaster, {} from "./Toaster.svelte";
+import { toast, dismissToast, } from "./store.svelte.js";
+export { Toast, Toaster, toast, dismissToast, };

package/dist/fancy-ui/toast/store.svelte.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Toast store — a module-level singleton, unlike every other reactive helper
+ * in this library (which is a per-instance factory a component calls).
+ * `toast()` has to be callable from anywhere — a submit handler, a promise
+ * rejection, code with no component instance in scope at all — so there can
+ * only be one stack per app, shared by whichever `<Toaster>` is mounted.
+ *
+ * This file owns the data and the timers. `Toast.svelte` and `Toaster.svelte`
+ * only render what this exposes; they never touch `items` or the timer map
+ * directly.
+ */
+export type ToastVariant = "success" | "error" | "info" | "loading";
+export interface ToastAction {
+    /** Label for the toast's single optional action button, e.g. "Retry". */
+    label: string;
+    /** Called on activation. Does not dismiss the toast on its own — call `dismissToast` from inside if the action should also close it. */
+    onClick: () => void;
+}
+export interface ToastOptions {
+    /** Primary line. */
+    title: string;
+    /** Secondary line, shown under the title. */
+    description?: string;
+    /** Controls the icon, the accent color, and the live region's politeness. Defaults to `"info"`. */
+    variant?: ToastVariant;
+    /**
+     * Milliseconds before auto-dismiss. `Infinity` means sticky — it never
+     * auto-dismisses. Defaults to 5000, except for `variant: "loading"`, which
+     * defaults to `Infinity`: a loading toast has no natural "done" time, and
+     * auto-dismissing it after a fixed delay would misreport an operation
+     * that is still running as finished.
+     */
+    duration?: number;
+    /** A single optional action button. */
+    action?: ToastAction;
+}
+export interface ToastItem {
+    readonly id: string;
+    readonly title: string;
+    readonly description?: string;
+    readonly variant: ToastVariant;
+    readonly duration: number;
+    readonly action?: ToastAction;
+}
+/**
+ * Queues a toast and returns its id (usable with `dismissToast`). A no-op
+ * that returns `""` when called outside the browser: there is no client to
+ * show it to, and a module-level list surviving across requests on a
+ * long-lived server would leak toasts between unrelated users — the same
+ * trap `_internals/id.ts`'s `uid()` guards against for the same reason.
+ */
+export declare function toast(options: ToastOptions): string;
+/** Dismisses a toast immediately and clears its timer. Safe to call with an id that no longer exists. */
+export declare function dismissToast(id: string): void;
+/**
+ * Pauses a toast's auto-dismiss countdown — e.g. while the pointer or focus
+ * is on it — so `resumeToast` can continue it rather than restart it. A
+ * no-op for a sticky toast or one already paused (or already unarmed for
+ * some other reason, e.g. no `<Toaster>` currently mounted to run it).
+ */
+export declare function pauseToast(id: string): void;
+/**
+ * Resumes a paused toast's countdown from where it left off — the deadline
+ * shifts forward by exactly how long it spent paused, so the toast still
+ * gets the same amount of on-screen, unpaused time it was promised. A no-op
+ * if a live timer is already counting down (nothing to resume).
+ */
+export declare function resumeToast(id: string): void;
+/**
+ * Clears every pending timer's *handle* without touching the toasts or their
+ * deadlines. `<Toaster>` calls this when it unmounts. Deliberately does not
+ * touch `deadline`: unmounting isn't pausing — there is no pointer left
+ * hovering anything for a destroyed viewport, so the countdown a toast was
+ * promised keeps running in real time whether or not something is currently
+ * rendering it. `rearmToastTimers` is the other half of this: whatever a new
+ * `<Toaster>` inherits gets a live timer again, counting toward the same
+ * deadline. Also clears any stale `pausedAt` — a pause tied to a hover/focus
+ * on a now-destroyed element cannot mean anything to whatever mounts next.
+ */
+export declare function clearAllToastTimers(): void;
+/**
+ * Re-arms every timer left unarmed with nothing currently pausing it — i.e.
+ * every finite-duration toast whose previous `<Toaster>` went away before
+ * its time was up. Call this from a `<Toaster>`'s own mount: without it, a
+ * toast that outlives one viewport and is picked up by another stays
+ * visible forever with no timer ever going to dismiss it, since nothing else
+ * re-arms what `clearAllToastTimers` cleared. A deadline already in the past
+ * (the gap between viewports was longer than the time left) re-arms to a
+ * near-immediate dismiss through the same path, rather than a special case.
+ */
+export declare function rearmToastTimers(): void;
+/** Read-only view of the current toast stack, oldest first. `<Toaster>` renders this directly; nothing else should need to. */
+export declare const toastStore: {
+    readonly items: readonly ToastItem[];
+};

package/dist/fancy-ui/toast/store.svelte.js

@@ -0,0 +1,160 @@
+/**
+ * Toast store — a module-level singleton, unlike every other reactive helper
+ * in this library (which is a per-instance factory a component calls).
+ * `toast()` has to be callable from anywhere — a submit handler, a promise
+ * rejection, code with no component instance in scope at all — so there can
+ * only be one stack per app, shared by whichever `<Toaster>` is mounted.
+ *
+ * This file owns the data and the timers. `Toast.svelte` and `Toaster.svelte`
+ * only render what this exposes; they never touch `items` or the timer map
+ * directly.
+ */
+/** Toasts visible at once. Past this, the oldest is dismissed to make room for the newest. */
+const MAX_VISIBLE = 4;
+const DEFAULT_DURATION = 5000;
+let items = $state([]);
+let seq = 0;
+// Timers live outside `items` — they are bookkeeping the UI never renders,
+// not state a template reads, so there is nothing to gain from making this
+// reactive and a `Map` mutated from a `setTimeout` callback is simpler than
+// juggling `$state` for it.
+const timers = new Map();
+function clearHandle(id) {
+    const entry = timers.get(id);
+    if (entry?.handle !== undefined) {
+        clearTimeout(entry.handle);
+        entry.handle = undefined;
+    }
+}
+/** Arms (or re-arms) the live timer counting down to an entry's stored `deadline`. */
+function armHandle(id) {
+    const entry = timers.get(id);
+    if (!entry)
+        return;
+    const ms = Math.max(0, entry.deadline - Date.now());
+    entry.handle = setTimeout(() => dismissToast(id), ms);
+}
+/**
+ * Queues a toast and returns its id (usable with `dismissToast`). A no-op
+ * that returns `""` when called outside the browser: there is no client to
+ * show it to, and a module-level list surviving across requests on a
+ * long-lived server would leak toasts between unrelated users — the same
+ * trap `_internals/id.ts`'s `uid()` guards against for the same reason.
+ */
+export function toast(options) {
+    if (typeof window === "undefined") {
+        return "";
+    }
+    seq += 1;
+    const id = `toast-${seq}`;
+    const variant = options.variant ?? "info";
+    const duration = options.duration ?? (variant === "loading" ? Infinity : DEFAULT_DURATION);
+    const item = {
+        id,
+        title: options.title,
+        description: options.description,
+        variant,
+        duration,
+        action: options.action,
+    };
+    // Append-ordered, so index 0 is always the longest-standing toast — the
+    // one evicted when a new toast would push the stack past the limit.
+    const next = [...items, item];
+    if (next.length > MAX_VISIBLE) {
+        const evicted = next.shift();
+        if (evicted) {
+            clearHandle(evicted.id);
+            timers.delete(evicted.id);
+        }
+    }
+    items = next;
+    if (Number.isFinite(duration)) {
+        timers.set(id, { handle: undefined, deadline: Date.now() + duration, pausedAt: undefined });
+        armHandle(id);
+    }
+    return id;
+}
+/** Dismisses a toast immediately and clears its timer. Safe to call with an id that no longer exists. */
+export function dismissToast(id) {
+    items = items.filter((item) => item.id !== id);
+    clearHandle(id);
+    timers.delete(id);
+}
+/**
+ * Pauses a toast's auto-dismiss countdown — e.g. while the pointer or focus
+ * is on it — so `resumeToast` can continue it rather than restart it. A
+ * no-op for a sticky toast or one already paused (or already unarmed for
+ * some other reason, e.g. no `<Toaster>` currently mounted to run it).
+ */
+export function pauseToast(id) {
+    const entry = timers.get(id);
+    if (!entry || entry.handle === undefined)
+        return;
+    clearHandle(id);
+    entry.pausedAt = Date.now();
+}
+/**
+ * Resumes a paused toast's countdown from where it left off — the deadline
+ * shifts forward by exactly how long it spent paused, so the toast still
+ * gets the same amount of on-screen, unpaused time it was promised. A no-op
+ * if a live timer is already counting down (nothing to resume).
+ */
+export function resumeToast(id) {
+    const entry = timers.get(id);
+    if (!entry || entry.handle !== undefined)
+        return;
+    if (entry.pausedAt !== undefined) {
+        entry.deadline += Date.now() - entry.pausedAt;
+        entry.pausedAt = undefined;
+    }
+    if (entry.deadline <= Date.now()) {
+        dismissToast(id);
+        return;
+    }
+    armHandle(id);
+}
+/**
+ * Clears every pending timer's *handle* without touching the toasts or their
+ * deadlines. `<Toaster>` calls this when it unmounts. Deliberately does not
+ * touch `deadline`: unmounting isn't pausing — there is no pointer left
+ * hovering anything for a destroyed viewport, so the countdown a toast was
+ * promised keeps running in real time whether or not something is currently
+ * rendering it. `rearmToastTimers` is the other half of this: whatever a new
+ * `<Toaster>` inherits gets a live timer again, counting toward the same
+ * deadline. Also clears any stale `pausedAt` — a pause tied to a hover/focus
+ * on a now-destroyed element cannot mean anything to whatever mounts next.
+ */
+export function clearAllToastTimers() {
+    for (const entry of timers.values()) {
+        if (entry.handle !== undefined) {
+            clearTimeout(entry.handle);
+            entry.handle = undefined;
+        }
+        entry.pausedAt = undefined;
+    }
+}
+/**
+ * Re-arms every timer left unarmed with nothing currently pausing it — i.e.
+ * every finite-duration toast whose previous `<Toaster>` went away before
+ * its time was up. Call this from a `<Toaster>`'s own mount: without it, a
+ * toast that outlives one viewport and is picked up by another stays
+ * visible forever with no timer ever going to dismiss it, since nothing else
+ * re-arms what `clearAllToastTimers` cleared. A deadline already in the past
+ * (the gap between viewports was longer than the time left) re-arms to a
+ * near-immediate dismiss through the same path, rather than a special case.
+ */
+export function rearmToastTimers() {
+    for (const [id, entry] of timers) {
+        if (entry.handle !== undefined)
+            continue; // already counting down
+        if (entry.pausedAt !== undefined)
+            continue; // genuinely paused; resumeToast's job
+        armHandle(id);
+    }
+}
+/** Read-only view of the current toast stack, oldest first. `<Toaster>` renders this directly; nothing else should need to. */
+export const toastStore = {
+    get items() {
+        return items;
+    },
+};