@volr/react-ui 0.1.0

package/README.md

@@ -0,0 +1,341 @@
+# @volr/react-ui 사용 가이드
+
+Volr의 UI 컴포넌트 라이브러리입니다. 미니멀하고 모던한 디자인의 로그인 모달을 제공합니다.
+
+## 설치
+
+```bash
+npm install @volr/react-ui @volr/react
+# 또는
+yarn add @volr/react-ui @volr/react
+```
+
+## 기본 설정
+
+### 1. VolrUIProvider로 앱 래핑
+
+앱의 최상위 레벨에서 `VolrUIProvider`로 앱을 래핑합니다.
+
+```tsx
+import { VolrUIProvider } from '@volr/react-ui';
+import { VolrConfig } from '@volr/react';
+
+const volrConfig: VolrConfig = {
+  apiBaseUrl: 'https://api.volr.dev',
+  defaultChainId: 1,
+  projectApiKey: 'your-project-api-key',
+};
+
+function App() {
+  return (
+    <VolrUIProvider
+      config={volrConfig}
+      accentColor="#3b82f6" // 버튼, 링크 등 강조 요소에 사용되는 색상
+      enabledLoginMethods={['email', 'social', 'siwe']} // 활성화할 로그인 방식
+      socialProviders={['google', 'twitter', 'apple']} // 활성화할 소셜 제공자
+    >
+      <YourApp />
+    </VolrUIProvider>
+  );
+}
+```
+
+### 2. LoginModal 사용
+
+로그인 모달을 표시하려면 `LoginModal` 컴포넌트를 사용합니다.
+
+```tsx
+import { useState } from 'react';
+import { LoginModal } from '@volr/react-ui';
+
+function LoginButton() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <button onClick={() => setIsOpen(true)}>로그인</button>
+      
+      <LoginModal
+        isOpen={isOpen}
+        onClose={() => setIsOpen(false)}
+        onError={(error) => {
+          console.error('로그인 오류:', error);
+          // 에러 처리 로직
+        }}
+      />
+    </>
+  );
+}
+```
+
+## 설정 옵션
+
+### 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 정책 설정 |
+
+### 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)}
+      />
+    </>
+  );
+}
+```
+
+### 이메일 로그인만 활성화
+
+```tsx
+<VolrUIProvider
+  config={volrConfig}
+  accentColor="#6366f1"
+  enabledLoginMethods={['email']}
+>
+  <App />
+</VolrUIProvider>
+```
+
+### Google과 Apple만 활성화
+
+```tsx
+<VolrUIProvider
+  config={volrConfig}
+  accentColor="#8b5cf6"
+  enabledLoginMethods={['social']}
+  socialProviders={['google', 'apple']}
+>
+  <App />
+</VolrUIProvider>
+```
+
+### 커스텀 에러 처리
+
+```tsx
+function App() {
+  const [showLogin, setShowLogin] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  return (
+    <>
+      {error && (
+        <div style={{ 
+          padding: '12px', 
+          backgroundColor: '#fef2f2', 
+          color: '#991b1b',
+          borderRadius: '8px',
+          marginBottom: '16px'
+        }}>
+          {error}
+        </div>
+      )}
+      
+      <button onClick={() => setShowLogin(true)}>로그인</button>
+      
+      <LoginModal
+        isOpen={showLogin}
+        onClose={() => {
+          setShowLogin(false);
+          setError(null);
+        }}
+        onError={(err) => {
+          setError(err.message);
+          // 3초 후 에러 메시지 자동 숨김
+          setTimeout(() => setError(null), 3000);
+        }}
+      />
+    </>
+  );
+}
+```
+
+## 로그인 플로우
+
+### 이메일 로그인
+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 아이콘만 사용
+- **일관된 여백과 타이포그래피**: 명확한 시각적 계층
+
+## 백엔드 설정
+
+로그인 기능을 사용하려면 백엔드에 다음 환경 변수를 설정해야 합니다:
+
+```bash
+# Google OAuth
+GOOGLE_CLIENT_ID=your_google_client_id
+GOOGLE_CLIENT_SECRET=your_google_client_secret
+GOOGLE_REDIRECT_URI=http://localhost:3000/auth/google/callback
+
+# Twitter OAuth
+TWITTER_CLIENT_ID=your_twitter_client_id
+TWITTER_CLIENT_SECRET=your_twitter_client_secret
+TWITTER_REDIRECT_URI=http://localhost:3000/auth/twitter/callback
+
+# Apple OAuth
+APPLE_CLIENT_ID=your_apple_client_id
+APPLE_REDIRECT_URI=http://localhost:3000/auth/apple/callback
+
+# Frontend URL (OAuth 콜백 후 리다이렉트)
+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 콜백
+
+### SIWE 로그인
+- `POST /auth/siwe/nonce` - Nonce 생성
+- `POST /auth/siwe/verify` - SIWE 서명 검증
+
+### Passkey 관련
+- `POST /blob/presign` - S3 업로드 URL 생성
+- `POST /wallet/provider/register` - Provider 등록
+
+## 완전한 예제
+
+```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);
+        }}
+      />
+    </>
+  );
+}
+
+function App() {
+  return (
+    <VolrUIProvider
+      config={volrConfig}
+      accentColor="#6366f1"
+      enabledLoginMethods={['email', 'social', 'siwe']}
+      socialProviders={['google', 'twitter', 'apple']}
+    >
+      <LoginPage />
+    </VolrUIProvider>
+  );
+}
+
+export default App;
+```
+
+## 문제 해결
+
+### OAuth 리다이렉트 실패
+- OAuth Client ID와 Secret 확인
+- Redirect URI가 OAuth 앱 설정과 일치하는지 확인
+- CORS 설정 확인
+
+### SIWE 서명 실패
+- MetaMask 또는 다른 지갑이 설치되어 있는지 확인
+- 지갑이 올바른 네트워크에 연결되어 있는지 확인
+
+### Passkey 생성 실패
+- HTTPS 또는 localhost에서만 작동 (HTTP는 불가)
+- 브라우저가 WebAuthn을 지원하는지 확인
+- 디바이스에 생체 인증이 활성화되어 있는지 확인