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

package/skills/multi-chain-modal.md

@@ -1,178 +0,0 @@
-# Skill: Multi-chain 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](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/skills/setup.md)
-
-## Hooks
-
-| 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
-import {
-  useWalletModal,
-  useChainGroups,
-  useXConnectors,
-  type IXConnector,
-} from '@sodax/wallet-sdk-react';
-
-export function WalletModalRoot() {
-  const modal = useWalletModal({
-    onConnected: async (chainType, account) => {
-      // app side-effects (e.g. registration, ToS check)
-      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 (driven by `useChainGroups`)
-
-```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 (driven by `useXConnectors`)
-
-```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.
-
-## Reference docs
-
-- [Wallet Modal](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/WALLET_MODAL.md) — full state machine + cancellation semantics
-- [Chain Detection](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CHAIN_DETECTION.md) — `useChainGroups` + ordering
-- [Connect Flow](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONNECT_FLOW.md) — underlying `useXConnect` lifecycle

package/skills/setup.md

@@ -1,107 +0,0 @@
-# Skill: Setup
-
-Install and wire `@sodax/wallet-sdk-react` into a React project.
-
-**Depends on:** None
-
-## Install
-
-```bash
-pnpm add @sodax/wallet-sdk-react @tanstack/react-query
-```
-
-Peer dependencies:
-
-```json
-{
-  "react": ">=19",
-  "@tanstack/react-query": "5.x"
-}
-```
-
-## Wire `SodaxWalletProvider`
-
-Top-level keys on `SodaxWalletConfig` are chain-type slots — **omit a slot to skip mounting that adapter**, pass `{}` to mount with SDK defaults. `<QueryClientProvider>` must wrap `<SodaxWalletProvider>`.
-
-```tsx
-// providers.tsx
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import { SodaxWalletProvider, type SodaxWalletConfig } from '@sodax/wallet-sdk-react';
-import { ChainKeys } from '@sodax/types';
-
-const queryClient = new QueryClient();
-
-const walletConfig: SodaxWalletConfig = {
-  EVM: {
-    ssr: true, // Next.js — keep true for SSR-safe 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' },
-    },
-  },
-  ICON: {
-    chains: { [ChainKeys.ICON_MAINNET]: { rpcUrl: 'https://ctz.solidwallet.io/api/v3' } },
-  },
-  // BITCOIN: {},  // mount with SDK defaults
-  // SOLANA: { chains: { [ChainKeys.SOLANA_MAINNET]: { rpcUrl: '...' } } },
-};
-
-export function Providers({ children }: { children: React.ReactNode }) {
-  return (
-    <QueryClientProvider client={queryClient}>
-      <SodaxWalletProvider config={walletConfig}>{children}</SodaxWalletProvider>
-    </QueryClientProvider>
-  );
-}
-```
-
-Use `Providers` at the app root (e.g. `app/layout.tsx` for Next.js, `main.tsx` for Vite).
-
-## Chain-type slots
-
-| Slot | Mounts | When to include |
-|------|--------|-----------------|
-| `EVM` | wagmi (12 EVM chains) | Sonic, Ethereum, Arbitrum, Base, BSC, etc. |
-| `SOLANA` | `@solana/wallet-adapter-react` | Solana support |
-| `SUI` | `@mysten/dapp-kit` | Sui support |
-| `BITCOIN` | (no React adapter) | Bitcoin support |
-| `STELLAR` | (no React adapter) | Stellar support |
-| `ICON` | (no React adapter) | ICON support |
-| `INJECTIVE` | (no React adapter) | Injective support |
-| `NEAR` | (no React adapter) | NEAR support |
-| `STACKS` | (no React adapter) | Stacks support |
-
-## Config is captured once on mount
-
-`SodaxWalletProvider` freezes the `config` prop on first render. Subsequent re-renders with a new reference have **no effect**. To swap config at runtime, remount with a new `key`:
-
-```tsx
-<SodaxWalletProvider key={configVersion} config={walletConfig}>
-  {children}
-</SodaxWalletProvider>
-```
-
-## Pair with `@sodax/dapp-kit` (optional)
-
-If you also use `@sodax/dapp-kit` for SDK feature hooks, mount `SodaxProvider` outermost:
-
-```tsx
-<SodaxProvider config={sodaxConfig}>
-  <QueryClientProvider client={queryClient}>
-    <SodaxWalletProvider config={walletConfig}>{children}</SodaxWalletProvider>
-  </QueryClientProvider>
-</SodaxProvider>
-```
-
-See [`packages/dapp-kit/skills/setup.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/dapp-kit/skills/setup.md) for the dapp-kit side.
-
-## Next steps
-
-- [`connect-button.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/skills/connect-button.md) — single-chain connect/disconnect button
-- [`multi-chain-modal.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/skills/multi-chain-modal.md) — multi-chain headless wallet modal
-- [`bridge-to-sdk.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/skills/bridge-to-sdk.md) — pass `walletProvider` to `@sodax/sdk` calls
-
-## Reference docs
-
-- [Configure SodaxWalletProvider](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONFIGURE_PROVIDER.md) — full config reference, breaking changes from v1, per-chain `defaults`