@neynar/ui 0.1.1 → 0.1.2

package/src/components/ui/sonner.tsx

@@ -1,17 +1,233 @@
 import { useTheme } from "@/hooks/use-theme";
 import { Toaster as Sonner, type ToasterProps, toast } from "sonner";
 
+/**
+ * Props for Toaster (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace sonner library inferred types
+ *
+ * Toast notification container configuration that extends the base ToasterProps from the sonner library
+ * with enhanced theming integration. All props are optional and have sensible defaults for most use cases.
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type ToasterDocsProps = {
+  /**
+   * Controls whether to invert toast colors for better contrast
+   * Useful when the container background differs significantly from the expected theme
+   * @default false
+   */
+  invert?: boolean;
+
+  /**
+   * Theme mode for toast styling
+   * Automatically synced with application theme via useTheme hook when not specified
+   * @default "system" (auto-detected from useTheme)
+   */
+  theme?: "light" | "dark" | "system";
+
+  /**
+   * Position of toasts on the screen
+   * Determines where new toasts appear and how they stack
+   * @default "bottom-right"
+   */
+  position?:
+    | "top-left"
+    | "top-right"
+    | "bottom-left"
+    | "bottom-right"
+    | "top-center"
+    | "bottom-center";
+
+  /**
+   * Keyboard shortcut to focus the toast region
+   * Array of key modifiers and key codes for accessibility
+   * @default ["altKey", "KeyT"]
+   */
+  hotkey?: string[];
+
+  /**
+   * Enable enhanced colors for different toast types
+   * Provides more vibrant and distinct colors for success, error, warning, and info toasts
+   * @default false
+   */
+  richColors?: boolean;
+
+  /**
+   * Expand toasts by default to show full content
+   * When true, toasts don't require hover to show full text
+   * @default false
+   */
+  expand?: boolean;
+
+  /**
+   * Default duration in milliseconds before auto-dismiss
+   * Individual toasts can override this value
+   * @default 4000
+   */
+  duration?: number;
+
+  /**
+   * Spacing between toasts in pixels
+   * Controls the visual separation between stacked toasts
+   * @default 14
+   */
+  gap?: number;
+
+  /**
+   * Maximum number of toasts visible simultaneously
+   * Older toasts are automatically dismissed when limit is reached
+   * @default 3
+   */
+  visibleToasts?: number;
+
+  /**
+   * Show close button on each toast
+   * Provides manual dismiss option for users
+   * @default false
+   */
+  closeButton?: boolean;
+
+  /**
+   * Default options applied to all toasts
+   * Individual toast calls can override these defaults
+   */
+  toastOptions?: {
+    /** Additional CSS classes for toast elements */
+    className?: string;
+    /** Show close button for individual toasts @default false */
+    closeButton?: boolean;
+    /** CSS classes for description text */
+    descriptionClassName?: string;
+    /** Inline styles for toast container */
+    style?: React.CSSProperties;
+    /** Styles for cancel button */
+    cancelButtonStyle?: React.CSSProperties;
+    /** Styles for action button */
+    actionButtonStyle?: React.CSSProperties;
+    /** Duration before auto-dismiss in milliseconds */
+    duration?: number;
+    /** Remove default styling to allow full custom styling @default false */
+    unstyled?: boolean;
+    /** CSS class overrides for specific toast elements */
+    classNames?: {
+      toast?: string;
+      title?: string;
+      description?: string;
+      loader?: string;
+      closeButton?: string;
+      cancelButton?: string;
+      actionButton?: string;
+      success?: string;
+      error?: string;
+      info?: string;
+      warning?: string;
+      loading?: string;
+      default?: string;
+      content?: string;
+      icon?: string;
+    };
+    /** Accessible label for close button */
+    closeButtonAriaLabel?: string;
+  };
+
+  /**
+   * Additional CSS classes for the toast container
+   * Applied to the root toaster element
+   */
+  className?: string;
+
+  /**
+   * Additional inline styles for the toast container
+   * Applied to the root toaster element
+   */
+  style?: React.CSSProperties;
+
+  /**
+   * Offset from viewport edges
+   * Can be a number (pixels), string with units, or object with directional offsets
+   * @default 32
+   */
+  offset?:
+    | string
+    | number
+    | {
+        top?: string | number;
+        right?: string | number;
+        bottom?: string | number;
+        left?: string | number;
+      };
+
+  /**
+   * Offset specifically for mobile viewports
+   * Overrides offset on mobile devices for better UX
+   */
+  mobileOffset?:
+    | string
+    | number
+    | {
+        top?: string | number;
+        right?: string | number;
+        bottom?: string | number;
+        left?: string | number;
+      };
+
+  /**
+   * Text direction for toast content
+   * Controls layout direction for RTL languages
+   * @default "ltr"
+   */
+  dir?: "rtl" | "ltr" | "auto";
+
+  /**
+   * Allowed swipe directions for dismissing toasts
+   * Controls which gestures can dismiss toasts on touch devices
+   * @default ["right"] for left positions, ["left"] for right positions
+   */
+  swipeDirections?: ("top" | "right" | "bottom" | "left")[];
+
+  /**
+   * Custom icons for different toast types
+   * Override default icons with your own components
+   */
+  icons?: {
+    success?: React.ReactNode;
+    info?: React.ReactNode;
+    warning?: React.ReactNode;
+    error?: React.ReactNode;
+    loading?: React.ReactNode;
+    close?: React.ReactNode;
+  };
+
+  /**
+   * Accessible label for the toast container region
+   * Announced to screen readers when toasts appear
+   * @default "Notifications"
+   */
+  containerAriaLabel?: string;
+} & ToasterProps;
+
 /**
  * Toast notification container component built on Sonner
  *
- * An opinionated toast component that provides beautiful, accessible notifications
- * with minimal setup. Automatically integrates with the theme system and provides
- * consistent styling across the application. This is the recommended toast solution
- * for @neynar/ui projects, replacing previous toast implementations.
+ * A feature-rich toast component that provides beautiful, accessible notifications
+ * with seamless theme integration and extensive customization options. Built on the
+ * popular Sonner library with enhanced theming that automatically synchronizes with
+ * the application's theme system using the useTheme hook.
  *
- * @example
+ * This component serves as the central toast container and should be placed once in
+ * your application root. It manages the display, positioning, and lifecycle of all
+ * toast notifications throughout your application.
+ *
+ * **Key Features:**
+ * - **Automatic theme synchronization** - Integrates with useTheme for consistent styling
+ * - **Flexible positioning** - Six different positions with smart stacking
+ * - **Rich accessibility** - Full keyboard navigation and screen reader support
+ * - **Promise integration** - Built-in loading/success/error states for async operations
+ * - **Gesture support** - Touch-friendly swipe-to-dismiss with configurable directions
+ * - **Performance optimized** - Efficient rendering with configurable limits
+ * - **Customizable styling** - Comprehensive theming and custom icon support
+ *
+ * @example Basic setup in root layout
  * ```tsx
- * // Add to your app root layout
  * import { Toaster } from '@neynar/ui/components/ui/sonner';
  *
  * export default function RootLayout({ children }) {
@@ -26,76 +242,138 @@ import { Toaster as Sonner, type ToasterProps, toast } from "sonner";
  * }
  * ```
  *
- * @example
+ * @example Basic toast usage from anywhere in your app
  * ```tsx
- * // Basic toast usage from anywhere in your app
- * import { toast } from 'sonner';
+ * import { toast } from '@neynar/ui/components/ui/sonner';
  *
  * // Simple notification
  * toast('Cast published successfully');
  *
- * // Success variant
+ * // Success variant with icon
  * toast.success('Profile updated');
  *
- * // With description and action
+ * // Rich toast with description and action
  * toast('Event created', {
  *   description: 'Sunday, December 03, 2023 at 9:00 AM',
  *   action: {
  *     label: 'Undo',
- *     onClick: () => console.log('Undo')
+ *     onClick: () => handleUndo()
  *   }
  * });
+ *
+ * // Error with custom styling
+ * toast.error('Upload failed', {
+ *   description: 'File size must be less than 10MB',
+ *   className: 'error-toast'
+ * });
  * ```
  *
- * @example
+ * @example Promise-based toasts for async operations
  * ```tsx
- * // Promise-based toasts for async operations
- * toast.promise(saveData(), {
- *   loading: 'Saving changes...',
- *   success: 'Data saved successfully!',
- *   error: 'Failed to save changes'
+ * import { toast } from '@neynar/ui/components/ui/sonner';
+ *
+ * // Automatically handles loading/success/error states
+ * toast.promise(saveUserProfile(data), {
+ *   loading: 'Saving profile changes...',
+ *   success: (result) => `Profile updated for ${result.username}`,
+ *   error: 'Failed to save profile changes'
+ * });
+ *
+ * // With custom duration and retry action
+ * toast.promise(uploadFile(file), {
+ *   loading: 'Uploading file...',
+ *   success: 'File uploaded successfully',
+ *   error: (error) => ({
+ *     message: 'Upload failed',
+ *     description: error.message,
+ *     action: {
+ *       label: 'Retry',
+ *       onClick: () => uploadFile(file)
+ *     }
+ *   })
  * });
  * ```
  *
- * @example
+ * @example Custom positioned toaster with enhanced styling
  * ```tsx
- * // Custom configuration
  * <Toaster
  *   position="top-center"
  *   expand={true}
  *   richColors
  *   duration={5000}
  *   closeButton
+ *   visibleToasts={5}
+ *   gap={16}
+ *   offset={64}
  * />
  * ```
  *
- * @param props - Configuration options for the toast container
- * @param props.position - Position of toasts on screen. Options: "top-left", "top-center", "top-right", "bottom-left", "bottom-center", "bottom-right". Default: "bottom-right"
- * @param props.hotkey - Keyboard shortcut to focus toasts. Default: ["altKey", "KeyT"]
- * @param props.richColors - Enable enhanced colors for different toast types. Default: false
- * @param props.expand - Expand toasts by default to show full content. Default: false
- * @param props.duration - Default duration in milliseconds before auto-dismiss. Default: 4000
- * @param props.gap - Spacing between toasts in pixels. Default: 14
- * @param props.visibleToasts - Maximum number of toasts visible at once. Default: 3
- * @param props.closeButton - Show close button on each toast. Default: false
- * @param props.toastOptions - Default options applied to all toasts
- * @param props.className - Additional CSS classes for the toast container
- * @param props.style - Additional inline styles for the toast container
- * @param props.offset - Offset from viewport edges in pixels or string
- * @param props.dir - Text direction for toast content. Options: "ltr", "rtl", "auto". Default: "ltr"
- * @param props.loadingIcon - Custom loading icon component
- * @param props.icons - Custom icons for different toast types
+ * @example RTL support and mobile optimization
+ * ```tsx
+ * <Toaster
+ *   dir="rtl"
+ *   position="top-right"
+ *   offset={{ top: 20, right: 20 }}
+ *   mobileOffset={{ top: 10, right: 10 }}
+ *   swipeDirections={["left", "top"]}
+ *   containerAriaLabel="إشعارات"
+ * />
+ * ```
+ *
+ * @example Custom icons and advanced configuration
+ * ```tsx
+ * <Toaster
+ *   richColors
+ *   icons={{
+ *     success: <CheckCircleIcon />,
+ *     error: <XCircleIcon />,
+ *     warning: <ExclamationTriangleIcon />,
+ *     info: <InformationCircleIcon />,
+ *     loading: <SpinnerIcon />
+ *   }}
+ *   toastOptions={{
+ *     classNames: {
+ *       toast: 'group toast group-[.toaster]:bg-background',
+ *       description: 'group-[.toast]:text-muted-foreground',
+ *       actionButton: 'group-[.toast]:bg-primary',
+ *       cancelButton: 'group-[.toast]:bg-muted'
+ *     },
+ *     closeButtonAriaLabel: 'Close notification'
+ *   }}
+ * />
+ * ```
+ *
+ * @example Keyboard shortcuts and accessibility
+ * ```tsx
+ * <Toaster
+ *   hotkey={["ctrlKey", "KeyN"]} // Ctrl+N to focus toasts
+ *   closeButton
+ *   containerAriaLabel="Application notifications"
+ *   toastOptions={{
+ *     closeButtonAriaLabel: "Dismiss notification",
+ *     duration: 6000 // Longer duration for accessibility
+ *   }}
+ * />
+ * ```
+ *
+ * @param props - Configuration options for the toast container. All props are optional with sensible defaults.
  *
  * @accessibility
- * - Toasts are announced to screen readers with appropriate ARIA attributes
- * - Keyboard navigation support with customizable hotkey
- * - Auto-dismiss functionality with configurable duration
- * - Focus management for interactive elements within toasts
- * - Respects user's prefers-reduced-motion settings
- * - High contrast support for better visibility
- *
- * @see {@link https://ui.shadcn.com/docs/components/sonner} - shadcn/ui Sonner documentation
- * @see {@link https://sonner.emilkowal.ski/} - Official Sonner documentation
+ * - **ARIA Live Region**: Toasts are announced to screen readers automatically
+ * - **Keyboard Navigation**: Configurable hotkey to focus toast region (default Alt+T)
+ * - **Focus Management**: Interactive elements within toasts receive proper focus
+ * - **Screen Reader Support**: Toast content is properly announced with role and aria-label
+ * - **Close Button Accessibility**: When enabled, includes accessible close buttons
+ * - **Motion Preferences**: Respects user's prefers-reduced-motion for animations
+ * - **High Contrast**: Compatible with high contrast modes and custom color schemes
+ * - **Touch Accessibility**: Swipe gestures work with assistive touch technologies
+ * - **Keyboard Dismissal**: Escape key can dismiss toasts when focused
+ * - **Semantic Markup**: Uses appropriate ARIA roles and properties for toast region
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/sonner} shadcn/ui Sonner documentation
+ * @see {@link https://sonner.emilkowal.ski/} Official Sonner library documentation
+ * @see {@link useTheme} Theme hook for understanding automatic theme integration
+ * @see {@link toast} Toast function for creating notifications
  * @since 1.0.0
  */
 function Toaster({ ...props }: ToasterProps) {
@@ -117,4 +395,254 @@ function Toaster({ ...props }: ToasterProps) {
   );
 }
 
-export { Toaster, toast };
+/**
+ * Props for toast function (Documentation only - NOT used in function implementation)
+ * These types are for documentation generation and should not replace sonner library inferred types
+ *
+ * Configuration options for the toast() function and its variants. Extended from ExternalToast
+ * interface provided by the sonner library for comprehensive type coverage.
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type ToastFunctionDocsProps = {
+  /** Secondary text displayed below the main message */
+  description?: string | React.ReactNode;
+  /** Duration in milliseconds before auto-dismiss @default 4000 */
+  duration?: number;
+  /** Custom icon to display instead of default type icon */
+  icon?: React.ReactNode;
+  /** Primary action button configuration */
+  action?: {
+    /** Button text or React element */
+    label: React.ReactNode;
+    /** Click handler for the action button @param event - Mouse click event */
+    onClick: (event: MouseEvent) => void;
+  };
+  /** Cancel/dismiss button configuration */
+  cancel?: {
+    /** Button text or React element */
+    label: React.ReactNode;
+    /** Click handler for the cancel button @param event - Mouse click event */
+    onClick?: (event: MouseEvent) => void;
+  };
+  /** Unique identifier for programmatic control */
+  id?: string | number;
+  /** Additional CSS classes for toast styling */
+  className?: string;
+  /** Inline styles for toast container */
+  style?: React.CSSProperties;
+  /** Show close button on this toast @default false */
+  closeButton?: boolean;
+  /** Whether toast can be dismissed by user interaction @default true */
+  dismissible?: boolean;
+  /** Callback when toast is dismissed @param toast - Toast object */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  onDismiss?: (toast: any) => void;
+  /** Callback when toast auto-closes @param toast - Toast object */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  onAutoClose?: (toast: any) => void;
+  /** Remove default styling for complete customization @default false */
+  unstyled?: boolean;
+  /** CSS class overrides for specific toast elements */
+  classNames?: {
+    toast?: string;
+    title?: string;
+    description?: string;
+    loader?: string;
+    closeButton?: string;
+    cancelButton?: string;
+    actionButton?: string;
+    success?: string;
+    error?: string;
+    info?: string;
+    warning?: string;
+    loading?: string;
+    default?: string;
+  };
+  /** Inline styles for specific toast elements */
+  styles?: {
+    toast?: React.CSSProperties;
+    title?: React.CSSProperties;
+    description?: React.CSSProperties;
+    loader?: React.CSSProperties;
+    closeButton?: React.CSSProperties;
+    cancelButton?: React.CSSProperties;
+    actionButton?: React.CSSProperties;
+  };
+  /** Position override for this specific toast */
+  position?:
+    | "top-left"
+    | "top-right"
+    | "bottom-left"
+    | "bottom-right"
+    | "top-center"
+    | "bottom-center";
+  /** Enable rich colors for this toast @default false */
+  richColors?: boolean;
+  /** Text direction for this toast @default "ltr" */
+  dir?: "rtl" | "ltr" | "auto";
+  /** Accessible label for close button @default "Close toast" */
+  closeButtonAriaLabel?: string;
+};
+
+/**
+ * Toast function with comprehensive methods for creating notifications
+ *
+ * A powerful toast API that supports multiple notification types, promise handling,
+ * and extensive customization. Re-exported from the sonner library with enhanced
+ * type safety and documentation for seamless integration with @neynar/ui.
+ *
+ * **Available Methods:**
+ * - `toast(message)` - Basic notification
+ * - `toast.success(message)` - Success notification with green styling
+ * - `toast.error(message)` - Error notification with red styling
+ * - `toast.warning(message)` - Warning notification with yellow styling
+ * - `toast.info(message)` - Info notification with blue styling
+ * - `toast.loading(message)` - Loading notification with spinner
+ * - `toast.promise(promise, states)` - Promise-based notifications with loading/success/error
+ * - `toast.custom(jsx)` - Fully custom toast with JSX content
+ * - `toast.dismiss(id)` - Programmatically dismiss specific toast
+ * - `toast.message(message)` - Alias for basic toast
+ *
+ * **Common Options (ExternalToast):**
+ * ```typescript
+ * {
+ *   description?: string | React.ReactNode,
+ *   duration?: number,
+ *   icon?: React.ReactNode,
+ *   action?: {
+ *     label: React.ReactNode,
+ *     onClick: (event: MouseEvent) => void
+ *   },
+ *   cancel?: {
+ *     label: React.ReactNode,
+ *     onClick: (event: MouseEvent) => void
+ *   },
+ *   id?: string | number,
+ *   className?: string,
+ *   style?: CSSProperties,
+ *   closeButton?: boolean,
+ *   dismissible?: boolean,
+ *   onDismiss?: (toast) => void,
+ *   onAutoClose?: (toast) => void
+ * }
+ * ```
+ *
+ * @example Basic notifications
+ * ```tsx
+ * // Simple message
+ * toast('User logged in');
+ *
+ * // With description
+ * toast('New message', {
+ *   description: 'You have a new direct message from @alice'
+ * });
+ *
+ * // Typed notifications
+ * toast.success('Profile saved');
+ * toast.error('Failed to upload image');
+ * toast.warning('Storage space is running low');
+ * toast.info('New features available');
+ * ```
+ *
+ * @example Advanced notifications with actions
+ * ```tsx
+ * // With action button
+ * toast('Cast scheduled', {
+ *   description: 'Will be published in 1 hour',
+ *   action: {
+ *     label: 'Cancel',
+ *     onClick: () => cancelScheduledCast()
+ *   }
+ * });
+ *
+ * // With both action and cancel
+ * toast('Delete account?', {
+ *   description: 'This action cannot be undone',
+ *   action: {
+ *     label: 'Delete',
+ *     onClick: () => deleteAccount()
+ *   },
+ *   cancel: {
+ *     label: 'Cancel',
+ *     onClick: () => console.log('Cancelled')
+ *   }
+ * });
+ * ```
+ *
+ * @example Promise-based notifications
+ * ```tsx
+ * // Basic promise handling
+ * toast.promise(uploadFile(file), {
+ *   loading: 'Uploading...',
+ *   success: 'Upload complete!',
+ *   error: 'Upload failed'
+ * });
+ *
+ * // Dynamic success message based on result
+ * toast.promise(createUser(userData), {
+ *   loading: 'Creating account...',
+ *   success: (user) => `Welcome ${user.name}!`,
+ *   error: (error) => `Failed: ${error.message}`
+ * });
+ *
+ * // With custom options per state
+ * toast.promise(processData(), {
+ *   loading: 'Processing data...',
+ *   success: (result) => ({
+ *     message: 'Processing complete',
+ *     description: `Processed ${result.count} items`,
+ *     action: {
+ *       label: 'View Results',
+ *       onClick: () => showResults(result)
+ *     }
+ *   }),
+ *   error: 'Processing failed'
+ * });
+ * ```
+ *
+ * @example Custom styling and behavior
+ * ```tsx
+ * // Custom duration and styling
+ * toast('Custom toast', {
+ *   duration: 10000,
+ *   className: 'my-custom-toast',
+ *   style: { backgroundColor: '#ff6b6b' },
+ *   icon: <CustomIcon />
+ * });
+ *
+ * // Non-dismissible toast (manual dismiss only)
+ * const toastId = toast('Important notice', {
+ *   dismissible: false,
+ *   duration: Infinity,
+ *   action: {
+ *     label: 'Acknowledge',
+ *     onClick: () => toast.dismiss(toastId)
+ *   }
+ * });
+ * ```
+ *
+ * @example Programmatic control
+ * ```tsx
+ * // Store toast ID for later control
+ * const loadingToast = toast.loading('Processing...');
+ *
+ * // Update the same toast
+ * setTimeout(() => {
+ *   toast.success('Process complete!', { id: loadingToast });
+ * }, 2000);
+ *
+ * // Dismiss specific toast
+ * toast.dismiss(loadingToast);
+ *
+ * // Dismiss all toasts
+ * toast.dismiss();
+ * ```
+ *
+ * @returns The toast ID that can be used for programmatic control
+ *
+ * @see {@link Toaster} Toast container component that must be rendered in your app
+ * @see {@link https://sonner.emilkowal.ski/toast} Complete toast API documentation
+ */
+const toastFunction: typeof toast = toast;
+
+export { Toaster, toastFunction as toast };