@cookill/wallet-adapter 3.2.1 → 3.2.2

package/README.md

@@ -1,61 +1,41 @@
-# @cookill/wallet-adapter
+# @cookill/wallet-adapter v3.2.1
 
-Wallet adapter for **Sheep Wallet** — the browser extension wallet for the Rialo blockchain.
+Official wallet adapter for **Sheep Wallet** on Rialo blockchain.
+
+## 🚀 What's New in v3.2.1
+
+- **Anti-freeze connect flow**: connect path remains timeout-protected
+- **Luxury Minimal WalletModal**: rebranded Sheep Wallet modal with clearer connect state
+- **ConnectButton behavior fix**: disconnected click now opens modal consistently
+- **Safer developer guidance**: docs clarified to avoid misleading integration assumptions
 
 ## Installation
 
 ```bash
 npm install @cookill/wallet-adapter
+# or
+pnpm add @cookill/wallet-adapter
+# or
+yarn add @cookill/wallet-adapter
 ```
 
 ## Quick Start (React)
 
 ```tsx
-import { WalletProvider, ConnectButton } from '@cookill/wallet-adapter/react';
+import { WalletProvider, ConnectButton, WalletErrorBoundary } from '@cookill/wallet-adapter/react';
 
 function App() {
   return (
-    <WalletProvider network="devnet" autoConnect>
-      <ConnectButton />
-      <YourDApp />
-    </WalletProvider>
+    <WalletErrorBoundary>
+      <WalletProvider network="devnet" autoConnect>
+        <ConnectButton />
+        <YourDApp />
+      </WalletProvider>
+    </WalletErrorBoundary>
   );
 }
 ```
 
-`WalletProvider` renders a built-in connect modal automatically. On desktop it opens as a centered dialog; on mobile it slides up as a bottom sheet with swipe-to-dismiss.
-
-## Built-in Modal
-
-The built-in modal is rendered inside `WalletProvider` and includes:
-
-- **Extension tab** — detects Sheep Wallet, shows install link if not found, triggers `window.rialo.connect()` on click
-- **Scan to Connect tab** — generates a `rialo-wc://` QR code for cross-device pairing
-- **Responsive layout** — centered dialog on desktop, slide-up sheet on mobile
-- **Auto-close** — closes automatically after successful connection
-
-Control it programmatically:
-
-```tsx
-const { openModal, closeModal } = useWallet();
-
-// Open the built-in modal
-openModal();
-```
-
-Or use `ConnectButton` which handles everything:
-
-```tsx
-<ConnectButton
-  connectLabel="Connect Wallet"
-  disconnectLabel="Disconnect"
-  showAddress={true}
-  showBalance={false}
-/>
-```
-
-> When the extension is installed, `ConnectButton` calls `connect()` directly without opening the modal. When not installed, it opens the modal with a download link.
-
 ## React Hooks
 
 ### useWallet
@@ -63,206 +43,272 @@ Or use `ConnectButton` which handles everything:
 ```tsx
 import { useWallet } from '@cookill/wallet-adapter/react';
 
-const {
-  connected,       // boolean
-  connecting,      // boolean
-  activeAccount,   // WalletAccount | null
-  chainId,         // string — e.g. "rialo:devnet"
-  isInstalled,     // boolean — extension detected
-
-  // Actions
-  connect,         // () => Promise<WalletAccount[]>
-  disconnect,      // () => Promise<void>
-  switchNetwork,   // (network) => Promise<void>
-  refreshBalance,  // () => Promise<void>
-
-  // Signing & Transactions
-  signMessage,             // (msg: string) => Promise<SignedMessage>
-  signTransaction,         // (tx) => Promise<string>
-  sendTransaction,         // (tx) => Promise<TransactionResult>
-  signAndSendTransaction,  // (tx) => Promise<TransactionResult>
-
-  // Modal control
-  openModal,   // () => void
-  closeModal,  // () => void
-} = useWallet();
+function MyComponent() {
+  const {
+    // State
+    connected,           // boolean
+    connecting,          // boolean
+    activeAccount,       // WalletAccount | null
+    state,               // Full state object
+    chainId,             // 'rialo:devnet' etc
+    isInstalled,         // boolean
+    
+    // Actions
+    connect,             // () => Promise<WalletAccount[]>
+    disconnect,          // () => Promise<void>
+    switchNetwork,       // (network) => Promise<void>
+    refreshBalance,      // () => Promise<void>
+    
+    // Transactions
+    signMessage,         // (message: string) => Promise<SignedMessage>
+    signTransaction,     // (tx) => Promise<string>
+    sendTransaction,     // (tx) => Promise<TransactionResult>
+    signAndSendTransaction, // (tx) => Promise<TransactionResult>
+    
+    // Modal
+    openModal,
+    closeModal,
+  } = useWallet();
+
+  return (
+    <div>
+      {connected ? (
+        <p>Connected: {activeAccount?.address}</p>
+      ) : (
+        <button onClick={connect}>Connect</button>
+      )}
+    </div>
+  );
+}
 ```
 
-### Focused Hooks
+### Specialized Hooks
 
 ```tsx
+// Connection
 const { connect, connecting, isInstalled, error } = useConnectWallet();
 const { disconnect, connected } = useDisconnectWallet();
 const connected = useIsConnected();
+
+// Account
 const account = useActiveAccount();
 const accounts = useAccounts();
-const { balance, refresh } = useBalance();
-const { network, chainId } = useNetwork();
-const { switchNetwork } = useSwitchNetwork();
-const { sendTransaction, signAndSendTransaction, sendGaslessTransaction } = useSendTransaction();
-const { signMessage } = useSignMessage();
-```
 
-### REX (Confidential Transactions)
-
-```tsx
-const { capabilities, supported, submitREXTransaction } = useREX();
-```
+// Balance
+const { balance, refresh } = useBalance();
 
-### SfS (Stake-for-Service / Gasless)
+// Network
+const { network, chainId } = useNetwork();
+const { switchNetwork, network } = useSwitchNetwork();
 
-```tsx
-const { positions, credits, hasCredits, createPosition, sendGasless, refresh } = useSfS();
+// Transactions
+const { signMessage, connected } = useSignMessage();
+const { sendTransaction, signAndSendTransaction, connected } = useSendTransaction();
 ```
 
-### Scan-to-Connect
+## Vanilla JavaScript
 
-```tsx
-const { scanURI, status, generateQR, approveSession, rejectSession } = useScanConnect();
-```
+```typescript
+import { SheepWallet, isInstalled, formatBalance } from '@cookill/wallet-adapter';
 
-## Custom Modal (Optional)
+// Check if installed
+if (!isInstalled()) {
+  console.log('Please install Sheep Wallet');
+}
 
-If you need full control over the UI, build your own modal using the hooks:
+// Create wallet instance
+const wallet = new SheepWallet();
 
-```tsx
-import { useConnectWallet, useScanConnect, isInstalled } from '@cookill/wallet-adapter/react';
+// Connect (with built-in timeout)
+try {
+  const accounts = await wallet.connect();
+  console.log('Connected:', accounts[0].address);
+} catch (error) {
+  console.error('Connection failed:', error.message);
+}
 
-function MyConnectModal({ open, onClose }) {
-  const { connect, connecting, error } = useConnectWallet();
-  const { scanURI, status, generateQR } = useScanConnect();
+// Get balance
+const balance = await wallet.getBalance();
+console.log('Balance:', formatBalance(balance), 'RLO');
 
-  const handleConnect = async () => {
-    try {
-      const accounts = await connect();
-      console.log('Connected:', accounts[0].address);
-      onClose();
-    } catch (err) {
-      console.error('Connection failed:', err);
-    }
-  };
+// Sign message
+const signed = await wallet.signMessage('Hello!');
 
-  if (!open) return null;
+// Send transaction
+const tx = await wallet.signAndSendTransaction({
+  to: 'RecipientAddress...',
+  value: '1000000000', // 1 RLO in kelvins
+});
+console.log('TX Hash:', tx.hash);
 
-  return (
-    <div className="modal-overlay" onClick={onClose}>
-      <div className="modal-content" onClick={e => e.stopPropagation()}>
-        <h2>Connect Wallet</h2>
-
-        {isInstalled() ? (
-          <button onClick={handleConnect} disabled={connecting}>
-            {connecting ? 'Approve in extension...' : 'Connect Sheep Wallet'}
-          </button>
-        ) : (
-          <a href="https://rialo.io/wallet" target="_blank">Install Sheep Wallet</a>
-        )}
-
-        {error && <p className="error">{error.message}</p>}
-      </div>
-    </div>
-  );
+// Silent session check (for auto-connect, never triggers approval)
+const existingSession = await wallet.checkSession();
+if (existingSession) {
+  console.log('Session restored:', existingSession[0].address);
 }
 ```
 
-Key points:
-- `connect()` calls `window.rialo.connect()` which triggers the extension's approval popup
-- The `connect()` call has a 20-second timeout to prevent dApp freezes
-- Use `isInstalled()` to check if the extension is present before connecting
-
-## Vanilla JavaScript
+## Direct Provider Access
 
 ```typescript
-import { SheepWallet, isInstalled, formatBalance } from '@cookill/wallet-adapter';
+// Access window.rialo directly
+if (window.rialo) {
+  const accounts = await window.rialo.connect();
+  const balance = await window.rialo.getBalance();
+  const tx = await window.rialo.signAndSendTransaction({
+    to: 'RecipientAddress...',
+    value: '1000000000',
+  });
+}
+```
 
-const wallet = new SheepWallet();
+## Components
 
-if (!wallet.isInstalled) {
-  console.log('Extension not found');
-}
+### ConnectButton
 
-const accounts = await wallet.connect();
-const balance = await wallet.getBalance();
-console.log('Balance:', formatBalance(balance));
+```tsx
+<ConnectButton
+  connectLabel="Connect Wallet"
+  disconnectLabel="Disconnect"
+  showAddress={true}
+  showBalance={false}
+  className="my-button"
+  style={{ backgroundColor: '#6EB9A8' }}
+/>
+```
 
-await wallet.signAndSendTransaction({
-  to: 'RecipientAddress',
-  value: '1000000000', // 1 RLO in kelvins
-});
+### WalletProvider
 
-await wallet.disconnect();
+```tsx
+<WalletProvider
+  network="devnet"        // 'mainnet' | 'testnet' | 'devnet' | 'localnet'
+  autoConnect={true}      // Restore session silently on mount
+  wallets={[customWallet]} // Additional wallets to show
+  onConnect={(accounts) => console.log('Connected', accounts)}
+  onDisconnect={() => console.log('Disconnected')}
+  onNetworkChange={(network) => console.log('Network:', network)}
+  onError={(error) => console.error(error)}
+>
+  {children}
+</WalletProvider>
 ```
 
-## WalletProvider Props
+### Error Boundary & Loading States
+
+```tsx
+import { 
+  WalletErrorBoundary,
+  ApprovalPending,
+  LoadingSpinner,
+  ConnectionStatus,
+} from '@cookill/wallet-adapter/react';
+
+// Error Boundary
+<WalletErrorBoundary 
+  fallback={<CustomError />} 
+  onError={(error, info) => logError(error)}
+>
+  <WalletProvider>...</WalletProvider>
+</WalletErrorBoundary>
+
+// Loading states
+<ApprovalPending
+  title="Waiting for Approval"
+  message="Please approve in Sheep Wallet"
+  walletName="Sheep Wallet"
+  onCancel={() => disconnect()}
+/>
+
+<LoadingSpinner size="md" color="#6EB9A8" />
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `network` | `RialoNetwork` | `'devnet'` | Default network |
-| `autoConnect` | `boolean` | `true` | Silently restore previous session on load |
-| `scanConnectRelay` | `string` | `'wss://relay.rialo.io'` | Relay URL for scan-to-connect |
-| `onConnect` | `(accounts) => void` | — | Called after successful connection |
-| `onDisconnect` | `() => void` | — | Called after disconnect |
-| `onError` | `(error) => void` | — | Called on connection errors |
-| `onNetworkChange` | `(network) => void` | — | Called when network changes |
+<ConnectionStatus status="connecting" />
+<ConnectionStatus status="approving" message="Check your wallet" />
+<ConnectionStatus status="error" onRetry={() => connect()} />
+```
 
 ## Networks
 
-| Network  | Chain ID        | RPC URL                        | Symbol |
-|----------|-----------------|--------------------------------|--------|
-| Mainnet  | rialo:mainnet   | https://mainnet.rialo.io:4101  | RLO    |
-| Testnet  | rialo:testnet   | https://testnet.rialo.io:4101  | tRLO   |
-| Devnet   | rialo:devnet    | https://devnet.rialo.io:4101   | dRLO   |
+| Network  | Chain ID        | RPC URL                         | Symbol |
+|----------|-----------------|----------------------------------|--------|
+| Mainnet  | rialo:mainnet   | https://mainnet.rialo.io:4101   | RLO    |
+| Testnet  | rialo:testnet   | https://testnet.rialo.io:4101   | tRLO   |
+| Devnet   | rialo:devnet    | https://devnet.rialo.io:4101    | dRLO   |
 | Localnet | rialo:localnet  | http://localhost:4101           | lRLO   |
 
-## Key Types
+## Utilities
 
 ```typescript
-interface WalletAccount {
-  address: string;
-  publicKey: string;
-}
+import { 
+  formatAddress,      // (address, chars?) => "5YNm...VWr8"
+  formatBalance,      // (kelvins, decimals?) => "1.0000"
+  parseBalance,       // (rlo) => bigint (kelvins)
+  isValidAddress,     // (address) => boolean
+  toChainId,          // (network) => 'rialo:devnet'
+  fromChainId,        // (chainId) => 'devnet'
+  isInstalled,        // () => boolean
+  getProvider,        // () => RialoProvider | undefined
+  waitForProvider,    // (timeout?) => Promise<RialoProvider | undefined>
+  NETWORKS,           // Network configurations
+} from '@cookill/wallet-adapter';
+```
 
-interface TransactionRequest {
-  to: string;
-  value: string;      // amount in kelvins (1 RLO = 1_000_000_000 kelvins)
-  data?: string;
-  memo?: string;
-  gasless?: boolean;   // set by sendGaslessTransaction
-}
+## TypeScript
 
-interface TransactionResult {
-  hash: string;
-  signature?: string;
-  status: 'pending' | 'confirmed' | 'failed';
-}
+```typescript
+import type {
+  WalletAccount,
+  TransactionRequest,
+  TransactionResult,
+  SignedMessage,
+  BalanceResult,
+  NetworkConfig,
+  WalletInfo,
+  RialoProvider,
+  RialoNetwork,
+  RialoChainId,
+} from '@cookill/wallet-adapter';
+```
 
-interface SignedMessage {
-  signature: string;
-  message: string;
-  address: string;
-}
+## Troubleshooting
+
+### Connection hangs / freezes
 
-type RialoNetwork = 'mainnet' | 'testnet' | 'devnet' | 'localnet';
+v3.2.1 has built-in 20-second timeout. If connection still hangs:
+
+1. Make sure extension is installed and unlocked
+2. Check if popup was blocked by browser
+3. Try refreshing the page
+
+### Auto-connect not working
+
+Auto-connect uses `checkSession()` which only restores **existing** sessions silently.
+It won't trigger the approval popup. User must explicitly call `connect()` first time.
+
+### Modal connect flow
+
+`ConnectButton` now always opens the modal when disconnected, then connection is initiated from the modal so extension approval flow stays consistent and never feels like a silent fail.
+
+```tsx
+const { openModal } = useWallet();
+openModal();
 ```
 
-## Utilities
+## Migration from v3.0.x
 
-```typescript
-import {
-  formatAddress,   // (address, chars?) => "5YNm...VWr8"
-  formatBalance,   // (kelvins, decimals?) => "1.0000"
-  parseBalance,    // (rlo) => bigint (kelvins)
-  isValidAddress,  // (address) => boolean
-  isInstalled,     // () => boolean — checks window.rialo
-  NETWORKS,        // Record<RialoNetwork, NetworkConfig>
-} from '@cookill/wallet-adapter';
+```diff
+ import { WalletProvider, ConnectButton } from '@cookill/wallet-adapter/react';
+
+ const { connect, connected } = useWallet();
+ 
+ // v3.2.1 updates:
+ // - ConnectButton opens WalletModal when disconnected
+ // - WalletModal uses refreshed Sheep Wallet Luxury Minimal branding
+ // - connect() path remains timeout-guarded
 ```
 
-## Architecture Notes
+### Important note about QR / scan-to-connect
 
-- All provider calls have a 20-second timeout to prevent dApp freezes
-- `autoConnect` uses `checkSession()` — never triggers a user-facing popup
-- The built-in modal uses a sibling DOM architecture (backdrop and content are separate elements) to prevent click events from interfering with tab switching or button interactions
-- `ConnectButton` bypasses the modal when the extension is installed
+Core `@cookill/wallet-adapter/react` does **not** ship camera QR scanner UI. If your app needs QR scan/connect flow, implement custom modal UI at app layer and pass resulting URI to your own connect handler.
 
 ## License