Complete error handling improvements and documentation updates

Co-authored-by: 0xrinegade <[email protected]>

Author: Copilot

SWIG_WALLET_MIGRATION.md

@@ -19,6 +19,53 @@
 - Clean up legacy code paths
 - **Timeline**: Next major release
 
+## New Features & Improvements
+
+### Enhanced Error Handling System
+The new Swig wallet integration includes a categorized error handling system:
+
+#### Error Categories
+- **Critical Errors**: Authentication failures, API issues (persistent toasts)
+- **System Errors**: Network issues, connection problems (actionable toasts)
+- **Informational Errors**: Form validation, user input (inline or brief toasts)
+- **Success Messages**: Brief confirmation toasts
+
+#### Usage Examples
+```javascript
+const { toast } = useToast();
+
+// Critical errors - persistent with retry actions
+toast.criticalError('Authentication failed', {
+  action: <button onClick={retry}>Retry</button>
+});
+
+// System errors - connection issues with fallbacks
+toast.systemError('Connection lost', {
+  action: <button onClick={reconnect}>Reconnect</button>
+});
+
+// Success messages - brief confirmations
+toast.success('Wallet connected successfully');
+```
+
+### Improved Reconnection Logic
+- **Exponential backoff with jitter** prevents thundering herd problems
+- **Comprehensive timeout cleanup** prevents memory leaks
+- **Progress tracking UI** shows reconnection attempts to users
+- **Cancellation support** allows users to stop reconnection
+
+### Enhanced Popup Handling
+- **Better popup blocker detection** including mobile browsers
+- **Fallback options** for blocked popups (same-tab navigation)
+- **Sequential popup management** reduces blocker issues
+- **User-friendly error messages** with actionable buttons
+
+### Accessibility Improvements
+- **Focus trapping** in modals for keyboard navigation
+- **ARIA labels** for screen readers
+- **Escape key support** for modal dismissal
+- **Proper focus restoration** after modal close
+
 ## Migration Steps
 
 ### 1. Update Hook Usage

src/contexts/SwigWalletProvider.js

@@ -21,6 +21,7 @@ import { useToast } from '../hooks/useToast';
 import { ToastContainer } from '../components/Toast';
 import { ReconnectionModal } from '../components/ReconnectionModal';
 import { SVM_NETWORKS, getNetworkConfig, getDefaultNetworkConfig } from '../config/networks';
+import { ERROR_CATEGORIES } from '../hooks/useToast';
 
 // Maximum number of reconnection attempts
 const MAX_RECONNECT_ATTEMPTS = 3;
@@ -196,12 +197,23 @@ const SwigWalletProvider = ({ children }) => {
           setPublicKey(new PublicKey(selectedWallet.address));
           setConnected(true);
           setConnectionState('connected');
-          toast.success('Wallet connected successfully');
+          toast.success('Wallet connected successfully', { 
+            category: ERROR_CATEGORIES.SUCCESS 
+          });
         } else {
           const errorMsg = `No ${storedWalletType} wallet found`;
           setError(errorMsg);
           setConnectionState('error');
-          toast.error(errorMsg);
+          toast.criticalError(errorMsg, {
+            action: (
+              <button
+                onClick={() => window.location.reload()}
+                className="mt-2 px-3 py-1 bg-blue-500 text-white text-xs rounded hover:bg-blue-600"
+              >
+                Retry
+              </button>
+            )
+          });
         }
       } else {
         setConnected(false);
@@ -212,7 +224,22 @@ const SwigWalletProvider = ({ children }) => {
       const errorMsg = err.message || 'Authentication check failed';
       setError(errorMsg);
       setConnectionState('error');
-      toast.error(`Connection failed: ${errorMsg}`);
+      
+      // Categorize error based on type
+      if (err.message?.includes('network') || err.message?.includes('connection')) {
+        toast.systemError(`Connection failed: ${errorMsg}`, {
+          action: (
+            <button
+              onClick={() => checkAuthentication()}
+              className="mt-2 px-3 py-1 bg-blue-500 text-white text-xs rounded hover:bg-blue-600"
+            >
+              Retry Connection
+            </button>
+          )
+        });
+      } else {
+        toast.criticalError(`Authentication failed: ${errorMsg}`);
+      }
     } finally {
       setConnecting(false);
     }
@@ -243,8 +270,10 @@ const SwigWalletProvider = ({ children }) => {
 
     const errorMsg = `Popup blocked. Please allow popups for this site and try again.`;
 
-    toast.error(errorMsg, {
+    toast.systemError(errorMsg, {
+      category: ERROR_CATEGORIES.SYSTEM,
       duration: 15000, // Longer duration for instructions
+      persistent: true,
       action: (
         <div className="mt-3 space-y-2">
           <button
@@ -372,7 +401,22 @@ const SwigWalletProvider = ({ children }) => {
       } else {
         const errorMsg = err.message || 'Authentication failed';
         setError(errorMsg);
-        toast.error(`Login failed: ${errorMsg}`);
+        
+        // Categorize authentication errors
+        if (errorMsg.includes('network') || errorMsg.includes('timeout')) {
+          toast.systemError(`Login failed: ${errorMsg}`, {
+            action: (
+              <button
+                onClick={() => authenticate(method)}
+                className="mt-2 px-3 py-1 bg-blue-500 text-white text-xs rounded hover:bg-blue-600"
+              >
+                Retry Login
+              </button>
+            )
+          });
+        } else {
+          toast.criticalError(`Login failed: ${errorMsg}`);
+        }
       }
       setConnectionState('error');
     } finally {
@@ -404,12 +448,14 @@ const SwigWalletProvider = ({ children }) => {
       setError(null);
       setConnectionState('disconnected');
 
-      toast.success('Wallet disconnected');
+      toast.success('Wallet disconnected', { 
+        category: ERROR_CATEGORIES.SUCCESS 
+      });
     } catch (err) {
       console.error('[SwigWalletProvider] Disconnect failed:', err);
       const errorMsg = err.message || 'Disconnect failed';
       setError(errorMsg);
-      toast.error(`Disconnect failed: ${errorMsg}`);
+      toast.criticalError(`Disconnect failed: ${errorMsg}`);
     }
   }, [toast]);
 
@@ -426,12 +472,14 @@ const SwigWalletProvider = ({ children }) => {
       // This is a simplified version - full implementation would use createSwigAccount utilities
 
       console.log('[SwigWalletProvider] Swig wallet setup completed');
-      toast.success('Swig wallet setup completed');
+      toast.success('Swig wallet setup completed', { 
+        category: ERROR_CATEGORIES.SUCCESS 
+      });
     } catch (err) {
       console.error('[SwigWalletProvider] Swig wallet setup failed:', err);
       const errorMsg = err.message || 'Swig wallet setup failed';
       setError(errorMsg);
-      toast.error(`Setup failed: ${errorMsg}`);
+      toast.criticalError(`Setup failed: ${errorMsg}`);
     } finally {
       setIsSettingUp(false);
     }

src/hooks/useToast.js

@@ -1,27 +1,63 @@
 /**
  * Toast hook for managing toast notifications
+ * 
+ * Provides categorized error handling:
+ * - Critical errors: Show as persistent toasts (auth failures, network issues)
+ * - Informational errors: Show inline or as brief toasts (form validation)
+ * - System errors: Show as urgent toasts with actions (connection lost)
  */
 
 import { useState, useCallback } from 'react';
 
 let toastId = 0;
 
 /**
- * Hook for managing toast notifications
+ * Error categories for proper UI placement
+ */
+export const ERROR_CATEGORIES = {
+  CRITICAL: 'critical',     // Show as persistent toasts (auth, network)
+  INFORMATIONAL: 'info',    // Show inline or brief toasts (validation)
+  SYSTEM: 'system',         // Show as urgent toasts with actions (connection)
+  SUCCESS: 'success',       // Show as brief success toasts
+  WARNING: 'warning'        // Show as warning toasts
+};
+
+/**
+ * Hook for managing categorized toast notifications
  * @returns {Object} Toast management functions and state
  */
 export const useToast = () => {
   const [toasts, setToasts] = useState([]);
 
-  const addToast = useCallback(({ message, type = 'info', duration = 5000, action = null }) => {
+  const addToast = useCallback(({ 
+    message, 
+    type = 'info', 
+    category = ERROR_CATEGORIES.INFORMATIONAL,
+    duration = 5000, 
+    action = null,
+    persistent = false 
+  }) => {
     const id = ++toastId;
+    
+    // Adjust duration based on category
+    let adjustedDuration = duration;
+    if (category === ERROR_CATEGORIES.CRITICAL) {
+      adjustedDuration = persistent ? 0 : 10000; // 10s or persistent
+    } else if (category === ERROR_CATEGORIES.SYSTEM) {
+      adjustedDuration = persistent ? 0 : 15000; // 15s or persistent 
+    } else if (category === ERROR_CATEGORIES.SUCCESS) {
+      adjustedDuration = 3000; // Brief success messages
+    }
+    
     const toast = {
       id,
       message,
       type,
-      duration,
+      category,
+      duration: adjustedDuration,
       action,
-      timestamp: Date.now()
+      timestamp: Date.now(),
+      persistent
     };
 
     setToasts(prev => [...prev, toast]);
@@ -36,33 +72,98 @@ export const useToast = () => {
     setToasts([]);
   }, []);
 
-  // Convenience methods for different toast types
+  const clearByCategory = useCallback((category) => {
+    setToasts(prev => prev.filter(toast => toast.category !== category));
+  }, []);
+
+  // Convenience methods for different toast types with proper categorization
   const success = useCallback((message, options = {}) => {
-    return addToast({ message, type: 'success', ...options });
+    return addToast({ 
+      message, 
+      type: 'success', 
+      category: ERROR_CATEGORIES.SUCCESS,
+      ...options 
+    });
   }, [addToast]);
 
   const error = useCallback((message, options = {}) => {
-    return addToast({ message, type: 'error', duration: 8000, ...options });
+    return addToast({ 
+      message, 
+      type: 'error', 
+      category: ERROR_CATEGORIES.CRITICAL,
+      duration: 8000, 
+      ...options 
+    });
   }, [addToast]);
 
   const warning = useCallback((message, options = {}) => {
-    return addToast({ message, type: 'warning', duration: 6000, ...options });
+    return addToast({ 
+      message, 
+      type: 'warning', 
+      category: ERROR_CATEGORIES.WARNING,
+      duration: 6000, 
+      ...options 
+    });
   }, [addToast]);
 
   const info = useCallback((message, options = {}) => {
-    return addToast({ message, type: 'info', ...options });
+    return addToast({ 
+      message, 
+      type: 'info', 
+      category: ERROR_CATEGORIES.INFORMATIONAL,
+      ...options 
+    });
+  }, [addToast]);
+
+  // Specialized methods for different error categories
+  const criticalError = useCallback((message, options = {}) => {
+    return addToast({
+      message,
+      type: 'error',
+      category: ERROR_CATEGORIES.CRITICAL,
+      duration: 10000,
+      persistent: true,
+      ...options
+    });
+  }, [addToast]);
+
+  const systemError = useCallback((message, options = {}) => {
+    return addToast({
+      message,
+      type: 'error',
+      category: ERROR_CATEGORIES.SYSTEM,
+      duration: 15000,
+      ...options
+    });
   }, [addToast]);
 
+  const inlineError = useCallback((message, options = {}) => {
+    // For inline errors, we provide the message but don't show toast
+    // Components can use this for form validation, etc.
+    return {
+      message,
+      type: 'error',
+      category: ERROR_CATEGORIES.INFORMATIONAL,
+      inline: true,
+      ...options
+    };
+  }, []);
+
   return {
     toasts,
     addToast,
     removeToast,
     clearAllToasts,
+    clearByCategory,
     success,
     error,
     warning,
-    info
+    info,
+    criticalError,
+    systemError,
+    inlineError,
+    ERROR_CATEGORIES
   };
 };
 
-export default useToast;
+export default useToast;