@marv3l/canopy-ui 1.1.0 → 1.2.1

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/dist/index.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+#!/usr/bin/env node
 
 // src/index.ts
 import { Command } from "commander";
@@ -13,28 +14,33 @@ import pc from "picocolors";
 
 // src/registry.ts
 var REGISTRY = {
-  // Toast component registration
   toast: {
-    name: "Custom Toast Notification System",
-    // Packages to automatically install in consumer project
-    dependencies: ["lucide-react", "clsx", "tailwind-merge"],
+    name: "Toast",
+    packageName: "@canopy-ui/toast",
+    // Your published npm package name
+    dependencies: ["lucide-react"],
     files: [
       {
-        templatePath: "toast/toast.tsx",
-        targetName: "toast.tsx"
-      },
-      {
-        templatePath: "toast/use-toast.ts",
-        targetName: "use-toast.ts"
+        targetName: "toast.tsx",
+        content: `"use client";
+
+export * from "@canopy-ui/toast";`
       }
     ]
   }
-  // Future components (dialog, sheet, dropdown) are added here
 };
 
 // src/commands/add.ts
 var __filename = fileURLToPath(import.meta.url);
 var __dirname = path.dirname(__filename);
+async function detectPackageManager(projectRoot) {
+  if (await fs.pathExists(path.join(projectRoot, "pnpm-lock.yaml"))) return "pnpm";
+  if (await fs.pathExists(path.join(projectRoot, "yarn.lock"))) return "yarn";
+  if (await fs.pathExists(path.join(projectRoot, "bun.lockb")) || await fs.pathExists(path.join(projectRoot, "bun.lock"))) {
+    return "bun";
+  }
+  return "npm";
+}
 async function add(componentKeys) {
   p.intro(pc.bgCyan(pc.black(" Canopy UI ")));
   let selected = componentKeys;
@@ -55,6 +61,7 @@ async function add(componentKeys) {
     selected = response;
   }
   const projectRoot = process.cwd();
+  const pkgManager = await detectPackageManager(projectRoot);
   const hasSrc = await fs.pathExists(path.join(projectRoot, "src"));
   const targetDir = hasSrc ? path.join(projectRoot, "src", "components", "ui") : path.join(projectRoot, "components", "ui");
   await fs.ensureDir(targetDir);
@@ -65,35 +72,58 @@ async function add(componentKeys) {
       p.log.error(`Component "${key}" was not found in registry.`);
       continue;
     }
-    spinner2.start(`Copying ${meta.name} source files...`);
+    spinner2.start(`Setting up ${meta.name}...`);
+    const allDependencies = [
+      ...meta.packageName ? [meta.packageName] : [],
+      ...meta.dependencies || []
+    ];
+    if (allDependencies.length > 0) {
+      spinner2.message(
+        `Installing packages (${pc.cyan(pkgManager)}): ${pc.dim(allDependencies.join(", "))}...`
+      );
+      const installArgs = {
+        npm: ["install", ...allDependencies],
+        pnpm: ["add", ...allDependencies],
+        yarn: ["add", ...allDependencies],
+        bun: ["add", ...allDependencies]
+      }[pkgManager];
+      try {
+        await execa(pkgManager, installArgs, {
+          cwd: projectRoot,
+          stdio: "pipe"
+        });
+      } catch (err) {
+        spinner2.stop(pc.red(`Failed to install dependencies for ${meta.name}`));
+        p.log.error(String(err));
+        continue;
+      }
+    }
+    spinner2.message(`Creating component stub for ${meta.name}...`);
     for (const file of meta.files) {
-      const srcPath = path.resolve(__dirname, "../templates", file.templatePath);
       const destPath = path.join(targetDir, file.targetName);
-      if (await fs.pathExists(srcPath)) {
-        await fs.copy(srcPath, destPath, { overwrite: true });
-      } else {
-        spinner2.stop(pc.red(`Template file missing: ${file.templatePath}`));
-        p.log.warn(pc.dim(`Looked at path: ${srcPath}`));
-        return;
+      if (file.templatePath) {
+        const srcPath = path.resolve(__dirname, "../templates", file.templatePath);
+        if (await fs.pathExists(srcPath)) {
+          await fs.copy(srcPath, destPath, { overwrite: true });
+        } else {
+          spinner2.stop(pc.red(`Template file missing: ${file.templatePath}`));
+          p.log.warn(pc.dim(`Looked at path: ${srcPath}`));
+          return;
+        }
+      } else if (file.content) {
+        await fs.writeFile(destPath, file.content.trim() + "\n", "utf-8");
       }
     }
-    if (meta.dependencies && meta.dependencies.length > 0) {
-      spinner2.message(
-        `Installing required npm packages: ${meta.dependencies.join(", ")}...`
-      );
-      await execa("npm", ["install", ...meta.dependencies], {
-        cwd: projectRoot
-      });
-    }
-    spinner2.stop(pc.green(`\u2714 Added ${meta.name} into ${hasSrc ? "src/" : ""}components/ui/`));
+    const relativePath = `${hasSrc ? "src/" : ""}components/ui/`;
+    spinner2.stop(pc.green(`\u2714 Added ${meta.name} into ${relativePath}`));
   }
   p.outro(pc.green("All components successfully installed!"));
 }
 
 // src/index.ts
 var program = new Command();
-program.name("Canopy UI").description("Install custom modular UI components directly to your project").version("1.0.0");
-program.command("add").description("Add a component to your project").argument("[components...]", "Component identifiers (e.g., toast").action(async (components) => {
+program.name("canopy-ui").description("Install custom modular UI components directly to your project").version("1.0.0");
+program.command("add").description("Add a component to your project").argument("[components...]", "Component identifiers (e.g., toast)").action(async (components) => {
   await add(components);
 });
 program.parse(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marv3l/canopy-ui",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "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,21 +1,14 @@
 "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 semantic & dark-safe theme tokens
 const variantStyles: Record<
   string,
   {
@@ -26,7 +19,7 @@ const variantStyles: Record<
     progress: string;
     iconColor: string;
     badge: string;
-    icon: any;
+    icon: LucideIcon | null;
   }
 > = {
   default: {
@@ -79,9 +72,18 @@ const variantStyles: Record<
     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();
 
@@ -161,7 +163,6 @@ export function Toaster({ defaultDuration = 4000, position = "top-center" }: Toa
   );
 }
 
-// Atomic Toast Card Component
 function ToastElement({
   toast,
   defaultDuration,
@@ -171,44 +172,84 @@ 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;
 
-  // Reset lifespan timer whenever count or duration changes
+  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, toast.count, 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 isError = variant === "error";
+
   return (
     <div
+      role={isError ? "alert" : "status"}
+      aria-live={isError ? "assertive" : "polite"}
       style={customInlineStyle}
+      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 : ""} ${toast.className || ""}`}
     >
-      {/* Render icon if preset defines one */}
-      {IconComponent && (
-        <IconComponent
-          className={`w-5 h-5 mt-0.5 shrink-0 ${defaultStyle.iconColor}`}
-          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 */}
@@ -238,7 +279,6 @@ function ToastElement({
           )}
         </div>
 
-        {/* Collapsible/Expanding Description Wrapper */}
         {toast.description && (
           <div
             className="grid overflow-hidden"
@@ -260,28 +300,28 @@ function ToastElement({
           </div>
         )}
 
-        {/* Interactive Action Button Slot */}
         {toast.action && <div className="pt-2">{toast.action}</div>}
       </div>
 
-      {/* Close Button */}
       <button
         onClick={onDismiss}
+        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 (Resets on stack increment) */}
-      {duration > 0 && (
+      {/* Progress Bar resets animation on each state change */}
+      {showProgress && isAutoDismissible && (
         <div
-          key={toast.count}
+          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,113 +1,134 @@
 "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
+  /** Optional custom identifier. If omitted, a collision-resistant UUID is generated. */
   id?: string;
-  // Primary header text or React component
+  /** Primary title text or JSX element displayed in the toast header. */
   title?: React.ReactNode;
-  // Secondary descriptive message or details
+  /** Secondary explanatory text or JSX node rendered below the title. */
   description?: React.ReactNode;
-  // Optional action button or interactive element
+  /** Interactive action button or control rendered at the bottom of the toast. */
   action?: React.ReactNode;
-  // Visual style preset (success, error, warning, info, default, custom)
+  /** Visual variant styling preset. Defaults to "default". */
   variant?: ToastVariant;
-  // Individual lifespan in milliseconds; overrides the global layout default
+  /** Display duration in milliseconds before auto-dismissing. Set to 0 or Infinity to prevent auto-dismiss. */
   duration?: number;
-  // Maximum number of duplicate stacks allowed for this toast (defaults to 5)
+  /** Maximum number of duplicate message stacks allowed for this specific toast (defaults to 5). */
   maxCount?: number;
-  // User-defined custom styling parameters for dynamic themes
+  /** 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?: {
-    // 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
+  /** 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;
-  // Tracks duplicate trigger count
   count: number;
-  // Indicates if maximum stack limit has been hit
   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;
-// Default maximum stack limit for duplicate toast triggers
+
+/** Default duplicate stack cap if not overridden per toast. */
 const DEFAULT_MAX_COUNT = 5;
-// Delay before removed toasts are completely purged from memory (allows exit transition)
+
+/** Delay in ms before unmounting a dismissed toast from the state tree. */
 const TOAST_REMOVE_DELAY = 0;
 
-// Discriminated union type representing all possible reducer actions
+// -----------------------------------------------------------------------------
+// Action Types & State Management
+// -----------------------------------------------------------------------------
+
 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
 interface State {
   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);
 };
 
-// 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": {
-      // Find existing active toast with identical title, description, and variant
+      // 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 &&
@@ -133,7 +154,7 @@ export const reducer = (state: State, action: Action): State => {
           open: true,
         };
 
-        // Remove old instance and push updated version to the front
+        // Move updated toast to the top of the stack
         const rest = state.toasts.filter((t) => t.id !== existing.id);
         return {
           ...state,
@@ -141,9 +162,9 @@ export const reducer = (state: State, action: Action): State => {
         };
       }
 
+      // 3. New Toast: Prepend to list and truncate at TOAST_LIMIT
       return {
         ...state,
-        // Prepend new toast and enforce maximum visible limit
         toasts: [action.toast, ...state.toasts].slice(0, TOAST_LIMIT),
       };
     }
@@ -151,7 +172,6 @@ export const reducer = (state: State, action: Action): State => {
     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
         ),
@@ -160,17 +180,16 @@ export const reducer = (state: State, action: Action): State => {
     case "DISMISS_TOAST": {
       const { toastId } = action;
 
-      // If a specific ID is provided, schedule removal for only that toast
+      // Queue removal for specific toast or all active toasts
       if (toastId) {
         addToRemoveQueue(toastId);
       } else {
-        // Otherwise schedule removal for all currently open toasts
         state.toasts.forEach((toast) => addToRemoveQueue(toast.id));
       }
 
+      // Mark toast as closed to trigger exit transitions
       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
         ),
@@ -178,12 +197,9 @@ export const reducer = (state: State, action: Action): State => {
     }
 
     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),
       };
 
@@ -192,33 +208,33 @@ export const reducer = (state: State, action: Action): 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));
 }
 
-// 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: {
@@ -230,16 +246,85 @@ export function toast(props: ToastOptions) {
     },
   });
 
-  // Return control object allowing caller to dismiss or update toast programmatically
   return { id, dismiss, update };
 }
 
-// Custom React hook subscribing components to real-time toast updates
+/** 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,
+      });
+    });
+
+  return promiseFn;
+};
+
+// -----------------------------------------------------------------------------
+// React Consumer Hook
+// -----------------------------------------------------------------------------
+
+/**
+ * React hook providing reactive toast state, dispatchers, and dismissal handlers.
+ */
 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 () => {
@@ -248,9 +333,8 @@ export function useToast() {
         listeners.splice(index, 1);
       }
     };
-  }, []); // Empty array ensures registration only happens on mount/unmount
+  }, []);
 
-  // Expose current state, trigger function, and dismiss helper
   return {
     ...state,
     toast,