@varialkit/toast 0.1.0

package/docs.md

@@ -0,0 +1,68 @@
+# Toast
+
+Toast provides lightweight notification messaging with optional actions and animated stacking.
+
+## Setup
+
+Wrap your application with `ToastProvider` so child components can enqueue notifications.
+
+```tsx
+import { ToastProvider } from "@solara/toast";
+
+export function App() {
+  return (
+    <ToastProvider dismissDuration={5000}>
+      {/* app content */}
+    </ToastProvider>
+  );
+}
+```
+
+## Usage
+
+Use the convenience hook for common variants:
+
+```tsx
+import { useToast } from "@solara/toast/use-toast";
+
+export function SaveButton() {
+  const { success, error } = useToast();
+
+  return (
+    <button
+      type="button"
+      onClick={() => success("Saved", "Your changes are live.")}
+    >
+      Save
+    </button>
+  );
+}
+```
+
+## API Notes
+
+- `ToastProvider` controls default dismissal timing with `dismissDuration`.
+- `useToast` (low-level) exposes `addToast`, `dismissToast`, and the current `toasts` list.
+- Toasts support `variant`, `duration`, `direction`, `action`, and optional `icon`.
+
+## Icons
+
+You can provide an icon name or full icon props. Use `showIcon={false}` to hide it.
+Icons inherit the toast text color.
+
+```tsx
+toast({
+  title: "Saved",
+  description: "Your changes are live.",
+  iconName: "data_spreadsheet_search_24",
+});
+```
+
+## Tokens Used
+
+The toast styles rely on `@solara/styles` tokens for spacing, typography, colors, elevation, and radius:
+
+- `--space-*`, `--spacing-multiplier`
+- `--font-body`, `--font-size-caption-scaled`, `--line-height-caption-scaled`
+- `--color-surface-*`, `--color-text-*`, `--color-divider-*`
+- `--elevation-*`, `--radius-*`

package/examples.tsx

@@ -0,0 +1,534 @@
+import React from "react";
+import { iconNames } from "@solara/icons";
+import type { SolaraIconName } from "@solara/icons";
+import { ToastProvider } from "./src/Toast";
+import { useToast as useToastConvenience } from "./src/use-toast";
+import { useToast as useToastContext } from "./src/useToast";
+import type { ToastVariant } from "./src/Toast.types";
+
+const panelStyle: React.CSSProperties = {
+  display: "flex",
+  flexDirection: "column",
+  gap: "1rem",
+  padding: "1.5rem",
+  borderRadius: "12px",
+  border: "1px solid var(--color-divider-secondary)",
+  background: "var(--color-surface-0)",
+  fontFamily: "var(--font-body)",
+};
+
+const buttonStyle: React.CSSProperties = {
+  padding: "0.5rem 0.85rem",
+  borderRadius: "999px",
+  border: "1px solid var(--color-divider-primary)",
+  background: "var(--color-surface-0)",
+  color: "var(--color-text-primary)",
+  fontFamily: "var(--font-body)",
+  fontSize: "0.875rem",
+  cursor: "pointer",
+};
+
+const PrimaryButton = ({ label, onClick }: { label: string; onClick: () => void }) => (
+  <button type="button" onClick={onClick} style={buttonStyle}>
+    {label}
+  </button>
+);
+
+const ToastPlayground = ({
+  title,
+  description,
+  variant,
+  duration,
+  direction,
+  withAction,
+  iconName,
+  showIcon,
+}: {
+  title: string;
+  description?: string;
+  variant?: ToastVariant;
+  duration?: number;
+  direction?: "left" | "right";
+  withAction?: boolean;
+  iconName?: SolaraIconName | "";
+  showIcon?: boolean;
+}) => {
+  const { toast } = useToastConvenience();
+
+  return (
+    <div style={panelStyle}>
+      <div>
+        <strong style={{ color: "var(--color-text-primary)" }}>Toast Playground</strong>
+        <p style={{ color: "var(--color-text-secondary)", margin: "0.5rem 0 0" }}>
+          Trigger a toast using the controls on the right panel.
+        </p>
+      </div>
+      <PrimaryButton
+        label="Show Toast"
+        onClick={() =>
+          toast({
+            title,
+            description,
+            variant,
+            duration,
+            direction,
+            iconName: iconName || undefined,
+            showIcon,
+            action: withAction
+              ? {
+                  label: "Undo",
+                  onClick: () => {
+                    console.log("Toast action clicked");
+                  },
+                }
+              : undefined,
+          })
+        }
+      />
+    </div>
+  );
+};
+
+const ToastVariants = () => {
+  const { toast } = useToastConvenience();
+
+  return (
+    <div style={{ ...panelStyle, flexDirection: "row", flexWrap: "wrap" }}>
+      <PrimaryButton
+        label="Success"
+        onClick={() =>
+          toast({
+            title: "Success",
+            description: "Changes saved.",
+            variant: "success",
+            iconName: "arrow_line_up_16",
+          })
+        }
+      />
+      <PrimaryButton
+        label="Error"
+        onClick={() =>
+          toast({
+            title: "Error",
+            description: "Something went wrong.",
+            variant: "destructive",
+            iconName: "arrow_swap_16",
+          })
+        }
+      />
+      <PrimaryButton
+        label="Warning"
+        onClick={() =>
+          toast({
+            title: "Warning",
+            description: "Check your inputs.",
+            variant: "warning",
+            iconName: "arrow_chevron_down_16",
+          })
+        }
+      />
+      <PrimaryButton
+        label="Info"
+        onClick={() =>
+          toast({
+            title: "Info",
+            description: "Update available.",
+            variant: "info",
+            iconName: "data_spreadsheet_search_24",
+          })
+        }
+      />
+    </div>
+  );
+};
+
+const ToastWithAction = () => {
+  const { toast } = useToastConvenience();
+
+  return (
+    <div style={panelStyle}>
+      <PrimaryButton
+        label="Show Action Toast"
+        onClick={() =>
+          toast({
+            title: "Message sent",
+            description: "Your update is live.",
+            variant: "success",
+            action: {
+              label: "Undo",
+              onClick: () => {
+                console.log("Undo");
+              },
+            },
+          })
+        }
+      />
+    </div>
+  );
+};
+
+const ToastWithDismiss = () => {
+  const { toast } = useToastConvenience();
+
+  return (
+    <div style={panelStyle}>
+      <PrimaryButton
+        label="Show Dismissible Toast"
+        onClick={() =>
+          toast({
+            title: "Dismissible Toast",
+            description: "This toast can be dismissed.",
+            variant: "info",
+            duration: 10000, // Set a longer duration for dismissible toast
+          })
+        }
+      />
+    </div>
+  );
+};
+
+const ToastStacking = () => {
+  const { addToast } = useToastContext();
+
+  return (
+    <div style={panelStyle}>
+      <PrimaryButton
+        label="Queue 6 Toasts"
+        onClick={() => {
+          Array.from({ length: 6 }).forEach((_, index) => {
+            addToast({
+              title: `Toast ${index + 1}`,
+              description: "Stacking demo",
+              variant: index % 2 === 0 ? "info" : "default",
+            });
+          });
+        }}
+      />
+    </div>
+  );
+};
+
+export const stories = {
+  playground: {
+    title: "Playground",
+    description: "Customize the toast and trigger it on demand.",
+    render: (props: {
+      title: string;
+      description?: string;
+      variant?: ToastVariant;
+      duration?: number;
+      direction?: "left" | "right";
+      withAction?: boolean;
+      iconName?: SolaraIconName | "";
+      showIcon?: boolean;
+    }) => (
+      <ToastProvider>
+        <ToastPlayground {...props} />
+      </ToastProvider>
+    ),
+    controls: [
+      { name: "title", type: "text" },
+      { name: "description", type: "text" },
+      {
+        name: "variant",
+        type: "select",
+        options: ["default", "success", "destructive", "warning", "info"],
+      },
+      { name: "duration", type: "number", min: 1000, max: 10000, step: 500 },
+      { name: "direction", type: "select", options: ["right", "left"] },
+      { name: "withAction", type: "boolean" },
+      { name: "showIcon", type: "boolean" },
+      { name: "iconName", type: "select", options: ["", ...iconNames] },
+    ],
+    initialProps: {
+      title: "Update saved",
+      description: "Your changes have been published.",
+      variant: "success",
+      duration: 5000,
+      direction: "right",
+      withAction: false,
+      showIcon: false,
+      iconName: "",
+    },
+  },
+  variants: {
+    title: "Variants",
+    description: "Common toast variants for state feedback.",
+    showProps: false,
+    render: () => (
+      <ToastProvider>
+        <ToastVariants />
+      </ToastProvider>
+    ),
+    code: `import React from "react";
+import { ToastProvider } from "@solara/toast";
+import { useToast } from "@solara/toast";
+
+const buttonStyle: React.CSSProperties = {
+  padding: "0.5rem 0.85rem",
+  borderRadius: "999px",
+  border: "1px solid var(--color-divider-primary)",
+  background: "var(--color-surface-0)",
+  color: "var(--color-text-primary)",
+  fontFamily: "var(--font-body)",
+  fontSize: "0.875rem",
+  cursor: "pointer",
+};
+
+const PrimaryButton = ({ label, onClick }: { label: string; onClick: () => void }) => (
+  <button type="button" onClick={onClick} style={buttonStyle}>
+    {label}
+  </button>
+);
+
+const ToastVariants = () => {
+  const { toast } = useToast();
+
+  return (
+    <div style={{ display: "flex", flexDirection: "row", flexWrap: "wrap", gap: "1rem" }}>
+      <PrimaryButton
+        label="Success"
+        onClick={() =>
+          toast({
+            title: "Success",
+            description: "Changes saved.",
+            variant: "success",
+            iconName: "arrow_line_up_16",
+          })
+        }
+      />
+      <PrimaryButton
+        label="Error"
+        onClick={() =>
+          toast({
+            title: "Error",
+            description: "Something went wrong.",
+            variant: "destructive",
+            iconName: "arrow_swap_16",
+          })
+        }
+      />
+      <PrimaryButton
+        label="Warning"
+        onClick={() =>
+          toast({
+            title: "Warning",
+            description: "Check your inputs.",
+            variant: "warning",
+            iconName: "arrow_chevron_down_16",
+          })
+        }
+      />
+      <PrimaryButton
+        label="Info"
+        onClick={() =>
+          toast({
+            title: "Info",
+            description: "Update available.",
+            variant: "info",
+            iconName: "data_spreadsheet_search_24",
+          })
+        }
+      />
+    </div>
+  );
+};
+
+export function Example() {
+  return (
+    <ToastProvider>
+      <ToastVariants />
+    </ToastProvider>
+  );
+}
+`,
+  },
+  withAction: {
+    title: "With Action",
+    description: "Include an optional inline action button.",
+    showProps: false,
+    render: () => (
+      <ToastProvider>
+        <ToastWithAction />
+      </ToastProvider>
+    ),
+    code: `import React from "react";
+import { ToastProvider } from "@solara/toast";
+import { useToast } from "@solara/toast";
+
+const buttonStyle: React.CSSProperties = {
+  padding: "0.5rem 0.85rem",
+  borderRadius: "999px",
+  border: "1px solid var(--color-divider-primary)",
+  background: "var(--color-surface-0)",
+  color: "var(--color-text-primary)",
+  fontFamily: "var(--font-body)",
+  fontSize: "0.875rem",
+  cursor: "pointer",
+};
+
+const PrimaryButton = ({ label, onClick }: { label: string; onClick: () => void }) => (
+  <button type="button" onClick={onClick} style={buttonStyle}>
+    {label}
+  </button>
+);
+
+const ToastWithAction = () => {
+  const { toast } = useToast();
+
+  return (
+    <div>
+      <PrimaryButton
+        label="Show Action Toast"
+        onClick={() =>
+          toast({
+            title: "Message sent",
+            description: "Your update is live.",
+            variant: "success",
+            action: {
+              label: "Undo",
+              onClick: () => {
+                console.log("Undo");
+              },
+            },
+          })
+        }
+      />
+    </div>
+  );
+};
+
+export function Example() {
+  return (
+    <ToastProvider>
+      <ToastWithAction />
+    </ToastProvider>
+  );
+}
+`,
+  },
+  stacking: {
+      title: "ToastContainer behavior",
+      description: "Queue more than five toasts to preview stacking limits.",
+    showProps: false,
+    render: () => (
+      <ToastProvider>
+        <ToastStacking />
+      </ToastProvider>
+    ),
+    code: `import React from "react";
+import { ToastProvider } from "@solara/toast";
+import { useToast } from "@solara/toast";
+
+const buttonStyle: React.CSSProperties = {
+  padding: "0.5rem 0.85rem",
+  borderRadius: "999px",
+  border: "1px solid var(--color-divider-primary)",
+  background: "var(--color-surface-0)",
+  color: "var(--color-text-primary)",
+  fontFamily: "var(--font-body)",
+  fontSize: "0.875rem",
+  cursor: "pointer",
+};
+
+const PrimaryButton = ({ label, onClick }: { label: string; onClick: () => void }) => (
+  <button type="button" onClick={onClick} style={buttonStyle}>
+    {label}
+  </button>
+);
+
+const ToastStacking = () => {
+  const { addToast } = useToast();
+
+  return (
+    <div>
+      <PrimaryButton
+        label="Queue 6 Toasts"
+        onClick={() => {
+          Array.from({ length: 6 }).forEach((_, index) => {
+            addToast({
+              title: \`Toast \${index + 1}\`,
+              description: "Stacking demo",
+              variant: index % 2 === 0 ? "info" : "default",
+            });
+          });
+        }}
+      />
+    </div>
+  );
+};
+
+export function Example() {
+  return (
+    <ToastProvider>
+      <ToastStacking />
+    </ToastProvider>
+  );
+}
+`,
+  },
+  withButton: {
+    title: "With Button",
+    description: "A toast with a tertiary button.",
+    showProps: false,
+    render: () => (
+      <ToastProvider>
+        <ToastWithAction />
+      </ToastProvider>
+    ),
+    code: `import React from "react";
+import { ToastProvider } from "@solara/toast";
+import { useToast } from "@solara/toast";
+
+const buttonStyle: React.CSSProperties = {
+  padding: "0.5rem 0.85rem",
+  borderRadius: "999px",
+  border: "1px solid var(--color-divider-primary)",
+  background: "var(--color-surface-0)",
+  color: "var(--color-text-primary)",
+  fontFamily: "var(--font-body)",
+  fontSize: "0.875rem",
+  cursor: "pointer",
+};
+
+const PrimaryButton = ({ label, onClick }: { label: string; onClick: () => void }) => (
+  <button type="button" onClick={onClick} style={buttonStyle}>
+    {label}
+  </button>
+);
+
+const ToastWithAction = () => {
+  const { toast } = useToast();
+
+  return (
+    <div>
+      <PrimaryButton
+        label="Show Action Toast"
+        onClick={() =>
+          toast({
+            title: "Message sent",
+            description: "Your update is live.",
+            variant: "success",
+            action: {
+              label: "Undo",
+              onClick: () => {
+                console.log("Undo");
+              },
+            },
+          })
+        }
+      />
+    </div>
+  );
+};
+
+export function Example() {
+  return (
+    <ToastProvider>
+      <ToastWithAction />
+    </ToastProvider>
+  );
+}
+`,
+  },
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@varialkit/toast",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./examples": "./examples.tsx",
+    "./use-toast": "./src/use-toast.ts"
+  },
+  "dependencies": {
+    "@varialkit/icons": "0.1.0"
+  },
+  "files": [
+    "src",
+    "docs.md",
+    "examples.tsx"
+  ],
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "framer-motion": "^11.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "19.0.10",
+    "react": "19.0.0",
+    "framer-motion": "11.0.0"
+  }
+}

package/src/Toast.scss

@@ -0,0 +1,185 @@
+.solara-toast-container {
+  position: fixed;
+  z-index: 9999;
+  display: flex;
+  flex-direction: column;
+  gap: calc(var(--space-3) * var(--spacing-multiplier));
+  width: min(100%, 24rem);
+  padding: 0;
+  margin: 0;
+  pointer-events: none;
+}
+
+.solara-toast-container--top-right {
+  top: var(--space-4);
+  right: var(--space-4);
+  align-items: flex-end;
+}
+
+.solara-toast-container--top-left {
+  top: var(--space-4);
+  left: var(--space-4);
+  align-items: flex-start;
+}
+
+.solara-toast-container--bottom-right {
+  bottom: var(--space-4);
+  right: var(--space-4);
+  align-items: flex-end;
+}
+
+.solara-toast-container--bottom-left {
+  bottom: var(--space-4);
+  left: var(--space-4);
+  align-items: flex-start;
+}
+
+.solara-toast-wrapper {
+  position: relative;
+  width: 100%;
+  max-width: 24rem;
+  pointer-events: auto;
+  overflow: hidden;
+  transition: opacity 0.2s ease;
+  will-change: transform, opacity;
+}
+
+.solara-toast-wrapper--dismissed {
+  opacity: 0;
+}
+
+.solara-toast {
+  --toast-bg: var(--color-surface-0);
+  --toast-text: var(--color-text-primary);
+  --toast-description: var(--color-text-secondary);
+  --toast-border: var(--color-divider-secondary);
+
+  position: relative;
+  width: 100%;
+  border-radius: var(--radius-pill);
+  border: 1px solid hsl(from var(--toast-border) h s l / 0.8);
+  background-color: var(--toast-bg);
+  color: var(--toast-text);
+  box-shadow: var(--elevation-2);
+  backdrop-filter: blur(12px);
+  -webkit-backdrop-filter: blur(12px);
+  overflow: hidden;
+  transition: background-color 0.2s ease, border-color 0.2s ease, color 0.2s ease;
+  font-family: var(--font-body);
+}
+
+.solara-toast--default {
+  --toast-bg: var(--color-content-gray-light);
+  --toast-text: var(--color-content-gray-dark);
+  --toast-border: var(--color-content-gray-med);
+}
+
+.solara-toast--success {
+  --toast-bg: var(--color-content-green-light);
+  --toast-text: var(--color-content-green-dark);
+  --toast-border: var(--color-content-green-med);
+}
+
+.solara-toast--destructive {
+  --toast-bg: var(--color-content-red-light);
+  --toast-text: var(--color-content-red-dark);
+  --toast-border: var(--color-content-red-med);
+}
+
+.solara-toast--warning {
+  --toast-bg: var(--color-content-yellow-light);
+  --toast-text: var(--color-content-yellow-dark);
+  --toast-border: var(--color-content-yellow-med);
+}
+
+.solara-toast--info {
+  --toast-bg: var(--color-content-blue-light);
+  --toast-text: var(--color-content-blue-dark);
+  --toast-border: var(--color-content-blue-med);
+}
+
+.solara-toast__content {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: calc(var(--space-2) * var(--spacing-multiplier));
+  padding: calc(var(--space-2) * var(--spacing-multiplier)) calc(var(--space-6) * var(--spacing-multiplier)) calc(var(--space-2) * var(--spacing-multiplier)) calc(var(--space-4) * var(--spacing-multiplier));
+}
+
+.solara-toast__icon {
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: calc(var(--space-5) * var(--spacing-multiplier));
+  height: calc(var(--space-5) * var(--spacing-multiplier));
+  color: currentColor;
+}
+
+.solara-toast__icon .solara-icon [stroke]:not([stroke="none"]) {
+  stroke: currentColor;
+}
+
+.solara-toast__icon .solara-icon [fill]:not([fill="none"]) {
+  fill: currentColor;
+}
+
+.solara-toast__message {
+  flex: 1;
+  min-width: 0;
+}
+
+.solara-toast__actions {
+  display: flex;
+  align-items: center;
+  gap: calc(var(--space-2) * var(--spacing-multiplier));
+}
+
+.solara-toast__title {
+  margin: 0 0 calc(var(--space-1) * var(--spacing-multiplier)) 0;
+  font-weight: 600;
+  font-size: var(--font-size-caption-scaled);
+  line-height: var(--line-height-caption-scaled);
+  color: currentColor;
+}
+
+.solara-toast__description {
+  margin: 0;
+  font-size: var(--font-size-caption-scaled);
+  line-height: var(--line-height-caption-scaled);
+  color: var(--toast-description);
+}
+
+.solara-toast__action-wrapper {
+  display: flex;
+  align-items: center;
+  margin-left: auto;
+  padding-left: calc(var(--space-2) * var(--spacing-multiplier));
+}
+
+.solara-toast__close {
+  position: relative;
+  top: auto;
+  right: auto;
+  transform: none;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: calc(var(--space-4) * var(--spacing-multiplier));
+  height: calc(var(--space-4) * var(--spacing-multiplier));
+  padding: 0;
+  background: transparent;
+  border: none;
+  border-radius: var(--radius-1);
+  color: var(--color-text-secondary);
+  cursor: pointer;
+  opacity: 0.7;
+  transition: opacity 0.2s ease, background-color 0.2s ease;
+}
+
+.solara-toast__close:hover,
+.solara-toast__close:focus-visible {
+  opacity: 1;
+  background-color: var(--color-surface-200);
+  outline: none;
+}

package/src/Toast.tsx

@@ -0,0 +1,175 @@
+"use client";
+
+import React from "react";
+import { Button } from "@solara/button";
+import { Icon } from "@solara/icons";
+import type { IconProps } from "@solara/icons";
+import type { ToastContextValue, ToastOptions, ToastProps } from "./Toast.types";
+import { ToastContainer } from "./ToastContainer";
+import "./Toast.scss";
+
+const classNames = (...classes: Array<string | undefined | false | null>) =>
+  classes.filter(Boolean).join(" ");
+
+type ToastIcon = IconProps | IconProps["name"];
+
+const normalizeIconProps = (icon: ToastIcon): IconProps =>
+  typeof icon === "string" ? { name: icon } : icon;
+
+const resolveIconProps = (icon: ToastIcon): IconProps => {
+  const iconProps = normalizeIconProps(icon);
+
+  return {
+    ...iconProps,
+    style: {
+      ...iconProps.style,
+      color: "currentColor",
+    },
+  };
+};
+
+export const Toast = React.forwardRef<
+  HTMLDivElement,
+  ToastProps & { createdAt?: number; isDismissed?: boolean }
+>(
+  (
+    {
+      title,
+      description,
+      variant = "default",
+      icon,
+      iconName,
+      showIcon = true,
+      action,
+      onDismiss,
+      className,
+      duration,
+      direction,
+      createdAt,
+      isDismissed,
+      ...rest
+    },
+    ref
+  ) => {
+    void duration;
+    void direction;
+    const resolvedIcon =
+      showIcon === false
+        ? null
+        : icon
+        ? icon
+        : iconName
+        ? <Icon {...resolveIconProps(iconName)} />
+        : null;
+
+    return (
+      <div
+        ref={ref}
+        className={classNames("solara-toast", `solara-toast--${variant}`, className)}
+        role="alert"
+        {...rest}
+      >
+        <div className="solara-toast__content">
+          {resolvedIcon ? <div className="solara-toast__icon">{resolvedIcon}</div> : null}
+          <div className="solara-toast__message">
+            <h3 className="solara-toast__title">{title}</h3>
+            {description ? (
+              <p className="solara-toast__description">{description}</p>
+            ) : null}
+          </div>
+          <div className="solara-toast__actions">
+            {action ? (
+              <div className="solara-toast__action-wrapper">
+                <Button
+                  variant="tertiary"
+                  size="small"
+                  label={action.label}
+                  onClick={action.onClick}
+                />
+              </div>
+            ) : null}
+            {onDismiss ? (
+              <button
+                type="button"
+                className="solara-toast__close"
+                onClick={onDismiss}
+                aria-label="Close"
+              >
+                <Icon name="x_16" size={14} aria-hidden />
+              </button>
+            ) : null}
+          </div>
+        </div>
+      </div>
+    );
+  }
+);
+
+Toast.displayName = "Toast";
+
+export const ToastContext = React.createContext<ToastContextValue | undefined>(
+  undefined
+);
+
+export function ToastProvider({
+  children,
+  dismissDuration = 5000,
+}: {
+  children: React.ReactNode;
+  dismissDuration?: number;
+}) {
+  const [toasts, setToasts] = React.useState<
+    Array<ToastOptions & { id: string; createdAt: number; isDismissed?: boolean }>
+  >([]);
+
+  const addToast = React.useCallback((toast: ToastOptions) => {
+    const id = Math.random().toString(36).substring(2, 9);
+    const newToast = {
+      ...toast,
+      id,
+      createdAt: Date.now(),
+      isDismissed: false,
+    };
+    setToasts((prev) => [...prev, newToast]);
+    return id;
+  }, []);
+
+  const dismissToast = React.useCallback((id: string) => {
+    setToasts((prev) =>
+      prev.map((toast) =>
+        toast.id === id
+          ? {
+            ...toast,
+            isDismissed: true,
+          }
+          : toast
+      )
+    );
+
+    setTimeout(() => {
+      setToasts((prev) => prev.filter((toast) => toast.id !== id));
+    }, 300);
+  }, []);
+
+  const value = React.useMemo(
+    () => ({
+      toasts,
+      addToast,
+      dismissToast,
+    }),
+    [toasts, addToast, dismissToast]
+  );
+
+  return (
+    <ToastContext.Provider value={value}>
+      {children}
+      <ToastContainer
+        toasts={toasts}
+        onDismiss={dismissToast}
+        dismissDuration={dismissDuration}
+      />
+    </ToastContext.Provider>
+  );
+}
+
+export default Toast;

package/src/Toast.types.ts

@@ -0,0 +1,48 @@
+import type React from "react";
+import type { IconProps } from "@solara/icons";
+
+export type ToastVariant = "default" | "success" | "destructive" | "warning" | "info";
+
+export type ToastAction = {
+  label: string;
+  onClick: () => void | Promise<void>;
+};
+
+export interface ToastMessage {
+  id: string;
+  title: string;
+  description?: string;
+  variant?: ToastVariant;
+  icon?: React.ReactNode;
+  iconName?: IconProps | IconProps["name"];
+  showIcon?: boolean;
+  action?: ToastAction;
+  duration?: number;
+  createdAt: number;
+  isDismissed?: boolean;
+  direction?: "left" | "right";
+}
+
+export interface ToastContainerProps {
+  toasts: ToastMessage[];
+  onDismiss: (id: string) => void;
+  maxToasts?: number;
+  position?: "top-right" | "top-left" | "bottom-right" | "bottom-left";
+  className?: string;
+  dismissDuration?: number;
+}
+
+export interface ToastProps
+  extends Omit<ToastMessage, "id" | "createdAt" | "isDismissed">,
+  Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+  onDismiss?: () => void;
+  className?: string;
+}
+
+export type ToastOptions = Omit<ToastProps, "onDismiss" | "className">;
+
+export type ToastContextValue = {
+  toasts: ToastMessage[];
+  addToast: (toast: ToastOptions) => string;
+  dismissToast: (id: string) => void;
+};

package/src/ToastContainer.tsx

@@ -0,0 +1,164 @@
+"use client";
+
+import React from "react";
+import { AnimatePresence, LayoutGroup, motion, type Variants } from "framer-motion";
+import { Toast } from "./Toast";
+import type { ToastContainerProps } from "./Toast.types";
+
+const DEFAULT_MAX_TOASTS = 5;
+
+const toastVariants: Variants = {
+  hidden: (custom: { position: string; direction?: "left" | "right" }) => {
+    const isBottom = custom.position.includes("bottom");
+    return {
+      opacity: 0,
+      x: custom.direction === "left" ? -50 : 50,
+      y: isBottom ? 40 : -40,
+      scale: 0.85,
+    };
+  },
+  visible: {
+    opacity: 1,
+    scale: 1,
+    x: 0,
+    y: 0,
+  },
+  exit: (custom: { position: string; direction?: "left" | "right" }) => {
+    const isBottom = custom.position.includes("bottom");
+    return {
+      opacity: 0,
+      scale: 0.8,
+      x: custom.direction === "left" ? -50 : 50,
+      y: isBottom ? 20 : -20,
+    };
+  },
+};
+
+
+
+const classNames = (...classes: Array<string | undefined | false | null>) =>
+  classes.filter(Boolean).join(" ");
+
+export function ToastContainer({
+  toasts,
+  onDismiss,
+  maxToasts = DEFAULT_MAX_TOASTS,
+  position = "bottom-right",
+  className,
+  dismissDuration = 5000,
+}: ToastContainerProps) {
+  const containerRef = React.useRef<HTMLDivElement>(null);
+  const toastRefs = React.useRef<Record<string, HTMLDivElement | null>>({});
+
+  React.useEffect(() => {
+    const now = Date.now();
+    const timers = toasts
+      .filter((toast) => !toast.isDismissed)
+      .map((toast) => ({
+        id: toast.id,
+        duration: toast.duration ?? dismissDuration,
+        remaining: Math.max(0, toast.createdAt + (toast.duration ?? dismissDuration) - now),
+      }));
+
+    const timeouts = timers
+      .map(({ id, remaining }) => {
+        if (remaining <= 0) {
+          onDismiss(id);
+          return null;
+        }
+        return setTimeout(() => onDismiss(id), remaining);
+      })
+      .filter(Boolean) as Array<ReturnType<typeof setTimeout>>;
+
+    return () => timeouts.forEach(clearTimeout);
+  }, [toasts, onDismiss, dismissDuration]);
+
+  const visibleToasts = React.useMemo(() => {
+    return toasts
+      .filter((toast) => !toast.isDismissed)
+      .sort((a, b) => a.createdAt - b.createdAt)
+      .slice(-maxToasts);
+  }, [toasts, maxToasts]);
+
+  const positionClasses = {
+    "top-right": "solara-toast-container--top-right",
+    "top-left": "solara-toast-container--top-left",
+    "bottom-right": "solara-toast-container--bottom-right",
+    "bottom-left": "solara-toast-container--bottom-left",
+  } as const;
+
+  if (visibleToasts.length === 0) return null;
+
+  return (
+    <div
+      ref={containerRef}
+      className={classNames(
+        "solara-toast-container",
+        positionClasses[position as keyof typeof positionClasses],
+        className
+      )}
+      role="region"
+      aria-live="polite"
+      aria-label="Notifications"
+    >
+      <LayoutGroup>
+        <AnimatePresence>
+          {visibleToasts.map((toast, index) => (
+            <motion.div
+              key={toast.id}
+              {...({
+                layout: true,
+                layoutId: `toast-${toast.id}`,
+                ref: (el: HTMLDivElement | null) => {
+                  if (el) {
+                    toastRefs.current[toast.id] = el;
+                  } else {
+                    delete toastRefs.current[toast.id];
+                  }
+                },
+                className: classNames(
+                  "solara-toast-wrapper",
+                  toast.isDismissed ? "solara-toast-wrapper--dismissed" : undefined
+                ),
+                variants: toastVariants,
+                custom: { position, direction: toast.direction },
+                initial: "hidden",
+                animate: "visible",
+                exit: "exit",
+                transition: {
+                  type: "spring",
+                  stiffness: 400,
+                  damping: 30,
+                  mass: 0.9,
+                },
+                style: {
+                  zIndex: 1000 + index,
+                  marginBottom: 4,
+                  willChange: "transform, opacity, height",
+                },
+                whileHover: {
+                  scale: 1.02,
+                  transition: {
+                    type: "spring",
+                    stiffness: 400,
+                    damping: 15,
+                  },
+                },
+                whileTap: {
+                  scale: 0.98,
+                  transition: {
+                    type: "spring",
+                    stiffness: 400,
+                    damping: 20,
+                  },
+                },
+              } as any)}
+            >
+              <Toast {...toast} onDismiss={() => onDismiss(toast.id)} />
+            </motion.div>
+          ))}
+        </AnimatePresence>
+      </LayoutGroup>
+    </div>
+  );
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export { Toast, ToastProvider, ToastContext } from "./Toast";
+export { ToastContainer } from "./ToastContainer";
+export { useToast } from "./useToast";
+export type {
+  ToastAction,
+  ToastContainerProps,
+  ToastContextValue,
+  ToastMessage,
+  ToastOptions,
+  ToastProps,
+  ToastVariant,
+} from "./Toast.types";

package/src/use-toast.ts

@@ -0,0 +1,50 @@
+"use client";
+
+import React from "react";
+import { useToast as useToastContext } from "./useToast";
+import type { ToastAction, ToastVariant } from "./Toast.types";
+import type { IconProps } from "@solara/icons";
+
+export type ToastOptions = {
+  title: string;
+  description?: string;
+  variant?: ToastVariant;
+  duration?: number;
+  direction?: "left" | "right";
+  action?: ToastAction;
+  icon?: React.ReactNode;
+  iconName?: IconProps | IconProps["name"];
+  showIcon?: boolean;
+};
+
+export function useToast() {
+  const { addToast } = useToastContext();
+
+  const toast = React.useCallback(
+    ({ title, description, variant = "default", duration = 5000, action, icon, iconName, showIcon, direction }: ToastOptions) => {
+      addToast({
+        title,
+        description,
+        variant,
+        duration,
+        action,
+        icon,
+        iconName,
+        showIcon,
+        direction,
+      });
+    },
+    [addToast]
+  );
+
+  return React.useMemo(
+    () => ({
+      toast,
+      success: (title: string, description?: string) => toast({ title, description, variant: "success" }),
+      error: (title: string, description?: string) => toast({ title, description, variant: "destructive" }),
+      warning: (title: string, description?: string) => toast({ title, description, variant: "warning" }),
+      info: (title: string, description?: string) => toast({ title, description, variant: "info" }),
+    }),
+    [toast]
+  );
+}

package/src/useToast.ts

@@ -0,0 +1,17 @@
+"use client";
+
+import { useContext } from "react";
+import { ToastContext } from "./Toast";
+import type { ToastContextValue, ToastMessage } from "./Toast.types";
+
+export function useToast(): ToastContextValue {
+  const context = useContext(ToastContext);
+
+  if (context === undefined) {
+    throw new Error("useToast must be used within a ToastProvider");
+  }
+
+  return context;
+}
+
+export type { ToastMessage };