refactor: enhance UI components with improved styling and accessibility

- Add comprehensive JSDoc comments and type definitions for all components
- Implement consistent styling with Tailwind CSS and improved visual hierarchy
- Enhance accessibility with ARIA attributes and keyboard navigation support
- Add new features: tooltip positioning, recent tokens management, and network selection
- Improve error handling and user feedback across all interactive components

Author: El-swaggerito

src/components/AddTrustlineButton.tsx

@@ -1,50 +1,68 @@
+/**
+ * Add Trustline Button Component.
+ * Encapsulates the logic for establishing a Stellar trustline for a specific asset.
+ * A trustline is mandatory before an account can hold non-native assets.
+ */
+
 import React, { useState } from "react";
 import { toast } from "react-hot-toast";
-import { Plus, Check, Loader2 } from "lucide-react";
+import { Plus, Check, Loader2, ShieldCheck, AlertCircle } from "lucide-react";
 import { addTrustline } from "../lib/stellar";
 import Button from "./ui/Button";
 
+/**
+ * Props for the AddTrustlineButton component.
+ */
 interface AddTrustlineButtonProps {
+  /** The 1-12 character asset code (e.g., "USDC") */
   assetCode: string;
+  /** The public Stellar address of the asset issuer */
   assetIssuer: string;
 }
 
 /**
- * A reusable button that establishes a Trustline for a specific Stellar asset
- * using the Freighter wallet extension.
+ * A specialized button that handles the 'change_trust' operation flow.
  */
 export default function AddTrustlineButton({ assetCode, assetIssuer }: AddTrustlineButtonProps) {
+  // --- Component State ---
+  /** Current status of the asynchronous trustline operation */
   const [status, setStatus] = useState<"idle" | "loading" | "success" | "error">("idle");
 
+  /**
+   * Initiates the trustline transaction flow.
+   */
   const handleAddTrustline = async () => {
+    // Prevent redundant clicks
     if (status === "loading" || status === "success") return;
 
     setStatus("loading");
-    const toastId = toast.loading(`Requesting ${assetCode} trustline...`);
+    const toastId = toast.loading(`Establishing ${assetCode} trustline...`);
 
     try {
+      // 1. Trigger the Stellar SDK / Wallet transaction
       await addTrustline(assetCode, assetIssuer);
 
       setStatus("success");
-      toast.success(`${assetCode} Trustline Established!`, { 
+      toast.success(`${assetCode} Trustline Active`, { 
         id: toastId,
-        icon: '✅'
+        icon: '🛡️'
       });
 
-      // Revert to idle after 5 seconds
+      // 2. Revert to idle after 5 seconds to reset UI
       setTimeout(() => setStatus("idle"), 5000);
+      console.log(`[AddTrustline] Successfully added ${assetCode} from ${assetIssuer}`);
     } catch (error: any) {
-      console.error(`[AddTrustline] Error:`, error);
+      console.error(`[AddTrustline] Failed to add ${assetCode}:`, error);
       setStatus("error");
 
-      // Handle rejection vs generic error
-      const errorMsg = error.message?.includes("denied") 
-        ? "Access Denied by User" 
-        : `Failed to add ${assetCode}`;
+      // User-friendly error mapping
+      const errorMsg = error.message?.toLowerCase().includes("denied") 
+        ? "Transaction rejected by user" 
+        : `Network error adding ${assetCode}`;
 
       toast.error(errorMsg, { id: toastId });
 
-      // Revert to idle after 3 seconds to allow retry
+      // 3. Revert to idle after a short delay to allow retry
       setTimeout(() => setStatus("idle"), 3000);
     }
   };
@@ -54,21 +72,36 @@ export default function AddTrustlineButton({ assetCode, assetIssuer }: AddTrustl
       variant="secondary"
       onClick={handleAddTrustline}
       disabled={status === "loading" || status === "success"}
-      className={`flex items-center gap-2 text-xs py-1.5 px-3 h-auto transition-all duration-200 ${
-        status === "success" ? "bg-green-600/20 text-green-400 border-green-600/50" : ""
+      className={`flex items-center gap-2 text-[10px] font-black uppercase tracking-widest py-2 px-4 h-auto transition-all duration-300 border ${
+        status === "success" 
+          ? "bg-emerald-500/10 text-emerald-400 border-emerald-500/30" 
+          : "bg-slate-800/50 text-slate-400 border-slate-700 hover:border-slate-500 hover:text-white"
       }`}
+      aria-label={`Add trustline for ${assetCode}`}
     >
+      {/* Dynamic Icon State */}
       {status === "loading" ? (
-        <Loader2 size={14} className="animate-spin" />
+        <Loader2 size={12} className="animate-spin text-blue-400" />
       ) : status === "success" ? (
-        <Check size={14} />
+        <ShieldCheck size={12} className="text-emerald-400" />
+      ) : status === "error" ? (
+        <AlertCircle size={12} className="text-rose-400" />
       ) : (
-        <Plus size={14} />
+        <Plus size={12} className="group-hover:rotate-90 transition-transform" />
       )}
 
+      {/* Dynamic Label State */}
       <span>
-        {status === "loading" ? "Signing..." : status === "success" ? "Trustline Active" : `Add ${assetCode}`}
+        {status === "loading" 
+          ? "Signing..." 
+          : status === "success" 
+            ? "Established" 
+            : status === "error"
+              ? "Retry"
+              : `Add ${assetCode}`
+        }
       </span>
     </Button>
   );
 }
+

src/components/ConnectWallet.tsx

@@ -1,19 +1,33 @@
+/**
+ * Connect Wallet Component.
+ * A standalone button/dropdown component for managing Stellar wallet sessions.
+ * Displays the connected address and provides a disconnect option.
+ */
+
 "use client";
+
 import { useState, useRef, useEffect } from "react";
-import { connectWallet, WalletType, FREIGHTER_ID } from "../lib/stellar";
+import { connectWallet, WalletType, FREIGHTER_ID, shortenAddress } from "../lib/stellar";
 import Button from "./ui/Button";
 import { useTokenStore } from "../stores/tokenStore";
-import { LogOut, ChevronDown } from "lucide-react";
+import { LogOut, ChevronDown, User, ShieldCheck } from "lucide-react";
 
+/** Key for purging recent token history on logout */
 const RECENT_TOKENS_KEY = "tradeflow_recent_tokens";
 
+/**
+ * A component that handles the wallet connection flow and account display.
+ */
 export default function ConnectWallet() {
+      // --- Component State ---
       const [pubKey, setPubKey] = useState<string | null>(null);
       const [isDropdownOpen, setIsDropdownOpen] = useState(false);
       const { setConnected } = useTokenStore();
       const dropdownRef = useRef<HTMLDivElement>(null);
 
-      // Close dropdown when clicking outside
+      /**
+       * Effect: Closes the account dropdown when clicking outside.
+       */
       useEffect(() => {
             const handleClickOutside = (event: MouseEvent) => {
                   if (dropdownRef.current && !dropdownRef.current.contains(event.target as Node)) {
@@ -24,65 +38,92 @@ export default function ConnectWallet() {
             return () => document.removeEventListener("mousedown", handleClickOutside);
       }, []);
 
+      /**
+       * Initiates the wallet connection process.
+       * 
+       * @param {WalletType} walletType - The ID of the wallet provider.
+       */
       const handleConnect = async (walletType: WalletType = FREIGHTER_ID) => {
             try {
                   const userInfo = await connectWallet(walletType);
                   if (userInfo.publicKey) {
                         setPubKey(userInfo.publicKey);
                         setConnected(true, userInfo.publicKey);
+                        console.log(`[ConnectWallet] Session started for: ${userInfo.publicKey}`);
                   }
             } catch (e: any) {
-                  console.error("Connection error:", e);
+                  console.error("[ConnectWallet] Connection failed:", e);
+                  // TODO: Use a toast instead of native alert
                   alert(e.message || "Failed to connect to wallet!");
             }
       };
 
+      /**
+       * Terminates the session and clears related data.
+       */
       const handleDisconnect = () => {
             setPubKey(null);
             setConnected(false, undefined);
+            // Clear local history for privacy/security
             localStorage.removeItem(RECENT_TOKENS_KEY);
             setIsDropdownOpen(false);
+            console.log("[ConnectWallet] Session terminated.");
       };
 
+      // 1. Authenticated UI (Dropdown)
       if (pubKey) {
             return (
                   <div className="relative" ref={dropdownRef}>
                         <button
                               onClick={() => setIsDropdownOpen((prev) => !prev)}
-                              className="flex items-center gap-2 px-4 py-2 rounded-lg bg-slate-800 hover:bg-slate-700 border border-slate-700 text-slate-200 text-sm font-medium transition-colors"
+                              className="flex items-center gap-2.5 px-4 py-2.5 rounded-xl bg-slate-800/80 hover:bg-slate-700/80 border border-slate-700 text-slate-200 text-sm font-bold transition-all shadow-sm active:scale-[0.98]"
+                              aria-haspopup="menu"
+                              aria-expanded={isDropdownOpen}
                         >
-                              <span className="w-2 h-2 rounded-full bg-green-400 shrink-0" />
-                              {`${pubKey.slice(0, 4)}...${pubKey.slice(-4)}`}
-                              <ChevronDown size={14} className={`transition-transform ${isDropdownOpen ? "rotate-180" : ""}`} />
+                              <div className="w-2 h-2 rounded-full bg-emerald-400 shadow-[0_0_8px_rgba(52,211,153,0.5)] shrink-0" />
+                              <span className="font-mono tracking-tight">{shortenAddress(pubKey, 4)}</span>
+                              <ChevronDown size={14} className={`text-slate-500 transition-transform duration-300 ${isDropdownOpen ? "rotate-180" : ""}`} />
                         </button>
 
                         {isDropdownOpen && (
-                              <div className="absolute right-0 mt-2 w-48 rounded-lg bg-slate-800 border border-slate-700 shadow-xl z-50 overflow-hidden">
-                                    <div className="px-3 py-2 border-b border-slate-700">
-                                          <p className="text-xs text-slate-400 font-medium">Connected Wallet</p>
-                                          <p className="text-xs text-slate-300 font-mono truncate mt-0.5">{pubKey}</p>
+                              <div 
+                                    className="absolute right-0 mt-2 w-64 rounded-2xl bg-slate-800 border border-slate-700 shadow-2xl z-50 overflow-hidden animate-in fade-in slide-in-from-top-2 duration-200"
+                                    role="menu"
+                              >
+                                    <div className="px-4 py-4 border-b border-slate-700 bg-slate-900/50">
+                                          <div className="flex items-center gap-2 mb-1.5">
+                                                <ShieldCheck size={14} className="text-blue-400" />
+                                                <p className="text-[10px] text-slate-400 font-black uppercase tracking-widest">Verified Account</p>
+                                          </div>
+                                          <p className="text-xs text-slate-200 font-mono break-all leading-relaxed">{pubKey}</p>
+                                    </div>
+                                    <div className="p-1.5">
+                                          <button
+                                                onClick={handleDisconnect}
+                                                className="w-full flex items-center gap-3 px-3 py-2.5 text-sm font-bold text-rose-400 hover:bg-rose-500/10 rounded-xl transition-all group"
+                                                role="menuitem"
+                                          >
+                                                <LogOut size={16} className="group-hover:translate-x-0.5 transition-transform" />
+                                                Disconnect Wallet
+                                          </button>
                                     </div>
-                                    <button
-                                          onClick={handleDisconnect}
-                                          className="w-full flex items-center gap-2 px-3 py-2.5 text-sm text-slate-300 hover:bg-red-500/10 hover:text-red-400 transition-colors"
-                                    >
-                                          <LogOut size={14} />
-                                          Disconnect Wallet
-                                    </button>
                               </div>
                         )}
                   </div>
             );
       }
 
+      // 2. Unauthenticated UI (CTA Button)
       return (
             <div>
                   <Button
                         onClick={() => handleConnect(FREIGHTER_ID)}
-                        className="bg-purple-600 hover:bg-purple-700 shadow-lg flex items-center gap-2 px-6 py-3"
+                        className="bg-indigo-600 hover:bg-indigo-500 shadow-xl shadow-indigo-500/20 flex items-center gap-2 px-7 py-3 rounded-xl font-bold uppercase tracking-widest text-xs transition-all active:scale-95"
                   >
+                        <User size={16} />
                         Connect Wallet
                   </Button>
             </div>
       );
 }
+