@loke/design-system/dist/components/toast/toast.d.ts

A design system with individually importable components

import React from "react";
/**
 * Defines the available appearance types for toast notifications.
 */
export type ToastTypes = "normal" | "action" | "success" | "info" | "warning" | "error" | "loading" | "default";
/**
 * Represents either a Promise or a function that returns a Promise.
 * Used for the promise property in toast notifications to track async operations.
 */
export type PromiseT<Data = unknown> = Promise<Data> | (() => Promise<Data>);
/**
 * Collection of custom icons that can be provided to override the default toast icons.
 */
interface ToastIcons {
    /** Custom icon to display for the toast close button */
    close?: React.ReactNode;
    /** Custom icon to display for error toast notifications */
    error?: React.ReactNode;
    /** Custom icon to display for informational toast notifications */
    info?: React.ReactNode;
    /** Custom icon to display for loading toast notifications */
    loading?: React.ReactNode;
    /** Custom icon to display for success toast notifications */
    success?: React.ReactNode;
    /** Custom icon to display for warning toast notifications */
    warning?: React.ReactNode;
}
/**
 * Represents an action button that can be added to a toast notification.
 */
interface Action {
    /** The content to display on the action button */
    label: React.ReactNode;
    onClick: (event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void;
}
/**
 * Configuration object for an individual toast notification.
 */
interface ToastT {
    /** Primary action button or custom component shown on the toast */
    action?: Action | React.ReactNode;
    /** Secondary/cancel action button or custom component shown on the toast */
    cancel?: Action | React.ReactNode;
    /** Whether to show a close button on this toast */
    closeButton?: boolean;
    /** When true, marks the toast for deletion */
    delete?: boolean;
    /** Secondary content displayed below the title, can be a React node or a function returning a React node */
    description?: (() => React.ReactNode) | React.ReactNode;
    /** Whether this toast can be dismissed by user actions like swiping or clicking close */
    dismissible?: boolean;
    /** Time in milliseconds before the toast auto-dismisses (0 or Infinity to prevent auto-dismiss) */
    duration?: number;
    /** Custom icon to display, overrides the default icon for the selected type */
    icon?: React.ReactNode;
    /** Unique identifier for the toast */
    id: number | string;
    /** Callback fired when the toast is automatically closed after its duration expires */
    onAutoClose?: (toast: ToastT) => void;
    /** Callback fired when the toast is dismissed by user action */
    onDismiss?: (toast: ToastT) => void;
    /** Promise to track for loading/success/error states - used for promise-based toast creation */
    promise?: PromiseT;
    /** Primary content of the toast, can be a React node or a function returning a React node */
    title?: (() => React.ReactNode) | React.ReactNode;
    /** Visual appearance type for the toast */
    type?: ToastTypes;
}
/**
 * Global configuration options that can be applied to all toasts.
 */
interface ToastOptions {
    /** Whether to show close buttons on all toasts */
    closeButton?: boolean;
    /** Accessibility label for close buttons */
    closeButtonAriaLabel?: string;
    /** Default duration in milliseconds before toasts auto-dismiss */
    duration?: number;
}
/**
 * Defines positioning offsets for the toast container.
 * Can be a simple value applied to all sides, or an object with specific values per side.
 */
type Offset = {
    /** Distance from the top edge of the viewport */
    top?: string | number;
    /** Distance from the right edge of the viewport */
    right?: string | number;
    /** Distance from the bottom edge of the viewport */
    bottom?: string | number;
    /** Distance from the left edge of the viewport */
    left?: string | number;
} | string | number;
/**
 * Props for the Toaster component that manages and displays toasts.
 */
interface ToasterProps {
    /** Whether to show a close button on toasts by default */
    closeButton?: boolean;
    /** Accessibility label for the toast container */
    containerAriaLabel?: string;
    /** Default duration in milliseconds that toasts remain visible */
    duration?: number;
    /** When true, toasts remain expanded by default instead of collapsing */
    expand?: boolean;
    /** Spacing between toasts in pixels */
    gap?: number;
    /** Array of keys used as a keyboard shortcut to focus the toast list */
    hotkey?: (keyof KeyboardEvent | "KeyT")[];
    /** Custom icon components to override defaults */
    icons?: ToastIcons;
    /** Positioning offset for mobile viewport */
    mobileOffset?: Offset;
    /** Positioning offset from viewport edges */
    offset?: Offset;
    /** Options applied to all toasts */
    toastOptions?: ToastOptions;
    /** Maximum number of toasts visible at once */
    visibleToasts?: number;
}
/**
 * Instructions to dismiss a specific toast by ID.
 * Used internally by the toast state management system.
 */
interface ToastToDismiss {
    /** Flag indicating the toast should be dismissed */
    dismiss: boolean;
    /** ID of the toast to dismiss */
    id: number | string;
}
/**
 * Hook for consuming toasts within components
 *
 * This hook provides access to active toasts from the global toast state.
 * Use this hook to retrieve the current list of active toasts within any component.
 */
declare function useToasts(): {
    toasts: ToastT[];
};
/**
 * Toaster component for managing and displaying toast notifications
 *
 * The Toaster component provides a container for displaying toast notifications in a consistent,
 * accessible way. It manages the visibility, positioning, and interaction behavior of toasts.
 *
 * Key features:
 * - Stacked arrangement of multiple toasts
 * - Keyboard support with customizable hotkeys
 * - Responsive positioning for different screen sizes
 * - Accessibility support with appropriate ARIA attributes
 * - Expand/collapse behavior for managing multiple notifications
 *
 * Usage considerations:
 * - Place a single Toaster component at the root of your application
 * - Use the useToasts hook to programmatically trigger toasts from any component
 * - Configure default behavior through props for consistent notifications
 */
declare const Toaster: React.ForwardRefExoticComponent<ToasterProps & React.RefAttributes<HTMLElement>>;
export { Toaster, useToasts };
export type { Action, ToastToDismiss, ToastT };