@deloraprotocol/widget 1.0.6 → 1.0.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +96 -96
  2. package/dist/index.js +8237 -8192
  3. package/dist/index.js.map +1 -1
  4. package/dist/styles.css +1 -1
  5. package/package.json +1 -1
package/README.md CHANGED
@@ -1,13 +1,13 @@
1
- # @deloraprotocol/widget
1
+ # @deloraprotocol/widget
2
2
 
3
3
  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.
4
4
 
5
- **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`.
5
+ **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`.
6
6
 
7
7
  ## Installation
8
8
 
9
9
  ```bash
10
- npm install @deloraprotocol/widget react react-dom
10
+ npm install @deloraprotocol/widget react react-dom
11
11
  ```
12
12
 
13
13
  ## Import styles
@@ -15,47 +15,47 @@ npm install @deloraprotocol/widget react react-dom
15
15
  You must import the library CSS once in your app (e.g. in your root entry file):
16
16
 
17
17
  ```ts
18
- import "@deloraprotocol/widget/styles.css";
18
+ import "@deloraprotocol/widget/styles.css";
19
19
  ```
20
20
 
21
21
  ## Usage
22
22
 
23
- ### Trade Widget
24
-
25
- ```tsx
26
- import { TradeWidget } from "@deloraprotocol/widget";
27
-
28
- <TradeWidget
29
- theme="dark"
30
- config={{
31
- apiBase: "https://api.delora.build",
32
- isWalletConnected: connected,
33
- onConnectWallet: openWalletModal,
34
- }}
35
- initialBuyToken={{ chainId: 1, address: "0x..." }}
36
- lockBuyToken
37
- onQuote={(quote) => console.log("quote", quote)}
38
- onApprove={(payload) => console.log("approve", payload)}
39
- onSwap={(payload) => console.log("swap", payload)}
40
- onError={(error) => console.error(error)}
41
- />
42
- ```
43
-
44
- `apiBase` is used for:
45
- - `/v1/chains`
46
- - `/v1/tokens`
47
- - `/v1/quotes`
48
-
49
- If omitted, the widget defaults to `https://api.delora.build`.
50
-
51
- `dataBaseUrl` is no longer required for metadata fetching. Keep it only if you need
52
- to resolve relative image URLs from a custom source. For explicit control over image
53
- resolution, pass `assetBaseUrl`.
23
+ ### Trade Widget
24
+
25
+ ```tsx
26
+ import { TradeWidget } from "@deloraprotocol/widget";
27
+
28
+ <TradeWidget
29
+ theme="dark"
30
+ config={{
31
+ apiBase: "https://api.delora.build",
32
+ isWalletConnected: connected,
33
+ onConnectWallet: openWalletModal,
34
+ }}
35
+ initialBuyToken={{ chainId: 1, address: "0x..." }}
36
+ lockBuyToken
37
+ onQuote={(quote) => console.log("quote", quote)}
38
+ onApprove={(payload) => console.log("approve", payload)}
39
+ onSwap={(payload) => console.log("swap", payload)}
40
+ onError={(error) => console.error(error)}
41
+ />
42
+ ```
43
+
44
+ `apiBase` is used for:
45
+ - `/v1/chains`
46
+ - `/v1/tokens`
47
+ - `/v1/quotes`
48
+
49
+ If omitted, the widget defaults to `https://api.delora.build`.
50
+
51
+ `dataBaseUrl` is no longer required for metadata fetching. Keep it only if you need
52
+ to resolve relative image URLs from a custom source. For explicit control over image
53
+ resolution, pass `assetBaseUrl`.
54
54
 
55
55
  ### Simple Widget (MyWidget)
56
56
 
57
57
  ```tsx
58
- import { MyWidget } from "@deloraprotocol/widget";
58
+ import { MyWidget } from "@deloraprotocol/widget";
59
59
 
60
60
  <MyWidget theme="light" />
61
61
  <MyWidget theme="dark" />
@@ -65,19 +65,19 @@ import { MyWidget } from "@deloraprotocol/widget";
65
65
 
66
66
  ## API
67
67
 
68
- ### Exports
69
-
70
- - `MyWidget` — the widget component
71
- - `TradeWidget` — trade widget with token/network selection and quote flow
72
- - `MyWidgetTheme` — `"light" | "dark"`
73
- - `MyWidgetVars` — typed object for token overrides
74
- - `MyWidgetProps` — component props
75
- - `TradeWidgetProps`, `TradeWidgetConfig`
76
- - `TradeWidgetTokenSelection`
77
- - `TradeWidgetQuotePayload`
78
- - `TradeWidgetActionPayload`
79
- - `TradeWidgetErrorPayload`
80
- - `Token`, `Network`
68
+ ### Exports
69
+
70
+ - `MyWidget` — the widget component
71
+ - `TradeWidget` — trade widget with token/network selection and quote flow
72
+ - `MyWidgetTheme` — `"light" | "dark"`
73
+ - `MyWidgetVars` — typed object for token overrides
74
+ - `MyWidgetProps` — component props
75
+ - `TradeWidgetProps`, `TradeWidgetConfig`
76
+ - `TradeWidgetTokenSelection`
77
+ - `TradeWidgetQuotePayload`
78
+ - `TradeWidgetActionPayload`
79
+ - `TradeWidgetErrorPayload`
80
+ - `Token`, `Network`
81
81
 
82
82
  ### `MyWidgetProps`
83
83
 
@@ -88,51 +88,51 @@ import { MyWidget } from "@deloraprotocol/widget";
88
88
  | `className` | `string` | Applied to root (for host layout/styling) |
89
89
  | `style` | `React.CSSProperties` | Applied last for advanced overrides |
90
90
 
91
- Extends `React.HTMLAttributes<HTMLDivElement>` for other div props.
92
-
93
- ### `TradeWidgetProps`
94
-
95
- `TradeWidgetProps` extends normal root `div` props except DOM `onError`, which is reserved for the widget error callback below.
96
-
97
- | Prop | Type | Description |
98
- |----------|-------------------|--------------------------------------------------|
99
- | `config` | `TradeWidgetConfig` | Widget runtime config |
100
- | `theme` | `"light" \| "dark"` | Built-in theme (default: `"dark"`) |
101
- | `vars` | `Partial<MyWidgetVars>` | Override theme tokens via CSS variables |
102
- | `initialSellToken` | `{ chainId: number; address: string }` | Preselect sell token |
103
- | `initialBuyToken` | `{ chainId: number; address: string }` | Preselect buy token |
104
- | `initialSellNetworkId` | `number` | Preselect sell network |
105
- | `initialBuyNetworkId` | `number` | Preselect buy network |
106
- | `lockSellToken` | `boolean` | Prevent changing sell token |
107
- | `lockBuyToken` | `boolean` | Prevent changing buy token |
108
- | `lockSellNetwork` | `boolean` | Prevent changing sell network |
109
- | `lockBuyNetwork` | `boolean` | Prevent changing buy network |
110
- | `onQuote` | `(payload) => void` | Called when a new quote is resolved |
111
- | `onApprove` | `(payload) => void` | Called when the user presses `Approve` |
112
- | `onSwap` | `(payload) => void` | Called when the user presses `Swap` |
113
- | `onError` | `(payload) => void` | Called for metadata, selection, and quote errors |
114
-
115
- ### `TradeWidgetConfig`
116
-
117
- | Prop | Type | Description |
118
- |----------|-------------------|--------------------------------------------------|
119
- | `apiBase` | `string` | Delora API base for `/v1/chains`, `/v1/tokens`, `/v1/quotes` |
120
- | `assetBaseUrl` | `string` | Optional base for resolving relative image URLs |
121
- | `dataBaseUrl` | `string` | Legacy image-base fallback |
122
- | `isWalletConnected` | `boolean` | Controls the main action button state |
123
- | `onConnectWallet` | `() => void` | Called when the user clicks `Connect Wallet` |
124
-
125
- ### Callback payloads
126
-
127
- - `onQuote(payload)` returns selected sell/buy network, selected sell/buy token, current sell/buy amounts, slippage, and the raw Delora `quote`.
128
- - `onApprove(payload)` and `onSwap(payload)` return the current selection plus `quote`, `txData`, `price`, and `gasCostUSD`.
129
- - `onError(payload)` returns `{ source, message, status?, statusCode?, error? }`, where `source` is one of `metadata`, `selection`, or `quote`.
130
-
131
- ### Locking behavior
132
-
133
- - `lockBuyToken` / `lockSellToken` disable token picking and also freeze the related network, because the token already implies a chain.
134
- - `lockBuyNetwork` / `lockSellNetwork` disable network changes but keep token selection available within the locked chain.
135
- - Any lock also disables the center "swap sides" button to avoid silently breaking host-provided constraints.
91
+ Extends `React.HTMLAttributes<HTMLDivElement>` for other div props.
92
+
93
+ ### `TradeWidgetProps`
94
+
95
+ `TradeWidgetProps` extends normal root `div` props except DOM `onError`, which is reserved for the widget error callback below.
96
+
97
+ | Prop | Type | Description |
98
+ |----------|-------------------|--------------------------------------------------|
99
+ | `config` | `TradeWidgetConfig` | Widget runtime config |
100
+ | `theme` | `"light" \| "dark"` | Built-in theme (default: `"dark"`) |
101
+ | `vars` | `Partial<MyWidgetVars>` | Override theme tokens via CSS variables |
102
+ | `initialSellToken` | `{ chainId: number; address: string }` | Preselect sell token |
103
+ | `initialBuyToken` | `{ chainId: number; address: string }` | Preselect buy token |
104
+ | `initialSellNetworkId` | `number` | Preselect sell network |
105
+ | `initialBuyNetworkId` | `number` | Preselect buy network |
106
+ | `lockSellToken` | `boolean` | Prevent changing sell token |
107
+ | `lockBuyToken` | `boolean` | Prevent changing buy token |
108
+ | `lockSellNetwork` | `boolean` | Prevent changing sell network |
109
+ | `lockBuyNetwork` | `boolean` | Prevent changing buy network |
110
+ | `onQuote` | `(payload) => void` | Called when a new quote is resolved |
111
+ | `onApprove` | `(payload) => void` | Called when the user presses `Approve` |
112
+ | `onSwap` | `(payload) => void` | Called when the user presses `Swap` |
113
+ | `onError` | `(payload) => void` | Called for metadata, selection, and quote errors |
114
+
115
+ ### `TradeWidgetConfig`
116
+
117
+ | Prop | Type | Description |
118
+ |----------|-------------------|--------------------------------------------------|
119
+ | `apiBase` | `string` | Delora API base for `/v1/chains`, `/v1/tokens`, `/v1/quotes` |
120
+ | `assetBaseUrl` | `string` | Optional base for resolving relative image URLs |
121
+ | `dataBaseUrl` | `string` | Legacy image-base fallback |
122
+ | `isWalletConnected` | `boolean` | Controls the main action button state |
123
+ | `onConnectWallet` | `() => void` | Called when the user clicks `Connect Wallet` |
124
+
125
+ ### Callback payloads
126
+
127
+ - `onQuote(payload)` returns selected sell/buy network, selected sell/buy token, current sell/buy amounts, slippage, and the raw Delora `quote`.
128
+ - `onApprove(payload)` and `onSwap(payload)` return the current selection plus `quote`, `txData`, `price`, and `gasCostUSD`.
129
+ - `onError(payload)` returns `{ source, message, status?, statusCode?, error? }`, where `source` is one of `metadata`, `selection`, or `quote`.
130
+
131
+ ### Locking behavior
132
+
133
+ - `lockBuyToken` / `lockSellToken` disable token picking and also freeze the related network, because the token already implies a chain.
134
+ - `lockBuyNetwork` / `lockSellNetwork` disable network changes but keep token selection available within the locked chain.
135
+ - Any lock also disables the center "swap sides" button to avoid silently breaking host-provided constraints.
136
136
 
137
137
  ## Why no Tailwind required in host
138
138
 
@@ -166,7 +166,7 @@ Outputs:
166
166
  ### Prerequisites
167
167
 
168
168
  - [npm account](https://www.npmjs.com/signup)
169
- - For scoped packages like `@deloraprotocol/widget`: create the org at [npmjs.com/org/create](https://www.npmjs.com/org/create) (or change the scope in `package.json` to your username)
169
+ - For scoped packages like `@deloraprotocol/widget`: create the org at [npmjs.com/org/create](https://www.npmjs.com/org/create) (or change the scope in `package.json` to your username)
170
170
 
171
171
  ### First-time publish
172
172
 
@@ -223,7 +223,7 @@ cd playground && npm install
223
223
  npm run playground:dev
224
224
  ```
225
225
 
226
- This runs the library watcher and the playground dev server together. The playground uses the built output from `dist/`.
226
+ This runs the library watcher and the playground dev server together. The playground uses the built output from `dist/`.
227
227
 
228
228
  **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.
229
229