@wheelx-widget/widget 0.1.18 → 0.2.0

package/README.md

@@ -8,7 +8,7 @@ An open-source, framework-agnostic React widget for cross-chain token swaps and
 - 👛 **Built-in Wallet Connection** — Dynamic SDK + Wagmi v2 supporting EVM (MetaMask, OKX, etc.) and Solana (Phantom)
 - 🎨 **Configurable Theme** — 14 color tokens for custom skinning
 - ⚛️ **Framework Agnostic** — Works with any React framework (Next.js, Vite, Create React App, etc.)
-- 📦 **Tree-shakeable** — ESM + CJS builds with TypeScript declarations
+- 📦 **ESM + CJS** — Dual-format builds with full TypeScript declarations
 - 🔌 **Configurable Default Tokens** — Set default from/to chains and tokens
 - 📱 **Deep Link Support** — Wallet app launch support in WebView (React Native) — see [Deep Link Guide](./DEEP_LINK_GUIDE.md)
 
@@ -22,6 +22,19 @@ Note: `@chakra-ui/react` and `@emotion/react` are required peer dependencies.
 
 ## Quick Start
 
+If you don't have a project yet, scaffold one first:
+
+```bash
+npm create vite@latest my-swap-page -- --template react-ts
+cd my-swap-page
+```
+
+Then install the widget and required peer dependencies:
+
+```bash
+npm install @wheelx-widget/widget @chakra-ui/react @emotion/react
+```
+
 ```tsx
 // main.tsx — wrap with ChakraProvider
 import { ChakraProvider, defaultSystem } from '@chakra-ui/react'
@@ -38,7 +51,7 @@ createRoot(document.getElementById('root')!).render(
 ```tsx
 // App.tsx
 // Import the CSS for animations (required!)
-import '@wheelx-widget/widget/dist/index.css'
+import '@wheelx-widget/widget/styles.css'
 import { WheelXProvider, WheelXWidget } from '@wheelx-widget/widget'
 
 function App() {
@@ -106,18 +119,6 @@ Customize 14 visual tokens:
 </WheelXProvider>
 ```
 
-### API Base URL
-
-Override the default WheelX API endpoint. Useful for testing against a staging or development environment.
-
-```tsx
-<WheelXProvider config={{
-  apiBaseUrl: 'https://dev-api.wheelx.fi'  // Default: 'https://api.wheelx.fi'
-}}>
-  <WheelXWidget />
-</WheelXProvider>
-```
-
 ### Fixed Recipient Address (Different Address)
 
 Configure fixed recipient addresses for EVM or Solana chains. When set, the widget will:
@@ -170,9 +171,6 @@ The main trading widget component.
 interface WidgetConfig {
   theme?: Partial<WidgetTheme>
 
-  /** API base URL. Default 'https://api.wheelx.fi' */
-  apiBaseUrl?: string
-
   from?: {
     chains?: number[]
     defaultChainId?: number
@@ -242,6 +240,16 @@ In short, three things are required:
 2. Configure `<queries>` declaration in Android's `AndroidManifest.xml`
 3. Configure `LSApplicationQueriesSchemes` in iOS's `Info.plist`
 
+## Troubleshooting
+
+| Problem | Symptom | Solution |
+|----------|---------|----------|
+| **Missing ChakraProvider** | White screen or unstyled component | Wrap your app in `<ChakraProvider value={defaultSystem}>` — the widget depends on Chakra's context |
+| **Forgot to import CSS** | Component works but has no styling/animations | Add `import '@wheelx-widget/widget/styles.css'` in your entry file |
+| **Vite dev server starts slow** | `vite dev` takes 30+ seconds | Normal — Vite pre-bundles large wallet dependencies (wagmi, viem, ethers, etc.). Subsequent starts with cache are faster |
+| **Build output is large** | dist/ folder tens of MB, main bundle ~7.5MB (1.9MB gzipped) | Expected — the widget bundles all wallet SDKs. Use code-splitting or lazy-loading in your host app if needed |
+| **React hooks errors** | "Invalid hook call" or context mismatch | You may have duplicate React instances. Ensure `react` and `react-dom` are peer dependencies in your project, and use a single version (18 or 19) |
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -36,8 +36,6 @@ interface WidgetTheme {
 }
 interface WidgetConfig {
     theme?: Partial<WidgetTheme>;
-    /** API base URL. Default 'https://api.wheelx.fi' */
-    apiBaseUrl?: string;
     from?: {
         chains?: number[];
         defaultChainId?: number;
@@ -74,6 +72,8 @@ interface WidgetConfig {
     evmDifferentAddress?: string;
     /** Solana链固定收款异地址（base58格式）。配置后，to网络为Solana链时优先使用此地址 */
     solanaDifferentAddress?: string;
+    /** Tron链固定收款异地址（T地址格式，以T开头）。配置后，to网络为Tron链时优先使用此地址 */
+    tronDifferentAddress?: string;
     /**
      * 返佣ID（affiliation code）。
      * 配置后在 quote 请求中优先使用此值；为空时回退到从 URL path 中提取。
@@ -87,7 +87,7 @@ interface WheelXProviderProps {
 }
 declare const WheelXProvider: React.FC<WheelXProviderProps>;
 
-interface routesItem {
+interface routesItem$1 {
     name: string;
     logo: string;
 }
@@ -108,7 +108,9 @@ interface TxInfoProps {
     amountOut: string;
     fromTokenInUsd?: Fraction;
     router_type: string | null | undefined;
-    routes?: routesItem[] | undefined;
+    routes?: routesItem$1[] | undefined;
+    onToggleAiRouter?: () => void;
+    hasMultipleQuotes?: boolean;
 }
 
 interface RefetchQuoteParams {
@@ -128,6 +130,29 @@ interface QuoteRequest {
     to_platform_id: number;
     sponsor_gas?: boolean;
 }
+interface routesItem {
+    name: string;
+    logo: string;
+}
+interface QuoteItem {
+    request_id: string;
+    router: string;
+    amount_out: string;
+    tx: {
+        chainId: number;
+        data: `0x${string}`;
+        to: `0x${string}`;
+        value: string;
+        gas?: bigint | null;
+        maxFeePerGas?: bigint | undefined;
+        maxPriorityFeePerGas?: bigint | undefined;
+        message?: string;
+        sender?: string;
+        tx?: string;
+    };
+    routes: routesItem[];
+    gas_fee?: string | null;
+}
 type QuoteErrorType = 'business_error' | 'http_error' | 'network_error' | 'timeout' | 'unknown_error';
 interface QuoteMutationError extends Error {
     httpStatus?: number;
@@ -154,6 +179,7 @@ interface TokenInfo {
     platform_id?: number;
     platform_type?: string[];
     isSolana?: boolean;
+    isTron?: boolean;
     fee_level?: FeeLevel;
 }
 interface TokenInfoWithBalance extends TokenInfo {
@@ -199,7 +225,7 @@ interface ChainsAndTokens {
     };
 }
 declare function getChainsAndTokens(): Promise<ChainsAndTokens>;
-declare const useChainsAndTokens: (enabled?: boolean) => _tanstack_react_query.UseQueryResult<ChainsAndTokens, Error>;
+declare const useChainsAndTokens: (enabled?: boolean) => _tanstack_react_query.UseQueryResult<NoInfer<ChainsAndTokens>, Error>;
 declare function mergeTokensWithCompositeKey(arr1: TokenInfoWithBalance[], arr2: TokenInfoWithBalance[]): TokenInfoWithBalance[];
 
 type WheelXWidgetProps = {
@@ -221,7 +247,8 @@ interface QuoteInfo {
     tx_value?: string | null;
     points?: number | 0 | string;
     quote_message?: string | null;
-    routes?: routesItem[];
+    routes?: routesItem$1[];
+    quotes?: QuoteItem[];
     solanaTxMessage?: string;
     solanaTxSender?: string;
 }
@@ -314,7 +341,7 @@ declare const useRefreshLoading: () => {
 interface Props {
     chainId: number;
     tokenAddress?: `0x${string}`;
-    connectAddress?: `0x${string}`;
+    connectAddress?: string;
 }
 interface BalanceResult {
     decimals: number;
@@ -322,7 +349,7 @@ interface BalanceResult {
     symbol: string;
     value: bigint;
 }
-declare const useTokenBalance: ({ chainId, tokenAddress, connectAddress }: Props) => BalanceResult | undefined;
+declare const useTokenBalance: ({ chainId, tokenAddress, connectAddress }: Props) => NoInfer<BalanceResult> | undefined;
 
 interface ChainsStore {
     chains: ChainInfo[] | null;
@@ -354,6 +381,27 @@ declare const useEvmAddress: () => `0x${string}` | undefined;
  * Used to detect and intercept deep links when the widget runs inside
  * a WebView (e.g., React Native, Android WebView, WKWebView).
  */
+declare global {
+    interface Window {
+        ReactNativeWebView?: {
+            postMessage?: (msg: string) => void;
+        };
+        __wheelx_wallet_callback_url__?: string;
+        __walletx_callback_params__?: Record<string, string>;
+        __wheelx_trigger_url_update__?: () => void;
+        __wheelx_callback_listener_installed?: boolean;
+        __wheelx_pending_callback__?: string;
+        DynamicLabs?: {
+            utils?: {
+                PlatformService?: unknown;
+            };
+        };
+        __DYNAMIC_LABS__?: {
+            PlatformService?: unknown;
+        };
+        PlatformService?: unknown;
+    }
+}
 /** Check if running inside a React Native WebView */
 declare const isReactNativeWebView: () => boolean;
 /** Check if running in any WebView (Android/iOS) */
@@ -401,11 +449,15 @@ interface WalletStore {
     setIsEthWalletConnected: (isEthWalletConnected: boolean) => void;
     isSolanaWalletConnected: boolean;
     setIsSolanaWalletConnected: (isSolanaWalletConnected: boolean) => void;
+    isTronWalletConnected: boolean;
+    setIsTronWalletConnected: (isTronWalletConnected: boolean) => void;
     totalConnectedWallets: number;
     setTotalConnectedWallets: () => void;
     totalWallets: number;
     solanaWalletAddress: string | null;
     setSolanaWalletAddress: (address: string | null) => void;
+    tronWalletAddress: string | null;
+    setTronWalletAddress: (address: string | null) => void;
     evmWalletAddress: string | null;
     evmWalletConnectorId: string | null;
     setEvmWalletInfo: (address: string | null, connectorId: string | null) => void;

package/dist/index.d.ts

@@ -36,8 +36,6 @@ interface WidgetTheme {
 }
 interface WidgetConfig {
     theme?: Partial<WidgetTheme>;
-    /** API base URL. Default 'https://api.wheelx.fi' */
-    apiBaseUrl?: string;
     from?: {
         chains?: number[];
         defaultChainId?: number;
@@ -74,6 +72,8 @@ interface WidgetConfig {
     evmDifferentAddress?: string;
     /** Solana链固定收款异地址（base58格式）。配置后，to网络为Solana链时优先使用此地址 */
     solanaDifferentAddress?: string;
+    /** Tron链固定收款异地址（T地址格式，以T开头）。配置后，to网络为Tron链时优先使用此地址 */
+    tronDifferentAddress?: string;
     /**
      * 返佣ID（affiliation code）。
      * 配置后在 quote 请求中优先使用此值；为空时回退到从 URL path 中提取。
@@ -87,7 +87,7 @@ interface WheelXProviderProps {
 }
 declare const WheelXProvider: React.FC<WheelXProviderProps>;
 
-interface routesItem {
+interface routesItem$1 {
     name: string;
     logo: string;
 }
@@ -108,7 +108,9 @@ interface TxInfoProps {
     amountOut: string;
     fromTokenInUsd?: Fraction;
     router_type: string | null | undefined;
-    routes?: routesItem[] | undefined;
+    routes?: routesItem$1[] | undefined;
+    onToggleAiRouter?: () => void;
+    hasMultipleQuotes?: boolean;
 }
 
 interface RefetchQuoteParams {
@@ -128,6 +130,29 @@ interface QuoteRequest {
     to_platform_id: number;
     sponsor_gas?: boolean;
 }
+interface routesItem {
+    name: string;
+    logo: string;
+}
+interface QuoteItem {
+    request_id: string;
+    router: string;
+    amount_out: string;
+    tx: {
+        chainId: number;
+        data: `0x${string}`;
+        to: `0x${string}`;
+        value: string;
+        gas?: bigint | null;
+        maxFeePerGas?: bigint | undefined;
+        maxPriorityFeePerGas?: bigint | undefined;
+        message?: string;
+        sender?: string;
+        tx?: string;
+    };
+    routes: routesItem[];
+    gas_fee?: string | null;
+}
 type QuoteErrorType = 'business_error' | 'http_error' | 'network_error' | 'timeout' | 'unknown_error';
 interface QuoteMutationError extends Error {
     httpStatus?: number;
@@ -154,6 +179,7 @@ interface TokenInfo {
     platform_id?: number;
     platform_type?: string[];
     isSolana?: boolean;
+    isTron?: boolean;
     fee_level?: FeeLevel;
 }
 interface TokenInfoWithBalance extends TokenInfo {
@@ -199,7 +225,7 @@ interface ChainsAndTokens {
     };
 }
 declare function getChainsAndTokens(): Promise<ChainsAndTokens>;
-declare const useChainsAndTokens: (enabled?: boolean) => _tanstack_react_query.UseQueryResult<ChainsAndTokens, Error>;
+declare const useChainsAndTokens: (enabled?: boolean) => _tanstack_react_query.UseQueryResult<NoInfer<ChainsAndTokens>, Error>;
 declare function mergeTokensWithCompositeKey(arr1: TokenInfoWithBalance[], arr2: TokenInfoWithBalance[]): TokenInfoWithBalance[];
 
 type WheelXWidgetProps = {
@@ -221,7 +247,8 @@ interface QuoteInfo {
     tx_value?: string | null;
     points?: number | 0 | string;
     quote_message?: string | null;
-    routes?: routesItem[];
+    routes?: routesItem$1[];
+    quotes?: QuoteItem[];
     solanaTxMessage?: string;
     solanaTxSender?: string;
 }
@@ -314,7 +341,7 @@ declare const useRefreshLoading: () => {
 interface Props {
     chainId: number;
     tokenAddress?: `0x${string}`;
-    connectAddress?: `0x${string}`;
+    connectAddress?: string;
 }
 interface BalanceResult {
     decimals: number;
@@ -322,7 +349,7 @@ interface BalanceResult {
     symbol: string;
     value: bigint;
 }
-declare const useTokenBalance: ({ chainId, tokenAddress, connectAddress }: Props) => BalanceResult | undefined;
+declare const useTokenBalance: ({ chainId, tokenAddress, connectAddress }: Props) => NoInfer<BalanceResult> | undefined;
 
 interface ChainsStore {
     chains: ChainInfo[] | null;
@@ -354,6 +381,27 @@ declare const useEvmAddress: () => `0x${string}` | undefined;
  * Used to detect and intercept deep links when the widget runs inside
  * a WebView (e.g., React Native, Android WebView, WKWebView).
  */
+declare global {
+    interface Window {
+        ReactNativeWebView?: {
+            postMessage?: (msg: string) => void;
+        };
+        __wheelx_wallet_callback_url__?: string;
+        __walletx_callback_params__?: Record<string, string>;
+        __wheelx_trigger_url_update__?: () => void;
+        __wheelx_callback_listener_installed?: boolean;
+        __wheelx_pending_callback__?: string;
+        DynamicLabs?: {
+            utils?: {
+                PlatformService?: unknown;
+            };
+        };
+        __DYNAMIC_LABS__?: {
+            PlatformService?: unknown;
+        };
+        PlatformService?: unknown;
+    }
+}
 /** Check if running inside a React Native WebView */
 declare const isReactNativeWebView: () => boolean;
 /** Check if running in any WebView (Android/iOS) */
@@ -401,11 +449,15 @@ interface WalletStore {
     setIsEthWalletConnected: (isEthWalletConnected: boolean) => void;
     isSolanaWalletConnected: boolean;
     setIsSolanaWalletConnected: (isSolanaWalletConnected: boolean) => void;
+    isTronWalletConnected: boolean;
+    setIsTronWalletConnected: (isTronWalletConnected: boolean) => void;
     totalConnectedWallets: number;
     setTotalConnectedWallets: () => void;
     totalWallets: number;
     solanaWalletAddress: string | null;
     setSolanaWalletAddress: (address: string | null) => void;
+    tronWalletAddress: string | null;
+    setTronWalletAddress: (address: string | null) => void;
     evmWalletAddress: string | null;
     evmWalletConnectorId: string | null;
     setEvmWalletInfo: (address: string | null, connectorId: string | null) => void;