Add Toaster builder

.changeset/angry-buttons-develop.md

@@ -0,0 +1,5 @@
+---
+"melt": minor
+---
+
+feat: add toasts

docs/src/components/preview.svelte

@@ -114,7 +114,17 @@
 					{:else if control.type === "number"}
 						<input
 							type="number"
-							bind:value={values[key] as number}
+							bind:value={() => values[key] as number,
+							(v: number) => {
+								// Make sure that inputed values don't go outside the specified min/max values.
+								if (control.min && v < control.min) {
+									values[key] = control.min;
+								} else if (control.max && v > control.max) {
+									values[key] = control.max;
+								} else {
+									values[key] = v;
+								}
+							}}
 							min={control.min}
 							max={control.max}
 							class="self-stretch rounded-md px-1 py-0.5 dark:bg-gray-900"

docs/src/content/docs/components/toaster.mdx

@@ -0,0 +1,92 @@
+---
+title: Toaster
+description: A succinct message that is displayed temporarily.
+---
+import ApiTable from "@components/api-table.astro";
+import Preview from "@previews/toaster.svelte";
+import Features from "@components/features.astro";
+import ThemedCode from "@components/themed-code.astro";
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+<Preview client:load />
+
+
+## Features
+
+<Features>
+	- 🕐 Automatically closes
+	- ⏯️ Pause closing on hover (single, all, none)
+</Features>
+
+## Usage
+
+Unlike most builders, the toast is not component-based. Instead, it provides a global functionality that can be accessed from anywhere in your application. To accomplish this, it is recommended that you create a global component that is called on the root of your application.
+
+The first step is to create a `Toaster` component that will be used to render toast notifications. We can take advantage of [Svelte context module](https://svelte.dev/docs/svelte/svelte-files#script-module) to create the template for the toast notifications and expose the helper function so it can be used in other components.
+
+```svelte
+<script lang="ts" module>
+	// Define your toast data.
+	type ToastData = {
+		title: string;
+		description: string;
+	};
+
+	const toaster = new Toaster<ToastData>();
+
+	export const addToast = toaster.addToast;
+</script>
+
+<script lang="ts">
+	import { Toaster } from "melt/builders";
+</script>
+
+<div {...toaster.root}>
+	{#each toaster.toasts as t (t.id)}
+		{@const toast = toaster.getToastFromToaster(t)}
+
+		<div {...toast.content}>
+			<h3 {...toast.title}>{toast.data.title}</h3>
+			<div {...toast.description}>{toast.data.description}</div>
+			<button {...toast.close} aria-label="dismiss alert">X</button>
+		</div>
+	{/each}
+</div>
+```
+
+This component should be added to your root `+layout.svelte` or `App.svelte` component.
+
+```svelte
+<script>
+	import Toaster from '$lib/Toaster.svelte'
+
+	let { children } = $props();
+</script>
+
+<Toaster />
+
+{@render children()}
+```
+
+Finally, you can use the exported `addToast` helper function to add a toast from any component of the application.
+
+```svelte
+<script lang="ts">
+	import { addToast } from '$lib/Toaster.svelte'
+
+	function onclick() {
+		addToast({
+			data: {
+				title: 'Success',
+				description: 'The resource was created!'
+			}
+		})
+	}
+</script>
+
+<button {onclick}>Create</button>
+```
+
+## API Reference
+
+<ApiTable entry="Toaster" />

docs/src/previews/toaster.svelte

@@ -0,0 +1,128 @@
+<script lang="ts">
+	import { flip } from "svelte/animate";
+	import { fly } from "svelte/transition";
+	import { usePreviewControls } from "@components/preview-ctx.svelte";
+	import Preview from "@components/preview.svelte";
+	import { Progress, Toaster, getters } from "melt/builders";
+	import Close from "~icons/material-symbols/close-rounded";
+
+	const controls = usePreviewControls({
+		hover: {
+			type: "select",
+			label: "Hover",
+			options: ["pause", "pause-all"],
+			defaultValue: "pause",
+		},
+		closeDelay: {
+			type: "number",
+			min: 0,
+			max: 10000,
+			defaultValue: 5000,
+			label: "Close Delay",
+		},
+	});
+
+	type ToastData = {
+		title: string;
+		description: string;
+		color: string;
+		shadow: string;
+	};
+
+	const toastData: ToastData[] = [
+		{
+			title: "Success",
+			description: "Congratulations! It worked!",
+			color: "bg-green-500",
+			shadow: "shadow-green-500/50",
+		},
+		{
+			title: "Warning",
+			description: "Please check again.",
+			color: "bg-orange-500",
+			shadow: "shadow-orange-500/50",
+		},
+		{
+			title: "Error",
+			description: "Something did not work!",
+			color: "bg-red-500",
+			shadow: "shadow-red-500/50",
+		},
+	];
+
+	const toaster = new Toaster<ToastData>({
+		...getters(controls),
+	});
+
+	function addRandomToast() {
+		toaster.addToast({
+			data: toastData[Math.floor(Math.random() * toastData.length)],
+		});
+	}
+</script>
+
+<Preview class="text-center">
+	<button
+		class="mx-auto block rounded-xl bg-gray-100 px-4 py-2 text-gray-800
+				transition-all hover:cursor-pointer hover:bg-gray-200
+				active:bg-gray-300 disabled:cursor-not-allowed disabled:bg-gray-100 disabled:opacity-50
+				dark:bg-gray-800 dark:text-gray-200 dark:hover:bg-gray-500/50 dark:active:bg-gray-600/50"
+		on:click={addRandomToast}
+	>
+		Show toast
+	</button>
+
+	<div {...toaster.root}>
+		<div
+			class="fixed right-0 top-0 m-4 flex flex-col items-end gap-4 text-left md:bottom-0 md:top-auto"
+		>
+			{#each toaster.toasts as t (t.id)}
+				{@const toast = toaster.getToastFromToaster(t)}
+				{@const progress = new Progress({ value: () => toast.percentage })}
+
+				<div
+					{...toast.content}
+					animate:flip={{ duration: 500 }}
+					in:fly={{ duration: 150, x: "100%" }}
+					out:fly={{ duration: 150, x: "100%" }}
+					class="{toast.data.shadow} rounded-lg bg-white shadow-md dark:bg-gray-800"
+				>
+					<div class="relative w-[24rem] max-w-[calc(100vw-2rem)] gap-4 p-5">
+						<div>
+							<h3 {...toast.title} class="flex items-center gap-2 !text-base font-semibold">
+								{toast.data.title}
+								<span class="size-1.5 rounded-full {toast.data.color}"></span>
+							</h3>
+
+							<div {...toast.description} class="!m-0 text-base">
+								{toast.data.description}
+							</div>
+						</div>
+
+						<button
+							{...toast.close}
+							aria-label="dismiss alert"
+							class="text-accent-500 dark:text-accent-300 absolute right-4 top-4 !m-0 grid size-10 cursor-pointer place-items-center rounded-full hover:bg-gray-300/50 dark:bg-gray-800 dark:hover:bg-gray-500/50"
+						>
+							<Close />
+						</button>
+
+						{#if toast.closeDelay !== 0}
+							<div class="absolute bottom-1 right-auto">
+								<div
+									{...progress.root}
+									class="relative h-1.5 w-[20rem] overflow-hidden rounded-full bg-white"
+								>
+									<div
+										{...progress.progress}
+										class="h-full w-full translate-x-[var(--progress)] rounded-r-full bg-neutral-700"
+									></div>
+								</div>
+							</div>
+						{/if}
+					</div>
+				</div>
+			{/each}
+		</div>
+	</div>
+</Preview>