@b3dotfun/sdk 0.0.42-alpha.2 → 0.0.42-alpha.3

package/src/shared/react/hooks/__tests__/useCurrencyConversion.test.ts

@@ -0,0 +1,308 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook } from "@testing-library/react";
+import { useCurrencyConversion } from "../useCurrencyConversion";
+
+// Mock the external dependencies
+// Store mock rates for different quote currencies
+const mockRates: Record<string, number | undefined> = {};
+
+// Mock store state
+const mockStoreState: any = {
+  selectedCurrency: "B3",
+  baseCurrency: "B3",
+  setSelectedCurrency: vi.fn(),
+  setBaseCurrency: vi.fn(),
+};
+
+vi.mock("@b3dotfun/sdk/global-account/react", () => ({
+  useExchangeRate: vi.fn((params: any) => {
+    const rate = mockRates[params?.quoteCurrency];
+    return { rate };
+  }),
+}));
+
+vi.mock("@b3dotfun/sdk/shared/utils/number", () => ({
+  formatDisplayNumber: vi.fn((value: any) => {
+    const num = Number(value);
+    if (isNaN(num)) return "0";
+    return num.toLocaleString("en-US", { maximumFractionDigits: 6 });
+  }),
+}));
+
+vi.mock("../../stores/currencyStore", () => ({
+  useCurrencyStore: vi.fn((selector: any) => {
+    if (selector) {
+      return selector(mockStoreState);
+    }
+    return mockStoreState;
+  }),
+  CURRENCY_SYMBOLS: {
+    B3: "B3",
+    USD: "$",
+    EUR: "€",
+    GBP: "£",
+    JPY: "¥",
+    CAD: "C$",
+    AUD: "A$",
+    ETH: "ETH",
+    SOL: "SOL",
+    KRW: "₩",
+  },
+}));
+
+describe("useCurrencyConversion", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // Reset mock rates to default
+    Object.keys(mockRates).forEach(key => delete mockRates[key]);
+    mockRates.USD = 1.0;
+    // Reset store state
+    mockStoreState.selectedCurrency = "B3";
+    mockStoreState.baseCurrency = "B3";
+  });
+
+  describe("formatCurrencyValue", () => {
+    it("should format base currency (B3) without conversion", () => {
+      mockStoreState.selectedCurrency = "B3";
+      mockStoreState.baseCurrency = "B3";
+
+      const { result } = renderHook(() => useCurrencyConversion());
+      const formatted = result.current.formatCurrencyValue(100);
+
+      expect(formatted).toContain("B3");
+      expect(formatted).toContain("100");
+    });
+
+    it("should show base currency when exchange rate is unavailable", () => {
+      mockRates.USD = undefined;
+      mockStoreState.selectedCurrency = "USD";
+      mockStoreState.baseCurrency = "B3";
+
+      const { result } = renderHook(() => useCurrencyConversion());
+      const formatted = result.current.formatCurrencyValue(100);
+
+      expect(formatted).toContain("B3");
+      expect(formatted).not.toContain("$");
+    });
+
+    it("should format USD with prefix symbol", () => {
+      mockRates.USD = 2.0;
+      mockStoreState.selectedCurrency = "USD";
+      mockStoreState.baseCurrency = "B3";
+
+      const { result } = renderHook(() => useCurrencyConversion());
+      const formatted = result.current.formatCurrencyValue(100);
+
+      expect(formatted).toMatch(/^\$/);
+      expect(formatted).toContain("200");
+    });
+
+    it("should format EUR with prefix symbol", () => {
+      mockRates.EUR = 1.8;
+      mockRates.USD = 2.0;
+      mockStoreState.selectedCurrency = "EUR";
+      mockStoreState.baseCurrency = "B3";
+
+      const { result } = renderHook(() => useCurrencyConversion());
+      const formatted = result.current.formatCurrencyValue(100);
+
+      expect(formatted).toMatch(/^€/);
+    });
+
+    it("should format JPY without decimals", () => {
+      mockRates.JPY = 150;
+      mockRates.USD = 2.0;
+      mockStoreState.selectedCurrency = "JPY";
+      mockStoreState.baseCurrency = "B3";
+
+      const { result } = renderHook(() => useCurrencyConversion());
+      const formatted = result.current.formatCurrencyValue(100);
+
+      expect(formatted).toContain("¥");
+      expect(formatted).not.toContain(".");
+    });
+
+    it("should format KRW without decimals", () => {
+      mockRates.KRW = 1300;
+      mockRates.USD = 2.0;
+      mockStoreState.selectedCurrency = "KRW";
+      mockStoreState.baseCurrency = "B3";
+
+      const { result } = renderHook(() => useCurrencyConversion());
+      const formatted = result.current.formatCurrencyValue(100);
+
+      expect(formatted).toContain("₩");
+      expect(formatted).not.toContain(".");
+    });
+
+    it("should format ETH with suffix symbol", () => {
+      mockRates.ETH = 0.0005;
+      mockRates.USD = 2.0;
+      mockStoreState.selectedCurrency = "ETH";
+      mockStoreState.baseCurrency = "B3";
+
+      const { result } = renderHook(() => useCurrencyConversion());
+      const formatted = result.current.formatCurrencyValue(100);
+
+      expect(formatted).toContain("ETH");
+      expect(formatted).not.toMatch(/^ETH/);
+    });
+
+    it("should format SOL with suffix symbol", () => {
+      mockRates.SOL = 0.05;
+      mockRates.USD = 2.0;
+      mockStoreState.selectedCurrency = "SOL";
+      mockStoreState.baseCurrency = "B3";
+
+      const { result } = renderHook(() => useCurrencyConversion());
+      const formatted = result.current.formatCurrencyValue(100);
+
+      expect(formatted).toContain("SOL");
+      expect(formatted).not.toMatch(/^SOL/);
+    });
+
+    it("should handle small USD amounts with proper conversion", () => {
+      mockRates.USD = 1.5;
+      mockStoreState.selectedCurrency = "USD";
+      mockStoreState.baseCurrency = "B3";
+
+      const { result } = renderHook(() => useCurrencyConversion());
+      const formatted = result.current.formatCurrencyValue(10);
+
+      // 10 * 1.5 = 15
+      expect(formatted).toMatch(/^\$/);
+      expect(formatted).toContain("15");
+    });
+
+    it("should apply correct exchange rate conversion", () => {
+      const testRate = 3.5;
+      mockRates.USD = testRate;
+      mockStoreState.selectedCurrency = "USD";
+      mockStoreState.baseCurrency = "B3";
+
+      const { result } = renderHook(() => useCurrencyConversion());
+      const inputValue = 100;
+      const formatted = result.current.formatCurrencyValue(inputValue);
+
+      expect(formatted).toContain("350");
+    });
+  });
+
+  describe("return values", () => {
+    it("should return selected currency", () => {
+      mockStoreState.selectedCurrency = "USD";
+      mockStoreState.baseCurrency = "B3";
+
+      const { result } = renderHook(() => useCurrencyConversion());
+
+      expect(result.current.selectedCurrency).toBe("USD");
+    });
+
+    it("should return base currency", () => {
+      mockStoreState.selectedCurrency = "USD";
+      mockStoreState.baseCurrency = "B3";
+
+      const { result } = renderHook(() => useCurrencyConversion());
+
+      expect(result.current.baseCurrency).toBe("B3");
+    });
+
+    it("should return exchange rate", () => {
+      const testRate = 2.5;
+      mockRates.USD = testRate;
+      mockStoreState.selectedCurrency = "USD";
+      mockStoreState.baseCurrency = "B3";
+
+      const { result } = renderHook(() => useCurrencyConversion());
+
+      expect(result.current.exchangeRate).toBe(testRate);
+    });
+
+    it("should return correct currency symbols", () => {
+      mockStoreState.selectedCurrency = "EUR";
+      mockStoreState.baseCurrency = "B3";
+
+      const { result } = renderHook(() => useCurrencyConversion());
+
+      expect(result.current.selectedCurrencySymbol).toBe("€");
+      expect(result.current.baseCurrencySymbol).toBe("B3");
+    });
+  });
+
+  describe("formatTooltipValue", () => {
+    it("should show USD equivalent when displaying base currency", () => {
+      mockRates.USD = 1.5;
+      mockStoreState.selectedCurrency = "B3";
+      mockStoreState.baseCurrency = "B3";
+
+      const { result } = renderHook(() => useCurrencyConversion());
+      const tooltip = result.current.formatTooltipValue(100);
+
+      expect(tooltip).toContain("USD");
+      expect(tooltip).toContain("150");
+    });
+
+    it("should show base currency when displaying other currency", () => {
+      mockRates.EUR = 0.9;
+      mockRates.USD = 1.2;
+      mockStoreState.selectedCurrency = "EUR";
+      mockStoreState.baseCurrency = "B3";
+
+      const { result } = renderHook(() => useCurrencyConversion());
+      const tooltip = result.current.formatTooltipValue(100);
+
+      expect(tooltip).toContain("B3");
+      expect(tooltip).toContain("100");
+    });
+
+    it("should handle custom currency for base currency", () => {
+      mockRates.USD = 2.0;
+      mockRates.EUR = 1.8;
+      mockStoreState.selectedCurrency = "EUR";
+      mockStoreState.baseCurrency = "B3";
+
+      const { result } = renderHook(() => useCurrencyConversion());
+      const tooltip = result.current.formatTooltipValue(100, "B3");
+
+      expect(tooltip).toContain("USD");
+      expect(tooltip).toContain("200");
+    });
+
+    it("should handle custom currency for non-base currency", () => {
+      mockRates.USD = 2.0;
+      mockStoreState.selectedCurrency = "USD";
+      mockStoreState.baseCurrency = "B3";
+
+      const { result } = renderHook(() => useCurrencyConversion());
+      const tooltip = result.current.formatTooltipValue(50, "ETH");
+
+      expect(tooltip).toContain("ETH");
+      expect(tooltip).toContain("50");
+    });
+
+    it("should handle absolute values for negative amounts", () => {
+      mockRates.USD = 1.5;
+      mockStoreState.selectedCurrency = "B3";
+      mockStoreState.baseCurrency = "B3";
+
+      const { result } = renderHook(() => useCurrencyConversion());
+      const tooltip = result.current.formatTooltipValue(-100);
+
+      expect(tooltip).toContain("USD");
+      expect(tooltip).toContain("150");
+      expect(tooltip).not.toContain("-");
+    });
+
+    it("should handle exchange rate unavailable", () => {
+      mockRates.USD = undefined;
+      mockStoreState.selectedCurrency = "B3";
+      mockStoreState.baseCurrency = "B3";
+
+      const { result } = renderHook(() => useCurrencyConversion());
+      const tooltip = result.current.formatTooltipValue(100);
+
+      expect(tooltip).toContain("USD");
+      expect(tooltip).toContain("100");
+    });
+  });
+});

package/src/shared/react/hooks/index.ts

@@ -1 +1,2 @@
+export * from "./useCurrencyConversion";
 export * from "./useNavigation";

package/src/shared/react/hooks/useCurrencyConversion.ts

@@ -0,0 +1,211 @@
+import { useExchangeRate } from "@b3dotfun/sdk/global-account/react";
+import { formatDisplayNumber } from "@b3dotfun/sdk/shared/utils/number";
+import { CURRENCY_SYMBOLS, useCurrencyStore } from "../stores/currencyStore";
+
+/**
+ * Hook for currency conversion and formatting with real-time exchange rates.
+ *
+ * This hook provides currency conversion functionality using live exchange rates
+ * and formats values according to currency-specific rules (decimals, symbols, etc.).
+ *
+ * @returns Currency conversion utilities and state
+ *
+ * @example
+ * ```tsx
+ * function PriceDisplay({ amount }: { amount: number }) {
+ *   const { formatCurrencyValue, selectedCurrency } = useCurrencyConversion();
+ *   return <div>{formatCurrencyValue(amount)}</div>;
+ * }
+ * ```
+ */
+export function useCurrencyConversion() {
+  const selectedCurrency = useCurrencyStore(state => state.selectedCurrency);
+  const baseCurrency = useCurrencyStore(state => state.baseCurrency);
+
+  // Get exchange rate for the selected currency
+  const { rate: exchangeRate } = useExchangeRate({
+    baseCurrency,
+    quoteCurrency: selectedCurrency === baseCurrency ? "USD" : selectedCurrency,
+  });
+
+  // Always fetch USD rate for tooltip purposes
+  const { rate: usdRate } = useExchangeRate({
+    baseCurrency,
+    quoteCurrency: "USD",
+  });
+
+  /**
+   * Formats a numeric value as a currency string with proper conversion and formatting.
+   *
+   * Behavior:
+   * - When exchange rate is unavailable, displays value in base currency
+   * - Applies currency-specific formatting rules:
+   *   - JPY/KRW: No decimal places
+   *   - ETH/SOL: 6 significant digits with subscript notation for small values
+   *   - Fiat (USD/EUR/GBP/CAD/AUD): 2 decimal places minimum for values < 1000
+   * - Handles symbol positioning (prefix for fiat, suffix for crypto)
+   *
+   * @param value - The numeric value to format (in base currency)
+   * @param options - Optional formatting overrides
+   * @param options.decimals - Override number of decimal places
+   * @param options.currency - Override currency (bypasses conversion)
+   * @returns Formatted currency string with appropriate symbol and decimal places
+   *
+   * @example
+   * ```tsx
+   * formatCurrencyValue(100) // Returns "$100.00" if USD is selected
+   * formatCurrencyValue(0.0001) // Returns "0.0₄1 ETH" if ETH is selected
+   * formatCurrencyValue(1500) // Returns "¥1,500" if JPY is selected
+   * formatCurrencyValue(100, { decimals: 4, currency: "ETH" }) // Returns "100.0000 ETH"
+   * ```
+   */
+  const formatCurrencyValue = (value: number, options?: { decimals?: number; currency?: string }): string => {
+    const overrideCurrency = options?.currency;
+    const overrideDecimals = options?.decimals;
+
+    // Custom currency provided - bypass conversion and use simple formatting
+    if (overrideCurrency) {
+      const decimalsToUse = overrideDecimals !== undefined ? overrideDecimals : overrideCurrency === "B3" ? 0 : 2;
+
+      const formatted = formatDisplayNumber(value, {
+        fractionDigits: decimalsToUse,
+        showSubscripts: false,
+      });
+      return `${formatted} ${overrideCurrency}`;
+    }
+
+    // Custom decimals for base currency without conversion
+    if (overrideDecimals !== undefined && selectedCurrency === baseCurrency) {
+      const formatted = formatDisplayNumber(value, {
+        fractionDigits: overrideDecimals,
+        showSubscripts: false,
+      });
+      return `${formatted} ${baseCurrency}`;
+    }
+
+    // If no exchange rate available, show base currency to prevent showing
+    // incorrect values with wrong currency symbols during rate fetching
+    if (selectedCurrency === baseCurrency || !exchangeRate) {
+      const formatted = formatDisplayNumber(value, {
+        significantDigits: baseCurrency === "B3" ? 6 : 8,
+        showSubscripts: true,
+      });
+      return `${formatted} ${baseCurrency}`;
+    }
+
+    // Convert value using current exchange rate
+    const convertedValue = value * exchangeRate;
+    const symbol = CURRENCY_SYMBOLS[selectedCurrency];
+
+    // Currencies that display symbol before the number (e.g., $100.00)
+    const prefixCurrencies = ["USD", "EUR", "GBP", "CAD", "AUD"];
+
+    let formatted: string;
+
+    if (selectedCurrency === "JPY" || selectedCurrency === "KRW") {
+      // Japanese Yen and Korean Won don't use decimal places
+      formatted = formatDisplayNumber(convertedValue, {
+        fractionDigits: 0,
+        showSubscripts: false,
+      });
+    } else if (selectedCurrency === "ETH" || selectedCurrency === "SOL") {
+      // Crypto currencies use more precision and subscript notation
+      // for very small amounts (e.g., 0.0₃45 ETH)
+      formatted = formatDisplayNumber(convertedValue, {
+        significantDigits: 6,
+        showSubscripts: true,
+      });
+    } else {
+      // Standard fiat currencies (USD, EUR, GBP, CAD, AUD)
+      // Use 2 decimal places minimum for amounts under 1000
+      formatted = formatDisplayNumber(convertedValue, {
+        significantDigits: 6,
+        fractionDigits: convertedValue < 1000 ? 2 : undefined,
+        showSubscripts: true,
+      });
+    }
+
+    // Apply currency symbol with correct positioning
+    if (prefixCurrencies.includes(selectedCurrency)) {
+      return `${symbol}${formatted}`;
+    } else {
+      // Suffix currencies: JPY, KRW, ETH, SOL, B3
+      return `${formatted} ${symbol}`;
+    }
+  };
+
+  /**
+   * Formats a tooltip value showing the alternate currency representation.
+   *
+   * Behavior:
+   * - When displaying base currency: Shows USD equivalent
+   * - When displaying other currency: Shows base currency equivalent
+   * - For custom currencies: Shows appropriate conversion or original value
+   *
+   * @param value - The numeric value to format
+   * @param customCurrency - Optional custom currency override
+   * @returns Formatted tooltip string
+   *
+   * @example
+   * ```tsx
+   * formatTooltipValue(100) // Returns "$150.00 USD" if displaying B3 with rate 1.5
+   * formatTooltipValue(100, "ETH") // Returns "100.0000 ETH" if custom currency
+   * ```
+   */
+  const formatTooltipValue = (value: number, customCurrency?: string): string => {
+    const displayCurrency = customCurrency || selectedCurrency;
+    const absoluteValue = Math.abs(value);
+
+    // Custom currency provided
+    if (customCurrency) {
+      if (customCurrency === baseCurrency) {
+        // Show USD equivalent for base currency using USD rate
+        const usdValue = usdRate ? absoluteValue * usdRate : absoluteValue;
+        const formatted = formatDisplayNumber(usdValue, {
+          significantDigits: 6,
+          fractionDigits: usdValue < 1000 ? 2 : undefined,
+          showSubscripts: true,
+        });
+        return `$${formatted} USD`;
+      } else {
+        // Show as-is for other custom currencies
+        return `${formatDisplayNumber(absoluteValue, { significantDigits: 6 })} ${customCurrency}`;
+      }
+    }
+
+    // Showing base currency - display USD equivalent
+    if (displayCurrency === baseCurrency) {
+      const usdValue = usdRate ? absoluteValue * usdRate : absoluteValue;
+      const formatted = formatDisplayNumber(usdValue, {
+        significantDigits: 6,
+        fractionDigits: usdValue < 1000 ? 2 : undefined,
+        showSubscripts: true,
+      });
+      return `$${formatted} USD`;
+    }
+
+    // Showing other currency - display base currency equivalent
+    const formatted = formatDisplayNumber(absoluteValue, {
+      significantDigits: baseCurrency === "B3" ? 6 : 8,
+      showSubscripts: true,
+    });
+    return `${formatted} ${baseCurrency}`;
+  };
+
+  return {
+    /** Currently selected display currency */
+    selectedCurrency,
+    /** Base currency used for conversion (typically B3) */
+    baseCurrency,
+    /** Current exchange rate from base to selected currency (undefined while loading) */
+    exchangeRate,
+    /** Format a value with currency conversion and proper symbol/decimal handling */
+    formatCurrencyValue,
+    /** Format a tooltip value showing alternate currency representation */
+    formatTooltipValue,
+    /** Symbol for the currently selected currency (e.g., "$", "€", "ETH") */
+    selectedCurrencySymbol: CURRENCY_SYMBOLS[selectedCurrency],
+    /** Symbol for the base currency */
+    baseCurrencySymbol: CURRENCY_SYMBOLS[baseCurrency],
+  };
+}

package/src/shared/react/index.ts

@@ -1 +1,3 @@
+export * from "./components";
 export * from "./hooks";
+export * from "./stores";

package/src/shared/react/stores/currencyModalStore.ts

@@ -0,0 +1,13 @@
+import { create } from "zustand";
+
+interface CurrencyModalState {
+  isOpen: boolean;
+  openModal: () => void;
+  closeModal: () => void;
+}
+
+export const useCurrencyModalStore = create<CurrencyModalState>(set => ({
+  isOpen: false,
+  openModal: () => set({ isOpen: true }),
+  closeModal: () => set({ isOpen: false }),
+}));

package/src/shared/react/stores/currencyStore.ts

@@ -0,0 +1,82 @@
+import { create } from "zustand";
+import { persist } from "zustand/middleware";
+
+/**
+ * Supported currencies for display and conversion.
+ * Includes fiat currencies (USD, EUR, GBP, JPY, CAD, AUD, KRW) and crypto (ETH, SOL, B3).
+ */
+export type SupportedCurrency = "ETH" | "USD" | "EUR" | "GBP" | "JPY" | "CAD" | "AUD" | "B3" | "SOL" | "KRW";
+
+/**
+ * Currency symbols used for display formatting.
+ * Prefix currencies (USD, EUR, GBP, CAD, AUD) show symbol before the amount.
+ * Suffix currencies (JPY, KRW, ETH, SOL, B3) show symbol after the amount.
+ */
+export const CURRENCY_SYMBOLS: Record<SupportedCurrency, string> = {
+  ETH: "ETH",
+  USD: "$",
+  EUR: "€",
+  GBP: "£",
+  JPY: "¥",
+  CAD: "C$",
+  AUD: "A$",
+  B3: "B3",
+  SOL: "SOL",
+  KRW: "₩",
+};
+
+/**
+ * Human-readable currency names for display in selectors and labels.
+ */
+export const CURRENCY_NAMES: Record<SupportedCurrency, string> = {
+  ETH: "Ethereum",
+  USD: "US Dollar",
+  EUR: "Euro",
+  GBP: "British Pound",
+  JPY: "Japanese Yen",
+  CAD: "Canadian Dollar",
+  AUD: "Australian Dollar",
+  B3: "B3",
+  SOL: "Solana",
+  KRW: "Korean Won",
+};
+
+/**
+ * Currency store state interface.
+ * @property selectedCurrency - The currency currently selected for display
+ * @property baseCurrency - The base currency for conversion (typically B3)
+ * @property setSelectedCurrency - Update the selected display currency
+ * @property setBaseCurrency - Update the base currency for conversions
+ */
+interface CurrencyState {
+  selectedCurrency: SupportedCurrency;
+  baseCurrency: SupportedCurrency;
+  setSelectedCurrency: (currency: SupportedCurrency) => void;
+  setBaseCurrency: (currency: SupportedCurrency) => void;
+}
+
+/**
+ * Zustand store for managing currency selection and conversion.
+ * Persists user's selected currency preference in localStorage.
+ *
+ * @example
+ * ```tsx
+ * const { selectedCurrency, setSelectedCurrency } = useCurrencyStore();
+ * // Change display currency to USD
+ * setSelectedCurrency('USD');
+ * ```
+ */
+export const useCurrencyStore = create<CurrencyState>()(
+  persist(
+    set => ({
+      selectedCurrency: "B3",
+      baseCurrency: "B3",
+      setSelectedCurrency: currency => set({ selectedCurrency: currency }),
+      setBaseCurrency: currency => set({ baseCurrency: currency }),
+    }),
+    {
+      name: "currency-storage",
+      version: 2,
+    },
+  ),
+);

package/src/shared/react/stores/index.ts

@@ -0,0 +1,2 @@
+export * from "./currencyModalStore";
+export * from "./currencyStore";