@sodax/wallet-sdk-react 1.5.6-beta → 2.0.0-rc.1

package/ai-exported/integration/recipes/chain-detection.md

@@ -0,0 +1,254 @@
+# Recipe: Chain & Wallet Detection
+
+Aggregate views over the wallet store — what's enabled, what's connected, what's installed. Use these hooks to render chain pickers, "manage connections" panels, install CTAs, and hydration-safe UIs.
+
+**Depends on:** [`setup.md`](./setup.md)
+
+---
+
+## Hooks at a glance
+
+| Hook | Purpose |
+|------|---------|
+| `useEnabledChains()` | List chain types mounted in `SodaxWalletProvider` config |
+| `useChainGroups({ order? })` | One row per enabled chain (with display + connection metadata) — for chain pickers |
+| `useConnectedChains({ order? })` | List of currently-connected chains + hydration `status` — for "manage connections" |
+| `useIsWalletInstalled({ connectors?, chainType? })` | Cross-chain install check — for gating "Install X" CTA |
+
+EVM **collapses to a single row** — wagmi maintains one connection across every configured EVM network.
+
+---
+
+## `useEnabledChains` — what's mounted
+
+```tsx
+import { useEnabledChains } from '@sodax/wallet-sdk-react';
+
+const enabled = useEnabledChains();
+// e.g. ['EVM', 'SOLANA', 'BITCOIN']
+```
+
+Returns the slot keys in `SodaxWalletConfig` (`config.EVM`, `config.SOLANA`, …), not which chains have a wallet connected. Use cases:
+
+- Render only chain rows the dApp opted into.
+- Cross-reference with `useXConnections()` to compute "of N enabled chains, M are connected".
+- Drive `<Tabs>` / `<Select>` UIs without hard-coding a list.
+
+`useChainGroups` and `useConnectedChains` already filter by `useEnabledChains` internally — reach for it directly only when you need the raw list.
+
+---
+
+## `useChainGroups` — chain picker model
+
+One `ChainGroup` per enabled chain type, with display metadata + connection status. Designed for the "select a chain" step in modals.
+
+```tsx
+'use client';
+
+import { useChainGroups } from '@sodax/wallet-sdk-react';
+import type { ChainType } from '@sodax/types';
+
+export function ChainPicker({ onPick }: { onPick: (c: ChainType) => void }) {
+  const groups = useChainGroups({ order: ['EVM', 'SOLANA', 'BITCOIN', 'ICON'] });
+
+  return (
+    <ul>
+      {groups.map((group) => (
+        <li key={group.chainType}>
+          <button onClick={() => onPick(group.chainType)}>
+            {group.iconUrl && <img src={group.iconUrl} alt="" width={24} height={24} />}
+            <span>{group.displayName}</span>
+            {group.isConnected && <span className="badge">Connected</span>}
+          </button>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### `ChainGroup` shape
+
+| Field | Type | Source |
+|-------|------|--------|
+| `chainType` | `ChainType` | The slot key (`'EVM'`, `'SOLANA'`, …) |
+| `chainIds` | `readonly SpokeChainKey[]` | All chain keys sharing this `chainType` (e.g. all 12 EVM `ChainKeys.*` for `'EVM'`) |
+| `displayName` | `string` | Default per-chain display name |
+| `iconUrl` | `string \| undefined` | `undefined` = SDK doesn't ship one — provide your own |
+| `isConnected` | `boolean` | `true` when an account is connected for this chain |
+| `account` | `XAccount \| undefined` | Connected account |
+| `connectorId` | `string \| undefined` | Active connector id when connected |
+
+EVM's `chainIds` lists every configured EVM `ChainKey`, but the group itself is **one row**. Per-network switching belongs to [`switch-chain.md`](./switch-chain.md), not a separate group.
+
+---
+
+## `useConnectedChains` — connected list with hydration gate
+
+Returns one entry per **currently-connected** chain (skipping the rest), with enriched connector metadata for "manage connections" UIs and status badges.
+
+```tsx
+'use client';
+
+import { useConnectedChains } from '@sodax/wallet-sdk-react';
+
+export function ConnectionList() {
+  const { chains, total, status } = useConnectedChains();
+
+  if (status === 'loading') return <Skeleton />;
+  if (total === 0) return <ConnectCta />;
+
+  return (
+    <ul>
+      {chains.map((chain) => (
+        <li key={chain.chainType}>
+          {chain.connectorIcon && <img src={chain.connectorIcon} alt="" />}
+          <span>{chain.connectorName ?? chain.connectorId}</span>
+          <code>{chain.account.address}</code>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### `ConnectedChain` shape
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `chainType` | `ChainType` | |
+| `account` | `XAccount` | Always populated (only included when address is non-empty) |
+| `connectorId` | `string` | The persisted active connector |
+| `connectorName` | `string \| undefined` | Looked up in `xConnectorsByChain` |
+| `connectorIcon` | `string \| undefined` | |
+
+### Result shape
+
+```typescript
+type UseConnectedChainsResult = {
+  chains: ConnectedChain[];
+  total: number;
+  status: 'loading' | 'ready';
+};
+```
+
+---
+
+## `useIsWalletInstalled` — install detection
+
+Read hook for gating "Connect" buttons on actual installation. Same identifier matching as `useBatchConnect` — see [`batch-operations.md`](./batch-operations.md).
+
+```typescript
+import { useIsWalletInstalled } from '@sodax/wallet-sdk-react';
+
+// True if any Hana variant is installed across all enabled chains
+const hasHana = useIsWalletInstalled({ connectors: ['hana'] });
+
+// True if any wallet is installed for Bitcoin specifically
+const hasBitcoinWallet = useIsWalletInstalled({ chainType: 'BITCOIN' });
+
+// AND filter — Hana specifically on EVM
+const hanaOnEvm = useIsWalletInstalled({ connectors: ['hana'], chainType: 'EVM' });
+```
+
+The type union enforces at compile time that **at least one of `connectors` / `chainType`** is present — `useIsWalletInstalled({})` is a type error. `connectors: []` is explicit "match nothing" — returns `false`.
+
+---
+
+## Hydration status — gate reload flicker
+
+`useConnectedChains` exposes `status: 'loading' | 'ready'`. Use it to avoid the "Connect wallet" → "Connected" flash on page reload while Zustand rehydrates from `localStorage`:
+
+```tsx
+const { chains, status } = useConnectedChains();
+
+// ❌ Flicker — `chains` is empty for one render before hydration completes
+return chains.length >= 1 ? <Connected /> : <ConnectCta />;
+
+// ✅ No flicker — wait for hydration before deciding
+return status === 'loading'
+  ? <Skeleton />
+  : chains.length >= 1 ? <Connected /> : <ConnectCta />;
+```
+
+For first-paint correctness in SSR (Next.js), prefer `useConnectedChains.status` over an ad-hoc `useEffect(() => setMounted(true), [])` pattern — it's the official hydration signal.
+
+`useChainGroups` does **not** expose this flag — its outputs are stable across hydration because connection-status fields (`isConnected`, `account`) start as `false` / `undefined` and gain values atomically when the persist middleware finishes.
+
+---
+
+## Display ordering
+
+Both `useChainGroups` and `useConnectedChains` accept an `order?: readonly ChainType[]`:
+
+1. Chains in the array render in array order.
+2. Chains **not** in the array fall to the bottom, sorted alphabetically.
+3. Without `order`:
+   - `useChainGroups` follows the order of slots in `walletConfig` (config object key order).
+   - `useConnectedChains` follows `ChainTypeArr` from `@sodax/types` — stable across reloads.
+
+```typescript
+const groups = useChainGroups({ order: ['EVM', 'ICON'] });
+// EVM → ICON → (alphabetical: BITCOIN, INJECTIVE, NEAR, SOLANA, STACKS, STELLAR, SUI)
+```
+
+For UIs that must not reflow on reload (header chain list, navigation), always pass `order`.
+
+---
+
+## Common patterns
+
+### Pattern 1 — header connected-account chip
+
+```tsx
+function HeaderAccountChip() {
+  const { chains, status } = useConnectedChains();
+
+  if (status === 'loading') return null;
+  if (chains.length === 0) return <ConnectButton />;
+
+  return <span>{chains.length} chain{chains.length !== 1 ? 's' : ''} connected</span>;
+}
+```
+
+### Pattern 2 — "install Hana" CTA when not installed
+
+```tsx
+function HanaCta() {
+  const installed = useIsWalletInstalled({ connectors: ['hana'] });
+  return installed ? null : (
+    <a href="https://hana-wallet.com" target="_blank" rel="noreferrer">
+      Install Hana Wallet
+    </a>
+  );
+}
+```
+
+### Pattern 3 — chain selector in swap form
+
+```tsx
+function ChainSelector({ value, onChange }: { value: ChainType; onChange: (c: ChainType) => void }) {
+  const groups = useChainGroups({ order: ['EVM', 'SOLANA', 'SUI'] });
+  return (
+    <select value={value} onChange={(e) => onChange(e.target.value as ChainType)}>
+      {groups.map((g) => (
+        <option key={g.chainType} value={g.chainType}>
+          {g.displayName} {g.isConnected ? '✓' : ''}
+        </option>
+      ))}
+    </select>
+  );
+}
+```
+
+---
+
+## Verification
+
+```bash
+# 1. Type check
+pnpm checkTs
+
+# 2. Manual — load page on slow 3G, confirm no Connect→Connected flash on reload
+# 3. Manual — uninstall Hana, confirm CTA appears; reinstall, confirm CTA disappears
+```

package/ai-exported/integration/recipes/connect-button.md

@@ -0,0 +1,156 @@
+# Recipe: Connect Button
+
+Single-chain connect/disconnect button — pick a connector, connect, read the account, disconnect. Self-contained.
+
+**Depends on:** [`setup.md`](./setup.md)
+
+---
+
+## Hooks used
+
+| Hook | Purpose |
+|------|---------|
+| `useXConnectors({ xChainType })` | List available connectors for the chain family |
+| `useXConnect()` | React Query mutation — `mutate(connector)` |
+| `useXAccount({ xChainType })` | Read connected account (always returns object — `address` is `undefined` when disconnected) |
+| `useXDisconnect()` | Returns `(xChainType) => Promise<void>` |
+| `sortConnectors(list, { preferred })` | Optional — rank installed/preferred wallets first |
+
+---
+
+## Connect button
+
+```tsx
+'use client';
+
+import {
+  useXConnectors,
+  useXConnect,
+  useXAccount,
+  useXDisconnect,
+  sortConnectors,
+  type IXConnector,
+} from '@sodax/wallet-sdk-react';
+
+const PREFERRED = ['hana', 'metamask'] as const;
+
+export function EvmConnectButton() {
+  const raw = useXConnectors({ xChainType: 'EVM' });
+  const connectors = sortConnectors(raw, { preferred: PREFERRED });
+  const { mutateAsync: connect, isPending, error } = useXConnect();
+  const account = useXAccount({ xChainType: 'EVM' });
+  const disconnect = useXDisconnect();
+
+  if (account.address) {
+    return (
+      <div>
+        <code>{account.address}</code>
+        <button onClick={() => disconnect({ xChainType: 'EVM' })}>Disconnect</button>
+      </div>
+    );
+  }
+
+  return (
+    <div>
+      {connectors.map((connector) => (
+        <button
+          key={connector.id}
+          onClick={() => connect(connector).catch(() => {})}
+          disabled={isPending}
+        >
+          {connector.icon && <img src={connector.icon} alt="" width={20} height={20} />}
+          {connector.name}
+          {!connector.isInstalled && ' (not installed)'}
+        </button>
+      ))}
+      {error && <p style={{ color: 'red' }}>{error.message}</p>}
+    </div>
+  );
+}
+```
+
+---
+
+## Install CTA for missing wallets
+
+```tsx
+{connectors.map((connector) =>
+  connector.isInstalled ? (
+    <button key={connector.id} onClick={() => connect(connector)}>
+      {connector.name}
+    </button>
+  ) : (
+    <a key={connector.id} href={connector.installUrl} target="_blank" rel="noreferrer">
+      Install {connector.name}
+    </a>
+  ),
+)}
+```
+
+`isInstalled` reads `window.*` at render time (no extra subscription). For batch install detection across wallet brands, use `useIsWalletInstalled` — see [`batch-operations.md`](./batch-operations.md).
+
+---
+
+## Caveat — provider-managed chains resolve with `undefined`
+
+For EVM, Solana, and Sui, `connect(connector)` resolves with `undefined` because connection state is set asynchronously after the native SDK adapter reports `connected`. Always read the account via `useXAccount`, not the mutation's return value:
+
+```typescript
+const { mutateAsync: connect } = useXConnect();
+const account = useXAccount({ xChainType: 'EVM' });
+
+await connect(connector); // resolves with undefined for EVM
+// account.address is populated on the next render
+```
+
+Non-provider chains (Bitcoin, ICON, Injective, Stellar, NEAR, Stacks) return the resolved `XAccount` from `connect()` — but reading via `useXAccount` works for both, so default to it.
+
+---
+
+## Multiple chains, one button
+
+For a "connect EVM + Solana + Bitcoin in one click" pattern, use [`batch-operations.md`](./batch-operations.md):
+
+```tsx
+import { useBatchConnect } from '@sodax/wallet-sdk-react';
+
+const { run, status } = useBatchConnect({ connectors: ['hana'] });
+// Connects every chain Hana supports — sequential, errors collected.
+<button onClick={run} disabled={status === 'running'}>
+  Connect Hana on all chains
+</button>;
+```
+
+---
+
+## Variations
+
+### Per-chain-id button (e.g. one button per EVM network)
+
+⚠️ Not recommended for EVM — wagmi treats EVM as a **single connection across every configured network**. A per-Ethereum button rarely matches user expectations. If you really need per-chain-id resolution:
+
+```tsx
+import { ChainKeys } from '@sodax/types';
+
+const account = useXAccount({ xChainId: ChainKeys.ETHEREUM_MAINNET });
+```
+
+### Sui / Solana / etc.
+
+Replace `'EVM'` with the chain type the button targets:
+
+```tsx
+const connectors = useXConnectors({ xChainType: 'SUI' });
+const { address } = useXAccount({ xChainType: 'SUI' });
+```
+
+---
+
+## Verification
+
+```bash
+# 1. Type check
+pnpm checkTs
+
+# 2. Manual — load page, click connect, confirm address renders, reload page, confirm connection survives
+```

package/ai-exported/integration/recipes/multi-chain-modal.md

@@ -0,0 +1,199 @@
+# Recipe: Multi-Chain Wallet Modal
+
+Headless wallet-connect modal that walks the user through `chainSelect → walletSelect → connecting → success | error`. Pair with `useChainGroups` for the chain picker and `useXConnectors` for the wallet picker. Render-agnostic — works with any dialog/drawer/inline UI.
+
+**Depends on:** [`setup.md`](./setup.md)
+
+---
+
+## Hooks used
+
+| Hook | Purpose |
+|------|---------|
+| `useWalletModal({ onConnected? })` | State machine + actions (`open`, `close`, `back`, `selectChain`, `selectWallet`, `retry`) |
+| `useChainGroups({ order? })` | One row per enabled chain family (EVM collapses to one row) |
+| `useXConnectors({ xChainType })` | Wallet list for the chosen chain family |
+| `useXAccount({ xChainType })` | Read the connected account when needed |
+
+---
+
+## Render switch
+
+```tsx
+'use client';
+
+import {
+  useWalletModal,
+  useChainGroups,
+  useXConnectors,
+  type IXConnector,
+} from '@sodax/wallet-sdk-react';
+
+export function WalletModalRoot() {
+  const modal = useWalletModal({
+    onConnected: async (chainType, account) => {
+      console.log('connected', chainType, account.address);
+    },
+  });
+
+  switch (modal.state.kind) {
+    case 'closed':
+      return <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 is up for WalletConnect
+      if (modal.state.connector.id === 'walletConnect') return null;
+      return (
+        <Dialog onClose={modal.close}>
+          <p>Approve in {modal.state.connector.name}…</p>
+          <button onClick={modal.back}>Cancel</button>
+        </Dialog>
+      );
+
+    case 'success':
+      // onConnected fired; close after a beat
+      setTimeout(modal.close, 0);
+      return null;
+
+    case 'error':
+      return (
+        <Dialog onClose={modal.close}>
+          <p>{modal.state.error.message}</p>
+          {!modal.state.connector.isInstalled && modal.state.connector.installUrl && (
+            <a href={modal.state.connector.installUrl}>Install {modal.state.connector.name}</a>
+          )}
+          <button onClick={modal.retry}>Retry</button>
+          <button onClick={modal.back}>Pick another wallet</button>
+        </Dialog>
+      );
+  }
+}
+```
+
+Render `<WalletModalRoot />` once at the app root — any other component can dispatch `useWalletModal().open()` to show it.
+
+---
+
+## Chain picker
+
+```tsx
+import { useChainGroups } from '@sodax/wallet-sdk-react';
+import type { ChainType } from '@sodax/types';
+
+function ChainPicker({ onPick, onClose }: { onPick: (c: ChainType) => void; onClose: () => void }) {
+  const groups = useChainGroups({ order: ['EVM', 'SOLANA', 'BITCOIN', 'ICON'] });
+
+  return (
+    <Dialog onClose={onClose}>
+      <h2>Select a chain</h2>
+      {groups.map((group) => (
+        <button key={group.chainType} onClick={() => onPick(group.chainType)}>
+          {group.iconUrl && <img src={group.iconUrl} alt="" width={24} height={24} />}
+          <span>{group.displayName}</span>
+          {group.isConnected && <span>Connected</span>}
+        </button>
+      ))}
+    </Dialog>
+  );
+}
+```
+
+EVM collapses to a single group covering every configured EVM network — this matches reality (wagmi maintains one connection across all EVM chains).
+
+---
+
+## Wallet picker
+
+```tsx
+import { useXConnectors, sortConnectors, type IXConnector } from '@sodax/wallet-sdk-react';
+import type { ChainType } from '@sodax/types';
+
+function WalletPicker({
+  chainType,
+  onPick,
+  onBack,
+  onClose,
+}: {
+  chainType: ChainType;
+  onPick: (c: IXConnector) => void;
+  onBack: () => void;
+  onClose: () => void;
+}) {
+  const connectors = sortConnectors(useXConnectors({ xChainType: chainType }), {
+    preferred: ['hana', 'metamask', 'phantom'],
+  });
+
+  return (
+    <Dialog onClose={onClose}>
+      <button onClick={onBack}>← Back</button>
+      <h2>Select a wallet</h2>
+      {connectors.map((connector) => (
+        <button key={connector.id} onClick={() => onPick(connector)}>
+          {connector.icon && <img src={connector.icon} alt="" />}
+          {connector.name}
+          {!connector.isInstalled && ' (not installed)'}
+        </button>
+      ))}
+    </Dialog>
+  );
+}
+```
+
+---
+
+## Concurrency rules
+
+- **Same connector double-click** → returns the same in-flight promise (no double popup).
+- **Different connector mid-attempt** → starts a new attempt; previous one's late resolution is dropped.
+- **`back()` / `close()` mid-attempt** → cancellation guard inside the modal layer; the wallet may still approve in the background but `success`/`error` won't fire. To roll back, call `useXDisconnect()(xChainType)` from the same handler.
+
+---
+
+## `onConnected` is non-fatal
+
+Throwing inside `onConnected` is logged but **does not** downgrade `success` → `error`. The connection is already persisted; the user is genuinely connected.
+
+---
+
+## Non-modal alternative — `useConnectionFlow`
+
+For a single-button flow without the multi-step modal:
+
+```tsx
+import { useConnectionFlow } from '@sodax/wallet-sdk-react';
+
+const { status, error, connect, retry, activeConnector } = useConnectionFlow();
+
+return (
+  <button onClick={() => connect(connector)} disabled={status === 'connecting'}>
+    {status === 'connecting' ? 'Waiting…' : 'Connect'}
+  </button>
+);
+```
+
+`connect()` and `retry()` never throw — errors flow into `error` state.
+
+---
+
+## Verification
+
+```bash
+# 1. Type check
+pnpm checkTs
+
+# 2. Manual — open modal, walk through chain → wallet → connecting → success → close
+# 3. Manual — pick non-installed wallet, confirm install link appears in error state
+```