Toast Notifications

/**
 * Provides toast notification behavior and accessibility
 * @param props - Toast configuration options
 * @param state - Toast state from useToastState
 * @param ref - Ref to the toast element
 * @returns Toast props and state
 */
function useToast(props: AriaToastProps, state: ToastState, ref: RefObject<Element>): ToastAria;

interface AriaToastProps {
  /** Priority level of the toast for screen readers */
  priority?: 'low' | 'high';
  /** Whether the toast can be dismissed by the user */
  isDismissible?: boolean;
  /** Handler called when the toast is dismissed */
  onClose?: () => void;
  /** Timeout in milliseconds before auto-dismissal */
  timeout?: number;
  /** Animation duration for enter/exit transitions */
  animation?: 'none' | 'slide' | 'fade';
}

interface ToastAria {
  /** Props to spread on the toast element */
  toastProps: DOMAttributes<Element>;
  /** Props for the close button (if dismissible) */
  closeButtonProps: DOMAttributes<Element>;
  /** Whether the toast is currently visible */
  isVisible: boolean;
}

import { useToast } from "react-aria";
import { useToastState } from "react-stately";

function Toast(props) {
  let state = useToastState(props);
  let ref = useRef();
  let { toastProps, closeButtonProps, isVisible } = useToast(props, state, ref);

  if (!isVisible) return null;

  return (
    <div {...toastProps} ref={ref} className="toast">
      <div className="toast-content">{props.children}</div>
      {props.isDismissible && (
        <button {...closeButtonProps} className="toast-close">
          ×
        </button>
      )}
    </div>
  );
}

/**
 * Provides toast region behavior for managing multiple toast notifications
 * @param props - Toast region configuration
 * @param state - Toast region state from useToastRegionState
 * @param ref - Ref to the toast region element
 * @returns Toast region props
 */
function useToastRegion(props: AriaToastRegionProps, state: ToastRegionState, ref: RefObject<Element>): ToastRegionAria;

interface AriaToastRegionProps {
  /** Maximum number of toasts to display simultaneously */
  maxToasts?: number;
  /** Position of the toast region on screen */
  position?: 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
  /** Whether toasts should be announced to screen readers */
  hasLiveRegion?: boolean;
  /** ARIA live region politeness setting */
  politeness?: 'polite' | 'assertive';
}

interface ToastRegionAria {
  /** Props to spread on the toast region container */
  regionProps: DOMAttributes<Element>;
  /** Props for the ARIA live region */
  liveRegionProps: DOMAttributes<Element>;
}

import { useToastRegion } from "react-aria";
import { useToastRegionState } from "react-stately";

function ToastRegion(props) {
  let state = useToastRegionState(props);
  let ref = useRef();
  let { regionProps, liveRegionProps } = useToastRegion(props, state, ref);

  return (
    <div {...regionProps} ref={ref} className="toast-region">
      <div {...liveRegionProps} />
      {state.toasts.map((toast) => (
        <Toast key={toast.key} {...toast} />
      ))}
    </div>
  );
}

interface ToastState {
  /** Collection of active toasts */
  toasts: Collection<ToastItem>;
  /** Add a new toast to the region */
  add(toast: ToastItem): string;
  /** Remove a toast by key */
  remove(key: string): void;
  /** Clear all toasts */
  clear(): void;
}

interface ToastRegionState {
  /** Collection of active toast regions */
  regions: Collection<ToastRegion>;
  /** Default toast region */
  defaultRegion: ToastRegion;
}

interface ToastItem {
  /** Unique identifier for the toast */
  key: string;
  /** Toast content */
  content: ReactNode;
  /** Toast priority level */
  priority: 'low' | 'high';
  /** Whether the toast is dismissible */
  isDismissible: boolean;
  /** Auto-dismiss timeout */
  timeout?: number;
}