@liberfi.io/ui-trade 0.1.4 → 0.1.6

package/dist/index.d.ts

@@ -1,10 +1,53 @@
 import * as _liberfi_io_types from '@liberfi.io/types';
 import { Chain, API, Token, Portfolio } from '@liberfi.io/types';
+import * as jotai_family from 'jotai-family';
+import * as jotai from 'jotai';
+import * as jotai_utils from 'jotai/utils';
 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';
 
+interface AmountPresetState {
+    amount: number | undefined;
+    preset: number;
+}
+/**
+ * Construct an atomFamily key for instant-trade amount + preset state.
+ *
+ * @param id           - Business identifier (e.g. `"token-detail"`).
+ * @param chain        - Target chain.
+ * @param tokenAddress - Payment token address.
+ * @param prefix       - Storage key prefix. Defaults to `"liberfi."`.
+ */
+declare function instantTradeAmountKey(id: string, chain: Chain, tokenAddress: string, prefix?: string): string;
+/**
+ * Atom family for instant-trade amount and preset index, persisted via `atomWithStorage`.
+ *
+ * Each atom is keyed by a string built with {@link instantTradeAmountKey}.
+ * The storage key includes `id`, `chain`, and `tokenAddress` so the same token
+ * on different chains (e.g. USDC on Solana vs Ethereum) has separate persisted values.
+ */
+declare const instantTradeAmountAtomFamily: jotai_family.AtomFamily<string, jotai.WritableAtom<AmountPresetState, [AmountPresetState | typeof jotai_utils.RESET | ((prev: AmountPresetState) => AmountPresetState | typeof jotai_utils.RESET)], void>>;
+
+interface UseInstantTradeAmountParams {
+    /** Business identifier (e.g. `"token-detail"`). */
+    id: string;
+    /** Target chain. */
+    chain: Chain;
+    /** Payment token address. */
+    tokenAddress: string;
+    /** Storage key prefix. Must match the prefix used by the corresponding AmountPresetInputWidget. Defaults to `"liberfi."`. */
+    storageKeyPrefix?: string;
+}
+/**
+ * Read the persisted instant-trade amount and preset index for a given id / chain / token.
+ *
+ * The value is sourced from the same `atomWithStorage` atom family that
+ * {@link AmountPresetInputWidget} writes to, so it stays in sync automatically.
+ */
+declare function useInstantTradeAmount({ id, chain, tokenAddress, storageKeyPrefix, }: UseInstantTradeAmountParams): AmountPresetState;
+
 /**
  * Input parameters for the `swap()` function returned by {@link useSwap}.
  *
@@ -67,27 +110,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;
+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;
-/** Default quick-buy amounts (native token units). */
-declare const DEFAULT_BUY_AMOUNTS: number[];
+/** 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. */
@@ -102,6 +147,42 @@ interface UseTxConfirmationOptions {
     timeout?: number;
 }
 
+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, [typeof jotai_utils.RESET | TradePresetValues | ((prev: TradePresetValues) => typeof jotai_utils.RESET | TradePresetValues)], void>>;
+
+interface UsePresetValuesParams {
+    /** Target chain. */
+    chain: Chain;
+    /** Trade direction. */
+    direction: PresetDirection;
+    /** Preset index (0, 1, or 2). Defaults to 0. */
+    presetIndex?: number;
+    /** Storage key prefix. Must match the prefix used by the corresponding PresetFormWidget. Defaults to `"liberfi."`. */
+    storageKeyPrefix?: string;
+}
+/**
+ * Read the current {@link TradePresetValues} for a given chain / direction / preset index.
+ *
+ * The value is sourced from the same `atomWithStorage` atom family that
+ * {@link PresetFormWidget} writes to, so it stays in sync automatically.
+ */
+declare function usePresetValues({ chain, direction, presetIndex, storageKeyPrefix, }: UsePresetValuesParams): TradePresetValues;
+
 /**
  * Hook that orchestrates the full swap flow: route -> sign -> send.
  *
@@ -418,8 +499,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;
@@ -467,18 +546,48 @@ interface InstantTradeProviderProps {
     onSettingsChange?: (settings: InstantTradeSettings) => void;
     children: ReactNode;
 }
-/** Props for {@link InstantTradeAmountInput}. */
-interface InstantTradeAmountInputProps {
+/** Props for {@link AmountPresetInputUI}. */
+interface AmountPresetInputUIProps {
+    /** Payment token (provides symbol, decimals, and icon). */
+    token: PredefinedToken;
+    /** Target chain — used by preset tooltips to show chain-specific features. */
+    chain: Chain;
+    /** Current amount value. */
     amount?: number;
+    /** Called when the amount changes. */
     onAmountChange: (amount?: number) => void;
+    /** Currently selected preset index (0, 1, or 2). Defaults to 0. */
     preset?: number;
+    /** Called when the user selects a different preset. */
     onPresetChange?: (preset: number) => void;
-    /** Called when an already-selected preset is clicked (e.g. open settings) */
+    /** Called when the user clicks the already-selected preset (e.g. open settings). */
     onPresetClick?: (preset: number) => void;
-    variant?: "default" | "bordered";
+    /** Preset configurations for tooltip display. Falls back to chain defaults when omitted. */
+    presetValues?: TradePresetValues[];
+    /** Controls overall component size. Defaults to `"sm"`. */
+    size?: "sm" | "md" | "lg";
+    radius?: "full" | "lg" | "md" | "sm" | "none";
+    className?: string;
+}
+/** Props for {@link AmountPresetInputWidget}. */
+interface AmountPresetInputWidgetProps {
+    /** Business identifier used as part of the storage key (e.g. `"token-detail"`, `"watchlist"`). */
+    id: string;
+    /** Target chain. */
+    chain: Chain;
+    /** Payment token (provides symbol, decimals, address for storage key, and icon). */
+    token: PredefinedToken;
+    /** Storage key prefix. Must match the prefix used by the corresponding PresetFormWidget. Defaults to `"liberfi."`. */
+    storageKeyPrefix?: string;
+    /** Notification callback when the amount changes (does not control state). */
+    onAmountChange?: (amount?: number) => void;
+    /** Notification callback when a different preset is selected (does not control state). */
+    onPresetChange?: (preset: number) => void;
+    /** Called when the user clicks the already-selected preset (e.g. open settings). */
+    onPresetClick?: (preset: number) => void;
+    /** Controls overall component size. Defaults to `"sm"`. */
+    size?: "sm" | "md" | "lg";
     radius?: "full" | "lg" | "md" | "sm";
-    size?: "sm" | "lg";
-    fullWidth?: boolean;
     className?: string;
 }
 /** Props for {@link InstantTradeButton}. */
@@ -490,19 +599,46 @@ interface InstantTradeButtonProps {
 interface PresetFormUIProps {
     value: TradePresetValues;
     onChange: (value: TradePresetValues) => void;
-    /** Target chain — determines which fields are shown (e.g. anti-MEV for Solana only). */
+    /** Target chain — determines which fields are shown and native token info. */
     chain: Chain;
-    nativeSymbol?: string;
-    nativeDecimals?: number;
+    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 {
@@ -556,12 +692,46 @@ 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.
+ * Amount + preset input widget — atom-backed orchestration layer.
+ *
+ * Persists `{ amount, preset }` via `atomWithStorage`, keyed by
+ * `id + chain + token.address`. Reads preset values from
+ * {@link presetAtomFamily} for tooltip display.
+ *
+ * For a pure presentational input without persistence, use {@link AmountPresetInputUI}.
+ */
+declare function AmountPresetInputWidget({ id, chain, token, storageKeyPrefix, onAmountChange, onPresetChange, onPresetClick, size, radius, className, }: AmountPresetInputWidgetProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * 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.
@@ -569,7 +739,15 @@ 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({ chain, 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;
+
+/**
+ * Compact amount input with preset selector buttons (presentational).
+ *
+ * Designed for inline/header usage (e.g. token detail page).
+ * Receives all data via props — no context dependency.
+ */
+declare function AmountPresetInputUI({ token, chain, amount, onAmountChange, preset, onPresetChange, onPresetClick, presetValues, radius, size, className, }: AmountPresetInputUIProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Pure presentational preset-settings form.
@@ -582,15 +760,7 @@ declare function InstantTradeUI({ chain, direction, onDirectionChange, amount, o
  * - Ethereum: gas fee (Gwei) only
  * - BSC: gas fee (Gwei) + tip fee (BNB)
  */
-declare function PresetFormUI({ value, onChange, chain, 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;
+declare function PresetFormUI({ value, onChange, chain, disableAnimation, className, }: PresetFormUIProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Trade execution button that reads state from {@link InstantTradeProvider}.
@@ -601,9 +771,12 @@ 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 {
-    /** Label for the priority/gas fee field */
-    feeLabel: string;
+    /** 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 */
@@ -614,6 +787,10 @@ interface ChainPresetFeatures {
     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"]
@@ -629,8 +806,7 @@ interface ChainPresetFeatures {
  * - BSC: gas fee (Gwei) + tip fee (BNB)
  * - Other EVM: gas fee (Gwei), same as Ethereum by default
  */
-declare function getChainPresetFeatures(chain: Chain, nativeSymbol?: string): ChainPresetFeatures;
-declare function isSolanaChain(chain: Chain): boolean;
+declare function getChainPresetFeatures(chain: Chain): ChainPresetFeatures;
 /** Returns chain-appropriate default preset values. */
 declare function getDefaultPresetForChain(chain: Chain): TradePresetValues;
 
@@ -641,6 +817,6 @@ declare global {
         };
     }
 }
-declare const _default: "0.1.4";
+declare const _default: "0.1.6";
 
-export { type AntiMevOption, type BuySettings, type ChainPresetFeatures, DEFAULT_BSC_TRADE_PRESET, DEFAULT_BUY_AMOUNTS, DEFAULT_EVM_TRADE_PRESET, 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, getChainPresetFeatures, getDefaultPresetForChain, isSolanaChain, useInstantTrade, useInstantTradeScript, useSwap, useSwapRoutePolling, useSwapScript, useTxConfirmation, _default as version };
+export { AmountPresetInputUI, type AmountPresetInputUIProps, AmountPresetInputWidget, type AmountPresetInputWidgetProps, type AmountPresetState, 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, 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 UseInstantTradeAmountParams, type UseInstantTradeScriptParams, type UseInstantTradeScriptResult, type UsePresetValuesParams, type UseSwapOptions, type UseSwapRoutePollingOptions, type UseSwapScriptParams, type UseSwapScriptResult, type UseTxConfirmationOptions, getChainPresetFeatures, getDefaultBuyAmounts, getDefaultPresetForChain, instantTradeAmountAtomFamily, instantTradeAmountKey, presetAtomFamily, presetKey, useInstantTrade, useInstantTradeAmount, useInstantTradeScript, usePresetValues, useSwap, useSwapRoutePolling, useSwapScript, useTxConfirmation, _default as version };