@volr/react-ui 0.1.0 → 0.1.2

package/README.md

@@ -1,28 +1,25 @@
-# @volr/react-ui 사용 가이드
+# @volr/react-ui
 
-Volr의 UI 컴포넌트 라이브러리입니다. 미니멀하고 모던한 디자인의 로그인 모달을 제공합니다.
+Pre-built UI components for Volr SDK with minimal, modern design.
 
-## 설치
+## Installation
 
 ```bash
 npm install @volr/react-ui @volr/react
-# 또는
+# or
 yarn add @volr/react-ui @volr/react
 ```
 
-## 기본 설정
+## Quick Start
 
-### 1. VolrUIProvider로 앱 래핑
-
-앱의 최상위 레벨에서 `VolrUIProvider`로 앱을 래핑합니다.
+### 1. Wrap your app with VolrUIProvider
 
 ```tsx
 import { VolrUIProvider } from '@volr/react-ui';
-import { VolrConfig } from '@volr/react';
+import type { VolrConfig } from '@volr/react';
 
 const volrConfig: VolrConfig = {
-  apiBaseUrl: 'https://api.volr.dev',
-  defaultChainId: 1,
+  defaultChainId: 8453,
   projectApiKey: 'your-project-api-key',
 };
 
@@ -30,9 +27,9 @@ function App() {
   return (
     <VolrUIProvider
       config={volrConfig}
-      accentColor="#3b82f6" // 버튼, 링크 등 강조 요소에 사용되는 색상
-      enabledLoginMethods={['email', 'social', 'siwe']} // 활성화할 로그인 방식
-      socialProviders={['google', 'twitter', 'apple']} // 활성화할 소셜 제공자
+      accentColor="#3b82f6"
+      enabledLoginMethods={['email', 'social', 'siwe']}
+      socialProviders={['google', 'twitter', 'apple']}
     >
       <YourApp />
     </VolrUIProvider>
@@ -40,9 +37,7 @@ function App() {
 }
 ```
 
-### 2. LoginModal 사용
-
-로그인 모달을 표시하려면 `LoginModal` 컴포넌트를 사용합니다.
+### 2. Use LoginModal
 
 ```tsx
 import { useState } from 'react';
@@ -53,14 +48,13 @@ function LoginButton() {
 
   return (
     <>
-      <button onClick={() => setIsOpen(true)}>로그인</button>
+      <button onClick={() => setIsOpen(true)}>Login</button>
       
       <LoginModal
         isOpen={isOpen}
         onClose={() => setIsOpen(false)}
         onError={(error) => {
-          console.error('로그인 오류:', error);
-          // 에러 처리 로직
+          console.error('Login error:', error);
         }}
       />
     </>
@@ -68,52 +62,78 @@ function LoginButton() {
 }
 ```
 
-## 설정 옵션
+## Configuration
 
 ### VolrUIProvider Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `config` | `VolrConfig` | **필수** | Volr 설정 (apiBaseUrl, defaultChainId, projectApiKey) |
-| `accentColor` | `string` | `'#303030'` | 버튼, 링크 등 강조 요소에 사용되는 색상 |
-| `appName` | `string` | `undefined` | 앱 이름 |
-| `enabledLoginMethods` | `('email' \| 'social' \| 'siwe')[]` | `['email', 'social', 'siwe']` | 활성화할 로그인 방식 |
-| `socialProviders` | `('google' \| 'twitter' \| 'apple')[]` | `['google', 'twitter', 'apple']` | 활성화할 소셜 제공자 |
-| `volrLogoUrl` | `string` | `undefined` | Volr 로고 URL |
-| `providerPolicy` | `object` | `{ enforceOnFirstLogin: true }` | Provider 정책 설정 |
+| `config` | `VolrConfig` | **Required** | Volr configuration (defaultChainId, projectApiKey) |
+| `accentColor` | `string` | `'#303030'` | Accent color for buttons and links |
+| `appName` | `string` | `undefined` | Application name |
+| `enabledLoginMethods` | `('email' \| 'social' \| 'siwe')[]` | `['email', 'social', 'siwe']` | Enabled login methods |
+| `socialProviders` | `('google' \| 'twitter' \| 'apple')[]` | `['google', 'twitter', 'apple']` | Enabled social providers |
+| `volrLogoUrl` | `string` | `undefined` | Custom Volr logo URL |
+| `providerPolicy` | `object` | `{ enforceOnFirstLogin: true }` | Provider policy settings |
 
 ### LoginModal Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `isOpen` | `boolean` | **필수** | 모달 열림/닫힘 상태 |
-| `onClose` | `() => void` | **필수** | 모달 닫기 콜백 |
-| `onError` | `(error: Error) => void` | `undefined` | 에러 발생 시 콜백 |
-
-## 사용 예시
-
-### 기본 사용
-
-```tsx
-import { useState } from 'react';
-import { LoginModal } from '@volr/react-ui';
-
-function App() {
-  const [showLogin, setShowLogin] = useState(false);
-
-  return (
-    <>
-      <button onClick={() => setShowLogin(true)}>로그인</button>
-      <LoginModal
-        isOpen={showLogin}
-        onClose={() => setShowLogin(false)}
-      />
-    </>
-  );
-}
-```
-
-### 이메일 로그인만 활성화
+| `isOpen` | `boolean` | **Required** | Modal open/close state |
+| `onClose` | `() => void` | **Required** | Close callback |
+| `onError` | `(error: Error) => void` | `undefined` | Error callback |
+
+## Features
+
+- **Email Login**: Email verification with 6-digit code
+- **Social Login**: Google, Twitter, Apple OAuth
+- **SIWE**: Sign-In with Ethereum (wallet login)
+- **Passkey Wallet**: Automatic passkey-based wallet creation for new users
+- **Minimal Design**: Clean, modern UI without emojis
+- **Customizable**: Accent color and enabled methods
+- **Type-Safe**: Full TypeScript support
+
+## Login Flow
+
+### Email Login
+1. User clicks "Email Login"
+2. Enter email address
+3. Receive 6-digit verification code
+4. Enter code
+5. **New users**: Passkey setup
+6. **Existing users**: Success
+
+### Social Login (Google, Twitter, Apple)
+1. User clicks social login button
+2. Redirect to OAuth provider
+3. Authorize and return
+4. **New users**: Passkey setup
+5. **Existing users**: Success
+
+### Wallet Login (SIWE)
+1. User clicks "Wallet Login"
+2. Connect MetaMask or other wallet
+3. Sign SIWE message
+4. **New users**: Passkey setup
+5. **Existing users**: Success
+
+## Passkey Setup
+
+For new users, a passkey-based wallet is automatically created:
+
+1. **Create Passkey**: WebAuthn API with platform authenticator
+2. **Derive Wrap Key**: From Passkey PRF
+3. **Generate Master Seed**: 32-byte random seed
+4. **Encrypt**: AES-256-GCM with Wrap Key
+5. **Upload**: Encrypted seed to S3
+6. **Register Provider**: Backend registration
+7. **Derive EVM Key**: BIP-32 derivation
+8. **Complete**: Wallet address confirmed
+
+## Examples
+
+### Email Only
 
 ```tsx
 <VolrUIProvider
@@ -125,7 +145,7 @@ function App() {
 </VolrUIProvider>
 ```
 
-### Google과 Apple만 활성화
+### Google and Apple Only
 
 ```tsx
 <VolrUIProvider
@@ -138,7 +158,7 @@ function App() {
 </VolrUIProvider>
 ```
 
-### 커스텀 에러 처리
+### Custom Error Handling
 
 ```tsx
 function App() {
@@ -159,7 +179,7 @@ function App() {
         </div>
       )}
       
-      <button onClick={() => setShowLogin(true)}>로그인</button>
+      <button onClick={() => setShowLogin(true)}>Login</button>
       
       <LoginModal
         isOpen={showLogin}
@@ -169,7 +189,6 @@ function App() {
         }}
         onError={(err) => {
           setError(err.message);
-          // 3초 후 에러 메시지 자동 숨김
           setTimeout(() => setError(null), 3000);
         }}
       />
@@ -178,57 +197,9 @@ function App() {
 }
 ```
 
-## 로그인 플로우
-
-### 이메일 로그인
-1. 사용자가 "Email Login" 버튼 클릭
-2. 이메일 주소 입력 화면 표시
-3. 인증 코드 전송
-4. 6자리 코드 입력 화면 표시
-5. 코드 검증
-6. **신규 사용자**: Passkey 설정 화면으로 이동
-7. **기존 사용자**: 성공 화면으로 이동
-
-### 소셜 로그인 (Google, Twitter, Apple)
-1. 사용자가 소셜 로그인 버튼 클릭
-2. OAuth 페이지로 리다이렉트
-3. 소셜 계정으로 로그인 및 권한 승인
-4. 백엔드 콜백 처리 후 프론트엔드로 리다이렉트
-5. **신규 사용자**: Passkey 설정 화면으로 이동
-6. **기존 사용자**: 성공 화면으로 이동
-
-### 지갑 로그인 (SIWE)
-1. 사용자가 "Wallet Login" 버튼 클릭
-2. MetaMask 또는 다른 지갑 연결
-3. SIWE 메시지에 서명
-4. 백엔드에서 서명 검증
-5. **신규 사용자**: Passkey 설정 화면으로 이동
-6. **기존 사용자**: 성공 화면으로 이동
-
-## Passkey 설정
-
-신규 사용자의 경우 자동으로 Passkey 지갑이 생성됩니다:
-
-1. **Passkey 생성**: WebAuthn API를 사용하여 플랫폼 인증자(생체 인증) 생성
-2. **Wrap Key 파생**: Passkey PRF에서 Wrap Key 생성
-3. **Master Seed 생성 및 암호화**: 
-   - 32바이트 무작위 Master Seed 생성
-   - Wrap Key로 AES-256-GCM 암호화
-4. **S3 업로드**: 암호화된 Master Seed를 S3에 업로드
-5. **Provider 등록**: 백엔드에 Provider 정보 등록
-6. **EVM 키 파생**: Master Seed에서 BIP-32로 EVM 키 쌍 파생
-7. **완료**: 지갑 주소 확인 및 로그인 완료
-
-## 디자인 원칙
-
-- **미니멀리즘**: 깔끔하고 모던한 디자인, 불필요한 장식 없음
-- **accentColor 사용**: 버튼, 링크 등 강조 요소에 config의 accentColor 활용
-- **이모지 금지**: 모든 UI 요소에서 이모지 사용 안 함, SVG 아이콘만 사용
-- **일관된 여백과 타이포그래피**: 명확한 시각적 계층
-
-## 백엔드 설정
-
-로그인 기능을 사용하려면 백엔드에 다음 환경 변수를 설정해야 합니다:
+## Backend Requirements
+
+### Environment Variables
 
 ```bash
 # Google OAuth
@@ -245,97 +216,51 @@ TWITTER_REDIRECT_URI=http://localhost:3000/auth/twitter/callback
 APPLE_CLIENT_ID=your_apple_client_id
 APPLE_REDIRECT_URI=http://localhost:3000/auth/apple/callback
 
-# Frontend URL (OAuth 콜백 후 리다이렉트)
+# Frontend URL (OAuth callback redirect)
 FRONTEND_URL=http://localhost:5173
 
 # API Base URL
 API_BASE_URL=http://localhost:3000
 ```
 
-## API 엔드포인트
-
-백엔드에서 제공해야 하는 엔드포인트:
-
-### 이메일 로그인
-- `POST /auth/email/send` - 인증 코드 전송
-- `POST /auth/email/verify` - 인증 코드 검증 및 로그인
-
-### 소셜 로그인
-- `GET /auth/google` - Google OAuth 시작
-- `GET /auth/google/callback` - Google OAuth 콜백
-- `GET /auth/twitter` - Twitter OAuth 시작
-- `GET /auth/twitter/callback` - Twitter OAuth 콜백
-- `GET /auth/apple` - Apple OAuth 시작
-- `POST /auth/apple/callback` - Apple OAuth 콜백
+### Required Endpoints
 
-### SIWE 로그인
-- `POST /auth/siwe/nonce` - Nonce 생성
-- `POST /auth/siwe/verify` - SIWE 서명 검증
+**Email Login**
+- `POST /auth/email/send` - Send verification code
+- `POST /auth/email/verify` - Verify code and login
 
-### Passkey 관련
-- `POST /blob/presign` - S3 업로드 URL 생성
-- `POST /wallet/provider/register` - Provider 등록
+**Social Login**
+- `GET /auth/google` - Start Google OAuth
+- `GET /auth/google/callback` - Google OAuth callback
+- `GET /auth/twitter` - Start Twitter OAuth
+- `GET /auth/twitter/callback` - Twitter OAuth callback
+- `GET /auth/apple` - Start Apple OAuth
+- `POST /auth/apple/callback` - Apple OAuth callback
 
-## 완전한 예제
+**SIWE**
+- `POST /auth/siwe/nonce` - Generate nonce
+- `POST /auth/siwe/verify` - Verify SIWE signature
 
-```tsx
-import { useState } from 'react';
-import { VolrUIProvider, LoginModal } from '@volr/react-ui';
-import { VolrConfig } from '@volr/react';
-
-const volrConfig: VolrConfig = {
-  apiBaseUrl: process.env.VITE_API_BASE_URL || 'http://localhost:3000',
-  defaultChainId: 1,
-  projectApiKey: process.env.VITE_PROJECT_API_KEY || '',
-};
-
-function LoginPage() {
-  const [isLoginOpen, setIsLoginOpen] = useState(false);
-
-  return (
-    <>
-      <button onClick={() => setIsLoginOpen(true)}>로그인</button>
-      
-      <LoginModal
-        isOpen={isLoginOpen}
-        onClose={() => setIsLoginOpen(false)}
-        onError={(error) => {
-          console.error('로그인 오류:', error);
-          alert(error.message);
-        }}
-      />
-    </>
-  );
-}
+**Passkey**
+- `POST /blob/presign` - Generate S3 upload URL
+- `POST /wallet/provider/register` - Register provider
 
-function App() {
-  return (
-    <VolrUIProvider
-      config={volrConfig}
-      accentColor="#6366f1"
-      enabledLoginMethods={['email', 'social', 'siwe']}
-      socialProviders={['google', 'twitter', 'apple']}
-    >
-      <LoginPage />
-    </VolrUIProvider>
-  );
-}
+## Troubleshooting
 
-export default App;
-```
+### OAuth Redirect Failure
+- Verify OAuth Client ID and Secret
+- Check Redirect URI matches OAuth app settings
+- Verify CORS configuration
 
-## 문제 해결
+### SIWE Signature Failure
+- Ensure MetaMask or wallet is installed
+- Check wallet is connected to correct network
 
-### OAuth 리다이렉트 실패
-- OAuth Client ID와 Secret 확인
-- Redirect URI가 OAuth 앱 설정과 일치하는지 확인
-- CORS 설정 확인
+### Passkey Creation Failure
+- HTTPS or localhost required (HTTP not supported)
+- Verify browser supports WebAuthn
+- Check biometric authentication is enabled on device
 
-### SIWE 서명 실패
-- MetaMask 또는 다른 지갑이 설치되어 있는지 확인
-- 지갑이 올바른 네트워크에 연결되어 있는지 확인
+## License
 
-### Passkey 생성 실패
-- HTTPS 또는 localhost에서만 작동 (HTTP는 불가)
-- 브라우저가 WebAuthn을 지원하는지 확인
-- 디바이스에 생체 인증이 활성화되어 있는지 확인
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volr/react-ui",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Volr React UI - UI components for Volr built on top of @volr/react",
   "type": "module",
   "main": "./dist/index.cjs",