@deloraprotocol/widget 1.0.1 → 1.0.2

package/README.md

@@ -2,7 +2,7 @@
 
 A React widget component library for crypto trading UI, migrated from delora-exchange (Angular). Includes Trade widget, token selection, network selection, and slippage panel. **Consumers do not need Tailwind** — the library ships compiled CSS.
 
-**Note:** Wallet connection is not implemented. The widget shows placeholder UI for swap actions.
+**Note:** Wallet connection and transaction execution remain host-managed. The widget can request connect, emit quotes, and notify the host when the user clicks `Approve` or `Swap`.
 
 ## Installation
 
@@ -29,7 +29,15 @@ import { TradeWidget } from "@deloraprotocol/widget";
   theme="dark"
   config={{
     apiBase: "https://api.delora.build",
+    isWalletConnected: connected,
+    onConnectWallet: openWalletModal,
   }}
+  initialBuyToken={{ chainId: 1, address: "0x..." }}
+  lockBuyToken
+  onQuote={(quote) => console.log("quote", quote)}
+  onApprove={(payload) => console.log("approve", payload)}
+  onSwap={(payload) => console.log("swap", payload)}
+  onError={(error) => console.error(error)}
 />
 ```
 
@@ -57,12 +65,19 @@ import { MyWidget } from "@deloraprotocol/widget";
 
 ## API
 
-### Exports
-
-- `MyWidget` — the widget component
-- `MyWidgetTheme` — `"light" | "dark"`
-- `MyWidgetVars` — typed object for token overrides
-- `MyWidgetProps` — component props
+### Exports
+
+- `MyWidget` — the widget component
+- `TradeWidget` — trade widget with token/network selection and quote flow
+- `MyWidgetTheme` — `"light" | "dark"`
+- `MyWidgetVars` — typed object for token overrides
+- `MyWidgetProps` — component props
+- `TradeWidgetProps`, `TradeWidgetConfig`
+- `TradeWidgetTokenSelection`
+- `TradeWidgetQuotePayload`
+- `TradeWidgetActionPayload`
+- `TradeWidgetErrorPayload`
+- `Token`, `Network`
 
 ### `MyWidgetProps`
 
@@ -73,7 +88,51 @@ import { MyWidget } from "@deloraprotocol/widget";
 | `className` | `string`       | Applied to root (for host layout/styling)        |
 | `style`  | `React.CSSProperties` | Applied last for advanced overrides         |
 
-Extends `React.HTMLAttributes<HTMLDivElement>` for other div props.
+Extends `React.HTMLAttributes<HTMLDivElement>` for other div props.
+
+### `TradeWidgetProps`
+
+`TradeWidgetProps` extends normal root `div` props except DOM `onError`, which is reserved for the widget error callback below.
+
+| Prop | Type | Description |
+|----------|-------------------|--------------------------------------------------|
+| `config` | `TradeWidgetConfig` | Widget runtime config |
+| `theme` | `"light" \| "dark"` | Built-in theme (default: `"dark"`) |
+| `vars` | `Partial<MyWidgetVars>` | Override theme tokens via CSS variables |
+| `initialSellToken` | `{ chainId: number; address: string }` | Preselect sell token |
+| `initialBuyToken` | `{ chainId: number; address: string }` | Preselect buy token |
+| `initialSellNetworkId` | `number` | Preselect sell network |
+| `initialBuyNetworkId` | `number` | Preselect buy network |
+| `lockSellToken` | `boolean` | Prevent changing sell token |
+| `lockBuyToken` | `boolean` | Prevent changing buy token |
+| `lockSellNetwork` | `boolean` | Prevent changing sell network |
+| `lockBuyNetwork` | `boolean` | Prevent changing buy network |
+| `onQuote` | `(payload) => void` | Called when a new quote is resolved |
+| `onApprove` | `(payload) => void` | Called when the user presses `Approve` |
+| `onSwap` | `(payload) => void` | Called when the user presses `Swap` |
+| `onError` | `(payload) => void` | Called for metadata, selection, and quote errors |
+
+### `TradeWidgetConfig`
+
+| Prop | Type | Description |
+|----------|-------------------|--------------------------------------------------|
+| `apiBase` | `string` | Delora API base for `/v1/chains`, `/v1/tokens`, `/v1/quotes` |
+| `assetBaseUrl` | `string` | Optional base for resolving relative image URLs |
+| `dataBaseUrl` | `string` | Legacy image-base fallback |
+| `isWalletConnected` | `boolean` | Controls the main action button state |
+| `onConnectWallet` | `() => void` | Called when the user clicks `Connect Wallet` |
+
+### Callback payloads
+
+- `onQuote(payload)` returns selected sell/buy network, selected sell/buy token, current sell/buy amounts, slippage, and the raw Delora `quote`.
+- `onApprove(payload)` and `onSwap(payload)` return the current selection plus `quote`, `txData`, `price`, and `gasCostUSD`.
+- `onError(payload)` returns `{ source, message, status?, statusCode?, error? }`, where `source` is one of `metadata`, `selection`, or `quote`.
+
+### Locking behavior
+
+- `lockBuyToken` / `lockSellToken` disable token picking and also freeze the related network, because the token already implies a chain.
+- `lockBuyNetwork` / `lockSellNetwork` disable network changes but keep token selection available within the locked chain.
+- Any lock also disables the center "swap sides" button to avoid silently breaking host-provided constraints.
 
 ## Why no Tailwind required in host
 

package/dist/index.d.ts

@@ -49,6 +49,34 @@ export declare interface Network {
     nativeCurrency: INativeCurrency;
 }
 
+declare interface QuoteResponse {
+    calldata?: {
+        to?: string;
+        data?: string;
+        value?: string;
+    };
+    gas?: {
+        gasPrice?: string;
+        gasLimit?: string;
+        maxFeePerGas?: string;
+        maxPriorityFeePerGas?: string;
+    };
+    inputAmount?: string;
+    outputAmount?: string;
+    fees?: {
+        total?: {
+            amount: string;
+            decimals?: number;
+        };
+        breakdown?: Array<{
+            type: string;
+            amount: string;
+            gasPrice?: string;
+        }>;
+    };
+    [key: string]: unknown;
+}
+
 export declare interface Token {
     symbol: string;
     imageUrl: string;
@@ -61,6 +89,21 @@ export declare interface Token {
 
 export declare function TradeWidget(props: TradeWidgetProps): JSX.Element;
 
+export declare interface TradeWidgetActionPayload {
+    action: "approve" | "swap";
+    sellNetwork: Network;
+    buyNetwork: Network;
+    sellToken: Token;
+    buyToken: Token;
+    sellAmount: string;
+    buyAmount: string;
+    slippage: number;
+    quote: QuoteResponse | null;
+    txData: QuoteResponse["calldata"] | null;
+    price: number;
+    gasCostUSD: string | null;
+}
+
 export declare interface TradeWidgetConfig {
     /** Legacy asset base or custom relative-image base. Metadata is loaded from apiBase/v1/... */
     dataBaseUrl?: string;
@@ -74,8 +117,44 @@ export declare interface TradeWidgetConfig {
     onConnectWallet?: () => void;
 }
 
-export declare interface TradeWidgetProps extends MyWidgetProps {
+export declare interface TradeWidgetErrorPayload {
+    source: "metadata" | "quote" | "selection";
+    message: string;
+    status?: number;
+    statusCode?: number;
+    error?: unknown;
+}
+
+export declare interface TradeWidgetProps extends Omit<MyWidgetProps, "onError"> {
     config: TradeWidgetConfig;
+    initialSellToken?: TradeWidgetTokenSelection;
+    initialBuyToken?: TradeWidgetTokenSelection;
+    initialSellNetworkId?: number;
+    initialBuyNetworkId?: number;
+    lockBuyToken?: boolean;
+    lockSellToken?: boolean;
+    lockBuyNetwork?: boolean;
+    lockSellNetwork?: boolean;
+    onApprove?: (payload: TradeWidgetActionPayload) => void;
+    onSwap?: (payload: TradeWidgetActionPayload) => void;
+    onQuote?: (payload: TradeWidgetQuotePayload) => void;
+    onError?: (payload: TradeWidgetErrorPayload) => void;
+}
+
+export declare interface TradeWidgetQuotePayload {
+    sellNetwork: Network;
+    buyNetwork: Network;
+    sellToken: Token;
+    buyToken: Token;
+    sellAmount: string;
+    buyAmount: string;
+    slippage: number;
+    quote: QuoteResponse;
+}
+
+export declare interface TradeWidgetTokenSelection {
+    chainId: number;
+    address: string;
 }
 
 export { }