@liberfi.io/ui-trade 0.1.4 → 0.1.6

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` / `instantTradeAmountAtomFamily`) — Jotai-based persistent state for trade presets and amount/preset selection, 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
@@ -511,47 +514,185 @@ Full instant-trade form with buy/sell tabs, amount input, quick buttons, preset
 
 #### `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>
-```
+Context provider for instant trade state. Use with `InstantTradeButton` for compact inline trading.
 
 #### `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`.
+#### `AmountPresetInputUI`
+
+Pure presentational compact amount input with token icon, lightning icon, and 3 preset buttons (P1/P2/P3) with tooltips. No context dependency — all data is received via props.
+
+**Props (`AmountPresetInputUIProps`):**
+
+| Name              | Type                             | Description                                                         |
+| ----------------- | -------------------------------- | ------------------------------------------------------------------- |
+| `token`           | `PredefinedToken`                | Payment token (provides symbol, decimals, and icon).                |
+| `chain`           | `Chain`                          | Target chain — used by preset tooltips to show chain-specific info. |
+| `amount?`         | `number`                         | Current amount value.                                               |
+| `onAmountChange`  | `(amount?: number) => void`      | Called when the amount changes.                                     |
+| `preset?`         | `number`                         | Currently selected preset index (0–2). Defaults to 0.               |
+| `onPresetChange?` | `(preset: number) => void`       | Called when the user selects a different preset.                    |
+| `onPresetClick?`  | `(preset: number) => void`       | Called when the user clicks the already-selected preset.            |
+| `presetValues?`   | `TradePresetValues[]`            | Preset configurations for tooltip display. Falls back to defaults.  |
+| `size?`           | `"sm" \| "lg"`                   | Controls overall component size. Defaults to `"sm"`.                |
+| `variant?`        | `"default" \| "bordered"`        | Visual variant.                                                     |
+| `radius?`         | `"full" \| "lg" \| "md" \| "sm"` | Border radius.                                                      |
+| `fullWidth?`      | `boolean`                        | Whether the input takes full width.                                 |
+| `className?`      | `string`                         | External style customization.                                       |
+
+#### `AmountPresetInputWidget`
+
+Atom-backed widget that wraps `AmountPresetInputUI` with `atomWithStorage` persistence. Amount and preset selection are persisted per `id + chain + token.address` so different payment tokens and chains have separate saved values.
+
+**Props (`AmountPresetInputWidgetProps`):**
+
+| Name                | Type                             | Description                                                                  |
+| ------------------- | -------------------------------- | ---------------------------------------------------------------------------- |
+| `id`                | `string`                         | Business identifier for storage key (e.g. `"token-detail"`).                 |
+| `chain`             | `Chain`                          | Target chain.                                                                |
+| `token`             | `PredefinedToken`                | Payment token (provides symbol, decimals, address for storage key).          |
+| `storageKeyPrefix?` | `string`                         | Storage key prefix. Must match `PresetFormWidget`. Defaults to `"liberfi."`. |
+| `onAmountChange?`   | `(amount?: number) => void`      | Notification callback (does not control state).                              |
+| `onPresetChange?`   | `(preset: number) => void`       | Notification callback (does not control state).                              |
+| `onPresetClick?`    | `(preset: number) => void`       | Called when the user clicks the already-selected preset.                     |
+| `size?`             | `"sm" \| "lg"`                   | Controls overall component size. Defaults to `"sm"`.                         |
+| `variant?`          | `"default" \| "bordered"`        | Visual variant.                                                              |
+| `radius?`           | `"full" \| "lg" \| "md" \| "sm"` | Border radius.                                                               |
+| `fullWidth?`        | `boolean`                        | Whether the input takes full width.                                          |
+| `className?`        | `string`                         | External style customization.                                                |
 
 #### `InstantTradeButton`
 
 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.
+
+#### `useInstantTradeAmount(params)`
+
+Read-only hook for the persisted instant-trade amount and preset index. Reads from the same `atomWithStorage` atom family that `AmountPresetInputWidget` writes to.
+
+**Parameters (`UseInstantTradeAmountParams`):**
+
+| Name                | Type     | Description                                                                   |
+| ------------------- | -------- | ----------------------------------------------------------------------------- |
+| `id`                | `string` | Business identifier (must match the widget's `id`).                           |
+| `chain`             | `Chain`  | Target chain.                                                                 |
+| `tokenAddress`      | `string` | Payment token address.                                                        |
+| `storageKeyPrefix?` | `string` | Storage key prefix. Must match the widget's prefix. Defaults to `"liberfi."`. |
+
+**Returns:** `AmountPresetState`
+
+| Name     | Type                  | Description             |
+| -------- | --------------------- | ----------------------- |
+| `amount` | `number \| undefined` | Persisted amount value. |
+| `preset` | `number`              | Persisted preset index. |
+
+### 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, "buy", 0));
+```
+
+#### `presetKey(chain, direction, index, prefix?)`
+
+Constructs an atomFamily key string from chain, direction, preset index and optional prefix.
+
+| Name        | Type              | Description                                   |
+| ----------- | ----------------- | --------------------------------------------- |
+| `chain`     | `Chain`           | Target chain.                                 |
+| `direction` | `"buy" \| "sell"` | Trade direction.                              |
+| `index`     | `number`          | Preset index (0, 1, or 2).                    |
+| `prefix?`   | `string`          | Storage key prefix. Defaults to `"liberfi."`. |
+
+**Returns:** `string` — key for use with `presetAtomFamily`.
+
+#### `instantTradeAmountAtomFamily`
+
+Atom family for instant-trade amount and preset index, persisted via `atomWithStorage`. Each atom is keyed by a string built with `instantTradeAmountKey`. The storage key includes `id`, `chain`, and `tokenAddress` so the same token on different chains has separate persisted values.
+
+```typescript
+import {
+  instantTradeAmountAtomFamily,
+  instantTradeAmountKey,
+} from "@liberfi.io/ui-trade";
+
+const atom = instantTradeAmountAtomFamily(
+  instantTradeAmountKey(
+    "token-detail",
+    Chain.SOLANA,
+    "11111111111111111111111111111111",
+  ),
+);
+```
+
+#### `instantTradeAmountKey(id, chain, tokenAddress, prefix?)`
+
+Constructs an atomFamily key string for instant-trade amount + preset state.
+
+| Name           | Type     | Description                                   |
+| -------------- | -------- | --------------------------------------------- |
+| `id`           | `string` | Business identifier.                          |
+| `chain`        | `Chain`  | Target chain.                                 |
+| `tokenAddress` | `string` | Payment token address.                        |
+| `prefix?`      | `string` | Storage key prefix. Defaults to `"liberfi."`. |
+
+**Returns:** `string` — key for use with `instantTradeAmountAtomFamily`.
 
 ### Instant Trade Types
 
@@ -588,7 +729,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".
 
@@ -620,53 +761,100 @@ function TokenTradePage({ tokenAddress }: { tokenAddress: string }) {
 }
 ```
 
-### Compact Inline Trading
+### AmountPresetInputWidget (Persisted Quick-Buy)
 
 ```tsx
 import { Chain } from "@liberfi.io/types";
-import {
-  InstantTradeProvider,
-  InstantTradeAmountInput,
-  InstantTradeButton,
-} from "@liberfi.io/ui-trade";
+import { AmountPresetInputWidget } from "@liberfi.io/ui-trade";
+import { SOLANA_TOKENS } from "@liberfi.io/utils";
 
-function TokenHeader({ tokenAddress }: { tokenAddress: string }) {
+function TokenHeader() {
   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>
+    <AmountPresetInputWidget
+      id="token-detail"
+      chain={Chain.SOLANA}
+      token={SOLANA_TOKENS.native}
+      variant="bordered"
+      size="sm"
+      onPresetClick={(p) => console.log(`Open settings for preset ${p}`)}
+    />
   );
 }
 ```
 
-### Preset Settings Editor
+### AmountPresetInputUI (Controlled)
 
 ```tsx
 import { useState } from "react";
 import { Chain } from "@liberfi.io/types";
-import { PresetFormWidget, DEFAULT_TRADE_PRESET } from "@liberfi.io/ui-trade";
+import { AmountPresetInputUI } from "@liberfi.io/ui-trade";
+import { SOLANA_TOKENS } from "@liberfi.io/utils";
 
-function TradeSettings() {
-  const [preset, setPreset] = useState(DEFAULT_TRADE_PRESET);
+function CustomAmountInput() {
+  const [amount, setAmount] = useState<number | undefined>();
+  const [preset, setPreset] = useState(0);
 
   return (
-    <PresetFormWidget
+    <AmountPresetInputUI
+      token={SOLANA_TOKENS.native}
       chain={Chain.SOLANA}
-      value={preset}
-      onChange={setPreset}
+      amount={amount}
+      onAmountChange={setAmount}
+      preset={preset}
+      onPresetChange={setPreset}
+      variant="bordered"
+      size="lg"
+    />
+  );
+}
+```
+
+### Reading Persisted Amount/Preset
+
+```tsx
+import { Chain } from "@liberfi.io/types";
+import { useInstantTradeAmount } from "@liberfi.io/ui-trade";
+
+function useTokenDetailAmount(tokenAddress: string) {
+  const { amount, preset } = useInstantTradeAmount({
+    id: "token-detail",
+    chain: Chain.SOLANA,
+    tokenAddress,
+  });
+  return { amount, preset };
+}
+```
+
+### Multi-Chain Preset Settings Editor
+
+```tsx
+import { Chain } from "@liberfi.io/types";
+import { MultiChainPresetFormWidget } from "@liberfi.io/ui-trade";
+
+function TradeSettings() {
+  return (
+    <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 { Chain } from "@liberfi.io/types";
+import { usePresetValues } from "@liberfi.io/ui-trade";
+
+function useCurrentPreset(chain: Chain, index: number) {
+  return usePresetValues({ chain, direction: "buy", presetIndex: index });
+}
+```
+
 ## Future Improvements
 
 - Add `useSwapQuote` hook for fetching quotes without executing (read-only route info).