import type { ToasterProps } from 'vue-sonner';

/**
 * Toast notification container (Sonner). Place once near the app root,
 * then call `toast()` (or `toast.success()`, `toast.error()`, etc.) from
 * anywhere to display a non-blocking notification.
 * @category Feedback
 * @useCases success confirmation, error notice, undo action, async progress, background updates
 * @keywords snackbar, toast, sonner, notification, alert, message, banner, undo
 * @related UiAlert, UiAlertDialog
 */
export type UiSnackbarProps = {
  /**
   * Where toasts appear on screen.
   * @default 'bottom-right'
   */
  position?: ToasterProps['position'];
  /**
   * Color theme for toasts.
   * @default 'light'
   */
  theme?: ToasterProps['theme'];
  /** Mirror the body color scheme so toasts contrast against it. */
  invert?: ToasterProps['invert'];
  /**
   * Apply colored backgrounds for `success`, `error`, `info`, and `warning` toasts.
   *
   * Accessibility: color must not be the only signal of toast type
   * (WCAG 1.4.1 Use of Color). Always pair with a descriptive message
   * and/or icon so the meaning is conveyed to users who cannot perceive
   * the color difference.
   */
  richColors?: ToasterProps['richColors'];
  /** Show all stacked toasts expanded by default instead of collapsed. */
  expand?: ToasterProps['expand'];
  /**
   * Show a close (X) button on every toast.
   *
   * Accessibility: recommended whenever toasts have non-trivial
   * `duration` values or contain actions, so keyboard and screen
   * reader users can dismiss them on their own terms. The close
   * button has an accessible name of `'Close toast'` by default;
   * customise via `toastOptions.closeButtonAriaLabel`.
   */
  closeButton?: ToasterProps['closeButton'];
  /** Position of the close button within each toast. */
  closeButtonPosition?: ToasterProps['closeButtonPosition'];
  /**
   * Default duration in milliseconds before a toast auto-dismisses.
   * Pass `Infinity` to keep toasts open until dismissed.
   *
   * Accessibility: very short durations can violate WCAG 2.2.1
   * (Timing Adjustable). For toasts that carry critical information
   * or actions (e.g. an Undo button), prefer longer durations or
   * `Infinity` combined with `closeButton: true` so users with
   * cognitive or motor impairments have time to read and respond.
   */
  duration?: ToasterProps['duration'];
  /** Pixel gap between stacked toasts. */
  gap?: ToasterProps['gap'];
  /**
   * Maximum number of toasts visible at the same time.
   * @default 3
   */
  visibleToasts?: ToasterProps['visibleToasts'];
  /** Offset from the viewport edges. Accepts a string, number, or per-side object. */
  offset?: ToasterProps['offset'];
  /** Offset used on mobile viewports. */
  mobileOffset?: ToasterProps['mobileOffset'];
  /** Document writing direction. */
  dir?: ToasterProps['dir'];
  /**
   * Keyboard combination that focuses the toast region.
   * Provides a keyboard escape hatch (WCAG 2.1.1 Keyboard) so users
   * can reach toasts without a pointing device. Document the chosen
   * combination in your app's keyboard-shortcuts help.
   * @default ['altKey', 'KeyT']
   */
  hotkey?: ToasterProps['hotkey'];
  /** Directions in which a toast can be dismissed by swipe. */
  swipeDirections?: ToasterProps['swipeDirections'];
  /** Custom icons used for each toast type. */
  icons?: ToasterProps['icons'];
  /** Default options applied to every toast. */
  toastOptions?: ToasterProps['toastOptions'];
  /**
   * Accessible label announced to screen readers for the live region wrapping all toasts.
   *
   * The default `'Notifications'` is sufficient for most apps. Override only
   * when you need a localized label or when multiple Toaster instances exist
   * on the same page and need to be distinguishable to assistive technology.
   * @default 'Notifications'
   */
  containerAriaLabel?: ToasterProps['containerAriaLabel'];
  /** Identifier when rendering more than one Toaster instance. */
  id?: ToasterProps['id'];
};
