@liberfi.io/ui-trade 0.1.1 → 0.1.3

package/README.md

@@ -1,13 +1,20 @@
 # @liberfi.io/ui-trade
 
-Trade hooks for the Liberfi React SDK. This package provides chain-agnostic swap logic that works across Solana, Ethereum, and BSC. It is a pure-logic layer — no UI components, no toasts, no i18n — leaving side-effect control entirely to the consumer.
+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 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
 
-- **IoC (Inversion of Control)** — Side-effects (toast, analytics, navigation) are injected via `onSubmitted` / `onError` callbacks. The hook never hardcodes any feedback mechanism.
+- **IoC (Inversion of Control)** — Side-effects (toast, analytics, navigation) are injected via callbacks. Hooks never hardcode any feedback mechanism.
+- **Script/Widget/UI architecture** — The swap form follows the monorepo's three-layer pattern: `useSwapScript` (data + state), `SwapWidget` (orchestration), `SwapUI` (presentation). Consumers can use the widget directly or compose Script + custom UI.
 - **Chain-agnostic** — Works across Solana (Jupiter) and EVM chains (KyberSwap). Chain-specific differences (dex selection, tx format) are handled by the underlying `@liberfi.io/client` and `WalletAdapter` abstractions.
-- **Wallet-flexible** — The `WalletAdapter` is passed per-call, not coupled to a specific wallet provider or context.
-- **Layered architecture** — Builds on `@liberfi.io/react` (data layer) and `@liberfi.io/wallet-connector` (signing layer) without duplicating their logic.
+- **UI via `@liberfi.io/ui`** — Uses the shared UI library (`Button`, `Input`, `Avatar`, `Modal`, etc.) for consistent styling across the monorepo. No direct `@heroui/react` dependency.
+- **Layered architecture** — Builds on `@liberfi.io/react` (data layer), `@liberfi.io/wallet-connector` (signing layer), and `@liberfi.io/ui` (presentation layer) without duplicating their logic.
 
 ## Installation
 
@@ -20,6 +27,7 @@ Peer dependencies the consumer must provide:
 - `react` (>=18)
 - `react-dom` (>=18)
 - `@liberfi.io/react` (provides `DexClientProvider` and `useDexClient`)
+- `@liberfi.io/ui` (provides UI components: `Button`, `Input`, `Modal`, `Avatar`, etc.)
 - `@liberfi.io/wallet-connector` (provides `WalletAdapter` type)
 
 ## API Reference
@@ -44,6 +52,27 @@ Orchestrates the full swap flow: **route -> sign -> send**.
 | `swap`       | `(input: SwapInput) => Promise<SwapResult>` | Executes the swap. Resolves with `SwapResult` on success, throws on failure. |
 | `isSwapping` | `boolean`                                   | Whether a swap is currently in progress.                                     |
 
+#### `useSwapRoutePolling(params, options?)`
+
+Polls for swap route quotes at a configurable interval. Built on `useSwapRouteQuery` (TanStack Query).
+
+**Parameters:**
+
+| Name               | Type                      | Description                                                            |
+| ------------------ | ------------------------- | ---------------------------------------------------------------------- |
+| `params`           | `Partial<API.SwapParams>` | Route parameters. Polling starts when all required fields are present. |
+| `options.interval` | `number`                  | Polling interval in ms. Defaults to 12000.                             |
+| `options.paused`   | `boolean`                 | Pause polling (e.g. during swap execution).                            |
+| `options.onError`  | `(error: Error) => void`  | Called when a route fetch fails.                                       |
+
+**Returns:** `{ route, isRouting, error }`
+
+| Name        | Type                         | Description                       |
+| ----------- | ---------------------------- | --------------------------------- |
+| `route`     | `API.SwapRoute \| undefined` | Current route quote.              |
+| `isRouting` | `boolean`                    | Whether a route is being fetched. |
+| `error`     | `Error \| null`              | Latest route fetch error.         |
+
 #### `useTxConfirmation(options?: UseTxConfirmationOptions)`
 
 Tracks transaction confirmation via backend SSE. Designed to compose with `useSwap`.
@@ -65,6 +94,126 @@ Tracks transaction confirmation via backend SSE. Designed to compose with `useSw
 | `clearAll`     | `() => void`                             | Remove all tracked transactions.                    |
 | `transactions` | `Map<string, TrackedTx>`                 | All tracked transactions with their current status. |
 
+### Components (Swap Widget)
+
+The swap widget follows the **Script / Widget / UI** three-layer architecture.
+
+#### `SwapWidget`
+
+Plug-and-play swap form. Calls `useSwapScript` internally and renders `SwapUI` with `SwapPreviewModal`. Clicking the swap button opens a preview modal; confirming in the modal executes the swap.
+
+```tsx
+<SwapWidget
+  chain={Chain.SOLANA}
+  from="So11111111111111111111111111111111111111112"
+  to="EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
+  onComplete={(result) => console.log(result)}
+  className="my-swap"
+/>
+```
+
+**Props (`SwapWidgetProps`):**
+
+| Name          | Type                                                      | Description                   |
+| ------------- | --------------------------------------------------------- | ----------------------------- |
+| `chain`       | `Chain`                                                   | Target chain.                 |
+| `from?`       | `string`                                                  | Initial from-token address.   |
+| `to?`         | `string`                                                  | Initial to-token address.     |
+| `onComplete?` | `(result: { success: boolean; txHash?: string }) => void` | Called when swap completes.   |
+| `className?`  | `string`                                                  | External style customization. |
+
+#### `useSwapScript(params: UseSwapScriptParams)`
+
+Script layer hook. Encapsulates all data fetching, state management, and swap execution. No JSX, no UI imports. Use this to build a custom swap UI.
+
+**Parameters (`UseSwapScriptParams`):**
+
+| Name          | Type                                                      | Description                 |
+| ------------- | --------------------------------------------------------- | --------------------------- |
+| `chain`       | `Chain`                                                   | Target chain.               |
+| `from?`       | `string`                                                  | Initial from-token address. |
+| `to?`         | `string`                                                  | Initial to-token address.   |
+| `onComplete?` | `(result: { success: boolean; txHash?: string }) => void` | Called when swap completes. |
+
+**Returns (`UseSwapScriptResult`):**
+
+| Name                  | Type                               | Description                                  |
+| --------------------- | ---------------------------------- | -------------------------------------------- |
+| `fromTokenAddress`    | `string`                           | Currently selected from-token address.       |
+| `toTokenAddress`      | `string`                           | Currently selected to-token address.         |
+| `setFromTokenAddress` | `(addr: string) => void`           | Update from-token address.                   |
+| `setToTokenAddress`   | `(addr: string) => void`           | Update to-token address.                     |
+| `fromToken`           | `Token \| null`                    | From-token metadata.                         |
+| `toToken`             | `Token \| null`                    | To-token metadata.                           |
+| `fromBalance`         | `Portfolio \| null`                | User's from-token balance.                   |
+| `toBalance`           | `Portfolio \| null`                | User's to-token balance.                     |
+| `amount`              | `string \| undefined`              | Human-readable amount.                       |
+| `setAmount`           | `(v: string \| undefined) => void` | Update amount.                               |
+| `setHalfAmount`       | `() => void`                       | Set amount to half of from-token balance.    |
+| `setMaxAmount`        | `() => void`                       | Set amount to full from-token balance.       |
+| `amountInDecimals`    | `string \| undefined`              | Amount in smallest unit.                     |
+| `amountInUsd`         | `string \| undefined`              | Amount in USD.                               |
+| `outputAmount`        | `string \| undefined`              | Formatted output amount from route.          |
+| `outputAmountInUsd`   | `string \| undefined`              | Output amount in USD.                        |
+| `route`               | `API.SwapRoute \| undefined`       | Current route quote.                         |
+| `isRouting`           | `boolean`                          | Whether a route is being fetched.            |
+| `routeError`          | `Error \| null`                    | Route fetch error.                           |
+| `swap`                | `() => Promise<void>`              | Execute the swap.                            |
+| `isSwapping`          | `boolean`                          | Whether a swap is in progress.               |
+| `txStatus`            | `TxConfirmationStatus`             | Confirmation status of the last transaction. |
+| `isLoading`           | `boolean`                          | Whether initial data is loading.             |
+
+#### `SwapUI`
+
+Pure presentational component for the swap form. Renders the From/To token inputs with token selector buttons, balance display, Half/Max shortcuts, and a preview button. Styled with `@liberfi.io/ui` components and Tailwind CSS.
+
+**Props (`SwapUIProps`):**
+
+| Name                | Type                               | Description                       |
+| ------------------- | ---------------------------------- | --------------------------------- |
+| `fromToken`         | `Token \| null`                    | From-token metadata.              |
+| `toToken`           | `Token \| null`                    | To-token metadata.                |
+| `fromBalance`       | `Portfolio \| null`                | User's from-token balance.        |
+| `toBalance`         | `Portfolio \| null`                | User's to-token balance.          |
+| `amount`            | `string \| undefined`              | Human-readable input amount.      |
+| `amountInUsd`       | `string \| undefined`              | Input amount in USD.              |
+| `onAmountChange`    | `(v: string \| undefined) => void` | Amount change handler.            |
+| `onHalfAmount?`     | `() => void`                       | Half balance shortcut handler.    |
+| `onMaxAmount?`      | `() => void`                       | Max balance shortcut handler.     |
+| `outputAmount`      | `string \| undefined`              | Formatted output amount.          |
+| `outputAmountInUsd` | `string \| undefined`              | Output amount in USD.             |
+| `onFromTokenSelect` | `(addr: string) => void`           | From-token selection handler.     |
+| `onToTokenSelect`   | `(addr: string) => void`           | To-token selection handler.       |
+| `route`             | `API.SwapRoute \| undefined`       | Current swap route quote.         |
+| `isRouting`         | `boolean`                          | Whether a route is being fetched. |
+| `routeError`        | `Error \| null`                    | Route error.                      |
+| `onPreview`         | `() => void`                       | Open preview modal handler.       |
+| `isSwapping`        | `boolean`                          | Whether a swap is in progress.    |
+| `className?`        | `string`                           | External style customization.     |
+
+#### `SwapPreviewModal`
+
+Modal component that previews swap details before confirmation. Shows from/to token cards with amounts, an expandable route plan details section, and a confirm button.
+
+**Props (`SwapPreviewModalProps`):**
+
+| Name                | Type                         | Description                       |
+| ------------------- | ---------------------------- | --------------------------------- |
+| `isOpen`            | `boolean`                    | Whether the modal is open.        |
+| `onOpenChange`      | `(isOpen: boolean) => void`  | Modal open/close handler.         |
+| `fromToken`         | `Token \| null`              | From-token metadata.              |
+| `toToken`           | `Token \| null`              | To-token metadata.                |
+| `fromBalance`       | `Portfolio \| null`          | User's from-token balance.        |
+| `inputAmount`       | `string \| undefined`        | Input amount (human-readable).    |
+| `inputAmountInUsd`  | `string \| undefined`        | Input amount in USD.              |
+| `outputAmount`      | `string \| undefined`        | Output amount (human-readable).   |
+| `outputAmountInUsd` | `string \| undefined`        | Output amount in USD.             |
+| `route`             | `API.SwapRoute \| undefined` | Current swap route.               |
+| `isRouting`         | `boolean`                    | Whether a route is being fetched. |
+| `routeError`        | `Error \| null`              | Route error.                      |
+| `onConfirm`         | `() => void`                 | Confirm swap handler.             |
+| `isSwapping`        | `boolean`                    | Whether a swap is in progress.    |
+
 ### Types
 
 #### `SwapInput`
@@ -128,6 +277,16 @@ interface UseTxConfirmationOptions {
 }
 ```
 
+#### `UseSwapRoutePollingOptions`
+
+```typescript
+interface UseSwapRoutePollingOptions {
+  interval?: number; // default: 12000
+  paused?: boolean;
+  onError?: (error: Error) => void;
+}
+```
+
 ### Constants
 
 #### `version`
@@ -138,7 +297,91 @@ const version: string; // e.g. "0.1.0"
 
 ## Usage Examples
 
-### Swap with Confirmation Tracking
+### SwapWidget (Plug-and-Play)
+
+```tsx
+import { Chain } from "@liberfi.io/types";
+import { SwapWidget } from "@liberfi.io/ui-trade";
+
+function TradePage() {
+  return (
+    <SwapWidget
+      chain={Chain.SOLANA}
+      from="So11111111111111111111111111111111111111112"
+      to="EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
+      onComplete={(result) => {
+        if (result.success) {
+          toast.success(`Swap confirmed: ${result.txHash}`);
+        } else {
+          toast.error("Swap failed");
+        }
+      }}
+    />
+  );
+}
+```
+
+### Custom UI with useSwapScript + SwapPreviewModal
+
+```tsx
+import { Chain } from "@liberfi.io/types";
+import { useDisclosure } from "@liberfi.io/ui";
+import { useSwapScript, SwapUI, SwapPreviewModal } from "@liberfi.io/ui-trade";
+
+function MyCustomSwapForm() {
+  const script = useSwapScript({
+    chain: Chain.SOLANA,
+    from: "So11111111111111111111111111111111111111112",
+    to: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+    onComplete: (result) => console.log("Done:", result),
+  });
+
+  const { isOpen, onOpen, onOpenChange } = useDisclosure();
+
+  return (
+    <>
+      <SwapUI
+        fromToken={script.fromToken}
+        toToken={script.toToken}
+        fromBalance={script.fromBalance}
+        toBalance={script.toBalance}
+        amount={script.amount}
+        amountInUsd={script.amountInUsd}
+        onAmountChange={script.setAmount}
+        onHalfAmount={script.setHalfAmount}
+        onMaxAmount={script.setMaxAmount}
+        outputAmount={script.outputAmount}
+        outputAmountInUsd={script.outputAmountInUsd}
+        onFromTokenSelect={script.setFromTokenAddress}
+        onToTokenSelect={script.setToTokenAddress}
+        route={script.route}
+        isRouting={script.isRouting}
+        routeError={script.routeError}
+        onPreview={onOpen}
+        isSwapping={script.isSwapping}
+      />
+      <SwapPreviewModal
+        isOpen={isOpen}
+        onOpenChange={onOpenChange}
+        fromToken={script.fromToken}
+        toToken={script.toToken}
+        fromBalance={script.fromBalance}
+        inputAmount={script.amount}
+        inputAmountInUsd={script.amountInUsd}
+        outputAmount={script.outputAmount}
+        outputAmountInUsd={script.outputAmountInUsd}
+        route={script.route}
+        isRouting={script.isRouting}
+        routeError={script.routeError}
+        onConfirm={script.swap}
+        isSwapping={script.isSwapping}
+      />
+    </>
+  );
+}
+```
+
+### Swap with Confirmation Tracking (Low-Level Hooks)
 
 ```tsx
 import { Chain } from "@liberfi.io/types";
@@ -236,8 +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.
+- 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`.