@marv3l/canopy-ui 1.0.4 → 1.2.0

package/README.md

@@ -8,7 +8,7 @@ A modern npm package for building beautiful, customizable user interfaces.
 
 <br />
 
-[![npm](https://img.shields.io/badge/npm-CB3837?style=for-the-badge\&logo=npm\&logoColor=white)](https://www.npmjs.com/package/canopy-ui)
+[![npm](https://img.shields.io/badge/npm-CB3837?style=for-the-badge\&logo=npm\&logoColor=white)](https://www.npmjs.com/package/@marv3l/canopy-ui)
 [![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge\&logo=typescript\&logoColor=white)](https://www.typescriptlang.org/)
 [![React](https://img.shields.io/badge/React-20232A?style=for-the-badge\&logo=react\&logoColor=61DAFB)](https://react.dev/)
 [![Next.js](https://img.shields.io/badge/Next.js-000000?style=for-the-badge\&logo=nextdotjs\&logoColor=white)](https://nextjs.org/)
@@ -272,7 +272,7 @@ Copyright © 2026 **Shawn Rimai**
 
 </a>
 
-<a href="https://www.npmjs.com/package/canopy-ui">
+<a href="https://www.npmjs.com/package/@marv3l/canopy-ui">
 
 <img src="https://img.shields.io/badge/npm-Canopy%20UI-CB3837?style=for-the-badge&logo=npm&logoColor=white" />
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marv3l/canopy-ui",
-  "version": "1.0.4",
+  "version": "1.2.0",
   "description": "An accessible, themable React UI component library built for fast-moving web applications.",
   "main": "./dist/index.js",
   "bin": {

package/templates/toast/toast.tsx

@@ -1,63 +1,89 @@
 "use client";
 
-// Import React runtime and component types
 import * as React from "react";
-// Import semantic SVG icons from lucide-react
-import { CheckCircle2, AlertCircle, AlertTriangle, Info, X } from "lucide-react";
-// Import toast hook and type interfaces
+import { CheckCircle2, AlertCircle, AlertTriangle, Info, Loader2, X, LucideIcon } from "lucide-react";
 import { useToast, ToastItem } from "./use-toast";
 
-// Props accepted by the root Toaster container mounted in the root layout
 export interface ToasterProps {
-  // Global lifespan (in milliseconds) for all toasts; defaults to 4000ms
   defaultDuration?: number;
-  // Screen viewport placement position
   position?: "top-right" | "bottom-right" | "top-center" | "bottom-center" | "top-left" | "bottom-left";
 }
 
-// Visual preset configurations mapped to your semantic theme tokens
 const variantStyles: Record<
   string,
-  { bg: string; border: string; text: string; progress: string; icon: any }
+  {
+    bg: string;
+    border: string;
+    title: string;
+    description: string;
+    progress: string;
+    iconColor: string;
+    badge: string;
+    icon: LucideIcon | null;
+  }
 > = {
   default: {
-    bg: "bg-card",
-    border: "border-border",
-    text: "text-card-foreground",
-    progress: "bg-foreground/20",
+    bg: "bg-card dark:bg-neutral-900/95",
+    border: "border-border dark:border-neutral-700/80",
+    title: "text-neutral-900 dark:text-neutral-50",
+    description: "text-neutral-600 dark:text-neutral-200",
+    progress: "bg-neutral-900/20 dark:bg-neutral-400",
+    iconColor: "text-neutral-700 dark:text-neutral-300",
+    badge: "bg-neutral-200 text-neutral-800 dark:bg-neutral-800 dark:text-neutral-100 border-neutral-300 dark:border-neutral-700",
     icon: null,
   },
   success: {
-    bg: "bg-success-bg",
-    border: "border-success/40",
-    text: "text-success",
-    progress: "bg-success",
+    bg: "bg-success-bg dark:bg-emerald-950/60",
+    border: "border-success/40 dark:border-emerald-500/50",
+    title: "text-emerald-950 dark:text-emerald-100",
+    description: "text-emerald-800 dark:text-emerald-200/90",
+    progress: "bg-emerald-600 dark:bg-emerald-400",
+    iconColor: "text-emerald-600 dark:text-emerald-400",
+    badge: "bg-emerald-100 text-emerald-900 dark:bg-emerald-900/80 dark:text-emerald-100 border-emerald-300 dark:border-emerald-700",
     icon: CheckCircle2,
   },
   error: {
-    bg: "bg-destructive/10",
-    border: "border-destructive/30",
-    text: "text-destructive",
-    progress: "bg-destructive",
+    bg: "bg-destructive/10 dark:bg-red-950/60",
+    border: "border-destructive/30 dark:border-red-500/50",
+    title: "text-red-950 dark:text-red-100",
+    description: "text-red-800 dark:text-red-200/90",
+    progress: "bg-destructive dark:bg-red-400",
+    iconColor: "text-red-600 dark:text-red-400",
+    badge: "bg-red-100 text-red-900 dark:bg-red-900/80 dark:text-red-100 border-red-300 dark:border-red-700",
     icon: AlertCircle,
   },
   warning: {
-    bg: "bg-warning-bg",
-    border: "border-warning/40",
-    text: "text-warning",
-    progress: "bg-warning",
+    bg: "bg-warning-bg dark:bg-amber-950/60",
+    border: "border-warning/40 dark:border-amber-500/50",
+    title: "text-amber-950 dark:text-amber-100",
+    description: "text-amber-800 dark:text-amber-200/90",
+    progress: "bg-amber-600 dark:bg-amber-400",
+    iconColor: "text-amber-600 dark:text-amber-400",
+    badge: "bg-amber-100 text-amber-900 dark:bg-amber-900/80 dark:text-amber-100 border-amber-300 dark:border-amber-700",
     icon: AlertTriangle,
   },
   info: {
-    bg: "bg-accent",
-    border: "border-primary/30",
-    text: "text-accent-foreground",
-    progress: "bg-primary",
+    bg: "bg-accent dark:bg-sky-950/60",
+    border: "border-primary/30 dark:border-sky-500/50",
+    title: "text-sky-950 dark:text-sky-100",
+    description: "text-sky-800 dark:text-sky-200/90",
+    progress: "bg-primary dark:bg-sky-400",
+    iconColor: "text-sky-600 dark:text-sky-400",
+    badge: "bg-sky-100 text-sky-900 dark:bg-sky-900/80 dark:text-sky-100 border-sky-300 dark:border-sky-700",
     icon: Info,
   },
+  loading: {
+    bg: "bg-card dark:bg-neutral-900/95",
+    border: "border-border dark:border-neutral-700/80",
+    title: "text-neutral-900 dark:text-neutral-50",
+    description: "text-neutral-600 dark:text-neutral-200",
+    progress: "bg-primary dark:bg-sky-400",
+    iconColor: "text-primary dark:text-sky-400 animate-spin",
+    badge: "bg-neutral-200 text-neutral-800 dark:bg-neutral-800 dark:text-neutral-100 border-neutral-300 dark:border-neutral-700",
+    icon: Loader2,
+  },
 };
 
-// Root Toaster Component placed into layout.tsx
 export function Toaster({ defaultDuration = 4000, position = "top-center" }: ToasterProps) {
   const { toasts, dismiss } = useToast();
 
@@ -81,6 +107,46 @@ export function Toaster({ defaultDuration = 4000, position = "top-center" }: Toa
             transform: scaleX(0);
           }
         }
+        @keyframes toast-expand {
+          from {
+            grid-template-rows: 0fr;
+          }
+          to {
+            grid-template-rows: 1fr;
+          }
+        }
+        @keyframes toast-fade-in {
+          from {
+            opacity: 0;
+            transform: translateY(-4px);
+          }
+          to {
+            opacity: 1;
+            transform: translateY(0);
+          }
+        }
+        @keyframes toast-pop {
+          0% {
+            transform: scale(0.6);
+          }
+          50% {
+            transform: scale(1.2);
+          }
+          100% {
+            transform: scale(1);
+          }
+        }
+        @keyframes toast-shake {
+          0%, 100% {
+            transform: translateX(0);
+          }
+          25% {
+            transform: translateX(-2px);
+          }
+          75% {
+            transform: translateX(2px);
+          }
+        }
       `}</style>
 
       <div className={`fixed z-50 pointer-events-none flex flex-col gap-2 p-4 w-full max-w-sm ${positionClasses}`}>
@@ -97,7 +163,6 @@ export function Toaster({ defaultDuration = 4000, position = "top-center" }: Toa
   );
 }
 
-// Atomic Toast Card Component
 function ToastElement({
   toast,
   defaultDuration,
@@ -107,76 +172,156 @@ function ToastElement({
   defaultDuration: number;
   onDismiss: () => void;
 }) {
-  const duration = toast.duration ?? defaultDuration;
+  const isAutoDismissible = toast.variant !== "loading" && (toast.duration === undefined || toast.duration > 0);
+  const activeDuration = toast.duration ?? defaultDuration;
+  const showProgress = toast.showProgress ?? isAutoDismissible;
+
+  const [isPaused, setIsPaused] = React.useState(false);
+  const remainingTimeRef = React.useRef<number>(activeDuration);
+  const startTimeRef = React.useRef<number>(0);
+  const timerRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
 
+  // Update remaining ref on prop changes without triggering synchronous setState re-renders
   React.useEffect(() => {
-    if (duration <= 0) return;
-    const timer = setTimeout(() => {
+    remainingTimeRef.current = activeDuration;
+  }, [toast.variant, toast.title, toast.count, activeDuration]);
+
+  // Handle countdown timeout
+  React.useEffect(() => {
+    if (!isAutoDismissible || isPaused) {
+      if (timerRef.current) clearTimeout(timerRef.current);
+      return;
+    }
+
+    startTimeRef.current = Date.now();
+    timerRef.current = setTimeout(() => {
       onDismiss();
-    }, duration);
-    return () => clearTimeout(timer);
-  }, [duration, onDismiss]);
+    }, remainingTimeRef.current);
+
+    return () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+    };
+  }, [isAutoDismissible, isPaused, toast.variant, toast.title, toast.count, activeDuration, onDismiss]);
+
+  const handleMouseEnter = () => {
+    if (!isAutoDismissible) return;
+    if (timerRef.current) clearTimeout(timerRef.current);
+    const elapsed = Date.now() - startTimeRef.current;
+    remainingTimeRef.current = Math.max(remainingTimeRef.current - elapsed, 0);
+    setIsPaused(true);
+  };
+
+  const handleMouseLeave = () => {
+    if (!isAutoDismissible) return;
+    setIsPaused(false);
+  };
 
   const variant = toast.variant || "default";
   const defaultStyle = variantStyles[variant] || variantStyles.default;
-  const IconComponent = defaultStyle.icon;
+  const IconComponent = toast.icon !== undefined ? null : defaultStyle.icon;
 
-  // 1. Only build inline styles for values that are explicitly provided
   const customInlineStyle: React.CSSProperties = {};
   if (toast.customColor?.bg) customInlineStyle.backgroundColor = toast.customColor.bg;
   if (toast.customColor?.border) customInlineStyle.borderColor = toast.customColor.border;
   if (toast.customColor?.text) customInlineStyle.color = toast.customColor.text;
 
-  // 2. Prevent default Tailwind classes from overriding user custom classes or inline styles
   const userHasBg = Boolean(toast.customColor?.bg || toast.className?.match(/(?:^|\s)bg-/));
   const userHasBorder = Boolean(toast.customColor?.border || toast.className?.match(/(?:^|\s)border-/));
-  const userHasText = Boolean(toast.customColor?.text || toast.className?.match(/(?:^|\s)text-/));
+
+  const isError = variant === "error";
 
   return (
     <div
+      role={isError ? "alert" : "status"}
+      aria-live={isError ? "assertive" : "polite"}
       style={customInlineStyle}
-      className={`pointer-events-auto relative overflow-hidden flex items-start gap-3 w-full p-4 rounded-[var(--radius-lg,0.625rem)] border shadow-lg transition-all duration-200 backdrop-blur-sm ${
+      onMouseEnter={handleMouseEnter}
+      onMouseLeave={handleMouseLeave}
+      className={`pointer-events-auto relative overflow-hidden flex items-start gap-3 w-full p-4 rounded-[var(--radius-lg,0.625rem)] border shadow-xl dark:shadow-2xl dark:shadow-black/70 dark:ring-1 dark:ring-white/10 backdrop-blur-md transition-all duration-300 ease-out ${
         !userHasBg ? defaultStyle.bg : ""
-      } ${!userHasBorder ? defaultStyle.border : ""} ${
-        !userHasText ? defaultStyle.text : ""
-      } ${toast.className || ""}`}
+      } ${!userHasBorder ? defaultStyle.border : ""} ${toast.className || ""}`}
     >
-      {/* Render icon if preset defines one */}
-      {IconComponent && (
-        <IconComponent
-          className="w-5 h-5 mt-0.5 shrink-0"
-          style={{ color: toast.customColor?.icon }}
-        />
+      {toast.icon !== undefined ? (
+        <div className="shrink-0 mt-0.5">{toast.icon}</div>
+      ) : (
+        IconComponent && (
+          <IconComponent
+            className={`w-5 h-5 mt-0.5 shrink-0 ${defaultStyle.iconColor}`}
+            style={{ color: toast.customColor?.icon }}
+          />
+        )
       )}
 
       {/* Toast Content Area */}
-      <div className="flex-1 text-sm space-y-1">
-        {toast.title && <div className="font-semibold leading-tight">{toast.title}</div>}
+      <div className="flex-1 text-sm">
+        <div className="flex items-center gap-2">
+          {toast.title && (
+            <div className={`font-semibold leading-tight tracking-tight ${defaultStyle.title}`}>
+              {toast.title}
+            </div>
+          )}
+
+          {/* Duplication Counter / Max Badge */}
+          {toast.count > 1 && (
+            <span
+              key={`${toast.count}-${toast.maxReached}`}
+              style={{
+                animation: toast.maxReached
+                  ? "toast-shake 200ms ease-in-out"
+                  : "toast-pop 200ms ease-out",
+              }}
+              className={`inline-flex items-center justify-center px-1.5 py-0.5 text-[10px] font-bold rounded-full border shadow-sm transition-transform ${
+                defaultStyle.badge
+              } ${toast.maxReached ? "ring-1 ring-destructive/40" : ""}`}
+            >
+              {toast.maxReached ? `×${toast.count} (max)` : `×${toast.count}`}
+            </span>
+          )}
+        </div>
+
         {toast.description && (
-          <div className="opacity-90 leading-relaxed text-xs">
-            {toast.description}
+          <div
+            className="grid overflow-hidden"
+            style={{
+              gridTemplateRows: "0fr",
+              animation: "toast-expand 250ms cubic-bezier(0.16, 1, 0.3, 1) 250ms forwards",
+            }}
+          >
+            <div className="overflow-hidden">
+              <div
+                className={`leading-relaxed text-xs pt-1 opacity-0 font-normal ${defaultStyle.description}`}
+                style={{
+                  animation: "toast-fade-in 200ms ease-out 250ms forwards",
+                }}
+              >
+                {toast.description}
+              </div>
+            </div>
           </div>
         )}
-        {toast.action && <div className="pt-1">{toast.action}</div>}
+
+        {toast.action && <div className="pt-2">{toast.action}</div>}
       </div>
 
-      {/* Close button */}
       <button
         onClick={onDismiss}
-        className="p-1 rounded-md opacity-70 hover:opacity-100 hover:bg-foreground/10 transition-colors"
+        aria-label="Close toast"
+        className="p-1 rounded-md opacity-70 hover:opacity-100 hover:bg-neutral-500/15 dark:hover:bg-white/10 transition-colors text-neutral-500 dark:text-neutral-300 hover:text-neutral-900 dark:hover:text-white"
       >
         <X className="w-4 h-4" />
       </button>
 
-      {/* Animated Lifespan Progress Bar */}
-      {duration > 0 && (
+      {/* Progress Bar resets animation on each state change */}
+      {showProgress && isAutoDismissible && (
         <div
+          key={`${toast.id}-${toast.variant}-${toast.count}`}
           className={`absolute bottom-0 left-0 right-0 h-1 origin-left ${
             !toast.customColor?.progress ? defaultStyle.progress : ""
           }`}
           style={{
             backgroundColor: toast.customColor?.progress,
-            animation: `toast-progress ${duration}ms linear forwards`,
+            animation: `toast-progress ${activeDuration}ms linear forwards`,
+            animationPlayState: isPaused ? "paused" : "running",
           }}
         />
       )}

package/templates/toast/use-toast.ts

@@ -1,214 +1,343 @@
-"use client"
+"use client";
 
-// Import React to access state hooks and ReactNode type definitions
 import * as React from "react";
 
-// Define the supported visual preset types for toast notifications
-export type ToastVariant = "default" | "success" | "error" | "warning" | "info" | "custom";
+/**
+ * Supported visual styles and operational modes for toasts.
+ * - "default" | "success" | "error" | "warning" | "info": Semantic presets
+ * - "custom": Custom token/color overrides
+ * - "loading": Persistent spinner mode for asynchronous operations
+ */
+export type ToastVariant =
+  | "default"
+  | "success"
+  | "error"
+  | "warning"
+  | "info"
+  | "custom"
+  | "loading";
 
-// Interface defining all configurable parameters when triggering a toast notification
 export interface ToastOptions {
-    // Unique identifier for toast; auto-generated if omitted
-    id?: string;
-    // Primary header text or React component
-    title?: React.ReactNode;
-    // Secondary descriptive message or details
-    description?: React.ReactNode;
-    // Optional action button or interactive element
-    action?: React.ReactNode;
-    // Visual style preset (success, error, warning, info, default, custom)
-    variant?: ToastVariant;
-    // Individual lifespan in milliseconds; overrides the global layout default
-    duration?: number;
-    // User-defined custom styling parameters for dynamic themes
-    customColor?: {
-        // Custom CSS background color (HEX, RGB, or HSL)
-        bg?: string;
-        // Custom text color
-        text?: string;
-        // Custom border stroke color
-        border?: string;
-        //Custom progress bar stroke color
-        progress?: string;
-        // Custom icon fill/stroke tint
-        icon?: string;
-    };
-    // Additional Tailwind or custom CSS classes applied to toast container
-    className?: string;
+  /** Optional custom identifier. If omitted, a collision-resistant UUID is generated. */
+  id?: string;
+  /** Primary title text or JSX element displayed in the toast header. */
+  title?: React.ReactNode;
+  /** Secondary explanatory text or JSX node rendered below the title. */
+  description?: React.ReactNode;
+  /** Interactive action button or control rendered at the bottom of the toast. */
+  action?: React.ReactNode;
+  /** Visual variant styling preset. Defaults to "default". */
+  variant?: ToastVariant;
+  /** Display duration in milliseconds before auto-dismissing. Set to 0 or Infinity to prevent auto-dismiss. */
+  duration?: number;
+  /** Maximum number of duplicate message stacks allowed for this specific toast (defaults to 5). */
+  maxCount?: number;
+  /** Explicitly toggle the animated bottom progress bar. Defaults to true when auto-dismissible. */
+  showProgress?: boolean;
+  /** Optional custom icon node to override the variant preset icon. */
+  icon?: React.ReactNode;
+  /** Custom inline token styling overrides for background, border, text, progress bar, and icon. */
+  customColor?: {
+    bg?: string;
+    text?: string;
+    border?: string;
+    progress?: string;
+    icon?: string;
+  };
+  /** Additional Tailwind or CSS class names to apply to the root toast card container. */
+  className?: string;
 }
 
-// Internal representation of an active toast item containing open state
 export interface ToastItem extends ToastOptions {
-    // Guaranteed string ID for DOM key mapping
-    id: string;
-    // Boolean flag controlling entrance and exit animations
-    open: boolean;
+  id: string;
+  open: boolean;
+  count: number;
+  maxReached?: boolean;
 }
 
-// Maximum number of visible toast cards on screen simultaneously
+// -----------------------------------------------------------------------------
+// Constants & Configuration
+// -----------------------------------------------------------------------------
+
+/** Maximum number of simultaneous toasts rendered on screen at any time. */
 const TOAST_LIMIT = 5;
-// Delay before removed toasts are completely purged from memory (allows exit transition)
-const TOAST_REMOVE_DELAY = 500;
-
-// Discriminated union type representing all possible reducer actions
-type Action = 
-    // Adds a newly triggered toast to state
-    | { type: "ADD_TOAST"; toast: ToastItem }
-    // Modifies properties of an existing active toast
-    | { type: "UPDATE_TOAST"; toast: Partial<ToastItem> }
-    // Initiates dismiss sequence (triggers exit animation)
-    | { type: "DISMISS_TOAST"; toastId?: string }
-    // Purges toast object from memory after exit animation finishes
-    | { type: "REMOVE_TOAST"; toastId?: string };
-
-// Structure of global toast memory state
+
+/** Default duplicate stack cap if not overridden per toast. */
+const DEFAULT_MAX_COUNT = 5;
+
+/** Delay in ms before unmounting a dismissed toast from the state tree. */
+const TOAST_REMOVE_DELAY = 0;
+
+// -----------------------------------------------------------------------------
+// Action Types & State Management
+// -----------------------------------------------------------------------------
+
+type Action =
+  | { type: "ADD_TOAST"; toast: ToastItem }
+  | { type: "UPDATE_TOAST"; toast: Partial<ToastItem> }
+  | { type: "DISMISS_TOAST"; toastId?: string }
+  | { type: "REMOVE_TOAST"; toastId?: string };
+
 interface State {
-    toasts: ToastItem[];
+  toasts: ToastItem[];
 }
 
-// Monotonically increasing counter for collision-free ID generation
-let count = 0;
-
-// Generates unique string identifiers for toast items
+/**
+ * Generates a collision-resistant unique identifier.
+ * Uses native crypto.randomUUID when available, falling back to high-resolution timestamps.
+ */
 function genId(): string {
-    count = (count + 1) % Number.MAX_SAFE_INTEGER;
-    return count.toString();
+  if (typeof crypto !== "undefined" && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  return `${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
 }
 
-// Map tracking active removal timers to prevent duplicate schedule queues
+/** Tracks active unmount timers to prevent duplicate queue dispatches. */
 const toastTimeouts = new Map<string, ReturnType<typeof setTimeout>>();
 
-// Schedule the hard removal of a dismissed toast after its exit animation completes
+/**
+ * Schedules a toast for removal from memory after dismissal animations complete.
+ */
 const addToRemoveQueue = (toastId: string) => {
-    // If a timeout is already scheduled for this ID, skip to avoid duplicates
-    if (toastTimeouts.has(toastId)) return;
-
-    // Schedule state dispatch after delay
-    const timeout = setTimeout(() => {
-        // Clean up timeout reference from tracking map
-        toastTimeouts.delete(toastId);
-        // Dispatch removal action to purge from state
-        dispatch({ type: "REMOVE_TOAST", toastId });
-    }, TOAST_REMOVE_DELAY);
-
-    // Store reference in tracking map
-    toastTimeouts.set(toastId, timeout);
+  if (toastTimeouts.has(toastId)) return;
+
+  const timeout = setTimeout(() => {
+    toastTimeouts.delete(toastId);
+    dispatch({ type: "REMOVE_TOAST", toastId });
+  }, TOAST_REMOVE_DELAY);
+
+  toastTimeouts.set(toastId, timeout);
 };
 
-// Pure reducer function handling toast state transitions
+/**
+ * Main state reducer managing insertion, deduplication stacking, updates, and dismissals.
+ */
 export const reducer = (state: State, action: Action): State => {
-    switch (action.type) {
-        case "ADD_TOAST":
-            return {
-                ...state,
-                // Prepend new toast and enforce maximum visible limit
-                toasts: [action.toast, ...state.toasts].slice(0, TOAST_LIMIT),
-            };
-
-        case "UPDATE_TOAST":
-            return {
-                ...state,
-                // Map through toasts and merge updated properties onto target ID
-                toasts: state.toasts.map((t) =>
-                    t.id === action.toast.id ? { ...t, ...action.toast } : t
-                ),
-            };
-
-        case "DISMISS_TOAST": {
-            const { toastId } = action;
-
-            // If a specific ID is provided, schedule removal for only that toast
-            if (toastId) {
-                addToRemoveQueue(toastId);
-            } else {
-                // Otherwise schedule removal for all currently open toasts
-                state.toasts.forEach((toast) => addToRemoveQueue(toast.id));
-            }
-
-            return {
-                ...state,
-                // Mark target toasts as closed to trigger CSS fade-out
-                toasts: state.toasts.map((t) =>
-                    t.id === toastId || toastId === undefined ? { ...t, open: false } : t
-                ),
-            };
-        }
-
-        case "REMOVE_TOAST":
-            // Clear entire array if no specific ID passed
-            if (action.toastId === undefined) return { ...state, toasts: [] };
-
-            return {
-                ...state,
-                // Filter out target toast from state memory
-                toasts: state.toasts.filter((t) => t.id !== action.toastId),
-            };
-
-        default:
-            return state;
+  switch (action.type) {
+    case "ADD_TOAST": {
+      // 1. In-place update: If a toast with this exact ID already exists (e.g. toast.promise transitions), update it
+      const existingByIdIndex = state.toasts.findIndex((t) => t.id === action.toast.id);
+
+      if (existingByIdIndex !== -1) {
+        return {
+          ...state,
+          toasts: state.toasts.map((t) =>
+            t.id === action.toast.id ? { ...t, ...action.toast, open: true } : t
+          ),
+        };
+      }
+
+      // 2. Duplicate Detection: Match on open state, title, description, and variant to increment badge counter
+      const existingIndex = state.toasts.findIndex(
+        (t) =>
+          t.open &&
+          t.title === action.toast.title &&
+          t.description === action.toast.description &&
+          (t.variant || "default") === (action.toast.variant || "default")
+      );
+
+      if (existingIndex !== -1) {
+        const existing = state.toasts[existingIndex];
+        const maxLimit = existing.maxCount ?? action.toast.maxCount ?? DEFAULT_MAX_COUNT;
+
+        // Cap the count at maxLimit
+        const newCount = Math.min(existing.count + 1, maxLimit);
+        const maxReached = existing.count + 1 >= maxLimit;
+
+        const updatedToast: ToastItem = {
+          ...existing,
+          ...action.toast,
+          id: existing.id,
+          count: newCount,
+          maxReached,
+          open: true,
+        };
+
+        // Move updated toast to the top of the stack
+        const rest = state.toasts.filter((t) => t.id !== existing.id);
+        return {
+          ...state,
+          toasts: [updatedToast, ...rest].slice(0, TOAST_LIMIT),
+        };
+      }
+
+      // 3. New Toast: Prepend to list and truncate at TOAST_LIMIT
+      return {
+        ...state,
+        toasts: [action.toast, ...state.toasts].slice(0, TOAST_LIMIT),
+      };
+    }
+
+    case "UPDATE_TOAST":
+      return {
+        ...state,
+        toasts: state.toasts.map((t) =>
+          t.id === action.toast.id ? { ...t, ...action.toast } : t
+        ),
+      };
+
+    case "DISMISS_TOAST": {
+      const { toastId } = action;
+
+      // Queue removal for specific toast or all active toasts
+      if (toastId) {
+        addToRemoveQueue(toastId);
+      } else {
+        state.toasts.forEach((toast) => addToRemoveQueue(toast.id));
+      }
+
+      // Mark toast as closed to trigger exit transitions
+      return {
+        ...state,
+        toasts: state.toasts.map((t) =>
+          t.id === toastId || toastId === undefined ? { ...t, open: false } : t
+        ),
+      };
     }
+
+    case "REMOVE_TOAST":
+      if (action.toastId === undefined) return { ...state, toasts: [] };
+      return {
+        ...state,
+        toasts: state.toasts.filter((t) => t.id !== action.toastId),
+      };
+
+    default:
+      return state;
+  }
 };
 
-// Array of subscriber callbacks implementing the Observer pattern
-const listeners: Array<(state: State) => void> = [];
+// -----------------------------------------------------------------------------
+// Store Listeners & Dispatch Dispatcher
+// -----------------------------------------------------------------------------
 
-// Singleton state variable preserving toast state across entire application
+const listeners: Array<(state: State) => void> = [];
 let memoryState: State = { toasts: [] };
 
-// Dispatches actions to state and notifies all registered React hook subscribers
 function dispatch(action: Action) {
-    // Update in-memory singleton state
-    memoryState = reducer(memoryState, action);
-    // Notify every mounted React component listener
-    listeners.forEach((listener) => listener(memoryState));
+  memoryState = reducer(memoryState, action);
+  listeners.forEach((listener) => listener(memoryState));
 }
 
-// Imperative toast function callable from anywhere (inside or outside React lifecycle)
+// -----------------------------------------------------------------------------
+// Core Toast Dispatcher & Convenience Helpers
+// -----------------------------------------------------------------------------
+
+/**
+ * Base dispatcher function to spawn or update a toast alert.
+ */
 export function toast(props: ToastOptions) {
-    // Use provided ID or generate a new unique identifier
-    const id = props.id || genId();
-
-    // Helper to dynamically update this specific toast
-    const update = (updatedProps: ToastOptions) => 
-        dispatch({ type: "UPDATE_TOAST", toast: { ...updatedProps, id } });
-
-    // Helper to dismiss this specific toast
-    const dismiss = () => dispatch({ type: "DISMISS_TOAST", toastId: id });
-
-    // Dispatch action to push toast into visible queue
-    dispatch({
-        type: "ADD_TOAST",
-        toast: {
-            ...props,
-            id,
-            open: true,
-        },
-    });
+  const id = props.id || genId();
+
+  const update = (updatedProps: ToastOptions) =>
+    dispatch({ type: "UPDATE_TOAST", toast: { ...updatedProps, id } });
+
+  const dismiss = () => dispatch({ type: "DISMISS_TOAST", toastId: id });
+
+  dispatch({
+    type: "ADD_TOAST",
+    toast: {
+      ...props,
+      id,
+      open: true,
+      count: 1,
+      maxReached: false,
+    },
+  });
 
-    // Return control object allowing caller to dismiss or update toast programmatically
-    return { id, dismiss, update };
+  return { id, dismiss, update };
 }
 
-// Custom React hook subscribing components to real-time toast updates
-export function useToast() {
-    // Local state synced with singleton memory state
-    const [state, setState] = React.useState<State>(memoryState);
-
-    // Register listener on mount; unregister on unmount
-    React.useEffect(() => {
-        listeners.push(setState);
-        return () => {
-            const index = listeners.indexOf(setState);
-            if (index > -1) {
-                listeners.splice(index, 1);
-            }
-        };
-    }, []); // Empty array ensures registration only happens on mount/unmount
+/** Convenience helper: Spawns a success variant toast. */
+toast.success = (title: React.ReactNode, options?: Omit<ToastOptions, "title" | "variant">) =>
+  toast({ ...options, title, variant: "success" });
+
+/** Convenience helper: Spawns an error variant toast. */
+toast.error = (title: React.ReactNode, options?: Omit<ToastOptions, "title" | "variant">) =>
+  toast({ ...options, title, variant: "error" });
+
+/** Convenience helper: Spawns a warning variant toast. */
+toast.warning = (title: React.ReactNode, options?: Omit<ToastOptions, "title" | "variant">) =>
+  toast({ ...options, title, variant: "warning" });
+
+/** Convenience helper: Spawns an informational variant toast. */
+toast.info = (title: React.ReactNode, options?: Omit<ToastOptions, "title" | "variant">) =>
+  toast({ ...options, title, variant: "info" });
+
+/** Convenience helper: Spawns a persistent loading variant toast with infinite duration. */
+toast.loading = (title: React.ReactNode, options?: Omit<ToastOptions, "title" | "variant">) =>
+  toast({ ...options, title, variant: "loading", duration: 0 });
+
+/** Global method to dismiss a specific toast by ID or all active toasts if no ID is passed. */
+toast.dismiss = (toastId?: string) => dispatch({ type: "DISMISS_TOAST", toastId });
+
+/**
+ * Asynchronous promise lifecycle handler.
+ * Displays a loading state and seamlessly transitions to success or error on resolution.
+ */
+toast.promise = <T,>(
+  promise: Promise<T> | (() => Promise<T>),
+  msgs: {
+    loading: React.ReactNode;
+    success: React.ReactNode | ((data: T) => React.ReactNode);
+    error: React.ReactNode | ((err: unknown) => React.ReactNode);
+  },
+  options?: ToastOptions
+) => {
+  const instance = toast({
+    ...options,
+    variant: "loading",
+    title: msgs.loading,
+    duration: 0,
+  });
+
+  const promiseFn = typeof promise === "function" ? promise() : promise;
+
+  promiseFn
+    .then((data) => {
+      const successTitle = typeof msgs.success === "function" ? msgs.success(data) : msgs.success;
+      toast.success(successTitle, {
+        ...options,
+        id: instance.id,
+        duration: options?.duration ?? 4000,
+      });
+    })
+    .catch((err: unknown) => {
+      const errorTitle = typeof msgs.error === "function" ? msgs.error(err) : msgs.error;
+      toast.error(errorTitle, {
+        ...options,
+        id: instance.id,
+        duration: options?.duration ?? 5000,
+      });
+    });
 
-    // Expose current state, trigger function, and dismiss helper
-    return {
-        ...state,
-        toast,
-        dismiss: (toastId?: string) => dispatch({ type: "DISMISS_TOAST", toastId }),
+  return promiseFn;
+};
+
+// -----------------------------------------------------------------------------
+// React Consumer Hook
+// -----------------------------------------------------------------------------
+
+/**
+ * React hook providing reactive toast state, dispatchers, and dismissal handlers.
+ */
+export function useToast() {
+  const [state, setState] = React.useState<State>(memoryState);
+
+  React.useEffect(() => {
+    listeners.push(setState);
+    return () => {
+      const index = listeners.indexOf(setState);
+      if (index > -1) {
+        listeners.splice(index, 1);
+      }
     };
+  }, []);
+
+  return {
+    ...state,
+    toast,
+    dismiss: (toastId?: string) => dispatch({ type: "DISMISS_TOAST", toastId }),
+  };
 }