@neynar/ui 0.1.1 → 0.1.2

package/dist/components/ui/sonner.d.ts

@@ -2,14 +2,26 @@ import { type ToasterProps, toast } from "sonner";
 /**
  * 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 }) {
@@ -24,78 +36,300 @@ import { 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}
+ * />
+ * ```
+ *
+ * @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
- * @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
+ * @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
  */
 declare function Toaster({ ...props }: ToasterProps): import("react/jsx-runtime").JSX.Element;
-export { Toaster, toast };
+/**
+ * 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
+ */
+declare const toastFunction: typeof toast;
+export { Toaster, toastFunction as toast };
 //# sourceMappingURL=sonner.d.ts.map

package/dist/components/ui/sonner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sonner.d.ts","sourceRoot":"","sources":["../../../src/components/ui/sonner.tsx"],"names":[],"mappings":"AACA,OAAO,EAAqB,KAAK,YAAY,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgGG;AACH,iBAAS,OAAO,CAAC,EAAE,GAAG,KAAK,EAAE,EAAE,YAAY,2CAiB1C;AAED,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC"}
+{"version":3,"file":"sonner.d.ts","sourceRoot":"","sources":["../../../src/components/ui/sonner.tsx"],"names":[],"mappings":"AACA,OAAO,EAAqB,KAAK,YAAY,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AA8MrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0KG;AACH,iBAAS,OAAO,CAAC,EAAE,GAAG,KAAK,EAAE,EAAE,YAAY,2CAiB1C;AA2FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8JG;AACH,QAAA,MAAM,aAAa,EAAE,OAAO,KAAa,CAAC;AAE1C,OAAO,EAAE,OAAO,EAAE,aAAa,IAAI,KAAK,EAAE,CAAC"}