@deloraprotocol/widget 1.0.0 → 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
 
@@ -20,26 +20,37 @@ import "@deloraprotocol/widget/styles.css";
 
 ## Usage
 
-### Trade Widget
-
-```tsx
+### Trade Widget
+
+```tsx
 import { TradeWidget } from "@deloraprotocol/widget";
-
-<TradeWidget
-  theme="dark"
-  config={{
-    dataBaseUrl: "https://your-app.com",  // or "" for same-origin
-    apiBase: "https://api.delora.build",
-  }}
-/>
-```
-
-`dataBaseUrl` must point to a server that hosts:
-- `/data/networks.json`
-- `/data/tokens.json`
-- `/data/tokens_search.json`
-
-Use `""` for same-origin (e.g. when data is in your app's public folder).
+
+<TradeWidget
+  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)}
+/>
+```
+
+`apiBase` is used for:
+- `/v1/chains`
+- `/v1/tokens`
+- `/v1/quotes`
+
+If omitted, the widget defaults to `https://api.delora.build`.
+
+`dataBaseUrl` is no longer required for metadata fetching. Keep it only if you need
+to resolve relative image URLs from a custom source. For explicit control over image
+resolution, pass `assetBaseUrl`.
 
 ### Simple Widget (MyWidget)
 
@@ -54,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`
 
@@ -70,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
 
@@ -161,7 +223,7 @@ cd playground && npm install
 npm run playground:dev
 ```
 
-This runs the library watcher and the playground dev server together. The playground uses the built output from `dist/`.
+This runs the library watcher and the playground dev server together. The playground uses the built output from `dist/`.
 
 **When errors occur or the UI shows stale/broken code:** run `npm run build` separately to rebuild the library, then restart or refresh the playground. The playground does not auto-rebuild the library.
 

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,10 +89,27 @@ 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 {
-    dataBaseUrl: string;
+    /** Legacy asset base or custom relative-image base. Metadata is loaded from apiBase/v1/... */
+    dataBaseUrl?: string;
+    /** Base URL of Delora API used for chains, tokens, and quotes. Defaults to https://api.delora.build */
     apiBase?: string;
-    /** Base URL for resolving relative image paths (e.g. /img/...). Defaults to dataBaseUrl or origin. */
+    /** Base URL for resolving relative image paths (e.g. /img/...). Defaults to dataBaseUrl, apiBase, or origin. */
     assetBaseUrl?: string;
     /** Whether a wallet is connected. When false, the main button shows "Connect Wallet" (Angular: isWalletConnected). */
     isWalletConnected?: boolean;
@@ -72,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 { }