@shapeshiftoss/swap-widget 0.7.0 → 0.8.0

package/README.md

@@ -11,6 +11,7 @@ An embeddable React widget that enables multi-chain token swaps using ShapeShift
 - [Wallet Connection](#wallet-connection)
 - [Props Reference](#props-reference)
 - [Filtering Chains and Assets](#filtering-chains-and-assets)
+- [Exact Output and Locked Destinations](#exact-output-and-locked-destinations)
 - [Theming](#theming)
 - [Examples](#examples)
 - [Exported Types](#exported-types)
@@ -139,6 +140,10 @@ when `allowShapeshiftRedirect` is enabled.
 | `allowedSwapperNames`    | `SwapperName[]`                                 | all enabled        | Limit quotes to specific swappers. See [Supported Swappers](#supported-swappers).                        |
 | `allowShapeshiftRedirect`| `boolean`                                       | `true`             | When a swap isn't executable in-widget, redirect to app.shapeshift.com instead of hiding it.             |
 | `isBuyAssetLocked`       | `boolean`                                       | `false`            | Prevent the user from changing the buy asset.                                                            |
+| `defaultBuyAmountCryptoBaseUnit` | `string`                                | –                  | Drive the trade from the buy side: the user receives exactly this amount and the sell amount is derived. Restricts routing to exact-output swappers. See [Exact Output and Locked Destinations](#exact-output-and-locked-destinations). |
+| `isBuyAmountLocked`      | `boolean`                                       | `false`            | Prevent the user from changing the buy amount. When an amount is supplied it also locks the buy asset, since a base-unit amount is meaningless without the asset it counts. |
+| `defaultReceiveAddress`  | `string`                                        | –                  | Prefill the destination address. Falls back to the connected wallet's address for the buy chain when unset. |
+| `isReceiveAddressLocked` | `boolean`                                       | `false`            | Prevent the user from changing the destination address.                                                   |
 | `theme`                  | `ThemeMode \| ThemeConfig`                      | `"dark"`           | Theme mode (`"light"` or `"dark"`) or a full theme configuration object. See [Theming](#theming).        |
 | `defaultSlippage`        | `string`                                        | `"0.5"`            | Default slippage tolerance, as a percentage string.                                                      |
 | `showPoweredBy`          | `boolean`                                       | `true`             | Show the "Powered by ShapeShift" footer.                                                                  |
@@ -183,6 +188,162 @@ function App() {
 }
 ```
 
+## Exact Output and Locked Destinations
+
+By default the user enters what they want to spend. These props invert that, and fix where the funds
+land — letting you configure the widget for one specific swap.
+
+### Fixed receive amount
+
+`defaultBuyAmountCryptoBaseUnit` drives the trade from the buy side. The user still chooses what to
+sell, but the sell amount comes back derived from whichever route they pick.
+
+```tsx
+<SwapWidget
+  walletConnectProjectId="..."
+  defaultBuyAsset={usdcOnBase}
+  defaultBuyAmountCryptoBaseUnit="500000" // 0.5 USDC, in base units
+  isBuyAmountLocked
+/>
+```
+
+Without `isBuyAmountLocked` the amount is only a **prefill**: both fields stay editable, and
+whichever one the user types into becomes the side that drives the trade — the other is then derived
+from the selected route. Adding the lock fixes the buy amount, and makes the sell field read-only,
+since typing there would clear the amount you locked.
+
+Because a base-unit amount only means something alongside the asset it counts, `isBuyAmountLocked`
+locks the buy asset too. Changing an unlocked buy asset keeps the entered amount and recalculates its
+base units at the new precision, matching how the sell side already behaves.
+
+Only swappers that can honour an exact output are routed to — currently **NEAR Intents** and
+**Relay**. The rest report `ExactOutputNotSupported` and are left out of the rate list, so expect
+fewer routes than a normal swap, and none at all for pairs those two don't cover.
+
+Slippage applies to the **sell** side. The amount received is fixed; what varies is what it costs.
+
+### Fixed destination
+
+`defaultReceiveAddress` prefills the destination. Add `isReceiveAddressLocked` to stop the user
+changing it — the locked address then outranks both a user entry and the connected wallet's own
+address.
+
+| Props                        | Behaviour                          |
+| ---------------------------- | ---------------------------------- |
+| `defaultReceiveAddress` only | Prefilled, user can still edit it   |
+| Both                         | Locked to the address you supplied  |
+
+A locked address is checked against the buy asset's chain, and if it doesn't validate there the
+widget says so and blocks the swap rather than falling back to the connected wallet — paying the
+user's own address is never what a locked destination meant. This is reachable whenever the buy
+asset is left unlocked, since the user can switch to a chain the address doesn't belong to.
+
+An **unlocked** prefill is checked the same way but fails quietly: one that doesn't match the buy
+chain is dropped, and the connected wallet's address takes over as if you had passed nothing. Verify
+a prefill against the chain of the buy asset you pair it with.
+
+A lock is only accepted alongside the value it locks — `isReceiveAddressLocked` on its own is a type
+error, as is `isBuyAmountLocked` without `defaultBuyAmountCryptoBaseUnit`. Locking with nothing to
+lock would fall back to the connected wallet's address, which is undefined whenever the wallet
+doesn't cover the buy asset's chain, leaving no address and no way to enter one.
+
+If you build props dynamically, import `ReceiveAddressProps` and `BuyAmountProps` and construct each
+pair together:
+
+```tsx
+const receiveAddressProps: ReceiveAddressProps = address
+  ? { defaultReceiveAddress: address, isReceiveAddressLocked: true }
+  : {}
+
+<SwapWidget {...receiveAddressProps} />
+```
+
+### Payment mode
+
+Locking **both** the buy amount and the address — `defaultBuyAmountCryptoBaseUnit` with
+`isBuyAmountLocked`, plus `defaultReceiveAddress` with `isReceiveAddressLocked` — puts the widget in
+**payment mode**: a set amount, sent to an address you supplied.
+
+```tsx
+<SwapWidget
+  walletConnectProjectId="..."
+  defaultBuyAsset={usdcOnBase}
+  defaultBuyAmountCryptoBaseUnit="500000"
+  isBuyAmountLocked
+  defaultReceiveAddress="0x…"
+  isReceiveAddressLocked
+  onSwapSuccess={txHash => recordPayment(txHash)}
+/>
+```
+
+The success screen is then terminal — no "New Swap" button. Repeating a payment means paying twice,
+so whether there's another swap is your call rather than the widget's; use `onSwapSuccess` to decide
+what happens next.
+
+Locking only **one** of the two stays repeatable, and keeps the button: a set amount sent to the
+user's own wallet, or topping up a locked address again, are both things a user may reasonably do
+twice.
+`isBuyAssetLocked` never affects this — restricting swaps to a given token is just a configuration.
+
+### Redirects are disabled by either lock
+
+The app.shapeshift.com redirect carries neither the destination nor the buy amount, so following it
+would drop whichever constraint you set. Locking the buy amount **or** the receive address
+therefore disables it outright: `allowShapeshiftRedirect` has no effect, and assets on
+non-executable chains drop out of the asset pickers rather than dead-ending. The pickers share that
+filter, so Cosmos-SDK assets go from the **buy** side too, even though a swap into them works — only
+the sell side needs a signature. The remaining redirect-only chains lose nothing: the widget has no
+address validator for them, so they were never usable as a destination.
+
+Note this is a wider condition than payment mode — locking either one is enough, because a single
+dropped constraint can send funds somewhere you didn't intend.
+
+### Configuration is applied at mount
+
+Every `default*` prop is applied a single time, when the widget mounts — the same semantics as
+`defaultValue` on an `<input>`. After that the value belongs to the user, so changing the prop on an
+already mounted widget has no effect, and neither does resolving it asynchronously: if you fetch
+`Asset` objects, hold off rendering until you have them.
+
+**Locked values are the exception.** A locked value is yours rather than the user's, so it tracks its
+prop rather than seeding once — change `defaultBuyAmountCryptoBaseUnit` alongside `isBuyAmountLocked`,
+or `defaultReceiveAddress` alongside `isReceiveAddressLocked`, and the widget follows without a
+remount. Both apply while the user is on the input step. Once they've asked for a quote a change may
+not land at all — that quote carries the amount and address it was built with — so change them
+before the user starts, or remount. `defaultBuyAsset` seeds once even when `isBuyAssetLocked`.
+
+To change anything else, or to start a fresh swap after a payment completes, **remount**.
+If the widget lives in a modal that unmounts its children while closed, that happens for free:
+
+```tsx
+{isOpen && <SwapWidget onSwapSuccess={() => setIsOpen(false)} {...config} />}
+```
+
+Inline — or in a modal that keeps its children mounted — bump a `key` instead:
+
+```tsx
+const [swapSession, setSwapSession] = useState(0)
+
+<SwapWidget
+  key={swapSession}
+  onSwapSuccess={txHash => {
+    recordSwap(txHash)
+    setSwapSession(n => n + 1)
+  }}
+  {...config}
+/>
+```
+
+Remounting is cheap. The AppKit instance and the React Query cache are module-level singletons
+rather than widget state, so the user stays connected and asset and balance data isn't refetched —
+only the swap itself resets.
+
+### Refunds
+
+If a swap can't be completed, the provider returns the funds to the **sending** address — the wallet
+the user swapped from — not to the receive address. A locked destination does not affect where a
+refund goes.
+
 ## Theming
 
 The widget supports a simple light/dark mode or a full theme configuration object.
@@ -303,8 +464,10 @@ end in a specific token.
 import type {
   Asset,
   AssetId,
+  BuyAmountProps,
   Chain,
   ChainId,
+  ReceiveAddressProps,
   SwapWidgetFilters,
   SwapWidgetProps,
   ThemeConfig,
@@ -522,5 +685,12 @@ revenue attribution works.
 - **Balances and USD prices.** When a wallet is connected, the widget shows balances and USD prices
   for the selected assets.
 - **Redirects.** Assets on non-executable chains (Cosmos, Zcash, Tron, Sui, TON, NEAR, Starknet)
-  send the user to app.shapeshift.com to finish the swap, unless `allowShapeshiftRedirect={false}`.
+  send the user to app.shapeshift.com to finish the swap, unless `allowShapeshiftRedirect={false}`
+  or the buy amount or receive address is locked (see
+  [Redirects are disabled by either lock](#redirects-are-disabled-by-either-lock)).
+- **Configuration is applied at mount.** `default*` props are read once; locked values keep
+  tracking their prop. Remount to change anything else, or to start a fresh swap. See
+  [Configuration is applied at mount](#configuration-is-applied-at-mount).
+- **`onSwapSuccess` reports the sell transaction.** The hash it receives is the transaction the user
+  signed on the sell chain. On cross-chain routes the destination transfer may still be in flight.
 - **Mobile responsive.** The widget is designed to work on mobile as well as desktop.

package/dist/index.css

@@ -155,6 +155,22 @@
 .ssw-amount-input::placeholder {
   color: var(--ssw-text-muted);
 }
+.ssw-amount-input-pending::placeholder {
+  animation: ssw-placeholder-pulse 1.4s ease-in-out infinite;
+}
+@keyframes ssw-placeholder-pulse {
+  0%, 100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.3;
+  }
+}
+@media (prefers-reduced-motion: reduce) {
+  .ssw-amount-input-pending::placeholder {
+    animation: none;
+  }
+}
 .ssw-token-btn {
   display: flex;
   align-items: center;
@@ -446,6 +462,9 @@
 .ssw-receive-row.ssw-attention {
   box-shadow: 0 0 16px -2px var(--ssw-accent);
 }
+.ssw-receive-row.ssw-receive-row-invalid {
+  border-color: var(--ssw-error);
+}
 .ssw-quotes {
   padding: 0 16px 16px;
 }

package/dist/index.d.ts

@@ -99,7 +99,21 @@ type SwapWidgetFilters = {
     allowedAssetIds?: AssetId[];
     disabledAssetIds?: AssetId[];
 };
-type SwapWidgetProps = {
+type ReceiveAddressProps = {
+    defaultReceiveAddress: string;
+    isReceiveAddressLocked?: boolean;
+} | {
+    defaultReceiveAddress?: never;
+    isReceiveAddressLocked?: false;
+};
+type BuyAmountProps = {
+    defaultBuyAmountCryptoBaseUnit: string;
+    isBuyAmountLocked?: boolean;
+} | {
+    defaultBuyAmountCryptoBaseUnit?: never;
+    isBuyAmountLocked?: false;
+};
+type SwapWidgetProps = ReceiveAddressProps & BuyAmountProps & {
     partnerCode?: string;
     apiBaseUrl?: string;
     allowShapeshiftRedirect?: boolean;
@@ -192,4 +206,4 @@ declare const useChains: () => AssetQueryResult<ChainInfo[]>;
 declare const useAssetsByChainId: (chainId: ChainId | undefined) => AssetQueryResult<Asset[]>;
 declare const useAssetSearch: (query: string, chainId?: ChainId) => AssetQueryResult<Asset[]>;
 
-export { type Asset, COSMOS_CHAIN_IDS, type Chain, EVM_CHAIN_IDS, OTHER_CHAIN_IDS, REDIRECT_ONLY_CHAIN_IDS, SwapWidget, type SwapWidgetFilters, type SwapWidgetProps, SwapperName, type ThemeConfig, type ThemeMode, type TradeQuote, type TradeRate, UTXO_CHAIN_IDS, formatAmount, getBaseAsset, getChainColor, getChainIcon, getChainName, getChainType, getEvmNetworkId, getExplorerTxLink, isEvmChainId, isWidgetExecutableChainId, isWidgetSupportedChainId, parseAmount, truncateAddress, useAssetById, useAssetSearch, useAssets, useAssetsByChainId, useChains };
+export { type Asset, type BuyAmountProps, COSMOS_CHAIN_IDS, type Chain, EVM_CHAIN_IDS, OTHER_CHAIN_IDS, REDIRECT_ONLY_CHAIN_IDS, type ReceiveAddressProps, SwapWidget, type SwapWidgetFilters, type SwapWidgetProps, SwapperName, type ThemeConfig, type ThemeMode, type TradeQuote, type TradeRate, UTXO_CHAIN_IDS, formatAmount, getBaseAsset, getChainColor, getChainIcon, getChainName, getChainType, getEvmNetworkId, getExplorerTxLink, isEvmChainId, isWidgetExecutableChainId, isWidgetSupportedChainId, parseAmount, truncateAddress, useAssetById, useAssetSearch, useAssets, useAssetsByChainId, useChains };