Initial Commit

openspec/changes/enterprise-react-crypto/proposal.md

@@ -0,0 +1,86 @@
+# OpenSpec Change: enterprise-react-crypto
+
+- **Change ID**: enterprise-react-crypto
+- **Package**: `@suaveplan/react-crypto`
+- **Category**: react
+- **Target path**: `react/auth/react-crypto`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-crypto.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/react-crypto` on genesis from scratch at enterprise quality. Wallet UI for EVM chains: `WalletConnect`, `AddressDisplay`, `BalanceDisplay`, `TransactionList`, and `useWallet` hook — fully implemented (no stub `0x000...` address, no README-vs-reality gaps). Integrates with `@suaveplan/crypto` for signing and `@suaveplan/crypto-browser` for WebCrypto operations. `useWallet` fully implements MetaMask/WalletConnect via injected provider interface, `autoConnect`, `switchNetwork`, `sendTransaction`, `signMessage`.
+
+---
+
+## Current-state audit (genesis)
+
+Package does not exist on genesis — fresh build.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/error` (`workspace:^`) | `WalletError` |
+| `@suaveplan/crypto` (`workspace:^`) | Signing utilities |
+| `@suaveplan/crypto-browser` (`workspace:^`) | WebCrypto adapters |
+| `@suaveplan/react-translate` (`workspace:^`) | i18n |
+| `zod` (`catalog:forms`) | Network/transaction schemas |
+| `@opentelemetry/api` (`catalog:observability`) | `wallet.connect` / `wallet.sign` spans |
+
+External: `tslib catalog:build`. React 18 peer.
+
+---
+
+## Public API surface
+
+```ts
+WalletConnect, AddressDisplay, BalanceDisplay, TransactionList
+useWallet
+
+explorerUrl, formatAddress, formatBalance, isValidEvmAddress, networkDisplayName
+
+// Types
+Network, TokenBalance, Transaction, TransactionDirection, TransactionStatus,
+WalletInfo, WalletStatus
+```
+
+---
+
+## New additions for genesis
+
+1. **Full `useWallet` implementation** — injected `WalletProvider` interface (MetaMask/WalletConnect adapters); `connect()`, `disconnect()`, `autoConnect`, `switchNetwork(chainId)`, `sendTransaction(tx)`, `signMessage(msg)`. No stubs.
+2. **`WalletError`** — codes: `WALLET_CONNECT_FAILED`, `WALLET_NOT_CONNECTED`, `WALLET_SIGN_FAILED`, `WALLET_NETWORK_ERROR`.
+3. **OTel spans** — `wallet.connect`, `wallet.sign`, `wallet.send_transaction`.
+4. **Stories** — connected, disconnected, loading, wrong-network, playground.
+5. **Playwright E2E** — injected mock provider; connect → address shown; signMessage → tx hash shown.
+
+---
+
+## File layout
+
+```text
+react/auth/react-crypto/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts
+    hooks/
+      use-wallet/ (ts + types + md + test + stories + index)
+    components/
+      wallet-connect/ address-display/ balance-display/ transaction-list/
+    providers/
+      wallet-provider/ (ts + types + md + test + index)
+    utils/
+      evm-utils/ (ts + md + test + index)
+    types/
+      crypto.types.ts
+  e2e/
+    wallet.spec.ts
+```