@liberfi.io/ui-trade 0.1.1 → 0.1.3

package/dist/index.d.mts

@@ -1,5 +1,9 @@
-import { Chain, API } from '@liberfi.io/types';
+import * as _liberfi_io_types from '@liberfi.io/types';
+import { Chain, API, Token, Portfolio } from '@liberfi.io/types';
 import { WalletAdapter } from '@liberfi.io/wallet-connector';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { PredefinedToken } from '@liberfi.io/utils';
 
 /**
  * Input parameters for the `swap()` function returned by {@link useSwap}.
@@ -50,6 +54,38 @@ interface UseSwapOptions {
     /** Called when an error occurs at any phase of the swap flow. */
     onError?: (error: Error, phase: SwapPhase) => void;
 }
+/** Options for the {@link useSwapRoutePolling} hook. */
+interface UseSwapRoutePollingOptions {
+    /** Polling interval in ms. Defaults to 12000 (12s). */
+    interval?: number;
+    /** Pause polling (e.g. during swap execution). */
+    paused?: boolean;
+    /** Called when a route fetch fails. */
+    onError?: (error: Error) => void;
+}
+/** Configuration values for a single trade preset (slippage, fees, MEV). */
+interface TradePresetValues {
+    /** Slippage tolerance, 0-100 (percent). `null` = use default. */
+    slippage: number | null;
+    /** Priority fee in native token units. `null` = use default. */
+    priorityFee: number | null;
+    /** Tip fee in native token units. `null` = use default. */
+    tipFee: number | null;
+    /** Whether automatic fee estimation is enabled. */
+    autoFee: boolean;
+    /** Maximum fee cap when auto-fee is on (native token units). */
+    maxAutoFee: number | null;
+    /** Anti-MEV protection level. */
+    antiMev: "off" | "reduced" | "secure";
+    /** Custom RPC endpoint URL. `null` = use default. */
+    customRPC: string | null;
+}
+/** Default preset values matching Solana-typical settings. */
+declare const DEFAULT_TRADE_PRESET: TradePresetValues;
+/** Default quick-buy amounts (native token units). */
+declare const DEFAULT_BUY_AMOUNTS: number[];
+/** Default quick-sell percentages. */
+declare const DEFAULT_SELL_PERCENTAGES: number[];
 /** Confirmation status of a tracked transaction. */
 type TxConfirmationStatus = "idle" | "pending" | "confirmed" | "failed";
 /** Options for the {@link useTxConfirmation} hook. */
@@ -77,6 +113,21 @@ declare function useSwap(options?: UseSwapOptions): {
     isSwapping: boolean;
 };
 
+/**
+ * Hook that polls for swap route quotes at a configurable interval.
+ *
+ * Built on top of `useSwapRouteQuery` (TanStack Query) — automatically
+ * deduplicates requests, caches results, and invalidates when params change.
+ *
+ * Polling pauses when `paused` is true (e.g. during swap execution) or
+ * when required params are missing.
+ */
+declare function useSwapRoutePolling(params: Partial<API.SwapParams>, options?: UseSwapRoutePollingOptions): {
+    route: _liberfi_io_types.SwapRoute | undefined;
+    isRouting: boolean;
+    error: Error | null;
+};
+
 interface TrackedTx {
     chain: Chain;
     txHash: string;
@@ -104,6 +155,439 @@ declare function useTxConfirmation(options?: UseTxConfirmationOptions): {
     transactions: Map<string, TrackedTx>;
 };
 
+/** Parameters for {@link useSwapScript}. */
+interface UseSwapScriptParams {
+    /** Target chain */
+    chain: Chain;
+    /** Initial from-token address */
+    from?: string;
+    /** Initial to-token address */
+    to?: string;
+    /** Called when the swap completes (success or failure) */
+    onComplete?: (result: {
+        success: boolean;
+        txHash?: string;
+    }) => void;
+}
+/** Return value of {@link useSwapScript}. */
+interface UseSwapScriptResult {
+    /** Currently selected from-token address */
+    fromTokenAddress: string;
+    /** Currently selected to-token address */
+    toTokenAddress: string;
+    /** Update the from-token address */
+    setFromTokenAddress: (addr: string) => void;
+    /** Update the to-token address */
+    setToTokenAddress: (addr: string) => void;
+    /** From-token metadata (name, symbol, decimals, price, ...) */
+    fromToken: Token | null;
+    /** To-token metadata */
+    toToken: Token | null;
+    /** User's from-token balance */
+    fromBalance: Portfolio | null;
+    /** User's to-token balance */
+    toBalance: Portfolio | null;
+    /** Human-readable amount entered by the user */
+    amount: string | undefined;
+    /** Update the amount */
+    setAmount: (v: string | undefined) => void;
+    /** Set amount to half of the from-token balance */
+    setHalfAmount: () => void;
+    /** Set amount to the full from-token balance */
+    setMaxAmount: () => void;
+    /** Amount converted to smallest unit using token decimals */
+    amountInDecimals: string | undefined;
+    /** Amount converted to USD using token price */
+    amountInUsd: string | undefined;
+    /** Formatted output amount from the route (human-readable) */
+    outputAmount: string | undefined;
+    /** Output amount converted to USD using to-token price */
+    outputAmountInUsd: string | undefined;
+    /** Current swap route quote */
+    route: API.SwapRoute | undefined;
+    /** Whether a route is currently being fetched */
+    isRouting: boolean;
+    /** Route fetch error, if any */
+    routeError: Error | null;
+    /** Execute the swap (route -> sign -> send) */
+    swap: () => Promise<void>;
+    /** Whether a swap is currently in progress */
+    isSwapping: boolean;
+    /** Confirmation status of the most recent transaction */
+    txStatus: TxConfirmationStatus;
+    /** Whether initial data (tokens, balances) is still loading */
+    isLoading: boolean;
+}
+/** Props for {@link SwapWidget}. */
+interface SwapWidgetProps {
+    /** Target chain */
+    chain: Chain;
+    /** Initial from-token address */
+    from?: string;
+    /** Initial to-token address */
+    to?: string;
+    /** Called when the swap completes (success or failure) */
+    onComplete?: (result: {
+        success: boolean;
+        txHash?: string;
+    }) => void;
+    /** External style customization */
+    className?: string;
+}
+/** Props for {@link SwapUI}. */
+interface SwapUIProps {
+    /** From-token metadata */
+    fromToken: Token | null;
+    /** To-token metadata */
+    toToken: Token | null;
+    /** User's from-token balance */
+    fromBalance: Portfolio | null;
+    /** User's to-token balance */
+    toBalance: Portfolio | null;
+    /** Human-readable amount */
+    amount: string | undefined;
+    /** Amount in USD */
+    amountInUsd: string | undefined;
+    /** Amount change handler */
+    onAmountChange: (v: string | undefined) => void;
+    /** Set amount to half of the from-token balance */
+    onHalfAmount?: () => void;
+    /** Set amount to the full from-token balance */
+    onMaxAmount?: () => void;
+    /** Formatted output amount (human-readable) */
+    outputAmount: string | undefined;
+    /** Output amount in USD */
+    outputAmountInUsd: string | undefined;
+    /** From-token selection handler */
+    onFromTokenSelect: (addr: string) => void;
+    /** To-token selection handler */
+    onToTokenSelect: (addr: string) => void;
+    /** Current swap route quote */
+    route: API.SwapRoute | undefined;
+    /** Whether a route is being fetched */
+    isRouting: boolean;
+    /** Route error */
+    routeError: Error | null;
+    /** Open preview modal before swap */
+    onPreview: () => void;
+    /** Whether a swap is in progress */
+    isSwapping: boolean;
+    /** External style customization */
+    className?: string;
+}
+/** Props for {@link SwapPreviewModal}. */
+interface SwapPreviewModalProps {
+    /** Whether the modal is open */
+    isOpen: boolean;
+    /** Modal open/close change handler */
+    onOpenChange: (isOpen: boolean) => void;
+    /** From-token metadata */
+    fromToken: Token | null;
+    /** To-token metadata */
+    toToken: Token | null;
+    /** User's from-token balance */
+    fromBalance: Portfolio | null;
+    /** Input amount (human-readable) */
+    inputAmount: string | undefined;
+    /** Input amount in USD */
+    inputAmountInUsd: string | undefined;
+    /** Output amount (human-readable) */
+    outputAmount: string | undefined;
+    /** Output amount in USD */
+    outputAmountInUsd: string | undefined;
+    /** Current swap route */
+    route: API.SwapRoute | undefined;
+    /** Whether a route is being fetched */
+    isRouting: boolean;
+    /** Route error */
+    routeError: Error | null;
+    /** Confirm swap handler */
+    onConfirm: () => void;
+    /** Whether a swap is in progress */
+    isSwapping: boolean;
+}
+
+/**
+ * Script hook that encapsulates all data fetching and state management
+ * for the swap form.
+ *
+ * Pure TypeScript — no JSX, no UI imports.
+ */
+declare function useSwapScript(params: UseSwapScriptParams): UseSwapScriptResult;
+
+/**
+ * Swap widget — thin orchestration layer.
+ *
+ * Calls `useSwapScript` to fetch all data, renders `SwapUI` for the form
+ * and `SwapPreviewModal` for pre-swap confirmation.
+ *
+ * For custom UIs, use `useSwapScript` directly with your own presentation.
+ */
+declare function SwapWidget({ chain, from, to, onComplete, className, }: SwapWidgetProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Pure presentational component for the swap form.
+ *
+ * Receives all data and callbacks via props — no API calls, no subscriptions.
+ * Consumers can replace this component entirely while reusing `useSwapScript`.
+ */
+declare function SwapUI({ fromToken, toToken, fromBalance, toBalance, amount, amountInUsd, onAmountChange, onHalfAmount, onMaxAmount, outputAmount, outputAmountInUsd, onFromTokenSelect, onToTokenSelect, route, isRouting, routeError, onPreview, isSwapping, className, }: SwapUIProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Modal that previews swap details before confirmation.
+ *
+ * Pure presentational — all data and callbacks received via props.
+ * Shows from/to token cards, expandable route plan details,
+ * and a confirm button.
+ */
+declare function SwapPreviewModal({ isOpen, onOpenChange, fromToken, toToken, fromBalance, inputAmount, inputAmountInUsd, outputAmount, outputAmountInUsd, route, isRouting, routeError, onConfirm, isSwapping, }: SwapPreviewModalProps): react_jsx_runtime.JSX.Element;
+
+/** Parameters for {@link useInstantTradeScript}. */
+interface UseInstantTradeScriptParams {
+    /** Target chain */
+    chain: Chain;
+    /** Address of the token being traded (the non-native side) */
+    tokenAddress: string;
+    /** Called when a swap transaction is successfully submitted */
+    onSwapSubmitted?: (result: SwapResult) => void;
+    /** Called when a swap error occurs at any phase */
+    onSwapError?: (error: Error, phase: SwapPhase) => void;
+}
+/** Return value of {@link useInstantTradeScript}. */
+interface UseInstantTradeScriptResult {
+    chain: Chain;
+    tokenAddress: string;
+    nativeToken: PredefinedToken | undefined;
+    tokenInfo: Token | null;
+    nativeBalance: Portfolio | null;
+    tokenBalance: Portfolio | null;
+    direction: "buy" | "sell";
+    setDirection: (d: "buy" | "sell") => void;
+    amount: number | undefined;
+    setAmount: (v: number | undefined) => void;
+    buyPreset: number;
+    setBuyPreset: (p: number) => void;
+    sellPreset: number;
+    setSellPreset: (p: number) => void;
+    currentPresetValues: TradePresetValues;
+    settings: InstantTradeSettings;
+    updateBuySettings: (s: BuySettings) => void;
+    updateSellSettings: (s: SellSettings) => void;
+    showSettings: boolean;
+    handlePresetClick: (preset: number) => void;
+    swap: () => Promise<void>;
+    isSwapping: boolean;
+    submitText: string;
+    isDisabled: boolean;
+    isLoading: boolean;
+}
+/** Props for {@link InstantTradeWidget}. */
+interface InstantTradeWidgetProps {
+    /** Target chain */
+    chain: Chain;
+    /** Address of the token being traded */
+    tokenAddress: string;
+    /** Called when a swap transaction is submitted */
+    onSwapSubmitted?: (result: SwapResult) => void;
+    /** Called on swap error */
+    onSwapError?: (error: Error, phase: SwapPhase) => void;
+    /** Controlled settings (omit for localStorage fallback) */
+    settings?: InstantTradeSettings;
+    /** Called when settings change */
+    onSettingsChange?: (settings: InstantTradeSettings) => void;
+    /** Slot rendered next to trade-type tabs (e.g. wallet switcher) */
+    headerExtra?: ReactNode;
+    /** External style customization */
+    className?: string;
+}
+/** Props for {@link InstantTradeUI}. */
+interface InstantTradeUIProps {
+    direction: "buy" | "sell";
+    onDirectionChange: (d: "buy" | "sell") => void;
+    amount: number | undefined;
+    onAmountChange: (v: number | undefined) => void;
+    customAmounts: (number | null)[];
+    customPercentages: (number | null)[];
+    onQuickAmountClick: (v: number) => void;
+    onQuickPercentageClick: (percent: number) => void;
+    onCustomAmountsEdit: (amounts: (number | null)[]) => void;
+    onCustomPercentagesEdit: (pcts: (number | null)[]) => void;
+    tokenSymbol?: string;
+    nativeSymbol?: string;
+    nativeDecimals?: number;
+    nativeBalance?: string;
+    tokenBalance?: string;
+    amountConversion?: string;
+    preset: number;
+    onPresetChange: (p: number) => void;
+    presetValues: TradePresetValues;
+    onPresetSettingsChange: (v: TradePresetValues) => void;
+    showSettings: boolean;
+    onPresetClick: (preset: number) => void;
+    submitText: string;
+    isDisabled: boolean;
+    isLoading: boolean;
+    onSubmit: () => void;
+    className?: string;
+    headerExtra?: ReactNode;
+}
+/** Value exposed by {@link InstantTradeContext}. */
+interface InstantTradeContextValue {
+    chain: Chain;
+    tokenAddress: string;
+    nativeToken: PredefinedToken | undefined;
+    direction: "buy" | "sell";
+    setDirection: (d: "buy" | "sell") => void;
+    /** Quick-trade amount (native token units for buy, token units for sell). */
+    amount: number | undefined;
+    setAmount: (v: number | undefined) => void;
+    buyPreset: number;
+    setBuyPreset: (p: number) => void;
+    sellPreset: number;
+    setSellPreset: (p: number) => void;
+    settings: InstantTradeSettings;
+    updateBuySettings: (s: BuySettings) => void;
+    updateSellSettings: (s: SellSettings) => void;
+    currentPresetValues: TradePresetValues;
+}
+/** Props for {@link InstantTradeProvider}. */
+interface InstantTradeProviderProps {
+    /** Target chain */
+    chain: Chain;
+    /** Address of the token being traded */
+    tokenAddress: string;
+    /** Controlled settings (omit for built-in localStorage persistence) */
+    settings?: InstantTradeSettings;
+    /** Called when settings change */
+    onSettingsChange?: (settings: InstantTradeSettings) => void;
+    children: ReactNode;
+}
+/** Props for {@link InstantTradeAmountInput}. */
+interface InstantTradeAmountInputProps {
+    amount?: number;
+    onAmountChange: (amount?: number) => void;
+    preset?: number;
+    onPresetChange?: (preset: number) => void;
+    /** Called when an already-selected preset is clicked (e.g. open settings) */
+    onPresetClick?: (preset: number) => void;
+    variant?: "default" | "bordered";
+    radius?: "full" | "lg" | "md" | "sm";
+    size?: "sm" | "lg";
+    fullWidth?: boolean;
+    className?: string;
+}
+/** Props for {@link InstantTradeButton}. */
+interface InstantTradeButtonProps {
+    className?: string;
+    children?: ReactNode;
+}
+/** Props for {@link PresetFormUI}. */
+interface PresetFormUIProps {
+    value: TradePresetValues;
+    onChange: (value: TradePresetValues) => void;
+    nativeSymbol?: string;
+    nativeDecimals?: number;
+    className?: string;
+}
+/** Props for {@link PresetFormWidget}. */
+interface PresetFormWidgetProps {
+    value: TradePresetValues;
+    onChange: (value: TradePresetValues) => void;
+    chain: Chain;
+    className?: string;
+}
+
+/** Buy-side trade settings. */
+interface BuySettings {
+    /** Four customizable quick-amount buttons (native token units) */
+    customAmounts: (number | null)[];
+    /** Three preset configurations */
+    presets: TradePresetValues[];
+}
+/** Sell-side trade settings. */
+interface SellSettings {
+    /** Four customizable quick-percentage buttons (0-100) */
+    customPercentages: (number | null)[];
+    /** Three preset configurations */
+    presets: TradePresetValues[];
+}
+/** Combined buy + sell settings for instant trade. */
+interface InstantTradeSettings {
+    buy: BuySettings;
+    sell: SellSettings;
+}
+
+declare const DEFAULT_INSTANT_TRADE_SETTINGS: InstantTradeSettings;
+/** Access the nearest {@link InstantTradeProvider}. Throws if none found. */
+declare function useInstantTrade(): InstantTradeContextValue;
+/**
+ * Provides instant-trade state to descendant components.
+ *
+ * Settings follow a controlled / uncontrolled pattern:
+ * - **Controlled**: pass `settings` + `onSettingsChange` props.
+ * - **Uncontrolled** (default): settings auto-persist to localStorage keyed by chain.
+ */
+declare function InstantTradeProvider({ chain, tokenAddress, settings: controlledSettings, onSettingsChange, children, }: InstantTradeProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Script hook that encapsulates all data and state for the instant trade form.
+ *
+ * Must be used inside an {@link InstantTradeProvider}.
+ * Pure TypeScript — no JSX, no UI imports.
+ */
+declare function useInstantTradeScript(params: UseInstantTradeScriptParams): UseInstantTradeScriptResult;
+
+/**
+ * Full instant-trade widget — thin orchestration layer.
+ *
+ * Wraps `InstantTradeProvider`, calls `useInstantTradeScript` to get all data,
+ * and renders `InstantTradeUI` as the presentational layer.
+ *
+ * For custom UIs, use `useInstantTradeScript` directly inside an
+ * `InstantTradeProvider` with your own presentation.
+ */
+declare function InstantTradeWidget({ chain, tokenAddress, onSwapSubmitted, onSwapError, settings, onSettingsChange, headerExtra, className, }: InstantTradeWidgetProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Preset form widget — thin orchestration layer.
+ *
+ * Manages local state initialized from `value`, resolves chain-specific
+ * native token info, and syncs changes upward via `onChange`.
+ */
+declare function PresetFormWidget({ value, onChange, chain, className, }: PresetFormWidgetProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Pure presentational component for the instant trade form.
+ *
+ * Receives all data and callbacks via props — no API calls, no context access.
+ * Consumers can replace this component while reusing `useInstantTradeScript`.
+ */
+declare function InstantTradeUI({ direction, onDirectionChange, amount, onAmountChange, customAmounts, customPercentages, onQuickAmountClick, onQuickPercentageClick, onCustomAmountsEdit, onCustomPercentagesEdit, tokenSymbol, nativeSymbol, nativeDecimals, nativeBalance, tokenBalance, amountConversion, preset, onPresetChange, presetValues, onPresetSettingsChange, showSettings, onPresetClick, submitText, isDisabled, isLoading, onSubmit, className, headerExtra, }: InstantTradeUIProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Pure presentational preset-settings form.
+ *
+ * Renders inputs for slippage, priority fee, tip fee, auto fee,
+ * max auto fee, anti-MEV and custom RPC. All data via props.
+ */
+declare function PresetFormUI({ value, onChange, nativeSymbol, nativeDecimals, className, }: PresetFormUIProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Compact amount input with preset selector buttons.
+ *
+ * Designed for inline/header usage (e.g. token detail page).
+ * Must be rendered inside an {@link InstantTradeProvider}.
+ */
+declare function InstantTradeAmountInput({ amount, onAmountChange, preset, onPresetChange, onPresetClick, variant, radius, size, fullWidth, className, }: InstantTradeAmountInputProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Trade execution button that reads state from {@link InstantTradeProvider}.
+ *
+ * Resolves wallet, token addresses, converts amounts, applies preset
+ * settings, and calls `useSwap` from the SDK.
+ */
+declare function InstantTradeButton({ className, children, }: InstantTradeButtonProps): react_jsx_runtime.JSX.Element;
+
 declare global {
     interface Window {
         __LIBERFI_VERSION__?: {
@@ -111,6 +595,6 @@ declare global {
         };
     }
 }
-declare const _default: "0.1.1";
+declare const _default: "0.1.3";
 
-export { type SwapInput, type SwapPhase, type SwapResult, type TxConfirmationStatus, type UseSwapOptions, type UseTxConfirmationOptions, useSwap, useTxConfirmation, _default as version };
+export { type BuySettings, DEFAULT_BUY_AMOUNTS, DEFAULT_INSTANT_TRADE_SETTINGS, DEFAULT_SELL_PERCENTAGES, DEFAULT_TRADE_PRESET, InstantTradeAmountInput, type InstantTradeAmountInputProps, InstantTradeButton, type InstantTradeButtonProps, type InstantTradeContextValue, InstantTradeProvider, type InstantTradeProviderProps, type InstantTradeSettings, InstantTradeUI, type InstantTradeUIProps, InstantTradeWidget, type InstantTradeWidgetProps, PresetFormUI, type PresetFormUIProps, PresetFormWidget, type PresetFormWidgetProps, type SellSettings, type SwapInput, type SwapPhase, SwapPreviewModal, type SwapPreviewModalProps, type SwapResult, SwapUI, type SwapUIProps, SwapWidget, type SwapWidgetProps, type TradePresetValues, type TxConfirmationStatus, type UseInstantTradeScriptParams, type UseInstantTradeScriptResult, type UseSwapOptions, type UseSwapRoutePollingOptions, type UseSwapScriptParams, type UseSwapScriptResult, type UseTxConfirmationOptions, useInstantTrade, useInstantTradeScript, useSwap, useSwapRoutePolling, useSwapScript, useTxConfirmation, _default as version };