npm - @marv3l/canopy-ui - Versions diffs - 1.0.0 - Mend

@marv3l/canopy-ui 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/LICENSE +21 -0
package/README.md +261 -0
package/dist/index.js +99 -0
package/package.json +53 -0
package/templates/toast/toast.tsx +185 -0
package/templates/toast/use-toast.ts +214 -0

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 ShawnR04
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,261 @@
+# Canopy UI
+> A modern, copy-and-paste CLI for adding customizable UI components directly to React and Next.js codebases.
+Canopy UI installs component source code into your project, giving you full ownership over the markup, styles, behavior, and design tokens. Customize components as much as you need—without being locked into a hosted UI library.
+## Quick Start
+Add a component with one command:
+```bash
+npx canopy-ui add toast
+```
+Run the command without a component name to open an interactive multi-select prompt:
+```bash
+npx canopy-ui add
+```
+---
+## Components
+### Toast
+A customizable, animated notification system with:
+- Built-in `success` and `error` variants
+- Configurable global default duration
+- Configurable screen position
+- Per-toast duration overrides
+- Custom colors using hex values, CSS variables, or design tokens
+- Progress-bar color controls
+- Direct Tailwind `className` overrides
+## Installation
+Install the Toast component into your project:
+```bash
+npx canopy-ui add toast
+```
+The component is added to your local UI directory, typically under:
+```text
+components/ui/toast.tsx
+components/ui/use-toast.ts
+```
+> The exact generated paths may depend on your project's configured import aliases.
+---
+## Setup
+Mount `Toaster` once in your root `app/layout.tsx`. This provides the toast viewport for all routes in your application.
+```tsx
+import type { Metadata } from "next";
+import { Geist, Geist_Mono } from "next/font/google";
+import "./globals.css";
+import { Toaster } from "@/components/ui/toast";
+const geistSans = Geist({
+  variable: "--font-geist-sans",
+  subsets: ["latin"],
+});
+const geistMono = Geist_Mono({
+  variable: "--font-geist-mono",
+  subsets: ["latin"],
+});
+export const metadata: Metadata = {
+  title: "My App",
+  description: "My application",
+};
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html
+      lang="en"
+      className={`${geistSans.variable} ${geistMono.variable} h-full antialiased`}
+    >
+      <body className="flex min-h-full flex-col">
+        {children}
+        <Toaster defaultDuration={3500} position="top-center" />
+      </body>
+    </html>
+  );
+}
+```
+### `Toaster` Props
+| Prop | Type | Description |
+| --- | --- | --- |
+| `defaultDuration` | `number` | Default time, in milliseconds, before a toast dismisses. Individual toasts can override it. |
+| `position` | `string` | Position of the toast viewport, for example `"top-center"`. |
+---
+## Usage
+Import `toast` inside a client component, then call it from an event handler or client-side action.
+```tsx
+"use client";
+import { toast } from "@/components/ui/use-toast";
+export default function Page() {
+  return (
+    <button
+      onClick={() =>
+        toast({
+          variant: "success",
+          title: "Changes saved",
+          description: "Your preferences were updated successfully.",
+        })
+      }
+    >
+      Show toast
+    </button>
+  );
+}
+```
+---
+## Examples
+### Success Toast
+```tsx
+toast({
+  variant: "success",
+  title: "Changes saved",
+  description: "Your preferences were updated successfully.",
+});
+```
+### Error Toast
+```tsx
+toast({
+  variant: "error",
+  title: "Action failed",
+  description: "Could not connect to the remote server.",
+});
+```
+### Custom Colors and Duration
+Use `customColor` to override the toast palette. Values can be literal CSS colors, such as hex values, or CSS custom properties such as `var(--primary)`.
+```tsx
+toast({
+  title: "Pro subscription unlocked",
+  description: "Welcome to VIP perks and custom styling.",
+  duration: 5000,
+  customColor: {
+    bg: "var(--card)",
+    border: "var(--primary)",
+    text: "var(--card-foreground)",
+    icon: "var(--primary)",
+    progress: "var(--primary)",
+  },
+});
+```
+### Tailwind Class Override
+Use `className` when you want to apply direct Tailwind utility classes to an individual toast.
+```tsx
+toast({
+  title: "Tailwind classes applied",
+  description: "Styled with direct className overrides.",
+  duration: 3500,
+  customColor: {
+    progress: "var(--destructive)",
+  },
+  className: "border-destructive/40 bg-card text-primary",
+});
+```
+---
+## Toast API
+```ts
+toast({
+  variant?: "success" | "error";
+  title?: string;
+  description?: string;
+  duration?: number;
+  customColor?: {
+    bg?: string;
+    border?: string;
+    text?: string;
+    icon?: string;
+    progress?: string;
+  };
+  className?: string;
+});
+```
+| Option | Description |
+| --- | --- |
+| `variant` | Applies a built-in visual style, such as `"success"` or `"error"`. |
+| `title` | Primary toast message. |
+| `description` | Supporting text displayed below the title. |
+| `duration` | Dismiss timeout in milliseconds. Overrides `Toaster`’s `defaultDuration`. |
+| `customColor.bg` | Toast background color. |
+| `customColor.border` | Toast border color. |
+| `customColor.text` | Toast text color. |
+| `customColor.icon` | Toast icon color. |
+| `customColor.progress` | Toast progress-bar color. |
+| `className` | Tailwind or custom CSS classes applied directly to the toast. |
+---
+## Development
+Build the CLI:
+```bash
+npm run build
+```
+Link the package locally:
+```bash
+npm link
+```
+Then, inside a sample React or Next.js project, install a component through the linked CLI:
+```bash
+canopy-ui add toast
+```
+## Publishing
+Publish the package to npm:
+```bash
+npm publish --access public
+```
+## License
+MIT © Shawn Rimai

package/dist/index.js ADDED Viewed

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// src/index.ts
+import { Command } from "commander";
+// src/commands/add.ts
+import path from "path";
+import { fileURLToPath } from "url";
+import fs from "fs-extra";
+import { execa } from "execa";
+import * as p from "@clack/prompts";
+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"],
+    files: [
+      {
+        templatePath: "toast/toast.tsx",
+        targetName: "toast.tsx"
+      },
+      {
+        templatePath: "toast/use-toast.ts",
+        targetName: "use-toast.ts"
+      }
+    ]
+  }
+  // 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 add(componentKeys) {
+  p.intro(pc.bgCyan(pc.black(" Canopy UI ")));
+  let selected = componentKeys;
+  if (!selected || selected.length === 0) {
+    const choices = Object.keys(REGISTRY).map((key) => ({
+      value: key,
+      label: `${REGISTRY[key]?.name ?? key} (${key})`
+    }));
+    const response = await p.multiselect({
+      message: "Select UI components to install:",
+      options: choices,
+      required: true
+    });
+    if (p.isCancel(response)) {
+      p.cancel("Operation aborted.");
+      process.exit(0);
+    }
+    selected = response;
+  }
+  const projectRoot = process.cwd();
+  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);
+  const spinner2 = p.spinner();
+  for (const key of selected) {
+    const meta = REGISTRY[key];
+    if (!meta) {
+      p.log.error(`Component "${key}" was not found in registry.`);
+      continue;
+    }
+    spinner2.start(`Copying ${meta.name} source files...`);
+    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 (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/`));
+  }
+  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) => {
+  await add(components);
+});
+program.parse(process.argv);

package/package.json ADDED Viewed

@@ -0,0 +1,53 @@
+{
+  "name": "@marv3l/canopy-ui",
+  "version": "1.0.0",
+  "description": "An accessible, themable React UI component library built for fast-moving web applications.",
+  "main": "./dist/index.js",
+  "bin": {
+    "canopy-ui": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShawnR04/canopy-ui.git"
+  },
+  "keywords": [
+    "react",
+    "ui",
+    "toast",
+    "shadcn",
+    "components",
+    "cli"
+  ],
+  "author": "Shawn Rimai",
+  "license": "MIT",
+  "type": "module",
+  "bugs": {
+    "url": "https://github.com/ShawnR04/canopy-ui/issues"
+  },
+  "homepage": "https://github.com/ShawnR04/canopy-ui#readme",
+  "dependencies": {
+    "@clack/prompts": "^1.7.0",
+    "commander": "^15.0.0",
+    "execa": "^10.0.1",
+    "fs-extra": "^11.4.0",
+    "lucide-react": "^1.31.0",
+    "ora": "^9.4.1",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^26.2.0",
+    "tsup": "^8.5.1",
+    "typescript": "^7.0.2"
+  }
+}

package/templates/toast/toast.tsx ADDED Viewed

@@ -0,0 +1,185 @@
+"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 { 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 }
+> = {
+  default: {
+    bg: "bg-card",
+    border: "border-border",
+    text: "text-card-foreground",
+    progress: "bg-foreground/20",
+    icon: null,
+  },
+  success: {
+    bg: "bg-success-bg",
+    border: "border-success/40",
+    text: "text-success",
+    progress: "bg-success",
+    icon: CheckCircle2,
+  },
+  error: {
+    bg: "bg-destructive/10",
+    border: "border-destructive/30",
+    text: "text-destructive",
+    progress: "bg-destructive",
+    icon: AlertCircle,
+  },
+  warning: {
+    bg: "bg-warning-bg",
+    border: "border-warning/40",
+    text: "text-warning",
+    progress: "bg-warning",
+    icon: AlertTriangle,
+  },
+  info: {
+    bg: "bg-accent",
+    border: "border-primary/30",
+    text: "text-accent-foreground",
+    progress: "bg-primary",
+    icon: Info,
+  },
+};
+// Root Toaster Component placed into layout.tsx
+export function Toaster({ defaultDuration = 4000, position = "top-center" }: ToasterProps) {
+  const { toasts, dismiss } = useToast();
+  const positionClasses = {
+    "top-right": "top-4 right-4 items-end",
+    "top-left": "top-4 left-4 items-start",
+    "bottom-right": "bottom-4 right-4 items-end",
+    "bottom-left": "bottom-4 left-4 items-start",
+    "top-center": "top-4 left-1/2 -translate-x-1/2 items-center",
+    "bottom-center": "bottom-4 left-1/2 -translate-x-1/2 items-center",
+  }[position];
+  return (
+    <>
+      <style>{`
+        @keyframes toast-progress {
+          from {
+            transform: scaleX(1);
+          }
+          to {
+            transform: scaleX(0);
+          }
+        }
+      `}</style>
+      <div className={`fixed z-50 pointer-events-none flex flex-col gap-2 p-4 w-full max-w-sm ${positionClasses}`}>
+        {toasts.map((item) => (
+          <ToastElement
+            key={item.id}
+            toast={item}
+            defaultDuration={defaultDuration}
+            onDismiss={() => dismiss(item.id)}
+          />
+        ))}
+      </div>
+    </>
+  );
+}
+// Atomic Toast Card Component
+function ToastElement({
+  toast,
+  defaultDuration,
+  onDismiss,
+}: {
+  toast: ToastItem;
+  defaultDuration: number;
+  onDismiss: () => void;
+}) {
+  const duration = toast.duration ?? defaultDuration;
+  React.useEffect(() => {
+    if (duration <= 0) return;
+    const timer = setTimeout(() => {
+      onDismiss();
+    }, duration);
+    return () => clearTimeout(timer);
+  }, [duration, onDismiss]);
+  const variant = toast.variant || "default";
+  const defaultStyle = variantStyles[variant] || variantStyles.default;
+  const IconComponent = 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-/));
+  return (
+    <div
+      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 ${
+        !userHasBg ? defaultStyle.bg : ""
+      } ${!userHasBorder ? defaultStyle.border : ""} ${
+        !userHasText ? defaultStyle.text : ""
+      } ${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 Content Area */}
+      <div className="flex-1 text-sm space-y-1">
+        {toast.title && <div className="font-semibold leading-tight">{toast.title}</div>}
+        {toast.description && (
+          <div className="opacity-90 leading-relaxed text-xs">
+            {toast.description}
+          </div>
+        )}
+        {toast.action && <div className="pt-1">{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"
+      >
+        <X className="w-4 h-4" />
+      </button>
+      {/* Animated Lifespan Progress Bar */}
+      {duration > 0 && (
+        <div
+          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`,
+          }}
+        />
+      )}
+    </div>
+  );
+}

package/templates/toast/use-toast.ts ADDED Viewed

@@ -0,0 +1,214 @@
+"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";
+// 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;
+}
+// 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;
+}
+// Maximum number of visible toast cards on screen simultaneously
+const TOAST_LIMIT = 5;
+// Delay before removed toasts are completely purged from memory (allows exit transition)
+const TOAST_REMOVE_DELAY = 1000;
+// 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
+interface State {
+    toasts: ToastItem[];
+}
+// Monotonically increasing counter for collision-free ID generation
+let count = 0;
+// Generates unique string identifiers for toast items
+function genId(): string {
+    count = (count + 1) % Number.MAX_SAFE_INTEGER;
+    return count.toString();
+}
+// Map tracking active removal timers to prevent duplicate schedule queues
+const toastTimeouts = new Map<string, ReturnType<typeof setTimeout>>();
+// Schedule the hard removal of a dismissed toast after its exit animation completes
+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
+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;
+    }
+};
+// Array of subscriber callbacks implementing the Observer pattern
+const listeners: Array<(state: State) => void> = [];
+// Singleton state variable preserving toast state across entire application
+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)
+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,
+        },
+    });
+    // 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
+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
+    // Expose current state, trigger function, and dismiss helper
+    return {
+        ...state,
+        toast,
+        dismiss: (toastId?: string) => dispatch({ type: "DISMISS_TOAST", toastId }),
+    };
+}