@hongming-wang/usdc-bridge-widget 0.1.0

package/src/icons.tsx

@@ -0,0 +1,228 @@
+import React from "react";
+
+interface IconProps {
+  /** Icon size in pixels */
+  size?: number;
+  /** Stroke/fill color */
+  color?: string;
+  /** Additional CSS class */
+  className?: string;
+  /** Additional inline styles */
+  style?: React.CSSProperties;
+}
+
+/**
+ * Chevron down icon for dropdowns
+ */
+export function ChevronDownIcon({
+  size = 16,
+  color = "currentColor",
+  className,
+  style,
+}: IconProps) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke={color}
+      className={className}
+      style={style}
+      aria-hidden="true"
+    >
+      <path
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth={2}
+        d="M19 9l-7 7-7-7"
+      />
+    </svg>
+  );
+}
+
+/**
+ * Swap/exchange icon for chain swap button
+ */
+export function SwapIcon({
+  size = 20,
+  color = "currentColor",
+  className,
+  style,
+}: IconProps) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke={color}
+      className={className}
+      style={style}
+      aria-hidden="true"
+    >
+      <path
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth={2}
+        d="M7 16V4m0 0L3 8m4-4l4 4m6 0v12m0 0l4-4m-4 4l-4-4"
+      />
+    </svg>
+  );
+}
+
+/**
+ * Loading spinner icon
+ */
+export function SpinnerIcon({
+  size = 20,
+  color = "currentColor",
+  className,
+  style,
+}: IconProps) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke={color}
+      className={className}
+      style={{
+        animation: "cc-spin 1s linear infinite",
+        ...style,
+      }}
+      aria-hidden="true"
+    >
+      <style>{`@keyframes cc-spin { from { transform: rotate(0deg); } to { transform: rotate(360deg); } }`}</style>
+      <circle
+        cx="12"
+        cy="12"
+        r="10"
+        strokeWidth={2}
+        strokeDasharray="32"
+        strokeLinecap="round"
+      />
+    </svg>
+  );
+}
+
+/**
+ * Check/success icon
+ */
+export function CheckIcon({
+  size = 20,
+  color = "currentColor",
+  className,
+  style,
+}: IconProps) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke={color}
+      className={className}
+      style={style}
+      aria-hidden="true"
+    >
+      <path
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth={2}
+        d="M5 13l4 4L19 7"
+      />
+    </svg>
+  );
+}
+
+/**
+ * Error/X icon
+ */
+export function ErrorIcon({
+  size = 20,
+  color = "currentColor",
+  className,
+  style,
+}: IconProps) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke={color}
+      className={className}
+      style={style}
+      aria-hidden="true"
+    >
+      <path
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth={2}
+        d="M6 18L18 6M6 6l12 12"
+      />
+    </svg>
+  );
+}
+
+/**
+ * External link icon
+ */
+export function ExternalLinkIcon({
+  size = 16,
+  color = "currentColor",
+  className,
+  style,
+}: IconProps) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke={color}
+      className={className}
+      style={style}
+      aria-hidden="true"
+    >
+      <path
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth={2}
+        d="M10 6H6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4M14 4h6m0 0v6m0-6L10 14"
+      />
+    </svg>
+  );
+}
+
+/**
+ * Wallet icon
+ */
+export function WalletIcon({
+  size = 20,
+  color = "currentColor",
+  className,
+  style,
+}: IconProps) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke={color}
+      className={className}
+      style={style}
+      aria-hidden="true"
+    >
+      <path
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth={2}
+        d="M3 10h18M3 6h18a2 2 0 012 2v10a2 2 0 01-2 2H3a2 2 0 01-2-2V8a2 2 0 012-2zm14 6h.01"
+      />
+    </svg>
+  );
+}

package/src/index.tsx

@@ -0,0 +1,111 @@
+// Main widget export
+export { BridgeWidget } from "./BridgeWidget";
+
+// Types
+export type {
+  BridgeWidgetProps,
+  BridgeWidgetTheme,
+  BridgeChainConfig,
+  BridgeEstimate,
+  BridgeResult,
+} from "./types";
+
+// Hooks (for advanced usage)
+export {
+  useUSDCBalance,
+  useAllUSDCBalances,
+  useUSDCAllowance,
+  /**
+   * @deprecated Use `useBridgeQuote` instead
+   */
+  useBridgeEstimate,
+  /**
+   * @deprecated Use `formatNumber` from utils instead
+   */
+  useFormatNumber,
+} from "./hooks";
+
+// Bridge hook
+export { useBridge, useBridgeQuote, getChainName } from "./useBridge";
+export type { BridgeParams, BridgeState, BridgeEvent, UseBridgeResult, BridgeQuote } from "./useBridge";
+
+// Utilities
+export {
+  formatNumber,
+  getErrorMessage,
+  parseUSDCAmount,
+  isValidPositiveAmount,
+  validateAmountInput,
+  validateChainConfig,
+  validateChainConfigs,
+  MAX_USDC_AMOUNT,
+  MIN_USDC_AMOUNT,
+} from "./utils";
+export type { ChainConfigValidationResult } from "./utils";
+
+// Constants
+export {
+  USDC_DECIMALS,
+  USDC_BRAND_COLOR,
+  USDC_ADDRESSES,
+  TOKEN_MESSENGER_V1_ADDRESSES,
+  TOKEN_MESSENGER_V2_ADDRESS,
+  TOKEN_MESSENGER_ADDRESSES,
+  CHAIN_ICONS,
+  DEFAULT_LOCALE,
+} from "./constants";
+
+// Chain configs and helpers
+export {
+  createChainConfig,
+  DEFAULT_CHAIN_CONFIGS,
+  // Custom chains
+  unichain,
+  hyperEvm,
+  plume,
+  monad,
+  codex,
+  // Re-exported viem chains
+  mainnet,
+  arbitrum,
+  avalanche,
+  base,
+  optimism,
+  polygon,
+  linea,
+  sei,
+  worldchain,
+  ink,
+  sonic,
+  xdc,
+  // Testnet support
+  createTestnetChainConfig,
+  TESTNET_CHAIN_CONFIGS,
+  sepolia,
+  arbitrumSepolia,
+  avalancheFuji,
+  baseSepolia,
+  optimismSepolia,
+  polygonAmoy,
+} from "./chains";
+
+// Theme utilities
+export {
+  defaultTheme,
+  mergeTheme,
+  themePresets,
+  THEME_COLORS,
+  THEME_SIZING,
+  THEME_FONTS,
+} from "./theme";
+
+// Icons (for custom implementations)
+export {
+  ChevronDownIcon,
+  SwapIcon,
+  SpinnerIcon,
+  CheckIcon,
+  ErrorIcon,
+  ExternalLinkIcon,
+  WalletIcon,
+} from "./icons";

package/src/theme.ts

@@ -0,0 +1,131 @@
+import type { BridgeWidgetTheme } from "./types";
+
+/**
+ * Default theme color palette
+ */
+export const THEME_COLORS = {
+  /** Primary accent - Indigo */
+  primary: "#6366f1",
+  /** Secondary accent - Purple */
+  secondary: "#a855f7",
+  /** Success state - Green */
+  success: "#22c55e",
+  /** Error state - Red */
+  error: "#ef4444",
+  /** Text color - White */
+  text: "#ffffff",
+  /** Muted text - Semi-transparent white */
+  mutedText: "rgba(255, 255, 255, 0.54)",
+  /** Border color - Semi-transparent white */
+  border: "rgba(255, 255, 255, 0.06)",
+  /** Background - Dark with transparency */
+  background: "rgba(15, 15, 25, 0.8)",
+  /** Card background - Darker with transparency */
+  cardBackground: "rgba(15, 15, 25, 0.6)",
+  /** Dropdown background - Near opaque dark */
+  dropdownBackground: "rgba(20, 20, 35, 0.98)",
+  /** Input background - Transparent black */
+  inputBackground: "rgba(0, 0, 0, 0.3)",
+  /** Hover state - Semi-transparent white */
+  hover: "rgba(255, 255, 255, 0.05)",
+} as const;
+
+/**
+ * Default theme spacing and sizing
+ */
+export const THEME_SIZING = {
+  /** Default border radius in pixels */
+  borderRadius: 12,
+  /** Widget max width */
+  maxWidth: "480px",
+  /** Standard padding */
+  padding: "16px",
+  /** Gap between elements */
+  gap: "12px",
+  /** Small gap */
+  smallGap: "8px",
+  /** Dropdown max height */
+  dropdownMaxHeight: "300px",
+} as const;
+
+/**
+ * Default font settings
+ */
+export const THEME_FONTS = {
+  /** Primary font family */
+  family: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+  /** Font sizes */
+  sizes: {
+    xs: "10px",
+    sm: "12px",
+    base: "14px",
+    lg: "18px",
+  },
+  /** Font weights */
+  weights: {
+    normal: 400,
+    medium: 500,
+    semibold: 600,
+    bold: 700,
+  },
+} as const;
+
+/**
+ * Default complete theme configuration
+ */
+export const defaultTheme: Required<BridgeWidgetTheme> = {
+  primaryColor: THEME_COLORS.primary,
+  secondaryColor: THEME_COLORS.secondary,
+  backgroundColor: THEME_COLORS.background,
+  cardBackgroundColor: THEME_COLORS.cardBackground,
+  textColor: THEME_COLORS.text,
+  mutedTextColor: THEME_COLORS.mutedText,
+  borderColor: THEME_COLORS.border,
+  successColor: THEME_COLORS.success,
+  errorColor: THEME_COLORS.error,
+  hoverColor: THEME_COLORS.hover,
+  borderRadius: THEME_SIZING.borderRadius,
+  fontFamily: THEME_FONTS.family,
+};
+
+/**
+ * Merge user theme overrides with defaults
+ */
+export function mergeTheme(
+  theme?: BridgeWidgetTheme
+): Required<BridgeWidgetTheme> {
+  return { ...defaultTheme, ...theme };
+}
+
+/**
+ * Pre-built theme presets
+ */
+export const themePresets = {
+  /** Default dark theme */
+  dark: defaultTheme,
+
+  /** Light theme variant */
+  light: {
+    ...defaultTheme,
+    backgroundColor: "rgba(255, 255, 255, 0.95)",
+    cardBackgroundColor: "rgba(245, 245, 245, 0.9)",
+    textColor: "#1a1a2e",
+    mutedTextColor: "rgba(0, 0, 0, 0.54)",
+    borderColor: "rgba(0, 0, 0, 0.1)",
+    hoverColor: "rgba(0, 0, 0, 0.05)",
+  } as Required<BridgeWidgetTheme>,
+
+  /** Blue accent theme */
+  blue: {
+    ...defaultTheme,
+    primaryColor: "#3b82f6",
+    secondaryColor: "#06b6d4",
+  } as Required<BridgeWidgetTheme>,
+
+  /** Green accent theme */
+  green: {
+    ...defaultTheme,
+    primaryColor: "#10b981",
+    secondaryColor: "#34d399",
+  } as Required<BridgeWidgetTheme>,
+} as const;

package/src/types.ts

@@ -0,0 +1,160 @@
+import type { Chain } from "viem";
+
+/**
+ * Theme configuration for the Bridge Widget.
+ * All color values should be valid CSS color strings (hex, rgb, rgba, etc.).
+ *
+ * @example
+ * const customTheme: BridgeWidgetTheme = {
+ *   primaryColor: "#3b82f6",
+ *   backgroundColor: "rgba(0, 0, 0, 0.9)",
+ *   borderRadius: 16,
+ * };
+ */
+export interface BridgeWidgetTheme {
+  /** Primary accent color used for buttons and highlights (hex) */
+  primaryColor?: string;
+  /** Secondary accent color used for gradients (hex) */
+  secondaryColor?: string;
+  /** Main background color of the widget (hex or rgba) */
+  backgroundColor?: string;
+  /** Background color for cards and nested elements (hex or rgba) */
+  cardBackgroundColor?: string;
+  /** Primary text color (hex) */
+  textColor?: string;
+  /** Secondary/muted text color for labels (hex or rgba) */
+  mutedTextColor?: string;
+  /** Border color for inputs and containers (hex or rgba) */
+  borderColor?: string;
+  /** Color for success states and messages (hex) */
+  successColor?: string;
+  /** Color for error states and messages (hex) */
+  errorColor?: string;
+  /** Color for hover states (hex or rgba) */
+  hoverColor?: string;
+  /** Border radius in pixels for rounded corners */
+  borderRadius?: number;
+  /** Font family for all text in the widget */
+  fontFamily?: string;
+}
+
+/**
+ * Configuration for a supported blockchain in the bridge.
+ * Contains chain metadata, USDC contract address, and CCTP TokenMessenger address.
+ *
+ * @example
+ * const ethereumConfig: BridgeChainConfig = {
+ *   chain: mainnet,
+ *   usdcAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+ *   tokenMessengerAddress: "0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d",
+ *   iconUrl: "https://icons.llamao.fi/icons/chains/rsz_ethereum.jpg",
+ * };
+ */
+export interface BridgeChainConfig {
+  /** Chain definition from viem containing id, name, and network details */
+  chain: Chain;
+  /** USDC token contract address on this chain (checksummed) */
+  usdcAddress: `0x${string}`;
+  /** Circle TokenMessenger contract address for CCTP transfers */
+  tokenMessengerAddress?: `0x${string}`;
+  /** URL for the chain's icon/logo image (optional, falls back to initial) */
+  iconUrl?: string;
+}
+
+/**
+ * Props for the BridgeWidget component.
+ *
+ * @example
+ * <BridgeWidget
+ *   defaultSourceChainId={1}
+ *   defaultDestinationChainId={8453}
+ *   onBridgeSuccess={({ txHash }) => console.log('Success:', txHash)}
+ *   onBridgeError={(error) => console.error('Error:', error)}
+ *   theme={{ primaryColor: "#3b82f6" }}
+ * />
+ */
+export interface BridgeWidgetProps {
+  /**
+   * Array of supported chains with their USDC addresses.
+   * Defaults to all CCTP-supported chains from DEFAULT_CHAIN_CONFIGS.
+   */
+  chains?: BridgeChainConfig[];
+  /** Chain ID to pre-select as the source chain */
+  defaultSourceChainId?: number;
+  /** Chain ID to pre-select as the destination chain */
+  defaultDestinationChainId?: number;
+  /**
+   * Callback fired when a bridge transaction is initiated.
+   * Called before approval (if needed) or bridge execution begins.
+   */
+  onBridgeStart?: (params: {
+    /** Source chain ID */
+    sourceChainId: number;
+    /** Destination chain ID */
+    destChainId: number;
+    /** Amount being bridged (as string) */
+    amount: string;
+    /** Transaction hash (only present if tx already submitted) */
+    txHash?: `0x${string}`;
+  }) => void;
+  /**
+   * Callback fired when a bridge transaction completes successfully.
+   * The txHash can be used to link to a block explorer.
+   */
+  onBridgeSuccess?: (params: {
+    /** Source chain ID */
+    sourceChainId: number;
+    /** Destination chain ID */
+    destChainId: number;
+    /** Amount bridged (as string) */
+    amount: string;
+    /** Transaction hash of the successful bridge */
+    txHash: `0x${string}`;
+  }) => void;
+  /**
+   * Callback fired when a bridge transaction fails.
+   * The error object contains details about what went wrong.
+   */
+  onBridgeError?: (error: Error) => void;
+  /**
+   * Callback fired when the user clicks "Connect Wallet".
+   * If not provided, the widget will attempt to use wagmi's connectors.
+   */
+  onConnectWallet?: () => void;
+  /** Custom theme overrides to customize the widget appearance */
+  theme?: BridgeWidgetTheme;
+  /** Custom CSS class name to apply to the widget container */
+  className?: string;
+  /** Custom inline styles to apply to the widget container */
+  style?: React.CSSProperties;
+}
+
+/**
+ * Estimated costs and timing for a bridge transfer.
+ * Used by the deprecated useBridgeEstimate hook.
+ *
+ * @deprecated Use BridgeQuote from useBridge.ts instead
+ */
+export interface BridgeEstimate {
+  /** Estimated gas fee (as formatted string) */
+  gasFee: string;
+  /** Protocol bridge fee (as formatted string) */
+  bridgeFee: string;
+  /** Total estimated fee including gas and protocol (as formatted string) */
+  totalFee: string;
+  /** Estimated time for the bridge to complete (e.g., "~15-20 minutes") */
+  estimatedTime: string;
+}
+
+/**
+ * Result state for a bridge operation.
+ * Tracks the current state and any associated transaction hash or error.
+ */
+export interface BridgeResult {
+  /** Current state of the bridge operation */
+  state: "idle" | "pending" | "success" | "error";
+  /** Transaction hash if a transaction has been submitted */
+  txHash?: `0x${string}`;
+  /** Error message if the operation failed */
+  error?: string;
+}