@sodax/wallet-sdk-react 2.0.0-rc.2 → 2.0.0-rc.21

package/ai-exported/integration/examples/02-multi-chain-modal.tsx

@@ -1,169 +0,0 @@
-/**
- * Multi-chain headless wallet modal.
- * Renders chain picker → wallet picker → connecting → success/error using `useWalletModal`.
- *
- * UI uses native <dialog> — replace with shadcn/Radix/your dialog primitive.
- */
-
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import {
-  SodaxWalletProvider,
-  type SodaxWalletConfig,
-  useWalletModal,
-  useChainGroups,
-  useXConnectors,
-  sortConnectors,
-  type IXConnector,
-} from '@sodax/wallet-sdk-react';
-import type { ChainType } from '@sodax/types';
-import { ChainKeys } from '@sodax/types';
-
-const queryClient = new QueryClient();
-
-const walletConfig: SodaxWalletConfig = {
-  EVM: {
-    chains: {
-      [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://rpc.soniclabs.com' },
-      [ChainKeys.ETHEREUM_MAINNET]: { rpcUrl: 'https://ethereum-rpc.publicnode.com' },
-    },
-  },
-  SOLANA: {
-    chains: { [ChainKeys.SOLANA_MAINNET]: { rpcUrl: 'https://api.mainnet-beta.solana.com' } },
-  },
-  SUI: { network: 'mainnet' },
-  BITCOIN: {},
-  ICON: {
-    chains: { [ChainKeys.ICON_MAINNET]: { rpcUrl: 'https://ctz.solidwallet.io/api/v3' } },
-  },
-};
-
-export function App() {
-  return (
-    <QueryClientProvider client={queryClient}>
-      <SodaxWalletProvider config={walletConfig}>
-        <WalletModalRoot />
-      </SodaxWalletProvider>
-    </QueryClientProvider>
-  );
-}
-
-function WalletModalRoot() {
-  const modal = useWalletModal({
-    onConnected: (chainType, account) => {
-      console.log('connected', chainType, account.address);
-    },
-  });
-
-  switch (modal.state.kind) {
-    case 'closed':
-      return (
-        <button type="button" onClick={modal.open}>
-          Connect Wallet
-        </button>
-      );
-
-    case 'chainSelect':
-      return <ChainPicker onPick={modal.selectChain} onClose={modal.close} />;
-
-    case 'walletSelect':
-      return (
-        <WalletPicker
-          chainType={modal.state.chainType}
-          onPick={modal.selectWallet}
-          onBack={modal.back}
-          onClose={modal.close}
-        />
-      );
-
-    case 'connecting':
-      // Hide modal while wagmi's QR modal owns the screen for WalletConnect
-      if (modal.state.connector.id === 'walletConnect') return null;
-      return (
-        <Dialog onClose={modal.close}>
-          <p>Approve in {modal.state.connector.name}…</p>
-          <button type="button" onClick={modal.back}>
-            Cancel
-          </button>
-        </Dialog>
-      );
-
-    case 'error':
-      return (
-        <Dialog onClose={modal.close}>
-          <p>Error: {modal.state.error.message}</p>
-          {!modal.state.connector.isInstalled && modal.state.connector.installUrl && (
-            <a href={modal.state.connector.installUrl} target="_blank" rel="noreferrer">
-              Install {modal.state.connector.name}
-            </a>
-          )}
-          <button type="button" onClick={modal.retry}>
-            Retry
-          </button>
-          <button type="button" onClick={modal.back}>
-            Pick another wallet
-          </button>
-        </Dialog>
-      );
-
-    case 'success':
-      // onConnected fired; close the modal
-      queueMicrotask(modal.close);
-      return null;
-
-    default:
-      return null;
-  }
-}
-
-function ChainPicker({ onPick, onClose }: { onPick: (c: ChainType) => void; onClose: () => void }) {
-  const groups = useChainGroups({ order: ['EVM', 'SOLANA', 'SUI', 'BITCOIN', 'ICON'] });
-  return (
-    <Dialog onClose={onClose}>
-      <h2>Select a chain</h2>
-      {groups.map(group => (
-        <button type="button" key={group.chainType} onClick={() => onPick(group.chainType)}>
-          <span>{group.displayName}</span>
-          {group.isConnected && ' ✓'}
-        </button>
-      ))}
-    </Dialog>
-  );
-}
-
-const PREFERRED = ['hana', 'metamask', 'phantom'] as const;
-
-function WalletPicker({
-  chainType,
-  onPick,
-  onBack,
-  onClose,
-}: {
-  chainType: ChainType;
-  onPick: (c: IXConnector) => void;
-  onBack: () => void;
-  onClose: () => void;
-}) {
-  const connectors = sortConnectors(useXConnectors({ xChainType: chainType }), { preferred: PREFERRED });
-  return (
-    <Dialog onClose={onClose}>
-      <button type="button" onClick={onBack}>
-        ← Back
-      </button>
-      <h2>Connect to {chainType}</h2>
-      {connectors.map(connector => (
-        <button type="button" key={connector.id} onClick={() => onPick(connector)} disabled={!connector.isInstalled}>
-          {connector.name}
-          {!connector.isInstalled && ' (not installed)'}
-        </button>
-      ))}
-    </Dialog>
-  );
-}
-
-function Dialog({ children, onClose }: { children: React.ReactNode; onClose: () => void }) {
-  return (
-    <dialog open onClose={onClose} style={{ padding: 16 }}>
-      {children}
-    </dialog>
-  );
-}

package/ai-exported/integration/examples/03-nextjs-app-router.tsx

@@ -1,99 +0,0 @@
-/**
- * Next.js 15 App Router setup with SSR-safe hydration.
- *
- * This file shows three separate files merged into one for reference. In your
- * project, split them into the matching paths:
- *
- *   app/
- *   ├── layout.tsx     ← server component (RootLayout below — make it the file's `export default`)
- *   ├── providers.tsx  ← client component (Providers below — needs `'use client'` at top of file)
- *   └── page.tsx       ← client component (Home below — needs `'use client'` at top of file)
- *
- * Key SSR points:
- * - `EVM.ssr: true` enables wagmi cookie-based hydration.
- * - `'use client'` on every component that calls a hook from this package.
- * - QueryClient as a module constant — one client per app, never recreated.
- * - SodaxWalletProvider config also a module constant — frozen on first render.
- *
- * NOTE: this combined file uses named exports only so it lints clean. Each of
- * `RootLayout`, `Providers`, and `Home` should be the `export default` of its
- * own file in your real project.
- */
-
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import { SodaxWalletProvider, type SodaxWalletConfig, useConnectedChains } from '@sodax/wallet-sdk-react';
-import { ChainKeys } from '@sodax/types';
-import type { ReactNode } from 'react';
-
-// ============================================================
-// app/providers.tsx — client component
-// (top of file: `'use client';`)
-// ============================================================
-
-const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: { staleTime: 60 * 1000 },
-  },
-});
-
-const walletConfig: SodaxWalletConfig = {
-  EVM: {
-    ssr: true, // ← required for Next.js — enables wagmi cookies hydration
-    chains: {
-      [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://rpc.soniclabs.com' },
-      [ChainKeys.ETHEREUM_MAINNET]: { rpcUrl: 'https://ethereum-rpc.publicnode.com' },
-      [ChainKeys.BSC_MAINNET]: { rpcUrl: 'https://bsc-dataseed.binance.org' },
-    },
-  },
-};
-
-export function Providers({ children }: { children: ReactNode }) {
-  return (
-    <QueryClientProvider client={queryClient}>
-      <SodaxWalletProvider config={walletConfig}>{children}</SodaxWalletProvider>
-    </QueryClientProvider>
-  );
-}
-
-// ============================================================
-// app/layout.tsx — server component
-// (no `'use client'`; in your real file, change `export function` to `export default function`)
-// ============================================================
-
-export function RootLayout({ children }: { children: ReactNode }) {
-  return (
-    <html lang="en">
-      <body>
-        <Providers>{children}</Providers>
-      </body>
-    </html>
-  );
-}
-
-// ============================================================
-// app/page.tsx — client component (because we use a hook)
-// (top of file: `'use client';`; change `export function` to `export default function`)
-// ============================================================
-
-export function Home() {
-  // Gate UI on hydration to prevent reload flicker
-  const { chains, status } = useConnectedChains();
-
-  if (status === 'loading') {
-    return <p>Loading…</p>;
-  }
-
-  if (chains.length === 0) {
-    return <p>No wallets connected</p>;
-  }
-
-  return (
-    <ul>
-      {chains.map((c) => (
-        <li key={c.chainType}>
-          {c.chainType}: <code>{c.account.address}</code>
-        </li>
-      ))}
-    </ul>
-  );
-}

package/ai-exported/integration/examples/04-walletconnect-setup.tsx

@@ -1,89 +0,0 @@
-/**
- * WalletConnect setup — adds the WalletConnect connector to the EVM modal.
- * For dApps that target users on mobile-only or enterprise custody wallets
- * (Ledger Live, Safe, Fireblocks, ...) which cannot install browser extensions.
- *
- * Get a projectId at https://cloud.walletconnect.com
- *
- * To narrow the WalletConnect modal to ONE specific wallet (e.g. an enterprise
- * custody integration), see the commented `qrModalOptions` block below — fill
- * in the target wallet id from https://walletconnect.com/explorer.
- */
-
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import {
-  SodaxWalletProvider,
-  type SodaxWalletConfig,
-  useWalletModal,
-  useXConnectors,
-  useXAccount,
-  useXDisconnect,
-} from '@sodax/wallet-sdk-react';
-import { ChainKeys } from '@sodax/types';
-
-const queryClient = new QueryClient();
-
-const walletConfig: SodaxWalletConfig = {
-  EVM: {
-    ssr: true,
-    chains: {
-      [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://rpc.soniclabs.com' },
-      [ChainKeys.ETHEREUM_MAINNET]: { rpcUrl: 'https://ethereum-rpc.publicnode.com' },
-      [ChainKeys.ARBITRUM_MAINNET]: { rpcUrl: 'https://arb1.arbitrum.io/rpc' },
-    },
-    walletConnect: {
-      projectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID ?? '',
-      // Optional — restrict the WalletConnect QR modal to a specific wallet:
-      //
-      // qrModalOptions: {
-      //   explorerRecommendedWalletIds: ['<target-wallet-id-from-walletconnect-explorer>'],
-      //   explorerExcludedWalletIds: 'ALL', // hide everything except recommended
-      // },
-    },
-  },
-};
-
-export function App() {
-  return (
-    <QueryClientProvider client={queryClient}>
-      <SodaxWalletProvider config={walletConfig}>
-        <ConnectWithWalletConnect />
-      </SodaxWalletProvider>
-    </QueryClientProvider>
-  );
-}
-
-function ConnectWithWalletConnect() {
-  const modal = useWalletModal();
-  const connectors = useXConnectors({ xChainType: 'EVM' });
-  const account = useXAccount({ xChainType: 'EVM' });
-  const disconnect = useXDisconnect();
-
-  const wcConnector = connectors.find((c) => c.id === 'walletConnect');
-
-  // Hide the modal while wagmi/WalletConnect's QR modal owns the screen
-  if (modal.state.kind === 'connecting' && modal.state.connector.id === 'walletConnect') {
-    return null;
-  }
-
-  if (account.address) {
-    return (
-      <div>
-        <code>{account.address}</code>
-        <button type="button" onClick={() => disconnect({ xChainType: 'EVM' })}>
-          Disconnect
-        </button>
-      </div>
-    );
-  }
-
-  if (!wcConnector) {
-    return <p>WalletConnect not configured — set NEXT_PUBLIC_WC_PROJECT_ID</p>;
-  }
-
-  return (
-    <button type="button" onClick={() => modal.selectWallet(wcConnector)}>
-      Connect via WalletConnect
-    </button>
-  );
-}

package/ai-exported/integration/examples/README.md

@@ -1,29 +0,0 @@
-# Examples
-
-Copy-paste-runnable code examples. Each file is complete — drop it into a fresh React 19 project with `@sodax/wallet-sdk-react` + `@tanstack/react-query` installed and it works.
-
-For narrative + step-by-step explanation, see [`../recipes/`](../recipes/). Examples here are pure code with minimal comments.
-
-| File | Use case | Lines |
-|---|---|---|
-| [`01-minimal-evm.tsx`](./01-minimal-evm.tsx) | Smallest working setup — provider + 1 connect button | ~50 |
-| [`02-multi-chain-modal.tsx`](./02-multi-chain-modal.tsx) | Headless wallet modal with chain → connector → connecting flow | ~120 |
-| [`03-nextjs-app-router.tsx`](./03-nextjs-app-router.tsx) | Next.js 15 App Router setup (SSR + `'use client'`) | ~60 |
-| [`04-walletconnect-setup.tsx`](./04-walletconnect-setup.tsx) | WalletConnect connector setup (with optional single-wallet filter) | ~50 |
-
-## Conventions
-
-- All files use TypeScript (`.tsx`).
-- All consumer components have `'use client'` (Next.js compatible).
-- `walletConfig` is defined as a **module-level constant** — never created inside a component (the provider freezes config on first render).
-- `QueryClient` is also a module-level constant — one client per app, shared across providers.
-- Examples use `<button>`, `<select>`, `<dialog>` etc. directly — bring your own UI library.
-
-## Running an example
-
-```bash
-pnpm add @sodax/wallet-sdk-react @tanstack/react-query
-# also: react@>=19, react-dom@>=19
-```
-
-Drop the file into your app, mount the provider component at the root, and use the consumer component anywhere below it.

package/ai-exported/integration/recipes/batch-operations.md

@@ -1,223 +0,0 @@
-# Recipe: Batch Connect / Disconnect
-
-`useBatchConnect` and `useBatchDisconnect` orchestrate multi-chain wallet operations sequentially using **wallet brand identifiers** (e.g. `'hana'`, `'phantom'`) instead of individual connectors. Pass an identifier and the hooks discover every chain that wallet supports across the registry, then connect/disconnect them in order.
-
-Sequential by design — many extensions share popup singletons, so parallel attempts would race a single popup. Errors are collected, not thrown — `run()` always resolves.
-
-**Depends on:** [`setup.md`](./setup.md)
-
----
-
-## Identifier matching
-
-Both batch hooks (and `useIsWalletInstalled`) take a `connectors: readonly string[]` field. Each entry is a **wallet brand identifier** matched **case-insensitive substring** against `connector.id` and `connector.name`:
-
-| Identifier | Matches connectors |
-|------------|--------------------|
-| `'hana'` | Hana on EVM (`io.havah.hana`), Hana on ICON (`hana`), Hana on Sui, Hana on Stellar… |
-| `'phantom'` | Phantom on Solana (`phantom`), Phantom on EVM (`app.phantom`) |
-| `'metamask'` | MetaMask on EVM (`io.metamask`), Injective MetaMask connector |
-| `'xverse'` | Xverse on Bitcoin (`xverse`), Xverse on Stacks (`XverseProviders.BitcoinProvider`) |
-
-For the full list of known wallet brands and a runtime-discovery snippet (paste-in component that lists every connector available in your app), see [`../reference/wallet-brands.md`](../reference/wallet-brands.md).
-
-Earlier identifiers in the array are **higher-priority per chain**. The runner uses **fallback-on-failure**:
-
-- If a chain matches `'hana'` but the Hana popup is denied / errors out, the runner tries the next identifier's connector on that same chain (e.g. Phantom).
-- If a chain succeeds on the first identifier, later identifiers for that chain are **silently skipped** — only one popup per chain on the happy path.
-- A chain ends up in `result.failed` only when **every** matched identifier's connector has failed.
-
-```typescript
-// Prefer Hana on every chain it covers; fall back to Phantom either
-// because Hana isn't available (e.g. Solana) OR because its popup failed.
-const { run } = useBatchConnect({ connectors: ['hana', 'phantom'] });
-```
-
-`onProgress` fires per attempt — a chain can emit a `failure` event followed by a `success` event when fallback kicks in. The final outcome lives in `result`.
-
-To target a specific connector (not a brand), bypass this API and use `useXConnectors({ xChainType }).find(c => c.id === '...')` + `useXConnect` directly.
-
----
-
-## `useBatchConnect`
-
-Connect every chain where one of the supplied identifiers matches an installed connector. Sequential, never throws, dedupes concurrent runs.
-
-```tsx
-'use client';
-
-import { useBatchConnect } from '@sodax/wallet-sdk-react';
-
-export function ConnectAllHana() {
-  const { run, status, result, reset } = useBatchConnect({
-    connectors: ['hana'],
-    skipConnected: true, // skip chains already connected at run() time
-    onProgress: event => {
-      console.log(`[batch] ${event.chainType}: ${event.outcome}`);
-    },
-  });
-
-  return (
-    <div>
-      <button onClick={run} disabled={status === 'running'}>
-        {status === 'running' ? 'Connecting all Hana chains…' : 'Connect with Hana'}
-      </button>
-      {status === 'done' && result && (
-        <div>
-          <p>{result.successful.length} connected</p>
-          <p>{result.failed.length} failed</p>
-          <p>{result.skipped.length} skipped</p>
-          <button onClick={reset}>Reset</button>
-        </div>
-      )}
-    </div>
-  );
-}
-```
-
-### Options
-
-| Field | Type | Effect |
-|-------|------|--------|
-| `connectors` | `readonly string[]` | Identifiers (required, non-empty) |
-| `skipConnected` | `boolean` | Skip chains already holding an account at `run()` time. Default `false` |
-| `onProgress` | `(event) => void` | Per-target progress event |
-
-### Result shape
-
-```typescript
-type BatchConnectResult = {
-  successful: ChainType[];
-  failed: Array<{ chainType: ChainType; error: Error }>;
-  skipped: ChainType[];
-};
-```
-
-`run()` returns `Promise<BatchConnectResult>` — never rejects.
-
----
-
-## `useBatchDisconnect`
-
-Mirror of `useBatchConnect` for disconnect:
-
-```tsx
-import { useBatchDisconnect } from '@sodax/wallet-sdk-react';
-
-function DisconnectAll() {
-  const { run, status } = useBatchDisconnect();
-  // No `connectors` → disconnect every currently-connected chain regardless of wallet
-
-  return (
-    <button onClick={run} disabled={status === 'running'}>
-      {status === 'running' ? 'Disconnecting…' : 'Disconnect all chains'}
-    </button>
-  );
-}
-
-function DisconnectHanaOnly() {
-  const { run } = useBatchDisconnect({ connectors: ['hana'] });
-  // Only disconnect chains whose CURRENTLY ACTIVE connector matches 'hana'
-  return <button onClick={run}>Disconnect Hana</button>;
-}
-```
-
-### Scope difference vs `useBatchConnect`
-
-`useBatchConnect.connectors` is **mandatory** — it picks **which connector** to use on each chain.
-
-`useBatchDisconnect.connectors` is **optional** — it filters **which chains** to disconnect by checking the **currently active** connector against the identifiers. Chains where the active connector doesn't match are left untouched.
-
-```typescript
-useBatchDisconnect();                                // Disconnect every chain
-useBatchDisconnect({ connectors: ['hana'] });        // Disconnect chains where Hana is active
-useBatchDisconnect({ connectors: ['hana', 'xverse'] }); // Hana OR Xverse
-```
-
----
-
-## Wallet install detection — `useIsWalletInstalled`
-
-Companion read hook that uses the same identifier matching to detect whether a wallet brand is installed for any (or specific) chain.
-
-```typescript
-import { useIsWalletInstalled } from '@sodax/wallet-sdk-react';
-
-// True if any Hana variant is installed across any enabled chain
-const isHanaInstalled = useIsWalletInstalled({ connectors: ['hana'] });
-
-// True if any wallet is installed for the given chain
-const hasBitcoinWallet = useIsWalletInstalled({ chainType: 'BITCOIN' });
-
-// AND filter — Hana specifically on EVM
-const hanaOnEvm = useIsWalletInstalled({ connectors: ['hana'], chainType: 'EVM' });
-```
-
-The options union enforces at the type level that **at least one** of `connectors` / `chainType` is present. Use this hook to gate an `useBatchConnect` button:
-
-```tsx
-const isInstalled = useIsWalletInstalled({ connectors: ['hana'] });
-const { run } = useBatchConnect({ connectors: ['hana'] });
-
-return isInstalled ? (
-  <button onClick={run}>Connect Hana</button>
-) : (
-  <a href="https://hana-wallet.com">Install Hana</a>
-);
-```
-
----
-
-## Status lifecycle and concurrency
-
-| `status` | Meaning |
-|----------|---------|
-| `'idle'` | Initial / after `reset()` |
-| `'running'` | A `run()` is in flight |
-| `'done'` | The last `run()` settled — `result` is populated |
-
-**Concurrent `run()` calls are deduped** — the second call returns the existing in-flight promise.
-
-**`reset()` does NOT abort an in-flight batch** — there is no cancellation signal. It only clears the observable `status` / `result`. Typical usage: call `reset()` only after `status === 'done'`.
-
----
-
-## Progress events
-
-```typescript
-const { run } = useBatchConnect({
-  connectors: ['hana'],
-  onProgress: event => {
-    switch (event.outcome) {
-      case 'success': toast(`✓ Connected ${event.chainType}`); break;
-      case 'failure': toast.error(`✗ ${event.chainType}: ${event.error.message}`); break;
-      case 'skipped': toast(`⏭ ${event.chainType} already connected`); break;
-    }
-  },
-});
-```
-
-`onProgress` is read from a ref each time, so passing an inline arrow function is safe.
-
----
-
-## When to use the lower-level hooks instead
-
-Reach for `useXConnect` / `useXDisconnect` directly when:
-
-- **You need a specific connector**, not a brand.
-- **Order is user-driven**, not registry-driven.
-- **You need cancellation** — batch hooks have no cancel signal.
-- **You only have one chain to operate on**.
-
----
-
-## Verification
-
-```bash
-# 1. Type check
-pnpm checkTs
-
-# 2. Manual — install Hana, click batch connect button, confirm sequential popups across chains
-# 3. Manual — confirm result.failed contains chains where Hana isn't available
-```