@chainloyalty/react 1.0.0

package/src/Leaderboard.tsx

@@ -0,0 +1,528 @@
+/**
+ * @chainloyalty/react - Leaderboard Component
+ * 
+ * Purpose:
+ * A fully-featured, embeddable leaderboard component that displays top users
+ * ranked by their points. This component provides real-time updates, filtering,
+ * and responsive design for both mobile and desktop.
+ * 
+ * Key Features:
+ * - Top users ranked by points
+ * - Display: Rank, Wallet (shortened with copy), Points, Badge count
+ * - Filter options (All-time / This month)
+ * - Refresh button for real-time updates
+ * - Fully responsive design
+ * - Loading and empty states
+ * - Dark theme UI
+ * - Professional animations and interactions
+ */
+
+import React, { useState, useEffect } from 'react';
+import {
+  Copy,
+  CheckCircle,
+  RefreshCw,
+  Trophy,
+  Calendar,
+  Award,
+  TrendingUp,
+  ExternalLink,
+} from 'lucide-react';
+
+// ============================================================================
+// Types & Interfaces
+// ============================================================================
+
+export type LeaderboardTimeframe = 'alltime' | 'month';
+
+export interface LeaderboardEntry {
+  rank: number;
+  walletAddress: string;
+  points: number;
+  badgesCount: number;
+  displayName?: string;
+  avatar?: string;
+}
+
+export interface LeaderboardProps {
+  walletAddress?: string | null;
+  customColors?: {
+    background?: string;
+    accent1?: string;
+    accent2?: string;
+  };
+  itemsPerPage?: number;
+  compactMode?: boolean;
+  hideTimeframeFilter?: boolean;
+}
+
+// ============================================================================
+// Mock Data & API Functions
+// ============================================================================
+
+/**
+ * Generate deterministic mock leaderboard data based on a seed
+ * In production, this would be fetched from an API
+ */
+const generateLeaderboardData = (timeframe: LeaderboardTimeframe): LeaderboardEntry[] => {
+  const baseData = [
+    { displayName: 'CryptoKing', points: 45230, badges: 12 },
+    { displayName: 'LoyaltyPro', points: 42890, badges: 11 },
+    { displayName: 'RewardSeeker', points: 38950, badges: 9 },
+    { displayName: 'ChainMaster', points: 35670, badges: 8 },
+    { displayName: 'TokenTrader', points: 32450, badges: 7 },
+    { displayName: 'PointsCollector', points: 29876, badges: 6 },
+    { displayName: 'EarnQuest', points: 27543, badges: 5 },
+    { displayName: 'BlockchainBob', points: 24567, badges: 5 },
+    { displayName: 'WebThreeWave', points: 21234, badges: 4 },
+    { displayName: 'DecentralizedDave', points: 18765, badges: 3 },
+    { displayName: 'SmartContractSally', points: 16543, badges: 3 },
+    { displayName: 'FutureOfFinance', points: 14321, badges: 2 },
+    { displayName: 'CryptoNinja', points: 12876, badges: 2 },
+    { displayName: 'BlockBuilder', points: 11234, badges: 2 },
+    { displayName: 'RewardRunner', points: 9876, badges: 1 },
+  ];
+
+  // Apply timeframe multiplier for month view
+  const multiplier = timeframe === 'month' ? 0.4 : 1;
+
+  return baseData.map((user, index) => ({
+    rank: index + 1,
+    walletAddress: `0x${(Math.random().toString(16) + '000000000000000000000000').slice(2, 42)}`,
+    points: Math.floor(user.points * multiplier),
+    badgesCount: user.badges,
+    displayName: user.displayName,
+  }));
+};
+
+/**
+ * Mock API call to fetch leaderboard data
+ */
+const fetchLeaderboardData = async (
+  timeframe: LeaderboardTimeframe
+): Promise<LeaderboardEntry[]> => {
+  // Simulate network delay
+  await new Promise((resolve) => setTimeout(resolve, 600));
+
+  // Return mock data
+  return generateLeaderboardData(timeframe);
+};
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+const shortenAddress = (address: string, chars = 6): string => {
+  if (!address) return '';
+  return `${address.substring(0, chars)}...${address.substring(address.length - 4)}`;
+};
+
+const copyToClipboard = (text: string): void => {
+  navigator.clipboard.writeText(text);
+};
+
+const getRankColor = (rank: number): string => {
+  if (rank === 1) return '#F59E0B'; // Gold
+  if (rank === 2) return '#E5E7EB'; // Silver
+  if (rank === 3) return '#FB923C'; // Bronze
+  return '#9CA3AF'; // Gray
+};
+
+const getRankIcon = (rank: number): React.ReactNode => {
+  if (rank === 1) return '🥇';
+  if (rank === 2) return '🥈';
+  if (rank === 3) return '🥉';
+  return null;
+};
+
+// ============================================================================
+// Leaderboard Row Component
+// ============================================================================
+
+interface LeaderboardRowProps {
+  entry: LeaderboardEntry;
+  accentColor: string;
+  isCurrentUser?: boolean;
+  onCopyAddress?: (address: string) => void;
+}
+
+const LeaderboardRow: React.FC<LeaderboardRowProps> = ({
+  entry,
+  accentColor,
+  isCurrentUser = false,
+  onCopyAddress,
+}) => {
+  const [copied, setCopied] = useState(false);
+
+  const handleCopy = () => {
+    copyToClipboard(entry.walletAddress);
+    setCopied(true);
+    if (onCopyAddress) {
+      onCopyAddress(entry.walletAddress);
+    }
+    setTimeout(() => setCopied(false), 2000);
+  };
+
+  const rankIcon = getRankIcon(entry.rank);
+  const rankColor = getRankColor(entry.rank);
+
+  return (
+    <tr
+      className={`border-b border-gray-700 transition-all hover:bg-gray-700/30 ${
+        isCurrentUser ? 'bg-gray-700/20' : ''
+      }`}
+    >
+      {/* Rank */}
+      <td className="px-4 py-3 text-sm">
+        <div className="flex items-center justify-center">
+          {rankIcon && <span className="text-lg mr-2">{rankIcon}</span>}
+          <span
+            className="font-bold"
+            style={{
+              color: rankColor,
+            }}
+          >
+            #{entry.rank}
+          </span>
+        </div>
+      </td>
+
+      {/* Wallet Address */}
+      <td className="px-4 py-3 text-sm">
+        <div className="flex items-center gap-2 group">
+          <span className="text-white font-mono">
+            {shortenAddress(entry.walletAddress)}
+          </span>
+          <button
+            onClick={handleCopy}
+            className="p-1.5 rounded-md text-gray-500 group-hover:text-gray-300 hover:bg-gray-700/50 transition-all opacity-0 group-hover:opacity-100"
+            title={entry.walletAddress}
+          >
+            {copied ? (
+              <CheckCircle className="w-4 h-4" style={{ color: '#3FB950' }} />
+            ) : (
+              <Copy className="w-4 h-4" />
+            )}
+          </button>
+          {entry.displayName && (
+            <span className="hidden sm:inline text-xs text-gray-400">({entry.displayName})</span>
+          )}
+        </div>
+      </td>
+
+      {/* Points */}
+      <td className="px-4 py-3 text-sm">
+        <div className="text-right">
+          <p className="font-bold" style={{ color: accentColor }}>
+            {entry.points.toLocaleString()}
+          </p>
+          <p className="text-xs text-gray-400 hidden sm:block">points</p>
+        </div>
+      </td>
+
+      {/* Badges Count */}
+      <td className="px-4 py-3 text-sm">
+        <div
+          className="inline-flex items-center gap-1 px-2 py-1 rounded-lg"
+          style={{
+            backgroundColor: 'rgba(47, 129, 247, 0.1)',
+            borderColor: accentColor,
+          }}
+        >
+          <Award className="w-4 h-4" style={{ color: accentColor }} />
+          <span className="font-semibold text-white">{entry.badgesCount}</span>
+        </div>
+      </td>
+    </tr>
+  );
+};
+
+// ============================================================================
+// Main Leaderboard Component
+// ============================================================================
+
+export const Leaderboard: React.FC<LeaderboardProps> = ({
+  walletAddress = null,
+  customColors = {},
+  itemsPerPage = 15,
+  compactMode = false,
+  hideTimeframeFilter = false,
+}) => {
+  const [timeframe, setTimeframe] = useState<LeaderboardTimeframe>('alltime');
+  const [data, setData] = useState<LeaderboardEntry[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [currentPage, setCurrentPage] = useState(1);
+
+  const backgroundColor = customColors.background || '#0D1117';
+  const accentColor = customColors.accent1 || '#2F81F7';
+  const accentColor2 = customColors.accent2 || '#3FB950';
+
+  // Fetch data when timeframe changes
+  useEffect(() => {
+    setLoading(true);
+    setError(null);
+    setCurrentPage(1);
+
+    fetchLeaderboardData(timeframe)
+      .then((result) => {
+        setData(result);
+        setLoading(false);
+      })
+      .catch((err) => {
+        setError(err.message || 'Failed to load leaderboard');
+        setLoading(false);
+      });
+  }, [timeframe]);
+
+  const handleRefresh = async () => {
+    setLoading(true);
+    const result = await fetchLeaderboardData(timeframe);
+    setData(result);
+    setLoading(false);
+  };
+
+  // Pagination
+  const totalPages = Math.ceil(data.length / itemsPerPage);
+  const startIndex = (currentPage - 1) * itemsPerPage;
+  const endIndex = startIndex + itemsPerPage;
+  const displayedData = compactMode ? data.slice(0, 10) : data.slice(startIndex, endIndex);
+
+  const currentUserRank = walletAddress
+    ? data.find((entry) => entry.walletAddress.toLowerCase() === walletAddress.toLowerCase())
+    : null;
+
+  return (
+    <div
+      className="rounded-lg border border-gray-700 overflow-hidden"
+      style={{ backgroundColor }}
+    >
+      {/* Header */}
+      <div className="p-6 border-b border-gray-700">
+        <div className="flex items-center justify-between mb-4">
+          <div className="flex items-center gap-3">
+            <Trophy className="w-6 h-6" style={{ color: accentColor2 }} />
+            <h2 className="text-2xl font-bold text-white">Leaderboard</h2>
+          </div>
+          <button
+            onClick={handleRefresh}
+            disabled={loading}
+            className="p-2 rounded-lg text-gray-400 hover:text-white hover:bg-gray-700 transition-all disabled:opacity-50"
+            title="Refresh leaderboard"
+          >
+            <RefreshCw className={`w-5 h-5 ${loading ? 'animate-spin' : ''}`} />
+          </button>
+        </div>
+
+        {/* Stats */}
+        <div className="grid grid-cols-2 md:grid-cols-3 gap-3 mb-4">
+          <div
+            className="p-3 rounded-lg border border-gray-700"
+            style={{ backgroundColor: 'rgba(31, 41, 55, 0.5)' }}
+          >
+            <p className="text-xs text-gray-400">Total Users</p>
+            <p className="text-2xl font-bold text-white">{data.length.toLocaleString()}</p>
+          </div>
+
+          {currentUserRank && (
+            <>
+              <div
+                className="p-3 rounded-lg border"
+                style={{
+                  borderColor: accentColor,
+                  backgroundColor: 'rgba(47, 129, 247, 0.1)',
+                }}
+              >
+                <p className="text-xs text-gray-400">Your Rank</p>
+                <p className="text-2xl font-bold" style={{ color: accentColor }}>
+                  #{currentUserRank.rank}
+                </p>
+              </div>
+
+              <div
+                className="p-3 rounded-lg border"
+                style={{
+                  borderColor: accentColor2,
+                  backgroundColor: 'rgba(63, 185, 80, 0.1)',
+                }}
+              >
+                <p className="text-xs text-gray-400">Your Points</p>
+                <p className="text-2xl font-bold" style={{ color: accentColor2 }}>
+                  {currentUserRank.points.toLocaleString()}
+                </p>
+              </div>
+            </>
+          )}
+        </div>
+
+        {/* Filters */}
+        {!hideTimeframeFilter && (
+          <div className="flex items-center gap-2">
+            <Calendar className="w-4 h-4 text-gray-400" />
+            <div className="flex gap-2">
+              {(['alltime', 'month'] as const).map((tf) => (
+                <button
+                  key={tf}
+                  onClick={() => setTimeframe(tf)}
+                  className={`px-3 py-1.5 rounded-lg text-sm font-medium transition-all ${
+                    timeframe === tf
+                      ? 'text-white'
+                      : 'text-gray-400 hover:text-white hover:bg-gray-700/50'
+                  }`}
+                  style={
+                    timeframe === tf
+                      ? {
+                          backgroundColor: accentColor,
+                          color: 'white',
+                        }
+                      : {}
+                  }
+                >
+                  {tf === 'alltime' ? 'All Time' : 'This Month'}
+                </button>
+              ))}
+            </div>
+          </div>
+        )}
+      </div>
+
+      {/* Content */}
+      <div style={{ backgroundColor: 'rgba(31, 41, 55, 0.2)' }}>
+        {/* Loading State */}
+        {loading && !data.length && (
+          <div className="p-6 space-y-3">
+            {[...Array(5)].map((_, i) => (
+              <div key={i} className="h-12 bg-gray-700 rounded-lg animate-pulse" />
+            ))}
+          </div>
+        )}
+
+        {/* Error State */}
+        {error && !data.length && (
+          <div className="p-6 text-center">
+            <p className="text-red-400 mb-4">{error}</p>
+            <button
+              onClick={handleRefresh}
+              className="px-4 py-2 rounded-lg text-white text-sm transition-all"
+              style={{ backgroundColor: accentColor }}
+            >
+              Try Again
+            </button>
+          </div>
+        )}
+
+        {/* Empty State */}
+        {!loading && !error && data.length === 0 && (
+          <div className="p-12 text-center">
+            <TrendingUp className="w-12 h-12 mx-auto mb-4 text-gray-500" />
+            <h3 className="text-lg font-semibold text-white mb-2">No Leaderboard Data</h3>
+            <p className="text-gray-400">The leaderboard will be populated as users start earning points.</p>
+          </div>
+        )}
+
+        {/* Table */}
+        {data.length > 0 && (
+          <div className="overflow-x-auto">
+            <table className="w-full">
+              <thead>
+                <tr className="border-b border-gray-700 bg-gray-800/50">
+                  <th className="px-4 py-3 text-left text-xs font-semibold text-gray-400 uppercase">
+                    Rank
+                  </th>
+                  <th className="px-4 py-3 text-left text-xs font-semibold text-gray-400 uppercase">
+                    Wallet
+                  </th>
+                  <th className="px-4 py-3 text-right text-xs font-semibold text-gray-400 uppercase">
+                    Points
+                  </th>
+                  <th className="px-4 py-3 text-center text-xs font-semibold text-gray-400 uppercase">
+                    Badges
+                  </th>
+                </tr>
+              </thead>
+              <tbody>
+                {displayedData.map((entry) => (
+                  <LeaderboardRow
+                    key={entry.rank}
+                    entry={entry}
+                    accentColor={accentColor}
+                    isCurrentUser={
+                      walletAddress
+                        ? entry.walletAddress.toLowerCase() === walletAddress.toLowerCase()
+                        : false
+                    }
+                    onCopyAddress={() => {
+                      // Toast notification would go here
+                      console.log('Copied:', entry.walletAddress);
+                    }}
+                  />
+                ))}
+              </tbody>
+            </table>
+          </div>
+        )}
+      </div>
+
+      {/* Pagination */}
+      {!compactMode && data.length > itemsPerPage && (
+        <div className="px-6 py-4 border-t border-gray-700 flex items-center justify-between">
+          <div className="text-sm text-gray-400">
+            Showing {startIndex + 1} to {Math.min(endIndex, data.length)} of {data.length}
+          </div>
+          <div className="flex gap-2">
+            <button
+              onClick={() => setCurrentPage((p) => Math.max(1, p - 1))}
+              disabled={currentPage === 1}
+              className="px-3 py-1.5 rounded-lg text-sm font-medium text-gray-400 hover:text-white hover:bg-gray-700 transition-all disabled:opacity-50 disabled:cursor-not-allowed"
+            >
+              ← Previous
+            </button>
+            <div className="flex items-center gap-1">
+              {[...Array(Math.min(5, totalPages))].map((_, i) => {
+                const pageNum = i + 1;
+                return (
+                  <button
+                    key={pageNum}
+                    onClick={() => setCurrentPage(pageNum)}
+                    className={`px-3 py-1.5 rounded-lg text-sm font-medium transition-all ${
+                      currentPage === pageNum
+                        ? 'text-white'
+                        : 'text-gray-400 hover:text-white hover:bg-gray-700'
+                    }`}
+                    style={
+                      currentPage === pageNum
+                        ? {
+                            backgroundColor: accentColor,
+                            color: 'white',
+                          }
+                        : {}
+                    }
+                  >
+                    {pageNum}
+                  </button>
+                );
+              })}
+            </div>
+            <button
+              onClick={() => setCurrentPage((p) => Math.min(totalPages, p + 1))}
+              disabled={currentPage === totalPages}
+              className="px-3 py-1.5 rounded-lg text-sm font-medium text-gray-400 hover:text-white hover:bg-gray-700 transition-all disabled:opacity-50 disabled:cursor-not-allowed"
+            >
+              Next →
+            </button>
+          </div>
+        </div>
+      )}
+
+      {/* Footer */}
+      <div className="px-6 py-3 border-t border-gray-700 flex items-center justify-end text-xs text-gray-500">
+        <span className="flex items-center gap-1">
+          <ExternalLink className="w-3 h-3" />
+          @chainloyalty/react
+        </span>
+      </div>
+    </div>
+  );
+};
+
+export default Leaderboard;