Toast API

/**
 * Creates a default toast notification
 * @param content - The content to display in the toast
 * @param options - Optional configuration for the toast
 * @returns Toast ID for programmatic control
 */
function toast<T = {}>(content: ToastContent<T>, options?: ToastOptions<T>): Id;

import { toast } from 'react-toastify';

// Simple text toast
toast("Hello World!");

// Toast with options
toast("Custom toast", {
  position: "top-center",
  autoClose: 5000,
  hideProgressBar: false,
  closeOnClick: true,
  pauseOnHover: true,
  draggable: true,
});

// Toast with React component
toast(<div>Custom <strong>HTML</strong> content</div>);

// Toast with render function
toast(({ closeToast }) => (
  <div>
    Custom content with <button onClick={closeToast}>Close</button>
  </div>
));

/**
 * Creates a success toast with green styling and checkmark icon
 */
toast.success(content: ToastContent<T>, options?: ToastOptions<T>): Id;

/**
 * Creates an error toast with red styling and error icon
 */
toast.error(content: ToastContent<T>, options?: ToastOptions<T>): Id;

/**
 * Creates a warning toast with orange styling and warning icon
 */
toast.warning(content: ToastContent<T>, options?: ToastOptions<T>): Id;

/**
 * Alias for toast.warning
 */
toast.warn(content: ToastContent<T>, options?: ToastOptions<T>): Id;

/**
 * Creates an info toast with blue styling and info icon
 */
toast.info(content: ToastContent<T>, options?: ToastOptions<T>): Id;

/**
 * Creates a loading toast with spinner icon and no auto-close
 */
toast.loading(content: ToastContent<T>, options?: ToastOptions<T>): Id;

/**
 * Creates a toast with dark theme styling
 */
toast.dark(content: ToastContent<T>, options?: ToastOptions<T>): Id;

// Type-specific toasts
toast.success("Operation completed successfully!");
toast.error("Something went wrong!");
toast.warning("Please check your input");
toast.info("New update available");

// Loading toast (doesn't auto-close)
const loadingId = toast.loading("Saving...");
// Later update or dismiss it
toast.dismiss(loadingId);

/**
 * Dismisses one or all toast notifications
 * @param id - Optional toast ID. If not provided, dismisses all toasts
 */
toast.dismiss(id?: Id): void;

/**
 * Updates an existing toast notification
 * @param id - The ID of the toast to update
 * @param options - New options to apply to the toast
 */
toast.update<T = {}>(id: Id, options: UpdateOptions<T>): void;

/**
 * Checks if a toast is currently active/visible
 * @param id - The toast ID to check
 * @param containerId - Optional container ID to check within
 * @returns True if the toast is active, false otherwise
 */
toast.isActive(id: Id, containerId?: Id): boolean;

/**
 * Clears the waiting queue of toasts
 * @param params - Optional parameters for selective clearing
 */
toast.clearWaitingQueue(params?: ClearWaitingQueueParams): void;

/**
 * Resumes toast timers (useful after pausing)
 * @param opts - Optional parameters
 */
toast.play(opts?: { id?: Id; containerId?: Id }): void;

/**
 * Pauses toast timers
 * @param opts - Optional parameters
 */
toast.pause(opts?: { id?: Id; containerId?: Id }): void;

/**
 * Marks a controlled progress toast as complete
 * @param id - The toast ID to mark as done
 */
toast.done(id: Id): void;

// Store toast ID for later control
const toastId = toast("Processing...", { autoClose: false });

// Update the toast
toast.update(toastId, {
  render: "Processing complete!",
  type: "success",
  autoClose: 3000
});

// Check if toast is still active
if (toast.isActive(toastId)) {
  console.log("Toast is still visible");
}

// Dismiss specific toast
toast.dismiss(toastId);

// Dismiss all toasts
toast.dismiss();

// Clear waiting queue when limit is reached
toast.clearWaitingQueue();

/**
 * Handles promise states automatically with toast notifications
 * @param promise - Promise to monitor or function returning a promise
 * @param messages - Messages for different promise states
 * @param options - Optional configuration
 * @returns The original promise (for chaining)
 */
toast.promise<T, E = any, P = {}>(
  promise: Promise<T> | (() => Promise<T>),
  messages: ToastPromiseParams<T, E, P>,
  options?: ToastOptions<P>
): Promise<T>;

interface ToastPromiseParams<T = {}, E = {}, P = {}> {
  pending?: ToastContent<P> | UpdateOptions<P>;
  success?: ToastContent<T> | UpdateOptions<T> | ((data: T) => ToastContent<T> | UpdateOptions<T>);
  error?: ToastContent<E> | UpdateOptions<E> | ((error: E) => ToastContent<E> | UpdateOptions<E>);
}

// Basic promise handling
const myPromise = fetch('/api/data');

toast.promise(
  myPromise,
  {
    pending: 'Loading data...',
    success: 'Data loaded successfully!',
    error: 'Failed to load data'
  }
);

// Advanced promise handling with custom options
toast.promise(
  fetch('/api/save'),
  {
    pending: {
      render: 'Saving your changes...',
      icon: false,
    },
    success: {
      render: 'Changes saved!',
      type: 'success',
      icon: '🎉',
      autoClose: 2000
    },
    error: {
      render: ({ data }) => {
        // Access error data
        return `Error: ${data.message}`;
      }
    }
  }
);

// Promise with dynamic content
toast.promise(
  uploadFile(file),
  {
    pending: 'Uploading file...',
    success: (data) => `File ${data.filename} uploaded successfully!`,
    error: (error) => `Upload failed: ${error.message}`
  }
);

/**
 * Subscribe to toast change events
 * @param callback - Function called when toasts are added, updated, or removed
 * @returns Unsubscribe function
 */
toast.onChange(callback: OnChangeCallback): () => void;

type OnChangeCallback = (payload: ToastItem) => void;

interface ToastItem<T = {}> {
  content: ToastContent<T>;
  id: Id;
  theme?: Theme;
  type?: TypeOptions;
  isLoading?: boolean;
  containerId?: Id;
  data: T;
  icon?: ToastIcon;
  status: ToastItemStatus;
}

type ToastItemStatus = 'added' | 'removed' | 'updated';

// Subscribe to toast changes
const unsubscribe = toast.onChange((payload) => {
  switch (payload.status) {
    case 'added':
      console.log('Toast added:', payload.id);
      break;
    case 'updated':
      console.log('Toast updated:', payload.id);
      break;
    case 'removed':
      console.log('Toast removed:', payload.id);
      break;
  }
});

// Later unsubscribe
unsubscribe();

interface UpdateOptions<T = {}> extends Omit<ToastOptions<T>, 'toastId'> {
  render?: ToastContent<T>;
}

interface ClearWaitingQueueParams {
  containerId?: Id;
}

type DraggableDirection = 'x' | 'y';

type ToastIcon = 
  | React.ReactElement 
  | string 
  | number 
  | boolean 
  | ((props: IconProps) => React.ReactElement) 
  | false;