@liberfi.io/ui-trade 0.1.2 → 0.1.3

package/README.md

@@ -1,11 +1,12 @@
 # @liberfi.io/ui-trade
 
-Trade hooks and swap widget for the Liberfi React SDK. This package provides chain-agnostic swap logic and a ready-to-use swap form component that works across Solana, Ethereum, and BSC.
+Trade hooks and widgets for the Liberfi React SDK. This package provides chain-agnostic swap logic and ready-to-use trade form components that work across Solana, Ethereum, and BSC.
 
-The package is organized in two layers:
+The package is organized in three layers:
 
 - **Hooks** (`useSwap`, `useSwapRoutePolling`, `useTxConfirmation`) — pure-logic building blocks with no UI side-effects, designed for IoC.
 - **Swap Widget** (`SwapWidget` / `useSwapScript` / `SwapUI` / `SwapPreviewModal`) — a full swap form with preview-before-confirm flow, following the Script/Widget/UI three-layer architecture, composable at any level.
+- **Instant Trade** (`InstantTradeWidget` / `InstantTradeProvider` / `PresetFormWidget`) — a configurable quick-trade form with buy/sell tabs, preset management, customizable quick-amount buttons, and trade settings (slippage, priority fee, tip fee, anti-MEV).
 
 ## Design Philosophy
 
@@ -478,11 +479,201 @@ function EvmSwapButton() {
 }
 ```
 
+### Components (Instant Trade)
+
+The instant trade module provides a configurable quick-trade form with preset management and customizable quick-amount buttons.
+
+#### `InstantTradeWidget`
+
+Full instant-trade form with buy/sell tabs, amount input, quick buttons, preset management, and trade execution.
+
+```tsx
+<InstantTradeWidget
+  chain={Chain.SOLANA}
+  tokenAddress="EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
+  onSwapSubmitted={(result) => console.log(result)}
+  onSwapError={(error, phase) => console.error(error)}
+/>
+```
+
+**Props (`InstantTradeWidgetProps`):**
+
+| Name                | Type                                       | Description                                           |
+| ------------------- | ------------------------------------------ | ----------------------------------------------------- |
+| `chain`             | `Chain`                                    | Target chain.                                         |
+| `tokenAddress`      | `string`                                   | Address of the token being traded.                    |
+| `onSwapSubmitted?`  | `(result: SwapResult) => void`             | Called when a swap is submitted.                      |
+| `onSwapError?`      | `(error: Error, phase: SwapPhase) => void` | Called on swap error.                                 |
+| `settings?`         | `InstantTradeSettings`                     | Controlled settings (omit for localStorage).          |
+| `onSettingsChange?` | `(settings: InstantTradeSettings) => void` | Called when settings change.                          |
+| `headerExtra?`      | `ReactNode`                                | Slot for extra header content (e.g. wallet switcher). |
+| `className?`        | `string`                                   | External style customization.                         |
+
+#### `InstantTradeProvider`
+
+Context provider for instant trade state. Use with `InstantTradeAmountInput` and `InstantTradeButton` for compact inline trading.
+
+```tsx
+<InstantTradeProvider chain={Chain.SOLANA} tokenAddress="...">
+  <InstantTradeAmountInput
+    amount={amount}
+    onAmountChange={setAmount}
+    preset={preset}
+    onPresetChange={setPreset}
+  />
+  <InstantTradeButton />
+</InstantTradeProvider>
+```
+
+#### `useInstantTradeScript(params)`
+
+Script-layer hook for the instant trade form. Must be used inside an `InstantTradeProvider`. Encapsulates token queries, balance queries, form state, and swap execution.
+
+#### `InstantTradeAmountInput`
+
+Compact amount input with lightning icon, native token avatar, and 3 preset buttons (P1/P2/P3) with tooltips. Must be inside an `InstantTradeProvider`.
+
+#### `InstantTradeButton`
+
+Trade execution button that reads state from `InstantTradeProvider`. Handles wallet resolution, amount conversion, and swap execution.
+
+#### `PresetFormWidget`
+
+Standalone widget for editing trade preset values (slippage, priority fee, tip fee, auto fee, anti-MEV, custom RPC).
+
+```tsx
+<PresetFormWidget
+  chain={Chain.SOLANA}
+  value={presetValues}
+  onChange={setPresetValues}
+/>
+```
+
+#### `PresetFormUI`
+
+Pure presentational preset form. Accepts value/onChange props directly, with optional `nativeSymbol` and `nativeDecimals`.
+
+### Instant Trade Types
+
+#### `TradePresetValues`
+
+```typescript
+interface TradePresetValues {
+  slippage: number | null;
+  priorityFee: number | null;
+  tipFee: number | null;
+  autoFee: boolean;
+  maxAutoFee: number | null;
+  antiMev: "off" | "reduced" | "secure";
+  customRPC: string | null;
+}
+```
+
+#### `InstantTradeSettings`
+
+```typescript
+interface InstantTradeSettings {
+  buy: BuySettings;
+  sell: SellSettings;
+}
+
+interface BuySettings {
+  customAmounts: (number | null)[];
+  presets: TradePresetValues[];
+}
+
+interface SellSettings {
+  customPercentages: (number | null)[];
+  presets: TradePresetValues[];
+}
+```
+
+#### `DEFAULT_TRADE_PRESET`
+
+Default preset values: slippage=20, priorityFee=0.001, tipFee=0.001, autoFee=false, maxAutoFee=0.1, antiMev="off".
+
+#### `DEFAULT_INSTANT_TRADE_SETTINGS`
+
+Default settings with 4 buy amounts (0.01, 0.1, 1, 10), 4 sell percentages (10, 25, 50, 100), and 3 default presets each.
+
+## Usage Examples
+
+### InstantTradeWidget (Full Trade Form)
+
+```tsx
+import { Chain } from "@liberfi.io/types";
+import { InstantTradeWidget } from "@liberfi.io/ui-trade";
+
+function TokenTradePage({ tokenAddress }: { tokenAddress: string }) {
+  return (
+    <InstantTradeWidget
+      chain={Chain.SOLANA}
+      tokenAddress={tokenAddress}
+      onSwapSubmitted={(result) => {
+        toast.success(`Transaction submitted: ${result.txHash}`);
+      }}
+      onSwapError={(error, phase) => {
+        toast.error(`Swap failed at ${phase}: ${error.message}`);
+      }}
+    />
+  );
+}
+```
+
+### Compact Inline Trading
+
+```tsx
+import { Chain } from "@liberfi.io/types";
+import {
+  InstantTradeProvider,
+  InstantTradeAmountInput,
+  InstantTradeButton,
+} from "@liberfi.io/ui-trade";
+
+function TokenHeader({ tokenAddress }: { tokenAddress: string }) {
+  return (
+    <InstantTradeProvider chain={Chain.SOLANA} tokenAddress={tokenAddress}>
+      <div className="flex items-center gap-2">
+        <InstantTradeAmountInput
+          amount={undefined}
+          onAmountChange={() => {}}
+          variant="bordered"
+          size="sm"
+        />
+        <InstantTradeButton />
+      </div>
+    </InstantTradeProvider>
+  );
+}
+```
+
+### Preset Settings Editor
+
+```tsx
+import { useState } from "react";
+import { Chain } from "@liberfi.io/types";
+import { PresetFormWidget, DEFAULT_TRADE_PRESET } from "@liberfi.io/ui-trade";
+
+function TradeSettings() {
+  const [preset, setPreset] = useState(DEFAULT_TRADE_PRESET);
+
+  return (
+    <PresetFormWidget
+      chain={Chain.SOLANA}
+      value={preset}
+      onChange={setPreset}
+    />
+  );
+}
+```
+
 ## Future Improvements
 
 - Add `useSwapQuote` hook for fetching quotes without executing (read-only route info).
 - Add ERC20 approval detection and `useTokenApproval` hook for EVM chains that don't support permit.
 - Support `ExactOut` swap mode with output amount estimation.
 - Add a skeleton loading component (`swap-skeleton.ui.tsx`) for the swap form.
-- Add slippage / priority fee / anti-MEV configuration to `SwapWidget` props.
 - Support token-select callback props on `SwapWidget` for integrating with external token picker UI.
+- Add limit order and advanced trade modes to `InstantTradeWidget`.
+- Add token price conversion display in the instant trade form.
+- Support custom RPC endpoint validation in `PresetFormWidget`.

package/dist/index.d.mts

@@ -2,6 +2,8 @@ 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}.
@@ -61,6 +63,29 @@ interface UseSwapRoutePollingOptions {
     /** 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. */
@@ -317,6 +342,252 @@ declare function SwapUI({ fromToken, toToken, fromBalance, toBalance, amount, am
  */
 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__?: {
@@ -324,6 +595,6 @@ declare global {
         };
     }
 }
-declare const _default: "0.1.2";
+declare const _default: "0.1.3";
 
-export { type SwapInput, type SwapPhase, SwapPreviewModal, type SwapPreviewModalProps, type SwapResult, SwapUI, type SwapUIProps, SwapWidget, type SwapWidgetProps, type TxConfirmationStatus, type UseSwapOptions, type UseSwapRoutePollingOptions, type UseSwapScriptParams, type UseSwapScriptResult, type UseTxConfirmationOptions, useSwap, useSwapRoutePolling, useSwapScript, 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 };