@umituz/react-native-auth 3.4.31 → 3.4.32

package/src/presentation/components/SocialLoginButtons.md

@@ -1,303 +1,340 @@
 # SocialLoginButtons
 
-Google ve Apple ile social login button'larını gösteren component.
+Component that displays Google and Apple social authentication buttons.
 
-## Özellikler
+---
 
-- ✅ Google ve Apple login button'ları
-- ✅ Loading states
-- ✅ Disabled states
-- ✅ Platform check (Apple sadece iOS)
-- ✅ Localisation desteği
-- ✅ Design system uyumlu
+## Component Overview
 
-## Kullanım
+### Strategy
 
+**Purpose**: Provides pre-built social authentication buttons for Google and Apple with consistent styling, loading states, and platform-specific behavior.
+
+**When to Use**:
+- Adding social login options to authentication screens
+- Need quick integration with OAuth providers
+- Want consistent social login UI across app
+- Supporting multiple social providers
+
+**Import Path**:
 ```typescript
 import { SocialLoginButtons } from '@umituz/react-native-auth';
-
-function LoginScreen() {
-  const { signInWithGoogle, googleLoading } = useGoogleAuth({
-    webClientId: 'your-client-id',
-  });
-
-  const { signInWithApple, appleLoading } = useAppleAuth();
-
-  return (
-    <View>
-      <LoginForm />
-
-      <SocialLoginButtons
-        enabledProviders={['google', 'apple']}
-        onGooglePress={signInWithGoogle}
-        onApplePress={signInWithApple}
-        googleLoading={googleLoading}
-        appleLoading={appleLoading}
-      />
-    </View>
-  );
-}
 ```
 
-## Props
+**Component Location**: `src/presentation/components/SocialLoginButtons.tsx`
 
-| Prop | Tip | Required | Default | Açıklama |
-|------|-----|----------|---------|----------|
-| `enabledProviders` | `SocialAuthProvider[]` | Yes | - | Aktif provider'lar |
-| `onGooglePress` | `() => void` | No | - | Google butonu handler |
-| `onApplePress` | `() => void` | No | - | Apple butonu handler |
-| `googleLoading` | `boolean` | No | `false` | Google loading durumu |
-| `appleLoading` | `boolean` | No | `false` | Apple loading durumu |
-| `disabled` | `boolean` | No | `false` | Tüm butonları disable et |
+---
 
-### SocialAuthProvider
+## Provider Configuration
 
-```typescript
-type SocialAuthProvider = 'google' | 'apple';
-```
+### Strategy
 
-## Örnekler
+**Purpose**: Configure which social providers to display based on platform and availability.
 
-### Sadece Google
+**Supported Providers**:
+- `google` - Google OAuth (all platforms)
+- `apple` - Apple Sign In (iOS only)
 
-```typescript
-function LoginScreen() {
-  const { signInWithGoogle, googleLoading } = useGoogleAuth({
-    webClientId: Config.GOOGLE_WEB_CLIENT_ID,
-  });
-
-  return (
-    <View>
-      <LoginForm />
-
-      <SocialLoginButtons
-        enabledProviders={['google']}
-        onGooglePress={signInWithGoogle}
-        googleLoading={googleLoading}
-      />
-    </View>
-  );
-}
-```
+### Rules
 
-### Google ve Apple (iOS)
+**MUST**:
+- Pass `enabledProviders` array with provider names
+- Check provider availability before enabling
+- Provide press handlers for enabled providers
+- Respect platform restrictions (Apple = iOS only)
 
-```typescript
-function LoginScreen() {
-  const { signInWithGoogle, googleLoading } = useGoogleAuth({
-    iosClientId: Config.GOOGLE_IOS_CLIENT_ID,
-  });
-
-  const { signInWithApple, appleLoading } = useAppleAuth();
-
-  return (
-    <View>
-      <LoginForm />
-
-      <SocialLoginButtons
-        enabledProviders={['google', 'apple']}
-        onGooglePress={signInWithGoogle}
-        onApplePress={signInWithApple}
-        googleLoading={googleLoading}
-        appleLoading={appleLoading}
-      />
-    </View>
-  );
-}
-```
+**MUST NOT**:
+- Enable Apple on Android or Web
+- Show provider buttons without press handlers
+- Assume provider is available without checking
 
-### Platform-Specific Providers
+### Constraints
 
-```typescript
-function LoginScreen() {
-  const { signInWithGoogle, googleLoading } = useGoogleAuth({
-    webClientId: Config.GOOGLE_WEB_CLIENT_ID,
-  });
-
-  const { signInWithApple, appleLoading, appleAvailable } = useAppleAuth();
-
-  // Sadece mevcut provider'ları göster
-  const enabledProviders = ['google'];
-  if (appleAvailable) {
-    enabledProviders.push('apple');
-  }
-
-  return (
-    <View>
-      <SocialLoginButtons
-        enabledProviders={enabledProviders}
-        onGooglePress={signInWithGoogle}
-        onApplePress={signInWithApple}
-        googleLoading={googleLoading}
-        appleLoading={appleLoading}
-      />
-    </View>
-  );
-}
-```
+**PLATFORM AVAILABILITY**:
+| Provider | iOS | Android | Web |
+|----------|-----|---------|-----|
+| Google   | ✅  | ✅      | ✅  |
+| Apple    | ✅  | ❌      | ❌  |
 
-### Custom Handlers
+**PROVIDER DETECTION**:
+- Use `useGoogleAuth` hook to check Google availability
+- Use `useAppleAuth` hook to check Apple availability
+- Filter enabled providers array based on availability
 
-```typescript
-function LoginScreen() {
-  const navigation = useNavigation();
-
-  const handleGoogleSignIn = async () => {
-    try {
-      const result = await customGoogleSignIn();
-
-      if (result.success) {
-        navigation.navigate('Home');
-      } else {
-        Alert.alert('Hata', result.error);
-      }
-    } catch (error) {
-      Alert.alert('Hata', 'Bir sorun oluştu');
-    }
-  };
-
-  const handleAppleSignIn = async () => {
-    try {
-      const result = await customAppleSignIn();
-
-      if (result.success) {
-        navigation.navigate('Home');
-      } else {
-        Alert.alert('Hata', result.error);
-      }
-    } catch (error) {
-      Alert.alert('Hata', 'Bir sorun oluştu');
-    }
-  };
-
-  return (
-    <View>
-      <SocialLoginButtons
-        enabledProviders={['google', 'apple']}
-        onGooglePress={handleGoogleSignIn}
-        onApplePress={handleAppleSignIn}
-      />
-    </View>
-  );
-}
-```
+**CONFIGURATION REQUIREMENTS**:
+- Google: Requires client ID configuration
+- Apple: Requires Apple Developer account
+- Both: Requires Firebase project setup
 
-### Disabled State
+---
 
-```typescript
-function LoginScreen() {
-  const [isSubmitting, setIsSubmitting] = useState(false);
-  const { signInWithGoogle, googleLoading } = useGoogleAuth();
-
-  return (
-    <View>
-      <Button onPress={handleSubmit} loading={isSubmitting}>
-        Giriş Yap
-      </Button>
-
-      <SocialLoginButtons
-        enabledProviders={['google']}
-        onGooglePress={signInWithGoogle}
-        googleLoading={googleLoading}
-        disabled={isSubmitting} // Form submit sırasında disable et
-      />
-    </View>
-  );
-}
-```
+## Button State Management
 
-### Error Handling
+### Strategy
 
-```typescript
-function LoginScreen() {
-  const { signInWithGoogle, googleLoading } = useGoogleAuth();
-  const [error, setError] = useState<string | null>(null);
-
-  const handleGoogleSignIn = async () => {
-    setError(null);
-    try {
-      const result = await signInWithGoogle();
-
-      if (!result.success) {
-        setError(result.error || 'Google ile giriş başarısız');
-      }
-    } catch (err) {
-      setError(err instanceof Error ? err.message : 'Bir hata oluştu');
-    }
-  };
-
-  return (
-    <View>
-      {error && <Text style={styles.error}>{error}</Text>}
-
-      <SocialLoginButtons
-        enabledProviders={['google']}
-        onGooglePress={handleGoogleSignIn}
-        googleLoading={googleLoading}
-      />
-    </View>
-  );
-}
-```
+**Purpose**: Provide visual feedback for loading, disabled, and error states.
 
-## Görünüm
+### Rules
 
-### Divider
-```
-───────────────────  veya şununla devam et  ───────────────────
-```
+**MUST**:
+- Show loading indicator during OAuth flow
+- Disable buttons during authentication
+- Re-enable buttons after completion (success or error)
+- Handle user cancellation gracefully
 
-### Buttons
-```
-┌─────────────────┐  ┌─────────────────┐
-│   G  Google     │  │   A  Apple      │
-└─────────────────┘  └─────────────────┘
-```
+**MUST NOT**:
+- Leave buttons in loading state indefinitely
+- Allow multiple simultaneous OAuth requests
+- Show loading without active OAuth flow
+
+### Constraints
+
+**LOADING STATES**:
+- `googleLoading` - Show Google button in loading state
+- `appleLoading` - Show Apple button in loading state
+- Loading overrides disabled state visually
+
+**DISABLED STATES**:
+- Global disabled: All buttons disabled
+- Per-button loading: Only that button disabled
+- Parent form disabled: All social buttons disabled
+
+**ERROR RECOVERY**:
+- Auto-recover after cancellation
+- Manual retry required after errors
+- No retry limit (user can try indefinitely)
+
+---
+
+## Platform-Specific Behavior
+
+### Strategy
+
+**Purpose**: Optimize social login experience for each platform's conventions.
+
+### Rules
+
+**MUST**:
+- Hide Apple button on non-iOS platforms
+- Use platform-appropriate button styles
+- Follow platform OAuth flow conventions
+- Respect platform-specific limitations
+
+**MUST NOT**:
+- Show Apple button on Android
+- Force web OAuth flow on native platforms
+- Bypass platform security features
+
+### Constraints
+
+**iOS BEHAVIOR**:
+- Apple Sign-In uses native credential UI
+- Google uses app-based OAuth when available
+- Falls back to web OAuth if needed
+- Requires Info.plist configuration
+
+**ANDROID BEHAVIOR**:
+- Google uses app-based OAuth
+- Apple button hidden
+- Requires Firebase configuration
+- Requires Google Services JSON
+
+**WEB BEHAVIOR**:
+- Both providers use popup/redirect OAuth
+- Requires proper callback handling
+- Requires auth session setup
+- Browser popup blockers may interfere
+
+---
+
+## Error Handling
+
+### Strategy
+
+**Purpose**: Gracefully handle OAuth errors without breaking user experience.
 
-### Loading
+### Rules
+
+**MUST**:
+- Distinguish between user cancellation and errors
+- Show user-friendly error messages
+- Allow retry after errors
+- Log errors for debugging (not to user)
+
+**MUST NOT**:
+- Show raw OAuth errors to users
+- Block retry after errors
+- Crash or hang on OAuth failure
+- Expose sensitive tokens in errors
+
+### Constraints
+
+**ERROR TYPES**:
+- User cancellation: Silent or gentle notification
+- Network error: Retry prompt
+- Configuration error: Developer-focused message
+- Provider error: Generic "try again" message
+
+**ERROR DISPLAY**:
+- Alert/Modal for critical errors
+- Inline text for non-critical errors
+- Toast for success/cancellation
+- Console logging for debugging
+
+---
+
+## Security Requirements
+
+### Strategy
+
+**Purpose**: Ensure OAuth authentication follows security best practices.
+
+### Rules
+
+**MUST**:
+- Use HTTPS for all OAuth endpoints
+- Store tokens securely (Keychain/Keystore)
+- Never log tokens or credentials
+- Validate tokens server-side
+- Implement token refresh logic
+
+**MUST NOT**:
+- Store tokens in AsyncStorage/localStorage
+- Log OAuth responses with tokens
+- Skip server-side token validation
+- Use HTTP for OAuth flows
+- Expose client secrets in app code
+
+### Constraints
+
+**TOKEN HANDLING**:
+- Tokens managed by Firebase SDK
+- App never directly accesses refresh tokens
+- ID tokens accessible for API calls
+- Secure storage handled automatically
+
+**CLIENT SECRETS**:
+- Never include client secrets in app
+- Use public client flows
+- Server-side validation required
+- Firebase manages OAuth credentials
+
+---
+
+## Localization
+
+### Strategy
+
+**Purpose**: Support international users with localized button text and messages.
+
+### Rules
+
+**MUST**:
+- Use localization keys for all text
+- Provide translations for supported languages
+- Respect user's language preference
+- Format error messages appropriately
+
+**MUST NOT**:
+- Hardcode English text
+- Assume user speaks English
+- Mix languages in UI
+
+### Constraints
+
+**LOCALIZATION KEYS**:
 ```
-┌─────────────────┐
-│  ⏳  Yükleniyor... │
-└─────────────────┘
+auth.orContinueWith
+auth.google
+auth.apple
+auth.signingIn
 ```
 
-## Platform Davranışı
+**SUPPORTED LANGUAGES**:
+- English (default)
+- Turkish
+- Add more via i18n configuration
 
-| Platform | Google | Apple |
-|----------|--------|-------|
-| iOS | ✅ | ✅ |
-| Android | ✅ | ❌ |
-| Web | ✅ | ❌ |
+---
 
-Apple butonu otomatik olarak sadece iOS'ta gösterilir.
+## Design System Integration
 
-## Localisation
+### Strategy
 
-Component localisation kullanır:
+**Purpose**: Consistent styling with application design system.
 
-```typescript
-// Türkçe
-"auth.orContinueWith": "veya şununla devam et"
-"auth.google": "Google"
-"auth.apple": "Apple"
-```
+### Rules
+
+**MUST**:
+- Use design system color tokens
+- Follow design system spacing
+- Match design system button styles
+- Use design system icons/logos
+
+**MUST NOT**:
+- Hardcode colors or sizes
+- Use unofficial provider logos
+- Override design system styles
+
+### Constraints
+
+**STYLE TOKENS**:
+- Button colors: Design system primary
+- Text colors: Design system text tokens
+- Spacing: Design system spacing scale
+- Border radius: Design system radius tokens
+
+**PROVIDER BRANDING**:
+- Use official Google/Apple logos
+- Follow provider brand guidelines
+- Maintain minimum logo sizes
+- Don't modify logo colors
+
+---
+
+## Analytics Integration
+
+### Strategy
+
+**Purpose**: Track social login usage for analytics and optimization.
+
+### Rules
+
+**MUST**:
+- Track login attempts per provider
+- Track successful logins
+- Track failures (without sensitive data)
+- Track cancellation rates
+
+**MUST NOT**:
+- Log personally identifiable information
+- Log OAuth tokens or credentials
+- Track before user consents
+- Expose raw analytics data to users
+
+### Constraints
 
-## Design System
+**EVENTS TO TRACK**:
+- `social_login_attempt` (provider, platform)
+- `social_login_success` (provider, platform)
+- `social_login_failed` (provider, error_category)
+- `social_login_cancelled` (provider, platform)
 
-Component design system tokens kullanır:
+**PRIVACY**:
+- No user data in events
+- No session identifiers in events
+- Aggregate data only
+- GDPR/CCPA compliant
 
-- `tokens.colors.border` - Border rengi
-- `tokens.colors.textPrimary` - Metin rengi
-- `tokens.spacing` - Spacing değerleri
+---
 
-## İlgili Component'ler
+## Related Components
 
-- [`LoginForm`](./LoginForm.md) - Login formu
-- [`RegisterForm`](./LoginForm.md#registerform) - Kayıt formu
-- [`AuthDivider`](./AuthDivider.md) - Divider component'i
+- **`LoginForm`** (`src/presentation/components/LoginForm.tsx`) - Email/password form
+- **`RegisterForm`** (`src/presentation/components/RegisterForm.tsx`) - Registration form
 
-## İlgili Hook'lar
+## Related Hooks
 
-- [`useGoogleAuth`](../hooks/useSocialLogin.md#usegoogleauth) - Google auth hook'u
-- [`useAppleAuth`](../hooks/useSocialLogin.md#useappleauth) - Apple auth hook'u
-- [`useSocialLogin`](../hooks/useSocialLogin.md#usesociallogin) - Genel social login hook'u
+- **`useGoogleAuth`** (`src/presentation/hooks/useSocialLogin.ts`) - Google authentication
+- **`useAppleAuth`** (`src/presentation/hooks/useSocialLogin.ts`) - Apple authentication
+- **`useSocialLogin`** (`src/presentation/hooks/useSocialLogin.ts`) - Combined social auth