@liberfi.io/ui-trade 0.1.3 → 0.1.5

package/README.md

@@ -6,7 +6,8 @@ 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).
+- **Instant Trade** (`InstantTradeWidget` / `InstantTradeProvider` / `MultiChainPresetFormWidget` / `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).
+- **State atoms** (`presetAtomFamily` / `presetKey`) — Jotai-based persistent state for trade presets, storage-backend agnostic via `atomWithStorage`.
 
 ## Design Philosophy
 
@@ -26,8 +27,10 @@ Peer dependencies the consumer must provide:
 
 - `react` (>=18)
 - `react-dom` (>=18)
+- `jotai` (>=2.15.1) — used for persistent preset state via `atomWithStorage`
 - `@liberfi.io/react` (provides `DexClientProvider` and `useDexClient`)
 - `@liberfi.io/ui` (provides UI components: `Button`, `Input`, `Modal`, `Avatar`, etc.)
+- `@liberfi.io/ui-chain-select` (provides `ChainSelectMobileUI` for `MultiChainPresetFormWidget`)
 - `@liberfi.io/wallet-connector` (provides `WalletAdapter` type)
 
 ## API Reference
@@ -537,21 +540,78 @@ Compact amount input with lightning icon, native token avatar, and 3 preset butt
 
 Trade execution button that reads state from `InstantTradeProvider`. Handles wallet resolution, amount conversion, and swap execution.
 
+#### `MultiChainPresetFormWidget`
+
+Self-contained multi-chain preset editor. Combines chain switching (`ChainSelectMobileUI`), preset index tabs (P1/P2/P3), and a persisted `PresetFormWidget`.
+
+```tsx
+<MultiChainPresetFormWidget
+  chains={[Chain.SOLANA, Chain.ETHEREUM, Chain.BINANCE]}
+  onChange={(chain, idx, value) => console.log(chain, idx, value)}
+/>
+```
+
+**Props (`MultiChainPresetFormWidgetProps`):**
+
+| Name                | Type                                                                    | Description                                          |
+| ------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------- |
+| `chains`            | `Chain[]`                                                               | Available chains to switch between.                  |
+| `defaultChain?`     | `Chain`                                                                 | Initial chain. Defaults to first item in `chains`.   |
+| `storageKeyPrefix?` | `string`                                                                | Storage key prefix. Defaults to `"liberfi."`.        |
+| `onChange?`         | `(chain: Chain, presetIndex: number, value: TradePresetValues) => void` | Notification callback with chain and preset context. |
+| `className?`        | `string`                                                                | External style customization.                        |
+
 #### `PresetFormWidget`
 
-Standalone widget for editing trade preset values (slippage, priority fee, tip fee, auto fee, anti-MEV, custom RPC).
+Atom-backed widget for editing a single trade preset (slippage, priority fee, tip fee, auto fee, anti-MEV, custom RPC). State is persisted via `atomWithStorage` (keyed by prefix + chain + preset index).
+
+For a pure presentational form without persistence, use `PresetFormUI` directly.
 
 ```tsx
 <PresetFormWidget
   chain={Chain.SOLANA}
-  value={presetValues}
-  onChange={setPresetValues}
+  presetIndex={0}
+  storageKeyPrefix="myapp."
+  onChange={(next) => console.log("Preset changed:", next)}
 />
 ```
 
+**Props (`PresetFormWidgetProps`):**
+
+| Name                | Type                                 | Description                                          |
+| ------------------- | ------------------------------------ | ---------------------------------------------------- |
+| `chain`             | `Chain`                              | Target chain — determines default values and fields. |
+| `presetIndex?`      | `number`                             | Preset index (0, 1, or 2). Defaults to 0.            |
+| `storageKeyPrefix?` | `string`                             | Storage key prefix. Defaults to `"liberfi."`.        |
+| `onChange?`         | `(value: TradePresetValues) => void` | Notification callback (does not control state).      |
+| `className?`        | `string`                             | External style customization.                        |
+
 #### `PresetFormUI`
 
-Pure presentational preset form. Accepts value/onChange props directly, with optional `nativeSymbol` and `nativeDecimals`.
+Pure presentational preset form. Accepts value/onChange props directly. No persistence — the caller owns the state.
+
+### State Atoms
+
+#### `presetAtomFamily`
+
+Atom family for trade preset values, persisted via `atomWithStorage`. Each atom is keyed by `"{chain}:{index}"` (use `presetKey` to build the key). Default values are chain-specific.
+
+```typescript
+import { presetAtomFamily, presetKey } from "@liberfi.io/ui-trade";
+
+const atom = presetAtomFamily(presetKey(Chain.SOLANA, 0));
+```
+
+#### `presetKey(chain, index)`
+
+Constructs an atomFamily key string from chain and preset index.
+
+| Name    | Type     | Description                |
+| ------- | -------- | -------------------------- |
+| `chain` | `Chain`  | Target chain.              |
+| `index` | `number` | Preset index (0, 1, or 2). |
+
+**Returns:** `string` — key for use with `presetAtomFamily`.
 
 ### Instant Trade Types
 
@@ -588,7 +648,7 @@ interface SellSettings {
 }
 ```
 
-#### `DEFAULT_TRADE_PRESET`
+#### `DEFAULT_SOL_TRADE_PRESET`
 
 Default preset values: slippage=20, priorityFee=0.001, tipFee=0.001, autoFee=false, maxAutoFee=0.1, antiMev="off".
 
@@ -647,26 +707,37 @@ function TokenHeader({ tokenAddress }: { tokenAddress: string }) {
 }
 ```
 
-### Preset Settings Editor
+### Multi-Chain Preset Settings Editor
 
 ```tsx
-import { useState } from "react";
 import { Chain } from "@liberfi.io/types";
-import { PresetFormWidget, DEFAULT_TRADE_PRESET } from "@liberfi.io/ui-trade";
+import { MultiChainPresetFormWidget } from "@liberfi.io/ui-trade";
 
 function TradeSettings() {
-  const [preset, setPreset] = useState(DEFAULT_TRADE_PRESET);
-
   return (
-    <PresetFormWidget
-      chain={Chain.SOLANA}
-      value={preset}
-      onChange={setPreset}
+    <MultiChainPresetFormWidget
+      chains={[Chain.SOLANA, Chain.ETHEREUM, Chain.BINANCE]}
+      storageKeyPrefix="myapp."
+      onChange={(chain, idx, value) =>
+        console.log(`chain=${chain}, preset=${idx}`, value)
+      }
     />
   );
 }
 ```
 
+### Reading Preset Values from Atoms
+
+```tsx
+import { useAtom } from "jotai";
+import { Chain } from "@liberfi.io/types";
+import { presetAtomFamily, presetKey } from "@liberfi.io/ui-trade";
+
+function useCurrentPreset(chain: Chain, index: number) {
+  return useAtom(presetAtomFamily(presetKey(chain, index)));
+}
+```
+
 ## Future Improvements
 
 - Add `useSwapQuote` hook for fetching quotes without executing (read-only route info).

package/dist/index.d.mts

@@ -4,6 +4,9 @@ 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';
+import * as jotai_family from 'jotai-family';
+import * as jotai from 'jotai';
+import * as jotai_utils from 'jotai/utils';
 
 /**
  * Input parameters for the `swap()` function returned by {@link useSwap}.
@@ -67,23 +70,29 @@ interface UseSwapRoutePollingOptions {
 interface TradePresetValues {
     /** Slippage tolerance, 0-100 (percent). `null` = use default. */
     slippage: number | null;
-    /** Priority fee in native token units. `null` = use default. */
+    /** Priority fee in SOL. `null` = use default. (Solana only) */
     priorityFee: number | null;
-    /** Tip fee in native token units. `null` = use default. */
-    tipFee: number | null;
-    /** Whether automatic fee estimation is enabled. */
+    /** Whether automatic fee estimation is enabled. (Solana only) */
     autoFee: boolean;
-    /** Maximum fee cap when auto-fee is on (native token units). */
+    /** Maximum fee cap when auto-fee is on, in SOL. (Solana only) */
     maxAutoFee: number | null;
+    /** Gas fee in Gwei. `null` = use default. (EVM only) */
+    gasFee: number | null;
+    /** Tip/bribe fee in native token units. `null` = not applicable. (Solana, BSC) */
+    tipFee: 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[];
+declare const DEFAULT_SOL_TRADE_PRESET: TradePresetValues;
+/** Default preset values for EVM chains (gas fee in Gwei). */
+declare const DEFAULT_EVM_TRADE_PRESET: TradePresetValues;
+/** Default preset values for BSC (gas in Gwei + tip in BNB). */
+declare const DEFAULT_BSC_TRADE_PRESET: TradePresetValues;
+/** Returns default quick-buy amounts for the given token symbol. */
+declare function getDefaultBuyAmounts(symbol: string): number[];
 /** Default quick-sell percentages. */
 declare const DEFAULT_SELL_PERCENTAGES: number[];
 /** Confirmation status of a tracked transaction. */
@@ -402,6 +411,7 @@ interface InstantTradeWidgetProps {
 }
 /** Props for {@link InstantTradeUI}. */
 interface InstantTradeUIProps {
+    chain: Chain;
     direction: "buy" | "sell";
     onDirectionChange: (d: "buy" | "sell") => void;
     amount: number | undefined;
@@ -413,8 +423,6 @@ interface InstantTradeUIProps {
     onCustomAmountsEdit: (amounts: (number | null)[]) => void;
     onCustomPercentagesEdit: (pcts: (number | null)[]) => void;
     tokenSymbol?: string;
-    nativeSymbol?: string;
-    nativeDecimals?: number;
     nativeBalance?: string;
     tokenBalance?: string;
     amountConversion?: string;
@@ -485,17 +493,46 @@ interface InstantTradeButtonProps {
 interface PresetFormUIProps {
     value: TradePresetValues;
     onChange: (value: TradePresetValues) => void;
-    nativeSymbol?: string;
-    nativeDecimals?: number;
+    /** Target chain — determines which fields are shown and native token info. */
+    chain: Chain;
+    disableAnimation?: boolean;
     className?: string;
 }
 /** Props for {@link PresetFormWidget}. */
 interface PresetFormWidgetProps {
-    value: TradePresetValues;
-    onChange: (value: TradePresetValues) => void;
+    /** Target chain — determines default values and visible fields. */
+    chain: Chain;
+    /** Preset index (0, 1, or 2). Defaults to 0. */
+    presetIndex?: number;
+    /** Storage key prefix. Defaults to `"liberfi."`. */
+    storageKeyPrefix?: string;
+    /** Notification callback when value changes (does not control state). */
+    onChange?: (direction: "buy" | "sell", value: TradePresetValues) => void;
+    disableAnimation?: boolean;
+    className?: string;
+}
+/** Props for {@link MultiPresetFormWidget}. */
+interface MultiPresetFormWidgetProps {
+    /** Target chain — determines default values and visible fields. */
     chain: Chain;
+    /** Storage key prefix. Defaults to `"liberfi."`. */
+    storageKeyPrefix?: string;
+    /** Notification callback when value changes (does not control state). */
+    onChange?: (presetIndex: number, direction: "buy" | "sell", value: TradePresetValues) => void;
+    disableAnimation?: boolean;
     className?: string;
 }
+/** Params passed when opening the preset-form modal via `useAsyncModal`. */
+interface PresetFormModalParams {
+    /** Available chains to switch between. */
+    chains: Chain[];
+    /** Default chain when no param is passed on open. Defaults to first item in `chains`. */
+    defaultChain?: Chain;
+    /** Storage key prefix. Defaults to `"liberfi."`. */
+    storageKeyPrefix?: string;
+    /** Notification callback when any preset value changes. */
+    onChange?: (chain: Chain, presetIndex: number, direction: "buy" | "sell", value: TradePresetValues) => void;
+}
 
 /** Buy-side trade settings. */
 interface BuySettings {
@@ -549,12 +586,35 @@ declare function useInstantTradeScript(params: UseInstantTradeScriptParams): Use
 declare function InstantTradeWidget({ chain, tokenAddress, onSwapSubmitted, onSwapError, settings, onSettingsChange, headerExtra, className, }: InstantTradeWidgetProps): react_jsx_runtime.JSX.Element;
 
 /**
- * Preset form widget — thin orchestration layer.
+ * Preset form widget — atom-backed orchestration layer with Buy/Sell tabs.
+ *
+ * State is persisted via `atomWithStorage` (keyed by prefix + chain + direction + preset index).
+ * Pass `storageKeyPrefix` to customize the storage key prefix.
+ *
+ * For a pure presentational form without persistence, use {@link PresetFormUI}.
+ */
+declare function PresetFormWidget({ chain, presetIndex, storageKeyPrefix, onChange, disableAnimation, className, }: PresetFormWidgetProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Multi preset form widget.
  *
- * Manages local state initialized from `value`, resolves chain-specific
- * native token info, and syncs changes upward via `onChange`.
+ * Combines preset index tabs,
+ * and a persisted {@link PresetFormWidget} into a single self-contained editor.
  */
-declare function PresetFormWidget({ value, onChange, chain, className, }: PresetFormWidgetProps): react_jsx_runtime.JSX.Element;
+declare function MultiPresetFormWidget({ chain, storageKeyPrefix, onChange, disableAnimation, className, }: MultiPresetFormWidgetProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Async-modal wrapper for multi-chain preset editing.
+ *
+ * Place this component once in the tree (e.g. layout). Open it from anywhere
+ * via `useAsyncModal("preset").onOpen({ params: { chains, defaultChain, storageKeyPrefix, onChange } })`.
+ *
+ * Header: title + chain switcher.
+ * Body:   multi-preset form.
+ */
+declare function PresetFormModal({ id }: {
+    id?: string;
+}): react_jsx_runtime.JSX.Element;
 
 /**
  * Pure presentational component for the instant trade form.
@@ -562,15 +622,20 @@ declare function PresetFormWidget({ value, onChange, chain, className, }: Preset
  * 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;
+declare function InstantTradeUI({ chain, direction, onDirectionChange, amount, onAmountChange, customAmounts, customPercentages, onQuickAmountClick, onQuickPercentageClick, onCustomAmountsEdit, onCustomPercentagesEdit, tokenSymbol, 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.
+ * max auto fee, anti-MEV and custom RPC.
+ *
+ * The `chain` prop controls which fields are visible:
+ * - Solana: priority fee (SOL), tip fee (SOL), anti-MEV
+ * - Ethereum: gas fee (Gwei) only
+ * - BSC: gas fee (Gwei) + tip fee (BNB)
  */
-declare function PresetFormUI({ value, onChange, nativeSymbol, nativeDecimals, className, }: PresetFormUIProps): react_jsx_runtime.JSX.Element;
+declare function PresetFormUI({ value, onChange, chain, disableAnimation, className, }: PresetFormUIProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Compact amount input with preset selector buttons.
@@ -588,6 +653,64 @@ declare function InstantTradeAmountInput({ amount, onAmountChange, preset, onPre
  */
 declare function InstantTradeButton({ className, children, }: InstantTradeButtonProps): react_jsx_runtime.JSX.Element;
 
+type AntiMevOption = "off" | "reduced" | "secure";
+type FeeType = "priorityFee" | "gasFee";
+interface ChainPresetFeatures {
+    /** Native token symbol (e.g. "SOL", "ETH", "BNB") */
+    nativeSymbol: string;
+    /** Semantic fee type — UI maps this to a translated label via i18n key. */
+    feeType: FeeType;
+    /** Unit displayed for the fee input (e.g. "SOL", "Gwei") */
+    feeUnit: string;
+    /** Decimal places for the fee input */
+    feeDecimals: number;
+    /** Whether this chain supports a separate tip/bribe fee */
+    showTipFee: boolean;
+    /** Unit for tip fee (e.g. "SOL", "BNB"). Empty when hidden. */
+    tipFeeUnit: string;
+    /** Decimal places for the tip fee input */
+    tipFeeDecimals: number;
+    /** Whether this chain supports automatic fee estimation */
+    showAutoFee: boolean;
+    /** Whether this chain supports custom RPC endpoint */
+    showCustomRPC: boolean;
+    /**
+     * Available anti-MEV protection levels for this chain.
+     * - Solana: ["off", "reduced", "secure"]
+     * - ETH / BSC: ["off", "secure"]
+     */
+    antiMevOptions: AntiMevOption[];
+}
+/**
+ * Returns the set of preset form features applicable to a given chain.
+ *
+ * - Solana: priority fee (SOL), tip fee (SOL/Jito), anti-MEV
+ * - Ethereum: gas fee (Gwei) only
+ * - BSC: gas fee (Gwei) + tip fee (BNB)
+ * - Other EVM: gas fee (Gwei), same as Ethereum by default
+ */
+declare function getChainPresetFeatures(chain: Chain): ChainPresetFeatures;
+/** Returns chain-appropriate default preset values. */
+declare function getDefaultPresetForChain(chain: Chain): TradePresetValues;
+
+type PresetDirection = "buy" | "sell";
+/**
+ * Construct an atomFamily key from chain, direction, preset index and prefix.
+ *
+ * @param chain     - Target chain.
+ * @param direction - Trade direction: `"buy"` or `"sell"`.
+ * @param index     - Preset index (0, 1, or 2).
+ * @param prefix    - Storage key prefix. Defaults to `"liberfi."`.
+ */
+declare function presetKey(chain: Chain, direction: PresetDirection, index: number, prefix?: string): string;
+/**
+ * Atom family for trade preset values, persisted via `atomWithStorage`.
+ *
+ * Each atom is keyed by a string built with {@link presetKey}.
+ * Default values are chain-specific via `getDefaultPresetForChain`.
+ */
+declare const presetAtomFamily: jotai_family.AtomFamily<string, jotai.WritableAtom<TradePresetValues, [TradePresetValues | typeof jotai_utils.RESET | ((prev: TradePresetValues) => TradePresetValues | typeof jotai_utils.RESET)], void>>;
+
 declare global {
     interface Window {
         __LIBERFI_VERSION__?: {
@@ -595,6 +718,6 @@ declare global {
         };
     }
 }
-declare const _default: "0.1.3";
+declare const _default: "0.1.5";
 
-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 };
+export { type AntiMevOption, type BuySettings, type ChainPresetFeatures, DEFAULT_BSC_TRADE_PRESET, DEFAULT_EVM_TRADE_PRESET, DEFAULT_INSTANT_TRADE_SETTINGS, DEFAULT_SELL_PERCENTAGES, DEFAULT_SOL_TRADE_PRESET, type FeeType, InstantTradeAmountInput, type InstantTradeAmountInputProps, InstantTradeButton, type InstantTradeButtonProps, type InstantTradeContextValue, InstantTradeProvider, type InstantTradeProviderProps, type InstantTradeSettings, InstantTradeUI, type InstantTradeUIProps, InstantTradeWidget, type InstantTradeWidgetProps, MultiPresetFormWidget, type MultiPresetFormWidgetProps, type PresetDirection, PresetFormModal, type PresetFormModalParams, 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, getChainPresetFeatures, getDefaultBuyAmounts, getDefaultPresetForChain, presetAtomFamily, presetKey, useInstantTrade, useInstantTradeScript, useSwap, useSwapRoutePolling, useSwapScript, useTxConfirmation, _default as version };