@pollar/react 0.10.0-rc.8 → 0.10.0

package/README.md

@@ -3,17 +3,19 @@
 React bindings for [Pollar](https://pollar.xyz) — drop-in authentication UI, transaction modals, and hooks for
 Stellar-based applications.
 
-> **0.9.0** requires `@pollar/core@^0.9.0`. `usePollar().walletAddress` is
-> unchanged (now derived from `session.wallet.address` internally — no consumer
-> change), and provider/modal logs route through the client's configured
-> `logLevel` / `logger`. Read the [CHANGELOG](../../CHANGELOG.md) before upgrading.
+> **0.10.0** requires `@pollar/core@^0.10.0`. Headline features: on-chain swaps
+> via `<SwapModal>` + `usePollar().swap` / `getSwapQuote` / `openSwapModal`;
+> live SEP-24 on/off-ramps through `<RampWidget>` (now wired to
+> `client.createOnRamp` / `client.createOffRamp`); and a self-driving Privy
+> adapter (registered interactive adapters are auto-driven to completion before
+> `login({ provider })`). Read the [CHANGELOG](../../CHANGELOG.md) before
+> upgrading.
 >
-> **0.8.0 reshapes `<PollarProvider>` props (breaking).** `config` → `client`
+> **0.8.0 reshapes `<PollarProvider>` props (breaking).** `config` > `client`
 > (now accepts a `PollarClient` instance or a `PollarClientConfig`); `styles`
 > moves under `appConfig.styles`; new `appConfig` prop is the opt-out switch
-> for the remote `/applications/config` fetch (pass it — even `{}` — to skip
-> the fetch); new `ui.renderWallets` slot replaces the default Freighter/Albedo
-> picker. Read the [CHANGELOG](../../CHANGELOG.md) and
+> for the remote `/applications/config` fetch (pass it - even `{}` - to skip
+> the fetch). Read the [CHANGELOG](../../CHANGELOG.md) and
 > [UPGRADE.md](../../UPGRADE.md) before upgrading.
 
 ## Installation
@@ -45,18 +47,18 @@ export default function App({ children }: { children: React.ReactNode }) {
 import { usePollar } from '@pollar/react';
 
 export function Profile() {
-  const { isAuthenticated, walletAddress, login, logout, getClient } = usePollar();
+  const { isAuthenticated, wallet, login, logout, getClient } = usePollar();
 
   if (!isAuthenticated) {
     return <button onClick={() => login({ provider: 'google' })}>Sign in with Google</button>;
   }
 
-  // PII (email, name, avatar, providers) lives in memory only — fetch it from the client.
+  // PII (email, name, avatar, providers) lives in memory only - fetch it from the client.
   const profile = getClient().getUserProfile();
 
   return (
     <div>
-      <p>Wallet: {walletAddress}</p>
+      <p>Wallet: {wallet?.address}</p>
       <p>Email: {profile?.mail}</p>
       <button onClick={logout}>Sign out</button>
     </div>
@@ -89,11 +91,6 @@ Context provider that initialises the Pollar client and makes it available to ch
       /* optional style overrides */
     },
   }}
-  ui={{
-    // Optional: replace the default Freighter/Albedo wallet picker.
-    // See "External wallet stacks" below for a kit-powered example.
-    renderWallets: undefined,
-  }}
   adapters={
     {
       /* optional named adapter set */
@@ -104,12 +101,11 @@ Context provider that initialises the Pollar client and makes it available to ch
 </PollarProvider>
 ```
 
-| Prop        | Type                                    | Required | Description                                                                                                                                                                                              |
-| ----------- | --------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `client`    | `PollarClient \| PollarClientConfig`    | Yes      | Either a pre-built `PollarClient` (testing, reuse outside React) or a `PollarClientConfig` the provider will construct one from. **Locked at first render** — swapping after mount is ignored            |
-| `appConfig` | `PollarConfig`                          | No       | Local override of `/applications/config`. **Presence is the opt-out switch**: pass it (even `{}`) and the remote fetch is skipped. Omit it to keep the existing remote-fetch-on-mount behaviour          |
-| `ui`        | `{ renderWallets?: RenderWalletsSlot }` | No       | UI customisation slots. `renderWallets` replaces the default Freighter/Albedo buttons in `LoginModal`'s wallet picker. Receives `{ onConnect, authState }` and is expected to call `onConnect(walletId)` |
-| `adapters`  | `PollarAdapters`                        | No       | Named set of `PollarAdapter` objects (e.g. Trustless Work). See below                                                                                                                                    |
+| Prop        | Type                                 | Required | Description                                                                                                                                                                                     |
+| ----------- | ------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `client`    | `PollarClient \| PollarClientConfig` | Yes      | Either a pre-built `PollarClient` (testing, reuse outside React) or a `PollarClientConfig` the provider will construct one from. **Locked at first render** — swapping after mount is ignored   |
+| `appConfig` | `PollarConfig`                       | No       | Local override of `/applications/config`. **Presence is the opt-out switch**: pass it (even `{}`) and the remote fetch is skipped. Omit it to keep the existing remote-fetch-on-mount behaviour |
+| `adapters`  | `PollarAdapters`                     | No       | Named set of `PollarAdapter` objects (e.g. Trustless Work). See below                                                                                                                           |
 
 > **Renamed in 0.8.0** — `config` → `client`, `styles` → `appConfig.styles`.
 > If you were passing `styles={{ ... }}` directly, move it to
@@ -127,25 +123,30 @@ needed.
 ```ts
 const {
   // Session
-  isAuthenticated, // boolean — true when a wallet public key is present
-  walletAddress, // string — '' until authenticated
-  walletType, // WalletId | null
+  isAuthenticated, // boolean - true when a wallet address is present
+  wallet, // WalletInfo | null - read wallet?.address for the on-chain address
+  verified, // boolean - true once the server has confirmed the session
 
   // Client escape hatch
-  getClient, // () => PollarClient — for getUserProfile(), listSessions(), …
+  getClient, // () => PollarClient - for getUserProfile(), listSessions(), …
 
   // Auth
   login, // (options: PollarLoginOptions) => void
   logout, // () => void  (fire-and-forget; await getClient().logout() if you need the promise)
   openLoginModal, // () => void
 
-  // Sessions (new in 0.7.0)
+  // Sessions
+  sessions, // SessionsState
   openSessionsModal, // () => void
 
   // Transactions
   tx, // TransactionState
-  buildTx, // (operation, params, options?) => Promise<void>
-  signAndSubmitTx, // (unsignedXdr: string) => Promise<void>
+  buildTx, // (operation, params, options?) => Promise<BuildOutcome>
+  signAndSubmitTx, // (unsignedXdr?: string) => Promise<SubmitOutcome>  (custodial; XDR optional)
+  signTx, // (unsignedXdr: string) => Promise<SignOutcome>  (external-wallet only)
+  submitTx, // (signedXdr: string) => Promise<SubmitOutcome>
+  buildAndSignAndSubmitTx, // (operation, params, options?) => Promise<SubmitOutcome>  (one-shot)
+  runTx, // alias of buildAndSignAndSubmitTx
   openTxModal, // () => void
 
   // Transaction history
@@ -157,18 +158,32 @@ const {
   refreshWalletBalance, // () => Promise<void>
   openWalletBalanceModal, // () => void
 
+  // Enabled assets / trustlines
+  enabledAssets, // EnabledAssetsState
+  refreshAssets, // () => Promise<void>
+  setTrustline, // (asset, opts?) => Promise<TrustlineOutcome>
+  openEnabledAssetsModal, // () => void
+
+  // Swap (DEX/AMM)
+  getSwapQuote, // (params: SwapQuoteParams) => Promise<SwapQuote[]>
+  swap, // (quote: SwapQuote, opts?) => Promise<SubmitOutcome>
+  openSwapModal, // () => void
+
+  // Distribution rules
+  openDistributionRulesModal, // () => void
+
   // Send / Receive
   openSendModal, // () => void
   openReceiveModal, // () => void
 
   // Network
-  network, // StellarNetwork — 'mainnet' | 'testnet'
+  network, // StellarNetwork - 'mainnet' | 'testnet'
   setNetwork, // (network: StellarNetwork) => void
 
-  // KYC (UI ready — backend coming soon)
+  // KYC (UI ready - backend coming soon)
   openKycModal, // (options?: { country?, level?, onApproved? }) => void
 
-  // Ramp (UI ready — backend coming soon)
+  // Ramp (SEP-24 on/off-ramps, wired through core)
   openRampModal, // () => void
 
   // App config / styles served by the Pollar API
@@ -180,8 +195,11 @@ const {
 } = usePollar();
 ```
 
-> **0.6.0 renames** — `transaction` → `tx`, `openTransactionModal` → `openTxModal`, `config` → `appConfig`,
-> `openRampWidget` → `openRampModal`, `refreshBalance` → `refreshWalletBalance`. Existing code on 0.5.x must update.
+Custody is derived from `wallet`, not a separate field - e.g.
+`wallet?.custody === 'external' ? wallet.provider : null`.
+
+> **0.6.0 renames** - `transaction` > `tx`, `openTransactionModal` > `openTxModal`, `config` > `appConfig`,
+> `openRampWidget` > `openRampModal`, `refreshBalance` > `refreshWalletBalance`. Existing code on 0.5.x must update.
 
 #### Login options
 
@@ -193,16 +211,32 @@ login({ provider: 'github' });
 // Email OTP
 login({ provider: 'email', email: 'user@example.com' });
 
-// Built-in Stellar wallet adapters
+// Built-in Stellar wallet adapters (the adapter's `type` IS the provider)
 import { WalletType } from '@pollar/core';
-login({ provider: 'wallet', type: WalletType.FREIGHTER });
-login({ provider: 'wallet', type: WalletType.ALBEDO });
+login({ provider: WalletType.FREIGHTER }); // 'freighter-native'
+login({ provider: WalletType.ALBEDO }); // 'albedo-native'
 
-// Any external adapter (e.g. Stellar Wallets Kit) when `walletAdapter` is set on config
-login({ provider: 'wallet', type: 'xbull' });
-login({ provider: 'wallet', type: 'lobstr' });
+// Any external adapter (e.g. Stellar Wallets Kit) registered via `walletAdapters`
+login({ provider: 'xbull' });
+login({ provider: 'lobstr' });
 ```
 
+#### Self-driving interactive adapters (Privy, …)
+
+Registered adapters that opt into the interactive-auth contract
+(`isInteractiveAuthAdapter` + `onProviderAuthChange`) are auto-driven by the
+provider:
+
+- `LoginModal` renders a login entry per registered wallet adapter, so each
+  interactive provider gets its own button.
+- Picking one opens `PrivyLoginSubmodal`, which drives the adapter's own login
+  (email code / OAuth) to completion, then hands off to `login({ provider })`
+  (which runs `connect()` + SEP-10).
+- If the provider authenticates outside the sub-modal - after an OAuth redirect
+  that reloaded the page, or a persisted provider session on load - the
+  provider's `onProviderAuthChange` subscription fires `login({ provider })`
+  automatically when Pollar has no session yet.
+
 ---
 
 ### Components
@@ -212,14 +246,17 @@ already wired inside `<PollarProvider>` — but they're exported in case you wan
 
 | Component              | Purpose                                                                                                                                                                                          |
 | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `<WalletButton>`       | Drop-in button. Opens login when signed out; signed in, shows the wallet address with a dropdown (Send, Receive, balance, history, sign out). Inline arc spinner during in-progress transactions |
-| `<SendModal>`          | Full send flow: asset picker, amount, destination, inline build → sign → success/error                                                                                                           |
-| `<ReceiveModal>`       | Wallet address as QR code with copy-to-clipboard (no external QR dependency required)                                                                                                            |
-| `<TxHistoryModal>`     | Paginated transaction history with auto-fetch on open and stellar.expert explorer links                                                                                                          |
-| `<WalletBalanceModal>` | Stellar account balances with refresh button                                                                                                                                                     |
-| `<SessionsModal>`      | **New in 0.7.0.** Lists every active refresh-token family for the current user with device metadata, marks the local session, per-row revoke, and a "Sign out everywhere" button                 |
-| `<KycModal>`           | Identity verification flow — provider selection + status polling _(UI preview — backend coming soon)_                                                                                            |
-| `<RampWidget>`         | Buy/sell crypto — direction tabs, route comparison, payment instructions _(UI preview — backend coming soon)_                                                                                    |
+| `<WalletButton>`         | Drop-in button. Opens login when signed out; signed in, shows the wallet address with a dropdown (Send, Receive, copy address, balance, history, ramp, KYC, distribution rules, sessions, sign out). Inline arc spinner during in-progress transactions |
+| `<SendModal>`            | Full send flow: asset picker, amount, destination, inline build > sign > success/error                                                                                                           |
+| `<SwapModal>`            | On-chain asset-to-asset swap: pick from/to assets and amount, quote across venues, execute (auto-trustline on the buy asset when needed)                                                          |
+| `<ReceiveModal>`         | Wallet address as QR code with copy-to-clipboard (no external QR dependency required)                                                                                                            |
+| `<TxHistoryModal>`       | Paginated transaction history with auto-fetch on open and stellar.expert explorer links                                                                                                          |
+| `<WalletBalanceModal>`   | Stellar account balances with refresh button                                                                                                                                                     |
+| `<EnabledAssetsModal>`   | The application's dashboard-enabled assets with per-asset trustline state; establish/remove trustlines                                                                                            |
+| `<DistributionRulesModal>` | Manage the wallet's distribution rules                                                                                                                                                         |
+| `<SessionsModal>`        | **New in 0.7.0.** Lists every active refresh-token family for the current user with device metadata, marks the local session, per-row revoke, and a "Sign out everywhere" button                 |
+| `<KycModal>`             | Identity verification flow - provider selection + status polling _(UI preview - backend coming soon)_                                                                                            |
+| `<RampWidget>`           | Buy/sell crypto via SEP-24 - direction tabs, route comparison, payment instructions (wired to `client.createOnRamp` / `client.createOffRamp`)                                                     |
 
 ```tsx
 import { WalletButton } from '@pollar/react';
@@ -241,10 +278,13 @@ want to swap the chrome but keep the data wiring from `usePollar()`.
 | `<WalletButton>`        | `<WalletButtonTemplate>`       |
 | _(internal LoginModal)_ | `<LoginModalTemplate>`         |
 | `<SendModal>`           | `<SendModalTemplate>`          |
+| `<SwapModal>`           | `<SwapModalTemplate>`          |
 | `<ReceiveModal>`        | `<ReceiveModalTemplate>`       |
 | `<TransactionModal>`    | `<TransactionModalTemplate>`   |
 | `<TxHistoryModal>`      | `<TxHistoryModalTemplate>`     |
 | `<WalletBalanceModal>`  | `<WalletBalanceModalTemplate>` |
+| `<EnabledAssetsModal>`  | `<EnabledAssetsModalTemplate>` |
+| `<DistributionRulesModal>` | `<DistributionRulesModalTemplate>` |
 | `<KycModal>`            | `<KycModalTemplate>`           |
 | `<RampWidget>`          | `<RampWidgetTemplate>`         |
 | `<SessionsModal>`       | `<SessionsModalTemplate>`      |
@@ -252,8 +292,7 @@ want to swap the chrome but keep the data wiring from `usePollar()`.
 `<TxStatusView>` is the shared status component (build → sign → success/error) reused by `TransactionModal` and
 `SendModal`; it's exported on its own for consumers that want to embed the lifecycle elsewhere.
 
-> **0.8.1** — `onWalletConnect` is now **optional** on `<LoginModalTemplate>` (defaults to a no-op). If you drive the
-> wallet picker entirely through `ui.renderWallets`, you no longer have to pass a handler you don't use.
+> **0.8.1** — `onWalletConnect` is now **optional** on `<LoginModalTemplate>` (defaults to a no-op).
 
 ---
 
@@ -299,68 +338,33 @@ function MyComponent() {
 
 ### External wallet stacks (Stellar Wallets Kit, …)
 
-Pass a `WalletAdapterResolver` to `client.walletAdapter` so Pollar can reach
-wallets that live outside `@pollar/core`. The signing path alone (no UI
-changes):
+Register adapters for wallets that live outside `@pollar/core` by passing a
+`walletAdapters: WalletAdapter[]` array. `LoginModal` auto-renders one button per
+registered adapter, and each is reachable via `login({ provider: adapter.type })`.
+`stellarWalletsKitAdapters()` returns that array (one adapter per kit module):
 
 ```tsx
 import { PollarProvider } from '@pollar/react';
-import { stellarWalletsKit } from '@pollar/stellar-wallets-kit-adapter';
+import { stellarWalletsKitAdapters } from '@pollar/stellar-wallets-kit-adapter';
 import { Networks } from '@creit.tech/stellar-wallets-kit';
 
 <PollarProvider
   client={{
     apiKey: 'your-api-key',
-    walletAdapter: stellarWalletsKit({ network: Networks.PUBLIC }),
+    walletAdapters: stellarWalletsKitAdapters({
+      network: Networks.PUBLIC,
+      picker: { wallets: ['xbull', 'lobstr', 'freighter'] }, // subset, optional
+    }),
   }}
 >
   {children}
 </PollarProvider>;
 ```
 
-Then any `login({ provider: 'wallet', type: '<kit wallet id>' })` is routed
-through the kit. The built-in `LoginModal` still shows only Freighter / Albedo
-unless you also wire `ui.renderWallets` (next section).
-
-#### Showing every kit wallet in `LoginModal`
-
-The `ui.renderWallets` slot replaces the hardcoded Freighter+Albedo buttons.
-`@pollar/stellar-wallets-kit-adapter/picker` ships a bundle that builds both
-halves (signing + picker UI) from a single options object — drop both into
-`<PollarProvider>` and the kit's full wallet list (xBull, Lobstr, Rabet, …)
-renders in `LoginModal`:
-
-```tsx
-import { PollarProvider } from '@pollar/react';
-import { createStellarWalletsKitBundle } from '@pollar/stellar-wallets-kit-adapter/picker';
-import { Networks } from '@creit.tech/stellar-wallets-kit';
-
-const bundle = createStellarWalletsKitBundle({
-  network: Networks.PUBLIC,
-  picker: { wallets: ['xbull', 'lobstr', 'freighter'] }, // subset, optional
-});
-
-<PollarProvider
-  client={{ apiKey: 'your-api-key', walletAdapter: bundle.walletAdapter }}
-  ui={{ renderWallets: bundle.renderWallets }}
->
-  {children}
-</PollarProvider>;
-```
-
-If you only want a custom picker (no kit), `renderWallets` is just a function
-of `{ onConnect, authState }` — return whatever JSX you want and call
-`onConnect(walletId)` when the user picks a wallet:
-
-```tsx
-ui={{
-  renderWallets: ({ onConnect, authState }) => (
-    <button disabled={authState.step !== 'idle'} onClick={() => onConnect('xbull')}>
-      xBull
-    </button>
-  ),
-}}
-```
+Each adapter's `meta.group` controls placement: adapters sharing a group label
+collapse behind one gateway button (the kit wallets default to `'Wallet'`),
+while adapters with no group — e.g. Privy — render as their own button in the
+root view. Pass `picker.groupLabel` to give the kit wallets a distinct gateway.
 
 ---
 
@@ -382,23 +386,25 @@ All class names are prefixed with `pollar-` to avoid conflicts.
 
 ```ts
 import type {
-  AuthProviderProps,
-  AuthContextValue,
   LoginButtonProps,
   AuthModalProps,
   PollarConfig,
   PollarStyles,
 
-  // 0.8.0 — wallet picker slot
-  RenderWalletsProps,
-  RenderWalletsSlot,
+  // Custom-provider contracts (re-exported from @pollar/core)
+  PollarAuthProvider,
+  AuthProviderContext,
 
   // Template props
+  WalletButtonTemplateProps,
   SendModalTemplateProps,
+  SwapModalTemplateProps,
+  SwapAssetOption,
   ReceiveModalTemplateProps,
   TransactionModalTemplateProps,
   TxStatusViewProps,
   WalletBalanceModalTemplateProps,
+  EnabledAssetsModalTemplateProps,
   SessionsModalTemplateProps,
   SessionsState,
 

package/dist/index.css

@@ -19,6 +19,9 @@
   display: flex;
   align-items: center;
   justify-content: center;
+  overflow-y: auto;
+  padding: 1rem;
+  box-sizing: border-box;
   background-color: rgba(0, 0, 0, 0.5);
 }
 .pollar-modal-card {
@@ -31,6 +34,8 @@
   background-color: var(--pollar-bg);
   box-sizing: border-box;
   font-family: inherit;
+  max-height: calc(100dvh - 2rem);
+  overflow-y: auto;
 }
 .pollar-input {
   width: 100%;
@@ -142,6 +147,7 @@
   flex: 1;
 }
 .pollar-btn-primary {
+  width: 100%;
   height: var(--pollar-buttons-height, 44px);
   border: none;
   border-radius: var(--pollar-buttons-border-radius, 0.5rem);
@@ -1019,26 +1025,29 @@
 .pollar-wallet-list {
   display: flex;
   flex-direction: column;
-  gap: 0.25rem;
+  gap: 0.625rem;
   margin-top: 0.5rem;
 }
 .pollar-wallet-list-btn {
   display: flex;
   width: 100%;
   align-items: center;
-  gap: 1rem;
-  padding: 0.75rem 0.75rem;
+  justify-content: center;
+  gap: 0.75rem;
+  min-height: var(--pollar-buttons-height, 44px);
+  padding: 0 1rem;
   border-radius: var(--pollar-buttons-border-radius, 0.5rem);
-  border: 1px solid transparent;
-  background-color: transparent;
+  border: 1px solid var(--pollar-border);
+  background-color: var(--pollar-input-bg);
   color: var(--pollar-text);
+  font-size: 1rem;
+  font-weight: 500;
   cursor: pointer;
   transition: all 0.15s;
   box-sizing: border-box;
-  text-align: left;
+  text-align: center;
 }
 .pollar-wallet-list-btn:hover:not(:disabled) {
-  background-color: var(--pollar-input-bg);
   border-color: var(--pollar-accent);
   color: var(--pollar-accent);
   box-shadow: 0 2px 8px rgba(0, 0, 0, 0.12);
@@ -1051,9 +1060,9 @@
   cursor: not-allowed;
 }
 .pollar-wallet-list-icon {
-  width: 2.75rem;
-  height: 2.75rem;
-  border-radius: 0.625rem;
+  width: 1.5rem;
+  height: 1.5rem;
+  border-radius: 0.375rem;
   flex-shrink: 0;
   object-fit: contain;
 }
@@ -1105,7 +1114,7 @@
   height: var(--pollar-buttons-height, 44px);
   align-items: center;
   justify-content: center;
-  gap: 0.625rem;
+  gap: 0.75rem;
   border-radius: var(--pollar-buttons-border-radius, 0.5rem);
   border: 1px solid var(--pollar-border);
   background-color: var(--pollar-input-bg);
@@ -1755,6 +1764,26 @@
   animation: pollar-pulse 1.4s ease-in-out infinite;
 }
 
+/* src/components/swap-modal/SwapModal.css */
+.pollar-swap-quote {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 12px;
+  margin-bottom: 12px;
+  border: 1px solid var(--pollar-border);
+  border-radius: var(--pollar-card-border-radius);
+  background: var(--pollar-input-bg);
+  color: var(--pollar-text);
+  font-size: 14px;
+}
+.pollar-swap-quote-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+}
+
 /* src/components/sessions-modal/SessionsModal.css */
 .pollar-sessions-modal {
   max-width: 480px;