From fc4067aecd86336794ea0fba72728d83091d9162 Mon Sep 17 00:00:00 2001 From: Quantara CI Date: Thu, 2 Jul 2026 09:17:53 +0100 Subject: [PATCH] docs(wallet): add docs/WALLET_INTEGRATION.md for useWallet and Freighter client Documents the hook shape, connection state machine, and the disconnected / not-installed / wrong-network UX contract. --- docs/ARCHITECTURE.md | 2 +- docs/README.md | 34 ++++++++++------- docs/WALLET_INTEGRATION.md | 77 +++++++++++++++++++++++++++++++++++++- 3 files changed, 96 insertions(+), 17 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index dcc1364..10357dc 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -26,7 +26,7 @@ graph TD ### Context Responsibilities 1. **`SettingsProvider`**: Manages global user preferences (theme mode, network, address display) and application settings (toast toggles and auto-dismiss timing). It must sit high in the tree because it reads from `localStorage` and applies the data-theme immediately. -2. **`WalletProvider`**: Manages Stellar wallet connection state, exposed address, and connect/disconnect functionality. Depends on `SettingsProvider` for network preferences. +2. **`WalletProvider`**: Manages Stellar wallet connection state, exposed address, and connect/disconnect functionality. Depends on `SettingsProvider` for network preferences. See [Wallet Integration](./WALLET_INTEGRATION.md) for more details. 3. **`ToastProvider`**: Exposes `addToast` and `removeToast` functions for global notifications. **Must be placed inside `SettingsProvider`**, because the toast component reads `toastsEnabled` and `autoDismiss` preferences via `useSettings()` to calculate timeout bounds and global mute states. ### The Route Table & Layout Shell diff --git a/docs/README.md b/docs/README.md index 7a18064..70b9b5b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -52,12 +52,12 @@ This directory contains comprehensive design specifications and implementation g - Color, spacing, radius, typography, and motion scales - Guidance for replacing one-off hex values in components -7. **[Motion Guidelines](./motion-guidelines.md)** +8. **[Motion Guidelines](./motion-guidelines.md)** - Motion token strategy and reduced-motion defaults - Best practices for animation and transitions - Implementation examples for UI micro-interactions -8. **[Figma Design Specs](./FIGMA_DESIGN_SPECS.md)** +9. **[Figma Design Specs](./FIGMA_DESIGN_SPECS.md)** - Visual design specifications - Color palette and design tokens - Layout measurements and spacing @@ -65,29 +65,35 @@ This directory contains comprehensive design specifications and implementation g - Responsive breakpoints - Component organization structure -9. **[Implementation Examples](./IMPLEMENTATION_EXAMPLES.md)** - - Practical code examples for each page - - Reusable hooks and patterns - - Testing examples - - Accessibility guidelines - - Performance considerations +10. **[Implementation Examples](./IMPLEMENTATION_EXAMPLES.md)** + - Practical code examples for each page + - Reusable hooks and patterns + - Testing examples + - Accessibility guidelines + - Performance considerations -10. **[Mobile Navigation Pattern](./mobile-navigation-pattern.md)** ⭐ NEW +11. **[Mobile Navigation Pattern](./mobile-navigation-pattern.md)** ⭐ NEW - Hybrid responsive navigation (hamburger mobile + horizontal desktop) - Complete implementation guide with code examples - Accessibility requirements (WCAG 2.1 AA) - Testing guide and troubleshooting - [Decision Matrix](./mobile-navigation-DECISION.md) | [Reconnaissance Report](./mobile-nav-RECON.md) | [Figma Rules](./figma-nav-rules.md) -11. **[Architecture Overview](./ARCHITECTURE.md)** ⭐ NEW +12. **[Architecture Overview](./ARCHITECTURE.md)** ⭐ NEW - Provider tree and routing architecture - Context responsibilities - Theming flow and mock data boundaries -12. **[Keyboard Interactions Contract](./keyboard-interactions.md)** ⭐ NEW - - Developer-facing matrix of every interactive component and its expected keyboard behavior - - Covers `ConfirmDialog`, `TierLadder`, `Banner`, `Toggle`, `AddressInput`, skip-link, and navigation - - Focus-restore contract and checklist for new interactive components +13. [Keyboard Interactions Contract](./keyboard-interactions.md) ⭐ NEW + +- Developer-facing matrix of every interactive component and its expected keyboard behavior +- Covers `ConfirmDialog`, `TierLadder`, `Banner`, `Toggle`, `AddressInput`, skip-link, and navigation +- Focus-restore contract and checklist for new interactive components + +13. [Wallet Integration](./WALLET_INTEGRATION.md) ⭐ NEW + - `useWallet` API documentation + - Connection state machine and UX contract for connection/network states + - Usage guide and network mismatch handling ### Quick Start diff --git a/docs/WALLET_INTEGRATION.md b/docs/WALLET_INTEGRATION.md index 70ba320..c5efac5 100644 --- a/docs/WALLET_INTEGRATION.md +++ b/docs/WALLET_INTEGRATION.md @@ -1,7 +1,80 @@ # Wallet Integration -Credence reads the connected Freighter account through `useWallet()` and compares its reported -network against the app setting stored in `SettingsContext`. +Credence reads the connected Freighter account through the `useWallet()` hook, which acts as the primary interface for Freighter interactions. This layer handles wallet state management, connection logic, and network alignment. + +## `useWallet` Hook API + +The `useWallet()` hook is the centralized source of truth for the wallet connection. + +```typescript +export interface UseWalletState { + /** Connected Stellar public key, or empty when disconnected. */ + address: string + /** True when a wallet address is available. */ + isConnected: boolean + /** True while a connect request is in flight. */ + isConnecting: boolean + /** Last connection error, if any (not_installed, rejected, network_mismatch, unknown). */ + error: WalletError | null + /** Request Freighter access and store the returned public key. */ + connect: () => Promise + /** Clear the local wallet session. */ + disconnect: () => void + /** Freighter network reported by the wallet, or null when unavailable. */ + network: CredenceNetwork | null +} +``` + +## Connection State Machine + +The wallet connection follows a strict state transition flow to ensure consistency. + +```text +[Disconnected] + | + | connect() called + V + [Connecting] ----------------> [Connected] + | | + | failure | disconnect() or external logout + V V + [Error] ----------------> [Disconnected] +(not_installed, rejected, + network_mismatch, unknown) +``` + +## UX Contract + +### 1. Connection Gating + +Action surfaces (e.g., "Create Bond", "Attest") MUST check `isConnected`. If `false`, the UI must surface the `ConnectWalletModal`. + +### 2. Not Installed + +If `error.code === 'not_installed'`, display a call-to-action urging the user to install the Freighter extension. + +### 3. Network Mismatch + +The app compares the wallet-reported network with the application's `network` setting. + +- Use `src/hooks/useNetworkMismatch.ts` to detect disparities. +- Components must block primary actions if a mismatch exists and display a warning banner prompting the user to switch networks. + +## Consuming the Hook + +```tsx +import { useWallet } from '../context/WalletContext' + +function ActionButton() { + const { isConnected, connect, address } = useWallet() + + if (!isConnected) { + return + } + + return
Connected: {address}
+} +``` ## Network mismatch guard