@svp-chain-sdk/ui 0.1.3 → 0.1.4

package/README.md

@@ -2,7 +2,88 @@
 
 ## 1. 适用范围
 
-`@svp-chain-sdk/ui` 当前的主要接入方式是 Tailwind provider：消费方把 `@svp-chain-sdk/ui/tailwind` 注册为 Tailwind 插件，然后直接在 HTML、React、Vue 或其他模板中组合 `.ui-button` 等 CSS class。
+`@svp-chain-sdk/ui` 提供 Tailwind provider，也提供 React 钱包公共能力。钱包支持链、钱包分组、RainbowKit 主题、SVP Wallet 检测与安装地址统一维护在 `src/wallet.tsx` 的 `walletDefaults` 及相关导出中。
+
+React 项目可直接复用 Provider 和连接按钮：
+
+```tsx
+import {
+  ConnectWalletButton,
+  SvpWalletProvider,
+} from '@svp-chain-sdk/ui'
+import '@rainbow-me/rainbowkit/styles.css'
+
+export function App() {
+  return (
+    <SvpWalletProvider appName="SVP Bridge" projectId={walletConnectProjectId}>
+      <ConnectWalletButton
+        labels={{ connect: '连接钱包', wrongNetwork: '网络错误' }}
+      />
+    </SvpWalletProvider>
+  )
+}
+```
+
+消费项目需要安装本包声明的 React、RainbowKit、TanStack Query、Wagmi 和 Viem peer dependencies。业务层只传应用名、WalletConnect Project ID 和本地化文案；默认链、钱包顺序、弹窗主题与 SVP Wallet 行为由 SDK 统一提供。
+
+### 在现有项目中接入（以 swap-v2 为例）
+
+1. 安装公共包及 peer dependencies：
+
+```sh
+pnpm add @svp-chain-sdk/ui @rainbow-me/rainbowkit @tanstack/react-query wagmi viem
+```
+
+本地联调尚未发布的 SDK 时，可以把依赖临时指向仓库中的 UI 包：
+
+```json
+{
+  "dependencies": {
+    "@svp-chain-sdk/ui": "file:../svp-chain-sdk-monorepo/packages/ui"
+  }
+}
+```
+
+2. 在应用入口导入 SDK 与 RainbowKit 样式，并用 `SvpWalletProvider` 包裹应用。`projectId` 应读取项目自己的 `VITE_WALLETCONNECT_PROJECT_ID`，不要提交真实凭据：
+
+```tsx
+import { SvpWalletProvider } from '@svp-chain-sdk/ui'
+import '@svp-chain-sdk/ui/styles.css'
+import '@rainbow-me/rainbowkit/styles.css'
+
+createRoot(document.getElementById('root')!).render(
+  <SvpWalletProvider
+    appName="NovaSwap"
+    projectId={import.meta.env.VITE_WALLETCONNECT_PROJECT_ID}
+    locale="zh-CN"
+  >
+    <App />
+  </SvpWalletProvider>,
+)
+```
+
+如果项目已经自行声明了 `WagmiProvider`、`QueryClientProvider` 和 `RainbowKitProvider`，应删除重复 Provider，避免出现两个 Wagmi/Query Client 上下文。默认网络、钱包排序、SVP Wallet 图标、安装跳转和弹窗主题由 SDK 提供。
+
+3. 在 Header 或其他业务组件中直接使用连接按钮：
+
+```tsx
+import { ConnectWalletButton } from '@svp-chain-sdk/ui'
+
+export function HeaderWallet() {
+  return (
+    <ConnectWalletButton
+      labels={{
+        connect: '连接钱包',
+        wrongNetwork: '网络错误',
+      }}
+    />
+  )
+}
+```
+
+按钮会自动处理未连接、错误网络和已连接三种状态。`showChain={false}` 可以在已连接时隐藏独立网络按钮；`className` 只应用到钱包操作按钮。SVP Wallet 图标已经随 npm 包构建，不需要消费项目把图片复制到 `public`。
+
+4. 升级 SDK 后执行项目自身的测试与生产构建，至少确认连接弹窗、SVP Wallet 图标、未安装跳转、网络切换和账户弹窗正常。
 
 这是**框架无关、非 React 组件优先**的模式。包根入口仍提供可选的 React `Button`、`buttonVariants` 和 `cn`，也导出 `@svp-chain-sdk/ui/styles.css` 样式入口，但它们不是本文的主要接入方式。目前 Tailwind provider 只注册按钮相关 class，不应假定它包含表单、弹窗或其他尚未实现的组件。
 

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export { Button, buttonVariants } from './button';
 export type { ButtonProps } from './button';
 export { cn } from './utils';
+export { ConnectWalletButton, createSvpWalletConfig, resolveSvpProvider, resolveSvpProviderForConnection, SVP_WALLET_DOWNLOAD_URL, svpTestnet, svpWallet, SvpWalletProvider, walletDefaults, walletTheme, } from './wallet';
+export type { ConnectWalletButtonProps, ConnectWalletLabels, CreateSvpWalletConfigOptions, SvpWalletProviderProps, SvpWalletDefaults, } from './wallet';